tina4-nodejs 3.13.92 → 3.13.95

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 {

package/packages/core/src/response.ts

@@ -293,11 +293,56 @@ export function createResponse(res: ServerResponse): Tina4Response {
     return response.json({ error: true, code, message, status: statusCode }, statusCode);
   };
 
-  response.file = function (filePath: string, options?: { download?: boolean; contentType?: string }): Tina4Response {
+  response.file = function (
+    filePath: string,
+    options?: { download?: boolean; contentType?: string; root?: string },
+  ): Tina4Response {
     if (res.headersSent) return response;
 
+    // SECURITY: confine the read. The natural spelling of a download route,
+    //
+    //     response.file("downloads/" + name)   // name = "../secret.env"
+    //
+    // served any file the process could read - measured over real HTTP at 200
+    // with the contents of a .env one directory above the intended one.
+    //
+    // TWO checks. Containment ALONE does not close it: that payload resolves to
+    // <project>/secret.env, which IS inside the project root, and the project
+    // root is exactly where .env lives. Rejecting ".." on the way in is the
+    // check that closes it; containment then catches absolute paths and
+    // symlinks, neither of which carries a ".." segment. Same shape as
+    // static.ts's startsWith guard, which this function never had.
+    // Containment ONLY when a root is declared. Defaulting to cwd broke every
+    // legitimate absolute path.
+    const base = options?.root ? nodePath.resolve(options.root) : null;
+    let forbidden = filePath.split(/[\\/]/).includes("..");
+
+    if (!forbidden) {
+      const candidate = (base === null || nodePath.isAbsolute(filePath)) ? filePath : nodePath.join(base, filePath);
+      let resolved = candidate;
+      try {
+        resolved = fs.realpathSync(candidate);
+      } catch {
+        /* missing file: fall through to the 404 below with the joined path */
+      }
+      if (base !== null && base !== nodePath.sep && resolved !== base && !resolved.startsWith(base + nodePath.sep)) {
+        forbidden = true;
+      } else {
+        filePath = resolved;
+      }
+    }
+
+    if (forbidden) {
+      // Refuse BEFORE reading: never load bytes we will not send.
+      res.statusCode = 403;
+      safeSetHeader("Content-Type", "text/plain");
+      safeEnd("Forbidden");
+      return response;
+    }
+
     if (!fs.existsSync(filePath)) {
       res.statusCode = 404;
+      safeSetHeader("Content-Type", "text/plain");
       safeEnd("File not found");
       return response;
     }

package/packages/core/src/router.ts

@@ -1,5 +1,6 @@
 import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, MiddlewareSpec, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
 import { isTruthy } from "./dotenv.js";
+import { MiddlewareRunner, isMiddlewareClass } from "./middleware.js";
 
 /**
  * Whether `TINA4_TRAILING_SLASH_REDIRECT` is enabled.
@@ -821,16 +822,29 @@ export async function resolveStringMiddleware(spec: string): Promise<Middleware>
 /**
  * Resolve a single route-middleware spec to a middleware function. Functions
  * pass through unchanged; strings are resolved via resolveStringMiddleware.
+ * A middleware CLASS never reaches here — runRouteMiddlewares runs it through
+ * the MiddlewareRunner instead.
  */
 async function resolveMiddlewareSpec(spec: MiddlewareSpec): Promise<Middleware> {
-  return typeof spec === "string" ? resolveStringMiddleware(spec) : spec;
+  return typeof spec === "string" ? resolveStringMiddleware(spec) : spec as Middleware;
 }
 
 /**
- * Run per-route middleware chain, then call the handler.
+ * Run the per-route middleware chain. Returns false when it short-circuited
+ * and the handler must be skipped.
  *
- * Accepts middleware functions and/or string specs (e.g. "ResponseCache:300").
- * Each spec is resolved to a middleware function just before it runs.
+ * Accepts middleware functions, middleware CLASSES, and string specs
+ * (e.g. "ResponseCache:300"). A function or string spec is resolved and
+ * invoked as `mw(req, res, next)` exactly as before.
+ *
+ * A CLASS runs its beforeX hooks through the SAME `MiddlewareRunner.runBefore`
+ * and the SAME return-value table as global middleware — no parallel runner.
+ * Its afterX hooks run with the global after pass once the handler is done
+ * (server.ts / testClient.ts append the route's classes to that list), because
+ * "after" means after the handler, not after this function. Every spec used to
+ * be invoked as `mw(req, res, next)`, which for a class throws "Class
+ * constructor cannot be invoked without 'new'", so a class attached per-route
+ * was inert. Python and PHP both ran per-route class hooks already.
  */
 export async function runRouteMiddlewares(
   middlewares: MiddlewareSpec[],
@@ -838,6 +852,17 @@ export async function runRouteMiddlewares(
   res: Tina4Response,
 ): Promise<boolean> {
   for (const spec of middlewares) {
+    if (isMiddlewareClass(spec)) {
+      // tina4: a class hook that returns a DIFFERENT [req, res] pair cannot be
+      // rebound here — this returns a bool and is public API (four of this
+      // repo's own test files import it). Node's req/res are per-request
+      // singletons, so every built-in returns the same pair back; widen the
+      // return type if that ever stops being true.
+      const [, , proceed] = await MiddlewareRunner.runBefore([spec], req, res);
+      if (!proceed || res.raw.writableEnded) return false;
+      continue;
+    }
+
     const mw = await resolveMiddlewareSpec(spec);
     let nextCalled = false;
     await mw(req, res, () => {