Skip to content

Papermark is the open-source DocSend alternative and secure data rooms with built-in analytics and custom domains.

feat: add distributed locker for tus

Marc Seitz22c9c112c18e
diff --git a/.env.example b/.env.example
index 81df80cb..c9bcc4ba 100644
--- a/.env.example
+++ b/.env.example
@@ -63,4 +63,9 @@ NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_ID=""
NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_CONTENTS=
# Encryption key for document passwords.
-NEXT_PRIVATE_DOCUMENT_PASSWORD_KEY=my-superstrong-document-secret
\ No newline at end of file
+NEXT_PRIVATE_DOCUMENT_PASSWORD_KEY=my-superstrong-document-secret
+
+# [[REDIS LOCKER CONFIGURATION]]
+# For bulk upload using tus.io, we use a Redis-based locker to prevent corruption of the data.
+UPSTASH_REDIS_REST_LOCKER_URL=
+UPSTASH_REDIS_REST_LOCKER_TOKEN=
\ No newline at end of file
diff --git a/lib/files/tus-redis-locker.ts b/lib/files/tus-redis-locker.ts
new file mode 100644
index 00000000..7fcd03cf
--- /dev/null
+++ b/lib/files/tus-redis-locker.ts
@@ -0,0 +1,133 @@
+import { ERRORS, Lock, Locker, RequestRelease } from "@tus/utils";
+import { Redis } from "@upstash/redis";
+import { request } from "node:http";
+
+/**
+ * RedisLocker is an implementation of the Locker interface that manages locks in key-value store using Redis.
+ * This class is designed for exclusive access control over resources, often used in scenarios like upload management.
+ *
+ * Key Features:
+ * - Ensures exclusive resource access by using a KV-based map to track locks.
+ * - Implements timeout for lock acquisition, mitigating deadlock situations.
+ * - Facilitates both immediate and graceful release of locks through different mechanisms.
+ *
+ * Locking Behavior:
+ * - When the `lock` method is invoked for an already locked resource, the `cancelReq` callback is called.
+ * This signals to the current lock holder that another process is requesting the lock, encouraging them to release it as soon as possible.
+ * - The lock attempt continues until the specified timeout is reached. If the timeout expires and the lock is still not
+ * available, an error is thrown to indicate lock acquisition failure.
+ *
+ * Lock Acquisition and Release:
+ * - The `lock` method implements a wait mechanism, allowing a lock request to either succeed when the lock becomes available,
+ * or fail after the timeout period.
+ * - The `unlock` method releases a lock, making the resource available for other requests.
+ */
+
+interface RedisLockerOptions {
+ acquireLockTimeout?: number;
+ redisClient: Redis;
+}
+
+export class RedisLocker implements Locker {
+ timeout: number;
+ redisClient: Redis;
+
+ constructor(options: RedisLockerOptions) {
+ this.timeout = options.acquireLockTimeout ?? 1000 * 30; // default: 30 seconds
+ this.redisClient = options.redisClient;
+ }
+
+ newLock(id: string) {
+ return new RedisLock(id, this, this.timeout);
+ }
+}
+
+class RedisLock implements Lock {
+ constructor(
+ private id: string,
+ private locker: RedisLocker,
+ private timeout: number = 1000 * 30, // default: 30 seconds
+ ) {}
+
+ async lock(requestRelease: RequestRelease): Promise<void> {
+ const abortController = new AbortController();
+ const lock = await Promise.race([
+ this.waitTimeout(abortController.signal),
+ this.acquireLock(this.id, requestRelease, abortController.signal),
+ ]);
+
+ abortController.abort();
+
+ if (!lock) {
+ throw ERRORS.ERR_LOCK_TIMEOUT;
+ }
+ }
+
+ protected async acquireLock(
+ id: string,
+ requestRelease: RequestRelease,
+ signal: AbortSignal,
+ ): Promise<boolean> {
+ if (signal.aborted) {
+ return false;
+ }
+
+ const lockKey = `tus-lock-${id}`;
+ const lock = await this.locker.redisClient.set(lockKey, "locked", {
+ nx: true,
+ px: this.timeout,
+ });
+
+ if (lock) {
+ // Register a release request flag in Redis
+ await this.locker.redisClient.set(`requestRelease:${lockKey}`, "true", {
+ px: this.timeout,
+ });
+ return true;
+ }
+
+ // Check if the release was requested
+ const releaseRequestStr: string | null = await this.locker.redisClient.get(
+ `requestRelease:${lockKey}`,
+ );
+ if (releaseRequestStr === "true") {
+ await requestRelease?.();
+ }
+
+ await new Promise((resolve, reject) => {
+ setImmediate(() => {
+ this.acquireLock(id, requestRelease, signal)
+ .then(resolve)
+ .catch(reject);
+ });
+ });
+
+ return false;
+ }
+
+ async unlock(): Promise<void> {
+ const lockKey = `tus-lock-${this.id}`;
+ const lockExists = await this.locker.redisClient.del(lockKey);
+ if (!lockExists) {
+ throw new Error("Releasing an unlocked lock!");
+ }
+
+ // Clean up the request release entry
+ await this.locker.redisClient.del(`requestRelease:${lockKey}`);
+ }
+
+ protected waitTimeout(signal: AbortSignal) {
+ return new Promise<boolean>((resolve) => {
+ const timeout = setTimeout(() => {
+ resolve(false);
+ }, this.timeout);
+
+ const abortListener = () => {
+ clearTimeout(timeout);
+ signal.removeEventListener("abort", abortListener);
+ resolve(false);
+ };
+ signal.addEventListener("abort", abortListener);
+ });
+ }
+}
diff --git a/lib/redis.ts b/lib/redis.ts
index 27def91b..9145934f 100644
--- a/lib/redis.ts
+++ b/lib/redis.ts
@@ -4,3 +4,8 @@ export const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL as string,
token: process.env.UPSTASH_REDIS_REST_TOKEN as string,
});
+
+export const lockerRedisClient = new Redis({
+ url: process.env.UPSTASH_REDIS_REST_LOCKER_URL as string,
+ token: process.env.UPSTASH_REDIS_REST_LOCKER_TOKEN as string,
+});
diff --git a/package-lock.json b/package-lock.json
index 3ffcddb6..90f7620c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -49,6 +49,7 @@
"@trigger.dev/sdk": "^2.3.19",
"@tus/s3-store": "^1.5.0",
"@tus/server": "^1.7.0",
+ "@tus/utils": "^0.3.0",
"@upstash/qstash": "^2.6.0",
"@upstash/ratelimit": "^1.2.1",
"@upstash/redis": "^1.32.0",
diff --git a/package.json b/package.json
index 667038c6..dfecd203 100644
--- a/package.json
+++ b/package.json
@@ -58,6 +58,7 @@
"@trigger.dev/sdk": "^2.3.19",
"@tus/s3-store": "^1.5.0",
"@tus/server": "^1.7.0",
+ "@tus/utils": "^0.3.0",
"@upstash/qstash": "^2.6.0",
"@upstash/ratelimit": "^1.2.1",
"@upstash/redis": "^1.32.0",
diff --git a/pages/api/file/tus/[[...file]].ts b/pages/api/file/tus/[[...file]].ts
index adcd6e82..612e1056 100644
--- a/pages/api/file/tus/[[...file]].ts
+++ b/pages/api/file/tus/[[...file]].ts
@@ -6,7 +6,9 @@ import { Server } from "@tus/server";
import { getServerSession } from "next-auth/next";
import path from "node:path";
+import { RedisLocker } from "@/lib/files/tus-redis-locker";
import { newId } from "@/lib/id-helper";
+import { lockerRedisClient } from "@/lib/redis";
import { log } from "@/lib/utils";
import { authOptions } from "../../auth/[...nextauth]";
@@ -17,11 +19,16 @@ export const config = {
},
};
+const locker = new RedisLocker({
+ redisClient: lockerRedisClient,
+});
+
const tusServer = new Server({
// `path` needs to match the route declared by the next file router
path: "/api/file/tus",
maxSize: 1024 * 1024 * 1024 * 2, // 2 GiB
respectForwardedHeaders: true,
+ locker,
datastore: new S3Store({
partSize: 8 * 1024 * 1024, // each uploaded part will have ~8MiB,
// TODO: expirationPeriodInMilliseconds is not working due to a permissions issue