@open-rlb/nestjs-amqp 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-rlb/nestjs-amqp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "",
   "author": "Giuseppe Riolo <riolo.giuseppe@gmail.com>",
   "private": false,
@@ -37,19 +37,19 @@
     "jwks-rsa": "^4.0.1",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@angular-devkit/core": "^22.0.1",
     "@angular-devkit/schematics": "^22.0.1",
-    "@nestjs/mongoose": "^11.0.4",
-    "@types/js-yaml": "^4.0.9",
-    "mongoose": "^8.19.3",
     "@nestjs/cli": "^11.0.23",
+    "@nestjs/mongoose": "^11.0.4",
     "@nestjs/schematics": "^11.1.0",
     "@nestjs/testing": "^11.1.26",
     "@types/express": "^5.0.6",
     "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/multer": "^2.1.0",
     "@types/node": "^25.9.3",
     "@types/supertest": "^7.2.0",
@@ -61,6 +61,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
     "jest": "^30.4.2",
+    "mongoose": "^8.19.3",
     "prettier": "^3.8.4",
     "source-map-support": "^0.5.21",
     "supertest": "^7.2.2",

package/schematics/add-auth-provider/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { AddAuthProviderOptions } from './schema';
+export declare function main(options: AddAuthProviderOptions): Rule;

