@lenne.tech/nest-server 11.7.3 → 11.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.7.3",
+  "version": "11.8.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -93,6 +93,8 @@
     "@nestjs/swagger": "11.2.3",
     "@nestjs/terminus": "11.0.0",
     "@nestjs/websockets": "11.1.9",
+    "@tus/file-store": "2.0.0",
+    "@tus/server": "2.3.0",
     "apollo-server-core": "3.13.0",
     "bcrypt": "6.0.0",
     "better-auth": "1.4.8-beta.4",
@@ -167,6 +169,7 @@
     "ts-morph": "27.0.2",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
+    "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
     "vite": "7.3.0",

package/src/core/common/interfaces/server-options.interface.ts

@@ -1132,4 +1132,158 @@ export interface IServerOptions {
      */
     path?: string;
   };
+
+  /**
+   * TUS resumable upload configuration.
+   *
+   * Follows the "Enabled by Default" pattern - tus is automatically enabled
+   * without any configuration. Set `tus: false` to explicitly disable.
+   *
+   * Accepts:
+   * - `true` or `undefined`: Enable with defaults (enabled by default)
+   * - `false`: Disable TUS uploads
+   * - `{ ... }`: Enable with custom configuration
+   *
+   * @example
+   * ```typescript
+   * // Default: TUS enabled with all defaults (no config needed)
+   *
+   * // Disable TUS
+   * tus: false,
+   *
+   * // Custom configuration
+   * tus: {
+   *   maxSize: 100 * 1024 * 1024, // 100 MB
+   *   path: '/uploads',
+   * },
+   * ```
+   *
+   * @since 11.8.0
+   */
+  tus?: boolean | ITusConfig;
+}
+
+/**
+ * TUS Upload Configuration Interface
+ *
+ * Follows the "Enabled by Default" pattern - tus is automatically enabled
+ * without any configuration. Set `tus: false` to explicitly disable.
+ */
+export interface ITusConfig {
+  /**
+   * Additional allowed HTTP headers for TUS requests (beyond @tus/server defaults).
+   *
+   * Note: @tus/server already includes all TUS protocol headers:
+   * Authorization, Content-Type, Location, Tus-Extension, Tus-Max-Size,
+   * Tus-Resumable, Tus-Version, Upload-Concat, Upload-Defer-Length,
+   * Upload-Length, Upload-Metadata, Upload-Offset, X-HTTP-Method-Override,
+   * X-Requested-With, X-Forwarded-Host, X-Forwarded-Proto, Forwarded
+   *
+   * Use this only for project-specific custom headers.
+   *
+   * @default [] (no additional headers needed)
+   */
+  allowedHeaders?: string[];
+
+  /**
+   * Allowed MIME types for uploads.
+   * If undefined, all types are allowed.
+   * @default undefined (all types allowed)
+   */
+  allowedTypes?: string[];
+
+  /**
+   * Checksum extension configuration.
+   * Enables data integrity verification.
+   * @default true
+   */
+  checksum?: boolean;
+
+  /**
+   * Concatenation extension configuration.
+   * Allows parallel uploads that are merged.
+   * @default true
+   */
+  concatenation?: boolean;
+
+  /**
+   * Creation extension configuration.
+   * Allows creating new uploads via POST.
+   * @default true
+   */
+  creation?: boolean | ITusCreationConfig;
+
+  /**
+   * Creation With Upload extension configuration.
+   * Allows sending data in the initial POST request.
+   * @default true
+   */
+  creationWithUpload?: boolean;
+
+  /**
+   * Whether tus uploads are enabled.
+   * @default true (enabled by default)
+   */
+  enabled?: boolean;
+
+  /**
+   * Expiration extension configuration.
+   * Automatically cleans up incomplete uploads.
+   * @default { expiresIn: '24h' }
+   */
+  expiration?: boolean | ITusExpirationConfig;
+
+  /**
+   * Maximum upload size in bytes
+   * @default 50 * 1024 * 1024 * 1024 (50 GB)
+   */
+  maxSize?: number;
+
+  /**
+   * Base path for tus endpoints
+   * @default '/tus'
+   */
+  path?: string;
+
+  /**
+   * Termination extension configuration.
+   * Allows deleting uploads via DELETE.
+   * @default true
+   */
+  termination?: boolean;
+
+  /**
+   * Directory for temporary upload chunks.
+   * @default 'uploads/tus'
+   */
+  uploadDir?: string;
+}
+
+/**
+ * TUS Creation extension configuration
+ */
+export interface ITusCreationConfig {
+  /**
+   * Whether creation is enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * TUS Expiration extension configuration
+ */
+export interface ITusExpirationConfig {
+  /**
+   * Whether expiration is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Time until incomplete uploads expire
+   * Supports formats: '24h', '1d', '12h', etc.
+   * @default '24h'
+   */
+  expiresIn?: string;
 }

package/src/core/modules/file/README.md

@@ -0,0 +1,165 @@
+# File Module
+
+File upload and download functionality with MongoDB GridFS storage.
+
+## Endpoints
+
+### Public Endpoints (via CoreFileController)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/files/id/:id` | Download file by ID |
+| GET | `/files/:filename` | Download file by filename |
+
+**Note:** These endpoints are public (`S_EVERYONE`) by default. Projects can restrict access by extending `CoreFileController`.
+
+### Admin Endpoints (project-specific)
+
+Projects typically add admin-only endpoints like:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/files/upload` | Upload file (multipart/form-data) |
+| GET | `/files/info/:id` | Get file metadata |
+| DELETE | `/files/:id` | Delete file |
+
+---
+
+## Usage in Projects
+
+### Basic Setup (Extend CoreFileController)
+
+```typescript
+// src/server/modules/file/file.controller.ts
+import { Controller } from '@nestjs/common';
+import { CoreFileController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+import { FileService } from './file.service';
+
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+
+  // Add admin-only endpoints here (upload, delete, etc.)
+}
+```
+
+### Restrict Download Access
+
+To require authentication for downloads, override the inherited methods:
+
+```typescript
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+
+  // Override to require authentication for ID-based download
+  @Get('id/:id')
+  @Roles(RoleEnum.S_USER) // Require logged-in user
+  override async getFileById(@Param('id') id: string, @Res() res: Response) {
+    return super.getFileById(id, res);
+  }
+
+  // Override to require authentication for filename-based download
+  @Get(':filename')
+  @Roles(RoleEnum.S_USER)
+  override async getFile(@Param('filename') filename: string, @Res() res: Response) {
+    return super.getFile(filename, res);
+  }
+}
+```
+
+---
+
+## GraphQL Support
+
+File operations are also available via GraphQL through `CoreFileResolver`:
+
+```graphql
+# Query file by ID
+query {
+  file(id: "...") {
+    id
+    filename
+    contentType
+    length
+  }
+}
+
+# Query file by filename
+query {
+  fileByFilename(filename: "...") {
+    id
+    filename
+    contentType
+  }
+}
+
+# Upload file (via GraphQL Upload scalar)
+mutation {
+  uploadFile(file: Upload!) {
+    id
+    filename
+  }
+}
+
+# Delete file
+mutation {
+  deleteFile(filename: "...") {
+    id
+  }
+}
+```
+
+---
+
+## Integration with TUS
+
+Files uploaded via TUS are automatically stored in GridFS and can be accessed through the same endpoints:
+
+```bash
+# After TUS upload completes, download by ID
+GET /files/id/<gridfs-file-id>
+
+# Or by filename (if unique)
+GET /files/<original-filename>
+```
+
+**Recommendation:** Use ID-based downloads for TUS uploads as filenames may not be unique.
+
+---
+
+## GridFS Storage
+
+Files are stored in MongoDB GridFS with the following structure:
+
+**fs.files collection:**
+```json
+{
+  "_id": ObjectId,
+  "filename": "example.pdf",
+  "length": 1048576,
+  "uploadDate": ISODate,
+  "metadata": {
+    "contentType": "application/pdf",
+    "tusUploadId": "...",  // If uploaded via TUS
+    "uploadedAt": ISODate
+  }
+}
+```
+
+**fs.chunks collection:**
+- Binary file data split into 255KB chunks
+- Automatically managed by GridFS
+
+---
+
+## Related Documentation
+
+- [TUS Module](../tus/README.md) - Resumable upload protocol
+- [CoreFileService](./core-file.service.ts) - File service implementation

package/src/core/modules/file/core-file.controller.ts

@@ -17,7 +17,33 @@ export abstract class CoreFileController {
   protected constructor(protected fileService: CoreFileService) {}
 
   /**
-   * Download file
+   * Download file by ID
+   *
+   * More reliable than filename-based download as IDs are unique.
+   * Recommended for TUS uploads and when filename uniqueness cannot be guaranteed.
+   */
+  @Get('id/:id')
+  @Roles(RoleEnum.S_EVERYONE)
+  async getFileById(@Param('id') id: string, @Res() res: Response) {
+    if (!id) {
+      throw new BadRequestException('Missing file ID for download');
+    }
+
+    const file = await this.fileService.getFileInfo(id);
+    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}`);
+    return filestream.pipe(res);
+  }
+
+  /**
+   * Download file by filename
+   *
+   * Note: If multiple files have the same filename, only the first match is returned.
+   * For unique file access, use GET /files/id/:id instead.
    */
   @Get(':filename')
   @Roles(RoleEnum.S_EVERYONE)

