Update documentation for the new routing feature

README.md

@@ -1,6 +1,6 @@
 # MQTT2HTTP
 
-A simple MQTT broker that connects to your HTTP services for login and message handling.
+MQTT broker that forwards topics to HTTP endpoints with configurable routing.
 
 ## Table of Contents
 
@@ -9,6 +9,7 @@ A simple MQTT broker that connects to your HTTP services for login and message h
 * [Quick Start](#quick-start)
 * [Docker](#docker)
 * [Configuration](#configuration)
+* [Routing](#routing)
 * [Metrics](#metrics)
 
 ## Features
@@ -20,7 +21,7 @@ A simple MQTT broker that connects to your HTTP services for login and message h
 
 ## Missing features
 
-* **ACL**: Limits wich topic can be published or subscribed to. Everything is allowed for now.
+* **ACL**: Limits which topic can be published or subscribed to. Everything is allowed for now.
 
 ## Quick Start
 
@@ -29,6 +30,7 @@ Set the URLs for your HTTP services using environment variables:
 ```env
 MQTT2HTTP_AUTHORIZE_URL=http://...
 MQTT2HTTP_PUBLISH_URL=http://...
+MQTT2HTTP_API_PASSWORD=somesecret
 ```
 
 ### MQTT to HTTP
@@ -38,10 +40,10 @@ MQTT2HTTP_PUBLISH_URL=http://...
 
 ### HTTP to MQTT
 
-* Publish messages to MQTT topics using the built-in REST API.
+* 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.
 
 ```bash
-curl --user username:password -X POST -d '{"test": true}' http://mqtt2http:8080/publish?topic=hello
+curl --user user:somesecret -X POST -d '{"test": true}' http://mqtt2http:8080/publish?topic=hello
 ```
 
 ## Docker
@@ -73,13 +75,39 @@ image: docker.io/amm0nite/mqtt2http:1.0.0
 | `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.             |
+| `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_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.                             |
 | `MQTT2HTTP_ROUTES_FILE_PATH` | `routes.yaml` | Path for the yaml file that defines all routes.
 | `MQTT2HTTP_API_PASSWORD` | random value | Password used to secure the API endpoints.
 
+## Routing
+
+Define fine-grained routing rules in a YAML file that is loaded at start-up. By default the broker looks for `routes.yaml` in the working directory, or you can set `MQTT2HTTP_ROUTES_FILE_PATH` to point to a different file.
+
+Each entry in the file is a map with three fields:
+
+* `name`: friendly identifier used in logs when the route matches.
+* `pattern`: Go regular expression tested against the MQTT topic (`^` / `$` anchors are optional).
+* `url`: target HTTP endpoint to receive the forwarded payload. Leave empty to drop messages for this route after a match.
+
+Example `routes.yaml`:
+
+```yaml
+- name: telemetry
+  pattern: '^sensors/.+'
+  url: https://example.com/iot/publish
+- name: drop-debug
+  pattern: '^debug/'
+  url: ''
+- name: fallback
+  pattern: '.*'
+  url: https://example.com/default/{topic}
+```
+
+Routes are evaluated in order and the first match wins. If no route matches, the broker logs the miss and no HTTP request is sent. When the routes file is empty (or missing) and `MQTT2HTTP_PUBLISH_URL` is configured, a default catch-all route using that URL is created automatically.
+
 ## Metrics
 
 Prometheus metrics are available at `/metrics` on the configured metrics address (`MQTT2HTTP_METRICS_HTTP_LISTEN_ADDRESS`).