package/schematics/add-auth-provider/index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const schematic_prompt_util_1 = require("../utils/schematic-prompt.util");
+const yaml_config_util_1 = require("../utils/yaml-config.util");
+const TYPES = ['jwt', 'jwks', 'basic', 'str-compare', 'none'];
+const RELEVANT_FIELDS = {
+    jwt: ['issuer', 'algorithms', 'secret', 'audience', 'uidClaim', 'jwtMap'],
+    jwks: ['issuer', 'jwksUri', 'algorithms', 'audience', 'uidClaim', 'jwtMap', 'httpsAllowUnauthorized'],
+    basic: ['clientId', 'clientSecret', 'uidClaim'],
+    'str-compare': ['secret', 'uidClaim'],
+    none: [],
+};
+function main(options) {
+    return async (tree, context) => {
+        const flagsProvided = options.name !== undefined;
+        const prompts = (0, schematic_prompt_util_1.loadPrompts)(context, flagsProvided);
+        const name = options.name || (await (0, schematic_prompt_util_1.askText)(prompts, 'Auth-provider name?', ''));
+        if (!name) {
+            context.logger.error('[rlb-amqp] add-auth-provider: a name is required.');
+            return tree;
+        }
+        const type = options.type || (await (0, schematic_prompt_util_1.askSelect)(prompts, 'Provider type?', TYPES, 'jwks'));
+        const headerPrefix = options.headerPrefix ?? 'X-GTW-AUTH-';
+        const configPath = (0, yaml_config_util_1.findConfigYaml)(tree, options.config);
+        const { doc, existed } = (0, yaml_config_util_1.readConfigDoc)(tree, configPath);
+        if (!existed)
+            context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+        const candidates = {
+            uidClaim: options.uidClaim,
+            jwtMap: options.jwtMap,
+            algorithms: options.algorithms,
+            issuer: options.issuer,
+            jwksUri: options.jwksUri,
+            secret: options.secret,
+            audience: options.audience,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            httpsAllowUnauthorized: options.httpsAllowUnauthorized,
+        };
+        const item = { name, type, headerPrefix };
+        for (const field of RELEVANT_FIELDS[type]) {
+            if (candidates[field] !== undefined)
+                item[field] = candidates[field];
+        }
+        if (type === 'jwt' || type === 'jwks') {
+            if (!options.algorithms || options.algorithms.length === 0) {
+                context.logger.warn('[rlb-amqp] add-auth-provider: algorithms is REQUIRED for jwt/jwks — verification will be DENIED until set (algorithm-confusion guard).');
+            }
+            if (!options.jwtMap || options.jwtMap.length === 0) {
+                context.logger.warn('[rlb-amqp] add-auth-provider: without jwtMap no identity claims are forwarded (uidClaim still needed for the action gate).');
+            }
+        }
+        const outcome = (0, yaml_config_util_1.upsertSeqItemByKey)(doc, ['auth-providers'], 'name', item, { overwrite: options.overwrite });
+        (0, schematic_prompt_util_1.logOutcome)(context, `auth-provider '${name}'`, outcome);
+        (0, yaml_config_util_1.writeConfigDoc)(tree, configPath, doc);
+        return tree;
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/add-auth-provider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-auth-provider/index.ts"],"names":[],"mappings":"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"}

package/schematics/add-auth-provider/index.spec.ts

@@ -0,0 +1,83 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { parseDocument } from 'yaml';
+import { main } from './index';
+import { AddAuthProviderOptions } from './schema';
+
+/**
+ * Schematics are tested by invoking the factory Rule directly against a Tree, NOT via
+ * SchematicTestRunner (its testing entrypoint eagerly loads `ora`, an ESM-only module jest cannot
+ * transform here). Passing `name` makes `flagsProvided` true, so no interactive prompt is attempted.
+ */
+function makeCtx(warnings: string[] = []): SchematicContext {
+  return { logger: { info() {}, warn: (m: string) => warnings.push(m), error() {} } } as unknown as SchematicContext;
+}
+
+async function run(options: AddAuthProviderOptions, tree: Tree, ctx = makeCtx()): Promise<Tree> {
+  const rule = main(options) as Rule;
+  const result = await (rule as (t: Tree, c: SchematicContext) => Promise<Tree>)(tree, ctx);
+  return result || tree;
+}
+
+function read(tree: Tree, path = 'config/config.yaml'): string {
+  return tree.read(path)!.toString('utf-8');
+}
+function doc(tree: Tree) {
+  return parseDocument(read(tree));
+}
+function seedConfig(): Tree {
+  const tree = Tree.empty();
+  tree.create(
+    'config/config.yaml',
+    ['# my config', 'auth-providers:', '  - name: existing', '    type: basic', 'gateway: {}', ''].join('\n'),
+  );
+  return tree;
+}
+
+describe('add-auth-provider schematic', () => {
+  it('appends a jwks provider with only type-relevant fields, preserving comments', async () => {
+    const tree = await run(
+      {
+        name: 'keycloak',
+        type: 'jwks',
+        jwksUri: 'https://kc/realms/x/protocol/openid-connect/certs',
+        algorithms: ['RS256'],
+        jwtMap: ['sub:userId'],
+        uidClaim: 'sub',
+        clientSecret: 'should-not-appear',
+      },
+      seedConfig(),
+    );
+    const providers = doc(tree).getIn(['auth-providers']) as any;
+    expect(providers.items.map((i: any) => String(i.get('name')))).toEqual(['existing', 'keycloak']);
+    const kc = providers.items[1];
+    expect(String(kc.get('type'))).toBe('jwks');
+    expect(String(kc.get('headerPrefix'))).toBe('X-GTW-AUTH-');
+    expect(kc.get('jwksUri')).toBeDefined();
+    // clientSecret is irrelevant for jwks and must be filtered out.
+    expect(kc.get('clientSecret')).toBeUndefined();
+    expect(read(tree)).toContain('# my config');
+  });
+
+  it('is idempotent: re-adding the same provider leaves a single entry', async () => {
+    let tree = await run({ name: 'demo', type: 'basic', clientSecret: 'secret' }, seedConfig());
+    tree = await run({ name: 'demo', type: 'basic', clientSecret: 'secret' }, tree);
+    const providers = doc(tree).getIn(['auth-providers']) as any;
+    const names = providers.items.map((i: any) => String(i.get('name')));
+    expect(names.filter((n: string) => n === 'demo')).toHaveLength(1);
+  });
+
+  it('warns when a jwt/jwks provider is missing algorithms and jwtMap (fails-closed invariant)', async () => {
+    const warnings: string[] = [];
+    await run({ name: 'insecure', type: 'jwt', issuer: 'https://issuer' }, seedConfig(), makeCtx(warnings));
+    expect(warnings.some((w) => w.includes('algorithms is REQUIRED'))).toBe(true);
+    expect(warnings.some((w) => w.includes('without jwtMap'))).toBe(true);
+  });
+
+  it('creates config.yaml when it does not exist', async () => {
+    const tree = await run({ name: 'demo', type: 'basic', clientSecret: 'secret', uidClaim: 'USERID' }, Tree.empty());
+    expect(tree.exists('config/config.yaml')).toBe(true);
+    const providers = doc(tree).getIn(['auth-providers']) as any;
+    expect(String(providers.items[0].get('name'))).toBe('demo');
+    expect(String(providers.items[0].get('uidClaim'))).toBe('USERID');
+  });
+});

package/schematics/add-auth-provider/index.ts

@@ -0,0 +1,83 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { askSelect, askText, loadPrompts, logOutcome } from '../utils/schematic-prompt.util';
+import { findConfigYaml, readConfigDoc, upsertSeqItemByKey, writeConfigDoc } from '../utils/yaml-config.util';
+import { AddAuthProviderOptions, AuthProviderType } from './schema';
+
+const TYPES: readonly AuthProviderType[] = ['jwt', 'jwks', 'basic', 'str-compare', 'none'];
+
+/**
+ * Optional fields that make sense per verification strategy. A field is only emitted when it is BOTH
+ * relevant to the chosen type AND provided — so a `basic` provider never carries a stray `jwksUri`,
+ * and a token provider never carries `clientSecret`. `name`/`type`/`headerPrefix` are always written.
+ */
+const RELEVANT_FIELDS: Record<AuthProviderType, readonly string[]> = {
+  jwt: ['issuer', 'algorithms', 'secret', 'audience', 'uidClaim', 'jwtMap'],
+  jwks: ['issuer', 'jwksUri', 'algorithms', 'audience', 'uidClaim', 'jwtMap', 'httpsAllowUnauthorized'],
+  basic: ['clientId', 'clientSecret', 'uidClaim'],
+  'str-compare': ['secret', 'uidClaim'],
+  none: [],
+};
+
+/**
+ * `add-auth-provider <name>` — idempotent upsert of a top-level `auth-providers[]` entry,
+ * comment-preserving. The provider name is what gateway paths/events reference via `auth`.
+ * Only the fields relevant to the selected verification `type` are written (see RELEVANT_FIELDS).
+ */
+export function main(options: AddAuthProviderOptions): Rule {
+  return async (tree: Tree, context: SchematicContext) => {
+    const flagsProvided = options.name !== undefined;
+    const prompts = loadPrompts(context, flagsProvided);
+
+    const name = options.name || (await askText(prompts, 'Auth-provider name?', ''));
+    if (!name) {
+      context.logger.error('[rlb-amqp] add-auth-provider: a name is required.');
+      return tree;
+    }
+
+    const type = (options.type as AuthProviderType) || (await askSelect(prompts, 'Provider type?', TYPES, 'jwks'));
+    const headerPrefix = options.headerPrefix ?? 'X-GTW-AUTH-';
+
+    const configPath = findConfigYaml(tree, options.config);
+    const { doc, existed } = readConfigDoc(tree, configPath);
+    if (!existed) context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+
+    // All candidate optional values; the per-type filter below keeps only the relevant, defined ones.
+    const candidates: Record<string, unknown> = {
+      uidClaim: options.uidClaim,
+      jwtMap: options.jwtMap,
+      algorithms: options.algorithms,
+      issuer: options.issuer,
+      jwksUri: options.jwksUri,
+      secret: options.secret,
+      audience: options.audience,
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      httpsAllowUnauthorized: options.httpsAllowUnauthorized,
+    };
+
+    const item: Record<string, unknown> = { name, type, headerPrefix };
+    for (const field of RELEVANT_FIELDS[type]) {
+      if (candidates[field] !== undefined) item[field] = candidates[field];
+    }
+
+    // Fails-closed invariants for token providers: without these the gateway can't safely verify.
+    if (type === 'jwt' || type === 'jwks') {
+      if (!options.algorithms || options.algorithms.length === 0) {
+        context.logger.warn(
+          '[rlb-amqp] add-auth-provider: algorithms is REQUIRED for jwt/jwks — verification will be DENIED until set (algorithm-confusion guard).',
+        );
+      }
+      if (!options.jwtMap || options.jwtMap.length === 0) {
+        context.logger.warn(
+          '[rlb-amqp] add-auth-provider: without jwtMap no identity claims are forwarded (uidClaim still needed for the action gate).',
+        );
+      }
+    }
+
+    const outcome = upsertSeqItemByKey(doc, ['auth-providers'], 'name', item, { overwrite: options.overwrite });
+    logOutcome(context, `auth-provider '${name}'`, outcome);
+
+    writeConfigDoc(tree, configPath, doc);
+    return tree;
+  };
+}

package/schematics/add-auth-provider/schema.d.ts

@@ -0,0 +1,18 @@
+export type AuthProviderType = 'jwt' | 'jwks' | 'basic' | 'str-compare' | 'none';
+export interface AddAuthProviderOptions {
+    name?: string;
+    type?: AuthProviderType;
+    headerPrefix?: string;
+    uidClaim?: string;
+    jwtMap?: string[];
+    algorithms?: string[];
+    issuer?: string;
+    jwksUri?: string;
+    secret?: string;
+    audience?: string;
+    clientId?: string;
+    clientSecret?: string;
+    httpsAllowUnauthorized?: boolean;
+    overwrite?: boolean;
+    config?: string;
+}

package/schematics/add-auth-provider/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/schematics/add-auth-provider/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-auth-provider/schema.ts"],"names":[],"mappings":""}

package/schematics/add-auth-provider/schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "SchematicsRlbAmqpAddAuthProvider",
+  "title": "Add an auth-providers[] entry to config.yaml",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Provider name (the key gateway paths/events reference via auth).",
+      "x-prompt": "Auth-provider name?",
+      "$default": { "$source": "argv", "index": 0 }
+    },
+    "type": {
+      "type": "string",
+      "enum": ["jwt", "jwks", "basic", "str-compare", "none"],
+      "default": "jwks",
+      "description": "Verification strategy."
+    },
+    "headerPrefix": {
+      "type": "string",
+      "default": "X-GTW-AUTH-",
+      "description": "Prefix for the identity headers forwarded downstream."
+    },
+    "uidClaim": {
+      "type": "string",
+      "description": "Claim whose value becomes the authenticated userId (drives the ACL/action gate)."
+    },
+    "jwtMap": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Claim->header maps as src:dest (jwt/jwks)."
+    },
+    "algorithms": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Allowed signature algorithms (jwt/jwks) — REQUIRED to verify."
+    },
+    "issuer": { "type": "string", "description": "Expected token issuer (jwt/jwks)." },
+    "jwksUri": { "type": "string", "description": "JWKS endpoint to fetch signing keys from (jwks)." },
+    "secret": { "type": "string", "description": "HMAC/shared secret (jwt symmetric, or str-compare)." },
+    "audience": { "type": "string", "description": "Expected token audience (jwt/jwks)." },
+    "clientId": { "type": "string", "description": "Client id (basic)." },
+    "clientSecret": { "type": "string", "description": "Client secret / password (basic)." },
+    "httpsAllowUnauthorized": {
+      "type": "boolean",
+      "description": "Accept self-signed TLS when fetching the JWKS (jwks) — DEV ONLY."
+    },
+    "overwrite": {
+      "type": "boolean",
+      "default": false,
+      "description": "Update the entry if it already exists (default: leave it untouched)."
+    },
+    "config": {
+      "type": "string",
+      "description": "Path to config.yaml (default: auto-detected)."
+    }
+  },
+  "required": []
+}

