Felipe M.
8a4b11281d
Expose /metrics with counters for routed requests, routing errors, upstream outcomes, and upstream latency histograms. Instrument the router and proxy forwarding path and document the new metrics.
137 lines
4 KiB
Markdown
137 lines
4 KiB
Markdown
# Mattermost Push Proxy Router
|
|
|
|
A small, stateless Go service that routes Mattermost push notifications by mobile client platform prefix. It lets a single `PushNotificationServer` URL serve both a custom mobile app (e.g. Bubbles) and the official Mattermost mobile apps on the same server.
|
|
|
|
## Why
|
|
|
|
Mattermost allows only **one** push notification server URL per instance. The stock push proxy routes by platform prefix (`apple_rn`, `android_rn`, …) and drops anything it cannot handle. A custom client registers under its own prefix (e.g. `apple_bubbles:<token>`) and needs its own APNs key/topic — but official app users on the same server still need HPNS.
|
|
|
|
This router sits in front of unmodified backends:
|
|
|
|
```
|
|
Mattermost server
|
|
└─ PushNotificationServer
|
|
└─ [router :8066]
|
|
├─ apple_bubbles:* → your mattermost-push-proxy (custom APNs key)
|
|
└─ apple_rn:* / android_rn:* → HPNS relay
|
|
```
|
|
|
|
## Features
|
|
|
|
- Implements the Mattermost push proxy API (`/api/v1/send_push`, `/api/v1/ack`)
|
|
- Routes by `platform` prefix extracted from the JSON payload
|
|
- Relays official app traffic to HPNS unchanged
|
|
- Forwards custom app traffic to a stock `mattermost-push-proxy` instance
|
|
- Single static binary with TOML-based configuration
|
|
- Docker and GoReleaser ready
|
|
- Prometheus metrics at `/metrics`
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.26+
|
|
- A running [mattermost-push-proxy](https://github.com/mattermost/mattermost-push-proxy) for your custom app (with your APNs `.p8` key)
|
|
|
|
### Run locally
|
|
|
|
```bash
|
|
cp config/router.toml.example config/router.toml
|
|
# Edit config/router.toml with your route prefixes and backend URLs
|
|
|
|
make build
|
|
CONFIG_FILE=config/router.toml ./mattermost-push-proxy-router
|
|
```
|
|
|
|
Point your Mattermost server's `EmailSettings.PushNotificationServer` at `http://<router-host>:8066`.
|
|
|
|
### Docker Compose
|
|
|
|
The included `docker-compose.yml` runs the router plus a placeholder push-proxy backend:
|
|
|
|
```bash
|
|
cp config/router.toml.example config/router.toml
|
|
cp config/mattermost-push-proxy.json.example config/mattermost-push-proxy.json
|
|
# Edit both config files for your deployment
|
|
|
|
docker compose up -d
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Routes are defined in a TOML config file — there are no built-in prefix defaults.
|
|
|
|
Set `CONFIG_FILE` to a TOML file:
|
|
|
|
```toml
|
|
listen = ":8066"
|
|
request_timeout_sec = 60
|
|
|
|
[[routes]]
|
|
prefixes = ["apple_bubbles"]
|
|
url = "http://bubbles-proxy:8067"
|
|
|
|
[[routes]]
|
|
prefixes = ["apple_rn", "android_rn"]
|
|
url = "https://push.mattermost.com"
|
|
```
|
|
|
|
See `config/router.toml.example`.
|
|
|
|
| Variable | Description |
|
|
| --- | --- |
|
|
| `CONFIG_FILE` | Path to router TOML config (required) |
|
|
| `PORT` | Overrides `listen` from the config file |
|
|
| `REQUEST_TIMEOUT_SEC` | Overrides upstream timeout |
|
|
|
|
## API
|
|
|
|
Compatible with the [Mattermost push notification service](https://developers.mattermost.com/contribute/more-info/mobile/push-notifications/service/) protocol:
|
|
|
|
| Endpoint | Method | Description |
|
|
| --- | --- | --- |
|
|
| `/api/v1/send_push` | POST | Route a push notification to the correct backend |
|
|
| `/api/v1/ack` | POST | Route a delivery acknowledgement |
|
|
| `/version` | GET | Service version |
|
|
| `/health` | GET | Health check |
|
|
| `/metrics` | GET | Prometheus metrics |
|
|
|
|
### Example
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8066/api/v1/send_push \
|
|
-X POST \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"type": "message",
|
|
"platform": "apple_bubbles",
|
|
"server_id": "YOUR_DIAGNOSTIC_ID",
|
|
"device_id": "YOUR_APNS_TOKEN",
|
|
"channel_id": "CHANNEL_ID",
|
|
"post_id": "POST_ID",
|
|
"is_id_loaded": true
|
|
}'
|
|
```
|
|
|
|
## Building
|
|
|
|
```bash
|
|
make help # Show all targets
|
|
make build # Production binary
|
|
make test # Unit tests
|
|
make format # Format Go source
|
|
make lint # Run linter
|
|
make build-snapshot # Cross-platform builds via goreleaser
|
|
```
|
|
|
|
## Mattermost Server Setup
|
|
|
|
```bash
|
|
MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS=true
|
|
MM_EMAILSETTINGS_PUSHNOTIFICATIONCONTENTS=id_loaded
|
|
MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://router-host:8066
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|