@lenne.tech/nest-server 11.7.2 → 11.8.0

package/src/core/modules/tus/tus.module.ts

@@ -0,0 +1,187 @@
+import { DynamicModule, Global, Logger, Module, OnModuleInit, Type } from '@nestjs/common';
+import { getConnectionToken } from '@nestjs/mongoose';
+import { Connection } from 'mongoose';
+
+import { ITusConfig } from '../../common/interfaces/server-options.interface';
+import { CoreTusController } from './core-tus.controller';
+import { CoreTusService } from './core-tus.service';
+import { normalizeTusConfig } from './interfaces/tus-config.interface';
+
+/**
+ * Token for injecting the TUS configuration
+ */
+export const TUS_CONFIG = 'TUS_CONFIG';
+
+/**
+ * Options for TusModule.forRoot()
+ */
+export interface TusModuleOptions {
+  /**
+   * TUS configuration.
+   * Accepts:
+   * - `true` or `undefined`: Enable with defaults (enabled by default)
+   * - `false`: Disable TUS uploads
+   * - `{ ... }`: Enable with custom configuration
+   */
+  config?: boolean | ITusConfig;
+
+  /**
+   * Custom controller class to use instead of CoreTusController.
+   * The class must extend CoreTusController.
+   *
+   * @example
+   * ```typescript
+   * @Controller('tus')
+   * @Roles(RoleEnum.S_USER) // Require authentication
+   * export class TusController extends CoreTusController {
+   *   override async handleTus(...) {
+   *     // Custom logic
+   *     return super.handleTus(...);
+   *   }
+   * }
+   *
+   * TusModule.forRoot({
+   *   controller: TusController,
+   * })
+   * ```
+   */
+  controller?: Type<CoreTusController>;
+}
+
+/**
+ * TUS Module for resumable file uploads
+ *
+ * This module provides integration with the tus.io protocol via @tus/server.
+ * It is enabled by default with sensible defaults - no configuration required.
+ *
+ * Features:
+ * - Resumable uploads via tus.io protocol
+ * - Automatic migration to GridFS after upload completion
+ * - Configurable extensions (creation, termination, expiration, etc.)
+ * - Module Inheritance Pattern for customization
+ *
+ * @example
+ * ```typescript
+ * // Default usage - enabled with all defaults
+ * @Module({
+ *   imports: [
+ *     CoreModule.forRoot(envConfig),
+ *     TusModule.forRoot(), // No config needed
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Custom configuration
+ * TusModule.forRoot({
+ *   config: {
+ *     maxSize: 100 * 1024 * 1024, // 100 MB
+ *     path: '/uploads',
+ *   },
+ * })
+ *
+ * // Disable TUS
+ * TusModule.forRoot({ config: false })
+ * ```
+ */
+@Global()
+@Module({})
+export class TusModule implements OnModuleInit {
+  private static logger = new Logger(TusModule.name);
+  private static tusEnabled = false;
+  private static currentConfig: ITusConfig | null = null;
+  private static customController: null | Type<CoreTusController> = null;
+
+  constructor(private readonly tusService?: CoreTusService) {}
+
+  async onModuleInit(): Promise<void> {
+    if (TusModule.tusEnabled && this.tusService?.isEnabled()) {
+      TusModule.logger.log('TusModule ready');
+    }
+  }
+
+  /**
+   * Gets the controller class to use (custom or default)
+   */
+  private static getControllerClass(): Type<CoreTusController> {
+    return this.customController || CoreTusController;
+  }
+
+  /**
+   * Creates a dynamic module for TUS uploads
+   *
+   * @param options - Configuration options (optional)
+   * @returns Dynamic module configuration
+   */
+  static forRoot(options: TusModuleOptions = {}): DynamicModule {
+    const { config: rawConfig, controller } = options;
+
+    // Normalize config: undefined/true → enabled with defaults, false → disabled
+    const config = normalizeTusConfig(rawConfig);
+
+    // Store config for service configuration
+    this.currentConfig = config;
+    // Store custom controller if provided
+    this.customController = controller || null;
+
+    // If TUS is disabled, return minimal module
+    if (config === null) {
+      this.logger.debug('TUS uploads disabled');
+      this.tusEnabled = false;
+      return {
+        exports: [TUS_CONFIG, CoreTusService],
+        module: TusModule,
+        providers: [
+          {
+            provide: TUS_CONFIG,
+            useValue: null,
+          },
+          {
+            inject: [getConnectionToken()],
+            provide: CoreTusService,
+            useFactory: (connection: Connection) => {
+              const service = new CoreTusService(connection);
+              service.configure(false);
+              return service;
+            },
+          },
+        ],
+      };
+    }
+
+    // Enable TUS
+    this.tusEnabled = true;
+
+    return {
+      controllers: [this.getControllerClass()],
+      exports: [TUS_CONFIG, CoreTusService],
+      module: TusModule,
+      providers: [
+        {
+          provide: TUS_CONFIG,
+          useValue: config,
+        },
+        {
+          inject: [getConnectionToken(), TUS_CONFIG],
+          provide: CoreTusService,
+          useFactory: async (connection: Connection, tusConfig: ITusConfig) => {
+            const service = new CoreTusService(connection);
+            service.configure(tusConfig);
+            // Manually call onModuleInit since useFactory bypasses lifecycle hooks
+            await service.onModuleInit();
+            return service;
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Resets the static state of TusModule
+   * Useful for testing
+   */
+  static reset(): void {
+    this.tusEnabled = false;
+    this.currentConfig = null;
+    this.customController = null;
+  }
+}

package/src/core/modules/user/core-user.service.ts

@@ -91,6 +91,33 @@ export abstract class CoreUserService<
     return this.process(async () => dbObject, { dbObject, serviceOptions });
   }
 
+  /**
+   * Get user by MongoDB ID or BetterAuth IAM ID
+   *
+   * This method is used by RolesGuard to resolve users from BetterAuth JWT tokens.
+   * The sub claim in BetterAuth JWTs can contain either:
+   * - The MongoDB _id of the user
+   * - The BetterAuth iamId
+   *
+   * @param idOrIamId - MongoDB _id or BetterAuth iamId
+   * @returns User object or null if not found
+   */
+  async getByIdOrIamId(idOrIamId: string): Promise<null | TUser> {
+    try {
+      // First, try to find by MongoDB _id
+      const byId = await this.mainDbModel.findById(idOrIamId).exec();
+      if (byId) {
+        return byId as TUser;
+      }
+    } catch {
+      // Invalid ObjectId format - try iamId instead
+    }
+
+    // Try to find by iamId
+    const byIamId = await this.mainDbModel.findOne({ iamId: idOrIamId }).exec();
+    return byIamId as null | TUser;
+  }
+
   /**
    * Get verified state of user by token
    */

package/src/index.ts

@@ -158,6 +158,12 @@ export * from './core/modules/health-check/core-health-check.service';
 
 export * from './core/modules/migrate';
 
+// =====================================================================================================================
+// Core - Modules - Tus
+// =====================================================================================================================
+
+export * from './core/modules/tus';
+
 // =====================================================================================================================
 // Core - Modules - User
 // =====================================================================================================================

package/src/server/modules/file/file.controller.ts

@@ -3,33 +3,41 @@ import {
   Controller,
   Delete,
   Get,
-  NotFoundException,
   Param,
   Post,
-  Res,
   UploadedFile,
   UseInterceptors,
 } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
-import { Response } from 'express';
 import { Readable } from 'stream';
 
 import { Roles } from '../../../core/common/decorators/roles.decorator';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
-import { CoreFileInfo } from '../../../core/modules/file/core-file-info.model';
+import { CoreFileController } from '../../../core/modules/file/core-file.controller';
 import { FileUpload } from '../../../core/modules/file/interfaces/file-upload.interface';
 import { FileService } from './file.service';
 
 /**
  * File controller
+ *
+ * Extends CoreFileController to provide public download endpoints:
+ * - GET /files/id/:id - Download file by ID (public)
+ * - GET /files/:filename - Download file by filename (public)
+ *
+ * Adds admin-only endpoints:
+ * - POST /files/upload - Upload file (admin)
+ * - GET /files/info/:id - Get file info (admin)
+ * - DELETE /files/:id - Delete file (admin)
  */
 @Controller('files')
 @Roles(RoleEnum.ADMIN)
-export class FileController {
+export class FileController extends CoreFileController {
   /**
    * Import services
    */
-  constructor(private readonly fileService: FileService) {}
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
 
   /**
    * Upload file via HTTP
@@ -54,34 +62,6 @@ export class FileController {
     return await this.fileService.createFile(fileUpload);
   }
 
-  /**
-   * Download file
-   */
-  @Get(':id')
-  @Roles(RoleEnum.ADMIN)
-  async getFile(@Param('id') id: string, @Res() res: Response) {
-    if (!id) {
-      throw new BadRequestException('Missing ID');
-    }
-
-    let file: CoreFileInfo | null;
-    try {
-      file = await this.fileService.getFileInfo(id);
-    } catch (e) {
-      console.error(e);
-      file = null;
-    }
-
-    if (!file) {
-      throw new NotFoundException('File not found');
-    }
-    const filestream = await this.fileService.getFileStream(id);
-    res.header('Content-Type', file.contentType || 'application/octet-stream');
-    res.header('Content-Disposition', `attachment; filename=${file.filename}`);
-    res.header('Cache-Control', 'max-age=31536000');
-    return filestream.pipe(res);
-  }
-
   /**
    * Get file information
    */

package/src/server/server.module.ts

@@ -7,6 +7,7 @@ import { Any } from '../core/common/scalars/any.scalar';
 import { DateScalar } from '../core/common/scalars/date.scalar';
 import { JSON } from '../core/common/scalars/json.scalar';
 import { CoreAuthService } from '../core/modules/auth/services/core-auth.service';
+import { TusModule } from '../core/modules/tus';
 import { CronJobs } from './common/services/cron-jobs.service';
 import { AuthController } from './modules/auth/auth.controller';
 import { AuthModule } from './modules/auth/auth.module';
@@ -25,7 +26,7 @@ import { ServerController } from './server.controller';
   controllers: [ServerController, AuthController],
 
   // Export modules for reuse in other modules
-  exports: [CoreModule, AuthModule, BetterAuthModule, FileModule],
+  exports: [CoreModule, AuthModule, BetterAuthModule, FileModule, TusModule],
 
   // Include modules
   imports: [
@@ -49,6 +50,9 @@ import { ServerController } from './server.controller';
 
     // Include FileModule for file handling
     FileModule,
+
+    // Include TusModule for resumable file uploads
+    TusModule.forRoot(),
   ],
 
   providers: [Any, CronJobs, DateScalar, JSON],