create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/task-queue.processor.ts

@@ -0,0 +1,75 @@
+import { OnWorkerEvent, Processor, WorkerHost } from '@nestjs/bullmq'
+import { Logger } from '@nestjs/common'
+import { type Job, UnrecoverableError } from 'bullmq'
+import { TASK_JOB_NAMES, TASK_QUEUE_CONCURRENCY, TASK_QUEUE_NAME } from './task-queue.constants'
+import { QueueSmokePayloadSchema } from './task-queue.contracts'
+
+@Processor(TASK_QUEUE_NAME, { concurrency: TASK_QUEUE_CONCURRENCY })
+export class TaskQueueProcessor extends WorkerHost {
+  private readonly logger = new Logger(TaskQueueProcessor.name)
+
+  /**
+   * 按任务名称校验并执行队列任务，冒烟任务返回标记及处理时间。
+   * @throws 未知任务或无效负载抛出 UnrecoverableError，阻止无意义的自动重试。
+   */
+  async process(job: Job): Promise<unknown> {
+    switch (job.name) {
+      case TASK_JOB_NAMES.QUEUE_SMOKE: {
+        const parsed = QueueSmokePayloadSchema.safeParse(job.data)
+
+        if (!parsed.success) {
+          throw new UnrecoverableError('Invalid payload for ' + job.name)
+        }
+
+        return {
+          marker: parsed.data.marker,
+          processedAt: new Date().toISOString(),
+        }
+      }
+
+      default:
+        throw new UnrecoverableError('Unsupported task name: ' + job.name)
+    }
+  }
+
+  /**
+   * 记录任务完成事件及任务标识，便于按队列和尝试次数追踪处理结果。
+   */
+  @OnWorkerEvent('completed')
+  onCompleted(job: Job) {
+    this.logger.log({
+      event: 'queue_job_completed',
+      queueName: TASK_QUEUE_NAME,
+      jobId: job.id,
+      jobName: job.name,
+      attemptsMade: job.attemptsMade,
+    })
+  }
+
+  /**
+   * 记录任务失败事件，允许任务记录缺失，并仅输出错误名称。
+   */
+  @OnWorkerEvent('failed')
+  onFailed(job: Job | undefined, error: Error) {
+    this.logger.error({
+      event: 'queue_job_failed',
+      queueName: TASK_QUEUE_NAME,
+      jobId: job?.id,
+      jobName: job?.name,
+      attemptsMade: job?.attemptsMade,
+      errorName: error.name,
+    })
+  }
+
+  /**
+   * 记录 Worker 运行错误的名称，便于定位消费者基础设施故障。
+   */
+  @OnWorkerEvent('error')
+  onWorkerError(error: Error) {
+    this.logger.error({
+      event: 'queue_worker_error',
+      queueName: TASK_QUEUE_NAME,
+      errorName: error.name,
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/task-queue.service.ts

@@ -0,0 +1,67 @@
+import { InjectQueue } from '@nestjs/bullmq'
+import { Injectable } from '@nestjs/common'
+import type { JobsOptions, Queue } from 'bullmq'
+import { TASK_QUEUE_NAME } from './task-queue.constants'
+import {
+  type EnqueuedTask,
+  type EnqueueTaskOptions,
+  parseTaskPayload,
+  type TaskName,
+  type TaskPayloadMap,
+} from './task-queue.contracts'
+
+@Injectable()
+export class TaskQueueService {
+  constructor(
+    @InjectQueue(TASK_QUEUE_NAME)
+    private readonly queue: Queue,
+  ) {}
+
+  /**
+   * 校验任务负载与投递选项后，将任务写入 BullMQ 队列。
+   * @param options 可指定任务 ID 和延迟毫秒数。
+   * @returns 可用于跟踪任务的队列名、任务 ID 和任务名称。
+   * @throws 负载或选项无效、投递失败或队列未返回任务 ID 时抛出错误。
+   */
+  async enqueue<Name extends TaskName>(
+    name: Name,
+    payload: TaskPayloadMap[Name],
+    options: EnqueueTaskOptions = {},
+  ): Promise<EnqueuedTask<Name>> {
+    this.validateOptions(options)
+
+    const data = parseTaskPayload(name, payload)
+    const jobOptions: JobsOptions = {
+      ...(options.jobId === undefined ? {} : { jobId: options.jobId }),
+      ...(options.delayMs === undefined ? {} : { delay: options.delayMs }),
+    }
+
+    const job = await this.queue.add(name, data, jobOptions)
+
+    if (job.id === undefined) {
+      throw new Error('BullMQ returned a Job without an id')
+    }
+
+    return {
+      queueName: TASK_QUEUE_NAME,
+      jobId: job.id,
+      name,
+    }
+  }
+
+  /**
+   * 检查任务 ID 不含冒号，且延迟为非负安全整数；不满足 BullMQ 约束时抛出错误。
+   */
+  private validateOptions(options: EnqueueTaskOptions) {
+    if (options.jobId?.includes(':')) {
+      throw new Error('BullMQ jobId must not contain a colon')
+    }
+
+    if (
+      options.delayMs !== undefined &&
+      (!Number.isSafeInteger(options.delayMs) || options.delayMs < 0)
+    ) {
+      throw new Error('delayMs must be a non-negative safe integer')
+    }
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/db/db.controller.ts

@@ -8,18 +8,27 @@ import { CreateUserDto } from './dto/create-user.dto'
 export class DbController {
   constructor(private readonly dbService: DbService) {}
 
+  /**
+   * 返回数据库当前时间，供 HTTP 层验证数据库连通性。
+   */
   @ApiOperation({ summary: '测试数据库连接' })
   @Get()
   async ping() {
     return { time: await this.dbService.ping() }
   }
 
+  /**
+   * 返回数据库示例服务查询的全部用户记录。
+   */
   @ApiOperation({ summary: '获取所有用户' })
   @Get('users')
   async list() {
     return this.dbService.findAll()
   }
 
+  /**
+   * 将经 DTO 校验的请求体提交给数据库示例服务创建用户。
+   */
   @ApiOperation({ summary: '创建用户' })
   @Post('user')
   async create(@Body() body: CreateUserDto) {

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/db/db.service.ts

@@ -6,15 +6,24 @@ import { users } from '@/database/schema'
 export class DbService {
   constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
 
+  /**
+   * 查询数据库当前时间以验证 PostgreSQL 连接可用。
+   */
   async ping() {
     const res = await this.db.execute('SELECT now() AS now')
     return res.rows[0]
   }
 
+  /**
+   * 读取全部用户记录，供数据库示例接口联调使用。
+   */
   async findAll() {
     return this.db.query.users.findMany()
   }
 
+  /**
+   * 插入示例用户资料并返回数据库生成的完整记录。
+   */
   async create(data: Omit<typeof users.$inferInsert, 'id' | 'createdAt'>) {
     const [row] = await this.db.insert(users).values(data).returning()
     return row

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/error-catelog.spec.ts

@@ -0,0 +1,34 @@
+import { COMMON_ERRORS } from '@/common/error/common.error'
+import { AUTH_ERRORS } from '@/modules/auth/auth.errors'
+import { describe, expect, it } from 'vite-plus/test'
+import { UPLOAD_ERRORS } from '../upload/upload.errors'
+
+const definitions = [
+  ...Object.values(COMMON_ERRORS),
+  ...Object.values(AUTH_ERRORS),
+  ...Object.values(UPLOAD_ERRORS),
+]
+
+describe('error catelog', () => {
+  it('uses valid and globally unique error codes', () => {
+    const codes = definitions.map((definition) => definition.code)
+    expect(new Set(codes).size).toBe(codes.length)
+
+    for (const definition of definitions) {
+      expect(definition.code).toMatch(/^[A-Z][A-Z0-9_]*(?:\.[A-Z][A-Z0-9_]*)+$/)
+      expect(definition.code.length).toBeLessThanOrEqual(80)
+      expect(definition.status).toBeGreaterThanOrEqual(400)
+      expect(definition.status).toBeLessThanOrEqual(599)
+      expect(definition.publicMessage.trim()).not.toBe('')
+    }
+  })
+
+  it('keeps bearerChallenge and HTTP 401 in sync', () => {
+    for (const definition of definitions) {
+      const hasBearerChallenge =
+        'bearerChallenge' in definition && definition.bearerChallenge === true
+
+      expect(hasBearerChallenge).toBe(definition.status === 401)
+    }
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/redis/redis.controller.ts

@@ -8,6 +8,9 @@ import { GetQueryDto, SetQueryDto } from './dto/redis-quary.dto'
 export class RedisController {
   constructor(private readonly redisService: RedisService) {}
 
+  /**
+   * 调用 Redis 连通性探测并将结果包装为 HTTP 响应。
+   */
   @ApiOperation({ summary: '测试 Redis 连接' })
   @Get('ping')
   async ping() {
@@ -15,6 +18,9 @@ export class RedisController {
   }
 
   // GET /redis/set?key=name&value=tom&ttl=60
+  /**
+   * 接收 Redis 测试键值和可选有效期，写入后返回提交的信息。
+   */
   @ApiOperation({ summary: '设置键值对' })
   @Post('set')
   async set(@Body() body: SetQueryDto) {
@@ -23,6 +29,9 @@ export class RedisController {
   }
 
   // GET /redis/get?key=name
+  /**
+   * 读取测试查询指定的 Redis 键，并返回键名及当前值。
+   */
   @ApiOperation({ summary: '获取键值对' })
   @Get('get')
   async get(@Query('key') query: GetQueryDto) {

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/redis/redis.service.ts

@@ -6,10 +6,16 @@ import Redis from 'ioredis'
 export class RedisService {
   constructor(@InjectRedis() private readonly redis: Redis) {}
 
+  /**
+   * 执行 Redis PING，验证当前连接可用。
+   */
   async ping() {
     return this.redis.ping()
   }
 
+  /**
+   * 写入字符串键值，可按秒设置正数有效期；未提供有效 TTL 时永久保存。
+   */
   async set(key: string, value: string, ttlSeconds?: number) {
     if (ttlSeconds && ttlSeconds > 0) {
       await this.redis.set(key, value, 'EX', ttlSeconds)
@@ -19,18 +25,30 @@ export class RedisService {
     return 'Ok'
   }
 
+  /**
+   * 读取字符串键的值，键不存在时返回 null。
+   */
   async get(key: string) {
     return this.redis.get(key)
   }
 
+  /**
+   * 删除指定 Redis 键并返回实际删除数量。
+   */
   async del(key: string) {
     return this.redis.del(key)
   }
 
+  /**
+   * 检查指定 Redis 键是否存在并返回布尔结果。
+   */
   async exist(key: string) {
     return (await this.redis.exists(key)) === 1
   }
 
+  /**
+   * 按 Redis 通配模式列出匹配键，供开发联调检查数据使用。
+   */
   async keys(pattern: string) {
     return this.redis.keys(pattern)
   }

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/dto/initiate-mutipart-upload.dto.ts

@@ -0,0 +1,26 @@
+import { createZodDto } from 'nestjs-zod'
+import z from 'zod'
+
+export const initiateMultipartUploadSchema = z
+  .object({
+    clientUploadId: z.uuid(),
+    fileName: z
+      .string()
+      .trim()
+      .min(1)
+      .max(255)
+      .refine((value) => !/[\u0000-\u001F\u007F]/u.test(value), 'fileName 不能包含控制字符'),
+    fileSize: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    contentType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(255)
+      .regex(
+        /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/,
+        'contentType 必须是安全的 MIME media type，例如 image/png',
+      ),
+  })
+  .strict()
+
+export class InitiateMultipartUploadDto extends createZodDto(initiateMultipartUploadSchema) {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/dto/upload-params.dto.ts

@@ -0,0 +1,15 @@
+import { createZodDto } from 'nestjs-zod'
+import z from 'zod'
+import { UPLOAD_MAX_PARTS } from '../upload.constants'
+
+export const uploadSessionParamsSchema = z.object({
+  uploadSessionId: z.uuid(),
+})
+
+export const uploadPartParamsSchema = uploadSessionParamsSchema.extend({
+  partNumber: z.coerce.number().int().min(1).max(UPLOAD_MAX_PARTS),
+})
+
+export class UploadSessionParamsDto extends createZodDto(uploadSessionParamsSchema) {}
+
+export class UploadPartParamsDto extends createZodDto(uploadPartParamsSchema) {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/storage/exact-size.transform.ts

@@ -0,0 +1,77 @@
+import { TransformCallback } from 'node:stream'
+import { Transform } from 'stream'
+
+export class ExactSizeError extends Error {
+  /**
+   * 记录期望与实际字节数，使上层能够识别上传内容长度不匹配。
+   */
+  constructor(
+    readonly expectedBytes: number,
+    readonly receivedBytes: number,
+  ) {
+    super(`Expected ${expectedBytes} bytes, recevied ${receivedBytes}`)
+    this.name = ExactSizeError.name
+  }
+}
+
+export class ExactSizeTransform extends Transform {
+  receivedBytes = 0
+
+  /**
+   * 记录流所要求的精确字节数，用于后续长度验证。
+   */
+  constructor(private readonly expectedBytes: number) {
+    super()
+  }
+
+  /**
+   * 累计并透传数据块；一旦实际字节数超过期望值，立即通过回调使流失败。
+   */
+  override _transform(chunk: any, encoding: BufferEncoding, callback: TransformCallback): void {
+    const byteLength = Buffer.isBuffer(chunk)
+      ? chunk.length
+      : Buffer.byteLength(String(chunk), encoding)
+    this.receivedBytes += byteLength
+
+    if (this.receivedBytes > this.expectedBytes) {
+      callback(new ExactSizeError(this.expectedBytes, this.receivedBytes))
+      return
+    }
+
+    callback(null, chunk)
+  }
+
+  /**
+   * 在输入流结束时核对总字节数，发现不足或不一致时通过回调报告长度错误。
+   * @param callback 通知流框架完成刷新，或传递长度校验异常。
+   */
+  override _flush(callback: TransformCallback): void {
+    if (this.receivedBytes !== this.expectedBytes) {
+      callback(new ExactSizeError(this.expectedBytes, this.receivedBytes))
+      return
+    }
+
+    callback()
+  }
+}
+
+/**
+ * 沿最多八层 cause 链查找长度校验异常，未找到时返回 null。
+ */
+export function findExactSizeError(cause: unknown): ExactSizeError | null {
+  let current = cause
+
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (current instanceof ExactSizeError) {
+      return current
+    }
+
+    if (typeof current !== 'object' || current === null || !('cause' in current)) {
+      return null
+    }
+
+    current = current.cause
+  }
+
+  return null
+}