create-easy-stack 1.0.3

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

@@ -0,0 +1,196 @@
+import { Injectable, OnModuleDestroy, Logger } from '@nestjs/common';
+import { Redis } from 'ioredis';
+
+type TtlValue = number;
+
+@Injectable()
+export class RedisService implements OnModuleDestroy {
+  private readonly logger = new Logger(RedisService.name);
+  private readonly redisClient: Redis;
+  private inFlightRequests = new Map<string, Promise<any>>();
+  private readonly NULLABLE_SENTINEL = '__NULL_CACHE_SENTINEL__';
+
+  constructor() {
+    this.redisClient = new Redis({
+      host: process.env.REDIS_HOST || 'localhost',
+      port: Number(process.env.REDIS_PORT) || 6379,
+      db: Number(process.env.REDIS_DB) || 0,
+      connectTimeout: 5000,
+      // Without this, a command on an already-open-but-unresponsive
+      // connection (Redis wedged, network black hole, ...) hangs forever
+      // instead of rejecting — every caller here awaits these commands
+      // directly, so that would hang the HTTP request itself.
+      commandTimeout: 5000,
+    });
+  }
+
+  getClient(): Redis {
+    return this.redisClient;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      return (await this.redisClient.exists(key)) === 1;
+    } catch (error: any) {
+      this.logger.error(`Redis exists error: ${error.message}`);
+      return false;
+    }
+  }
+
+  // Health-check liveness
+  async ping(): Promise<boolean> {
+    try {
+      return (await this.redisClient.ping()) === 'PONG';
+    } catch (error: any) {
+      this.logger.error(`Redis ping error: ${error.message}`);
+      return false;
+    }
+  }
+
+  // Utils
+  private withJitter(ttl: number, percent = 0.1): number {
+    const delta = ttl * percent;
+    const jitter = Math.floor(Math.random() * delta);
+    return ttl + jitter;
+  }
+
+  private serialize(value: any): string {
+    return JSON.stringify(value);
+  }
+
+  private deserialize<T>(value: string | null): T | null {
+    if (!value) return null;
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  // Base cache
+  async get<T>(key: string): Promise<T | null> {
+    try {
+      const data = await this.redisClient.get(key);
+      return this.deserialize<T>(data);
+    } catch (error: any) {
+      this.logger.error(`Redis get error: ${error.message}`);
+      return null;
+    }
+  }
+
+  async set(key: string, value: any, ttl?: TtlValue): Promise<void> {
+    try {
+      if (ttl) {
+        const finalTtl = this.withJitter(ttl);
+        await this.redisClient.set(key, this.serialize(value), 'EX', finalTtl);
+      } else {
+        await this.redisClient.set(key, this.serialize(value));
+      }
+    } catch (error: any) {
+      this.logger.error(`Redis set error: ${error.message}`);
+    }
+  }
+
+  async del(key: string): Promise<void> {
+    try {
+      await this.redisClient.del(key);
+    } catch (error: any) {
+      this.logger.error(`Redis del error: ${error.message}`);
+    }
+  }
+
+  // Tracker (version)
+  async getVersion(trackerKey: string): Promise<number> {
+    const version = await this.redisClient.get(trackerKey);
+    return version ? Number(version) : 0;
+  }
+
+  async bumpVersion(trackerKey: string): Promise<number> {
+    return this.redisClient.incr(trackerKey);
+  }
+
+  // Detail cache (Singleflight)
+  async getOrSetDetail<T>(
+    key: string,
+    ttl: TtlValue,
+    fetcher: () => Promise<T>,
+  ): Promise<T> {
+    // 1. Check cache
+    const cached = await this.get<T>(key);
+    if (cached) return cached;
+
+    // 2. Singleflight
+    if (this.inFlightRequests.has(key)) {
+      this.logger.debug(
+        `Singleflight: Waiting for in-flight request for key: ${key}`,
+      );
+      return this.inFlightRequests.get(key);
+    }
+
+    // 3. Perform fetch
+    const fetchPromise = fetcher()
+      .then(async (data) => {
+        if (data) {
+          await this.set(key, data, ttl);
+        }
+        this.inFlightRequests.delete(key);
+        return data;
+      })
+      .catch((err) => {
+        this.inFlightRequests.delete(key);
+        throw err;
+      });
+
+    this.inFlightRequests.set(key, fetchPromise);
+    return fetchPromise;
+  }
+
+  // Nullable Cache (cache cả null để chống cache penetration)
+  async getOrSetNullableDetail<T>(
+    key: string,
+    ttl: TtlValue,
+    fetcher: () => Promise<T | null>,
+  ): Promise<T | null> {
+    const cachedStr = await this.redisClient.get(key);
+    if (cachedStr === this.NULLABLE_SENTINEL) return null;
+
+    const cached = this.deserialize<T>(cachedStr);
+    if (cached) return cached;
+
+    if (this.inFlightRequests.has(key)) {
+      return this.inFlightRequests.get(key);
+    }
+
+    const fetchPromise = fetcher()
+      .then(async (data) => {
+        if (data !== null && data !== undefined) {
+          await this.set(key, data, ttl);
+        } else {
+          const finalTtl = this.withJitter(ttl);
+          await this.redisClient.set(
+            key,
+            this.NULLABLE_SENTINEL,
+            'EX',
+            finalTtl,
+          );
+        }
+        this.inFlightRequests.delete(key);
+        return data;
+      })
+      .catch((err) => {
+        this.inFlightRequests.delete(key);
+        throw err;
+      });
+
+    this.inFlightRequests.set(key, fetchPromise);
+    return fetchPromise;
+  }
+
+  async invalidateDetail(key: string) {
+    await this.del(key);
+  }
+
+  async onModuleDestroy() {
+    await this.redisClient.quit();
+  }
+}

