create-bubbles 0.1.25 → 0.1.26

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/dto/auth-repsponse.dto.ts

@@ -2,7 +2,7 @@ import { createZodDto } from 'nestjs-zod'
 import z from 'zod'
 
 const authUserSchema = z.object({
-  id: z.string().uuid(),
+  id: z.uuid(),
   account: z.string(),
   name: z.string(),
 })
@@ -14,7 +14,7 @@ export class LoginResultDto extends createZodDto(
     accessToken: z.string().min(1),
     tokenType: z.literal('Bearer'),
     idleExpiresIn: z.number().int().positive(),
-    absoluteExpiresAt: z.string().datetime(),
+    absoluteExpiresAt: z.iso.datetime(),
   }),
 ) {}
 

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

@@ -0,0 +1,24 @@
+import { BullRegistrar } from '@nestjs/bullmq'
+import { Injectable, type OnApplicationBootstrap } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+
+@Injectable()
+export class QueueWorkerBootstrap implements OnApplicationBootstrap {
+  private registered = false
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly registrar: BullRegistrar,
+  ) {}
+
+  onApplicationBootstrap() {
+    const workerEnabled = this.config.getOrThrow<boolean>('queue.workerEnabled')
+
+    if (!workerEnabled || this.registered) {
+      return
+    }
+
+    this.registrar.register()
+    this.registered = true
+  }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * BullMQ 队列名称。
+ *
+ * 在 BullModule.registerQueue 注册、@InjectQueue 注入与 @Processor 绑定时共用，
+ * 同时作为契约层的队列标识（见 EnqueuedTask.queueName）。
+ */
+export const TASK_QUEUE_NAME = 'server-tasks'
+
+/**
+ * Worker 并发数：单个 Processor 实例同时处理的任务数上限。
+ */
+export const TASK_QUEUE_CONCURRENCY = 5
+
+/**
+ * 任务名称注册表（全部任务的唯一来源）。
+ *
+ * 命名遵循 `域.动作.版本` 格式（如 `system.queue-smoke.v1`）。
+ * 新增任务时在此登记，并需在 contracts 中同步补充对应的 payload 契约
+ * （TaskPayloadMap 与 TASK_PAYLOAD_SCHEMAS）。
+ */
+export const TASK_JOB_NAMES = {
+  /** 队列连通性冒烟测试任务。 */
+  QUEUE_SMOKE: 'system.queue-smoke.v1',
+} as const

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

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { TASK_JOB_NAMES, TASK_QUEUE_NAME } from './task-queue.constants'
+
+export const QueueSmokePayloadSchema = z.object({
+  marker: z.string().min(1).max(100),
+  enqueuedAt: z.iso.datetime(),
+})
+
+export type TaskName = (typeof TASK_JOB_NAMES)[keyof typeof TASK_JOB_NAMES]
+
+export interface TaskPayloadMap {
+  [TASK_JOB_NAMES.QUEUE_SMOKE]: z.infer<typeof QueueSmokePayloadSchema>
+}
+
+export const TASK_PAYLOAD_SCHEMAS = {
+  [TASK_JOB_NAMES.QUEUE_SMOKE]: QueueSmokePayloadSchema,
+} satisfies Record<TaskName, z.ZodType>
+
+export function parseTaskPayload<Name extends TaskName>(
+  name: Name,
+  payload: unknown,
+): TaskPayloadMap[Name] {
+  return TASK_PAYLOAD_SCHEMAS[name].parse(payload) as TaskPayloadMap[Name]
+}
+
+export interface EnqueueTaskOptions {
+  jobId?: string
+  delayMs?: number
+}
+
+export interface EnqueuedTask<Name extends TaskName = TaskName> {
+  queueName: typeof TASK_QUEUE_NAME
+  jobId: string
+  name: Name
+}

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

