create-easy-stack 1.0.3

package/infra/prisma-postgres/infra.json

@@ -0,0 +1,60 @@
+{
+  "id": "prisma-postgres",
+  "label": "PostgreSQL + Prisma (adapter-pg)",
+  "default": true,
+  "templates": ["nest-ddd"],
+  "dependencies": {
+    "@prisma/adapter-pg": "^7.10.0",
+    "@prisma/client": "^7.10.0",
+    "pg": "^8.23.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.23.1",
+    "prisma": "7.10.0"
+  },
+  "scripts": {
+    "postinstall": "prisma generate || exit 0",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev",
+    "prisma:deploy": "prisma migrate deploy",
+    "prisma:studio": "prisma studio"
+  },
+  "env": [
+    "# PostgreSQL (docker-compose.yml)",
+    "DATABASE_URL=\"postgresql://root:rootpassword@localhost:5432/{{PROJECT_NAME_SNAKE}}_db?schema=public\""
+  ],
+  "docker": {
+    "file": "docker.service.yml",
+    "volumes": ["postgres_data"]
+  },
+  "inject": [
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:imports",
+      "lines": ["import { DatabaseModule } from './core/infrastructure/database/database.module.js';"]
+    },
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:modules",
+      "lines": ["DatabaseModule,"]
+    },
+    {
+      "file": "src/core/index.ts",
+      "marker": "// @infra:barrel",
+      "lines": [
+        "export * from './infrastructure/database/prisma.service.js';",
+        "export * from './infrastructure/database/database.module.js';"
+      ]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-imports",
+      "lines": ["import { validateDatabaseEnv } from './database.env.js';"]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-checks",
+      "lines": ["validateDatabaseEnv(config, errors);"]
+    }
+  ]
+}

package/infra/rabbitmq/docker.service.yml

@@ -0,0 +1,16 @@
+rabbitmq:
+  image: rabbitmq:3.12-management-alpine
+  container_name: {{PROJECT_NAME_SNAKE}}_rabbitmq
+  # RabbitMQ keeps its data under a folder named after the node, and the node is named after the
+  # host name. Without a fixed one, a re-created container gets a new random name and starts with
+  # an EMPTY broker, leaving the queues and messages in the volume unused.
+  hostname: {{PROJECT_NAME}}-rabbitmq
+  environment:
+    RABBITMQ_DEFAULT_USER: admin
+    RABBITMQ_DEFAULT_PASS: admin
+  ports:
+    - '5672:5672'
+    - '15672:15672'
+  volumes:
+    - rabbitmq_data:/var/lib/rabbitmq
+  restart: unless-stopped

package/infra/rabbitmq/files/src/core/config/messaging.env.ts