package/src/core/modules/tus/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,176 @@
+# TUS Integration Checklist
+
+**For customizing TUS uploads in projects using `@lenne.tech/nest-server`.**
+
+> **Note:** TUS is **enabled by default** with no configuration needed. This checklist is only for projects that need to customize behavior (e.g., require authentication).
+
+---
+
+## Do You Need This Checklist?
+
+| Scenario | Checklist Needed? |
+|----------|-------------------|
+| Use TUS with defaults (everyone can upload) | No - works automatically |
+| Require authentication for uploads | Yes - Step 1 |
+| Custom upload handling (notifications, etc.) | Yes - Step 2 |
+| Disable TUS completely | No - just use `TusModule.forRoot({ config: false })` |
+
+---
+
+## Reference Implementation
+
+**Local (in your node_modules):**
+```
+node_modules/@lenne.tech/nest-server/src/server/server.module.ts
+```
+
+**GitHub:**
+https://github.com/lenneTech/nest-server/tree/develop/src/server
+
+---
+
+## Step 1: Custom Controller (Require Authentication)
+
+**Create:** `src/server/modules/tus/tus.controller.ts`
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { CoreTusController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+
+@Controller('tus')
+@Roles(RoleEnum.S_USER) // Require authenticated user
+export class TusController extends CoreTusController {
+  // All methods inherit the S_USER requirement
+  // Override methods here for custom logic
+}
+```
+
+**Update ServerModule:**
+
+```typescript
+// src/server/server.module.ts
+import { TusModule } from '@lenne.tech/nest-server';
+import { TusController } from './modules/tus/tus.controller';
+
+@Module({
+  imports: [
+    // ... other imports
+    TusModule.forRoot({
+      controller: TusController, // Use custom controller
+    }),
+  ],
+})
+export class ServerModule {}
+```
+
+---
+
+## Step 2: Custom Service (Custom Upload Handling)
+
+**Create:** `src/server/modules/tus/tus.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CoreTusService } from '@lenne.tech/nest-server';
+import { Upload } from '@tus/server';
+
+@Injectable()
+export class TusService extends CoreTusService {
+  protected override async onUploadComplete(upload: Upload): Promise<void> {
+    // Call parent to handle GridFS migration
+    await super.onUploadComplete(upload);
+
+    // Add custom logic
+    const metadata = upload.metadata;
+    console.log(`Upload complete: ${metadata.filename}`);
+    // await this.notificationService.sendUploadComplete(...);
+  }
+}
+```
+
+**Note:** To use a custom service, you'll need to create a custom TusModule that provides your service instead of CoreTusService.
+
+---
+
+## Configuration Options
+
+### Default Configuration (No Changes Needed)
+
+```typescript
+// TUS works with these defaults:
+{
+  enabled: true,
+  path: '/tus',
+  maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
+  expiration: { expiresIn: '24h' },
+}
+```
+
+### Custom Configuration
+
+```typescript
+// server.module.ts
+TusModule.forRoot({
+  config: {
+    maxSize: 100 * 1024 * 1024, // 100 MB
+    path: '/uploads',
+    expiration: { expiresIn: '12h' },
+  },
+})
+```
+
+### Disable TUS
+
+```typescript
+TusModule.forRoot({ config: false })
+```
+
+---
+
+## Verification Checklist
+
+- [ ] `npm run build` succeeds
+- [ ] `npm test` passes
+- [ ] `OPTIONS /tus` returns TUS capabilities
+- [ ] Upload via tus-js-client works
+- [ ] File appears in GridFS after upload completion
+- [ ] (If customized) Authentication is required for uploads
+
+---
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Forgot to register custom controller | Default S_EVERYONE permissions | Add `controller: TusController` to forRoot() |
+| Custom controller missing @Roles | No authentication required | Add `@Roles(RoleEnum.S_USER)` to controller class |
+| Using wrong endpoint path | 404 on upload | Ensure client uses same path as config |
+
+---
+
+## Client Configuration
+
+```typescript
+import { Upload } from 'tus-js-client';
+
+const upload = new Upload(file, {
+  endpoint: 'http://localhost:3000/tus',
+  headers: {
+    Authorization: `Bearer ${token}`, // If authentication required
+  },
+  metadata: {
+    filename: file.name,
+    filetype: file.type,
+  },
+  onSuccess: () => console.log('Upload complete!'),
+});
+
+upload.start();
+```
+
+---
+
+## Detailed Documentation
+
+- **README.md:** `node_modules/@lenne.tech/nest-server/src/core/modules/tus/README.md`
+- **GitHub:** https://github.com/lenneTech/nest-server/blob/develop/src/core/modules/tus/README.md