create-bubbles 0.1.24 → 0.1.26

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

@@ -0,0 +1,61 @@
+import { Readable } from 'stream'
+
+export const STORAGE_PORT = Symbol('STORAGE_PORT')
+
+export class StorageMultipartNotFoundError extends Error {
+  constructor(cause: unknown) {
+    super('Multipart upload does not exist', { cause })
+    this.name = StorageMultipartNotFoundError.name
+  }
+}
+
+export interface CreateMultipartInput {
+  bucket: string
+  objectKey: string
+  contentType: string
+  metadata: Record<string, string>
+}
+
+export interface UploadPartInput {
+  bucket: string
+  objectKey: string
+  storageUploadId: string
+  partNumber: number
+  body: Readable
+  contentLength: number
+  abortSignal?: AbortSignal
+}
+
+export interface MultipartIdentity {
+  bucket: string
+  objectKey: string
+  storageUploadId: string
+}
+
+export interface StoragePart {
+  partNumber: number
+  etag: string
+  size: number
+}
+
+export interface StorageObject {
+  etag: string | null
+  contentLength: number | null
+  metadata: Record<string, string>
+}
+
+export interface StoragePort {
+  createMultipartUpload(input: CreateMultipartInput): Promise<{ storageUploadId: string }>
+
+  uploadPart(input: UploadPartInput): Promise<{ etag: string }>
+
+  listParts(input: MultipartIdentity): Promise<StoragePart[]>
+
+  completeMultipartUpload(
+    input: MultipartIdentity & { parts: readonly StoragePart[] },
+  ): Promise<{ etag: string | null }>
+
+  abortMultipartUpload(input: MultipartIdentity): Promise<void>
+
+  headObject(input: { bucket: string; objectKey: string }): Promise<StorageObject | null>
+}

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

@@ -0,0 +1,23 @@
+export const UPLOAD_PART_SIZE = 10 * 1024 * 1024
+export const UPLOAD_MAX_PARTS = 10_000
+export const UPLOAD_MAX_FILE_SIZE = 90 * 1024 * 1024 * 1024
+
+export function calculateTotalParts(fileSize: number): number {
+  return Math.ceil(fileSize / UPLOAD_PART_SIZE)
+}
+
+export function calculateExpectedPartSize(
+  fileSize: number,
+  totalParts: number,
+  partNumber: number,
+): number {
+  if (partNumber < 1 || partNumber > totalParts) {
+    throw new RangeError('partNumber is outside the upload range')
+  }
+
+  if (partNumber < totalParts) {
+    return UPLOAD_PART_SIZE
+  }
+
+  return fileSize - (totalParts - 1) * UPLOAD_PART_SIZE
+}

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

