tina4-nodejs 3.13.92 → 3.13.95

package/packages/core/src/queue.ts

@@ -1,17 +1,23 @@
 /**
  * Tina4 Queue — Unified job queue with pluggable backends, zero dependencies.
  *
- * Switching from file to RabbitMQ or Kafka is a .env change — no code change needed.
+ * Switching from file to MongoDB is a .env change — no code change needed.
  *
  * Supported backends:
  *   - 'file'     — JSON files on disk (default)
- *   - 'rabbitmq' — RabbitMQ via raw TCP (AMQP 0-9-1)
- *   - 'kafka'    — Kafka via raw TCP
  *   - 'mongodb'  — MongoDB via `mongodb` npm package (also 'mongo')
  *
+ * REFUSED backends (ADR-0022):
+ *   - 'rabbitmq' and 'kafka' THROW on construction. Node drives both through a
+ *     child process per operation, so no connection survives between pop() and
+ *     complete() and acknowledgement is impossible: RabbitMQ was at-most-once
+ *     (a dead consumer lost the job) and Kafka could never drain a topic. They
+ *     lost work silently, so they now refuse. tina4-python, tina4-php and
+ *     tina4-ruby still offer both. See unsupportedBrokerMessage() below.
+ *
  * Environment variables:
- *   TINA4_QUEUE_BACKEND — 'file', 'rabbitmq', 'kafka', or 'mongodb'
- *   TINA4_QUEUE_URL     — connection URL for rabbitmq/kafka
+ *   TINA4_QUEUE_BACKEND — 'file' or 'mongodb'
+ *   TINA4_QUEUE_URL     — connection URL for mongodb
  *   TINA4_QUEUE_PATH    — file backend storage path (default: data/queue)
  *
  * Usage:
@@ -22,14 +28,12 @@
  *   queue.push({ to: "alice@test.com", subject: "Hello" });
  *
  *   // Explicit backend
- *   const queue = new Queue({ topic: "tasks", backend: "rabbitmq" });
+ *   const queue = new Queue({ topic: "tasks", backend: "mongodb" });
  *
  *   // Legacy usage (still works — uses file backend)
  *   const queue = new Queue();
  *   queue.push("emails", { to: "alice@test.com" });
  */
-import { RabbitMQBackend } from "./queueBackends/rabbitmqBackend.js";
-import { KafkaBackend } from "./queueBackends/kafkaBackend.js";
 import { MongoBackend } from "./queueBackends/mongoBackend.js";
 import { LiteBackend } from "./queueBackends/liteBackend.js";
 import { type QueueJob, type JobData, createJob } from "./job.js";
@@ -58,13 +62,27 @@ export interface QueueConfig {
    * re-enqueuing, or dead-lettering past maxRetries (at-least-once delivery).
    * Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300 (5 min). <= 0
    * disables the reclaim (a reservation then lasts until the consumer acks —
-   * the old at-most-once behaviour). File + MongoDB backends only;
-   * RabbitMQ/Kafka delegate visibility to the broker. Parity with Python's
+   * the old at-most-once behaviour). File + MongoDB backends, which are the
+   * only backends Node offers (ADR-0022). Parity with Python's
    * visibility_timeout.
    */
   visibilityTimeout?: number;
 }
 
+/**
+ * Where the file-backed queue stores its jobs — `TINA4_QUEUE_PATH`, else
+ * `data/queue` (relative to the working directory).
+ *
+ * Exported because it is the ONE answer to "where do the queue files live",
+ * and anything that reads the store directly (the dev-admin queue panel) must
+ * ask here rather than re-deriving it. The dev admin hardcoded
+ * `cwd/data/queue/<topic>` and so listed a DIFFERENT directory from the one
+ * `Queue.size()` counted the moment `TINA4_QUEUE_PATH` was set.
+ */
+export function queueBasePath(): string {
+  return process.env.TINA4_QUEUE_PATH ?? "data/queue";
+}
+
 /**
  * Reservation/visibility timeout in seconds, from env (default 300 = 5 min).
  * Mirrors Python's _default_visibility_timeout().
@@ -99,15 +117,31 @@ export interface ConsumeOptions {
 }
 
 export interface QueueBackendInterface {
-  push(queue: string, payload: unknown, delay?: number): string;
+  push(queue: string, payload: unknown, delay?: number, priority?: number): string;
   pop(queue: string): QueueJob | null;
   size(queue: string): number;
   clear(queue: string): void;
+  /**
+   * Release whatever connection the backend holds, and be safe to call twice.
+   *
+   * REQUIRED, not optional, and deliberately so: it mirrors PHP's
+   * Tina4\Queue\QueueBackend, where close() has always been part of the
+   * interface. Optional would reintroduce exactly the bug this closes — a
+   * caller feature-detecting `backend.close?.()` silently skips the backend
+   * that forgot to implement it, which is how tina4-ruby's lite backend went
+   * un-closed by every `respond_to?(:close)` guard in its tree.
+   */
+  close(): void;
   // Optional full lifecycle. Reservation-based backends (MongoDB) implement
   // these so complete()/fail() ack the ACTIVE store — without complete(), a
