create-easy-stack 1.0.3

package/infra/rabbitmq/files/src/core/infrastructure/messaging/rabbitmq/rabbitmq.service.ts

@@ -0,0 +1,207 @@
+import {
+  Injectable,
+  Logger,
+  OnApplicationShutdown,
+  ServiceUnavailableException,
+} from '@nestjs/common';
+import * as amqp from 'amqplib';
+
+/** Runs every time a connection and channel are (re)established. Rejecting restarts the connection. */
+export type ConnectedHook = (channel: amqp.ConfirmChannel) => Promise<void>;
+
+const MAX_BACKOFF_MS = 30_000;
+const PUBLISH_CONFIRM_TIMEOUT_MS = 5_000;
+
+/**
+ * The connection to RabbitMQ and nothing else: connect in the background, reconnect with
+ * exponential backoff (1 s, 2 s, 4 s ... 30 s), and publish with the broker's confirmation.
+ *
+ * It does not block the application from starting while the broker is away, and `publish`
+ * fails at once (503) instead of hanging when there is no connection. What to publish and
+ * consume belongs to the layers above (see `RabbitMqJobQueue`); they use `onConnected`
+ * to set themselves up again after every reconnect, because a new connection starts with
+ * no queues bound and no consumers.
+ */
+@Injectable()
+export class RabbitMQService implements OnApplicationShutdown {
+  private readonly logger = new Logger(RabbitMQService.name);
+  private connection: amqp.ChannelModel | null = null;
+  private channel: amqp.ConfirmChannel | null = null;
+  private readonly hooks: ConnectedHook[] = [];
+  private started = false;
+  private connecting = false;
+  private shuttingDown = false;
+  private cancelWait: (() => void) | null = null;
+
+  /** Starts connecting in the background. Safe to call more than once. */
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    void this.connectLoop();
+  }
+
+  /** Registers a hook for every (re)connection; runs it now when already connected. */
+  onConnected(hook: ConnectedHook): void {
+    this.hooks.push(hook);
+    const channel = this.channel;
+    if (channel) {
+      hook(channel).catch((error: Error) => {
+        this.logger.error(`RabbitMQ setup hook failed: ${error.message}`);
+        this.restart();
+      });
+    }
+  }
+
+  /** The live channel, or null while disconnected. */
+  getChannel(): amqp.ConfirmChannel | null {
+    return this.channel;
+  }
+
+  isConnected(): boolean {
+    return this.channel !== null;
+  }
+
+  /**
+   * Publishes (on `onChannel`, by default the live one) and waits for the broker to confirm it stored the message. Rejects with a
+   * 503 when there is no connection, the broker refuses, or no confirmation arrives in time.
+   */
+  async publish(
+    exchange: string,
+    routingKey: string,
+    content: Buffer,
+    options: amqp.Options.Publish = {},
+    onChannel: amqp.ConfirmChannel | null = this.channel,
+  ): Promise<void> {
+    const channel = onChannel;
+    if (!channel) {
+      throw new ServiceUnavailableException('Message broker is unavailable');
+    }
+
+    let timer: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        new Promise<void>((resolve, reject) => {
+          channel.publish(
+            exchange,
+            routingKey,
+            content,
+            { persistent: true, ...options },
+            (error) => (error ? reject(error) : resolve()),
+          );
+        }),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error('publish confirmation timed out')),
+            PUBLISH_CONFIRM_TIMEOUT_MS,
+          );
+        }),
+      ]);
+    } catch (error) {
+      this.logger.error(
+        `Publish to "${routingKey}" failed: ${(error as Error).message}`,
+      );
+      throw new ServiceUnavailableException('Message broker is unavailable');
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    this.shuttingDown = true;
+    this.cancelWait?.();
+    const { channel, connection } = this;
+    this.channel = null;
+    this.connection = null;
+    try {
+      await channel?.close();
+      await connection?.close();
+    } catch {
+      // Already closed: nothing left to release
+    }
+  }
+
+  private async connectLoop(): Promise<void> {
+    if (this.connecting) return;
+    this.connecting = true;
+    let attempt = 0;
+
+    while (!this.shuttingDown) {
+      try {
+        const url =
+          process.env.RABBITMQ_URL || 'amqp://admin:admin@localhost:5672';
+        const connection = await amqp.connect(url);
+        if (this.shuttingDown) {
+          await connection.close().catch(() => undefined);
+          break;
+        }
+        // 'error' is always followed by 'close'; reconnecting happens there
+        connection.on('error', (error: Error) =>
+          this.logger.error(`RabbitMQ connection error: ${error.message}`),
+        );
+        connection.on('close', () => this.handleClosed(connection));
+
+        const channel = await connection.createConfirmChannel();
+        // A channel error (e.g. declaring a queue with different arguments) closes only the
+        // channel; start over with a clean connection rather than carry on without one
+        channel.on('error', (error: Error) =>
+          this.logger.error(`RabbitMQ channel error: ${error.message}`),
+        );
+        channel.on('close', () => {
+          if (this.channel === channel) {
+            this.channel = null;
+            connection.close().catch(() => undefined);
+          }
+        });
+
+        try {
+          for (const hook of this.hooks) await hook(channel);
+        } catch (error) {
+          await connection.close().catch(() => undefined);
+          throw error;
+        }
+
+        if (this.shuttingDown) {
+          await connection.close().catch(() => undefined);
+          break;
+        }
+        this.connection = connection;
+        this.channel = channel;
+        this.logger.log('Connected to RabbitMQ');
+        this.connecting = false;
+        return;
+      } catch (error) {
+        const delay = Math.min(2 ** attempt * 1000, MAX_BACKOFF_MS);
+        this.logger.warn(
+          `RabbitMQ not ready (${(error as Error).message}); retrying in ${delay / 1000}s`,
+        );
+        attempt += 1;
+        await this.wait(delay);
+      }
+    }
+    this.connecting = false;
+  }
+
+  private handleClosed(connection: amqp.ChannelModel): void {
+    if (this.connection !== connection) return;
+    this.connection = null;
+    this.channel = null;
+    if (this.shuttingDown) return;
+    this.logger.warn('RabbitMQ connection closed; reconnecting');
+    void this.connectLoop();
+  }
+
+  private restart(): void {
+    const connection = this.connection;
+    if (connection) connection.close().catch(() => undefined);
+  }
+
+  private wait(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      this.cancelWait = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    });
+  }
+}

