@open-rlb/nestjs-amqp 2.0.4 → 2.0.5

package/schematics/nest-add/files/acl/src/cache/in-memory-acl-store.ts

@@ -0,0 +1,54 @@
+import { Injectable } from '@nestjs/common';
+import { AclCacheStore } from '@open-rlb/nestjs-amqp';
+
+interface Entry { value: string; exp: number; }
+
+/**
+ * In-memory L2 ACL cache for the example app. Replaces the private Redis-backed store so
+ * the example builds without external/private packages. It implements the same
+ * RLB_ACL_CACHE_STORE contract (string '1'/'0' decisions with a TTL) using a plain Map.
+ *
+ * NOT for production / multi-instance: the map is per-process and not shared, so cache
+ * invalidations on one instance won't reach the others. For a real deployment, plug a
+ * shared store (Redis, etc.) under RLB_ACL_CACHE_STORE instead.
+ */
+@Injectable()
+export class InMemoryAclStore implements AclCacheStore {
+  private readonly store = new Map<string, Entry>();
+
+  async get(key: string): Promise<string | null | undefined> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (entry.exp <= Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    this.store.set(key, { value, exp: Date.now() + ttlSeconds * 1000 });
+  }
+
+  async del(keys: string[]): Promise<void> {
+    for (const key of keys) this.store.delete(key);
+  }
+
+  async keys(pattern: string): Promise<string[]> {
+    // AclCacheService only uses simple globs like `acl/<userId>/*` (or `acl/*`).
+    const regExp = this.globToRegExp(pattern);
+    const out: string[] = [];
+    for (const key of this.store.keys()) {
+      if (regExp.test(key)) out.push(key);
+    }
+    return out;
+  }
+
+  private globToRegExp(pattern: string): RegExp {
+    const escaped = pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '.*')
+      .replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+  }
+}

package/schematics/nest-add/files/acl/src/modules/database/repository/acl.repository.ts