@@ -0,0 +1,56 @@
+import { BullModule } from '@nestjs/bullmq'
+import { Module } from '@nestjs/common'
+import { ConfigModule, ConfigService } from '@nestjs/config'
+import type { QueueConfig } from '@/config/queue.config'
+import { QueueWorkerBootstrap } from './queue-worker.bootstrap'
+import { TASK_QUEUE_NAME } from './task-queue.constants'
+import { TaskQueueProcessor } from './task-queue.processor'
+import { TaskQueueService } from './task-queue.service'
+
+@Module({
+  imports: [
+    BullModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => {
+        const queue = config.getOrThrow<QueueConfig>('queue')
+
+        return {
+          connection: {
+            host: queue.host,
+            port: queue.port,
+            username: queue.username,
+            password: queue.password,
+            db: queue.db,
+            connectTimeout: 10_000,
+          },
+          prefix: queue.prefix,
+          defaultJobOptions: {
+            attempts: queue.defaultAttempts,
+            backoff: {
+              type: 'exponential',
+              delay: queue.backoffDelayMs,
+            },
+            removeOnComplete: {
+              age: queue.completedAgeSeconds,
+              count: queue.completedCount,
+            },
+            removeOnFail: {
+              age: queue.failedAgeSeconds,
+              count: queue.failedCount,
+            },
+          },
+        }
+      },
+      extraOptions: {
+        manualRegistration: true,
+      },
+    }),
+    BullModule.registerQueue({
+      name: TASK_QUEUE_NAME,
+    }),
+  ],
+  providers: [QueueWorkerBootstrap, TaskQueueProcessor, TaskQueueService],
+  exports: [TaskQueueService],
+})
+export class TaskQueueModule {}

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

@@ -0,0 +1,62 @@
+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)
+
+  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,
+    })
+  }
+
+  @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,58 @@
+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,
+  ) {}
+
+  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,
+    }
+  }
+
+  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/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/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(uploadPartParamsSchema) {}
+
+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,66 @@
+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
+   * @returns
+   */
+  override _flush(callback: TransformCallback): void {
+    if (this.receivedBytes !== this.expectedBytes) {
+      callback(new ExactSizeError(this.expectedBytes, this.receivedBytes))
+      return
+    }
+
+    callback()
+  }
+}
+
+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
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/storage/minio-storage.adapter.ts

