tina4-nodejs 3.13.39 → 3.13.41

package/packages/core/src/queueBackends/liteBackend.ts

@@ -24,9 +24,19 @@ import { createJob, type JobQueueBridge } from "../job.js";
 export class LiteBackend {
   private basePath: string;
   private seq: number = 0;
+  /**
+   * Reservation/visibility timeout (seconds). A popped job is held in reserved/
+   * with availableAt = now + visibilityTimeout. If the consumer dies before
+   * complete()/fail() (crash, OOM, k8s eviction) the next pop() reclaims it once
+   * the window expires — incrementing attempts and re-enqueuing, or
+   * dead-lettering past maxRetries. <= 0 disables the reclaim (a reservation
+   * then lasts until the consumer acks — the old at-most-once behaviour).
+   */
+  private visibilityTimeout: number;
 
-  constructor(basePath: string = "data/queue") {
+  constructor(basePath: string = "data/queue", visibilityTimeout: number = 300) {
     this.basePath = basePath;
+    this.visibilityTimeout = visibilityTimeout;
   }
 
   private ensureDir(queue: string): string {
@@ -41,6 +51,24 @@ export class LiteBackend {
     return dir;
   }
 
+  private ensureReservedDir(queue: string): string {
+    const dir = join(this.basePath, queue, "reserved");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  private reservedPath(queue: string, jobId: string): string {
+    return join(this.ensureReservedDir(queue), `${jobId}.queue-data`);
+  }
+
+  private nowIso(): string {
+    return new Date().toISOString();
+  }
+
+  private futureIso(seconds: number): string {
+    return new Date(Date.now() + seconds * 1000).toISOString();
+  }
+
   private nextPrefix(): string {
     this.seq++;
     return `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
@@ -111,22 +139,112 @@ export class LiteBackend {
     return candidates;
   }
 
+  /**
+   * Persist a reservation record so a dead consumer's job is reclaimable.
+   *
+   * Stores reservedAt + availableAt = now + visibilityTimeout. The next pop()
+   * reclaims this job once availableAt has passed (see reclaimExpired).
+   * complete()/fail()/retry() delete the record.
+   */
+  private writeReserved(queue: string, job: any): void {
+    const now = this.nowIso();
+    const vt = this.visibilityTimeout || 0;
+    const record = {
+      id: job.id,
+      payload: job.payload,
+      status: "reserved" as const,
+      priority: job.priority ?? 0,
+      attempts: job.attempts ?? 0,
+      error: job.error,
+      reservedAt: now,
+      availableAt: vt > 0 ? this.futureIso(vt) : now,
+      createdAt: job.createdAt ?? now,
+      topic: job.topic ?? queue,
+    };
+    writeFileSync(this.reservedPath(queue, record.id), JSON.stringify(record, null, 2));
+  }
+
+  /**
+   * Return expired reservations to the queue (at-least-once delivery).
+   *
+   * A reserved job whose availableAt <= now means its consumer never
+   * acknowledged in time (crash / OOM / pod eviction). Atomically claim it
+   * (delete the reservation file), increment attempts, and either re-enqueue it
+   * (so the next pop picks it up) or dead-letter it once it has hit maxRetries.
+   * Disabled when visibilityTimeout <= 0.
+   */
+  private reclaimExpired(queue: string, maxRetries: number, now: string): void {
+    if (!this.visibilityTimeout || this.visibilityTimeout <= 0) return;
+    const reservedDir = this.ensureReservedDir(queue);
+
+    let filenames: string[];
+    try {
+      filenames = readdirSync(reservedDir).filter(f => f.endsWith(".queue-data"));
+    } catch {
+      return;
+    }
+
+    for (const filename of filenames) {
+      const filePath = join(reservedDir, filename);
+      let record: any;
+      try {
+        record = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        continue;
+      }
+      if (record.availableAt && record.availableAt > now) continue; // still valid
+      // Atomically claim the expired reservation by deleting its file.
+      try {
+        unlinkSync(filePath);
+      } catch {
+        continue; // another worker reclaimed it first
+      }
+
+      const attempts = (record.attempts ?? 0) + 1;
+      const error = "reservation timed out — consumer did not acknowledge within the visibility timeout";
+      const job: QueueJob = {
+        id: record.id,
+        payload: record.payload,
+        status: "reserved",
+        createdAt: record.createdAt ?? now,
+        attempts,
+        delayUntil: null,
+        priority: record.priority ?? 0,
+        topic: record.topic ?? queue,
+        error,
+      } as QueueJob;
+
+      if (attempts >= maxRetries) {
+        this.deadLetter(queue, job, error);
+      } else {
+        this.requeue(queue, job, 0, error);
+      }
+    }
+  }
+
   pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
     const dir = this.ensureDir(queue);
-    const now = new Date().toISOString();
+    // First return any reservations whose consumer died mid-flight.
+    this.reclaimExpired(queue, bridge.getMaxRetries(), this.nowIso());
+    const now = this.nowIso();
 
     for (const [filename, job] of this.availableCandidates(queue, now)) {
       const filePath = join(dir, filename);
-      // Claim the job by deleting the file.
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      // Write the reservation BEFORE claiming the pending file, so a crash
+      // between claim and reserve can never strand the job. Only the worker
+      // that wins the unlink owns — and returns — it.
+      this.writeReserved(queue, job);
       try {
         unlinkSync(filePath);
       } catch {
-        continue; // Already consumed by another worker
+        // Already consumed by another worker — drop the speculative reservation.
+        try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
+        continue;
       }
 
       job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
       return createJob(job as any, bridge);
     }
 
@@ -135,34 +253,61 @@ export class LiteBackend {
 
   popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
     const dir = this.ensureDir(queue);
-    const now = new Date().toISOString();
+    this.reclaimExpired(queue, bridge.getMaxRetries(), this.nowIso());
+    const now = this.nowIso();
     const results: QueueJob[] = [];
 
     for (const [filename, job] of this.availableCandidates(queue, now)) {
       if (results.length >= count) break;
       const filePath = join(dir, filename);
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      this.writeReserved(queue, job);
       try {
         unlinkSync(filePath);
       } catch {
+        try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
         continue; // Already consumed by another worker
       }
 
       job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
       results.push(createJob(job as any, bridge));
     }
 
     return results;
   }
 
+  /**
+   * Delete a job's reservation record (best-effort).
+   */
+  private clearReservation(queue: string, jobId: string): void {
+    try {
+      unlinkSync(this.reservedPath(queue, jobId));
+    } catch {
+      // no reservation record — nothing to clear
+    }
+  }
+
+  /**
+   * Acknowledge a completed job — drop its reservation record so the visibility
+   * reclaim never re-delivers an already-acked job.
+   */
+  completeJob(queue: string, job: QueueJob): void {
+    this.clearReservation(queue, job.id);
+  }
+
   // Status aliases that live in the failed/ directory (dead-lettered jobs)
   // rather than as pending files in the queue directory.
   private static readonly DEAD_STATES = ["failed", "dead", "dead_letter"];
 
   size(queue: string, status: string = "pending"): number {
     const isDead = LiteBackend.DEAD_STATES.includes(status);
-    const scanDir = isDead ? this.ensureFailedDir(queue) : this.ensureDir(queue);
+    const isReserved = status === "reserved";
+    const scanDir = isDead
+      ? this.ensureFailedDir(queue)
+      : isReserved
+        ? this.ensureReservedDir(queue)
+        : this.ensureDir(queue);
 
     let files: string[];
     try {
@@ -171,9 +316,9 @@ export class LiteBackend {
       return 0;
     }
 
-    if (isDead) {
-      // Every file in failed/ is a dead-letter; count them all regardless of
-      // the exact stored status string.
+    if (isDead || isReserved) {
+      // Every file in failed/ (or reserved/) matches the requested status;
+      // count them all regardless of the exact stored status string.
       return files.length;
     }
 
@@ -215,6 +360,20 @@ export class LiteBackend {
     } catch {
       // ignore
     }
+
+    // Also clear reservation records.
+    const reservedDir = join(dir, "reserved");
+    try {
+      if (existsSync(reservedDir)) {
+        const files = readdirSync(reservedDir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          unlinkSync(join(reservedDir, file));
+          count++;
+        }
+      }
+    } catch {
+      // ignore
+    }
     return count;
   }
 
@@ -416,7 +575,18 @@ export class LiteBackend {
 
       if (job.status !== "pending") continue;
       if (job.id === id) {
-        try { unlinkSync(filePath); } catch { /* already consumed */ }
+        job.topic = queue;
+        job.priority = job.priority ?? 0;
+        // Reserve (so a dead consumer's job is reclaimable) then claim the
+        // pending file — mirrors pop().
+        this.writeReserved(queue, job);
+        try {
+          unlinkSync(filePath);
+        } catch {
+          try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
+          continue; // already consumed
+        }
+        job.status = "reserved";
         return job;
       }
     }
@@ -479,6 +649,8 @@ export class LiteBackend {
    * (attempts >= maxRetries) it is moved to the dead-letter store.
    */
   failJob(queue: string, job: QueueJob, error: string, maxRetries: number, retryBackoff: number = 0): void {
+    // Clear the reservation — the consumer acknowledged (with a failure).
+    this.clearReservation(queue, job.id);
     job.attempts = (job.attempts || 0) + 1;
     job.error = error;
     if (job.attempts < maxRetries) {
@@ -495,6 +667,8 @@ export class LiteBackend {
    * distinct from the automatic failJob() path.
    */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
+    // Clear the reservation — the consumer acknowledged (with an explicit retry).
+    this.clearReservation(queue, job.id);
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
     this.requeue(queue, job, delaySeconds ?? 0, undefined);

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -32,6 +32,15 @@ export interface MongoConfig {
   password?: string;
   database?: string;
   collection?: string;
+  /**
+   * Reservation/visibility timeout (seconds). A dequeued message is held
+   * reserved with availableAt = now + timeout; reclaim returns it once that
+   * passes (consumer died mid-flight, before complete()/fail()). <= 0 disables
+   * the reclaim. Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300.
+   */
+  visibilityTimeout?: number;
+  /** Max attempts before the reclaim dead-letters a job instead of re-delivering. */
+  maxRetries?: number;
 }
 
 export interface QueueBackend {
@@ -58,6 +67,8 @@ export class MongoBackend implements QueueBackend {
   private password: string;
   private database: string;
   private collection: string;
+  private visibilityTimeout: number;
+  private maxRetries: number;
 
   constructor(config?: MongoConfig) {
     this.host = config?.host ?? process.env.TINA4_MONGO_HOST ?? "localhost";
@@ -68,6 +79,16 @@ export class MongoBackend implements QueueBackend {
     this.database = config?.database ?? process.env.TINA4_MONGO_DB ?? "tina4";
     this.collection = config?.collection ?? process.env.TINA4_MONGO_COLLECTION ?? "tina4_queue";
 
+    // Reservation/visibility timeout (seconds): config wins, else env, else 300.
+    if (config?.visibilityTimeout !== undefined) {
+      this.visibilityTimeout = config.visibilityTimeout;
+    } else {
+      const raw = process.env.TINA4_QUEUE_VISIBILITY_TIMEOUT;
+      const parsed = raw === undefined || raw === "" ? 300 : Number(raw);
+      this.visibilityTimeout = Number.isFinite(parsed) ? parsed : 300;
+    }
+    this.maxRetries = config?.maxRetries ?? 3;
+
     // Connection URI precedence: explicit config.uri > TINA4_MONGO_URI
     // > TINA4_QUEUE_URL > a URI built from the host/port/auth field vars.
     const explicitUri = config?.uri ?? process.env.TINA4_MONGO_URI ?? process.env.TINA4_QUEUE_URL;
@@ -84,15 +105,34 @@ export class MongoBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): { uri: string; database: string; collection: string } {
-    return { uri: this.uri, database: this.database, collection: this.collection };
+  getConfig(): { uri: string; database: string; collection: string; visibilityTimeout: number } {
+    return {
+      uri: this.uri,
+      database: this.database,
+      collection: this.collection,
+      visibilityTimeout: this.visibilityTimeout,
+    };
   }
 
   /**
-   * Execute a MongoDB operation synchronously via a child process.
+   * Resolved reservation/visibility timeout (seconds). <= 0 disables the
+   * reclaim. Exposed for testing/introspection.
    */
-  private execSync(operation: string, queue: string, data?: string): string {
-    const script = `
+  getVisibilityTimeout(): number {
+    return this.visibilityTimeout;
+  }
+
+  /**
+   * Build the Node script that performs one MongoDB queue operation in a child
+   * process. Exposed (not private) so tests can assert the visibility-timeout
+   * behaviour without a live MongoDB — the script's pop branch advances
+   * availableAt = now + visibilityTimeout and stamps reservedAt (the core fix),
+   * and the reclaim branch flips an expired { status: reserved } back to
+   * pending with attempts incremented (dead-lettering past maxRetries),
+   * disabled when visibilityTimeout <= 0.
+   */
+  buildScript(operation: string, queue: string, data?: string): string {
+    return `
       async function main() {
         let mongodb;
         try {
@@ -109,6 +149,8 @@ export class MongoBackend implements QueueBackend {
         const operation = ${JSON.stringify(operation)};
         const queueName = ${JSON.stringify(queue)};
         const data = ${JSON.stringify(data ?? "")};
+        const visibilityTimeout = ${JSON.stringify(this.visibilityTimeout)};
+        const maxRetries = ${JSON.stringify(this.maxRetries)};
 
         const client = new MongoClient(uri, {
           connectTimeoutMS: 5000,
@@ -121,7 +163,7 @@ export class MongoBackend implements QueueBackend {
           const col = db.collection(collName);
 
           // Ensure indexes on first use
-          await col.createIndex({ queue: 1, status: 1, delayUntil: 1 });
+          await col.createIndex({ queue: 1, status: 1, availableAt: 1 });
           await col.createIndex({ queue: 1, createdAt: 1 });
 
           if (operation === "push") {
@@ -129,19 +171,59 @@ export class MongoBackend implements QueueBackend {
             await col.insertOne({ ...job, queue: queueName });
             process.stdout.write("__PUSHED__");
           }
+          else if (operation === "reclaim") {
+            // Return reservations whose visibility window expired (at-least-once
+            // delivery). A doc left { status: reserved, availableAt <= now } had
+            // its consumer die before acknowledging — flip it back to pending
+            // with attempts incremented, or dead-letter once attempts hit the
+            // limit. Disabled when visibilityTimeout <= 0.
+            let reclaimed = 0;
+            if (visibilityTimeout > 0) {
+              while (true) {
+                const now = new Date().toISOString();
+                const doc = await col.findOneAndUpdate(
+                  { queue: queueName, status: "reserved", availableAt: { $lte: now } },
+                  { $set: { status: "pending", availableAt: now, reservedAt: null }, $inc: { attempts: 1 } },
+                  { sort: { availableAt: 1 }, returnDocument: "after" },
+                );
+                const updated = doc && doc.value ? doc.value : (doc && doc._id ? doc : null);
+                if (!updated) break;
+                reclaimed++;
+                if ((updated.attempts || 0) >= maxRetries) {
+                  await col.insertOne({
+                    ...updated,
+                    _id: undefined,
+                    status: "dead",
+                    queue: queueName + ".dead_letter",
+                    error: "reservation timed out — consumer did not acknowledge within the visibility timeout",
+                  });
+                  await col.deleteOne({ _id: updated._id, queue: queueName });
+                }
+              }
+            }
+            process.stdout.write(String(reclaimed));
+          }
           else if (operation === "pop") {
             const now = new Date().toISOString();
+            // The claim advances availableAt = now + visibilityTimeout and
+            // stamps reservedAt so reclaim can return the job if the consumer
+            // dies before complete()/fail() — this is the fix for the "reserved
+            // forever" bug (previously availableAt was left unchanged).
+            const future = new Date(Date.now() + visibilityTimeout * 1000).toISOString();
             const result = await col.findOneAndUpdate(
               {
                 queue: queueName,
                 status: "pending",
                 $or: [
+                  { availableAt: null },
+                  { availableAt: { $exists: false } },
+                  { availableAt: { $lte: now } },
                   { delayUntil: null },
                   { delayUntil: { $lte: now } },
                 ],
               },
-              { $set: { status: "reserved" } },
-              { sort: { createdAt: 1 }, returnDocument: "before" },
+              { $set: { status: "reserved", reservedAt: now, availableAt: future } },
+              { sort: { priority: -1, createdAt: 1 }, returnDocument: "before" },
             );
 
             if (result && result.value) {
@@ -181,6 +263,13 @@ export class MongoBackend implements QueueBackend {
 
       main();
     `;
+  }
+
+  /**
+   * Execute a MongoDB operation synchronously via a child process.
+   */
+  private execSync(operation: string, queue: string, data?: string): string {
+    const script = this.buildScript(operation, queue, data);
 
     try {
       const result = execFileSync(process.execPath, ["-e", script], {
@@ -215,6 +304,11 @@ export class MongoBackend implements QueueBackend {
   }
 
   pop(queue: string): QueueJob | null {
+    // Reclaim any reservations whose consumer died before acking, then take the
+    // next available message (at-least-once delivery). Disabled at timeout <= 0.
+    if (this.visibilityTimeout > 0) {
+      this.execSync("reclaim", queue);
+    }
     const result = this.execSync("pop", queue);
     if (!result || result === "__EMPTY__") return null;
 

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -28,6 +28,12 @@ export interface RabbitMQConfig {
   username?: string;
   password?: string;
   vhost?: string;
+  /**
+   * Accepted for API parity with the file/MongoDB backends and IGNORED — the
+   * broker owns redelivery (unacked messages requeue on channel close), so the
+   * framework-level visibility timeout does not apply here.
+   */
+  visibilityTimeout?: number;
 }
 
 /**
@@ -200,7 +206,7 @@ export class RabbitMQBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): Required<RabbitMQConfig> {
+  getConfig(): Required<Omit<RabbitMQConfig, "visibilityTimeout">> {
     return {
       host: this.host,
       port: this.port,

package/packages/core/src/server.ts

@@ -183,8 +183,13 @@ export function _checkLegacyEnvVars(): void {
   }
   lines.push(
     "",
-    "Run `tina4 env --migrate` to rewrite your .env automatically,",
-    "or rename manually. See https://tina4.com/release/3.12.0",
+    "Note: these may come from a .env file loaded by dotenv, not just",
+    "the runtime environment — check your image / build context (a .env",
+    "baked into a Docker image is loaded at startup) as well as k8s/CI env.",
+    "",
+    "FIX: run `tina4 env --migrate` to rewrite your .env automatically",
+    "(it renames every legacy name to its TINA4_ form in place).",
+    "Or rename manually. See https://tina4.com/release/3.12.0",
     "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
     bar,
     "",

package/packages/core/src/sessionHandlers/mongoHandler.ts

@@ -66,8 +66,10 @@ export class MongoSessionHandler implements SessionHandler {
       ?? (process.env.TINA4_SESSION_MONGO_PORT
         ? parseInt(process.env.TINA4_SESSION_MONGO_PORT, 10)
         : 27017);
+    // Canonical TINA4_SESSION_MONGO_URI; TINA4_SESSION_MONGO_URL is a legacy alias.
     this.uri = config?.uri
       ?? process.env.TINA4_SESSION_MONGO_URI
+      ?? process.env.TINA4_SESSION_MONGO_URL
       ?? "";
     this.username = config?.username
       ?? process.env.TINA4_SESSION_MONGO_USERNAME

package/packages/core/src/types.ts

@@ -134,6 +134,10 @@ export interface RouteMeta {
   description?: string;
   tags?: string[];
   responses?: Record<string, { description: string }>;
+  /** Request-body example surfaced in the OpenAPI requestBody. */
+  example?: unknown;
+  /** Marks the operation deprecated in the spec. */
+  deprecated?: boolean;
 }
 
 export interface Tina4Config {