@@ -0,0 +1,29 @@
+const JOB_QUEUES = ['rabbitmq', 'inline'];
+// Where the built-in local RabbitMQ address may be used
+const LOCAL_ENVIRONMENTS = [undefined, 'development', 'test'];
+
+/** JOB_QUEUE must be known, `inline` is dev-only, and production must say where RabbitMQ is. */
+export function validateMessagingEnv(
+  config: Record<string, unknown>,
+  errors: string[],
+): void {
+  const jobQueue = (config.JOB_QUEUE ?? 'rabbitmq') as string;
+
+  if (!JOB_QUEUES.includes(jobQueue)) {
+    errors.push(
+      `JOB_QUEUE must be one of: ${JOB_QUEUES.join(', ')} (got "${jobQueue}")`,
+    );
+  } else if (jobQueue === 'inline' && config.NODE_ENV === 'production') {
+    errors.push(
+      'JOB_QUEUE=inline runs background work inside the request and is not allowed in production; use rabbitmq',
+    );
+  } else if (
+    jobQueue === 'rabbitmq' &&
+    !LOCAL_ENVIRONMENTS.includes(config.NODE_ENV as string | undefined) &&
+    !(typeof config.RABBITMQ_URL === 'string' && config.RABBITMQ_URL.trim())
+  ) {
+    errors.push(
+      'RABBITMQ_URL must be set unless NODE_ENV is development, test or unset, when JOB_QUEUE=rabbitmq',
+    );
+  }
+}

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/inline-job-queue.spec.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Logger } from '@nestjs/common';
+import { InlineJobQueue } from './inline-job-queue.js';
+import { defineJob } from './job-queue.port.js';
+
+const JOB = defineJob<{ to: string }>({
+  name: 'send-email',
+  retryDelaysMs: [],
+});
+
+describe('InlineJobQueue', () => {
+  let queue: InlineJobQueue;
+  let logged: string[];
+
+  beforeEach(() => {
+    logged = [];
+    for (const level of ['warn', 'error'] as const) {
+      vi.spyOn(Logger.prototype, level).mockImplementation((message: any) => {
+        logged.push(String(message));
+      });
+    }
+    queue = new InlineJobQueue();
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it('runs the handler right away, inside the call (AC-9)', async () => {
+    const handler = vi.fn().mockResolvedValue(undefined);
+    queue.register(JOB, handler);
+
+    await queue.enqueue(JOB, { to: 'a@example.com' });
+
+    expect(handler).toHaveBeenCalledWith({ to: 'a@example.com' });
+  });
+
+  it('logs a failing handler without the data and does not throw or retry (AC-9)', async () => {
+    const handler = vi.fn().mockRejectedValue(
+      Object.assign(new Error('550 <a@example.com> unknown'), {
+        code: 'EENVELOPE',
+      }),
+    );
+    queue.register(JOB, handler);
+
+    await expect(
+      queue.enqueue(JOB, { to: 'a@example.com' }),
+    ).resolves.toBeUndefined();
+
+    expect(handler).toHaveBeenCalledOnce();
+    const everything = logged.join('\n');
+    expect(everything).toContain('EENVELOPE');
+    expect(everything).not.toContain('a@example.com');
+  });
+
+  it('drops a job nobody handles, with a warning', async () => {
+    await expect(
+      queue.enqueue(JOB, { to: 'a@example.com' }),
+    ).resolves.toBeUndefined();
+
+    expect(logged.join('\n')).toContain('No handler registered');
+  });
+});

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/inline-job-queue.ts

@@ -0,0 +1,33 @@
+import { Logger } from '@nestjs/common';
+import type { IJobQueue, JobDefinition, JobHandler } from './job-queue.port.js';
+import { describeFailure } from './job-failure.js';
+
+/**
+ * Runs the job right away, inside the call to `enqueue`. For tests and for development
+ * without a broker. There are no retries: a handler that throws is logged and dropped.
+ */
+export class InlineJobQueue implements IJobQueue {
+  private readonly logger = new Logger(InlineJobQueue.name);
+  private readonly handlers = new Map<string, JobHandler<never>>();
+
+  register<T>(job: JobDefinition<T>, handler: JobHandler<T>): void {
+    this.handlers.set(job.name, handler as JobHandler<never>);
+  }
+
+  async enqueue<T>(job: JobDefinition<T>, data: T): Promise<void> {
+    const handler = this.handlers.get(job.name) as JobHandler<T> | undefined;
+    if (!handler) {
+      this.logger.warn(`No handler registered for job "${job.name}"; dropped`);
+      return;
+    }
+    try {
+      await handler(data);
+    } catch (error) {
+      // Only the kind of failure is logged: the payload and the provider's message can hold
+      // personal data (an email address, a one-time code)
+      this.logger.error(
+        `Job "${job.name}" failed (no retries inline): ${describeFailure(error)}`,
+      );
+    }
+  }
+}

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-failure.spec.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { describeFailure } from './job-failure.js';
+
+describe('describeFailure', () => {
+  it('keeps the error code, response code and name, and leaves the message out', () => {
+    const error = Object.assign(
+      new Error('550 5.1.1 <a@example.com> unknown'),
+      { code: 'EENVELOPE', responseCode: 550 },
+    );
+
+    expect(describeFailure(error)).toBe('EENVELOPE 550 Error');
+  });
+
+  it('strips anything that is not a plain word character, so a code cannot smuggle text into the log', () => {
+    expect(describeFailure({ code: 'a@b.com\nBcc: x' })).toBe('ab.comBccx');
+  });
+
+  it('copes with values that are not errors', () => {
+    expect(describeFailure(undefined)).toBe('unknown error');
+    expect(describeFailure('boom')).toBe('unknown error');
+    expect(describeFailure(null)).toBe('unknown error');
+  });
+});

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-failure.ts

@@ -0,0 +1,19 @@
+/**
+ * A short, safe description of why a job failed: the error's code and name only. The
+ * message is left out on purpose, because SMTP and driver messages often quote the
+ * recipient's address or the data that was being processed.
+ */
+export function describeFailure(error: unknown): string {
+  const e = error as { code?: unknown; responseCode?: unknown; name?: unknown };
+  const parts = [e?.code, e?.responseCode, e?.name]
+    .filter(
+      (part): part is string | number =>
+        typeof part === 'string' || typeof part === 'number',
+    )
+    .map((part) =>
+      String(part)
+        .replace(/[^\w.-]/g, '')
+        .slice(0, 40),
+    );
+  return parts.filter(Boolean).join(' ') || 'unknown error';
+}

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-payload-cipher.spec.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { JobPayloadCipher } from './job-payload-cipher.js';
+
+const MESSAGE = {
+  to: 'jane.doe@example.com',
+  subject: 'Your code',
+  text: 'Code: 482915',
+  html: '<p>Code: <b>482915</b></p>',
+};
+const SECRET = 's'.repeat(32);
+
+describe('JobPayloadCipher', () => {
+  const cipher = new JobPayloadCipher(SECRET, 'test-v1');
+
+  it('gives back exactly the message that was encrypted', () => {
+    expect(cipher.decrypt(cipher.encrypt(MESSAGE))).toEqual(MESSAGE);
+  });
+
+  it('keeps the address, the code and the text out of the encrypted form (AC-5)', () => {
+    const payload = cipher.encrypt(MESSAGE);
+
+    expect(payload).not.toContain('jane.doe');
+    expect(payload).not.toContain('482915');
+    expect(payload).not.toContain('Your code');
+    // base64 must not just be hiding the plain text
+    for (const part of payload.split('.')) {
+      const decoded = Buffer.from(part, 'base64').toString('latin1');
+      expect(decoded).not.toContain('482915');
+      expect(decoded).not.toContain('jane.doe');
+    }
+  });
+
+  it('refuses a payload that was made with another label: each kind of job has its own key', () => {
+    const other = new JobPayloadCipher(SECRET, 'other-v1');
+
+    expect(() => cipher.decrypt(other.encrypt(MESSAGE))).toThrow();
+  });
+
+  it('works for any JSON value, not only emails', () => {
+    expect(cipher.decrypt(cipher.encrypt({ email: 'a@example.com' }))).toEqual({
+      email: 'a@example.com',
+    });
+  });
+
+  it('produces a different result every time for the same message (fresh IV)', () => {
+    expect(cipher.encrypt(MESSAGE)).not.toBe(cipher.encrypt(MESSAGE));
+  });
+
+  it('refuses a payload that was made with another secret', () => {
+    const other = new JobPayloadCipher('t'.repeat(32), 'test-v1');
+
+    expect(() => cipher.decrypt(other.encrypt(MESSAGE))).toThrow();
+  });
+
+  it('refuses a payload that was altered', () => {
+    const [iv, tag, ciphertext] = cipher.encrypt(MESSAGE).split('.');
+    const bytes = Buffer.from(ciphertext, 'base64');
+    bytes[0] ^= 1;
+
+    expect(() =>
+      cipher.decrypt([iv, tag, bytes.toString('base64')].join('.')),
+    ).toThrow();
+  });
+
+  it('refuses a payload whose authentication tag was cut short, which would otherwise still verify', () => {
+    const [iv, tag, ciphertext] = cipher.encrypt(MESSAGE).split('.');
+    const shortTag = Buffer.from(tag, 'base64').subarray(0, 4);
+
+    expect(() =>
+      cipher.decrypt([iv, shortTag.toString('base64'), ciphertext].join('.')),
+    ).toThrow(/Malformed/);
+  });
+
+  it.each(['', 'abc', 'a.b', 'a.b.c.d'])(
+    'refuses a malformed payload "%s"',
+    (payload) => {
+      expect(() => cipher.decrypt(payload)).toThrow();
+    },
+  );
+});

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-payload-cipher.ts

@@ -0,0 +1,66 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  randomBytes,
+} from 'crypto';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+/**
+ * Encrypts the data of a job while it waits in the queue. Some of it is sensitive (a
+ * one-time code, an email address), and anything that sat in the broker in plain text
+ * would be readable by anyone who can see the broker. AES-256-GCM, so a payload that was
+ * changed in transit does not decrypt either.
+ *
+ * The key is derived from the server secret under a label of its own, so no new secret has
+ * to be configured and each kind of job gets a different key.
+ */
+export class JobPayloadCipher {
+  private readonly key: Buffer;
+
+  constructor(secret: string, label: string) {
+    this.key = createHmac('sha256', secret).update(label).digest();
+  }
+
+  /** `iv.tag.ciphertext`, each part base64. A fresh random IV every time. */
+  encrypt<T>(value: T): string {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', this.key, iv, {
+      authTagLength: TAG_BYTES,
+    });
+    const ciphertext = Buffer.concat([
+      cipher.update(JSON.stringify(value), 'utf8'),
+      cipher.final(),
+    ]);
+    return [iv, cipher.getAuthTag(), ciphertext]
+      .map((part) => part.toString('base64'))
+      .join('.');
+  }
+
+  /** Throws when the payload is malformed, was altered, or was made with another key. */
+  decrypt<T>(payload: string): T {
+    const [iv, tag, ciphertext] = payload
+      .split('.')
+      .map((part) => Buffer.from(part, 'base64'));
+    // A shortened tag would still "verify", with a far weaker guarantee, so only the full length is accepted
+    if (
+      !iv ||
+      !tag ||
+      !ciphertext ||
+      iv.length !== IV_BYTES ||
+      tag.length !== TAG_BYTES
+    ) {
+      throw new Error('Malformed job payload');
+    }
+    const decipher = createDecipheriv('aes-256-gcm', this.key, iv, {
+      authTagLength: TAG_BYTES,
+    });
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]);
+    return JSON.parse(plain.toString('utf8')) as T;
+  }
+}

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-queue.boundary.spec.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join, relative, sep } from 'path';
+
+const SRC = join(process.cwd(), 'src');
+const ALLOWED = [join('core', 'infrastructure', 'messaging')];
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) return sourceFiles(path);
+    return path.endsWith('.ts') ? [path] : [];
+  });
+}
+
+describe('job queue boundary (AC-11)', () => {
+  it('keeps amqplib and RabbitMQService inside core/infrastructure/messaging, so business code only knows the IJobQueue port', () => {
+    const offenders = sourceFiles(SRC)
+      .filter((file) => {
+        const path = relative(SRC, file);
+        return !ALLOWED.some((allowed) => path.startsWith(allowed + sep));
+      })
+      // `core/index.ts` only re-exports the module
+      .filter((file) => relative(SRC, file) !== join('core', 'index.ts'))
+      .filter((file) =>
+        /from ['"]amqplib['"]|RabbitMQService|RabbitMqJobQueue/.test(
+          readFileSync(file, 'utf8'),
+        ),
+      )
+      .map((file) => relative(SRC, file));
+
+    expect(offenders).toEqual([]);
+  });
+});

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-queue.factory.ts

