create-easy-stack 1.0.3

package/infra/redis/files/src/core/infrastructure/redis/idempotency/idempotency.service.spec.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ConflictException } from '@nestjs/common';
+import {
+  IdempotencyService,
+  computeIdempotencyFingerprint,
+} from './idempotency.service.js';
+import type { RedisService } from '../redis.service.js';
+
+describe('IdempotencyService', () => {
+  let redisClient: {
+    set: ReturnType<typeof vi.fn>;
+    get: ReturnType<typeof vi.fn>;
+    del: ReturnType<typeof vi.fn>;
+  };
+  let redisService: Pick<RedisService, 'getClient'>;
+  let service: IdempotencyService;
+
+  beforeEach(() => {
+    redisClient = {
+      set: vi.fn(),
+      get: vi.fn(),
+      del: vi.fn().mockResolvedValue(1),
+    };
+    redisService = { getClient: () => redisClient as any };
+    service = new IdempotencyService(redisService as RedisService);
+  });
+
+  it('runs the action directly when no idempotency key is given', async () => {
+    const action = vi.fn().mockResolvedValue('result');
+
+    const result = await service.execute(undefined, 'fp', action);
+
+    expect(result).toBe('result');
+    expect(action).toHaveBeenCalledOnce();
+    expect(redisClient.set).not.toHaveBeenCalled();
+  });
+
+  it('claims the key, runs the action once, and marks it completed', async () => {
+    redisClient.set.mockResolvedValueOnce('OK');
+    const action = vi.fn().mockResolvedValue({ id: '1' });
+
+    const result = await service.execute('key-1', 'fp-1', action);
+
+    expect(result).toEqual({ id: '1' });
+    expect(action).toHaveBeenCalledOnce();
+    expect(redisClient.set).toHaveBeenCalledTimes(2);
+    const completedCall = redisClient.set.mock.calls[1];
+    expect(JSON.parse(completedCall[1])).toMatchObject({
+      status: 'completed',
+      fingerprint: 'fp-1',
+      response: { id: '1' },
+    });
+  });
+
+  it('replays the cached response on retry with the same fingerprint after completion', async () => {
+    redisClient.set.mockResolvedValueOnce(null); // NX claim fails: key already exists
+    redisClient.get.mockResolvedValueOnce(
+      JSON.stringify({
+        status: 'completed',
+        fingerprint: 'fp-1',
+        response: { id: '1' },
+      }),
+    );
+    const action = vi.fn();
+
+    const result = await service.execute('key-1', 'fp-1', action);
+
+    expect(result).toEqual({ id: '1' });
+    expect(action).not.toHaveBeenCalled();
+  });
+
+  it('rejects a retry with the same key while still processing', async () => {
+    redisClient.set.mockResolvedValueOnce(null);
+    redisClient.get.mockResolvedValueOnce(
+      JSON.stringify({ status: 'processing', fingerprint: 'fp-1' }),
+    );
+    const action = vi.fn();
+
+    await expect(service.execute('key-1', 'fp-1', action)).rejects.toThrow(
+      ConflictException,
+    );
+    expect(action).not.toHaveBeenCalled();
+  });
+
+  it('rejects a retry that reuses the key with a different fingerprint', async () => {
+    redisClient.set.mockResolvedValueOnce(null);
+    redisClient.get.mockResolvedValueOnce(
+      JSON.stringify({
+        status: 'completed',
+        fingerprint: 'fp-1',
+        response: { id: '1' },
+      }),
+    );
+    const action = vi.fn();
+
+    await expect(service.execute('key-1', 'fp-2', action)).rejects.toThrow(
+      ConflictException,
+    );
+    expect(action).not.toHaveBeenCalled();
+  });
+
+  it('deletes the claim and rethrows if the action fails', async () => {
+    redisClient.set.mockResolvedValueOnce('OK');
+    const action = vi.fn().mockRejectedValue(new Error('boom'));
+
+    await expect(service.execute('key-1', 'fp-1', action)).rejects.toThrow(
+      'boom',
+    );
+    expect(redisClient.del).toHaveBeenCalledWith('idempotency:key-1');
+  });
+
+  it('runs the action unprotected if claiming the lock fails (Redis unavailable)', async () => {
+    redisClient.set.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+    const action = vi.fn().mockResolvedValue('ok-anyway');
+
+    const result = await service.execute('key-1', 'fp-1', action);
+
+    expect(result).toBe('ok-anyway');
+    expect(action).toHaveBeenCalledOnce();
+  });
+
+  it('still returns the response if marking completion fails', async () => {
+    redisClient.set
+      .mockResolvedValueOnce('OK') // claim succeeds
+      .mockRejectedValueOnce(new Error('write failed')); // completion write fails
+    const action = vi.fn().mockResolvedValue('done');
+
+    const result = await service.execute('key-1', 'fp-1', action);
+
+    expect(result).toBe('done');
+  });
+});
+
+describe('computeIdempotencyFingerprint', () => {
+  it('produces the same hash for the same payload', () => {
+    expect(computeIdempotencyFingerprint({ a: 1 })).toBe(
+      computeIdempotencyFingerprint({ a: 1 }),
+    );
+  });
+
+  it('produces a different hash for a different payload', () => {
+    expect(computeIdempotencyFingerprint({ a: 1 })).not.toBe(
+      computeIdempotencyFingerprint({ a: 2 }),
+    );
+  });
+});

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