@@ -0,0 +1,74 @@
+import { Injectable } from '@nestjs/common';
+import {
+  AclAction,
+  AclActionRepository,
+  AclGrant,
+  AclGrantRepository,
+  AclRole,
+  AclRoleRepository,
+  PaginationModel,
+} from '@open-rlb/nestjs-amqp';
+import { InMemoryCollection } from './in-memory-collection';
+
+const page1 = (p?: number) => Number(p) || 1;
+const lim10 = (l?: number) => Number(l) || 10;
+
+@Injectable()
+export class InMemoryAclActionRepository extends AclActionRepository {
+  // Storage keeps an internal _id (the collection's key); the public AclAction has none.
+  private readonly col = new InMemoryCollection<AclAction & { _id?: string }>();
+
+  async insert(model: AclAction): Promise<AclAction> { return this.col.insert(model); }
+  async insertMany(models: AclAction[]): Promise<AclAction[]> { return this.col.insertMany(models); }
+  async findByName(name: string): Promise<AclAction> { return this.col.findOne({ name })!; }
+  async findOne(filter: Record<string, any>): Promise<AclAction> { return this.col.findOne(filter)!; }
+  async upsertOne(filter: Record<string, any>, model: Partial<AclAction>): Promise<AclAction> { return this.col.upsertOne(filter, model); }
+  async updateOne(filter: Record<string, any>, model: Partial<AclAction>): Promise<AclAction> { return this.col.updateOne(filter, model)!; }
+  async mergeOne(filter: Record<string, any>, model: Partial<AclAction>): Promise<AclAction> { return this.col.updateOne(filter, model)!; }
+  async removeOne(filter: Record<string, any>): Promise<AclAction> { return this.col.removeOne(filter)!; }
+  async removeMany(filter: Record<string, any>): Promise<number> { return this.col.removeMany(filter); }
+  async filter(filter: Record<string, any>): Promise<AclAction[]> { return this.col.filter(filter); }
+  async filterPaginated(filter: Record<string, any>, page?: number, limit?: number): Promise<PaginationModel<AclAction>> { return this.col.paginate(filter, page1(page), lim10(limit)); }
+  async retrieveAll(): Promise<AclAction[]> { return this.col.all(); }
+  async retrieveAllPaginated(page: number, limit: number): Promise<PaginationModel<AclAction>> { return this.col.paginate({}, page1(page), lim10(limit)); }
+}
+
+@Injectable()
+export class InMemoryAclRoleRepository extends AclRoleRepository {
+  // Storage keeps an internal _id (the collection's key); the public AclRole has none.
+  private readonly col = new InMemoryCollection<AclRole & { _id?: string }>();
+
+  async insert(model: AclRole): Promise<AclRole> { return this.col.insert(model); }
+  async insertMany(models: AclRole[]): Promise<AclRole[]> { return this.col.insertMany(models); }
+  async findByName(name: string): Promise<AclRole> { return this.col.findOne({ name })!; }
+  async findOne(filter: Record<string, any>): Promise<AclRole> { return this.col.findOne(filter)!; }
+  async upsertOne(filter: Record<string, any>, model: Partial<AclRole>): Promise<AclRole> { return this.col.upsertOne(filter, model); }
+  async updateOne(filter: Record<string, any>, model: Partial<AclRole>): Promise<AclRole> { return this.col.updateOne(filter, model)!; }
+  async removeOne(filter: Record<string, any>): Promise<AclRole> { return this.col.removeOne(filter)!; }
+  async filter(filter: Record<string, any>): Promise<AclRole[]> { return this.col.filter(filter); }
+  async filterPaginated(filter: Record<string, any>, page?: number, limit?: number): Promise<PaginationModel<AclRole>> { return this.col.paginate(filter, page1(page), lim10(limit)); }
+  async list(): Promise<AclRole[]> { return this.col.all(); }
+  async listPaginated(page: number, limit: number): Promise<PaginationModel<AclRole>> { return this.col.paginate({}, page1(page), lim10(limit)); }
+
+  async getActionsByNames(names: string[]): Promise<string[]> {
+    if (!names?.length) return [];
+    const roles = this.col.filter({ name: { $in: names } });
+    return [...new Set(roles.flatMap((r) => r.actions || []))];
+  }
+}
+
+@Injectable()
+export class InMemoryAclGrantRepository extends AclGrantRepository {
+  private readonly col = new InMemoryCollection<AclGrant>();
+
+  async insert(model: AclGrant): Promise<AclGrant> { return this.col.insert(model); }
+  async findById(id: string): Promise<AclGrant> { return this.col.findById(id)!; }
+  async findOne(filter: Record<string, any>): Promise<AclGrant> { return this.col.findOne(filter)!; }
+  async updateById(id: string, model: Partial<AclGrant>): Promise<AclGrant> { return this.col.updateById(id, model)!; }
+  async updateOne(filter: Record<string, any>, model: Partial<AclGrant>): Promise<AclGrant> { return this.col.updateOne(filter, model)!; }
+  async mergeById(id: string, model: Partial<AclGrant>): Promise<AclGrant> { return this.col.updateById(id, model)!; }
+  async removeById(id: string): Promise<AclGrant> { return this.col.removeById(id)!; }
+  async removeOne(filter: Record<string, any>): Promise<AclGrant> { return this.col.removeOne(filter)!; }
+  async filter(filter: Record<string, any>): Promise<AclGrant[]> { return this.col.filter(filter); }
+  async filterPaginated(filter: Record<string, any>, page?: number, limit?: number): Promise<PaginationModel<AclGrant>> { return this.col.paginate(filter, page1(page), lim10(limit)); }
+}

package/schematics/nest-add/files/db-core/src/modules/database/repository/in-memory-collection.ts