@@ -0,0 +1,109 @@
+import { CurrentAuth } from '@/common/decorators/current-auth.decorator'
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Headers,
+  HttpCode,
+  HttpStatus,
+  Param,
+  Post,
+  Put,
+  Req,
+  Res,
+} from '@nestjs/common'
+import { ApiBearerAuth, ApiBody, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger'
+import { type FastifyReply, FastifyRequest } from 'fastify'
+import type { Readable } from 'stream'
+import { type CurrentAuthType } from '../auth/session/session.types'
+import { InitiateMultipartUploadDto } from './dto/initiate-mutipart-upload.dto'
+import { UploadPartParamsDto, UploadSessionParamsDto } from './dto/upload-params.dto'
+import { UploadService } from './upload.service'
+
+type OctetStreamRequest = FastifyRequest & {
+  body: Readable
+}
+
+@ApiTags('大文件分片上传')
+@ApiBearerAuth('session')
+@Controller('uploads/multipart')
+export class UploadController {
+  constructor(private readonly uploadService: UploadService) {}
+
+  @ApiOperation({ summary: '初始化大文件分片上传' })
+  @Post()
+  initiate(@CurrentAuth() auth: CurrentAuthType, @Body() body: InitiateMultipartUploadDto) {
+    return this.uploadService.initiate(auth.userId, body)
+  }
+
+  @ApiOperation({ summary: '查询上传状态和已上传分片' })
+  @Get(':uploadSessionId')
+  getStatus(@CurrentAuth() auth: CurrentAuthType, @Param() params: UploadSessionParamsDto) {
+    return this.uploadService.getStatus(auth.userId, params.uploadSessionId)
+  }
+
+  @ApiOperation({ summary: '上传一个原始二进制分片' })
+  @ApiConsumes('application/octet-stream')
+  @ApiBody({
+    schema: {
+      type: 'string',
+      format: 'binary',
+    },
+  })
+  @HttpCode(HttpStatus.OK)
+  @Put(':uploadSessionId/parts/:partNumber')
+  uploadPart(
+    @CurrentAuth() auth: CurrentAuthType,
+    @Param() params: UploadPartParamsDto,
+    @Headers('content-length') contentLength: string | undefined,
+    @Headers('content-encoding') contentEncoding: string | undefined,
+    @Req() request: OctetStreamRequest,
+    @Res({ passthrough: true }) reply: FastifyReply,
+  ) {
+    const abortController = new AbortController()
+    const onAborted = () => abortController.abort()
+    const onReplyClose = () => {
+      if (!reply.raw.writableEnded) {
+        abortController.abort()
+      }
+    }
+
+    request.raw.once('aborted', onAborted)
+    reply.raw.once('close', onReplyClose)
+
+    return this.uploadService
+      .uploadPart({
+        ownerId: auth.userId,
+        uploadSessionId: params.uploadSessionId,
+        partNumber: params.partNumber,
+        contentLength,
+        contentEncoding,
+        body: request.body,
+        abortSignal: abortController.signal,
+      })
+      .finally(() => {
+        // 前置校验失败时 Service 可能尚未 pipe 请求体。
+        // 统一排空剩余字节，避免连接一直占用到代理超时；这里不会聚合 Buffer。
+        if (!request.body.readableEnded && !request.body.destroyed) {
+          request.body.resume()
+        }
+
+        request.raw.off('aborted', onAborted)
+        reply.raw.off('close', onReplyClose)
+      })
+  }
+
+  @ApiOperation({ summary: '校验并完成分片上传' })
+  @HttpCode(HttpStatus.OK)
+  @Post(':uploadSessionId/complete')
+  complete(@CurrentAuth() auth: CurrentAuthType, @Param() params: UploadSessionParamsDto) {
+    return this.uploadService.complete(auth.userId, params.uploadSessionId)
+  }
+
+  @ApiOperation({ summary: '取消分片上传' })
+  @Delete(':uploadSessionId')
+  abort(@CurrentAuth() auth: CurrentAuthType, @Param() params: UploadSessionParamsDto) {
+    return this.uploadService.abort(auth.userId, params.uploadSessionId)
+  }
+}

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

@@ -0,0 +1,80 @@
+import type { AppErrorDefinition } from '@/common/exceptions/app.exception'
+import { HttpStatus } from '@nestjs/common'
+
+export const UPLOAD_ERRORS = {
+  FILE_EMPTY: {
+    code: 'UPLOAD.FILE_EMPTY',
+    publicMessage: '空文件不能使用分片上传',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
+  FILE_TOO_LARGE: {
+    code: 'UPLOAD.FILE_TOO_LARGE',
+    publicMessage: '文件超过允许的最大大小',
+    status: HttpStatus.PAYLOAD_TOO_LARGE,
+  },
+  CLIENT_UPLOAD_ID_CONFLICT: {
+    code: 'UPLOAD.CLIENT_UPLOAD_ID_CONFLICT',
+    publicMessage: '该客户端上传标识已用于另一个文件',
+    status: HttpStatus.CONFLICT,
+  },
+  SESSION_NOT_FOUND: {
+    code: 'UPLOAD.SESSION_NOT_FOUND',
+    publicMessage: '上传会话不存在',
+    status: HttpStatus.NOT_FOUND,
+  },
+  INVALID_STATE: {
+    code: 'UPLOAD.INVALID_STATE',
+    publicMessage: '当前上传状态不允许执行此操作',
+    status: HttpStatus.CONFLICT,
+  },
+  UPLOAD_EXPIRED: {
+    code: 'UPLOAD.UPLOAD_EXPIRED',
+    publicMessage: '上传会话已过期，请重新开始',
+    status: HttpStatus.GONE,
+  },
+  PART_NUMBER_INVALID: {
+    code: 'UPLOAD.PART_NUMBER_INVALID',
+    publicMessage: '分片编号超出当前文件范围',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
+  PART_LENGTH_REQUIRED: {
+    code: 'UPLOAD.PART_LENGTH_REQUIRED',
+    publicMessage: '分片请求缺少有效的 Content-Length',
+    status: HttpStatus.LENGTH_REQUIRED,
+  },
+  PART_SIZE_MISMATCH: {
+    code: 'UPLOAD.PART_SIZE_MISMATCH',
+    publicMessage: '分片实际大小与预期不一致',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
+  UNSUPPORTED_CONTENT_ENCODING: {
+    code: 'UPLOAD.UNSUPPORTED_CONTENT_ENCODING',
+    publicMessage: '分片请求不支持压缩编码',
+    status: HttpStatus.UNSUPPORTED_MEDIA_TYPE,
+  },
+  PARTS_INCOMPLETE: {
+    code: 'UPLOAD.PARTS_INCOMPLETE',
+    publicMessage: '分片尚未全部上传或大小不正确',
+    status: HttpStatus.CONFLICT,
+  },
+  PARTS_STILL_ACTIVE: {
+    code: 'UPLOAD.PARTS_STILL_ACTIVE',
+    publicMessage: '仍有分片正在上传，请稍后重试',
+    status: HttpStatus.CONFLICT,
+  },
+  PART_UPLOAD_ABORTED: {
+    code: 'UPLOAD.PART_UPLOAD_ABORTED',
+    publicMessage: '分片上传已取消',
+    status: HttpStatus.REQUEST_TIMEOUT,
+  },
+  STORAGE_UPLOAD_MISSING: {
+    code: 'UPLOAD.STORAGE_UPLOAD_MISSING',
+    publicMessage: '存储中的上传会话已失效，请重新开始',
+    status: HttpStatus.GONE,
+  },
+  STORAGE_UNAVAILABLE: {
+    code: 'UPLOAD.STORAGE_UNAVAILABLE',
+    publicMessage: '文件存储服务暂时不可用，请稍后重试',
+    status: HttpStatus.SERVICE_UNAVAILABLE,
+  },
+} as const satisfies Record<string, AppErrorDefinition>

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

@@ -0,0 +1,20 @@
+import { Module } from '@nestjs/common'
+import { MinioStorageAdapter } from './storage/minio-storage.adapter'
+import { STORAGE_PORT } from './storage/storage.port'
+import { UploadController } from './upload.controller'
+import { UploadRepository } from './upload.reponsitory'
+import { UploadService } from './upload.service'
+
+@Module({
+  controllers: [UploadController],
+  providers: [
+    UploadRepository,
+    UploadService,
+    MinioStorageAdapter,
+    {
+      provide: STORAGE_PORT,
+      useExisting: MinioStorageAdapter,
+    },
+  ],
+})
+export class UploadModule {}

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

@@ -0,0 +1,166 @@
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import { uploadSessions } from '@/database/schema'
+import { Inject, Injectable } from '@nestjs/common'
+import { and, eq, inArray } from 'drizzle-orm'
+
+export type UploadSession = typeof uploadSessions.$inferSelect
+export type CreateUploadSession = typeof uploadSessions.$inferInsert
+
+@Injectable()
+export class UploadRepository {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
+
+  async create(input: CreateUploadSession): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .insert(uploadSessions)
+      .values(input)
+      .onConflictDoNothing({
+        target: [uploadSessions.ownerId, uploadSessions.clientUploadId],
+      })
+      .returning()
+
+    return session ?? null
+  }
+
+  async findById(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .select()
+      .from(uploadSessions)
+      .where(and(eq(uploadSessions.id, uploadSessionId), eq(uploadSessions.ownerId, ownerId)))
+      .limit(1)
+    return session ?? null
+  }
+
+  async findByClientUploadId(
+    ownerId: string,
+    clientUploadId: string,
+  ): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .select()
+      .from(uploadSessions)
+      .where(
+        and(eq(uploadSessions.ownerId, ownerId), eq(uploadSessions.clientUploadId, clientUploadId)),
+      )
+      .limit(1)
+
+    return session ?? null
+  }
+
+  async claimCompleting(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .update(uploadSessions)
+      .set({
+        status: 'completing',
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          eq(uploadSessions.ownerId, ownerId),
+          eq(uploadSessions.status, 'uploading'),
+        ),
+      )
+      .returning()
+
+    return session ?? null
+  }
+
+  async markCompleted(
+    ownerId: string,
+    uploadSessionId: string,
+    objectEtag: string | null,
+  ): Promise<UploadSession | null> {
+    const now = new Date()
+    const [session] = await this.db
+      .update(uploadSessions)
+      .set({
+        status: 'completed',
+        objectEtag,
+        completedAt: now,
+        updatedAt: now,
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          eq(uploadSessions.ownerId, ownerId),
+          eq(uploadSessions.status, 'completing'),
+        ),
+      )
+      .returning()
+
+    return session ?? null
+  }
+
+  async claimAborting(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .update(uploadSessions)
+      .set({
+        status: 'aborting',
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          eq(uploadSessions.ownerId, ownerId),
+          inArray(uploadSessions.status, ['uploading', 'aborting', 'expired']),
+        ),
+      )
+      .returning()
+
+    return session ?? null
+  }
+
+  async markAborted(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .update(uploadSessions)
+      .set({
+        status: 'aborted',
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          eq(uploadSessions.ownerId, ownerId),
+          eq(uploadSessions.status, 'aborting'),
+        ),
+      )
+      .returning()
+
+    return session ?? null
+  }
+
+  async markExpired(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
+    const [session] = await this.db
+      .update(uploadSessions)
+      .set({
+        status: 'expired',
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          eq(uploadSessions.ownerId, ownerId),
+          eq(uploadSessions.status, 'uploading'),
+        ),
+      )
+      .returning()
+
+    return session ?? null
+  }
+
+  async resetCompleting(ownerId: string, uploadSessionId: string): Promise<void> {
+    await this.db
+      .update(uploadSessions)
+      .set({
+        status: 'uploading',
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          eq(uploadSessions.ownerId, ownerId),
+          eq(uploadSessions.status, 'completing'),
+        ),
+      )
+  }
+}