@@ -0,0 +1,131 @@
+import { Injectable, ConflictException, Logger } from '@nestjs/common';
+import { createHash } from 'crypto';
+import { RedisService } from '../redis.service.js';
+
+interface IdempotencyRecord<T> {
+  status: 'processing' | 'completed';
+  // Hash of the request payload this key was first used with, so a retry
+  // that reuses the same key with a *different* payload is rejected
+  // instead of silently replaying the wrong cached response.
+  fingerprint: string;
+  response?: T;
+}
+
+// Short: bounds how long a crashed/never-finishing attempt (or a failed
+// "mark completed" write, see below) can block retries under this key.
+const PROCESSING_TTL_SECONDS = 5 * 60;
+// Long: how long a *finished* result stays replayable for a legitimate
+// client retry.
+const COMPLETED_TTL_SECONDS = 24 * 60 * 60;
+
+export function computeIdempotencyFingerprint(payload: unknown): string {
+  return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+
+@Injectable()
+export class IdempotencyService {
+  private readonly logger = new Logger(IdempotencyService.name);
+
+  constructor(private readonly redis: RedisService) {}
+
+  private key(idempotencyKey: string): string {
+    return `idempotency:${idempotencyKey}`;
+  }
+
+  /**
+   * Runs `action` at most once per idempotencyKey within the TTL window.
+   * A retry with the same key and the same requestFingerprint while the
+   * first attempt is still running is rejected (409); after it completed,
+   * it replays the saved response instead of re-running the command. A
+   * retry with the same key but a *different* requestFingerprint is
+   * rejected instead of silently replaying an unrelated response. No key
+   * means no idempotency check.
+   */
+  async execute<T>(
+    idempotencyKey: string | undefined,
+    requestFingerprint: string,
+    action: () => Promise<T>,
+  ): Promise<T> {
+    if (!idempotencyKey) {
+      return action();
+    }
+
+    const key = this.key(idempotencyKey);
+    const client = this.redis.getClient();
+
+    let claimed: string | null;
+    try {
+      // Atomic claim: only the first request for this key gets NX to
+      // succeed. Bypasses RedisService's cache helpers (which swallow
+      // errors) because a failure here must be handled explicitly below.
+      claimed = await client.set(
+        key,
+        JSON.stringify({
+          status: 'processing',
+          fingerprint: requestFingerprint,
+        } satisfies IdempotencyRecord<T>),
+        'EX',
+        PROCESSING_TTL_SECONDS,
+        'NX',
+      );
+    } catch (err) {
+      // Redis unreachable/timed out (see commandTimeout on RedisService) —
+      // treat idempotency as best-effort infrastructure, not a hard
+      // dependency: run the action unprotected rather than failing (or
+      // hanging) the whole request over a duplicate-prevention nicety.
+      this.logger.warn(
+        `Idempotency claim failed for key ${idempotencyKey}, proceeding without protection: ${(err as Error).message}`,
+      );
+      return action();
+    }
+
+    if (claimed === null) {
+      const existingRaw = await client.get(key);
+      const existing = existingRaw
+        ? (JSON.parse(existingRaw) as IdempotencyRecord<T>)
+        : null;
+
+      if (existing && existing.fingerprint !== requestFingerprint) {
+        throw new ConflictException(
+          'This Idempotency-Key was already used with different request parameters',
+        );
+      }
+      if (existing?.status === 'completed') {
+        return existing.response as T;
+      }
+      throw new ConflictException(
+        'A request with this Idempotency-Key is already being processed',
+      );
+    }
+
+    try {
+      const response = await action();
+      try {
+        await client.set(
+          key,
+          JSON.stringify({
+            status: 'completed',
+            fingerprint: requestFingerprint,
+            response,
+          } satisfies IdempotencyRecord<T>),
+          'EX',
+          COMPLETED_TTL_SECONDS,
+        );
+      } catch (err) {
+        // The action already succeeded — don't fail a successful response
+        // over bookkeeping. Logged loudly (not swallowed) because it means
+        // this key is stuck reporting "processing" until PROCESSING_TTL_
+        // SECONDS expires, after which a retry would re-run the action.
+        this.logger.error(
+          `Failed to record completion for idempotency key ${idempotencyKey}: ${(err as Error).message}`,
+        );
+      }
+      return response;
+    } catch (err) {
+      // Don't hold the claim for a failed attempt — a retry should be able
+      // to try again rather than being stuck behind a dead "processing".
+      await client.del(key).catch(() => undefined);
+      throw err;
+    }
+  }
+}

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

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

package/infra/redis/files/src/core/infrastructure/redis/lock/lock.service.integration-spec.ts

@@ -0,0 +1,111 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { LockService } from './lock.service.js';
+import { RedisService } from '../redis.service.js';
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Against the real Redis: what matters is how two callers behave when they arrive together. */
+describe('LockService (Integration)', () => {
+  let locks: LockService;
+  let redis: RedisService;
+
+  beforeAll(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [LockService, RedisService],
+    }).compile();
+    locks = module.get(LockService);
+    redis = module.get(RedisService);
+  });
+
+  beforeEach(async () => {
+    const keys = await redis.getClient().keys('*:lock:*');
+    if (keys.length > 0) await redis.getClient().del(...keys);
+  });
+
+  afterAll(async () => {
+    await redis.getClient().quit();
+  });
+
+  it('runs the work and returns its result', async () => {
+    await expect(locks.run('t-1', async () => 42)).resolves.toBe(42);
+  });
+
+  it('makes two callers for the same name take turns, never overlap', async () => {
+    const events: string[] = [];
+    const job = (label: string) => async () => {
+      events.push(`${label} start`);
+      await sleep(150);
+      events.push(`${label} end`);
+    };
+
+    await Promise.all([locks.run('t-2', job('a')), locks.run('t-2', job('b'))]);
+
+    expect(events).toHaveLength(4);
+    // whoever started first also ended before the other started
+    expect(events[1]).toMatch(/end$/);
+    expect(events[1].split(' ')[0]).toBe(events[0].split(' ')[0]);
+  });
+
+  it('lets different names run at the same time', async () => {
+    const started: string[] = [];
+    const job = (label: string) => async () => {
+      started.push(label);
+      await sleep(200);
+    };
+
+    const begin = Date.now();
+    await Promise.all([
+      locks.run('t-3a', job('a')),
+      locks.run('t-3b', job('b')),
+    ]);
+
+    expect(Date.now() - begin).toBeLessThan(380);
+  });
+
+  it('gives up with a 409 when the other one takes too long', async () => {
+    const holder = locks.run('t-4', () => sleep(400));
+
+    await expect(
+      locks.run('t-4', async () => 'never', { waitMs: 100 }),
+    ).rejects.toMatchObject({ code: 'SYS-002', status: 409 });
+
+    await holder;
+  });
+
+  it('lets go when the work fails, so the next caller is not stuck', async () => {
+    await expect(
+      locks.run('t-5', async () => {
+        throw new Error('boom');
+      }),
+    ).rejects.toThrow('boom');
+
+    await expect(
+      locks.run('t-5', async () => 'ok', { waitMs: 100 }),
+    ).resolves.toBe('ok');
+  });
+
+  it('frees itself when the holder disappears (the time limit)', async () => {
+    await redis
+      .getClient()
+      .set('{{PROJECT_NAME_SNAKE}}:v1:lock:t-6', 'crashed-holder', 'PX', 100);
+
+    await expect(
+      locks.run('t-6', async () => 'ok', { waitMs: 1000 }),
+    ).resolves.toBe('ok');
+  });
+
+  it('does not release a lock that expired and now belongs to somebody else', async () => {
+    await locks.run(
+      't-7',
+      async () => {
+        await sleep(150); // longer than the time limit below: the lock expires meanwhile
+        await redis
+          .getClient()
+          .set('{{PROJECT_NAME_SNAKE}}:v1:lock:t-7', 'new-owner', 'PX', 5000);
+      },
+      { ttlMs: 50 },
+    );
+
+    expect(await redis.getClient().get('{{PROJECT_NAME_SNAKE}}:v1:lock:t-7')).toBe('new-owner');
+  });
+});

