@open-rlb/nestjs-amqp 2.0.4 → 2.0.6

package/schematics/nest-add/files/skills/rlb-amqp-add-route/SKILL.md

@@ -7,22 +7,46 @@ description: Expose a broker action over HTTP through the @open-rlb/nestjs-amqp
 
 Read first:
 - `.claude/skills/rlb-amqp/references/config-schema.md` (the `gateway.paths[]` section)
-- `.claude/skills/rlb-amqp/references/gotchas.md` (HTTP + auth items 11–15)
+- `.claude/skills/rlb-amqp/references/gotchas.md` (HTTP + auth items)
+- `docs/gateway.md` is the authority for the `PathDefinition` fields and status mapping.
 
 The target `topic`+`action` should already have a handler (otherwise also run
 `rlb-amqp-add-action`). The route only needs the topic to exist in `topics[]`.
+Canonical example: `sample/config-sample/gateway-in-memory/config/config.yaml`.
 
 ## Decide
 
-- **mode**: `rpc` (return the handler's response) or `event` (202 after publisher confirm,
-  503 on failure).
-- **dataSource**: how to build the payload — `body` | `query` | `params` | `body-query` |
-  `query-body` (see the composition table in the schema).
-- **auth**: an `auth-provider` name; `allowAnonymous: true` to permit unauthenticated access;
-  `roles: [...]` for ACL.
+- **mode**: `rpc` (return the handler's reply) or `event` (publish-and-confirm, no reply).
+- **dataSource**: how the payload is assembled — `req.params` are ALWAYS merged in, plus:
+  `body` | `query` | `params` | `body-query` (body wins) | `query-body` (query wins).
+- **auth**: an `auth-provider` name (validates the request, maps claims to `X-GTW-AUTH-*`
+  headers). `allowAnonymous: true` skips the gate. `roles: [...]` adds a role check.
 - Extras: `timeout` (rpc), `successStatusCode`, `binary`, `redirect`, `parseRaw`, static
   `headers`, `forwardHeaders`.
 
+## PathDefinition fields (all of them)
+
+| Field | Notes |
+| --- | --- |
+| `name` | Unique; used in logs + metrics. |
+| `method` | `GET` `POST` `PUT` `DELETE` `PATCH` … |
+| `path` | Express route, may carry `:params` (e.g. `/users/:id`). |
+| `topic` / `action` | Broker destination. Action strings are decorator-bound on the backend. |
+| `mode` | `rpc` \| `event`. |
+| `dataSource` | `body` \| `query` \| `params` \| `body-query` \| `query-body`. |
+| `auth` | Auth-provider name; validates + maps claims. |
+| `allowAnonymous` | `true` → gate skipped (token still mapped if present & valid). |
+| `roles` | Role NAMES; caller passes with AT LEAST ONE. Requires `auth`. |
+| `timeout` | RPC timeout (ms), `rpc` only. |
+| `binary` | Treat a raw (non-JSON) RPC reply as base64 → binary body. |
+| `parseRaw` | Adds the raw request body as `$raw` (needs `rawBody: true`). |
+| `successStatusCode` | Override success status (default 200 rpc / 202 event / 204 empty). |
+| `redirect` | On an `rpc` route, redirect with this status using the reply as the location. |
+| `headers` | Static response headers `{ k: v }`. |
+| `forwardHeaders` | `{ dest: srcHeader }` — copy request headers downstream (prefixed by `gateway.headerPrefix`). |
+
+Uploaded multipart files (any field) are attached as `$files` (buffers → binary strings).
+
 ## YAML fragment
 
 ```yaml
@@ -36,28 +60,67 @@ gateway:
       action: <action>
       mode: rpc                    # or event
       auth: gateway-jwks           # optional
-      roles: [resource.write]      # optional → needs IAclRoleService
+      roles: [resource.write]      # optional → needs RLB_GTW_ACL_ROLE_SERVICE
       timeout: 7000                # rpc only
       successStatusCode: 201
 ```
 
+## The 3-case auth gate
+
+For every request the gateway runs `processAuthData` (best-effort), then:
+
+1. **`allowAnonymous: true`** → gate SKIPPED. A valid token still gets its claims mapped &
+   forwarded; a missing/invalid token is NOT blocked.
+2. **`auth` set, no `roles`** → authentication only. Provider must validate (else `401`);
+   on success the `X-GTW-AUTH-*` headers are forwarded downstream.
+3. **`auth` + `roles`** → authn + role authz. After a valid token the gateway reads the user
+   id from the provider's `uidClaim` and calls `IAclRoleService.canUserDoGtw(roles, userId)`
+   in-process. Passes with at least one role, else `403`.
+
+> `roles` WITHOUT `auth` is a misconfiguration: no identity → fails closed (every request
+> `403`, logged loudly at boot). The resource-scoped check (`acl-can-user-do`) is NOT run by
+> the gateway — it lives on the target microservice.
+
+## Status mapping
+
+**`rpc`** reply → status:
+
+| Reply | Status |
+| --- | --- |
+| Defined value (incl. falsy `false` / `0` / `''`) | `200` + body |
+| `null` / `undefined` | `204 No Content` |
+
+> ONLY `null`/`undefined` collapses to `204`. A defined falsy result is real content, so a
+> boolean check route answers `200` with body `false` — not an empty `204`.
+
+**`rpc`** error → status (by error `name`):
+
+| Error name | Status |
+| --- | --- |
+| `BadRequestError`, `InvalidParamsErrror` | `400` |
+| `UnauthorizedError` | `401` |
+| `ForbiddenError` | `403` |
+| `NotFoundError` | `404` |
+| `ConflictError` | `409` |
+| (any other) | `500` |
+
+**`event`** route: successful publish → `successStatusCode || 202`; publish failure → `503`.
+
 ## Required wiring to flag
 
-- If `parseRaw: true` → the app must bootstrap with
-  `NestFactory.create(AppModule, { rawBody: true })` (gotcha 12).
-- If `roles` is used → an `IAclRoleService` must be registered via
-  `RLB_GTW_ACL_ROLE_SERVICE` in `ProxyModule.forRootAsync({ providers: [...] })`. The check
-  is role-based (`canUserDoGtw(path.roles, userId)`): `roles` are ROLE NAMES and the user
-  passes with AT LEAST ONE. The auth-provider only needs `uidClaim` (+ `headerPrefix`) to
-  extract the userId (gotcha 15). For a resource-scoped decision, the target ms calls
-  `canUserDo(roles, userId, resourceId)` (RPC `acl-can-user-do`) itself.
+- If `parseRaw: true` → bootstrap with `NestFactory.create(AppModule, { rawBody: true })`.
+- If `roles` is used → an `IAclRoleService` must be registered via `RLB_GTW_ACL_ROLE_SERVICE`
+  in `ProxyModule.forRootAsync({ providers: [{ provide: RLB_GTW_ACL_ROLE_SERVICE, useExisting: AclService }] })`.
+  If a path declares `roles` and the service is NOT registered → request DENIED (`403`) +
+  error logged. The auth-provider needs a `uidClaim` (+ `headerPrefix`) to resolve the userId.
 - Forwarded auth claims reach the handler as prefixed/uppercased headers
-  (e.g. `X-GTW-AUTH-USERID`) — read them with `@BrokerParam('header', ...)`.
+  (e.g. `X-GTW-AUTH-USERID`) — read them with `@BrokerParam('header', ...)`. Request headers
+  can never override mapped claim headers (anti-spoofing).
 
 ## Verify
 
-- topic exists in `topics[]` and resolves (gotchas 5–7).
-- route-param vs body/query key collisions are intentional (gotcha 13).
+- topic exists in `topics[]` and resolves.
+- route-param vs body/query key collisions are intentional (params always merge in).
 - `npm run build`, then optionally curl the route once the broker is up.
 
 Output the YAML fragment (with parent path), plus any bootstrap/ACL action the user still

package/schematics/nest-add/files/skills/rlb-amqp-add-ws-event/SKILL.md

@@ -8,38 +8,47 @@ description: Add a secure WebSocket event (or HTTP webhook) to the @open-rlb/nes
 Read first:
 - `.claude/skills/rlb-amqp/references/config-schema.md` (the `gateway.events[]` + `gateway.ws`
   sections)
-- `.claude/skills/rlb-amqp/references/gotchas.md` (WebSocket items 16–18, ACL item 15)
+- `.claude/skills/rlb-amqp/references/gotchas.md` (WebSocket items 16–18, 26–27; ACL item 15)
 
-A WS event subscribes to an exchange/routingKey and fans the messages out to the connected
-clients of EVERY gateway instance. Secure it by default.
+A WS event binds a broker `exchange`/`routingKey` to a named client-facing stream and fans
+each message out to the connected clients of EVERY gateway instance. Secure it by default.
 
 ## Decide
 
 - **type**: `ws` (push to clients) or `http` (forward each message to a webhook `url`).
+  (`mqtt` is also accepted by the type union but `ws`/`http` are the supported paths.)
 - **source**: `exchange` + `routingKey` (the exchange must exist in `broker.exchanges[]`;
-  `connection_name` must be set — gotcha 8).
+  each instance needs a distinct `connection_name` — gotcha 8).
+- **client-facing name**: clients subscribe by `name`; messages arrive as `on<Name>`
+  (first letter capitalized — `chat` → `onChat`).
 - **security**:
   - `auth: <provider>` → the provider that verifies the connection token AND maps its claims