package/infra/redis/infra.json

@@ -0,0 +1,53 @@
+{
+  "id": "redis",
+  "label": "Redis (cache, distributed lock, rate-limit, idempotency)",
+  "default": true,
+  "templates": ["nest-ddd"],
+  "dependencies": {
+    "ioredis": "^6.0.0"
+  },
+  "env": [
+    "# Redis (docker-compose.yml)",
+    "REDIS_HOST=localhost",
+    "REDIS_PORT=6379",
+    "REDIS_DB=0"
+  ],
+  "docker": {
+    "file": "docker.service.yml",
+    "volumes": ["redis_data"]
+  },
+  "inject": [
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:imports",
+      "lines": [
+        "import { RedisModule } from './core/infrastructure/redis/redis.module.js';",
+        "import { IdempotencyModule } from './core/infrastructure/redis/idempotency/idempotency.module.js';",
+        "import { RateLimitModule } from './core/infrastructure/redis/rate-limit/rate-limit.module.js';",
+        "import { LockModule } from './core/infrastructure/redis/lock/lock.module.js';"
+      ]
+    },
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:modules",
+      "lines": ["RedisModule,", "IdempotencyModule,", "RateLimitModule,", "LockModule,"]
+    },
+    {
+      "file": "src/core/index.ts",
+      "marker": "// @infra:barrel",
+      "lines": [
+        "export * from './infrastructure/redis/cache.constants.js';",
+        "export * from './infrastructure/redis/redis.service.js';",
+        "export * from './infrastructure/redis/redis.module.js';",
+        "export * from './infrastructure/redis/idempotency/idempotency.service.js';",
+        "export * from './infrastructure/redis/idempotency/idempotency.module.js';",
+        "export * from './infrastructure/redis/rate-limit/rate-limit.service.js';",
+        "export * from './infrastructure/redis/rate-limit/rate-limit.module.js';",
+        "export * from './infrastructure/redis/lock/lock.service.js';",
+        "export * from './infrastructure/redis/lock/lock.module.js';",
+        "export * from './http/interceptors/rate-limit.interceptor.js';",
+        "export * from './http/decorators/rate-limit.decorator.js';"
+      ]
+    }
+  ]
+}