package/infra/rabbitmq/infra.json

@@ -0,0 +1,55 @@
+{
+  "id": "rabbitmq",
+  "label": "RabbitMQ (broker + background job queue)",
+  "default": true,
+  "templates": ["nest-ddd"],
+  "dependencies": {
+    "amqplib": "^2.0.1"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.8"
+  },
+  "env": [
+    "# RabbitMQ (docker-compose.yml) — management UI on http://localhost:15672 (admin/admin)",
+    "RABBITMQ_URL=amqp://admin:admin@localhost:5672",
+    "# rabbitmq | inline (inline runs jobs inside the request: dev/tests only)",
+    "JOB_QUEUE=rabbitmq"
+  ],
+  "docker": {
+    "file": "docker.service.yml",
+    "volumes": ["rabbitmq_data"]
+  },
+  "inject": [
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:imports",
+      "lines": ["import { JobQueueModule } from './core/infrastructure/messaging/jobs/job-queue.module.js';"]
+    },
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:modules",
+      "lines": ["JobQueueModule,"]
+    },
+    {
+      "file": "src/core/index.ts",
+      "marker": "// @infra:barrel",
+      "lines": [
+        "export * from './infrastructure/messaging/rabbitmq/rabbitmq.service.js';",
+        "export * from './infrastructure/messaging/rabbitmq/rabbitmq.module.js';",
+        "export * from './infrastructure/messaging/jobs/job-queue.port.js';",
+        "export * from './infrastructure/messaging/jobs/job-queue.module.js';",
+        "export * from './infrastructure/messaging/jobs/job-payload-cipher.js';"
+      ]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-imports",
+      "lines": ["import { validateMessagingEnv } from './messaging.env.js';"]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-checks",
+      "lines": ["validateMessagingEnv(config, errors);"]
+    }
+  ]
+}

package/infra/redis/docker.service.yml

@@ -0,0 +1,10 @@
+redis:
+  image: redis:7-alpine
+  container_name: {{PROJECT_NAME_SNAKE}}_redis
+  # Append-only file: counters, locks and idempotency records must survive a restart
+  command: redis-server --appendonly yes --appendfsync everysec
+  ports:
+    - '6379:6379'
+  volumes:
+    - redis_data:/data
+  restart: unless-stopped

package/infra/redis/files/src/core/http/decorators/rate-limit.decorator.ts

