tina4-nodejs 3.13.94 → 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;

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();

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

@@ -44,10 +44,12 @@ export interface MongoConfig {
 }
 
 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;
+  /** Release whatever connection the backend holds. Must be idempotent. */
+  close(): void;
 }
 
 // ── MongoDB Backend ──────────────────────────────────────────
@@ -214,12 +216,31 @@ export class MongoBackend implements QueueBackend {
               {
                 queue: queueName,
                 status: "pending",
-                $or: [
-                  { availableAt: null },
-                  { availableAt: { $exists: false } },
-                  { availableAt: { $lte: now } },
-                  { delayUntil: null },
-                  { delayUntil: { $lte: now } },
+                // TWO INDEPENDENT GATES, both of which must pass: the
+                // reservation gate (availableAt) and the delay gate
+                // (delayUntil). These used to share ONE $or, which made them
+                // alternatives rather than requirements — a freshly pushed
+                // delayed job has no availableAt, matched
+                // { availableAt: { $exists: false } }, and was handed straight
+                // to a consumer. That is why push(payload, delay) fired
+                // immediately on Mongo and on time on the file backend.
+                // The $exists arms keep documents written before either field
+                // existed claimable, instead of stranding them forever.
+                $and: [
+                  {
+                    $or: [
+                      { availableAt: null },
+                      { availableAt: { $exists: false } },
+                      { availableAt: { $lte: now } },
+                    ],
+                  },
+                  {
+                    $or: [
+                      { delayUntil: null },
+                      { delayUntil: { $exists: false } },
+                      { delayUntil: { $lte: now } },
+                    ],
+                  },
                 ],
               },
               { $set: { status: "reserved", reservedAt: now, availableAt: future } },
@@ -250,6 +271,28 @@ export class MongoBackend implements QueueBackend {
               process.stdout.write("__EMPTY__");
             }
           }
+          else if (operation === "popById") {
+            // Claim ONE specific job by id, the same way pop() claims the head.
+            // Queue.popById used to read the LOCAL FILE STORE regardless of the
+            // configured backend, so it never saw a mongodb job at all.
+            const now = new Date().toISOString();
+            const future = new Date(Date.now() + visibilityTimeout * 1000).toISOString();
+            const wanted = JSON.parse(data);
+            const result = await col.findOneAndUpdate(
+              { queue: queueName, status: "pending", id: wanted.id },
+              { $set: { status: "reserved", reservedAt: now, availableAt: future } },
+              { returnDocument: "before" },
+            );
+            const doc = result && result.value ? result.value : (result && result._id ? { ...result } : null);
+            if (doc) {
+              doc.topic = queueName;
+              delete doc._id;
+              delete doc.queue;
+              process.stdout.write(JSON.stringify(doc));
+            } else {
+              process.stdout.write("__EMPTY__");
+            }
+          }
           else if (operation === "size") {
             const count = await col.countDocuments({
               queue: queueName,
@@ -318,8 +361,20 @@ export class MongoBackend implements QueueBackend {
             process.stdout.write(JSON.stringify(out));
           }
           else if (operation === "failed") {
+            // Found by the ATTEMPTS COUNTER, not by a "failed" status. The
+            // fail() branch above re-queues a still-retryable job as "pending"
+            // (that is what makes the next pop redeliver it) and dead-letters
+            // an exhausted one as "dead" - nothing ever writes "failed", so
+            // this query matched nothing and returned [] forever. An empty
+            // list is indistinguishable from "nothing has failed"
+            // (ADR-0022 decision 7). attempts > 0 is the real marker of a job
+            // that has already died at least once.
             const docs = await col
-              .find({ queue: queueName, status: "failed", attempts: { $lt: maxRetries } })
+              .find({
+                queue: queueName,
+                status: "pending",
+                attempts: { $gt: 0, $lt: maxRetries },
+              })
               .toArray();
             const out = docs.map((d) => { delete d._id; delete d.queue; return d; });
             process.stdout.write(JSON.stringify(out));
@@ -380,7 +435,17 @@ export class MongoBackend implements QueueBackend {
     }
   }
 
-  push(queue: string, payload: unknown, delay?: number): string {
+  popById(queue: string, id: string): QueueJob | null {
+    const out = this.execSync("popById", queue, JSON.stringify({ id }));
+    if (!out || out === "__EMPTY__") return null;
+    try {
+      return JSON.parse(out) as QueueJob;
+    } catch {
+      return null;
+    }
+  }
+
+  push(queue: string, payload: unknown, delay?: number, priority?: number): string {
     const id = randomUUID();
     const now = new Date().toISOString();
 
@@ -391,6 +456,11 @@ export class MongoBackend implements QueueBackend {
       createdAt: now,
       attempts: 0,
       delayUntil: delay ? new Date(Date.now() + delay * 1000).toISOString() : null,
+      // The pop sort has always been { priority: -1, createdAt: 1 }, but this
+      // field was never written, so every job scored undefined and the queue
+      // ran pure FIFO. Priority did not even reach here: the backend interface
+      // had no such parameter and Queue.push dropped it for external backends.
+      priority: priority ?? 0,
     };
 
     const result = this.execSync("push", queue, JSON.stringify(job));
@@ -471,4 +541,26 @@ export class MongoBackend implements QueueBackend {
     const out = this.execSync("purge", queue, JSON.stringify({ status: status ?? "" }));
     return parseInt(out, 10) || 0;
   }
+
+  /**
+   * Release the MongoDB connection. Idempotent — a second call is a no-op.
+   *
+   * HONEST CAVEAT, and it is the whole reason ADR-0022 exists: THIS backend
+   * holds no connection between calls to release. Every operation runs in its
+   * own child process (see execSync/buildScript), and that child's `finally`
+   * already does `await client.close()` before it exits — so the pool it opened
+   * is gone by the time the method returns. Unlike tina4-python, tina4-php and
+   * tina4-ruby, whose Mongo/broker backends hold a long-lived client that this
+   * method genuinely hands back, Node has nothing to give back.
+   *
+   * It is implemented anyway, and required by the QueueBackend interface,
+   * because the CONTRACT is what matters: `Queue.close()` must be callable on
+   * every backend in every framework, and the day the persistent-connection
+   * rewrite lands (ADR-0022's tracked fix) the client goes here with no change
+   * at any call site. A method that is a no-op today and correct forever beats
+   * a missing method the caller has to feature-detect.
+   */
+  close(): void {
+    // Nothing held: the per-operation child process owns and closes its client.
+  }
 }

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

@@ -40,8 +40,8 @@ export interface RabbitMQConfig {
  * Parse an AMQP URL (amqp://[user:pass@]host[:port][/vhost]) into a partial
  * RabbitMQConfig. Mirrors the Python/PHP/Ruby `parse_amqp_url` semantics:
  * strips a leading amqp:// or amqps:// scheme, splits optional credentials,
- * and prepends a leading "/" to the vhost when missing. Only fields present
- * in the URL are populated.
+ * and reads the path segment as the URL-decoded vhost name. Only fields
+ * present in the URL are populated.
  */
 export function parseAmqpUrl(url: string): RabbitMQConfig {
   const config: RabbitMQConfig = {};
@@ -65,8 +65,26 @@ export function parseAmqpUrl(url: string): RabbitMQConfig {
   if (slashIndex !== -1) {
     hostport = rest.slice(0, slashIndex);
     const vhost = rest.slice(slashIndex + 1);
+    // THE VHOST IS THE PATH SEGMENT, URL-DECODED, WITH NO LEADING SLASH
+    // (RabbitMQ URI spec). This used to prepend "/", so
+    // amqp://guest:guest@rabbit:5672/orders asked for a vhost literally named
+    // "/orders". No broker has that one - it is named "orders" - so every
+    // publish failed against a named vhost, which is the ordinary multi-tenant
+    // setup and the form every RabbitMQ tutorial shows. MEASURED against a real
+    // broker: 4 of 5 URL shapes resolved to the wrong name, and the only one
+    // that worked carried no vhost at all, which is why four green suites never
+    // noticed.
+    //
+    // Decoding matters for the same reason: the DEFAULT vhost is named "/",
+    // which cannot appear literally in a path, so the spec spells it "%2f".
+    //
+    // DELIBERATE DEVIATION, one shape: the spec reads a bare trailing slash as
+    // the EMPTY vhost name. Tina4 treats it as "not specified" and keeps the
+    // caller's default - nobody writes a trailing slash intending a vhost named
+    // "", and reading it literally would break a working "amqp://host:5672/"
+    // for no benefit.
     if (vhost) {
-      config.vhost = vhost.startsWith("/") ? vhost : "/" + vhost;
+      config.vhost = decodeURIComponent(vhost);
     }
   }
 
@@ -82,7 +100,7 @@ export function parseAmqpUrl(url: string): RabbitMQConfig {
 }
 
 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;

package/packages/core/src/rateLimiter.ts

@@ -1,4 +1,5 @@
 import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
+import { resolveClientIp } from "./trustedProxy.js";
 
 /** Per-IP sliding window entry */
 interface RateLimitEntry {
@@ -59,11 +60,15 @@ export function rateLimiter(config?: RateLimiterConfig): Middleware {
     const now = Date.now();
     const cutoff = now - windowMs;
 
-    // Extract client IP — check x-forwarded-for, then socket
-    const forwarded = req.headers["x-forwarded-for"];
-    const ip = (typeof forwarded === "string" ? forwarded.split(",")[0].trim() : undefined)
-      ?? req.socket?.remoteAddress
-      ?? "unknown";
+    // Client key. X-Forwarded-For is honoured ONLY when the socket peer is a
+    // declared trusted proxy (TINA4_TRUSTED_PROXIES) - otherwise any client
+    // could pick its own bucket, and pick someone else's. ADR-0019.
+    //
+    // This derived the key itself rather than reading req.ip, and its
+    // `typeof forwarded === "string"` test meant a REPEATED header (which
+    // arrives as an array) silently fell through to the socket address -
+    // inconsistent with req.ip, which did read the array.
+    const ip = resolveClientIp(req.headers, req.socket?.remoteAddress ?? "") || "unknown";
 
     // Get or create entry
     let entry = store.get(ip);

package/packages/core/src/request.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, IncomingHttpHeaders } from "node:http";
 import type { Tina4Request, UploadedFile } from "./types.js";
+import { resolveClientIp } from "./trustedProxy.js";
 
 /**
  * Wrap Node's `IncomingHttpHeaders` in a Proxy so mixed-case lookups
@@ -102,15 +103,11 @@ export function createRequest(req: IncomingMessage): Tina4Request {
   }
   tReq.cookies = cookies;
 
-  // Determine client IP with X-Forwarded-For support
-  const forwarded = req.headers["x-forwarded-for"];
-  if (typeof forwarded === "string") {
-    tReq.ip = forwarded.split(",")[0].trim();
-  } else if (Array.isArray(forwarded) && forwarded.length > 0) {
-    tReq.ip = forwarded[0].split(",")[0].trim();
-  } else {
-    tReq.ip = req.socket?.remoteAddress ?? "127.0.0.1";
-  }
+  // Raw socket peer — NEVER honours a forwarding header, so it can be trusted
+  // for security decisions. Resolved BEFORE .ip: the peer decides whether the
+  // forwarding headers may be believed at all (TINA4_TRUSTED_PROXIES, ADR-0019).
+  tReq.remoteIp = req.socket?.remoteAddress ?? "";
+  tReq.ip = resolveClientIp(req.headers, tReq.remoteIp) || "127.0.0.1";
 
   // Add convenience methods
   tReq.header = function (name: string): string | undefined {