-  // reserved Mongo job is re-delivered after the visibility window. Backends
-  // that auto-ack on pop (RabbitMQ no-ack) or delegate to the broker (Kafka
-  // offsets) omit them, and the Queue keeps its prior behaviour for them.
+  // reserved Mongo job is re-delivered after the visibility window.
+  //
+  // Optional is a wart, not a design: a backend that omitted them silently fell
+  // through to the LOCAL FILE store, so a fail() on a broker-backed queue wrote
+  // JSON to disk while the broker still held the message. The only backends
+  // that did that were RabbitMQ and Kafka, and ADR-0022 now refuses both, so
+  // nothing in tree relies on the fallback. Make these required when the
+  // persistent-connection rewrite lands.
   complete?(queue: string, id: string): void;
   fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
   retry?(queue: string, id: string, delaySeconds?: number): void;
@@ -117,6 +151,50 @@ export interface QueueBackendInterface {
   purge?(queue: string, status?: string): number;
 }
 
+/**
+ * Why `backend: "rabbitmq"` and `backend: "kafka"` are refused in Node (ADR-0022).
+ *
+ * Both backends drive the wire protocol through `execFileSync`, spawning a fresh
+ * child process for EVERY operation. The child connects, performs one operation,
+ * destroys its socket and exits, so no connection, channel, consumer or session
+ * survives between push, pop and complete.
+ *
+ * That makes acknowledgement impossible, not merely unimplemented. An AMQP
+ * delivery tag identifies a delivery on a CHANNEL that is already closed by the
+ * time pop() returns, and a Kafka consumer-group offset belongs to a SESSION
+ * that never existed. So RabbitMQ ran Basic.Get with no-ack=true (at-most-once:
+ * a consumer that dies after pop() loses the job outright) and Kafka fetched
+ * from offset 0 every time (the topic could never drain).
+ *
+ * Refusing loudly follows the same call the session backend already made for
+ * `redis-npm`: a silent demotion looks like it is working while the operator
+ * believes otherwise, which is worse than an outage you can see. Anyone
+ * "successfully" running these today is already losing jobs and does not know it.
+ *
+ * This is a HOLDING POSITION, not the design. The fix is a persistent
+ * connection held on the backend instance, the way Python, PHP and Ruby already
+ * do it. There is deliberately no opt-in escape hatch: nobody has asked for
+ * fire-and-forget, and a knob for a hypothetical user is not worth its weight.
+ */
+function unsupportedBrokerMessage(backendName: string): string {
+  const broker = backendName === "kafka" ? "Kafka" : "RabbitMQ";
+  const lost = backendName === "kafka"
+    ? "every pop() re-read offset 0, so the topic could never drain"
+    : "pop() destroyed the message with no acknowledgement, so a consumer that died lost the job";
+  return (
+    `Queue backend "${backendName}" is not available in tina4-nodejs.\n\n` +
+    `Reason: the ${broker} backend runs each operation in a separate child ` +
+    `process, so no connection survives between pop() and complete(). ` +
+    `Acknowledgement is therefore impossible, and ${lost}. It was losing work ` +
+    `silently, so it now refuses instead.\n\n` +
+    `Use backend "mongodb" (at-least-once, with a real reservation and ` +
+    `visibility timeout) or the default "file" backend. tina4-python, ` +
+    `tina4-php and tina4-ruby still offer ${broker}.\n\n` +
+    `Tracking: ADR-0022 in tina4-documentation/plan/v3/DECISIONS.md, ` +
+    `findings in plan/v3/features/048-queue-backends.md.`
+  );
+}
+
 // ── Queue ────────────────────────────────────────────────────
 
 export class Queue {
@@ -133,26 +211,28 @@ export class Queue {
    * Unified Queue constructor.
    *
    * Accepts either:
-   *   - new Queue({ topic: "tasks", backend: "rabbitmq" })
-   *   - new Queue("rabbitmq", { path: "data/queue" })  // legacy
+   *   - new Queue({ topic: "tasks", backend: "mongodb" })
+   *   - new Queue("mongodb", { path: "data/queue" })  // legacy
    *   - new Queue()  // file backend, default topic
+   *
+   * Throws on backend "rabbitmq" or "kafka" (ADR-0022).
    */
   constructor(backendOrConfig?: string | QueueConfig, config?: QueueConfig) {
     let resolvedConfig: QueueConfig = {};
 
     if (typeof backendOrConfig === "string") {
-      // Legacy: new Queue("rabbitmq", { ... })
+      // Legacy: new Queue("mongodb", { ... })
       resolvedConfig = { ...(config ?? {}), backend: backendOrConfig };
     } else if (typeof backendOrConfig === "object" && backendOrConfig !== null) {
       resolvedConfig = backendOrConfig;
     }
 
-    this.backendName = resolvedConfig.backend
-      ?? process.env.TINA4_QUEUE_BACKEND
-      ?? "file";
-    this.basePath = resolvedConfig.path
-      ?? process.env.TINA4_QUEUE_PATH
-      ?? "data/queue";
+    // Normalised (trimmed + lowercased) so " MongoDB " resolves, matching the
+    // Python master, Ruby and PHP. An unrecognised value THROWS below.
+    this.backendName = String(
+      resolvedConfig.backend ?? process.env.TINA4_QUEUE_BACKEND ?? "file",
+    ).trim().toLowerCase();
+    this.basePath = resolvedConfig.path ?? queueBasePath();
     this.topic = resolvedConfig.topic ?? "default";
     this._maxRetries = resolvedConfig.maxRetries ?? 3;
     this._retryBackoff = resolvedConfig.retryBackoff ?? 0;
@@ -160,15 +240,24 @@ export class Queue {
     this.liteBackend = new LiteBackend(this.basePath, this._visibilityTimeout);
 
     // Initialize external backends
-    if (this.backendName === "rabbitmq") {
-      // Broker manages visibility/redelivery (unacked messages requeue on
-      // channel close) — the framework timeout is accepted but not used.
-      this.externalBackend = new RabbitMQBackend({ visibilityTimeout: this._visibilityTimeout });
-    } else if (this.backendName === "kafka") {
-      // Consumer-group offsets manage redelivery — framework timeout N/A.
-      this.externalBackend = new KafkaBackend({ visibilityTimeout: this._visibilityTimeout });
+    if (this.backendName === "rabbitmq" || this.backendName === "kafka") {
+      throw new Error(unsupportedBrokerMessage(this.backendName));
     } else if (this.backendName === "mongodb" || this.backendName === "mongo") {
       this.externalBackend = new MongoBackend({ visibilityTimeout: this._visibilityTimeout });
+    } else if (!["file", "default", "lite"].includes(this.backendName)) {
+      // An UNRECOGNISED backend name THROWS rather than falling through to the
+      // local file store.
+      //
+      // MEASURED 2026-08-03: a typo in TINA4_QUEUE_BACKEND produced a running
+      // app writing every job to local disk while the operator believed they
+      // were in MongoDB - jobs nothing consumes, on a container filesystem that
+      // vanishes on the next deploy, with no error at any point. Python and Ruby
+      // already raise here; this is the same rule the session backend adopted
+      // for the same reason.
+      throw new Error(
+        `Unknown queue backend: '${this.backendName}'. ` +
+          `Use 'file', 'rabbitmq', 'kafka', or 'mongodb'.`,
+      );
     }
   }
 
@@ -202,7 +291,10 @@ export class Queue {
    */
   push(payload: unknown, delay?: number, priority: number = 0): string {
     if (this.externalBackend) {
-      return this.externalBackend.push(this.topic, payload, delay);
+      // priority goes to the external backend too. It used to be passed only to
+      // liteBackend, so switching to mongodb silently turned a prioritised
+      // queue into a FIFO one.
+      return this.externalBackend.push(this.topic, payload, delay, priority);
     }
     return this.liteBackend.push(this.topic, payload, delay, priority);
   }
@@ -214,7 +306,15 @@ export class Queue {
     const q = this.topic;
 
     if (this.externalBackend) {
-      return this.externalBackend.pop(q);
+      const raw = this.externalBackend.pop(q);
+      // Wrap it. An external backend returns PLAIN DATA with no lifecycle
+      // methods, so `queue.pop().fail("boom")` threw
+      // "TypeError: j.fail is not a function" on mongodb/rabbitmq/kafka while
+      // working on file — identical application code, different outcome, which
+      // is exactly what ADR-0024 forbids. createJob attaches
+      // complete()/fail()/reject()/retry(), and they route back through
+      // _completeJob/_failJob, which already dispatch to the external backend.
+      return raw ? createJob(raw as any, this) : null;
     }
     return this.liteBackend.pop(q, this);
   }
@@ -223,6 +323,19 @@ export class Queue {
    * Pop up to count jobs at once. Returns a partial batch if fewer available.
    */
   popBatch(count: number): QueueJob[] {
+    // Route to the CONFIGURED backend. This used to read the LOCAL FILE STORE
+    // unconditionally, so a mongodb-backed queue always came back empty.
+    // Repeated pop() is the correct batch on an external backend: each claim is
+    // atomic, and a short batch simply means the queue drained.
+    if (this.externalBackend) {
+      const jobs: QueueJob[] = [];
+      for (let i = 0; i < count; i++) {
+        const job = this.pop();
+        if (!job) break;
+        jobs.push(job);
+      }
+      return jobs;
+    }
     return this.liteBackend.popBatch(this.topic, this, count);
   }
 
@@ -311,6 +424,34 @@ export class Queue {
     return this.liteBackend.clear(q);
   }
 
+  /**
+   * Release the backend's connection and free its resources.
+   *
+   * MEASURED 2026-08-04: close() was absent on the top-level Queue in ALL FOUR
+   * frameworks, and in Node it was absent on every backend class too — so an
+   * application had no way at all to hand a queue's client back. Same class of
+   * leak as ADR-0025 corollary 4 (client-lifecycle-is-bounded).
+   *
+   * Safe on EVERY backend: the file backend holds no connection and closes as a
+   * documented no-op, so a TINA4_QUEUE_BACKEND change never turns a working
+   * shutdown path into an error. Idempotent — each backend drops its handles on
+   * the first call, so a second call finds nothing to close and returns.
+   *
+   * HONEST CAVEAT specific to Node: neither backend it can reach holds a
+   * connection between calls today. The Mongo backend runs each operation in
+   * its own child process (ADR-0022), which closes its own client before it
+   * exits, and rabbitmq/kafka are refused outright at construction. So this
+   * releases nothing YET — it is here for the contract, and because the day the
+   * persistent-connection rewrite lands the client is released here with no
+   * change at any call site. Python, PHP and Ruby release a REAL client through
+   * the identically-named method.
+   *
+   * Treat the queue as spent afterwards and build a new one to keep working.
+   */
+  close(): void {
+    (this.externalBackend ?? this.liteBackend).close();
+  }
+
   /**
    * Get jobs that failed at least once but are still being retried
    * (0 < attempts < maxRetries). These live in the pending queue under the
@@ -497,6 +638,21 @@ export class Queue {
    * Pop a specific job by ID from this queue's topic.
    */
   popById(id: string): QueueJob | null {
+    // Same defect as popBatch: this read the local file store on every backend.
+    if (this.externalBackend) {
+      const claim = (this.externalBackend as any).popById;
+      if (typeof claim !== "function") {
+        throw new Error(
+          `The ${this.backendName} queue backend cannot perform popById(): it ` +
+          `cannot address a single message by id. Use the file or mongodb backend.`,
+        );
+      }
+      // Same shape as pop() — and, like pop(), PLAIN DATA with no lifecycle
+      // methods, so it must be wrapped or job.complete()/job.fail() is a
+      // TypeError on every external backend.
+      const raw = claim.call(this.externalBackend, this.topic, id);
+      return raw ? createJob(raw as any, this) : null;
+    }
     return this.liteBackend.popById(this.topic, id);
   }
 

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

@@ -92,7 +92,7 @@ export function kafkaSecurityConfig(
 }
 
 export interface QueueBackend {
-  push(queue: string, payload: unknown, delay?: number): string;
+  push(queue: string, payload: unknown, delay?: number, priority?: number): string;
   pop(queue: string): QueueJob | null;
   size(queue: string): number;
   clear(queue: string): void;
@@ -497,12 +497,15 @@ export class KafkaBackend implements QueueBackend {
             if (errCode === 0) {
               finish("__PUBLISHED__", 0);
             } else {
+              // Report the CODE, not just "it failed" — the caller decides
+              // whether it is retriable (3/5, the async topic-creation race)
+              // or fatal (e.g. 29 TOPIC_AUTHORIZATION_FAILED).
               process.stderr.write("Produce error code " + errCode);
-              finish("__ERROR__" + errCode, 0);
+              finish("__PRODUCEERROR__" + errCode, 0);
             }
           } catch (e) {
             process.stderr.write("produce parse: " + e.message);
-            finish("__ERROR__", 0);
+            finish("__PARSEERROR__produce: " + e.message, 0);
           }
           return;
         } else if (operation === "get") {
@@ -516,6 +519,7 @@ export class KafkaBackend implements QueueBackend {
             pos += 4;                                   // throttleTimeMs (v1+)
             const topicCount = buffer.readInt32BE(pos); pos += 4;
             let out = "__EMPTY__";
+            let fatalCode = 0;
             for (let t = 0; t < topicCount; t++) {
               const tl = buffer.readInt16BE(pos); pos += 2 + tl;
               const pc = buffer.readInt32BE(pos); pos += 4;
@@ -527,6 +531,14 @@ export class KafkaBackend implements QueueBackend {
                 const abortedCount = buffer.readInt32BE(pos); pos += 4;
                 if (abortedCount > 0) pos += abortedCount * 16; // (-1 => none, skip)
                 const recSetSize = buffer.readInt32BE(pos); pos += 4;
+                // 3 = UNKNOWN_TOPIC_OR_PARTITION, 5 = LEADER_NOT_AVAILABLE:
+                // "nothing to read here yet", which a consumer that starts
+                // before its producer hits on every cold start. Any OTHER code
+                // (29 TOPIC_AUTHORIZATION_FAILED, 13 STALE_CONTROLLER_EPOCH, …)
+                // is a real failure and must NOT be reported as an empty queue.
+                if (errCode !== 0 && errCode !== 3 && errCode !== 5) {
+                  fatalCode = errCode;
+                }
                 if (errCode === 0 && recSetSize > 0) {
                   const val = firstRecordValue(buffer, pos, pos + recSetSize);
                   if (val !== null) out = val;
@@ -534,21 +546,33 @@ export class KafkaBackend implements QueueBackend {
                 pos += recSetSize > 0 ? recSetSize : 0;
               }
             }
+            if (fatalCode !== 0) {
+              process.stderr.write("Fetch error code " + fatalCode);
+              finish("__FETCHERROR__" + fatalCode, 0);
+              return;
+            }
             finish(out, 0);
           } catch (e) {
+            // A parse failure is NOT an empty queue either — say so.
             process.stderr.write("fetch parse: " + e.message);
-            finish("__EMPTY__", 0);
+            finish("__PARSEERROR__fetch: " + e.message, 0);
           }
           return;
         }
       });
 
+      // Report the reason on STDOUT and exit 0. Writing it to stderr and
+      // exiting non-zero LOST it: stderr to a pipe is an async write and
+      // process.exit() truncates it, so the parent saw an empty stderr and fell
+      // back to execFileSync's message -- which embeds this entire script.
+      // stdout is flushed by finish()'s write callback, so it survives.
       sock.on("error", (err) => {
-        process.stderr.write(err.message);
-        finish("", 1);
+        finish("__TRANSPORTERROR__" + err.message, 0);
       });
 
-      var timer = setTimeout(() => { finish("", 1); }, 10000);
+      var timer = setTimeout(() => {
+        finish("__TRANSPORTERROR__timed out after 10s talking to " + host + ":" + port, 0);
+      }, 10000);
     `;
 
     try {
@@ -558,8 +582,59 @@ export class KafkaBackend implements QueueBackend {
         stdio: ["pipe", "pipe", "pipe"],
       });
       return result;
-    } catch {
-      return "";
+    } catch (err) {
+      // Reached only when the child itself could not run (spawn failure, killed,
+      // the outer 15s timeout). The socket-level reasons come back through
+      // stdout as __TRANSPORTERROR__ instead. Swallowing this to "" made every
+      // failure indistinguishable from an empty queue.
+      //
+      // execFileSync's own message embeds the ENTIRE generated script, so it is
+      // truncated here -- a 20KB error that buries the cause is barely better
+      // than no error at all.
+      const e = err as { stderr?: Buffer | string; message?: string };
+      const reason = String(e.stderr ?? "").trim() || e.message || "unknown error";
+      const firstLine = reason.split("\n", 1)[0]!.slice(0, 200);
+      return "__TRANSPORTERROR__" + firstLine;
+    }
+  }
+
+  /**
+   * Sleep synchronously between produce retries.
+   *
+   * `push()` is synchronous (the whole backend drives its socket through a child
+   * process), so there is no event loop to await on. `Atomics.wait` on a
+   * SharedArrayBuffer is the stdlib way to block a thread for a fixed time --
+   * no dependency, no busy-wait burning CPU.
+   */
+  private static sleepSync(ms: number): void {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+  }
+
+  /**
+   * Turn a sentinel from the protocol child into a thrown error, or return.
+   *
+   * The wording matches the Python and PHP backends exactly -- the parity rule
+   * covers user-visible error messages, not just behaviour.
+   */
+  private static assertNoError(result: string, operation: string, topic: string): void {
+    const fatal = /^__(PRODUCEERROR|FETCHERROR)__(\d+)/.exec(result);
+    if (fatal) {
+      throw new Error(
+        `Kafka rejected the ${operation} for topic ${topic}: error code ${fatal[2]}`,
+      );
+    }
+    if (result.startsWith("__TRANSPORTERROR__")) {
+      throw new Error(
+        `Kafka ${operation} for topic ${topic} failed: ` +
+          result.slice("__TRANSPORTERROR__".length),
+      );
+    }
+    if (result.startsWith("__PARSEERROR__")) {
+      throw new Error(
+        `Kafka ${operation} for topic ${topic} returned an unreadable response: ` +
+          result.slice("__PARSEERROR__".length),
+      );
     }
   }
 
@@ -576,15 +651,36 @@ export class KafkaBackend implements QueueBackend {
       delayUntil: null,
     };
 
-    const result = this.execSync("publish", queue, JSON.stringify(job));
-    if (!result.includes("__PUBLISHED__")) {
-      throw new Error("Kafka publish failed");
+    // Topic auto-creation is ASYNCHRONOUS, so a brand-new topic answers
+    // UNKNOWN_TOPIC_OR_PARTITION (3) or LEADER_NOT_AVAILABLE (5) on the first
+    // attempt while the controller is still electing a leader. Retry those
+    // (same 10 attempts / 200ms as the Python and PHP backends) instead of
+    // failing a cold-start push; every other code throws immediately.
+    const body = JSON.stringify(job);
+    let result = "";
+    for (let attempt = 1; attempt <= 10; attempt++) {
+      result = this.execSync("publish", queue, body);
+      if (result.includes("__PUBLISHED__")) {
+        return id;
+      }
+      const retriable = /^__PRODUCEERROR__(3|5)\b/.test(result);
+      if (!retriable || attempt === 10) {
+        break;
+      }
+      KafkaBackend.sleepSync(200);
     }
-    return id;
+
+    KafkaBackend.assertNoError(result, "produce", queue);
+    throw new Error(`Kafka publish failed for topic ${queue}: ${result || "no response"}`);
   }
 
   pop(queue: string): QueueJob | null {
     const result = this.execSync("get", queue);
+
+    // A real failure must NOT read as an empty queue: a mis-permissioned
+    // consumer would otherwise poll an "idle" topic forever.
+    KafkaBackend.assertNoError(result, "fetch", queue);
+
     if (!result || result === "__EMPTY__" || result === "__UNSUPPORTED__") return null;
 
     try {

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

@@ -74,6 +74,19 @@ export class LiteBackend {
     return `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
   }
 
+  /**
+   * No-op: the file backend holds no connection to release.
+   *
+   * It exists so `Queue.close()` can call ONE method on every backend instead
+   * of testing for it, and so switching TINA4_QUEUE_BACKEND to "file" never
+   * turns a working close() into "backend.close is not a function". Idempotent
+   * by construction — there is nothing to drop.
+   */
+  close(): void {
+    // Nothing held: every operation opens, reads/writes and closes its own file
+    // descriptor synchronously, so no handle survives a call.
+  }
+
   push(queue: string, payload: unknown, delay?: number, priority?: number): string {
     const dir = this.ensureDir(queue);
     const id = randomUUID();