nestjs-ddd-cli 3.2.2 → 3.3.1

package/dist/templates/recipes/external-projection-worker/worker.ts.hbs

@@ -0,0 +1,296 @@
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import {
+  Inject,
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+  OnApplicationShutdown,
+} from '@nestjs/common';
+import { ExternalProjectionStore } from './external-projection-store';
+import {
+  ClaimedExternalProjection,
+  ExternalProjectionDispositionError,
+  ExternalProjectionExecutionResult,
+  ExternalProjectionFailureDisposition,
+  ExternalProjectionHandler,
+  ExternalProjectionWorkerOptions,
+} from './external-projection-worker.types';
+
+export const EXTERNAL_PROJECTION_HANDLER = Symbol('EXTERNAL_PROJECTION_HANDLER');
+export const EXTERNAL_PROJECTION_WORKER_OPTIONS = Symbol('EXTERNAL_PROJECTION_WORKER_OPTIONS');
+const LEASE_LOST = Symbol('LEASE_LOST');
+
+function boundedInteger(value: number, name: string, minimum: number, maximum: number): number {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`${name} must be an integer between ${minimum} and ${maximum}`);
+  }
+  return value;
+}
+
+function projectionName(value: string): string {
+  const normalized = value.trim();
+  if (
+    normalized.length < 1 ||
+    normalized.length > 120 ||
+    !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(normalized)
+  ) {
+    throw new Error('projectionName is invalid');
+  }
+  return normalized;
+}
+
+export function validateExternalProjectionWorkerOptions(
+  options: ExternalProjectionWorkerOptions,
+): Readonly<ExternalProjectionWorkerOptions> {
+  if (typeof options.enabled !== 'boolean') throw new Error('enabled must be a boolean');
+  const validated = {
+    projectionName: projectionName(options.projectionName),
+    enabled: options.enabled,
+    pollIntervalMs: boundedInteger(options.pollIntervalMs, 'pollIntervalMs', 50, 3_600_000),
+    batchSize: boundedInteger(options.batchSize, 'batchSize', 1, 1_000),
+    leaseSeconds: boundedInteger(options.leaseSeconds, 'leaseSeconds', 3, 3_600),
+    maxAttempts: boundedInteger(options.maxAttempts, 'maxAttempts', 1, 100),
+    retryBaseMs: boundedInteger(options.retryBaseMs, 'retryBaseMs', 100, 86_400_000),
+    retryMaxMs: boundedInteger(options.retryMaxMs, 'retryMaxMs', 100, 604_800_000),
+  };
+  if (validated.retryMaxMs < validated.retryBaseMs) {
+    throw new Error('retryMaxMs must be greater than or equal to retryBaseMs');
+  }
+  return Object.freeze(validated);
+}
+
+function validErrorCode(value: string): boolean {
+  return /^[A-Z][A-Z0-9_]{0,159}$/.test(value);
+}
+
+function normalizeExecutionResult(value: unknown): ExternalProjectionExecutionResult {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { disposition: 'blocked', errorCode: 'INVALID_HANDLER_RESULT' };
+  }
+  const record = value as Record<string, unknown>;
+  if (record['disposition'] === 'applied') {
+    const resultReference = record['resultReference'];
+    if (resultReference !== undefined && typeof resultReference !== 'string') {
+      return { disposition: 'blocked', errorCode: 'INVALID_HANDLER_RESULT' };
+    }
+    const normalizedReference = resultReference?.trim();
+    if (
+      resultReference !== undefined &&
+      (!normalizedReference ||
+        normalizedReference.length > 500 ||
+        /[\u0000-\u001f\u007f]/.test(normalizedReference))
+    ) {
+      return { disposition: 'blocked', errorCode: 'INVALID_HANDLER_RESULT_REFERENCE' };
+    }
+    return {
+      disposition: 'applied',
+      ...(normalizedReference === undefined ? {} : { resultReference: normalizedReference }),
+    };
+  }
+  const disposition = record['disposition'];
+  if (
+    typeof disposition !== 'string' ||
+    !['retry_wait', 'uncertain', 'blocked'].includes(disposition) ||
+    typeof record['errorCode'] !== 'string' ||
+    (record['retryAfterMs'] !== undefined && typeof record['retryAfterMs'] !== 'number')
+  ) {
+    return { disposition: 'blocked', errorCode: 'INVALID_HANDLER_RESULT' };
+  }
+  return {
+    disposition: disposition as ExternalProjectionFailureDisposition,
+    errorCode: record['errorCode'],
+    ...(record['retryAfterMs'] === undefined
+      ? {}
+      : { retryAfterMs: record['retryAfterMs'] as number }),
+  };
+}
+
+@Injectable()
+export class ExternalProjectionWorker implements OnApplicationBootstrap, OnApplicationShutdown {
+  private readonly logger = new Logger(ExternalProjectionWorker.name);
+  private readonly workerId = `${hostname()}:${process.pid}:${randomUUID()}`;
+  private readonly options: Readonly<ExternalProjectionWorkerOptions>;
+  private timer?: NodeJS.Timeout;
+  private activeRun?: Promise<number>;
+  private stopping = false;
+
+  constructor(
+    private readonly store: ExternalProjectionStore,
+    @Inject(EXTERNAL_PROJECTION_HANDLER) private readonly handler: ExternalProjectionHandler,
+    @Inject(EXTERNAL_PROJECTION_WORKER_OPTIONS) options: ExternalProjectionWorkerOptions,
+  ) {
+    this.options = validateExternalProjectionWorkerOptions(options);
+  }
+
+  onApplicationBootstrap(): void {
+    if (!this.options.enabled || this.stopping) return;
+    this.scheduleRun();
+    this.timer = setInterval(() => this.scheduleRun(), this.options.pollIntervalMs);
+    this.timer.unref();
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    this.stopping = true;
+    if (this.timer) clearInterval(this.timer);
+    await this.activeRun;
+  }
+
+  runOnce(): Promise<number> {
+    if (this.stopping) return Promise.resolve(0);
+    this.activeRun ??= this.runBatch().finally(() => {
+      this.activeRun = undefined;
+    });
+    return this.activeRun;
+  }
+
+  private async runBatch(): Promise<number> {
+    let processed = 0;
+    while (!this.stopping && processed < this.options.batchSize) {
+      const operation = await this.store.claimNext(
+        this.options.projectionName,
+        this.workerId,
+        this.options.leaseSeconds,
+        this.options.maxAttempts,
+      );
+      if (!operation) break;
+      processed += 1;
+      await this.process(operation);
+    }
+    return processed;
+  }
+
+  private async process(operation: ClaimedExternalProjection): Promise<void> {
+    let result: ExternalProjectionExecutionResult;
+    try {
+      const execution = await this.executeWithLeaseRenewal(operation);
+      if (execution === LEASE_LOST) return;
+      result = normalizeExecutionResult(execution);
+    } catch (error) {
+      if (error instanceof ExternalProjectionDispositionError) {
+        result = {
+          disposition: error.disposition,
+          errorCode: error.code,
+          retryAfterMs: error.retryAfterMs,
+        };
+      } else {
+        result = { disposition: 'uncertain', errorCode: 'UNEXPECTED_EXECUTION_FAILURE' };
+      }
+    }
+
+    if (result.disposition === 'applied') {
+      if (!(await this.store.markApplied(operation, result.resultReference))) {
+        this.logLeaseLost(operation.id);
+      }
+      return;
+    }
+
+    const normalized = this.normalizeFailure(
+      result,
+      operation.attemptCount,
+      operation.reconciliationRequired,
+    );
+    const nextAttemptAt =
+      normalized.disposition === 'blocked'
+        ? undefined
+        : new Date(Date.now() + normalized.retryAfterMs);
+    if (
+      !(await this.store.markFailure(operation, {
+        disposition: normalized.disposition,
+        errorCode: normalized.errorCode,
+        nextAttemptAt,
+      }))
+    ) {
+      this.logLeaseLost(operation.id);
+    }
+  }
+
+  private async executeWithLeaseRenewal(operation: ClaimedExternalProjection): Promise<unknown> {
+    let leaseValid = true;
+    let stopped = false;
+    let renewal: Promise<void> = Promise.resolve();
+    const renew = (): void => {
+      renewal = renewal.then(async () => {
+        if (stopped || !leaseValid) return;
+        try {
+          leaseValid = await this.store.renewLease(operation, this.options.leaseSeconds);
+        } catch {
+          leaseValid = false;
+        }
+      });
+    };
+    const interval = setInterval(
+      renew,
+      Math.max(1_000, Math.floor((this.options.leaseSeconds * 1_000) / 3)),
+    );
+    interval.unref();
+    try {
+      const result = operation.reconciliationRequired
+        ? await this.handler.reconcile(operation)
+        : await this.handler.execute(operation);
+      stopped = true;
+      clearInterval(interval);
+      await renewal;
+      if (!leaseValid || !(await this.store.renewLease(operation, this.options.leaseSeconds))) {
+        this.logLeaseLost(operation.id);
+        return LEASE_LOST;
+      }
+      return result;
+    } finally {
+      stopped = true;
+      clearInterval(interval);
+      await renewal;
+    }
+  }
+
+  private normalizeFailure(
+    result: Exclude<ExternalProjectionExecutionResult, { disposition: 'applied' }>,
+    attemptCount: number,
+    reconciliationRequired: boolean,
+  ): {
+    disposition: ExternalProjectionFailureDisposition;
+    errorCode: string;
+    retryAfterMs: number;
+  } {
+    if (!validErrorCode(result.errorCode)) {
+      return { disposition: 'blocked', errorCode: 'INVALID_HANDLER_ERROR_CODE', retryAfterMs: 0 };
+    }
+    if (result.disposition === 'blocked' || attemptCount >= this.options.maxAttempts) {
+      return { disposition: 'blocked', errorCode: result.errorCode, retryAfterMs: 0 };
+    }
+    const disposition =
+      reconciliationRequired && result.disposition === 'retry_wait'
+        ? 'uncertain'
+        : result.disposition;
+    const fallback = Math.min(
+      this.options.retryMaxMs,
+      this.options.retryBaseMs * 2 ** Math.max(0, Math.min(20, attemptCount - 1)),
+    );
+    const requested = result.retryAfterMs ?? fallback;
+    if (
+      !Number.isSafeInteger(requested) ||
+      requested < 100 ||
+      requested > this.options.retryMaxMs
+    ) {
+      return { disposition: 'blocked', errorCode: 'INVALID_HANDLER_RETRY_DELAY', retryAfterMs: 0 };
+    }
+    return {
+      disposition,
+      errorCode: result.errorCode,
+      retryAfterMs: requested,
+    };
+  }
+
+  private scheduleRun(): void {
+    if (this.stopping) return;
+    void this.runOnce().catch(() => {
+      this.logger.error('External projection poll failed');
+    });
+  }
+
+  private logLeaseLost(operationId: string): void {
+    this.logger.warn(
+      `External projection ${operationId} was not completed because its lease changed`,
+    );
+  }
+}