@@ -0,0 +1,21 @@
+import type { RabbitMQService } from '../rabbitmq/rabbitmq.service.js';
+import { InlineJobQueue } from './inline-job-queue.js';
+import type { IJobQueue, JobQueueOptions } from './job-queue.port.js';
+import { RabbitMqJobQueue } from './rabbitmq-job-queue.js';
+
+/** Picks the adapter for `JOB_QUEUE` (validated at boot by `validateEnv`). */
+export function createJobQueue(
+  env: NodeJS.ProcessEnv,
+  rabbit: RabbitMQService,
+  options: JobQueueOptions,
+): IJobQueue {
+  const kind = env.JOB_QUEUE ?? 'rabbitmq';
+  switch (kind) {
+    case 'inline':
+      return new InlineJobQueue();
+    case 'rabbitmq':
+      return new RabbitMqJobQueue(rabbit, options);
+    default:
+      throw new Error(`Unknown JOB_QUEUE "${kind}"`);
+  }
+}

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-queue.module.spec.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { JobQueueModule } from './job-queue.module.js';
+import { createJobQueue } from './job-queue.factory.js';
+import { InlineJobQueue } from './inline-job-queue.js';
+import { RabbitMqJobQueue } from './rabbitmq-job-queue.js';
+import { JOB_QUEUE } from './job-queue.port.js';
+import { RabbitMQService } from '../rabbitmq/rabbitmq.service.js';
+
+describe('createJobQueue', () => {
+  const rabbit = {} as RabbitMQService;
+
+  it('defaults to RabbitMQ', () => {
+    expect(createJobQueue({}, rabbit, {})).toBeInstanceOf(RabbitMqJobQueue);
+  });
+
+  it.each([
+    ['rabbitmq', RabbitMqJobQueue],
+    ['inline', InlineJobQueue],
+  ])('picks the adapter named by JOB_QUEUE=%s', (kind, adapter) => {
+    expect(createJobQueue({ JOB_QUEUE: kind }, rabbit, {})).toBeInstanceOf(
+      adapter,
+    );
+  });
+
+  it('refuses an unknown value instead of silently picking one', () => {
+    expect(() => createJobQueue({ JOB_QUEUE: 'kafka' }, rabbit, {})).toThrow(
+      /Unknown JOB_QUEUE/,
+    );
+  });
+});
+
+describe('JobQueueModule', () => {
+  const original = process.env.JOB_QUEUE;
+  let start: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    start = vi.spyOn(RabbitMQService.prototype, 'start');
+  });
+  afterEach(() => {
+    if (original === undefined) delete process.env.JOB_QUEUE;
+    else process.env.JOB_QUEUE = original;
+    vi.restoreAllMocks();
+  });
+
+  it('builds the inline queue and never opens a RabbitMQ connection (AC-9)', async () => {
+    process.env.JOB_QUEUE = 'inline';
+
+    const moduleRef = await Test.createTestingModule({
+      imports: [JobQueueModule],
+    }).compile();
+    await moduleRef.init();
+
+    expect(moduleRef.get(JOB_QUEUE)).toBeInstanceOf(InlineJobQueue);
+    expect(start).not.toHaveBeenCalled();
+    expect(moduleRef.get(RabbitMQService).isConnected()).toBe(false);
+    await moduleRef.close();
+  });
+
+  it('reads JOB_QUEUE when the module is built, not when the file is imported', async () => {
+    process.env.JOB_QUEUE = 'inline';
+    const first = await Test.createTestingModule({
+      imports: [JobQueueModule],
+    }).compile();
+    expect(first.get(JOB_QUEUE)).toBeInstanceOf(InlineJobQueue);
+
+    process.env.JOB_QUEUE = 'rabbitmq';
+    const second = await Test.createTestingModule({
+      imports: [JobQueueModule],
+    }).compile();
+    expect(second.get(JOB_QUEUE)).toBeInstanceOf(RabbitMqJobQueue);
+    // Built but not initialised: nothing connected
+    expect(start).not.toHaveBeenCalled();
+  });
+});

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-queue.module.ts