package/infra/storage-cloudinary/files/src/core/config/storage.env.ts

@@ -0,0 +1,43 @@
+// Cloudinary is optional, but its three settings go together
+const CLOUDINARY_VARS = [
+  'CLOUDINARY_CLOUD_NAME',
+  'CLOUDINARY_API_KEY',
+  'CLOUDINARY_API_SECRET',
+];
+const CLOUDINARY_CLOUD_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+// A folder path such as app/avatars: letters, digits, _ and -, parts separated by one slash
+const CLOUDINARY_FOLDER_PATTERN = /^[A-Za-z0-9_-]+(\/[A-Za-z0-9_-]+)*$/;
+
+const present = (config: Record<string, unknown>, name: string) =>
+  typeof config[name] === 'string' && (config[name] as string).trim() !== '';
+
+/** Image storage is optional; when any setting is given, all three are needed and must look right. */
+export function validateStorageEnv(
+  config: Record<string, unknown>,
+  errors: string[],
+): void {
+  const given = CLOUDINARY_VARS.filter((name) => present(config, name));
+
+  if (given.length > 0 && given.length < CLOUDINARY_VARS.length) {
+    const missing = CLOUDINARY_VARS.filter((name) => !present(config, name));
+    errors.push(
+      `${CLOUDINARY_VARS.join(', ')} must all be set together, or none of them (missing: ${missing.join(', ')})`,
+    );
+  } else if (
+    present(config, 'CLOUDINARY_CLOUD_NAME') &&
+    !CLOUDINARY_CLOUD_NAME_PATTERN.test(
+      (config.CLOUDINARY_CLOUD_NAME as string).trim(),
+    )
+  ) {
+    errors.push('CLOUDINARY_CLOUD_NAME may only contain letters, digits, _ and -');
+  }
+
+  if (
+    present(config, 'CLOUDINARY_FOLDER') &&
+    !CLOUDINARY_FOLDER_PATTERN.test((config.CLOUDINARY_FOLDER as string).trim())
+  ) {
+    errors.push(
+      'CLOUDINARY_FOLDER must look like app/avatars: letters, digits, _ and -, separated by single slashes',
+    );
+  }
+}

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/cloudinary-image-storage.spec.ts