-    for THIS event (at subscribe time). When set, a valid token is required to subscribe.
+    for THIS event (at subscribe time, memoized per provider). When set, a valid token is
+    required to subscribe.
   - `requireAuth: false` → makes `auth` optional (anonymous allowed; claims mapped if a token
     is present — handy with `scopeClaim`). Defaults to `true` when `auth` is set.
   - `roles: [...]` → ACL check (needs `IAclRoleService`); requires `auth` for the identity.
-  - `scopeClaim` + `payloadKey` → per-user scoping: a client only receives messages where
+  - `scopeClaim` + `payloadKey` → per-user isolation: a client only receives messages where
     `payload[payloadKey] === claims[scopeClaim]`. `scopeClaim` is the MAPPED claim
     (with `headerPrefix`, e.g. `X-GTW-AUTH-USERID`). Without `payloadKey` it denies all
-    (gotcha 16).
+    (gotcha 16). With `auth` but no `scopeClaim`/`payloadKey`, every authorized subscriber
+    gets ALL messages (warned at boot).
 
-> Auth/roles/scope are declared PER-EVENT. `gateway.ws` only holds connection-level limits
-> and heartbeat (no auth fields). Different events may use different providers.
+> Auth/roles/scope are declared PER-EVENT. `gateway.ws` only holds connection-level limits,
+> heartbeat, origin allowlist and message-size cap (no auth fields). Different events may use
+> different providers.
 
 ## YAML fragments
 
 ```yaml
 gateway:
   ws:                                   # connection-level only (optional)
-    maxConnections: 5000
-    maxSubscriptionsPerClient: 50
-    heartbeatIntervalMs: 30000
+    maxConnections: 5000                # max concurrent connections this instance accepts
+    maxSubscriptionsPerClient: 50       # max active subscriptions per client
+    heartbeatIntervalMs: 30000          # ping/pong; also drops dead sockets + expired tokens
+    allowedOrigins:                     # reject cross-site handshakes; omit → all origins (logged)
+      - https://app.example.com
+    maxMessageBytes: 16384              # inbound client frame cap; larger frames dropped (default)
 
   events:
     - name: orders
@@ -49,8 +58,8 @@ gateway:
       auth: gateway-jwks                # verifies token + maps claims for this event
       requireAuth: true                 # default true when auth is set; false → optional
       roles: [orders.read]              # optional → needs IAclRoleService
-      scopeClaim: X-GTW-AUTH-USERID     # optional per-user scoping
-      payloadKey: userId
+      scopeClaim: X-GTW-AUTH-USERID     # optional per-user scoping (MAPPED claim)
+      payloadKey: userId                # message field compared to scopeClaim
 
     - name: invoices                    # webhook variant
       type: http
@@ -58,6 +67,7 @@ gateway:
       routingKey: inv.#
       url: https://hooks.example.com/invoices
       method: POST
+      headers: { x-api-key: secret }
       timeout: 8000
 ```
 
