@open-rlb/nestjs-amqp 2.0.4 → 2.0.6

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

@@ -1,6 +1,6 @@
 ---
 name: rlb-amqp
-description: Reference, schema and gotchas for the @open-rlb/nestjs-amqp library (NestJS + RabbitMQ/AMQP + HTTP/WebSocket gateway). Use when answering questions about its YAML config (broker, topics, auth-providers, gateway, ws), AMQP rpc/handle/broadcast/event semantics, the @BrokerAction/@BrokerParam decorators, the BrokerService API, or when debugging wiring/timeout/auth/websocket errors. Also use as the shared knowledge base for the rlb-amqp-add-action, rlb-amqp-add-route, rlb-amqp-add-ws-event and rlb-amqp-scaffold skills.
+description: Reference, schema and gotchas for the @open-rlb/nestjs-amqp library (NestJS + RabbitMQ/AMQP + HTTP/WebSocket gateway). Use when answering questions about its YAML config (broker incl. routeDiscovery, topics, auth-providers, gateway paths/ws/events), AMQP rpc/handle/broadcast/event semantics, the @BrokerAction/@BrokerParam/@BrokerHTTP/@BrokerAuth decorators, the BrokerService API, route auto-discovery, gateway-admin (routes/auth-providers/metrics/health), the name-keyed ACL, or when debugging wiring/timeout/auth/websocket errors. Shared knowledge base for the rlb-amqp-add-action, rlb-amqp-add-route, rlb-amqp-add-ws-event, rlb-amqp-scaffold, rlb-amqp-acl and rlb-amqp-gateway-admin skills.
 ---
 
 # @open-rlb/nestjs-amqp — reference
