feat(garage-upload): add garage storage integration

- implement garage storage service for file uploads and deletions
- provide presigned urls for secure and direct uploads
- allow file deletion by url
- configure environment variables for garage storage credentials
- integrate garage storage module into the main upload module
- define file type enum for organized storage paths

.env.example

@@ -91,3 +91,8 @@ SEAWEEDFS_FILER_ENDPOINT="https://your-seaweedfs-instance.com/filer/buckets/your
 SEAWEEDFS_PUBLIC_URL="https://your-seaweedfs-instance.com/your-bucket"
 SEAWEEDFS_ACCESS_KEY="your-access-key"
 SEAWEEDFS_SECRET_KEY="your-secret-key"
+# Garage Storage Credentials
+GARAGE_ENDPOINT="https://your-garage-instance.com"
+GARAGE_ACCESS_KEY="your-garage-access-key"
+GARAGE_SECRET_KEY="your-garage-secret-key"
+GARAGE_BUCKET="stremflix"

src/shared/modules/upload/garage-storage/enums/file-type.enum.ts

@@ -0,0 +1,5 @@
+export enum FileType {
+  IMAGE = 'IMAGE',
+  DOCUMENT = 'DOCUMENT',
+  VIDEO = 'VIDEO',
+}

src/shared/modules/upload/garage-storage/garage-storage.config.ts

@@ -0,0 +1,8 @@
+import { registerAs } from '@nestjs/config';
+
+export default registerAs('garageStorage', () => ({
+  endpoint: process.env.GARAGE_ENDPOINT,
+  accessKey: process.env.GARAGE_ACCESS_KEY,
+  secretKey: process.env.GARAGE_SECRET_KEY,
+  bucket: process.env.GARAGE_BUCKET || 'stremflix',
+}));

src/shared/modules/upload/garage-storage/garage-storage.controller.ts

@@ -0,0 +1,39 @@
+import {
+  Controller,
+  Get,
+  Delete,
+  Query,
+  HttpCode,
+  HttpStatus,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiQuery } from '@nestjs/swagger';
+import { GarageStorageService } from './garage-storage.service';
+import { FileType } from './enums/file-type.enum';
+
+@ApiTags('Upload: Garage Storage')
+@Controller('garage')
+export class GarageStorageController {
+  constructor(private readonly garageStorageService: GarageStorageService) {}
+
+  @Get('presigned-upload')
+  @ApiOperation({ summary: 'Get presigned upload URL' })
+  @ApiQuery({ name: 'fileName', required: true })
+  @ApiQuery({ name: 'fileType', enum: FileType, required: false })
+  async getPresignedUploadUrl(
+    @Query('fileName') fileName: string,
+    @Query('fileType') fileType?: FileType,
+  ) {
+    return this.garageStorageService.getPresignedUploadUrl(fileName, fileType);
+  }
+
+  @Delete('by-url')
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({ summary: 'Delete file by URL' })
+  async deleteFileByUrl(@Query('url') url: string) {
+    const result = await this.garageStorageService.deleteFileByUrl(url);
+    return {
+      message: 'File deleted successfully',
+      ...result,
+    };
+  }
+}

src/shared/modules/upload/garage-storage/garage-storage.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { GarageStorageController } from './garage-storage.controller';
+import { GarageStorageService } from './garage-storage.service';
+import garageStorageConfig from './garage-storage.config';
+
+@Module({
+  imports: [ConfigModule.forFeature(garageStorageConfig)],
+  controllers: [GarageStorageController],
+  providers: [GarageStorageService],
+  exports: [GarageStorageService],
+})
+export class GarageStorageModule {}

src/shared/modules/upload/garage-storage/garage-storage.service.ts