@@ -75,19 +85,31 @@ broker:
 ## Required wiring to flag
 
 - The app bootstrap must register the WS adapter:
-  `app.useWebSocketAdapter(new WsAdapter(app))`.
+  `app.useWebSocketAdapter(new WsAdapter(app))` (see
+  `sample/config-sample/gateway-in-memory/src/main.ts`).
 - `events[].auth` must reference a `jwt`/`jwks` provider; subscribing without a valid token
   yields `{ topic:'onError', data:{ event, error:'unauthorized' } }` (unless `requireAuth:false`).
-- `roles` → `IAclRoleService` via `RLB_GTW_ACL_ROLE_SERVICE` (gotcha 15).
+  A failed role check yields `error:'forbidden'`.
+- `roles` → `IAclRoleService` via `RLB_GTW_ACL_ROLE_SERVICE` in
+  `ProxyModule.forRootAsync({ providers: [...] })` (gotcha 15).
 - Do NOT add a fixed durable queue for the event — the lib creates a per-instance exclusive
-  queue for fan-out (gotcha 17).
+  ephemeral auto-delete queue for fan-out (gotcha 17).
+- WS sessions are bounded by the token `exp`: the socket is closed (`1008`) when the JWT
+  expires; long-lived sockets need refresh + reconnect (gotcha 26).
 
 ## Client snippet (for docs/testing)
 
 ```js
-const ws = new WebSocket('ws://localhost:3000', [token]);   // token in subprotocol
+// token in subprotocol — browsers can't set custom handshake headers (gotcha 18).
+// single value = token; ['bearer', token] / ['jwt', token] pairs also accepted.
+const ws = new WebSocket('ws://localhost:3000', [token]);
 ws.onopen = () => ws.send(JSON.stringify({ action: 'subscribe', topic: 'orders' }));
 ws.onmessage = (e) => console.log(JSON.parse(e.data)); // { topic:'onOrders', data } | { topic:'onError', ... }
+// unsubscribe: ws.send(JSON.stringify({ action: 'unsubscribe', topic: 'orders' }));
 ```
 