@@ -23,17 +23,32 @@ HTTP/WS → Gateway (gateway.paths / gateway.events) → topic+action → Rabbit
   topic dispatches by `action`.
 - The same method serves both **RPC** (`requestData`, waits for the reply) and **event**
   (`publishMessage`, waits only for the broker's publisher confirm).
+- A microservice can announce its `@BrokerHTTP` routes to a gateway over AMQP
+  (**route auto-discovery**) so the gateway registers them without YAML edits.
 
 ## When to use this skill
 
 Load the bundled reference files before editing config, handlers or the gateway:
 
-- **`references/config-schema.md`** — full YAML schema for every section, field by field.
+- **`references/config-schema.md`** — full YAML schema for every section, field by field
+  (broker incl. `routeDiscovery`, topics 4 modes, auth-providers name-keyed, gateway
+  paths + ws + events).
 - **`references/gotchas.md`** — the checklist of bug-prone cases. ALWAYS scan it before
   adding/changing a topic, queue, exchange, action, route, auth provider or WS event.
 
-The human-facing docs live in the repo `README.md`; these files are the terse,
-rules-first version for editing tasks.
+The authoritative human-facing docs live under the repo `docs/` directory; these two files
+are the terse, rules-first version for editing tasks:
+
+- `docs/README.md` — index. `docs/getting-started.md` — bootstrap a ms + gateway.
+- `docs/broker.md` — `@BrokerAction`/`@BrokerParam`, topic modes, RPC, `BrokerService`.
+- `docs/gateway.md` — `gateway.paths[]`, `gateway.events[]`, auth gate, status mapping, ws.
+- `docs/acl.md` — name-keyed actions/roles, dual grant/revoke, `acl-can-user-do*` checks.
+- `docs/gateway-admin.md` — DB routes, name-keyed auth-providers, metrics, health, route-sync.
+- `docs/gotchas.md` — the canonical source `references/gotchas.md` is ported from.
+
+Runnable examples live under `sample/config-sample/` (`gateway-in-memory`, `gateway-db`,
+`calculator.ms`, plus the annotated `broker/gateway/acl/gateway-admin.yaml` reference
+configs). The retired `apps/gateway-2` is gone — do not cite it.
 
 ## Sibling task skills
 
@@ -41,6 +56,8 @@ rules-first version for editing tasks.
 - `rlb-amqp-add-route` — expose an action over HTTP (`gateway.paths[]`).
 - `rlb-amqp-add-ws-event` — add a secure WebSocket/webhook event (`gateway.events[]`).
 - `rlb-amqp-scaffold` — bootstrap a new microservice/gateway (module, main, config).
+- `rlb-amqp-acl` — name-keyed actions/roles, grant/revoke, the `acl-can-user-do*` checks.
+- `rlb-amqp-gateway-admin` — DB routes/auth-providers, metrics, health, route auto-discovery.
 
 ## Golden rules (summary — full list in references/gotchas.md)
 
@@ -49,7 +66,8 @@ rules-first version for editing tasks.
 2. `mode: rpc`/`handle` need `topics[].queue` present in `broker.queues[]`, whose
    `exchange` exists in `broker.exchanges[]`.
 3. Exchange `type: topic` → the queue MUST have a `routingKey`.
-4. `broadcast` and the WebSocket gateway require `connection_name`.
+4. `broadcast` and the WebSocket gateway require a **distinct** `connection_name` per
+   instance (set it, or let `broker.routeDiscovery.serviceName` fill it in).
 5. `(topic, action)` must be unique — duplicates overwrite silently.
 6. No destructuring / default values in `@BrokerAction` method parameters; always pass an
    explicit `name` to `@BrokerParam`.
@@ -57,3 +75,13 @@ rules-first version for editing tasks.
 8. `roles` (HTTP or WS) require an `IAclRoleService` registered via
    `RLB_GTW_ACL_ROLE_SERVICE` in `ProxyModule.forRootAsync({ providers: [...] })`.
    Auth-providers + gateway config are passed to `ProxyModule` (not `BrokerModule`).
+9. Topic names `rlb-acl` / `rlb-gateway-admin` / `rlb-gateway-control` and ALL action
+   strings (`acl-*`, `gw-path-*`, `gw-auth-*`, `gw-metrics-*`, `gw-health`, `gw-reload`)
+   are decorator-bound and NOT configurable. Only exchange/queue/routingKey and the
+   route-discovery exchange/queue are.
+10. ACL actions/roles and gateway-admin auth-providers are **name-keyed**: `PUT` upserts,
+    `GET` lists, `GET .../get?name=`, `DELETE` by name. There is no POST and no id-based
+    ACL CRUD. Boolean checks (`/acl/check*`) return `200` with `true`/`false`.
+11. HTTP-route auth is **per ROUTE** and DECOUPLED from `@BrokerHTTP`: pair `@BrokerHTTP { name }`
+    ↔ `@BrokerAuth` `httpName`. A single `@BrokerHTTP` auto-pairs its `@BrokerAuth` (no name needed);
+    a route with no `@BrokerAuth` is public.

package/schematics/nest-add/files/skills/rlb-amqp/references/config-schema.md

@@ -1,8 +1,19 @@
 # config.yaml — full schema
 
 Five top-level sections: `app`, `broker`, `topics`, `auth-providers`, `gateway`.
-Loaded by `config/config.loader.ts`. `app`/`broker`/`topics` go to `BrokerModule.forRootAsync`;
-`auth-providers` + `gateway` go to `ProxyModule.forRootAsync` (see the repo `README.md` Quick start).
+Loaded by `config/config.loader.ts`. `app`/`broker`/`topics` → `BrokerModule.forRoot(broker, topics, app?)`;
+`auth-providers` + `gateway` → `ProxyModule.forRootAsync` (`authOptions` / `gatewayOptions`).
+Gateway-admin repos + the consumer-side `routeDiscovery` are wired in NEST code via
+`GatewayAdminModule.forRoot/forRootAsync` — not YAML.
+
+Authoritative sources: `docs/broker.md`, `docs/gateway.md`, `docs/gateway-admin.md`,
+`docs/acl.md`, and the annotated reference YAMLs under `sample/config-sample/`
+(`broker.yaml`, `gateway.yaml`, `acl.yaml`, `gateway-admin.yaml`).
+
+> **Decorator-bound vs configurable.** Topic NAMES `rlb-acl` / `rlb-gateway-admin` /
+> `rlb-gateway-control` and ALL action strings are fixed in code — write them exactly.
+> `exchange` / `queue` / `routingKey` and the route-discovery `exchange` / `queue` ARE
+> configurable.
 
 ---
 
@@ -24,47 +35,62 @@ to `{ message, name }`; in `development` the full detail/stack is included.
 
 ```yaml
 broker:
-  name: rabbitmq
-  uri: "amqp://user:pass@host:5672/vhost"     # string | string[] (failover)
-  prefetchCount: 10
-  defaultRpcTimeout: 10000                      # ms
-  defaultSubscribeErrorBehavior: ack            # ack | reject | requeue
+  name: rabbitmq                                # cosmetic label (optional)
+  uri: "amqp://user:pass@host:5672/vhost"       # string | string[] (failover); vhost after last "/"
+  prefetchCount: 10                             # default channel prefetch
+  defaultRpcTimeout: 10000                      # ms (call arg → topic → this → 10000)
+  defaultSubscribeErrorBehavior: ack            # ack | nack | requeue (lib default REQUEUE)
   defaultPublishErrorBehavior: reject
 
+  routeDiscovery:                               # PUBLISHER-side route auto-discovery (microservice only)
+    serviceName: demo-ms                        # required to publish; fills connection_name if unset
+    publishOnBoot: true                         # default true — announce manifest on bootstrap
+    exchange: rlb-route-discovery               # default; MUST match the gateway consumer
+    queue: rlb-route-sync                        # default; MUST match the gateway consumer
+
   connectionManagerOptions:                     # amqp-connection-manager options
     heartbeatIntervalInSeconds: 60
     reconnectTimeInSeconds: 60
     connectionOptions:
       clientProperties:
-        connection_name: my-service             # REQUIRED for broadcast + WebSocket gateway
+        connection_name: my-service-1            # DISTINCT per instance for broadcast + WebSocket
       credentials:
         mechanism: PLAIN                         # PLAIN | EXTERNAL | AMQPLAIN (case-insensitive)
         username: guest
         password: guest
 
+  connectionInitOptions:                        # block on a healthy connection at boot?
+    wait: true                                   # default true
+    timeout: 5000                                # default 5000 ms
+    reject: true                                 # default true → throw on timeout
+
   exchanges:                                    # RabbitMQExchangeConfig[]
-    - name: users-ex
+    - name: rlb
       type: direct                               # direct | topic | fanout | headers
       createExchangeIfNotExists: true            # false → checkExchange (must pre-exist)
       options: { durable: true, autoDelete: false, internal: false }
 
   queues:                                       # RabbitMQQueueConfig[]
-    - name: users-rpc-q
-      exchange: users-ex
-      routingKey: users.rpc                       # string | string[]; REQUIRED if exchange type == topic
+    - name: rlb-acl
+      exchange: rlb
+      routingKey: rlb-acl                         # string | string[]; REQUIRED if exchange type == topic
       createQueueIfNotExists: true
       options: { durable: true, exclusive: false, autoDelete: false }
-      consumerTag: my-tag                         # optional, must be unique per channel
+      consumerTag: my-tag                         # optional, unique per channel
 
   replyQueues:                                  # map exchange → reply queue (RPC responses)
-    users-ex: users-reply-q                       # omit → RabbitMQ direct-reply-to is used
+    rlb: rlb-reply                                # omit → RabbitMQ direct-reply-to is used
 ```
 
 Notes:
-- `exchanges[]` and `queues[]` are asserted/checked once at boot on the default channel.
-- `replyQueues` values are auto-consumed at boot.
-- Queue `options` is amqplib `Options.AssertQueue` (durable, exclusive, autoDelete,
-  messageTtl, deadLetterExchange, maxLength, maxPriority, arguments, ...).
+- `exchanges[]` / `queues[]` are asserted/checked once at boot; `replyQueues` values auto-consumed.
+- `routeDiscovery.serviceName` doubles as `connection_name` when no explicit `clientProperties.connection_name`
+  is set (explicit always wins). The **gateway** (consumer) does NOT use `broker.routeDiscovery` —
+  it sets its side via `GatewayAdminModule` `routeDiscovery { exchange, queue }`; both sides must match.
+- Do NOT declare a `broadcast` topic's per-instance queue here — the broker asserts
+  `${topic}-${connection_name}` for you at subscribe time.
+- Other optional fields: `defaultAlternateExchange` (divert unroutable), `onUnroutableMessage`
+  (callback, needs `mandatory: true` publishes), per-channel `channels` map.
 
 ---
 
@@ -74,60 +100,70 @@ A topic maps a logical name to an AMQP path. `mode` decides the semantics.
 
 ```yaml
 topics:
-  - name: users-rpc          # logical name (must match @BrokerAction / requestData / gateway)
+  - name: rlb-acl            # logical name (must match @BrokerAction / requestData / gateway)
     mode: rpc                 # rpc | handle | broadcast | event
-    queue: users-rpc-q        # for rpc/handle: must exist in broker.queues[]
-    exchange: users-ex        # for broadcast/event (direct exchange path)
-    routingKey: users.rpc     # for broadcast/event / topic exchanges
+    queue: rlb-acl            # for rpc/handle: must exist in broker.queues[]
+    exchange: rlb             # exchange name
+    routingKey: rlb-acl       # broadcast / topic exchanges
+    errorBehavior: ack        # per-topic override of defaultSubscribeErrorBehavior (default REQUEUE)
+    mandatory: false          # publish with AMQP `mandatory` (unroutable → returned)
+    persistent: false         # publish delivery-mode 2 (survives restart if queue durable)
     toObservable: false       # handle only: route to BrokerService.events$ instead of a handler
 ```
 
-| mode        | required fields                                  | notes                                  |
-| ----------- | ------------------------------------------------ | -------------------------------------- |
-| `rpc`       | `name`, `queue` (or `exchange`+`routingKey`)     | request/response + timeout             |
-| `handle`    | `name`, `queue`                                  | simple queue worker                    |
-| `broadcast` | `name`, `exchange`, `routingKey`                 | fanout/topic; needs `connection_name`  |
-| `event`     | `name`, `queue` OR `exchange`+`routingKey`       | fire-and-forget                        |
+| mode        | required fields                                  | notes                                                              |
+| ----------- | ------------------------------------------------ | ------------------------------------------------------------------ |
+| `rpc`       | `name`, `queue` (or `exchange`)                  | request/response + timeout; also the mode `@BrokerAction` uses     |
+| `handle`    | `name`, `queue`                                  | plain consumer, no reply (`registerHandler` / `toObservable`)      |
+| `broadcast` | `name`, `exchange`, `routingKey`                 | per-instance queue `${topic}-${connection_name}`; distinct name    |
+| `event`     | `name`, `exchange`+`routingKey` (or `queue`)     | fire-and-forget publish; no consumer asserted for the topic        |
 
 > A single `@BrokerAction` topic registers ONE consumer; multiple actions on the same
-> topic share it and are dispatched by `action`.
+> topic share it and are dispatched by `action`. The gateway control topic
+> (`rlb-gateway-control`) is `broadcast` so every instance reloads.
 
 ---
 
 ## auth-providers  (HandlerAuthConfig[])
 
+Top-level (NOT under `gateway`). Each provider VALIDATES a token and MAPS its claims into
+forwarded `X-GTW-AUTH-*` headers. Referenced by `paths[].auth` / `events[].auth` by `name`.
+
 ```yaml
 auth-providers:
   - name: gateway-jwks
     type: jwks                       # jwt | jwks | basic | str-compare | none
-    issuer: https://issuer/realms/x
+    headerPrefix: "X-GTW-AUTH-"      # prefix for mapped claim headers (and <prefix>USERID)
+    uidClaim: sub                    # claim → <prefix>USERID; REQUIRED for role checks
+    jwtMap:                          # 'source:dest' pairs → <prefix><DEST>; WITHOUT it NO claims forwarded
+      - sub:userId                   #   → X-GTW-AUTH-USERID
+      - email:email                  #   → X-GTW-AUTH-EMAIL
+      - preferred_username:username  #   → X-GTW-AUTH-USERNAME
+      - roles:roles                  #   → X-GTW-AUTH-ROLES
+    algorithms: [RS256]              # REQUIRED for jwt/jwks; jwks allows only RS*/ES*/PS*
+    issuer: https://issuer/realms/x  # expected `iss`
     jwksUri: https://issuer/certs    # jwks only
-    secret: s3cr3t                   # jwt / str-compare only
-    audience: my-aud                 # jwt only
-    algorithms: [RS256]
+    secret: s3cr3t                   # jwt (HS secret) / str-compare (expected token string)
+    audience: my-aud                 # jwt only (optional)
+    clientId: u                      # basic only (username)
+    clientSecret: p                  # basic only (password)
     httpsAllowUnauthorized: false    # true ONLY for self-signed dev issuers
-    clientId: u                      # basic only
-    clientSecret: p                  # basic only
-    jwtMap: [sub:userId, roles:roles]# tokenClaim:destClaim  (dest is header-prefixed + uppercased)
-    headerPrefix: X-GTW-AUTH-        # prefix of headers propagated to microservices
-    uidClaim: USERID                 # dest used as user id for ACL
-    usernameClaim: USERNAME
-    # aclTopic / aclAction are DEPRECATED & unused: the gateway role check runs in-process
-    # (IAclRoleService.canUserDoGtw) — no RPC topic/action needed.
 ```
 
-Mapping example: token `{ sub: "u_1" }` + `jwtMap: [sub:userId]` + `headerPrefix: X-GTW-AUTH-`
-→ header `X-GTW-AUTH-USERID = u_1`. Read it in a handler with
-`@BrokerParam('header', 'X-GTW-AUTH-USERID')`.
+Type behaviour:
+- **`jwt` / `jwks`** — verify `Authorization: Bearer <token>`, then map via `jwtMap`.
+- **`basic`** — verify `Authorization: Basic` vs `clientId`/`clientSecret`; maps username to
+  `<prefix>USERNAME`/`<prefix>USERID`. **No `clientSecret` → passes through** (open by design).
+- **`str-compare`** — compare raw `Authorization` to `secret`; maps to `<prefix>TOKEN`.
+  **No `secret` → passes through.**
 
-Types: `jwt` (HS/RS secret), `jwks` (remote keys), `basic` (clientId/clientSecret),
-`str-compare` (static token after `headerPrefix` in Authorization).
+Hardening: `algorithms` REQUIRED for `jwt`/`jwks` (omit → denied; algorithm-confusion guard).
+Define `jwtMap` or no identity is forwarded (token still `success:true` — fail-safe, not leak).
+`usernameClaim` is deprecated; `aclTopic`/`aclAction` are removed (gateway role check is in-process
+via `IAclRoleService.canUserDoGtw`).
 
-Provider notes: `algorithms` is REQUIRED for `jwt`/`jwks` (omit → denied; `jwks` allows only
-RS*/ES*/PS*, rejects HS*/none). `str-compare` without `secret` and `basic` without
-`clientSecret` PASS THROUGH (request treated as authenticated — provider effectively open).
-Define `jwtMap` to forward identity headers: without it NO claims are forwarded (the token is
-still accepted, `success:true`) — fail-safe instead of leaking the whole payload.
+> DB-stored auth-providers (name-keyed `gw-auth-*` upserts) layer on top of this static list —
+> see `docs/gateway-admin.md`.
 
 ---
 
@@ -136,80 +172,133 @@ still accepted, `success:true`) — fail-safe instead of leaking the whole paylo
 ```yaml
 gateway:
   mode: gateway
-  headerPrefix: X-GTW-               # prefix for forwarded request headers (forwardHeaders)
+  headerPrefix: "X-FWD-"             # prefix for FORWARDED request headers (forwardHeaders);
+                                     #   separate from a provider's headerPrefix (auth claims)
+
+  reloadTopic: rlb-gateway-control   # broadcast control topic; action 'gw-reload' rebuilds routes
+  metrics:                           # per-call broker sink (omit to disable)
+    topic: rlb-gateway-admin
+    action: gw-metrics-track
+
+  loadConfig:                        # pull DB-stored routes/events, merged with YAML, on (re)load
+    paths:  { topic: rlb-gateway-admin, action: gw-path-export }    # gateway-admin ships this handler
+    # events: { topic: <topic>, action: <your-export-action> }     # optional; NO built-in handler — provide your own
 
   ws:                                # WebSocketGatewayOptions — connection-level only
-    maxConnections: 5000
+    maxConnections: 1000
     maxSubscriptionsPerClient: 50
-    heartbeatIntervalMs: 30000
-    allowedOrigins: [https://app.example.com]   # Origin allowlist (omit → all accepted)
-    maxMessageBytes: 16384                        # drop oversized client frames (default 16KB)
+    heartbeatIntervalMs: 30000                     # default 30000; also drops dead/expired-token sockets
+    maxMessageBytes: 16384                          # default 16384; oversized client frames dropped
+    allowedOrigins: [https://app.example.com]       # omit → all Origins accepted (logged)
     # auth/roles/scope are declared PER-EVENT on events[], not here
 
-  loadConfig:                        # optional remote load via RPC at boot
-    paths:  { topic: gtw.config, action: get-paths }
-    events: { topic: gtw.config, action: get-events }
-
   paths:   [ ... ]                   # PathDefinition[] (HTTP routes) — see below
   events:  [ ... ]                   # WebSocketEvent[] (WS / webhook) — see below
 ```
 