package/dist/templates/recipes/kafka-consumer/README.md.hbs

@@ -0,0 +1,50 @@
+# Kafka transactional consumer
+
+Generated by `ddd recipe kafka-consumer`. Independent of Relay/Pulsar:
+this recipe does not replace an existing outbox or enable a live consumer.
+
+## Integrate
+
+1. Install `kafkajs`, `typeorm` and `@nestjs/common` in the consuming application.
+2. Review/register the migration in the existing runner before enabling consumption.
+3. Generate a business handler with `ddd generate service`. Implement
+   `KafkaTransactionalHandler`, declare/export it in its owning Nest module,
+   then use `KafkaConsumerModule.register(options, Handler, [HandlerOwnerModule])`.
+   Do not redeclare the handler provider in the consumer module.
+4. Supply KafkaConfig from validated application configuration, with TLS/SASL
+   where required. Never embed credentials. Set explicit topics, a stable group
+   per independently maintained projection and a deliberate `fromBeginning` value.
+5. Enable Nest shutdown hooks. Keep database handlers within the session timeout.
+
+## Debezium contract
+
+Commit domain state and outbox together. Debezium's Outbox Event Router emits
+the durable event ID as an `id` header (`table.field.event.id=id`). Preserve
+aggregate ID as the record key. Prove envelope/header mapping against actual
+producer output; do not assume registry declarations determine serialization.
+
+The handler owns payload decoding, schema validation, tenant binding and source
+revision enforcement. Kafka facts never grant access to protected data. Keep
+clinical documents in their owner, not in a cross-service projection.
+
+## Guarantees and limits
+
+Receipt and handler changes share a database transaction; acknowledgement follows
+commit. Duplicate IDs with unchanged payload skip the handler; changed content
+fails closed. Keep receipts for the entire replay horizon. Offsets use BigInt.
+
+This is NOT exactly-once external delivery. Do not call HTTP/payment/email from
+the transaction. Append a domain outbox intent instead, with business replay
+fences. Do not use this receipt as a cached authorization decision.
+
+Malformed/poison messages stop progress instead of disappearing. Before enabling
+production, wire crash/lag alerts and the application's owned quarantine/replay
+policy. Never acknowledge rejected events without durably recording their reason.
+Broker connection retries are bounded; handler recovery needs operator visibility.
+
+Prove real PostgreSQL/Kafka migration reversal, concurrent duplicate, rollback,
+commit-before-ack crash, rebalance, out-of-order revision, poison and shutdown.
+Define initial backfill; broker retention is not a backup. A healthy HTTP API
+does not prove healthy consumption.
+
+Reference: https://kafka.js.org/docs/consuming

