Skip to content

Doc update with codex #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amm0nite merged 2 commits into from
Nov 18, 2025
Merged

Doc update with codex #20

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1879d6a
Update doc with new clients endpoint and new metrics
amm0nite Nov 18, 2025
956bf25
Fixes following Readme review
amm0nite Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,22 @@ MQTT2HTTP_API_PASSWORD=somesecret

### HTTP to MQTT

* Publish messages to MQTT topics using the built-in REST API. Requests must include HTTP Basic Auth with the password set in `MQTT2HTTP_API_PASSWORD` (the username is ignored). The default password is random at start-up, so set it explicitly if you want to call the API.
* Publish messages or inspect connected clients using the built-in REST API. Requests must include HTTP Basic Auth with the password set in `MQTT2HTTP_API_PASSWORD` (the username is ignored). The default password is random at start-up, so set it explicitly if you want to call the API.

`/publish` lets you inject payloads into MQTT topics:

```bash
curl --user user:somesecret -X POST -d '{"test": true}' http://mqtt2http:8080/publish?topic=hello
```

`/clients` dumps the active MQTT sessions, including their username, subscriptions, publication counters, and timestamps:

```bash
curl --user user:somesecret http://mqtt2http:8080/clients
```

The endpoint responds with a JSON array of objects matching the structure of `lib.Client` (fields: `id`, `username`, `subscriptions`, `publications`, `connected_at`, `last_activity_at`).

## Docker

Run with Docker Compose:
Expand Down Expand Up @@ -73,9 +83,9 @@ image: docker.io/amm0nite/mqtt2http:1.0.0
| Variable | Default | Description |
| --------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| `MQTT2HTTP_MQTT_LISTEN_ADDRESS` | `:1883` | Address where the MQTT broker listens (host\:port). |
| `MQTT2HTTP_HTTP_LISTEN_ADDRESS` | `:8080` | Address for the HTTP REST API (`/publish` endpoint). |
| `MQTT2HTTP_AUTHORIZE_URL` | `http://example.com` | HTTP Basic Auth endpoint for authorizing `CONNECT` requests. A 200/201 response allows access. |
| `MQTT2HTTP_PUBLISH_URL` | `http://example.com/{topic}` | Template URL for forwarding `PUBLISH` messages; `{topic}` is replaced dynamically. When no routes file is loaded, this URL is used for a catch-all default route. |
| `MQTT2HTTP_HTTP_LISTEN_ADDRESS` | `:8080` | Address for the HTTP REST API (hosts `/publish`, `/clients`, and `/`). |
| `MQTT2HTTP_AUTHORIZE_URL` | `http://127.0.0.1/authorize` | HTTP Basic Auth endpoint for authorizing `CONNECT` requests. A 200/201 response allows access. |
| `MQTT2HTTP_PUBLISH_URL` | `http://127.0.0.1/publish/{topic}` | Template URL for forwarding `PUBLISH` messages; `{topic}` is replaced dynamically. When no routes file is loaded, this URL is used for a catch-all default route. |
| `MQTT2HTTP_CONTENT_TYPE` | `application/octet-stream` | `Content-Type` header used in forwarded HTTP `POST` requests. E.g., `application/json`. |
| `MQTT2HTTP_TOPIC_HEADER` | `X-Topic` | Name of the HTTP header that carries the MQTT topic. |
| `MQTT2HTTP_METRICS_HTTP_LISTEN_ADDRESS` | `:9090` | Address for serving Prometheus metrics at the `/metrics` endpoint. |
Expand Down Expand Up @@ -112,7 +122,11 @@ Routes are evaluated in order and the first match wins. If no route matches, the

Prometheus metrics are available at `/metrics` on the configured metrics address (`MQTT2HTTP_METRICS_HTTP_LISTEN_ADDRESS`).

| Metric | Type | Labels | Description |
| ------------------------------ | ------- | --------------- | --------------------------------------------------------------------------------------------------- |
| `mqtt2http_publish_count` | Counter | `topic`, `code` | Counts forwarded MQTT `PUBLISH` messages as HTTP `POST` requests, labeled by topic and HTTP status. |
| `mqtt2http_authenticate_count` | Counter | `code` | Counts HTTP authentication attempts during MQTT `CONNECT`, labeled by HTTP status code. |
| Metric | Type | Labels | Description |
| ----------------------------- | ------ | ------------- | ---------------------------------------------------------------------------------------------------- |
| `mqtt2http_sessions` | Gauge | _none_ | Tracks the current number of connected MQTT sessions. |
| `mqtt2http_authenticate_count`| Counter| `url`, `code` | Counts HTTP Basic Auth attempts made during MQTT `CONNECT`, labeled by authorization URL and status. |
| `mqtt2http_publish_count` | Counter| `topic` | Counts MQTT `PUBLISH` packets received per topic. |
| `mqtt2http_forward_count` | Counter| `url`, `code` | Counts HTTP requests sent while forwarding MQTT payloads, labeled by the resolved URL and status. |
| `mqtt2http_subscribe_count` | Counter| `topic` | Counts subscription requests per topic. |
| `mqtt2http_no_match_count` | Counter| `topic` | Counts messages for which no route was found. |