@@ -0,0 +1,26 @@
+import { SetMetadata } from '@nestjs/common';
+import type { Request } from 'express';
+
+export const RATE_LIMIT_KEY = 'rateLimit';
+
+/**
+ * Who a request is counted against:
+ *  - 'ip'    : client IP (default)
+ *  - 'user'  : authenticated user id, falls back to IP on public routes
+ *  - function: custom identity, e.g. (req) => `${req.ip}:${req.body?.email}`
+ */
+export type RateLimitKey =
+  'ip' | 'user' | ((req: Request) => string | undefined);
+
+export interface RateLimitOptions {
+  /** Max requests allowed per window. */
+  limit: number;
+  /** Window length in seconds — use buildTTL, e.g. buildTTL('MINUTE', 15). */
+  window: number;
+  /** Who to count against. Defaults to 'ip'. */
+  key?: RateLimitKey;
+}
+
+/** Limit a route, or every route of a controller (each route gets its own bucket). */
+export const RateLimit = (options: RateLimitOptions) =>
+  SetMetadata(RATE_LIMIT_KEY, options);

package/infra/redis/files/src/core/http/interceptors/rate-limit.interceptor.spec.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CallHandler, ExecutionContext, HttpStatus } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { createHash } from 'crypto';
+import { of } from 'rxjs';
+import { RateLimitInterceptor } from './rate-limit.interceptor.js';
+import { RateLimitService } from '../../infrastructure/redis/rate-limit/rate-limit.service.js';
+import { CACHE } from '../../infrastructure/redis/cache.constants.js';
+
+const makeContext = (req: object) =>
+  ({
+    switchToHttp: () => ({ getRequest: () => req }),
+    getHandler: () => () => {},
+    getClass: () => class {},
+  }) as unknown as ExecutionContext;
+
+const makeRequest = (overrides: object = {}) => ({
+  ip: '1.1.1.1',
+  path: '/auth/login?x=1',
+  route: { path: '/auth/login' },
+  socket: { remoteAddress: '9.9.9.9' },
+  ...overrides,
+});
+
+const bucket = (identifier: string) =>
+  CACHE.RATE_LIMIT.KEYS.BUCKET('/auth/login', identifier);
+
+describe('RateLimitInterceptor', () => {
+  let interceptor: RateLimitInterceptor;
+  let reflector: { getAllAndOverride: ReturnType<typeof vi.fn> };
+  let service: { isAllowed: ReturnType<typeof vi.fn> };
+  let next: CallHandler;
+
+  beforeEach(() => {
+    reflector = { getAllAndOverride: vi.fn() };
+    service = { isAllowed: vi.fn().mockResolvedValue(true) };
+    next = { handle: vi.fn().mockReturnValue(of('handled')) };
+    interceptor = new RateLimitInterceptor(
+      reflector as unknown as Reflector,
+      service as unknown as RateLimitService,
+    );
+  });
+
+  it('passes through without touching Redis when the route has no @RateLimit', async () => {
+    reflector.getAllAndOverride.mockReturnValue(undefined);
+
+    await interceptor.intercept(makeContext(makeRequest()), next);
+
+    expect(service.isAllowed).not.toHaveBeenCalled();
+    expect(next.handle).toHaveBeenCalledOnce();
+  });
+
+  it('calls the handler while under the limit, bucketed by route pattern + IP by default', async () => {
+    reflector.getAllAndOverride.mockReturnValue({ limit: 5, window: 900 });
+
+    await interceptor.intercept(makeContext(makeRequest()), next);
+
+    expect(service.isAllowed).toHaveBeenCalledWith(
+      bucket('ip:1.1.1.1'),
+      5,
+      900,
+    );
+    expect(next.handle).toHaveBeenCalledOnce();
+  });
+
+  it('throws 429 and does not call the handler when the limit is exceeded', async () => {
+    reflector.getAllAndOverride.mockReturnValue({ limit: 5, window: 900 });
+    service.isAllowed.mockResolvedValue(false);
+
+    await expect(
+      interceptor.intercept(makeContext(makeRequest()), next),
+    ).rejects.toMatchObject({
+      status: HttpStatus.TOO_MANY_REQUESTS,
+    });
+    expect(next.handle).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the socket address when request.ip is missing', async () => {
+    reflector.getAllAndOverride.mockReturnValue({ limit: 5, window: 900 });
+
+    await interceptor.intercept(
+      makeContext(makeRequest({ ip: undefined })),
+      next,
+    );
+
+    expect(service.isAllowed).toHaveBeenCalledWith(
+      bucket('ip:9.9.9.9'),
+      5,
+      900,
+    );
+  });
+
+  it('never uses the raw URL (query string) in the bucket key', async () => {
+    reflector.getAllAndOverride.mockReturnValue({ limit: 5, window: 900 });
+
+    await interceptor.intercept(makeContext(makeRequest()), next);
+
+    expect(service.isAllowed.mock.calls[0][0]).not.toContain('?x=1');
+  });
+
+  describe('key', () => {
+    it("'user' counts against the authenticated user id", async () => {
+      reflector.getAllAndOverride.mockReturnValue({
+        limit: 5,
+        window: 60,
+        key: 'user',
+      });
+
+      await interceptor.intercept(
+        makeContext(makeRequest({ user: { id: 'u1' } })),
+        next,
+      );
+
+      expect(service.isAllowed).toHaveBeenCalledWith(bucket('user:u1'), 5, 60);
+    });
+
+    it("'user' falls back to IP on a public route", async () => {
+      reflector.getAllAndOverride.mockReturnValue({
+        limit: 5,
+        window: 60,
+        key: 'user',
+      });
+
+      await interceptor.intercept(makeContext(makeRequest()), next);
+
+      expect(service.isAllowed).toHaveBeenCalledWith(
+        bucket('ip:1.1.1.1'),
+        5,
+        60,
+      );
+    });
+
+    it('a custom function is hashed so e.g. an email never lands in Redis as plain text', async () => {
+      const custom = (req: any) => `${req.ip}:${req.body.email}`;
+      reflector.getAllAndOverride.mockReturnValue({
+        limit: 5,
+        window: 60,
+        key: custom,
+      });
+
+      await interceptor.intercept(
+        makeContext(makeRequest({ body: { email: 'a@b.com' } })),
+        next,
+      );
+
+      const hash = createHash('sha256').update('1.1.1.1:a@b.com').digest('hex');
+      expect(service.isAllowed).toHaveBeenCalledWith(
+        bucket(`key:${hash}`),
+        5,
+        60,
+      );
+      expect(service.isAllowed.mock.calls[0][0]).not.toContain('a@b.com');
+    });
+
+    it('a custom function returning undefined falls back to IP', async () => {
+      reflector.getAllAndOverride.mockReturnValue({
+        limit: 5,
+        window: 60,
+        key: () => undefined,
+      });
+
+      await interceptor.intercept(makeContext(makeRequest()), next);
+
+      expect(service.isAllowed).toHaveBeenCalledWith(
+        bucket('ip:1.1.1.1'),
+        5,
+        60,
+      );
+    });
+  });
+
+  it('fails open when Redis is unavailable', async () => {
+    reflector.getAllAndOverride.mockReturnValue({ limit: 5, window: 900 });
+    service.isAllowed.mockRejectedValue(new Error('ECONNREFUSED'));
+
+    await interceptor.intercept(makeContext(makeRequest()), next);
+
+    expect(next.handle).toHaveBeenCalledOnce();
+  });
+});