package/dist/templates/recipes/kafka-consumer/kafka-consumer.ts.hbs

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import {
+  DynamicModule, Inject, Injectable, Module, ModuleMetadata,
+  OnApplicationBootstrap, OnApplicationShutdown, Type,
+} from '@nestjs/common';
+import { Consumer, EachMessagePayload, Kafka, KafkaConfig } from 'kafkajs';
+import { DataSource, EntityManager } from 'typeorm';
+
+export const KAFKA_CONSUMER_OPTIONS = Symbol('KAFKA_CONSUMER_OPTIONS');
+export const KAFKA_TRANSACTIONAL_HANDLER = Symbol('KAFKA_TRANSACTIONAL_HANDLER');
+
+export interface KafkaConsumerOptions {
+  kafka: KafkaConfig;
+  groupId: string;
+  topics: string[];
+  fromBeginning: boolean;
+}
+
+export interface KafkaTransactionalHandler {
+  /** Validate contracts/revisions; use only this transaction. External effects belong in an outbox. */
+  handle(message: EachMessagePayload, manager: EntityManager): Promise<void>;
+}
+
+@Injectable()
+export class KafkaMessageProcessor {
+  constructor(
+    private readonly dataSource: DataSource,
+    @Inject(KAFKA_CONSUMER_OPTIONS) private readonly options: KafkaConsumerOptions,
+    @Inject(KAFKA_TRANSACTIONAL_HANDLER) private readonly handler: KafkaTransactionalHandler,
+  ) {}
+
+  async process(input: EachMessagePayload): Promise<void> {
+    const { message, topic } = input;
+    const rawId = message.headers?.id;
+    const id = Array.isArray(rawId) ? undefined : rawId?.toString();
+    if (!id || !/^[A-Za-z0-9._:-]{1,200}$/.test(id)) {
+      throw new Error('Kafka event requires a single stable outbox id header');
+    }
+    if (!message.key?.length || !message.value?.length || message.value.length > 1048576) {
+      throw new Error('Kafka event requires an aggregate key and bounded non-empty payload');
+    }
+    if (!this.options.topics.includes(topic)) throw new Error('Unexpected Kafka topic');
+    const hash = createHash('sha256')
+      .update(JSON.stringify([topic, message.key.toString('base64'), message.value.toString('base64')]))
+      .digest('hex');
+    await this.dataSource.transaction(async (manager) => {
+      const inserted = await manager.query(
+        'INSERT INTO kafka_consumer_receipts (consumer_id, event_id, payload_hash) ' +
+        'VALUES ($1, $2, $3) ON CONFLICT (consumer_id, event_id) DO NOTHING RETURNING event_id',
+        [this.options.groupId, id, hash],
+      ) as Array<{ event_id: string }>;
+      if (inserted.length === 0) {
+        const existing = await manager.query(
+          'SELECT payload_hash FROM kafka_consumer_receipts WHERE consumer_id = $1 AND event_id = $2',
+          [this.options.groupId, id],
+        ) as Array<{ payload_hash: string }>;
+        if (existing.length !== 1 || existing[0]?.payload_hash !== hash) {
+          throw new Error('Kafka event identity conflict');
+        }
+        return;
+      }
+      await this.handler.handle(input, manager);
+    });
+  }
+}
+
+@Injectable()
+export class KafkaConsumerLifecycle implements OnApplicationBootstrap, OnApplicationShutdown {
+  private consumer?: Consumer;
+
+  constructor(
+    @Inject(KAFKA_CONSUMER_OPTIONS) private readonly options: KafkaConsumerOptions,
+    private readonly processor: KafkaMessageProcessor,
+  ) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    if (!/^[A-Za-z0-9._-]{1,200}$/.test(this.options.groupId) ||
+        this.options.topics.length === 0 ||
+        this.options.topics.some(topic => !/^[A-Za-z0-9._-]{1,249}$/.test(topic)) ||
+        typeof this.options.fromBeginning !== 'boolean') {
+      throw new Error('Kafka consumer requires explicit group, topics and replay policy');
+    }
+    const consumer = new Kafka(this.options.kafka).consumer({
+      groupId: this.options.groupId,
+      allowAutoTopicCreation: false,
+      retry: { retries: 5 },
+    });
+    this.consumer = consumer;
+    try {
+      await consumer.connect();
+      await consumer.subscribe({ topics: this.options.topics, fromBeginning: this.options.fromBeginning });
+      await consumer.run({
+        autoCommit: false,
+        partitionsConsumedConcurrently: 1,
+        eachMessage: async (input) => {
+          await this.processor.process(input);
+          await input.heartbeat();
+          await consumer.commitOffsets([{
+            topic: input.topic,
+            partition: input.partition,
+            offset: (BigInt(input.message.offset) + 1n).toString(),
+          }]);
+        },
+      });
+    } catch (error) {
+      await consumer.disconnect();
+      throw error;
+    }
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await this.consumer?.stop();
+    await this.consumer?.disconnect();
+  }
+}
+
+@Module({})
+export class KafkaConsumerModule {
+  static register(
+    options: KafkaConsumerOptions,
+    handler: Type<KafkaTransactionalHandler>,
+    imports: ModuleMetadata['imports'],
+  ): DynamicModule {
+    return {
+      module: KafkaConsumerModule,
+      imports,
+      providers: [
+        { provide: KAFKA_CONSUMER_OPTIONS, useValue: options },
+        { provide: KAFKA_TRANSACTIONAL_HANDLER, useExisting: handler },
+        KafkaMessageProcessor,
+        KafkaConsumerLifecycle,
+      ],
+    };
+  }
+}