package/schematics/add-auth-provider/schema.ts

@@ -0,0 +1,35 @@
+/** Auth-provider verification strategy. Mirrors HandlerAuthConfig['type']. */
+export type AuthProviderType = 'jwt' | 'jwks' | 'basic' | 'str-compare' | 'none';
+
+export interface AddAuthProviderOptions {
+  /** Provider name (the key gateway paths/events reference via `auth`). Prompted when omitted. */
+  name?: string;
+  /** Verification strategy. Default: jwks. */
+  type?: AuthProviderType;
+  /** Prefix for the identity headers the gateway forwards downstream. Default: X-GTW-AUTH-. */
+  headerPrefix?: string;
+  /** Claim whose value becomes the authenticated userId (drives the ACL/action gate). */
+  uidClaim?: string;
+  /** Claim→header maps as `src:dest` (jwt/jwks): which token claims are forwarded downstream. */
+  jwtMap?: string[];
+  /** Allowed signature algorithms (jwt/jwks) — REQUIRED to verify (algorithm-confusion guard). */
+  algorithms?: string[];
+  /** Expected token issuer (jwt/jwks). */
+  issuer?: string;
+  /** JWKS endpoint to fetch signing keys from (jwks). */
+  jwksUri?: string;
+  /** HMAC/shared secret (jwt with symmetric alg, or str-compare). */
+  secret?: string;
+  /** Expected token audience (jwt/jwks). */
+  audience?: string;
+  /** Client id (basic). */
+  clientId?: string;
+  /** Client secret / password (basic). */
+  clientSecret?: string;
+  /** Accept self-signed TLS when fetching the JWKS (jwks) — DEV ONLY. */
+  httpsAllowUnauthorized?: boolean;
+  /** Update the entry when it already exists (default: leave it untouched). */
+  overwrite?: boolean;
+  /** Path to config.yaml (default: auto-detected, typically config/config.yaml). */
+  config?: string;
+}