package/infra/redis/files/src/core/http/interceptors/rate-limit.interceptor.ts

@@ -0,0 +1,105 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  HttpException,
+  HttpStatus,
+  Injectable,
+  Logger,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { createHash } from 'crypto';
+import type { Request } from 'express';
+import type { Observable } from 'rxjs';
+import { CACHE } from '../../infrastructure/redis/cache.constants.js';
+import { RateLimitService } from '../../infrastructure/redis/rate-limit/rate-limit.service.js';
+import {
+  RATE_LIMIT_KEY,
+  RateLimitKey,
+  RateLimitOptions,
+} from '../decorators/rate-limit.decorator.js';
+import type { ICurrentUser } from '../decorators/current-user.decorator.js';
+
+/**
+ * Enforces @RateLimit({ limit, window, key }) per route.
+ * Registered globally (RateLimitModule); routes without the decorator pass through.
+ *
+ * An interceptor rather than a guard on purpose: it runs after every guard, so
+ * request.user (set by JwtAuthGuard) is available for key: 'user' regardless of
+ * how the route orders its @UseGuards.
+ *
+ * Behind a proxy, enable Express `trust proxy` or every client shares the proxy's IP.
+ */
+@Injectable()
+export class RateLimitInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(RateLimitInterceptor.name);
+
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly rateLimitService: RateLimitService,
+  ) {}
+
+  async intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Promise<Observable<unknown>> {
+    const options = this.reflector.getAllAndOverride<
+      RateLimitOptions | undefined
+    >(RATE_LIMIT_KEY, [context.getHandler(), context.getClass()]);
+    if (!options) {
+      return next.handle();
+    }
+
+    const request = context
+      .switchToHttp()
+      .getRequest<Request & { user?: ICurrentUser }>();
+    // Route pattern, not the raw URL: the query string is client-controlled
+    // and would let a caller mint a fresh bucket per request.
+    const route = request.route?.path ?? request.path;
+    const identifier = this.resolveIdentifier(options.key ?? 'ip', request);
+    const key = CACHE.RATE_LIMIT.KEYS.BUCKET(route, identifier);
+
+    let allowed: boolean;
+    try {
+      allowed = await this.rateLimitService.isAllowed(
+        key,
+        options.limit,
+        options.window,
+      );
+    } catch (error: any) {
+      // Fail open: a Redis outage must not take the API down with it.
+      this.logger.error(
+        `Rate limit check failed for ${route}: ${error.message}`,
+      );
+      return next.handle();
+    }
+
+    if (!allowed) {
+      this.logger.warn(`Rate limit exceeded: ${route} (${identifier})`);
+      throw new HttpException(
+        'Too Many Requests',
+        HttpStatus.TOO_MANY_REQUESTS,
+      );
+    }
+    return next.handle();
+  }
+
+  private resolveIdentifier(
+    key: RateLimitKey,
+    request: Request & { user?: ICurrentUser },
+  ): string {
+    const ip = `ip:${request.ip ?? request.socket.remoteAddress ?? 'unknown'}`;
+
+    if (key === 'ip') {
+      return ip;
+    }
+    if (key === 'user') {
+      return request.user ? `user:${request.user.id}` : ip;
+    }
+    const custom = key(request);
+    // Hashed: custom keys often embed an email, which must not sit in Redis keys as plain text.
+    return custom
+      ? `key:${createHash('sha256').update(custom).digest('hex')}`
+      : ip;
+  }
+}

