@open-rlb/nestjs-amqp 2.0.3 → 2.0.5

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,233 @@
+---
+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.
+
+### 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`

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

@@ -9,10 +9,83 @@ Read first:
 - `.claude/skills/rlb-amqp/references/config-schema.md`
 - `.claude/skills/rlb-amqp/references/gotchas.md`
 
-Decide the role: a **microservice** (only `@BrokerAction` handlers), a **gateway**
-(HTTP/WS exposure), or **both** in one app. Generate only the pieces needed.
+Decide the role: a **microservice** (only `@BrokerAction` / `@BrokerHTTP` handlers, no
+HTTP server) or a **gateway** (HTTP/WS exposure in front of microservices). Two paths:
+the `nest add` schematic (fast, patches in place) or manual wiring. Canonical runnable
+examples live under `sample/config-sample/` (`gateway-in-memory`, `gateway-db`,
+`calculator.ms`) — mirror those, not the retired `apps/gateway-2`.
 
-## 1. `src/config/config.loader.ts`
+---
+
+## Path A — `nest add` schematic (preferred)
+
+From a NestJS project root:
+
+```bash
+nest add @open-rlb/nestjs-amqp
+```
+
+It **patches in place** (does not scaffold a new app): edits `src/app.module.ts` and
+`src/main.ts`, creates `src/config/config.loader.ts` + `config/config.yaml`, copies
+RUNNABLE in-memory repositories for the selected features, adds deps, and copies the
+Claude skills.
+
+### Interactive flow
+
+1. **"Create a gateway (HTTP/WebSocket) configuration? y/N"**
+2. **YES** → checkbox of gateway features:
+   - `acl` — `AclModule` + ACL management/grant/check paths
+   - `gateway-admin` — `GatewayAdminModule` + DB-managed routes/auth-providers/metrics paths
+   - `route-reception` — gateway consumes routes auto-published by microservices
+   Then prompts for names (defaults shown): exchange `rlb`, ACL queue `rlb-acl`,
+   admin queue `rlb-gateway-admin`, control topic `rlb-gateway-control`,
+   route exchange `rlb-route-discovery`, route queue `rlb-route-sync`.
+3. **NO** (plain microservice) → checkbox:
+   - `auto-config-publish` — publish this service's `@BrokerHTTP` routes to the gateway
+     on boot (adds `broker.routeDiscovery`). Prompts service name + route exchange/queue.
+4. "Copy the Claude skills into .claude/skills? Y/n"
+
+### Non-interactive flags (CI / scripted)
+
+Passing `--gatewayConfig` or any `--features` skips the prompts; everything else falls
+back to `rlb-*` defaults.
+
+```bash
+# Gateway with ACL + admin + route reception
+nest add @open-rlb/nestjs-amqp \
+  --gatewayConfig --features acl --features gateway-admin --features route-reception
+
+# Plain microservice that auto-publishes its @BrokerHTTP routes on boot
+nest add @open-rlb/nestjs-amqp \
+  --gatewayConfig=false --features auto-config-publish \
+  --serviceName my-service --routeExchange rlb-route-discovery --routeQueue rlb-route-sync
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--gatewayConfig` | `true` = gateway, `false` = microservice (default false non-interactive). |
+| `--features <f>` | Repeatable. Gateway: `acl`, `gateway-admin`, `route-reception`. MS: `auto-config-publish`. |
+| `--exchange` | Main AMQP exchange backing acl/admin queues. Default `rlb`. |
+| `--aclQueue` / `--adminQueue` | Queues backing the fixed `rlb-acl` / `rlb-gateway-admin` topics. |
+| `--controlTopic` | Broadcast control/reload topic. Default `rlb-gateway-control`. |
+| `--routeExchange` / `--routeQueue` | Route-discovery exchange/queue. Defaults `rlb-route-discovery` / `rlb-route-sync` — **must match both publisher and gateway**. |
+| `--serviceName` | Route-publish ownership key + AMQP `connection_name`. Default = project name. |
+| `--skills` | Copy Claude skills. Default `true`; `--skills=false` to skip. |
+
+> `app.module.ts` patch is idempotent (keys off `BrokerModule.forRootAsync`). If it can't
+> locate `app.module.ts` / `main.ts` it warns and leaves you the manual wiring below.
+
+After scaffolding, edit `config/config.yaml` (fill `<AMQP_URI>` / credentials) and replace
+the `<APP_NAME>` `connection_name` placeholder. Then use `rlb-amqp-add-action` /
+`rlb-amqp-add-route` / `rlb-amqp-add-ws-event` to grow the service.
+
+---
+
+## Path B — manual wiring
+
+Mirrors `sample/config-sample/gateway-in-memory` (gateway) and `calculator.ms` (pure MS).
+
+### 1. `src/config/config.loader.ts`
 
 ```ts
 import { readFileSync } from 'fs';
@@ -20,23 +93,25 @@ import * as yaml from 'js-yaml';
 import { join } from 'path';
 
 const YAML_CONFIG_FILENAME = 'config/config.yaml';
+
 export default () =>
   yaml.load(readFileSync(join(process.cwd(), YAML_CONFIG_FILENAME), 'utf8')) as Record<string, any>;
 ```
 