+The reload control action is the literal string **`gw-reload`** (`GW_RELOAD_ACTION`); the
+control-topic subscriber ignores every other message. Concurrent `reload()`s are coalesced.
+
 ### gateway.paths[]  (PathDefinition — HTTP routes)
 
 ```yaml
-- name: users-create
-  method: POST              # GET | POST | PUT | DELETE | PATCH
-  path: /users/:tenant?     # Express route, params supported
-  dataSource: body          # body | query | params | body-query | query-body
-  topic: users-rpc
-  action: user.create
-  mode: rpc                 # rpc | event
-  timeout: 7000             # rpc only (ms)
-  auth: gateway-jwks        # auth-provider name
-  allowAnonymous: false     # true → allow even without valid auth
-  roles: [users.create]     # requires IAclRoleService
-  successStatusCode: 201
-  binary: false             # true → response sent as base64-decoded Buffer
-  redirect: 302             # if set → redirect to the URL contained in the reply
-  parseRaw: false           # true → forward raw body as $raw (needs rawBody:true in bootstrap)
+- name: report-download   # logical name (logs + metrics)
+  method: GET             # GET | POST | PUT | DELETE | PATCH
+  path: /reports/:id      # Express route, :params merged into payload (params win)
+  dataSource: query-body  # body | query | params | body-query | query-body
+  topic: rlb-gateway-admin
+  action: gw-metrics-get
+  mode: rpc               # rpc | event
+  timeout: 15000          # rpc only (ms)
+  auth: gateway-jwks      # auth-provider name
+  allowAnonymous: false   # true → skip the auth/role gate entirely
+  roles: [user, admin]    # caller must hold AT LEAST ONE; requires auth + IAclRoleService
+  successStatusCode: 200  # default 200 rpc / 202 event / 204 empty rpc reply
+  binary: true            # treat a raw (non-JSON) reply as base64 → binary body
+  redirect: 302           # rpc only → redirect with this status, using the reply as Location
+  parseRaw: false         # true → forward raw body as $raw (needs rawBody:true at bootstrap)
   headers: { Cache-Control: no-store }    # static response headers
-  forwardHeaders: { Tenant: x-tenant }    # request header → forwarded to the microservice
+  forwardHeaders: { X-Trace-Id: X-Request-Id }   # request header → forwarded (dest prefixed by headerPrefix)
 ```
 