package/infra/redis/files/src/core/infrastructure/redis/cache.constants.ts

@@ -0,0 +1,67 @@
+import { buildTTL } from '../../utils/ttl.util.js';
+
+const GLOBAL_PREFIX = '{{PROJECT_NAME_SNAKE}}';
+const GLOBAL_VER = 'v1';
+
+/**
+ * Semantic TTL constants (in seconds).
+ * Pick based on data volatility — see the guidelines at the bottom of this file.
+ */
+export const TTL = {
+  TINY: buildTTL('MINUTE', 1), // highly volatile (stock count, live price)
+  SHORT: buildTTL('MINUTE', 5), // semi-volatile (entity detail)
+  MEDIUM: buildTTL('HOUR', 1), // semi-static (user profile, settings)
+  LONG: buildTTL('DAY', 1), // static (lookup tables, config)
+  WEEK: buildTTL('DAY', 7), // almost never changes
+} as const;
+
+/**
+ * Centralised cache-key factories.
+ *
+ * Key format:  <prefix>:<global-ver>:<domain>:<domain-ver>:<type>:<field>_<value>
+ * Example:     {{PROJECT_NAME_SNAKE}}:v1:orders:v1:order:id_01J8...
+ *
+ * Why a domain _VER?
+ *   Bumping ORDERS._VER instantly invalidates every key under that domain without
+ *   touching Redis — old keys just expire naturally.
+ *
+ * Add a block per bounded context, e.g.:
+ *
+ *   ORDERS: {
+ *     _VER: 'v1',
+ *     KEYS: {
+ *       DETAIL: (id: string): string =>
+ *         `${GLOBAL_PREFIX}:${GLOBAL_VER}:orders:${CACHE.ORDERS._VER}:order:id_${id}`,
+ *     },
+ *   },
+ */
+export const CACHE = {
+  RATE_LIMIT: {
+    _VER: 'v1',
+    KEYS: {
+      // route: Express route pattern (e.g. /auth/login), identifier: e.g. ip:1.1.1.1
+      BUCKET: (route: string, identifier: string) =>
+        `${GLOBAL_PREFIX}:${GLOBAL_VER}:ratelimit:${CACHE.RATE_LIMIT._VER}:${route}:${identifier}`,
+    },
+  },
+} as const;
+
+/*
+ * ── Cache TTL guidelines ─────────────────────────────────────────────────────
+ *
+ * 1. Data volatility
+ *    · Static (config, lookup tables)         → LONG / WEEK
+ *    · Semi-static (detail, profile)           → MEDIUM / SHORT
+ *    · Highly volatile (price, stock)          → TINY / SHORT, avoid tags
+ *
+ * 2. List vs detail TTL
+ *    · List keys   → shorter TTL (10–30 min) or version-tracked
+ *    · Detail keys → longer TTL, invalidated on write
+ *
+ * 3. Avoid thundering-herd / cache stampede
+ *    RedisService.set() already adds jitter to every TTL.
+ *
+ * 4. Stale data
+ *    Always invalidate (redis.invalidateDetail) right after a successful write.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */

package/infra/redis/files/src/core/infrastructure/redis/idempotency/idempotency.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { IdempotencyService } from './idempotency.service.js';
+
+@Global()
+@Module({
+  providers: [IdempotencyService],
+  exports: [IdempotencyService],
+})
+export class IdempotencyModule {}