@@ -0,0 +1,122 @@
+import { PaginationModel } from '@open-rlb/nestjs-amqp';
+
+let __seq = 0;
+/** Monotonic, ObjectId-looking id (24 hex chars) — no randomness needed. */
+function nextId(): string {
+  return (++__seq).toString(16).padStart(24, '0');
+}
+
+/** True when `item` matches a simple filter: field equality and `{ $in: [...] }`. */
+function matches(item: any, filter: Record<string, any>): boolean {
+  for (const key of Object.keys(filter || {})) {
+    const cond = filter[key];
+    if (cond === undefined) continue;
+    if (cond && typeof cond === 'object' && Array.isArray(cond.$in)) {
+      if (!cond.$in.includes(item[key])) return false;
+    } else if (item[key] !== cond) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Tiny in-memory collection that mimics the slice of Mongo behavior the repositories
+ * need (CRUD by id/filter, `$in`, pagination). Returns shallow copies so callers can't
+ * mutate stored documents. Used by the example's RAM repositories instead of Mongoose.
+ */
+export class InMemoryCollection<T extends { _id?: string }> {
+  private readonly items = new Map<string, T>();
+
+  insert(model: T): T {
+    const _id = model._id ?? nextId();
+    const stored = { ...model, _id } as T;
+    this.items.set(_id, stored);
+    return { ...stored };
+  }
+
+  insertMany(models: T[]): T[] {
+    return (models || []).map((m) => this.insert(m));
+  }
+
+  private findId(filter: Record<string, any>): string | undefined {
+    for (const [id, v] of this.items) if (matches(v, filter)) return id;
+    return undefined;
+  }
+
+  upsertById(id: string, patch: Partial<T>): T {
+    return this.items.has(id) ? this.updateById(id, patch)! : this.insert({ ...(patch as object), _id: id } as T);
+  }
+
+  upsertOne(filter: Record<string, any>, patch: Partial<T>): T {
+    const id = this.findId(filter);
+    return id ? this.updateById(id, patch)! : this.insert(patch as T);
+  }
+
+  removeMany(filter: Record<string, any>): number {
+    let removed = 0;
+    for (const [id, v] of [...this.items]) if (matches(v, filter)) { this.items.delete(id); removed++; }
+    return removed;
+  }
+
+  findById(id: string): T | undefined {
+    const v = this.items.get(id);
+    return v ? { ...v } : undefined;
+  }
+
+  findOne(filter: Record<string, any>): T | undefined {
+    for (const v of this.items.values()) if (matches(v, filter)) return { ...v };
+    return undefined;
+  }
+
+  filter(filter: Record<string, any>): T[] {
+    return [...this.items.values()].filter((v) => matches(v, filter)).map((v) => ({ ...v }));
+  }
+
+  updateById(id: string, patch: Partial<T>): T | undefined {
+    const v = this.items.get(id);
+    if (!v) return undefined;
+    const next = { ...v, ...patch, _id: id } as T;
+    this.items.set(id, next);
+    return { ...next };
+  }
+
+  updateOne(filter: Record<string, any>, patch: Partial<T>): T | undefined {
+    for (const [id, v] of this.items) {
+      if (matches(v, filter)) {
+        const next = { ...v, ...patch, _id: id } as T;
+        this.items.set(id, next);
+        return { ...next };
+      }
+    }
+    return undefined;
+  }
+
+  removeById(id: string): T | undefined {
+    const v = this.items.get(id);
+    if (!v) return undefined;
+    this.items.delete(id);
+    return { ...v };
+  }
+
+  removeOne(filter: Record<string, any>): T | undefined {
+    for (const [id, v] of this.items) {
+      if (matches(v, filter)) {
+        this.items.delete(id);
+        return { ...v };
+      }
+    }
+    return undefined;
+  }
+
+  all(): T[] {
+    return [...this.items.values()].map((v) => ({ ...v }));
+  }
+
+  paginate(filter: Record<string, any>, page = 1, limit = 10): PaginationModel<T> {
+    const data = this.filter(filter);
+    const p = page < 1 ? 1 : page;
+    const start = (p - 1) * limit;
+    return { page: p, limit, total: data.length, data: data.slice(start, start + limit) };
+  }
+}

package/schematics/nest-add/files/gateway-admin/src/modules/database/repository/gateway.repository.ts

@@ -0,0 +1,151 @@
+import { Injectable } from '@nestjs/common';
+import {
+  AuthProviderRepository,
+  HandlerAuthConfig,
+  HttpMetric,
+  HttpMetricPoint,
+  HttpMetricRepository,
+  HttpPathRepository,
+  MetricQuery,
+  MetricSeriesBucket,
+  MetricSeriesQuery,
+  PaginationModel,
+  PathDefinition,
+  StoredAuthProvider,
+  StoredHttpPath,
+  TrackCallInput,
+} from '@open-rlb/nestjs-amqp';
+import { InMemoryCollection } from './in-memory-collection';
+
+/** True when a metric point matches the query's method/route/name + [from,to] time window. */
+function matchPoint(p: HttpMetricPoint, q: MetricQuery): boolean {
+  if (q.method && p.method !== q.method) return false;
+  if (q.route && p.route !== q.route) return false;
+  if (q.name && p.name !== q.name) return false;
+  if (q.from != null && p.ts < q.from) return false;
+  if (q.to != null && p.ts > q.to) return false;
+  return true;
+}
+
+/** Drops persistence-only fields (_id, enabled) from a stored doc. */
+function toPlain<T extends { _id?: string; enabled?: boolean }>(doc: T): Omit<T, '_id' | 'enabled'> {
+  const { _id, enabled, ...rest } = doc;
+  return rest;
+}
+
+@Injectable()
+export class InMemoryHttpPathRepository extends HttpPathRepository {
+  private readonly col = new InMemoryCollection<StoredHttpPath>();
+
+  async insert(model: StoredHttpPath): Promise<StoredHttpPath> { return this.col.insert(model); }
+  async findById(id: string): Promise<StoredHttpPath> { return this.col.findById(id)!; }
+  async findOne(filter: Record<string, any>): Promise<StoredHttpPath> { return this.col.findOne(filter)!; }
+  async updateById(id: string, model: StoredHttpPath): Promise<StoredHttpPath> { return this.col.updateById(id, model)!; }
+  async removeById(id: string): Promise<StoredHttpPath> { return this.col.removeById(id)!; }
+  async filterPaginated(filter: Record<string, any>, page?: number, limit?: number): Promise<PaginationModel<StoredHttpPath>> {
+    return this.col.paginate(filter, Number(page) || 1, Number(limit) || 10);
+  }
+
+  async listEnabled(): Promise<PathDefinition[]> {
+    return this.col.all()
+      .filter((p) => p.enabled !== false)
+      .map((p) => toPlain(p) as PathDefinition);
+  }
+
+  async filter(filter: Record<string, any>): Promise<StoredHttpPath[]> {
+    return this.col.filter(filter);
+  }
+}
+
+@Injectable()
+export class InMemoryAuthProviderRepository extends AuthProviderRepository {
+  // Storage keeps an internal _id (the collection's key); the public StoredAuthProvider has none.
+  private readonly col = new InMemoryCollection<StoredAuthProvider & { _id?: string }>();
+
+  async insert(model: StoredAuthProvider): Promise<StoredAuthProvider> { return this.col.insert(model); }
+  async findByName(name: string): Promise<StoredAuthProvider> { return this.col.findOne({ name })!; }
+  async findOne(filter: Record<string, any>): Promise<StoredAuthProvider> { return this.col.findOne(filter)!; }
+  async upsertByName(name: string, model: StoredAuthProvider): Promise<StoredAuthProvider> { return this.col.upsertOne({ name }, model); }
+  async removeByName(name: string): Promise<StoredAuthProvider> { return this.col.removeOne({ name })!; }
+  async filterPaginated(filter: Record<string, any>, page?: number, limit?: number): Promise<PaginationModel<StoredAuthProvider>> {
+    return this.col.paginate(filter, Number(page) || 1, Number(limit) || 10);
+  }
+
+  async listEnabled(): Promise<HandlerAuthConfig[]> {
+    return this.col.all()
+      .filter((p) => p.enabled !== false)
+      .map((p) => toPlain(p) as HandlerAuthConfig);
+  }
+}
+
+@Injectable()
+export class InMemoryHttpMetricRepository extends HttpMetricRepository {
+  private readonly col = new InMemoryCollection<HttpMetric>();
+  private readonly pointsCol = new InMemoryCollection<HttpMetricPoint>();
+
+  async increment(input: TrackCallInput): Promise<void> {
+    if (!input?.method || !input?.route) return;
+    const existing = this.col.findOne({ method: input.method, route: input.route });
+    const isError = (input.status ?? 0) >= 400;
+    if (!existing) {
+      this.col.insert({
+        method: input.method,
+        route: input.route,
+        name: input.name,
+        topic: input.topic,
+        action: input.action,
+        count: 1,
+        errorCount: isError ? 1 : 0,
+        lastStatus: input.status,
+        lastCalledAt: Date.now(),
+        totalDurationMs: input.durationMs || 0,
+      });
+      return;
+    }
+    this.col.updateById(existing._id!, {
+      name: input.name ?? existing.name,
+      topic: input.topic ?? existing.topic,
+      action: input.action ?? existing.action,
+      count: existing.count + 1,
+      errorCount: existing.errorCount + (isError ? 1 : 0),
+      lastStatus: input.status,
+      lastCalledAt: Date.now(),
+      totalDurationMs: existing.totalDurationMs + (input.durationMs || 0),
+    });
+  }
+
+  async list(route?: string): Promise<(HttpMetric & { avgDurationMs: number; })[]> {
+    const rows = route ? this.col.filter({ route }) : this.col.all();
+    return rows.map((m) => ({ ...m, avgDurationMs: m.count > 0 ? Math.round(m.totalDurationMs / m.count) : 0 }));
+  }
+
+  async record(point: HttpMetricPoint): Promise<void> {
+    if (!point?.method || !point?.route) return;
+    this.pointsCol.insert({ ...point, ts: point.ts ?? Date.now() });
+  }
+
+  async points(query: MetricQuery): Promise<HttpMetricPoint[]> {
+    const rows = this.pointsCol.all().filter((p) => matchPoint(p, query)).sort((a, b) => b.ts - a.ts);
+    return query.limit ? rows.slice(0, query.limit) : rows;
+  }
+
+  async series(query: MetricSeriesQuery): Promise<MetricSeriesBucket[]> {
+    const width = query.bucketMs > 0 ? query.bucketMs : 60_000;
+    const buckets = new Map<number, MetricSeriesBucket>();
+    for (const p of this.pointsCol.all()) {
+      if (!matchPoint(p, query)) continue;
+      const start = Math.floor(p.ts / width) * width;
+      let b = buckets.get(start);
+      if (!b) { b = { bucketStart: start, count: 0, errorCount: 0, totalDurationMs: 0, avgDurationMs: 0 }; buckets.set(start, b); }
+      b.count++;
+      if ((p.status ?? 0) >= 400) b.errorCount++;
+      const d = p.durationMs ?? 0;
+      b.totalDurationMs += d;
+      b.minDurationMs = b.minDurationMs == null ? d : Math.min(b.minDurationMs, d);
+      b.maxDurationMs = b.maxDurationMs == null ? d : Math.max(b.maxDurationMs, d);
+    }
+    const out = [...buckets.values()].sort((a, b) => a.bucketStart - b.bucketStart);
+    for (const b of out) b.avgDurationMs = b.count > 0 ? Math.round(b.totalDurationMs / b.count) : 0;
+    return out;
+  }
+}

package/schematics/nest-add/files/gateway-admin/src/modules/database/repository/route-sync.repository.ts

@@ -0,0 +1,15 @@
+import { Injectable } from '@nestjs/common';
+import { RouteSyncLogEntry, RouteSyncLogRepository } from '@open-rlb/nestjs-amqp';
+import { InMemoryCollection } from './in-memory-collection';
+
+/** In-RAM journal collection for route-sync events (added/updated/removed/collision/...). */
+@Injectable()
+export class InMemoryRouteSyncLogRepository extends RouteSyncLogRepository {
+  private readonly col = new InMemoryCollection<RouteSyncLogEntry>();
+
+  async insert(entry: RouteSyncLogEntry): Promise<RouteSyncLogEntry> { return this.col.insert(entry); }
+  async list(limit = 100): Promise<RouteSyncLogEntry[]> {
+    // newest first
+    return this.col.all().sort((a, b) => (b.ts || 0) - (a.ts || 0)).slice(0, limit);
+  }
+}

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 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,10 @@ 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`.