-dataSource payload composition:
+dataSource payload composition (`req.params` always merged in, re-applied last so they win):
 
 | value        | payload                          |
 | ------------ | -------------------------------- |
 | `body`       | `{...params, ...body}`           |
 | `query`      | `{...params, ...query}`          |
-| `params`     | `params`                         |
+| `params`     | `{...params}`                    |
 | `body-query` | `{...params, ...query, ...body}` |
 | `query-body` | `{...params, ...body, ...query}` |
 
-Route params are re-applied last (win on key collisions). Uploads → `$files`, raw → `$raw`.
-Error `name` → HTTP status: BadRequestError/InvalidParamsErrror→400, UnauthorizedError→401,
-ForbiddenError→403, NotFoundError→404, else→500. `mode: event` confirm failure → 503.
+Uploads → `$files` (buffers as binary strings), raw → `$raw`.
+
+**rpc status:** defined reply (incl. falsy `false`/`0`/`""`) → `200` + body; `null`/`undefined`
+→ `204`. Error `name` → status: BadRequestError/InvalidParamsErrror→400, UnauthorizedError→401,
+ForbiddenError→403, NotFoundError→404, ConflictError→409, else→500.
+**event status:** successful publish → `successStatusCode || 202`; publish failure → `503`.
+
+Auth gate (per request): `allowAnonymous:true` → gate skipped; `auth` no `roles` → authn only
+(401 if invalid); `auth` + `roles` → authn then in-process `canUserDoGtw(roles, userId)` (403 if
+no role). `roles` without `auth` fails closed (every request 403).
 
 ### gateway.events[]  (WebSocketEvent — WS / webhook)
 
 ```yaml
-- name: orders
-  type: ws                 # ws | http (webhook)
-  exchange: orders-ex
-  routingKey: orders.#
+- name: chat               # clients subscribe to "chat"; messages arrive as onChat
+  type: ws                 # ws | mqtt (reserved) | http (webhook)
+  exchange: rlb            # broker source bound to a per-instance exclusive ephemeral queue
+  routingKey: chat.messages
   auth: gateway-jwks       # provider that verifies the token + maps claims FOR THIS event (at subscribe)
   requireAuth: true        # default true when `auth` is set; false → auth optional (anon allowed)
-  roles: [orders.read]     # ACL check via IAclRoleService
-  scopeClaim: X-GTW-AUTH-USERID   # forward only messages of this user...
-  payloadKey: userId              # ...where payload.userId === the mapped claim value
+  roles: [user]            # ACL check via IAclRoleService (needs auth)
+  scopeClaim: userId       # per-user isolation: the mapped claim value...
+  payloadKey: userId       # ...must equal payload[payloadKey]; without payloadKey → denies everything
   # type: http only:
   url: https://hooks.example.com/orders
   method: POST
-  timeout: 8000
+  timeout: 5000
   headers: { Authorization: "Bearer ..." }
 ```
 