+> An optional `select: { key: value }` in the subscribe frame is a client-side filter
+> (forwarded only when `payload[key] === value` for every key). It is INTERSECTED with the
+> server-enforced `scopeClaim` isolation — a `select` can never widen what a user receives.
+
 Output the YAML fragments (with parent paths) and the bootstrap/ACL items still required.

package/schematics/nest-add/files/skills/rlb-amqp-gateway-admin/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: rlb-amqp-gateway-admin
+description: Drive the @open-rlb/nestjs-amqp gateway-admin management plane and route auto-discovery. Use for DB-managed HTTP routes (gw-path-*), DB auth-providers CRUD (gw-auth-*, name-keyed PUT-upsert), gateway metrics (gw-metrics-get/series/points/track) and the gw-health probe, runtime route reload (gw-reload via the broadcast control topic), the in-proxy metrics hook (RLB_GTW_METRICS_HOOK), and wiring GatewayAdminModule.forRoot/forRootAsync. Also covers route auto-discovery: publisher (broker.routeDiscovery serviceName/publishOnBoot/exchange/queue) vs consumer (GatewayAdminModule routeDiscovery exchange/queue).
+---
+
+# Gateway-admin module + route auto-discovery
+
+Read first:
+- `docs/gateway-admin.md` (full reference)
+- `sample/config-sample/gateway-admin.yaml` (annotated YAML for every action)
+- `sample/config-sample/gateway-db/` (runnable wiring; `apps/gateway-2` was retired)
+
+The gateway-admin module is the gateway's management plane: DB-stored routes,
+DB auth-providers, metrics, runtime reload, and the consumer side of route
+auto-discovery. All handlers bind to the topic `rlb-gateway-admin`
+(`GATEWAY_ADMIN_TOPIC`). The topic NAME and every action string are
+**decorator-bound — NOT configurable**. You drive them by adding
+`gateway.paths[]` that forward to that topic/action.
+
+## Fixed vs configurable
+
+- FIXED (write exactly): topic names `rlb-gateway-admin`, control action
+  `gw-reload`, and all action strings `gw-path-*` / `gw-auth-*` / `gw-metrics-*`
+  / `gw-health` (from `GW_ADMIN_ACTIONS` + `GW_RELOAD_ACTION`).
+- CONFIGURABLE: each topic's exchange/queue/routingKey, and the route-discovery
+  exchange/queue (defaults `rlb-route-discovery` / `rlb-route-sync`) — which must
+  match on the publisher AND consumer sides.
+
+## Nest wiring — `GatewayAdminModule`
+
+`forRoot(providers, options)`: repo bindings FIRST, options SECOND. You supply
+the four repositories (any store); the module ships the services and wires
+`RouteSyncService` internally. Tokens are re-exported from `@open-rlb/nestjs-amqp`.
+
+```ts
+GatewayAdminModule.forRoot([
+  { provide: HttpPathRepository,     useExisting: MongoHttpPathRepository },
+  { provide: AuthProviderRepository, useExisting: MongoAuthProviderRepository },
+  { provide: HttpMetricRepository,   useExisting: MongoHttpMetricRepository },
+  { provide: RouteSyncLogRepository, useExisting: MongoRouteSyncLogRepository }, // route-discovery journal
+]),
+```
+
+Use `forRootAsync` to resolve the **consumer-side** `routeDiscovery { exchange, queue }`
+from config (see Route auto-discovery). Exports `GatewayPathService`,
+`GatewayAuthService`, `GatewayMetricsService`.
+
+## Broker topic + queue (required)
+
+```yaml
+broker:
+  queues:
+    - name: rlb-gateway-admin
+      exchange: rlb
+      routingKey: rlb-gateway-admin
+      createQueueIfNotExists: true
+      options: { durable: true }
+topics:
+  - name: rlb-gateway-admin     # MUST be this name
+    mode: rpc
+    queue: rlb-gateway-admin
+    exchange: rlb
+    routingKey: rlb-gateway-admin
+  - name: rlb-gateway-control   # name is yours; must match gateway.reloadTopic + gw-reload path
+    mode: broadcast
+    exchange: rlb
+    routingKey: rlb-gateway-control
+```
+
+Point `loadConfig.paths` at the export responder so DB routes merge with YAML
+`gateway.paths` on boot and on every reload (merged static-before-param):
+
+```yaml
+gateway:
+  loadConfig:
+    paths: { topic: rlb-gateway-admin, action: gw-path-export }
+  reloadTopic: rlb-gateway-control
+  metrics: { topic: rlb-gateway-admin, action: gw-metrics-track }  # auto-emit track per request
+```
+
+## Route management — `gw-path-*` (id-keyed)
+
+`gw-path-create` is a **POST** (DB paths have an `id`) — unlike the name-keyed
+auth/ACL resources. `create` rejects a `(method, path)` collision (409).
+`export` returns enabled paths, ordered, and feeds `loadConfig.paths`.
+
+| Method | Path | action | dataSource | Notes |
+| --- | --- | --- | --- | --- |
+| POST   | `/admin/paths`        | `gw-path-create` | body  | needs `name,method,path,topic`; 409 on collision |
+| GET    | `/admin/paths`        | `gw-path-list`   | query | `?page=&limit=` |
+| GET    | `/admin/paths/export` | `gw-path-export` | query | enabled, ordered; used by `loadConfig.paths` |
+| PUT    | `/admin/paths`        | `gw-path-update` | body  | needs `id`; re-checks collisions |
+| GET    | `/admin/paths/get`    | `gw-path-get`    | query | `?id=` |
+| DELETE | `/admin/paths`        | `gw-path-delete` | body  | `{ id }` |
+
+## Auth-provider management — `gw-auth-*` (name-keyed PUT-upsert)
+
+No `id`, no POST — a single `PUT` creates-or-updates by `name`. These are the
+DB-stored providers, ON TOP of the static `auth-providers[]` in YAML.
+
+| Method | Path | action | dataSource | Notes |
+| --- | --- | --- | --- | --- |
+| GET    | `/admin/auth`     | `gw-auth-list`   | query | `?page=&limit=` |
+| PUT    | `/admin/auth`     | `gw-auth-update` | body  | upsert by name; `{ name, type, ... }` |
+| GET    | `/admin/auth/get` | `gw-auth-get`    | query | `?name=` |
+| DELETE | `/admin/auth`     | `gw-auth-delete` | body  | `{ name }` |
+
+`gw-auth-export` (dump all enabled) also exists; not in the sample YAML.
+
+## Metrics — `gw-metrics-*` + `gw-health`
+
+| Method | Path | action | mode | dataSource | Returns |
+| --- | --- | --- | --- | --- | --- |
+| GET  | `/admin/metrics`        | `gw-metrics-get`    | rpc   | query | counters/route (`count,errorCount,avgDurationMs`); `?route=` |
+| GET  | `/admin/metrics/series` | `gw-metrics-series` | rpc   | query | buckets: `?bucketMs=60000&from=&to=&method=&route=&name=` |
+| GET  | `/admin/metrics/points` | `gw-metrics-points` | rpc   | query | raw points newest-first: `?method=&route=&from=&to=&limit=` |
+| POST | `/admin/metrics/track`  | `gw-metrics-track`  | event | body  | fire-and-forget sink (wired via `gateway.metrics`) |
+
+`gw-health` → `{ status: 'ok' }`, a real 200 liveness probe (NOT a metrics dump):
+
+```yaml
+- name: health
+  method: GET
+  path: /health
+  dataSource: query
+  topic: rlb-gateway-admin
+  action: gw-health
+  mode: rpc
+```
+
+### In-proxy metrics hook — `RLB_GTW_METRICS_HOOK`
+
+Independent of the broker `gateway.metrics` sink: the gateway invokes a hook
+once per request, after the response is flushed. Register under
+`RLB_GTW_METRICS_HOOK` in `ProxyModule.forRootAsync`'s `providers`. Both sinks
+can be active; the hook must not throw and should be cheap/async.
+
+```ts
+export interface GatewayMetricsHook { track(p: GatewayMetricPoint): void | Promise<void>; }
+// GatewayMetricPoint: { ts, method, route, name?, topic?, action?, mode?, status?, durationMs? }
+
+ProxyModule.forRootAsync({ /* ... */ providers: [
+  { provide: RLB_GTW_METRICS_HOOK, useClass: InfluxMetricsHook },
+]}),
+```
+
+(`sample/config-sample/gateway-db` ships an `InfluxMetricsHook` that is a no-op
+until `INFLUX_URL/TOKEN/ORG` env are set.)
+
+## Runtime reload — `gw-reload`
+
+The ONLY control action that forces a route rebuild. Published to the
+**broadcast control topic** (`gateway.reloadTopic`, NOT `rlb-gateway-admin`),
+`mode: event`. The control-topic subscriber ignores everything except
+`gw-reload`, staying decoupled from other control traffic.
+
+```yaml
+- name: gw-reload
+  method: POST
+  path: /admin/reload
+  dataSource: body
+  topic: rlb-gateway-control   # the broadcast control topic
+  action: gw-reload
+  mode: event
+```
+
+Seed DB routes via `POST /admin/paths`, then `POST /admin/reload` — no restart.
+
+## Route auto-discovery (publisher vs consumer)
+
+A microservice announces its own `@BrokerHTTP`/`@BrokerAction` routes; the
+gateway persists + registers them, no YAML edits. Two halves must agree on the
+same exchange/queue (defaults `rlb-route-discovery` / `rlb-route-sync`).
+
+### Publisher (microservice → gateway) — `broker.routeDiscovery`
+
+Lives in `BrokerModule`, so its config is INSIDE the broker block.
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `serviceName`   | —      | **Required to publish**; ownership key. PROMOTES to AMQP `connection_name` if none set. |
+| `publishOnBoot` | `true` | Announce manifest on bootstrap (durable/persistent message; queue buffers it). |
+| `exchange`      | `rlb-route-discovery` | Fanout exchange the manifest is published to. |
+| `queue`         | `rlb-route-sync`      | Durable shared work-queue the gateway consumes. |
+
+```yaml
+# in the MICROSERVICE config.yaml:
+broker:
+  routeDiscovery:
+    serviceName: demo-ms     # required; also fills connection_name if unset
+    publishOnBoot: true
+    # exchange/queue default; override only to namespace per env (then match the consumer)
+```
+
+Routes are declared `@BrokerHTTP` over a `@BrokerAction` method. The gateway must
+still declare the microservice's broker topic so it can route forwarded calls.
+
+Each published route's auth comes from `@BrokerAuth` (decoupled from `@BrokerHTTP`),
+paired per route by name: with one `@BrokerHTTP` it auto-pairs; with multiple, each
+`@BrokerHTTP` sets a `name` and each `@BrokerAuth` matches it via `httpName`. So two
+routes over the same action can publish with different auth — a route with no paired
+`@BrokerAuth` is published as public.
+
+```ts
+@BrokerHTTP('GET', '/admin/bookings/:id', 'params', { name: 'admin-get-booking' })
+@BrokerAuth('admin-jwks', undefined, ['admin'], 'admin-get-booking')  // pairs by httpName
+```
+
+### Consumer (gateway ← microservice) — `GatewayAdminModule` `routeDiscovery`
+
+Wired by `GatewayAdminModule` (NOT YAML). Asserts the fanout exchange, subscribes
+to the durable queue (competing consumers), then per manifest: diffs vs DB scoped
+to the publishing service, applies only changes (insert/update; soft-disable stale
+to `enabled:false`; skip collisions — existing owner keeps `(method,path)`),
+journals every event via `RouteSyncLogRepository`, and publishes `gw-reload` when
+anything changed. Never throws (acks; no poison loop).
+
+```ts
+GatewayAdminModule.forRootAsync({
+  imports: [ConfigModule], inject: [ConfigService],
+  useFactory: (c: ConfigService) => ({
+    routeDiscovery: {
+      exchange: c.get('routeDiscovery.exchange'), // default rlb-route-discovery
+      queue:    c.get('routeDiscovery.queue'),    // default rlb-route-sync — MUST match publishers
+    },
+  }),
+  providers: [ /* HttpPathRepository, AuthProviderRepository, HttpMetricRepository, RouteSyncLogRepository */ ],
+}),
+```
+
+The consumer has NO `serviceName` (it only receives). The exchange/queue MUST
+match every publisher's `broker.routeDiscovery`.
+
+## Verify
+
+- Topic `rlb-gateway-admin` (+ queue) declared; `reloadTopic` matches the
+  broadcast control topic name and the `gw-reload` path's `topic`.
+- Action strings written exactly (`gw-path-*`, `gw-auth-*`, `gw-metrics-*`,
+  `gw-health`, `gw-reload`).
+- `loadConfig.paths` → `gw-path-export`; `gateway.metrics` → `gw-metrics-track`.
+- Route-discovery `exchange`/`queue` identical on publisher and consumer.
+- All four repositories bound; `npm run build`.
+
+See also: `rlb-amqp` (schema/gotchas) · `rlb-amqp-add-route` · `docs/gateway.md` · `docs/acl.md`