@@ -0,0 +1,30 @@
+import { Global, Module } from '@nestjs/common';
+import { RabbitMQModule } from '../rabbitmq/rabbitmq.module.js';
+import { RabbitMQService } from '../rabbitmq/rabbitmq.service.js';
+import { createJobQueue } from './job-queue.factory.js';
+import {
+  JOB_QUEUE,
+  JOB_QUEUE_OPTIONS,
+  type JobQueueOptions,
+} from './job-queue.port.js';
+
+/**
+ * Chooses the job queue by `JOB_QUEUE`: `rabbitmq` (default) or `inline`. The choice is made
+ * when the module is built, not when this file is imported, so tests can set it first.
+ * Global: any feature can inject `JOB_QUEUE` without importing this module.
+ */
+@Global()
+@Module({
+  imports: [RabbitMQModule],
+  providers: [
+    { provide: JOB_QUEUE_OPTIONS, useValue: {} satisfies JobQueueOptions },
+    {
+      provide: JOB_QUEUE,
+      inject: [RabbitMQService, JOB_QUEUE_OPTIONS],
+      useFactory: (rabbit: RabbitMQService, options: JobQueueOptions) =>
+        createJobQueue(process.env, rabbit, options),
+    },
+  ],
+  exports: [JOB_QUEUE],
+})
+export class JobQueueModule {}