@@ -0,0 +1,239 @@
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  ListPartsCommand,
+  S3Client,
+  UploadPartCommand,
+} from '@aws-sdk/client-s3'
+import { Injectable, OnModuleDestroy } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import {
+  CreateMultipartInput,
+  MultipartIdentity,
+  StorageMultipartNotFoundError,
+  StorageObject,
+  StoragePart,
+  StoragePort,
+  UploadPartInput,
+} from './storage.port'
+
+function hasErrorName(cause: unknown, expected: string): boolean {
+  if (typeof cause !== 'object' || cause === null) {
+    return false
+  }
+  const record = cause as { name?: unknown; Code?: unknown }
+  return record.name === expected || record.Code === expected
+}
+
+function throwMappedMultipartError(cause: unknown): never {
+  if (hasErrorName(cause, 'NoSuchUpload')) {
+    throw new StorageMultipartNotFoundError(cause)
+  }
+
+  throw cause
+}
+
+@Injectable()
+export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
+  private readonly client: S3Client
+  private readonly bucket: string
+
+  constructor(config: ConfigService) {
+    this.bucket = config.getOrThrow<string>('storage.bucket')
+    this.client = new S3Client({
+      endpoint: config.getOrThrow<string>('storage.endpoint'),
+      region: config.getOrThrow<string>('storage.region'),
+      credentials: {
+        accessKeyId: config.getOrThrow<string>('storage.accessKeyId'),
+        secretAccessKey: config.getOrThrow<string>('storage.secretAccessKey'),
+      },
+      forcePathStyle: config.getOrThrow<boolean>('storage.forcePathStyle'),
+      // UploadPart 的 Body 是不可回放流，禁止 SDK 在后端自动重放。
+      maxAttempts: 1,
+      requestChecksumCalculation: 'WHEN_REQUIRED',
+      responseChecksumValidation: 'WHEN_REQUIRED',
+    })
+  }
+
+  private async assertBucketAvailable(): Promise<void> {
+    await this.client.send(
+      new HeadBucketCommand({
+        Bucket: this.bucket,
+      }),
+    )
+  }
+
+  onModuleDestroy() {
+    this.client.destroy()
+  }
+
+  async onModuleInit() {
+    await this.assertBucketAvailable()
+  }
+
+  async createMultipartUpload(input: CreateMultipartInput) {
+    const response = await this.client.send(
+      new CreateMultipartUploadCommand({
+        Bucket: input.bucket,
+        Key: input.objectKey,
+        ContentType: input.contentType,
+        Metadata: input.metadata,
+      }),
+    )
+
+    if (!response.UploadId) {
+      throw new Error('Storage did not return an UploadId')
+    }
+
+    return {
+      storageUploadId: response.UploadId,
+    }
+  }
+
+  async uploadPart(input: UploadPartInput) {
+    try {
+      const response = await this.client.send(
+        new UploadPartCommand({
+          Bucket: input.bucket,
+          Key: input.objectKey,
+          UploadId: input.storageUploadId,
+          PartNumber: input.partNumber,
+          Body: input.body,
+          ContentLength: input.contentLength,
+        }),
+        {
+          abortSignal: input.abortSignal,
+        },
+      )
+
+      if (!response.ETag) {
+        throw new Error('Storage did not return an ETag')
+      }
+
+      return {
+        etag: response.ETag,
+      }
+    } catch (cause: unknown) {
+      throwMappedMultipartError(cause)
+    }
+  }
+
+  async listParts(input: MultipartIdentity): Promise<StoragePart[]> {
+    const parts: StoragePart[] = []
+    let partNumberMarker: string | undefined
+    try {
+      for (;;) {
+        const response = await this.client.send(
+          new ListPartsCommand({
+            Bucket: input.bucket,
+            Key: input.objectKey,
+            UploadId: input.storageUploadId,
+            PartNumberMarker: partNumberMarker,
+          }),
+        )
+
+        for (const part of response.Parts ?? []) {
+          if (part.PartNumber === undefined || part.ETag === undefined || part.Size === undefined) {
+            throw new Error('Storage returned an incomplete part record')
+          }
+          parts.push({
+            partNumber: part.PartNumber,
+            etag: part.ETag,
+            size: part.Size,
+          })
+        }
+
+        if (!response.IsTruncated) {
+          break
+        }
+
+        const nextMarker = response.NextPartNumberMarker
+        if (!nextMarker || nextMarker === partNumberMarker) {
+          throw new Error('Storage returned an invalid ListParts cursor')
+        }
+
+        partNumberMarker = nextMarker
+      }
+    } catch (cause: unknown) {
+      throwMappedMultipartError(cause)
+    }
+
+    return parts.sort((left, right) => left.partNumber - right.partNumber)
+  }
+
+  async completeMultipartUpload(input: MultipartIdentity & { parts: readonly StoragePart[] }) {
+    try {
+      const response = await this.client.send(
+        new CompleteMultipartUploadCommand({
+          Bucket: input.bucket,
+          Key: input.objectKey,
+          UploadId: input.storageUploadId,
+          MultipartUpload: {
+            Parts: input.parts.map((part) => ({
+              PartNumber: part.partNumber,
+              ETag: part.etag,
+            })),
+          },
+        }),
+      )
+      return {
+        etag: response.ETag ?? null,
+      }
+    } catch (cause: unknown) {
+      throwMappedMultipartError(cause)
+    }
+  }
+
+  async abortMultipartUpload(input: MultipartIdentity): Promise<void> {
+    try {
+      await this.client.send(
+        new AbortMultipartUploadCommand({
+          Bucket: input.bucket,
+          Key: input.objectKey,
+          UploadId: input.storageUploadId,
+        }),
+      )
+    } catch (cause: unknown) {
+      if (hasErrorName(cause, 'NoSuchUpload')) {
+        return
+      }
+      throw cause
+    }
+  }
+
+  async headObject(input: { bucket: string; objectKey: string }): Promise<StorageObject | null> {
+    try {
+      const response = await this.client.send(
+        new HeadObjectCommand({
+          Bucket: input.bucket,
+          Key: input.objectKey,
+        }),
+      )
+      return {
+        etag: response.ETag ?? null,
+        contentLength: response.ContentLength ?? null,
+        metadata: response.Metadata ?? {},
+      }
+    } catch (cause: unknown) {
+      if (hasErrorName(cause, 'NoSuchBucket')) {
+        throw cause
+      }
+
+      if (hasErrorName(cause, 'NoSuchKey')) {
+        return null
+      }
+
+      if (hasErrorName(cause, 'NotFound')) {
+        // 某些 S3 兼容实现会把“对象不存在”和“Bucket 不存在”都表示成 404。
+        // 额外探测 Bucket；只有 Bucket 确实可用时，才把这次 404 当成对象不存在。
+        await this.assertBucketAvailable()
+        return null
+      }
+
+      throw cause
+    }
+  }
+}