package/schematics/add-exchange/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { AddExchangeOptions } from './schema';
+export declare function main(options: AddExchangeOptions): Rule;

package/schematics/add-exchange/index.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const broker_yaml_util_1 = require("../utils/broker-yaml.util");
+const schematic_prompt_util_1 = require("../utils/schematic-prompt.util");
+const yaml_config_util_1 = require("../utils/yaml-config.util");
+const TYPES = ['direct', 'topic', 'fanout', 'headers'];
+function main(options) {
+    return async (tree, context) => {
+        const flagsProvided = options.name !== undefined;
+        const prompts = (0, schematic_prompt_util_1.loadPrompts)(context, flagsProvided);
+        const name = options.name || (await (0, schematic_prompt_util_1.askText)(prompts, 'Exchange name?', ''));
+        if (!name) {
+            context.logger.error('[rlb-amqp] add-exchange: a name is required.');
+            return tree;
+        }
+        const type = options.type || (await (0, schematic_prompt_util_1.askSelect)(prompts, 'Exchange type?', TYPES, 'direct'));
+        const configPath = (0, yaml_config_util_1.findConfigYaml)(tree, options.config);
+        const { doc, existed } = (0, yaml_config_util_1.readConfigDoc)(tree, configPath);
+        if (!existed)
+            context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+        const outcome = (0, broker_yaml_util_1.ensureExchange)(doc, {
+            name,
+            type,
+            createExchangeIfNotExists: options.createIfNotExists ?? true,
+            durable: options.durable ?? true,
+            autoDelete: options.autoDelete ?? false,
+            internal: options.internal ?? false,
+        }, { overwrite: options.overwrite });
+        (0, schematic_prompt_util_1.logOutcome)(context, `exchange '${name}'`, outcome);
+        const withQueue = options.withQueue ?? (await (0, schematic_prompt_util_1.askConfirm)(prompts, `Create a queue bound to '${name}'?`, false));
+        if (withQueue) {
+            const queueName = options.queueName || (await (0, schematic_prompt_util_1.askText)(prompts, 'Queue name?', name));
+            const needsRoutingKey = type === 'topic';
+            const routingKey = needsRoutingKey ? options.routingKey || queueName : options.routingKey;
+            const qOutcome = (0, broker_yaml_util_1.ensureQueue)(doc, {
+                name: queueName,
+                exchange: name,
+                routingKey,
+                createQueueIfNotExists: true,
+                durable: true,
+            });
+            (0, schematic_prompt_util_1.logOutcome)(context, `queue '${queueName}'`, qOutcome);
+        }
+        (0, yaml_config_util_1.writeConfigDoc)(tree, configPath, doc);
+        return tree;
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/add-exchange/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-exchange/index.ts"],"names":[],"mappings":";;AAcA,oBAkDC;AA/DD,gEAAsF;AACtF,0EAAyG;AACzG,gEAA0F;AAG1F,MAAM,KAAK,GAA4B,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAQhF,SAAgB,IAAI,CAAC,OAA2B;IAC9C,OAAO,KAAK,EAAE,IAAU,EAAE,OAAyB,EAAE,EAAE;QACrD,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC;QACjD,MAAM,OAAO,GAAG,IAAA,mCAAW,EAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAEpD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,IAAA,+BAAO,EAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAI,OAAO,CAAC,IAAqB,IAAI,CAAC,MAAM,IAAA,iCAAS,EAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QAE7G,MAAM,UAAU,GAAG,IAAA,iCAAc,EAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACxD,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,IAAA,gCAAa,EAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,UAAU,2BAA2B,CAAC,CAAC;QAEvF,MAAM,OAAO,GAAG,IAAA,iCAAc,EAC5B,GAAG,EACH;YACE,IAAI;YACJ,IAAI;YACJ,yBAAyB,EAAE,OAAO,CAAC,iBAAiB,IAAI,IAAI;YAC5D,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;YAChC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,KAAK;YACvC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;SACpC,EACD,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CACjC,CAAC;QACF,IAAA,kCAAU,EAAC,OAAO,EAAE,aAAa,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC;QAGnD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,MAAM,IAAA,kCAAU,EAAC,OAAO,EAAE,4BAA4B,IAAI,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAChH,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,MAAM,IAAA,+BAAO,EAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC;YACrF,MAAM,eAAe,GAAG,IAAI,KAAK,OAAO,CAAC;YACzC,MAAM,UAAU,GAAG,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;YAC1F,MAAM,QAAQ,GAAG,IAAA,8BAAW,EAAC,GAAG,EAAE;gBAChC,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,IAAI;gBACd,UAAU;gBACV,sBAAsB,EAAE,IAAI;gBAC5B,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;YACH,IAAA,kCAAU,EAAC,OAAO,EAAE,UAAU,SAAS,GAAG,EAAE,QAAQ,CAAC,CAAC;QACxD,CAAC;QAED,IAAA,iCAAc,EAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}

package/schematics/add-exchange/index.spec.ts

@@ -0,0 +1,65 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { parseDocument } from 'yaml';
+import { main } from './index';
+import { AddExchangeOptions } from './schema';
+
+/**
+ * Schematics are tested by invoking the factory Rule directly against a Tree, NOT via
+ * SchematicTestRunner (its testing entrypoint eagerly loads `ora`, an ESM-only module jest cannot
+ * transform here). Passing `name` makes `flagsProvided` true, so no interactive prompt is attempted.
+ */
+const ctx = { logger: { info() {}, warn() {}, error() {} } } as unknown as SchematicContext;
+
+async function run(options: AddExchangeOptions, tree: Tree): Promise<Tree> {
+  const rule = main(options) as Rule;
+  const result = await (rule as (t: Tree, c: SchematicContext) => Promise<Tree>)(tree, ctx);
+  return result || tree;
+}
+
+function read(tree: Tree, path = 'config/config.yaml'): string {
+  return tree.read(path)!.toString('utf-8');
+}
+function doc(tree: Tree) {
+  return parseDocument(read(tree));
+}
+function seedConfig(): Tree {
+  const tree = Tree.empty();
+  tree.create(
+    'config/config.yaml',
+    ['# my config', 'broker:', '  exchanges:', '    - name: rlb', '      type: direct', 'topics: []', ''].join('\n'),
+  );
+  return tree;
+}
+
+describe('add-exchange schematic', () => {
+  it('appends a new exchange, preserving the existing one and comments', async () => {
+    const tree = await run({ name: 'events', type: 'fanout' }, seedConfig());
+    const exchanges = doc(tree).getIn(['broker', 'exchanges']) as any;
+    expect(exchanges.items.map((i: any) => String(i.get('name')))).toEqual(['rlb', 'events']);
+    expect(String(exchanges.items[1].get('type'))).toBe('fanout');
+    expect(read(tree)).toContain('# my config');
+  });
+
+  it('is idempotent: re-adding the same exchange leaves a single entry', async () => {
+    let tree = await run({ name: 'events', type: 'fanout' }, seedConfig());
+    tree = await run({ name: 'events', type: 'fanout' }, tree);
+    const exchanges = doc(tree).getIn(['broker', 'exchanges']) as any;
+    const names = exchanges.items.map((i: any) => String(i.get('name')));
+    expect(names.filter((n: string) => n === 'events')).toHaveLength(1);
+  });
+
+  it('with withQueue creates a bound queue (routingKey only for topic exchanges)', async () => {
+    const tree = await run({ name: 'jobs', type: 'topic', withQueue: true, queueName: 'jobs-q' }, seedConfig());
+    const queue = (doc(tree).getIn(['broker', 'queues']) as any).items[0];
+    expect(String(queue.get('name'))).toBe('jobs-q');
+    expect(String(queue.get('exchange'))).toBe('jobs');
+    expect(String(queue.get('routingKey'))).toBe('jobs-q');
+  });
+
+  it('creates config.yaml when it does not exist', async () => {
+    const tree = await run({ name: 'rlb', type: 'direct' }, Tree.empty());
+    expect(tree.exists('config/config.yaml')).toBe(true);
+    const exchanges = doc(tree).getIn(['broker', 'exchanges']) as any;
+    expect(String(exchanges.items[0].get('name'))).toBe('rlb');
+  });
+});

package/schematics/add-exchange/index.ts

@@ -0,0 +1,65 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { ensureExchange, ensureQueue, ExchangeType } from '../utils/broker-yaml.util';
+import { askConfirm, askSelect, askText, loadPrompts, logOutcome } from '../utils/schematic-prompt.util';
+import { findConfigYaml, readConfigDoc, writeConfigDoc } from '../utils/yaml-config.util';
+import { AddExchangeOptions } from './schema';
+
+const TYPES: readonly ExchangeType[] = ['direct', 'topic', 'fanout', 'headers'];
+
+/**
+ * `add-exchange <name>` — idempotent upsert of a `broker.exchanges[]` entry, comment-preserving.
+ * When interactive it also offers to create a queue bound to the exchange (default queue name =
+ * exchange name). Creating that queue calls the ensureQueue DATA helper directly — NOT the
+ * add-queue schematic — so there is no "create exchange? → create queue? → …" prompt ping-pong.
+ */
+export function main(options: AddExchangeOptions): Rule {
+  return async (tree: Tree, context: SchematicContext) => {
+    const flagsProvided = options.name !== undefined;
+    const prompts = loadPrompts(context, flagsProvided);
+
+    const name = options.name || (await askText(prompts, 'Exchange name?', ''));
+    if (!name) {
+      context.logger.error('[rlb-amqp] add-exchange: a name is required.');
+      return tree;
+    }
+
+    const type = (options.type as ExchangeType) || (await askSelect(prompts, 'Exchange type?', TYPES, 'direct'));
+
+    const configPath = findConfigYaml(tree, options.config);
+    const { doc, existed } = readConfigDoc(tree, configPath);
+    if (!existed) context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+
+    const outcome = ensureExchange(
+      doc,
+      {
+        name,
+        type,
+        createExchangeIfNotExists: options.createIfNotExists ?? true,
+        durable: options.durable ?? true,
+        autoDelete: options.autoDelete ?? false,
+        internal: options.internal ?? false,
+      },
+      { overwrite: options.overwrite },
+    );
+    logOutcome(context, `exchange '${name}'`, outcome);
+
+    // Offer to bind a queue. In non-interactive mode this fires only when --with-queue was passed.
+    const withQueue = options.withQueue ?? (await askConfirm(prompts, `Create a queue bound to '${name}'?`, false));
+    if (withQueue) {
+      const queueName = options.queueName || (await askText(prompts, 'Queue name?', name));
+      const needsRoutingKey = type === 'topic';
+      const routingKey = needsRoutingKey ? options.routingKey || queueName : options.routingKey;
+      const qOutcome = ensureQueue(doc, {
+        name: queueName,
+        exchange: name,
+        routingKey,
+        createQueueIfNotExists: true,
+        durable: true,
+      });
+      logOutcome(context, `queue '${queueName}'`, qOutcome);
+    }
+
+    writeConfigDoc(tree, configPath, doc);
+    return tree;
+  };
+}

package/schematics/add-exchange/schema.d.ts

@@ -0,0 +1,14 @@
+import { ExchangeType } from '../utils/broker-yaml.util';
+export interface AddExchangeOptions {
+    name?: string;
+    type?: ExchangeType;
+    createIfNotExists?: boolean;
+    durable?: boolean;
+    autoDelete?: boolean;
+    internal?: boolean;
+    withQueue?: boolean;
+    queueName?: string;
+    routingKey?: string;
+    overwrite?: boolean;
+    config?: string;
+}

package/schematics/add-exchange/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/schematics/add-exchange/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-exchange/schema.ts"],"names":[],"mappings":""}