package/infra/rabbitmq/files/src/core/infrastructure/messaging/jobs/job-queue.port.ts

@@ -0,0 +1,59 @@
+/**
+ * Describes one kind of background job. Business code declares these and never
+ * touches the message broker: it only knows this port.
+ */
+export interface JobDefinition<T = unknown> {
+  /** Unique, stable name (also the routing key). Lowercase words joined by dashes. */
+  readonly name: string;
+  /**
+   * Wait before each retry, in milliseconds. Its length is the number of retries:
+   * `[10_000, 30_000]` means up to 3 runs in total, the 2nd after 10 s and the 3rd after
+   * 30 s more. A job that still fails after the last retry is set aside (dead-lettered).
+   */
+  readonly retryDelaysMs: readonly number[];
+  /** How many jobs of this kind run at the same time. Default 1. */
+  readonly concurrency?: number;
+  /** Type-only marker so `enqueue` and `register` agree on the payload type. Never set. */
+  readonly __payload?: T;
+}
+
+export type JobHandler<T> = (data: T) => Promise<void>;
+
+/** Declares a job; the payload type is carried by `T`. Payloads must be plain JSON. */
+export function defineJob<T>(
+  definition: Omit<JobDefinition<T>, '__payload'>,
+): JobDefinition<T> {
+  return definition;
+}
+
+/**
+ * Runs work in the background with retries. Delivery is at-least-once: a job can run
+ * twice (e.g. the process died after doing the work but before confirming it), and jobs
+ * of one kind are not guaranteed to run in order, so handlers must tolerate both.
+ */
+export interface IJobQueue {
+  /**
+   * Hands a job over and returns once it is safely stored, not once it has run.
+   * Rejects with `ServiceUnavailableException` when it could not be stored.
+   */
+  enqueue<T>(job: JobDefinition<T>, data: T): Promise<void>;
+
+  /**
+   * Sets the handler that runs jobs of this kind. Call once, when the module starts. A
+   * handler that throws gets the job retried per the definition.
+   */
+  register<T>(job: JobDefinition<T>, handler: JobHandler<T>): void;
+}
+
+/** DI token for the active IJobQueue. */
+export const JOB_QUEUE = 'IJobQueue';
+
+/** Tuning that only tests change; the defaults are the real behaviour. */
+export interface JobQueueOptions {
+  /** Prefix for exchange and queue names, so a test run never touches real queues. */
+  namespace?: string;
+  /** Multiplies every retry delay (0.01 turns 10 s into 100 ms). */
+  retryDelayScale?: number;
+}
+
+export const JOB_QUEUE_OPTIONS = 'JOB_QUEUE_OPTIONS';