-WS client connects with the JWT in the subprotocol: `new WebSocket(url, [token])`. The token
-is verified per-event with `events[].auth`'s provider (memoized per provider per connection).
-Client protocol: `{action:'subscribe'|'unsubscribe', topic, select?}`; inbound messages
-arrive as `{ topic: 'on<Name>', data }`, errors as `{ topic:'onError', data:{event,error} }`.
+WS client connects with the JWT in the subprotocol: `new WebSocket(url, [token])` (browsers
+can't set handshake headers). A bare value, or `['bearer', '<token>']` / `['jwt', '<token>']`,
+is accepted. Token verified per-event at subscribe (memoized per provider per connection);
+session bounded by the JWT `exp` (closed `1008` on expiry). Client protocol:
+`{action:'subscribe'|'unsubscribe', topic, select?}`; inbound `{ topic:'on<Name>', data }`;
+errors `{ topic:'onError', data:{event,error} }` (`unauthorized`, `forbidden`,
+`subscription_limit`, `unknown_event`). `select` is a client filter, intersected with — never
+bypassing — the server `scopeClaim` isolation. Each instance binds its own exclusive
+auto-delete queue, so every instance needs a distinct `connection_name`.
+
+---
+
+## gateway-admin / ACL HTTP surface (decorator-bound topics + actions)
+
+These are exposed as ordinary `gateway.paths[]` entries forwarding to the fixed topics/actions
+below. **Name-keyed** resources have NO POST and no id — `PUT` upserts by `name`.
+
+ACL (topic `rlb-acl`):
+
+| Method | Path | Action |
+| --- | --- | --- |
+| GET | `/acl/check` | `acl-can-user-do-gtw` (resource-agnostic; `200` true/false) |
+| GET | `/acl/check-resource` | `acl-can-user-do` (resource-scoped; `200` true/false) |
+| GET | `/acl/resources` | `acl-list-resources-by-user` (auth, reads `X-GTW-AUTH-USERID`) |
+| POST | `/acl/grants` | `acl-grant` (`{userId, roles, resourceId?, companyId?}`) |
+| DELETE | `/acl/grants` | `acl-revoke` (same shape; `roles` REQUIRED) |
+| GET / PUT / DELETE | `/acl/actions[/get?name=]` | `acl-action-list`/`-update`/`-delete`/`-get` |
+| GET / PUT / DELETE | `/acl/roles[/get?name=]` | `acl-role-list`/`-update`/`-delete`/`-get` |
+
+Gateway-admin (topic `rlb-gateway-admin`, except reload):
+
+| Method | Path | Action |
+| --- | --- | --- |
+| GET | `/health` | `gw-health` → `{ status: 'ok' }` |
+| POST / GET / PUT / DELETE | `/admin/paths[/export\|/get]` | `gw-path-create`/`-list`/`-export`/`-update`/`-get`/`-delete` (**id-keyed, POST creates**) |
+| GET / PUT / DELETE | `/admin/auth[/get?name=]` | `gw-auth-list`/`-update`/`-delete`/`-get` (**name-keyed PUT-upsert**) |
+| GET | `/admin/metrics[/series\|/points]` | `gw-metrics-get`/`-series`/`-points` |
+| POST | `/admin/metrics/track` | `gw-metrics-track` (`mode: event`) |
+| POST | `/admin/reload` | `gw-reload` on `rlb-gateway-control` (`mode: event`) |
+
+> Removed: `acl-list-by-user`, `acl-verify-access`, `gw-auth-create`, all id-based ACL CRUD.