package/infra/redis/files/src/core/infrastructure/redis/lock/lock.service.ts

@@ -0,0 +1,82 @@
+import {
+  Injectable,
+  Logger,
+  ServiceUnavailableException,
+} from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { RedisService } from '../redis.service.js';
+import { DomainException } from '../../../domain/exceptions/domain.exception.js';
+import { CoreErrorCodes } from '../../../domain/exceptions/error-codes.js';
+
+const KEY_PREFIX = '{{PROJECT_NAME_SNAKE}}:v1:lock:';
+const POLL_INTERVAL_MS = 50;
+// Only the holder may release: a lock that expired and was taken by somebody else stays theirs
+const RELEASE_SCRIPT = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end`;
+
+export interface LockOptions {
+  /** How long the lock lives if the holder never lets go (crash). Must exceed the work. */
+  ttlMs?: number;
+  /** How long to wait for somebody else to finish before giving up with a 409. */
+  waitMs?: number;
+}
+
+/**
+ * Lets one request at a time work on one thing across all server instances, e.g. the avatar
+ * of a user: an upload and a removal arriving together then run one after the other instead
+ * of overlapping.
+ */
+@Injectable()
+export class LockService {
+  private readonly logger = new Logger(LockService.name);
+
+  constructor(private readonly redis: RedisService) {}
+
+  async run<T>(
+    name: string,
+    work: () => Promise<T>,
+    { ttlMs = 60_000, waitMs = 10_000 }: LockOptions = {},
+  ): Promise<T> {
+    const key = KEY_PREFIX + name;
+    const owner = randomUUID();
+    await this.acquire(key, owner, ttlMs, waitMs);
+    try {
+      return await work();
+    } finally {
+      await this.release(key, owner);
+    }
+  }
+
+  private async acquire(
+    key: string,
+    owner: string,
+    ttlMs: number,
+    waitMs: number,
+  ): Promise<void> {
+    const giveUpAt = Date.now() + waitMs;
+    for (;;) {
+      let taken: string | null;
+      try {
+        taken = await this.redis.getClient().set(key, owner, 'PX', ttlMs, 'NX');
+      } catch (error: any) {
+        this.logger.error(`Redis lock failed: ${error.message}`);
+        throw new ServiceUnavailableException(
+          'Service temporarily unavailable',
+        );
+      }
+      if (taken === 'OK') return;
+      if (Date.now() >= giveUpAt) {
+        throw new DomainException(CoreErrorCodes.RESOURCE_BUSY);
+      }
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+  }
+
+  private async release(key: string, owner: string): Promise<void> {
+    try {
+      await this.redis.getClient().eval(RELEASE_SCRIPT, 1, key, owner);
+    } catch (error: any) {
+      // The work is done; the lock expires by itself, so this must not turn it into a failure
+      this.logger.warn(`Releasing a lock failed: ${error.message}`);
+    }
+  }
+}

package/infra/redis/files/src/core/infrastructure/redis/rate-limit/rate-limit.module.ts

@@ -0,0 +1,15 @@
+import { Global, Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { RateLimitService } from './rate-limit.service.js';
+import { RateLimitInterceptor } from '../../../http/interceptors/rate-limit.interceptor.js';
+
+// The interceptor is global but inert: it only acts on routes carrying @RateLimit().
+@Global()
+@Module({
+  providers: [
+    RateLimitService,
+    { provide: APP_INTERCEPTOR, useClass: RateLimitInterceptor },
+  ],
+  exports: [RateLimitService],
+})
+export class RateLimitModule {}

package/infra/redis/files/src/core/infrastructure/redis/rate-limit/rate-limit.service.spec.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi } from 'vitest';
+import { RateLimitService } from './rate-limit.service.js';
+import type { RedisService } from '../redis.service.js';
+
+const serviceReturning = (count: number | Error) => {
+  const evalFn = vi.fn();
+  if (count instanceof Error) evalFn.mockRejectedValue(count);
+  else evalFn.mockResolvedValue(count);
+  const service = new RateLimitService({
+    getClient: () => ({ eval: evalFn }),
+  } as unknown as RedisService);
+  return { service, evalFn };
+};
+
+describe('RateLimitService.isAllowed', () => {
+  // limit = 5 means "5 requests allowed, the 6th is blocked" (spec SC-5).
+  // `count <= limit` — NOT `count >= limit`, which would block the 5th request.
+  it.each([1, 2, 3, 4, 5])('allows hit number %i of 5', async (count) => {
+    const { service } = serviceReturning(count);
+    await expect(service.isAllowed('k', 5, 900)).resolves.toBe(true);
+  });
+
+  it.each([6, 7, 100])('blocks hit number %i of 5', async (count) => {
+    const { service } = serviceReturning(count);
+    await expect(service.isAllowed('k', 5, 900)).resolves.toBe(false);
+  });
+
+  it('sends the bucket key and window to the atomic script', async () => {
+    const { service, evalFn } = serviceReturning(1);
+
+    await service.isAllowed('bucket-key', 3, 3600);
+
+    const [script, numKeys, key, window] = evalFn.mock.calls[0];
+    expect(script).toContain('INCR');
+    expect(script).toContain('EXPIRE');
+    expect([numKeys, key, window]).toEqual([1, 'bucket-key', 3600]);
+  });
+
+  it('rejects when Redis fails, so the caller decides whether to fail open', async () => {
+    const { service } = serviceReturning(new Error('ECONNREFUSED'));
+    await expect(service.isAllowed('k', 5, 900)).rejects.toThrow(
+      'ECONNREFUSED',
+    );
+  });
+});

package/infra/redis/files/src/core/infrastructure/redis/rate-limit/rate-limit.service.ts

@@ -0,0 +1,38 @@
+import { Injectable } from '@nestjs/common';
+import { RedisService } from '../redis.service.js';
+
+// INCR + EXPIRE in one atomic step: a crash between two separate commands
+// would leave a counter with no TTL, locking the caller out forever.
+const INCREMENT_IN_WINDOW_SCRIPT = `
+  local current = redis.call("INCR", KEYS[1])
+  if current == 1 then
+    redis.call("EXPIRE", KEYS[1], ARGV[1])
+  end
+  return current
+`;
+
+/**
+ * Fixed-window counter on Redis. The window starts at the first hit of a key
+ * and the counter expires `window` seconds later.
+ */
+@Injectable()
+export class RateLimitService {
+  constructor(private readonly redis: RedisService) {}
+
+  /**
+   * @param key    bucket key, see CACHE.RATE_LIMIT.KEYS.BUCKET
+   * @param limit  max hits allowed per window
+   * @param window window length in seconds
+   * @throws if Redis is unreachable — the caller decides whether to fail open
+   */
+  async isAllowed(
+    key: string,
+    limit: number,
+    window: number,
+  ): Promise<boolean> {
+    const count = (await this.redis
+      .getClient()
+      .eval(INCREMENT_IN_WINDOW_SCRIPT, 1, key, window)) as number;
+    return count <= limit;
+  }
+}

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

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