@@ -0,0 +1,275 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Logger } from '@nestjs/common';
+import {
+  CloudinaryImageStorage,
+  type CloudinaryClient,
+} from './cloudinary-image-storage.js';
+import { UnconfiguredImageStorage } from './unconfigured-image-storage.js';
+import {
+  cloudinarySettingsFromEnv,
+  createImageStorage,
+} from './image-storage.factory.js';
+import type { ImageFit, ImageType } from './image-storage.port.js';
+
+const SETTINGS = {
+  cloudName: 'demo',
+  apiKey: '123456',
+  apiSecret: 'super-secret-value',
+  folder: 'ecom',
+};
+const GOOD_ADDRESS =
+  'https://res.cloudinary.com/demo/image/upload/v1/ecom/avatars/u-1.png';
+const AVATAR_FIT: ImageFit = {
+  width: 256,
+  height: 256,
+  crop: 'fill',
+  focus: 'face',
+};
+const code = (promise: Promise<unknown>) =>
+  promise.then(
+    () => 'resolved',
+    (e: any) => e.code ?? e.constructor.name,
+  );
+
+describe('CloudinaryImageStorage', () => {
+  let client: {
+    upload: ReturnType<typeof vi.fn>;
+    destroy: ReturnType<typeof vi.fn>;
+  };
+  let logged: string[];
+  const storage = () =>
+    new CloudinaryImageStorage(SETTINGS, client as unknown as CloudinaryClient);
+  const upload = (
+    options: {
+      type?: ImageType;
+      path?: string;
+      fit?: ImageFit;
+    } = {},
+  ) =>
+    storage().upload({
+      path: options.path ?? 'avatars/u-1',
+      image: Buffer.from('FILE-CONTENT'),
+      type: options.type ?? 'png',
+      fit: options.fit ?? AVATAR_FIT,
+    });
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    logged = [];
+    vi.spyOn(Logger.prototype, 'error').mockImplementation((m: any) => {
+      logged.push(String(m));
+    });
+    client = {
+      upload: vi.fn().mockResolvedValue({ secure_url: GOOD_ADDRESS }),
+      destroy: vi.fn().mockResolvedValue({ result: 'ok' }),
+    };
+  });
+
+  it('stores the picture under the app folder at the given path, replacing what was there', async () => {
+    expect(await upload()).toBe(GOOD_ADDRESS);
+
+    const [image, options] = client.upload.mock.calls[0];
+    expect(image.toString()).toBe('FILE-CONTENT');
+    expect(options).toMatchObject({
+      public_id: 'ecom/avatars/u-1',
+      overwrite: true,
+      invalidate: true,
+      allowed_formats: ['png'],
+    });
+    expect(options.timeout).toBeGreaterThan(0);
+  });
+
+  it('cuts to a square around the face when asked to', async () => {
+    await upload();
+
+    expect(client.upload.mock.calls[0][1].transformation).toEqual([
+      {
+        width: 256,
+        height: 256,
+        crop: 'fill',
+        gravity: 'face',
+        quality: 'auto',
+      },
+    ]);
+  });
+
+  it('shrinks to fit without enlarging, or fills from the centre, when asked to', async () => {
+    await upload({ fit: { width: 800, height: 800, crop: 'limit' } });
+    await upload({
+      fit: { width: 100, height: 50, crop: 'fill', focus: 'center' },
+    });
+
+    const [limit, center] = client.upload.mock.calls.map(
+      (call) => call[1].transformation[0],
+    );
+    expect(limit).toEqual({
+      width: 800,
+      height: 800,
+      crop: 'limit',
+      quality: 'auto',
+    });
+    expect(center).not.toHaveProperty('gravity');
+    expect(center).toMatchObject({ crop: 'fill', width: 100, height: 50 });
+  });
+
+  it('names a JPEG the way Cloudinary does', async () => {
+    await upload({ type: 'jpeg' });
+
+    expect(client.upload.mock.calls[0][1].allowed_formats).toEqual(['jpg']);
+  });
+
+  it.each([
+    ['another cloud', 'https://res.cloudinary.com/other/image/upload/a.png'],
+    [
+      'a plain http address',
+      'http://res.cloudinary.com/demo/image/upload/a.png',
+    ],
+    ['another host', 'https://evil.example.com/demo/a.png'],
+    ['a look-alike host', 'https://res.cloudinary.com.evil.example/demo/a.png'],
+    ['nothing', undefined],
+  ])('does not trust an answer pointing at %s', async (_name, url) => {
+    client.upload.mockResolvedValue({ secure_url: url });
+
+    expect(await code(upload())).toBe('STO-002');
+  });
+
+  it('turns "Cloudinary cannot read this as an image" (400) into STO-003', async () => {
+    client.upload.mockRejectedValue({
+      message: 'Invalid image file',
+      http_code: 400,
+    });
+
+    expect(await code(upload())).toBe('STO-003');
+  });
+
+  it.each([
+    ['a network failure', new Error('socket hang up')],
+    ['a timeout', { message: 'Request Timeout', http_code: 499 }],
+    ['wrong keys', { message: 'Invalid Signature', http_code: 401 }],
+    ['no reason at all', undefined],
+  ])('answers STO-002 for %s', async (_name, failure) => {
+    client.upload.mockRejectedValue(failure);
+
+    expect(await code(upload())).toBe('STO-002');
+  });
+
+  it('logs only the reason of a failure, not the keys or the file', async () => {
+    client.upload.mockRejectedValue(new Error('socket hang up'));
+
+    await upload().catch(() => undefined);
+
+    const everything = logged.join('\n');
+    expect(everything).toContain('socket hang up');
+    for (const secret of [
+      SETTINGS.apiSecret,
+      SETTINGS.apiKey,
+      'FILE-CONTENT',
+    ]) {
+      expect(everything).not.toContain(secret);
+    }
+  });
+
+  it('leaves a trace in the log when Cloudinary calls the file unreadable, since our own options can cause that too', async () => {
+    client.upload.mockRejectedValue({
+      message: 'Invalid transformation',
+      http_code: 400,
+    });
+    const warnings: string[] = [];
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation((m: any) => {
+      warnings.push(String(m));
+    });
+
+    await upload().catch(() => undefined);
+
+    expect(warnings.join(String.fromCharCode(10))).toContain(
+      'Invalid transformation',
+    );
+    expect(warnings.join(String.fromCharCode(10))).not.toContain(
+      'FILE-CONTENT',
+    );
+  });
+
+  it.each([
+    '',
+    '/avatars/u-1',
+    'avatars/',
+    'avatars//u-1',
+    '../secret',
+    'avatars/u 1',
+    'avatars/u-1.png',
+  ])('refuses the path %j, which is a bug in the caller', async (path) => {
+    await expect(upload({ path })).rejects.toThrow(/Invalid image path/);
+    await expect(storage().delete(path)).rejects.toThrow(/Invalid image path/);
+    expect(client.upload).not.toHaveBeenCalled();
+    expect(client.destroy).not.toHaveBeenCalled();
+  });
+
+  it('removes the picture at the same place and clears the cache', async () => {
+    await storage().delete('avatars/u-1');
+
+    expect(client.destroy).toHaveBeenCalledWith('ecom/avatars/u-1', {
+      invalidate: true,
+      timeout: expect.any(Number),
+    });
+  });
+
+  it('answers STO-002 when removing fails', async () => {
+    client.destroy.mockRejectedValue(new Error('down'));
+
+    expect(await code(storage().delete('avatars/u-1'))).toBe('STO-002');
+  });
+});
+
+describe('UnconfiguredImageStorage', () => {
+  it('refuses to upload with STO-001 and has nothing to remove, without an error', async () => {
+    const storage = new UnconfiguredImageStorage();
+
+    expect(
+      await code(
+        storage.upload({
+          path: 'avatars/u-1',
+          image: Buffer.from('x'),
+          type: 'png',
+          fit: AVATAR_FIT,
+        }),
+      ),
+    ).toBe('STO-001');
+    await expect(storage.delete('avatars/u-1')).resolves.toBeUndefined();
+  });
+});
+
+describe('image storage choice', () => {
+  const ENV = {
+    CLOUDINARY_CLOUD_NAME: ' demo ',
+    CLOUDINARY_API_KEY: '123456',
+    CLOUDINARY_API_SECRET: 'super-secret-value',
+  };
+
+  it('uses Cloudinary when all three settings are present, with the default folder', () => {
+    expect(cloudinarySettingsFromEnv(ENV)).toEqual({
+      cloudName: 'demo',
+      apiKey: '123456',
+      apiSecret: 'super-secret-value',
+      folder: '{{PROJECT_NAME}}',
+    });
+    expect(createImageStorage(ENV)).toBeInstanceOf(CloudinaryImageStorage);
+  });
+
+  it('takes the folder from CLOUDINARY_FOLDER', () => {
+    const settings = cloudinarySettingsFromEnv({
+      ...ENV,
+      CLOUDINARY_FOLDER: 'shop/dev',
+    });
+
+    expect(settings?.folder).toBe('shop/dev');
+  });
+
+  it.each([
+    {},
+    { CLOUDINARY_CLOUD_NAME: 'demo' },
+    { ...ENV, CLOUDINARY_API_SECRET: '  ' },
+  ])('falls back to "not configured" for %j', (env) => {
+    expect(cloudinarySettingsFromEnv(env)).toBeNull();
+    expect(createImageStorage(env)).toBeInstanceOf(UnconfiguredImageStorage);
+  });
+});