@lenne.tech/nest-server 11.32.3 → 11.33.0

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

@@ -4,9 +4,21 @@ import { Server, Upload } from '@tus/server';
 import * as fs from 'fs';
 import { Connection, mongo } from 'mongoose';
 import * as path from 'path';
+import { Readable } from 'stream';
 
 import { GridFSHelper } from '../../common/helpers/gridfs.helper';
 import { ITusConfig } from '../../common/interfaces/server-options.interface';
+import { ConfigService } from '../../common/services/config.service';
+import { CoreRedisService } from '../../common/services/core-redis.service';
+import { CoreS3Service } from '../../common/services/core-s3.service';
+import { resolveFileStorage } from '../file/file-storage.helper';
+import {
+  DEFAULT_FILESYSTEM_DIR,
+  FILESYSTEM_FILES_COLLECTION,
+  FilesystemFileHelper,
+} from '../file/filesystem-file.helper';
+import { S3_FILES_COLLECTION, S3FileHelper } from '../file/s3-file.helper';
+import { TusRedisLocker } from './tus-redis-locker';
 import {
   DEFAULT_TUS_ALLOWED_HEADERS,
   DEFAULT_TUS_CONFIG,
@@ -14,11 +26,40 @@ import {
   parseExpirationTime,
 } from './interfaces/tus-config.interface';
 
+/**
+ * Optional dependencies of CoreTusService.
+ *
+ * With an enabled CoreS3Service, in-progress uploads are staged in the S3
+ * staging bucket instead of on local disk (`tus.s3Staging`), which keeps
+ * resumable uploads working across replica restarts.
+ */
+export interface CoreTusServiceOptions {
+  configService?: ConfigService;
+
+  /** Central Redis; when present, upload locks are shared across replicas */
+  redisService?: CoreRedisService;
+
+  s3Service?: CoreS3Service;
+}
+
 /**
  * Core TUS Service
  *
  * Provides integration with @tus/server for resumable file uploads.
- * After upload completion, files are migrated to GridFS and a File entity is created.
+ * After upload completion, files are migrated to the configured file storage
+ * (S3 when `file.storage: 's3'`, otherwise GridFS).
+ *
+ * Uploads in progress are staged either on local disk (`@tus/file-store`) or,
+ * when S3 is configured and `tus.s3Staging` is not disabled, in the S3 staging
+ * bucket (`@tus/s3-store`). When BOTH ends are that same S3 store, the finished
+ * upload is moved by S3 itself (`CopyObject`) instead of being streamed through
+ * this process — see `canCopyWithinS3()`.
+ *
+ * NOTE: give the staging bucket a lifecycle rule that expires incomplete
+ * multipart uploads — aborted TUS uploads leave parts behind that nothing else
+ * cleans up (the local-disk store is swept by the expiration cleanup below).
+ * Objects of COMPLETED uploads are not covered by such a rule and are removed
+ * explicitly instead — see `deleteStagedObjects()`.
  *
  * This service follows the Module Inheritance Pattern and can be extended in projects.
  */
@@ -30,7 +71,23 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
   private files: mongo.GridFSBucket;
   private cleanupInterval: NodeJS.Timeout | null = null;
 
-  constructor(private readonly connection: Connection) {
+  /** Datastore of the TUS server; set when uploads are staged in S3 */
+  protected s3Store: any = null;
+
+  /**
+   * Whether {@link CoreTusService.s3Store} was built from `options.s3Service`.
+   *
+   * Only then do staging and final storage share one endpoint, one region and one set of
+   * credentials — the precondition for letting S3 copy the finished upload internally. Tracked
+   * as a flag rather than inferred from `s3Store` being set, because a subclass may override
+   * {@link CoreTusService.createS3Store} to stage somewhere else entirely.
+   */
+  protected s3StoreSharesEndpoint = false;
+
+  constructor(
+    private readonly connection: Connection,
+    protected readonly options?: CoreTusServiceOptions,
+  ) {
     // Initialize with defaults - will be configured in onModuleInit or via configure()
     this.config = { ...DEFAULT_TUS_CONFIG };
   }
@@ -52,6 +109,12 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       return;
     }
 
+    // Idempotent on purpose: a second init would replace `tusServer` and `cleanupInterval`, and
+    // the replaced interval — no longer referenced — could never be cleared again.
+    if (this.tusServer) {
+      return;
+    }
+
     // Initialize GridFS bucket
     this.files = new mongo.GridFSBucket(this.connection.db, { bucketName: 'fs' });
 
@@ -60,7 +123,7 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
     await this.ensureUploadDir(uploadDir);
 
     // Create TUS server instance
-    this.tusServer = this.createTusServer(uploadDir);
+    this.tusServer = await this.createTusServer(uploadDir);
 
     // Setup expiration cleanup if enabled
     this.setupExpirationCleanup();
@@ -111,53 +174,290 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
    * what happens after an upload completes.
    */
   protected async onUploadComplete(upload: Upload): Promise<void> {
-    const uploadDir = this.config.uploadDir || DEFAULT_TUS_CONFIG.uploadDir;
-    const filePath = path.join(uploadDir, upload.id);
-
     try {
       // Extract metadata
       const metadata = this.parseMetadata(upload.metadata);
       const filename = metadata.filename || upload.id;
       const contentType = metadata.filetype || 'application/octet-stream';
+      const fileMetadata = {
+        originalMetadata: metadata,
+        tusUploadId: upload.id,
+        uploadedAt: new Date(),
+      };
+
+      // S3 → S3: hand the object over INSIDE S3 rather than pulling it down and pushing it back
+      // up. The streaming path below is correct but pins the finishing PATCH request — and the
+      // upload lock it holds — for a full download plus a full upload of the whole file. At the
+      // 50 GB default cap that is unbounded; even a few GB overruns a typical reverse-proxy read
+      // timeout, and it pays for the traffic twice.
+      if (this.canCopyWithinS3(upload)) {
+        const fileInfo = await S3FileHelper.copyFile(
+          this.options.s3Service,
+          this.connection.db.collection(S3_FILES_COLLECTION),
+          {
+            contentLength: upload.size,
+            contentType,
+            filename,
+            metadata: fileMetadata,
+            sourceBucket: this.options.s3Service.getConfig().stagingBucket,
+            sourceKey: upload.id,
+          },
+        );
+        this.logger.debug(
+          `Upload ${upload.id} copied inside S3 to ${fileInfo._id} (filename: ${filename}) — no bytes through this process`,
+        );
+        await this.deleteStagedUpload(upload.id);
+        return;
+      }
 
-      // Check if file exists
-      const fileExists = await fs.promises
-        .access(filePath)
-        .then(() => true)
-        .catch(() => false);
-      if (!fileExists) {
-        this.logger.warn(`Upload file not found at ${filePath}, skipping GridFS migration`);
+      const readStream = await this.readStagedUpload(upload.id);
+      if (!readStream) {
         return;
       }
 
-      // Read the completed file and upload to GridFS
-      const readStream = fs.createReadStream(filePath);
-      const fileInfo = await GridFSHelper.writeFileFromStream(this.files, readStream, {
-        contentType,
-        filename,
-        metadata: {
-          originalMetadata: metadata,
-          tusUploadId: upload.id,
-          uploadedAt: new Date(),
-        },
-      });
-
-      this.logger.debug(`Upload ${upload.id} migrated to GridFS as ${fileInfo._id} (filename: ${filename})`);
-
-      // Clean up the temporary file
-      await this.deleteTemporaryFile(upload.id);
+      if (this.fileStorageDriver === 'filesystem') {
+        const fileInfo = await FilesystemFileHelper.writeFile(
+          this.fileStorageDir,
+          this.connection.db.collection(FILESYSTEM_FILES_COLLECTION),
+          { body: readStream, contentType, filename, metadata: fileMetadata },
+        );
+        this.logger.debug(`Upload ${upload.id} migrated to the filesystem as ${fileInfo._id} (filename: ${filename})`);
+      } else if (this.s3FileStorage) {
+        const fileInfo = await S3FileHelper.writeFile(
+          this.options.s3Service,
+          this.connection.db.collection(S3_FILES_COLLECTION),
+          // Streamed with the length TUS already knows, so a multi-GB resumable upload is never
+          // materialised in memory.
+          { body: readStream, contentLength: upload.size, contentType, filename, metadata: fileMetadata },
+        );
+        this.logger.debug(`Upload ${upload.id} migrated to S3 as ${fileInfo._id} (filename: ${filename})`);
+      } else {
+        const fileInfo = await GridFSHelper.writeFileFromStream(this.files, readStream, {
+          contentType,
+          filename,
+          metadata: fileMetadata,
+        });
+        this.logger.debug(`Upload ${upload.id} migrated to GridFS as ${fileInfo._id} (filename: ${filename})`);
+      }
+
+      // Clean up the staged upload
+      await this.deleteStagedUpload(upload.id);
     } catch (error) {
-      this.logger.error(`Failed to migrate upload ${upload.id} to GridFS: ${error.message}`);
+      this.logger.error(`Failed to migrate upload ${upload.id}: ${error.message}`);
       throw error;
     }
   }
 
+  /**
+   * Which store a finished upload is migrated into.
+   *
+   * Deliberately the SAME resolution `CoreFileService` uses. A tus upload has to
+   * land where the download routes look for it — resolving this independently is
+   * how an upload ends up written to one store and read from another.
+   */
+  protected get fileStorageDriver(): string {
+    return resolveFileStorage(ConfigService.configFastButReadOnly).driver;
+  }
+
+  /** Directory used when uploads are migrated to the local filesystem */
+  protected get fileStorageDir(): string {
+    return ConfigService.configFastButReadOnly?.file?.storageDir || DEFAULT_FILESYSTEM_DIR;
+  }
+
+  /**
+   * Whether finished uploads are stored in S3 (`file.storage: 's3'`) instead of GridFS
+   */
+  protected get s3FileStorage(): boolean {
+    return !!this.options?.s3Service?.enabled && this.fileStorageDriver === 's3';
+  }
+
+  /**
+   * Whether the finished upload can be handed over inside S3 (server-side copy) instead of
+   * streaming through this process.
+   *
+   * Requires BOTH ends to be the same S3 store: staged by `createS3Store()` from
+   * `options.s3Service`, and a final driver of `'s3'` backed by that same service. Every other
+   * combination — S3 staging → GridFS, S3 staging → filesystem, local-disk staging → anything —
+   * genuinely has to transit the pod, because no store can reach into the other.
+   */
+  protected canCopyWithinS3(upload: Upload): boolean {
+    if (!this.s3StoreSharesEndpoint || !this.s3FileStorage) {
+      return false;
+    }
+
+    // A single CopyObject cannot move more than 5 GB; above that S3 requires multipart
+    // upload-part-copy. We fall back to streaming rather than implement that — but never
+    // silently: this is exactly the size at which the streaming cost the copy avoids becomes
+    // severe, so an operator seeing slow, timing-out completions needs to find the reason in
+    // the log rather than guess at it.
+    if (typeof upload.size !== 'number') {
+      this.logger.warn(
+        `Upload ${upload.id} has no known size, so it cannot be size-checked against the ${CoreS3Service.MAX_COPY_OBJECT_BYTES}-byte ` +
+          'CopyObject limit — streaming it through this process instead.',
+      );
+      return false;
+    }
+    if (upload.size > CoreS3Service.MAX_COPY_OBJECT_BYTES) {
+      this.logger.warn(
+        `Upload ${upload.id} is ${upload.size} bytes, above the ${CoreS3Service.MAX_COPY_OBJECT_BYTES}-byte limit of a single ` +
+          'S3 CopyObject (multipart upload-part-copy would be required). Streaming it through this process instead — ' +
+          'expect the finishing request to run for the duration of a full download plus a full upload.',
+      );
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Locker for upload exclusivity, or undefined to keep @tus/server's in-process default.
+   */
+  protected createLocker(): any {
+    const redisService = this.options?.redisService;
+    if (!redisService?.enabled) {
+      return undefined;
+    }
+    this.logger.debug('TUS upload locks are shared via Redis');
+    return new TusRedisLocker(redisService);
+  }
+
+  /**
+   * Import the optional peer dependency `@tus/s3-store`.
+   * Separate method so tests can substitute the module.
+   */
+  protected importS3Store(): Promise<any> {
+    return import('@tus/s3-store');
+  }
+
+  /**
+   * Create the S3 staging datastore.
+   * Returns null when S3 staging is not available, so the caller falls back to the local FileStore.
+   */
+  protected async createS3Store(): Promise<any> {
+    const s3Service = this.options?.s3Service;
+    if (!s3Service?.enabled || this.config.s3Staging === false) {
+      return null;
+    }
+
+    let s3StoreModule: any;
+    try {
+      s3StoreModule = await this.importS3Store();
+    } catch {
+      this.logger.warn(
+        'S3 is configured but the optional peer dependency "@tus/s3-store" is not installed — TUS uploads are ' +
+          'staged on local disk. Run: pnpm add @tus/s3-store',
+      );
+      return null;
+    }
+
+    const { accessKeyId, endpoint, forcePathStyle, region, secretAccessKey, stagingBucket } = s3Service.getConfig();
+    this.s3Store = new s3StoreModule.S3Store({
+      s3ClientConfig: {
+        bucket: stagingBucket,
+        forcePathStyle,
+        region,
+        ...(endpoint ? { endpoint } : {}),
+        ...(accessKeyId && secretAccessKey ? { credentials: { accessKeyId, secretAccessKey } } : {}),
+      },
+    });
+    // Built from the shared CoreS3Service, so a finished upload can be copied inside S3.
+    this.s3StoreSharesEndpoint = true;
+    this.logger.log(`TUS uploads staged in S3 bucket ${stagingBucket}`);
+    return this.s3Store;
+  }
+
+  /**
+   * Read a completed upload from its staging location (S3 or local disk).
+   * Returns null when the staged data is gone.
+   */
+  protected async readStagedUpload(uploadId: string): Promise<null | Readable> {
+    if (this.s3Store) {
+      return await this.s3Store.read(uploadId);
+    }
+
+    const uploadDir = this.config.uploadDir || DEFAULT_TUS_CONFIG.uploadDir;
+    const filePath = path.join(uploadDir, uploadId);
+    const fileExists = await fs.promises
+      .access(filePath)
+      .then(() => true)
+      .catch(() => false);
+    if (!fileExists) {
+      this.logger.warn(`Upload file not found at ${filePath}, skipping migration`);
+      return null;
+    }
+    return fs.createReadStream(filePath);
+  }
+
+  /**
+   * Delete a staged upload from its staging location (S3 or local disk)
+   */
+  protected async deleteStagedUpload(uploadId: string): Promise<void> {
+    if (this.s3Store) {
+      try {
+        // Still worth calling: for an upload that never finished, this aborts the multipart and
+        // frees the uploaded parts, which a DeleteObject cannot do.
+        await this.s3Store.remove(uploadId);
+      } catch (error) {
+        // `remove()` issues AbortMultipartUpload FIRST, and for a COMPLETED upload S3 answers
+        // NoSuchUpload. @tus/s3-store v2 swallows that by testing `error.code` — an AWS SDK v2
+        // field that SDK v3 never populates (v3 uses `error.name` / `$metadata.httpStatusCode`) —
+        // so the error escapes and the deletion that follows it never runs. Every finished upload
+        // therefore left a full second copy of the file behind, in a bucket that by default IS the
+        // file bucket. No lifecycle rule reaches those: they are completed objects, not incomplete
+        // multiparts. Hence the explicit cleanup below, which does not depend on the peer's guard.
+        if (!this.isMissingUploadError(error)) {
+          this.logger.warn(`Failed to remove staged upload ${uploadId} from S3: ${error.message}`);
+        }
+      }
+      await this.deleteStagedObjects(uploadId);
+      return;
+    }
+    await this.deleteTemporaryFile(uploadId);
+  }
+
+  /**
+   * Delete the staged object and its `.info` sidecar from the staging bucket.
+   *
+   * Unconditional and idempotent: when `S3Store.remove()` already got there, these are no-ops
+   * (S3 answers a successful delete for a key that does not exist), and when it did not, this is
+   * what actually reclaims the space.
+   */
+  protected async deleteStagedObjects(uploadId: string): Promise<void> {
+    const s3Service = this.options?.s3Service;
+    // Only when the staging store is OURS — a subclass may stage somewhere this service cannot see.
+    if (!this.s3StoreSharesEndpoint || !s3Service?.enabled) {
+      return;
+    }
+    const { stagingBucket } = s3Service.getConfig();
+    for (const key of [uploadId, `${uploadId}.info`]) {
+      try {
+        await s3Service.deleteObject(key, stagingBucket);
+      } catch (error) {
+        this.logger.warn(`Failed to delete staged object ${key} from S3 bucket ${stagingBucket}: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Whether an S3 error means "that upload/object is not there" — which, when cleaning up, is the
+   * outcome we wanted anyway.
+   *
+   * Matches on `name` and the HTTP status, never on `code`: that is the AWS SDK v2 shape, and
+   * relying on it is exactly the bug this guards against.
+   */
+  protected isMissingUploadError(error: any): boolean {
+    const name = error?.name ?? error?.Code;
+    return (
+      name === 'NoSuchUpload' || name === 'NoSuchKey' || name === 'NotFound' || error?.$metadata?.httpStatusCode === 404
+    );
+  }
+
   /**
    * Handle upload termination (deletion)
    */
   protected async onUploadTerminate(upload: Upload): Promise<void> {
     this.logger.debug(`Upload ${upload.id} terminated`);
-    await this.deleteTemporaryFile(upload.id);
+    await this.deleteStagedUpload(upload.id);
   }
 
   /**
@@ -203,12 +503,21 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
   /**
    * Create the TUS server instance with configured extensions
    */
-  private createTusServer(uploadDir: string): Server {
-    const datastore = new FileStore({ directory: uploadDir });
+  private async createTusServer(uploadDir: string): Promise<Server> {
+    const datastore = (await this.createS3Store()) || new FileStore({ directory: uploadDir });
+
+    // @tus/server's default locker is in-memory, which is exclusive within ONE process only:
+    // behind a load balancer two replicas each hold their own lock for the same upload id and
+    // both accept a PATCH, interleaving two byte ranges into one file. Resumable uploads are
+    // long-lived and clients retry, so requests for one upload landing on different replicas is
+    // the normal case. With Redis the lock is shared; without it the default stands, which is
+    // correct for the single-replica deployment that configuration describes.
+    const locker = this.createLocker();
 
     const server = new Server({
       allowedHeaders: this.config.allowedHeaders || DEFAULT_TUS_ALLOWED_HEADERS,
       datastore,
+      ...(locker ? { locker } : {}),
       maxSize: this.config.maxSize,
       onUploadCreate: async (_req, upload) => {
         // Validate file type if allowedTypes is configured
@@ -240,8 +549,16 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
           await this.onUploadComplete(upload);
           return {};
         } catch (error) {
+          // Do NOT swallow this. `onUploadComplete` is what moves the finished upload into its
+          // permanent store; returning `{}` after it failed answers the client with a 204 that
+          // says the upload completed while nothing was persisted. The client then deletes its
+          // local copy and the file is gone — a silent data loss, and the one failure mode a
+          // resumable-upload protocol exists to prevent. Failing loudly lets the client retry.
           this.logger.error(`Upload finish error: ${error.message}`);
-          return {};
+          throw Object.assign(new Error(`Upload could not be stored: ${error.message}`), {
+            body: 'Upload could not be stored',
+            status_code: 500,
+          });
         }
       },
       path: this.config.path || DEFAULT_TUS_CONFIG.path,
@@ -349,6 +666,8 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       },
       60 * 60 * 1000,
     );
+    // An hourly sweep must never be the thing keeping the process alive.
+    this.cleanupInterval.unref?.();
 
     this.logger.debug(`Expiration cleanup scheduled (expire after ${expiresIn})`);
   }
@@ -357,6 +676,11 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
    * Clean up expired incomplete uploads
    */
   private async cleanupExpiredUploads(maxAgeMs: number): Promise<void> {
+    if (this.s3Store) {
+      // Aborted uploads live in the S3 staging bucket — expire them with a
+      // bucket lifecycle rule for incomplete multipart uploads instead.
+      return;
+    }
     const uploadDir = this.config.uploadDir || DEFAULT_TUS_CONFIG.uploadDir;
     const now = Date.now();
 

package/src/core/modules/tus/interfaces/tus-config.interface.ts

@@ -4,6 +4,7 @@
  * The interfaces are defined in server-options.interface.ts to avoid circular imports.
  * This file contains helper functions and defaults.
  */
+import { RoleEnum } from '../../../common/enums/role.enum';
 import { ITusConfig, ITusExpirationConfig } from '../../../common/interfaces/server-options.interface';
 
 // Re-export for convenience
@@ -46,6 +47,14 @@ export const DEFAULT_TUS_CONFIG: Required<
   expiration: { enabled: true, expiresIn: '24h' },
   maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
   path: '/tus',
+  // A tus upload writes into the SAME file store that `file.downloadRoles`
+  // guards — GridFS or S3, whichever `file.storage` selects — and with the
+  // termination extension it can delete from it too. Requiring a session is the
+  // least that keeps the module's own posture coherent: anonymous 50 GB writes
+  // into a store only admins may read is not a defensible default. Widen
+  // deliberately via `tus: { roles: [...] }`.
+  roles: [RoleEnum.S_USER],
+  s3Staging: true,
   termination: true,
   uploadDir: 'uploads/tus',
 };

package/src/core/modules/tus/tus-redis-locker.ts

@@ -0,0 +1,139 @@
+import { Logger } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+
+import { CoreRedisService } from '../../common/services/core-redis.service';
+
+/** Release callback handed to the current lock holder when someone else wants the resource */
+type RequestRelease = () => Promise<void> | void;
+
+/**
+ * TUS lock that is exclusive across REPLICAS, not just within one process.
+ *
+ * `@tus/server` defaults to an in-memory locker, which is exactly right for one process and
+ * useless behind a load balancer: two replicas each hold their own lock for the same upload id
+ * and both accept a PATCH, so two byte ranges are written to one upload and the file ends up
+ * interleaved. Resumable uploads are long-lived and clients retry aggressively, so a request
+ * pair landing on different replicas is the normal case, not a rare one.
+ *
+ * The lock is a Redis key with a TTL held only while a request is being served, refreshed by a
+ * heartbeat so a slow but live PATCH keeps it, and released in `unlock()`. A holder that dies
+ * mid-request stops refreshing and the key expires — the upload becomes writable again instead
+ * of being stuck until someone intervenes.
+ */
+export class TusRedisLock {
+  protected heartbeat?: NodeJS.Timeout;
+
+  /** Random per-acquisition value, so only the actual holder can release or refresh the lock */
+  protected token?: string;
+
+  constructor(
+    protected readonly redisService: CoreRedisService,
+    protected readonly key: string,
+    protected readonly ttlMs: number,
+    protected readonly acquireTimeoutMs: number,
+  ) {}
+
+  /**
+   * Wait for exclusive access to the upload, or throw once the timeout is reached.
+   *
+   * `cancelReq` is the TUS mechanism for cooperative handover: when a newer request wants an
+   * upload we already hold, the holder is asked to let go rather than made to wait it out.
+   */
+  async lock(signal: AbortSignal, cancelReq: RequestRelease): Promise<void> {
+    const deadline = Date.now() + this.acquireTimeoutMs;
+    // randomUUID, not Math.random: this token is the ONLY thing separating "holds the lock" from
+    // "does not" in the compare-and-delete below and in the heartbeat's PEXPIRE. A collision lets
+    // one holder refresh or release another's lock, and two replicas then interleave byte ranges
+    // into one upload — the exact corruption this locker exists to prevent.
+    const token = `${process.pid}-${randomUUID()}`;
+
+    for (;;) {
+      const acquired = await this.redisService.getClient().set(this.key, token, 'PX', this.ttlMs, 'NX');
+
+      if (acquired === 'OK') {
+        this.token = token;
+        this.startHeartbeat();
+        return;
+      }
+
+      // Tell whoever holds it that someone else is waiting. Signalling on every attempt is
+      // deliberate: the holder may be on another replica and only learns of us through this.
+      await cancelReq();
+
+      if (signal.aborted || Date.now() > deadline) {
+        throw new Error(`Could not acquire the upload lock for "${this.key}" within ${this.acquireTimeoutMs}ms`);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  /** Release the lock — only if we still hold it */
+  async unlock(): Promise<void> {
+    this.stopHeartbeat();
+    const token = this.token;
+    this.token = undefined;
+    if (!token) {
+      return;
+    }
+
+    // Compare-and-delete: after our TTL expired the key may already belong to someone else,
+    // and deleting it blindly would unlock an upload another replica is actively writing.
+    const script = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+    try {
+      await this.redisService.getClient().eval(script, 1, this.key, token);
+    } catch {
+      // The key expires on its own; a failed release costs at most one TTL of waiting.
+    }
+  }
+
+  /** Keep the lock alive while the request is still being served */
+  protected startHeartbeat(): void {
+    this.heartbeat = setInterval(
+      () => {
+        const token = this.token;
+        if (!token) {
+          return;
+        }
+        const script = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0`;
+        this.redisService
+          .getClient()
+          .eval(script, 1, this.key, token, this.ttlMs)
+          .catch(() => undefined);
+      },
+      Math.max(1000, Math.floor(this.ttlMs / 3)),
+    );
+    this.heartbeat.unref?.();
+  }
+
+  protected stopHeartbeat(): void {
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = undefined;
+    }
+  }
+}
+
+/**
+ * Locker handed to `@tus/server` when Redis is configured (see {@link TusRedisLock}).
+ */
+export class TusRedisLocker {
+  protected readonly logger = new Logger(TusRedisLocker.name);
+
+  constructor(
+    protected readonly redisService: CoreRedisService,
+    /** How long a lock survives without a heartbeat — a dead holder's upload frees itself */
+    protected readonly ttlMs = 30_000,
+    /** How long a request waits for a busy upload before giving up with 500 */
+    protected readonly acquireTimeoutMs = 10_000,
+  ) {}
+
+  newLock(id: string): TusRedisLock {
+    return new TusRedisLock(
+      this.redisService,
+      this.redisService.key('tus-lock', id),
+      this.ttlMs,
+      this.acquireTimeoutMs,
+    );
+  }
+}