@@ -0,0 +1,178 @@
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import {
+  S3Client,
+  PutObjectCommand,
+  DeleteObjectCommand,
+} from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+@Injectable()
+export class GarageStorageService {
+  private readonly logger = new Logger(GarageStorageService.name);
+  private s3Client: S3Client;
+  private bucket: string;
+  private endpoint: string;
+
+  constructor(private configService: ConfigService) {
+    this.endpoint =
+      this.configService.get<string>('garageStorage.endpoint') || '';
+    const accessKeyId =
+      this.configService.get<string>('garageStorage.accessKey') || '';
+    const secretAccessKey =
+      this.configService.get<string>('garageStorage.secretKey') || '';
+    this.bucket =
+      this.configService.get<string>('garageStorage.bucket') || 'stremflix';
+
+    this.s3Client = new S3Client({
+      region: 'garage', // Garage doesn't use regions, but AWS SDK requires it
+      endpoint: this.endpoint,
+      credentials: {
+        accessKeyId,
+        secretAccessKey,
+      },
+      forcePathStyle: true, // Required for Garage
+      tls: true,
+      // Disable request checksums for Garage compatibility
+      requestChecksumCalculation: 'WHEN_REQUIRED',
+    });
+  }
+
+  /**
+   * Get folder path based on file type
+   * @param fileType - The file type (IMAGE, DOCUMENT, VIDEO)
+   * @returns Folder path for the file type
+   */
+  private getFolderPath(fileType: string): string {
+    const folderMap: Record<string, string> = {
+      IMAGE: 'images',
+      DOCUMENT: 'documents',
+      VIDEO: 'videos',
+    };
+    return folderMap[fileType.toUpperCase()] || 'others';
+  }
+
+  /**
+   * Generate presigned upload URL using S3
+   * @param fileName - The file name
+   * @param fileType - The file type (IMAGE, DOCUMENT, VIDEO)
+   * @returns Presigned upload URL and file path
+   */
+  async getPresignedUploadUrl(fileName: string, fileType?: string) {
+    try {
+      // Determine folder based on file type
+      const folder = fileType ? this.getFolderPath(fileType) : 'others';
+
+      // Create full file path: folder/timestamp-filename
+      const timestamp = Date.now();
+      const filePath = `${folder}/${timestamp}-${fileName}`;
+
+      // Create PutObject command
+      // Disable checksum for Garage compatibility
+      const command = new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: filePath,
+        ChecksumAlgorithm: undefined, // Disable automatic checksums for Garage
+      });
+
+      // Generate presigned URL (valid for 1 hour)
+      // Disable checksums in presigned URL for Garage compatibility
+      const uploadUrl = await getSignedUrl(this.s3Client, command, {
+        expiresIn: 3600,
+        unhoistableHeaders: new Set(['x-amz-checksum-crc32']),
+      });
+
+      // Construct the public URL using Garage's public path format
+      const fileUrl = `${this.endpoint}/public/${this.bucket}/${filePath}`;
+
+      this.logger.log(
+        `Generated presigned upload URL for: ${filePath}${fileType ? ` (type: ${fileType})` : ''}`,
+      );
+
+      return {
+        uploadUrl,
+        fileUrl,
+        filePath,
+        expiresIn: 3600, // 1 hour in seconds
+        ...(fileType && { fileType }),
+      };
+    } catch (error) {
+      this.logger.error('Failed to generate presigned upload URL', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Delete a file from Garage Storage using S3
+   * @param filePath - The file path in the bucket
+   * @returns Deletion result
+   */
+  async deleteFile(filePath: string): Promise<any> {
+    try {
+      const command = new DeleteObjectCommand({
+        Bucket: this.bucket,
+        Key: filePath,
+      });
+
+      const result = await this.s3Client.send(command);
+
+      this.logger.log(`Successfully deleted file: ${filePath}`);
+      return {
+        success: true,
+        deletedPath: filePath,
+        result,
+      };
+    } catch (error) {
+      this.logger.error(`Failed to delete file: ${filePath}`, error);
+      throw new NotFoundException('File not found or already deleted');
+    }
+  }
+
+  /**
+   * Delete a file by URL
+   * @param url - The Garage Storage file URL
+   * @returns Deletion result
+   */
+  async deleteFileByUrl(url: string): Promise<any> {
+    try {
+      // Extract file path from URL
+      // Example: https://lucifer925-garage-storage.hf.space/public/stremflix/images/1234567890-file.jpg
+      // Extract: images/1234567890-file.jpg
+      const filePath = this.extractFilePathFromUrl(url);
+
+      if (!filePath) {
+        throw new NotFoundException('Could not extract file path from URL');
+      }
+
+      const result = await this.deleteFile(filePath);
+
+      this.logger.log(`Successfully deleted file from URL: ${url}`);
+
+      return {
+        ...result,
+        deletedUrl: url,
+      };
+    } catch (error) {
+      if (error instanceof NotFoundException) {
+        throw error;
+      }
+      this.logger.error(`Failed to delete file by URL: ${url}`, error);
+      throw new NotFoundException('File not found or already deleted');
+    }
+  }
+
+  /**
+   * Extract file path from Garage Storage URL
+   * @param url - The Garage Storage URL
+   * @returns File path
+   */
+  private extractFilePathFromUrl(url: string): string | null {
+    try {
+      // Match pattern: /public/{bucket}/{path}
+      const match = url.match(/\/public\/[^/]+\/(.+)$/);
+      return match ? match[1] : null;
+    } catch {
+      return null;
+    }
+  }
+}

src/shared/modules/upload/upload.module.ts

@@ -7,6 +7,7 @@ import { NewMinioStorageModule } from './new-minio-storage/new-minio-storage.mod
 import { OldMinioStorageModule } from './old-minio-storage/old-minio-storage.module';
 import { SeaweedfsStorageModule } from './seaweedfs-storage/seaweedfs-storage.module';
 import { FilestackModule } from './filestack/filestack.module';
+import { GarageStorageModule } from './garage-storage/garage-storage.module';
 
 @Module({
   imports: [
@@ -16,6 +17,7 @@ import { FilestackModule } from './filestack/filestack.module';
     BackblazeStorageModule,
     NewMinioStorageModule,
     OldMinioStorageModule,
+    GarageStorageModule,
     SeaweedfsStorageModule,
     FilestackModule,
   ],