package/dist/templates/recipes/kafka-consumer/migration.ts.hbs

@@ -0,0 +1,17 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class KafkaConsumerReceipts1788600000000 implements MigrationInterface {
+  async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`CREATE TABLE kafka_consumer_receipts (
+      consumer_id varchar(200) NOT NULL,
+      event_id varchar(200) NOT NULL,
+      payload_hash char(64) NOT NULL,
+      processed_at timestamptz NOT NULL DEFAULT now(),
+      PRIMARY KEY (consumer_id, event_id)
+    )`);
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('DROP TABLE kafka_consumer_receipts');
+  }
+}

package/dist/templates/recipes/oauth2-client-credentials/README.md.hbs

@@ -0,0 +1,40 @@
+# OAuth2 client credentials
+
+Generated by `ddd recipe oauth2-client-credentials --dry-run`, then the same
+command without `--dry-run`. This adds a dependency-free grant client, Nest
+sync/async module, tests, and the exact bounded JSON HTTP primitive used by the
+introspection recipe. Both recipes refuse existing changed output; do not delete
+adapted files to force an upgrade. No AppModule registration or permission grant.
+
+`OAuth2ClientCredentialsClient` takes a fixed HTTPS `tokenUrl`, `clientId`,
+`clientSecret`, optional `scopes`, and bounded timeout/response/token limits.
+It uses RFC6749 client-secret Basic authentication (form-encoded components),
+`grant_type=client_credentials`, and requires Bearer type plus explicit bounded
+positive `expires_in`. Decimal strings are rejected unless the consumer explicitly
+sets `allowStringExpiresIn: true` for a documented provider contract.
+
+`getAccessToken()` caches until a conservative expiry calculated from request
+start; `renewalMarginMs` is bounded and capped at ten percent of token lifetime.
+Concurrent callers share one grant acquisition. Failure clears that acquisition;
+no stale token, background grant, refresh-token path or implicit retry exists.
+`invalidate(rejectedToken)` evicts only that current token. It does not resend a
+provider operation; definite-rejection classification belongs to the provider.
+
+All credential/cache storage uses ECMAScript private fields. Errors retain only
+safe reason and optional HTTP status, without raw responses, causes or headers.
+Configuration options and returned tokens remain secret-bearing: never log them.
+
+The bounded helper supports `get`, `postForm`, and `postJson`. JSON is snapshotted
+before awaiting, supports bounded plain values, and refuses cycles, accessors,
+non-finite numbers, unsupported prototypes, excessive depth/nodes/UTF8 bytes.
+Its trusted headers are immutable and hidden from object serialization. Construct
+a fresh helper with the current Bearer token after acquisition rather than mutate
+the original header object. HTTP has no redirects, no implicit retries, bounded
+response/deadline and sanitized errors. Providers own response schema/acceptance.
+
+This is transport source infrastructure. It does not prove provider credentials,
+funding, destination/sender capability, delivered messages, authorization or an
+exactly-once external side effect. Unknown provider write results require owning
+reconciliation and cannot be retried by this helper.
+
+Protocol: [RFC6749 client credentials](https://www.rfc-editor.org/rfc/rfc6749#section-4.4).