-(`js-yaml` is a dependency of the config loader; ensure it's installed.)
+(`js-yaml` + `@nestjs/config` are deps; the gateway also needs `@nestjs/axios`,
+`@nestjs/platform-ws`, `@nestjs/websockets`, `ws`.)
 
-## 2. `src/app.module.ts`
+### 2. `src/app.module.ts`
 
 ```ts
-import { HttpModule } from '@nestjs/axios';
+import { HttpModule } from '@nestjs/axios';            // gateway only
 import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { AppConfig, BrokerModule, BrokerTopic, GatewayConfig, ProxyModule } from '@open-rlb/nestjs-amqp';
-import { RabbitMQConfig } from '@open-rlb/nestjs-amqp/amqp-lib/config/rabbitmq.config';
-import { HandlerAuthConfig } from '@open-rlb/nestjs-amqp/modules/broker/config/handler-auth.config';
+import {
+  AppConfig, BrokerModule, BrokerTopic, RabbitMQConfig,
+  GatewayConfig, HandlerAuthConfig, ProxyModule,       // gateway only
+} from '@open-rlb/nestjs-amqp';
 import yamlConfig from './config/config.loader';
-// import { MyActionService } from './my-action.service';
 
 @Module({
   imports: [
@@ -45,13 +120,15 @@ import yamlConfig from './config/config.loader';
       imports: [ConfigModule],
       inject: [ConfigService],
       useFactory: async (config: ConfigService) => ({
-        options: config.get<RabbitMQConfig>('broker'),
-        topics: config.get<BrokerTopic[]>('topics'),
+        // broker.routeDiscovery (publisher side), when used, lives INSIDE this `broker` block.
+        options: config.get<RabbitMQConfig>('broker')!,
+        topics: config.get<BrokerTopic[]>('topics')!,
         appOptions: config.get<AppConfig>('app'),
       }),
     }),
+
+    // --- gateway only: omit ProxyModule + HttpModule for a pure microservice ---
     HttpModule,
-    // Gateway: auth-providers + gateway config live in ProxyModule (NOT BrokerModule).
     ProxyModule.forRootAsync({
       imports: [ConfigModule],
       inject: [ConfigService],
@@ -60,33 +137,59 @@ import yamlConfig from './config/config.loader';
         gatewayOptions: config.get<GatewayConfig>('gateway'),
       }),
       providers: [
-        // { provide: RLB_GTW_ACL_ROLE_SERVICE, useClass: MyAclService }, // only if using `roles`
+        // Role-gated paths resolve the caller's roles in-process via this token (NO broker hop):
+        // { provide: RLB_GTW_ACL_ROLE_SERVICE, useExisting: AclService }, // required if any path uses `roles`
+        // Optional in-proxy per-request metrics hook (independent of gateway.metrics):
+        // { provide: RLB_GTW_METRICS_HOOK, useClass: InfluxMetricsHook },
       ],
     }),
   ],
-  providers: [/* MyActionService */],
+  providers: [/* AppService — your @BrokerAction / @BrokerHTTP handlers */],
 })
 export class AppModule {}
 ```
 
-> Omit `ProxyModule`/`HttpModule` for a pure microservice with no HTTP/WS gateway.
+> The gateway's `auth-providers` + `gateway` config belong to **`ProxyModule`**, not
+> `BrokerModule`. For ACL add `AclModule.forRoot([...repos], { cache })` and bind
+> `RLB_GTW_ACL_ROLE_SERVICE`; for DB routes/auth/metrics add
+> `GatewayAdminModule.forRoot([...repos])` — see the `gateway-in-memory` sample and the
+> ACL / Gateway Admin docs.
+
+### 3. `src/main.ts`
 
-## 3. `src/main.ts`
+**Gateway** (needs `rawBody` + `WsAdapter`):
 
 ```ts
+import { ConfigService } from '@nestjs/config';
 import { NestFactory } from '@nestjs/core';
 import { WsAdapter } from '@nestjs/platform-ws';
 import { AppModule } from './app.module';
 
 async function bootstrap() {
-  const app = await NestFactory.create(AppModule, { rawBody: true }); // rawBody needed if any path uses parseRaw
-  app.useWebSocketAdapter(new WsAdapter(app));                        // only if using the WS gateway
-  await app.listen(3000, '0.0.0.0');
+  const app = await NestFactory.create(AppModule, { rawBody: true }); // rawBody: raw-body/webhook routes
+  app.useWebSocketAdapter(new WsAdapter(app));                        // WS events
+  app.enableShutdownHooks();
+  const cfg = app.get(ConfigService).get<{ port?: number; host?: string }>('app');
+  await app.listen(Number(process.env.PORT) || cfg?.port || 3000, cfg?.host || '0.0.0.0');
 }
 bootstrap();
 ```
 
-## 4. `config/config.yaml` (starter)
+**Pure microservice** (no HTTP server — `init()`, not `listen()`):
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.enableShutdownHooks();       // drain in-flight RPC + close AMQP cleanly on SIGINT/SIGTERM
+  await app.init();                // @BrokerAction handlers start consuming once initialized
+}
+bootstrap();
+```
+
+### 4. `config/config.yaml` (starter)
 
 ```yaml
 app:
@@ -94,28 +197,29 @@ app:
   host: 0.0.0.0
   environment: development
 
-auth-providers: []
+auth-providers: []   # gateway only — JWT/JWKS providers
 
 broker:
+  name: rabbitmq
   uri: "amqp://guest:guest@localhost:5672/"
-  defaultRpcTimeout: 10000
   defaultSubscribeErrorBehavior: ack
+  defaultPublishErrorBehavior: reject
   connectionManagerOptions:
     heartbeatIntervalInSeconds: 60
     reconnectTimeInSeconds: 60
     connectionOptions:
       clientProperties:
-        connection_name: my-service        # REQUIRED for broadcast/WebSocket
+        connection_name: my-service     # distinct per instance; needed for broadcast/WebSocket
       credentials: { mechanism: PLAIN, username: guest, password: guest }
   exchanges:
-    - name: my-ex
+    - name: rlb
       type: direct
       createExchangeIfNotExists: true
       options: { durable: true }
   queues:
     - name: my-rpc-q
-      exchange: my-ex
-      routingKey: my.rpc
+      exchange: rlb
+      routingKey: my-rpc-q
       createQueueIfNotExists: true
       options: { durable: true }
 
@@ -123,38 +227,64 @@ topics:
   - name: my-rpc
     mode: rpc
     queue: my-rpc-q
+    exchange: rlb
+    routingKey: my-rpc-q
 
+# --- gateway only ---
 gateway:
   mode: gateway
+  events: []
   paths:
-    - name: ping
+    - name: health
       method: GET
-      path: /ping
+      path: /health
       dataSource: query
-      topic: my-rpc
-      action: ping
+      topic: rlb-gateway-admin       # gateway-admin gw-health → 200 { status: 'ok' }
+      action: gw-health
       mode: rpc
-  events: []
 ```
 
-## 5. Sample handler (optional)
+### Route auto-discovery (publisher side, optional)
+
+A microservice can announce its `@BrokerHTTP` routes on boot. Add INSIDE the `broker`
+block — `serviceName` is the ownership key AND fills `connection_name` when none is set
+explicitly. `exchange`/`queue` default to `rlb-route-discovery` / `rlb-route-sync` and
+must match the gateway's `GatewayAdminModule` `routeDiscovery { exchange, queue }`.
+
+```yaml
+broker:
+  # ...
+  routeDiscovery:
+    serviceName: my-service
+    publishOnBoot: true
+    # exchange: rlb-route-discovery   # override to namespace per env (must match the gateway)
+    # queue: rlb-route-sync
+```
+
+### 5. Sample handler (one method, both transports)
 
 ```ts
 import { Injectable } from '@nestjs/common';
-import { BrokerAction, BrokerParam } from '@open-rlb/nestjs-amqp';
+import { BrokerAction, BrokerHTTP, BrokerParam } from '@open-rlb/nestjs-amqp';
 
 @Injectable()
-export class MyActionService {
-  @BrokerAction('my-rpc', 'ping', 'rpc')
-  async ping(@BrokerParam('body-full') data: any) {
-    return { pong: true, echo: data };
+export class AppService {
+  @BrokerAction('my-rpc', 'ping')                 // AMQP RPC on topic my-rpc, action ping
+  @BrokerHTTP('POST', '/ping', 'body')            // route metadata for gateway auto-discovery
+  async ping(@BrokerParam('body', 'name') name: string) {  // flat params, one decorator each
+    return { pong: true, name };
   }
 }
 ```
 
 ## Verify
-- topic/queue/exchange names line up (gotchas 5–7); `connection_name` set if needed (8).
-- `npm run build`, start the app with a reachable RabbitMQ, hit `/ping`.
+- topic/queue/exchange names line up across `broker`/`topics`/paths (gotchas 5–7);
+  `connection_name` set if using broadcast/WebSocket (8).
+- Route-discovery `exchange`/`queue` identical on publisher and gateway.
+- Reload DB routes at runtime via the `gw-reload` action on the broadcast control topic
+  (default `rlb-gateway-control`).
+- `npm run build`, start with a reachable RabbitMQ, hit `/health` (gateway) or publish to
+  the RPC topic (microservice).
 
-After scaffolding, use `rlb-amqp-add-action` / `rlb-amqp-add-route` / `rlb-amqp-add-ws-event`
-to grow the service.
+After scaffolding, use `rlb-amqp-add-action` / `rlb-amqp-add-route` /
+`rlb-amqp-add-ws-event` to grow the service.