tina4-nodejs 3.13.95 → 3.13.97

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

@@ -471,16 +471,8 @@ export class RabbitMQBackend implements QueueBackend {
             process.stdout.write(String(msgCount));
             closeConnection();
           }
-          else if (operation === "purge") {
-            // Queue.Purge
-            const qBuf = Buffer.from(queueName, "utf-8");
-            const purgePayload = Buffer.alloc(4 + qBuf.length);
-            purgePayload.writeUInt16BE(0, 0);
-            purgePayload.writeUInt8(qBuf.length, 2);
-            qBuf.copy(purgePayload, 3);
-            purgePayload.writeUInt8(0, 3 + qBuf.length); // no-wait=false
-            sendMethod(1, 50, 30, purgePayload);
-          }
+          // No "purge" operation: clear()/purge() refuse by name (ADR-0022),
+          // so nothing ever sends Queue.Purge and the drain path is gone.
         }
         else if (classId === 60 && methodId === 71) {
           // Basic.Get-Ok — message body will follow in content frames
@@ -491,11 +483,6 @@ export class RabbitMQBackend implements QueueBackend {
           process.stdout.write("__EMPTY__");
           closeConnection();
         }
-        else if (classId === 50 && methodId === 31) {
-          // Queue.Purge-Ok
-          process.stdout.write("__PURGED__");
-          closeConnection();
-        }
         else if (classId === 10 && methodId === 50) {
           // Connection.Close (server-initiated, e.g. a channel/protocol error)
           // → send Connection.Close-Ok and exit non-zero so the caller sees the
@@ -633,7 +620,32 @@ export class RabbitMQBackend implements QueueBackend {
     return isNaN(num) ? 0 : num;
   }
 
-  clear(queue: string): void {
-    this.execSync("purge", queue);
+  clear(_queue: string): void {
+    // Not performable on RabbitMQ - throws naming the backend and the operation.
+    // clear() empties the queue, but RabbitMQ cannot address messages by status;
+    // the only thing it could do is queue.purge the WHOLE live queue. This used
+    // to do exactly that (execSync("purge", queue)), silently destroying every
+    // pending job. Draining a live broker on a status-addressed clear is data
+    // loss (ADR-0022 invariant 6), so it refuses by name instead. PHP, Python
+    // and Ruby already refuse; this brings the Node backend class in line.
+    throw new Error(
+      "The rabbitmq queue backend cannot perform clear(): RabbitMQ cannot " +
+        "address messages by status (basic.get pops the head of the queue), so " +
+        "a status-addressed clear would have to drain the entire live queue and " +
+        "destroy pending work. Use the file or mongodb backend.",
+    );
+  }
+
+  purge(_queue: string, _status?: string): number {
+    // Not performable on RabbitMQ - throws naming the backend and the operation.
+    // purge(status) removes jobs SELECTED BY STATUS; RabbitMQ has no status
+    // concept and could only drain the whole live queue. Refusing by name is
+    // the honest answer.
+    throw new Error(
+      "The rabbitmq queue backend cannot perform purge(): RabbitMQ cannot " +
+        "address messages by status (basic.get pops the head of the queue), so " +
+        "a status-addressed purge would have to drain the entire live queue and " +
+        "destroy pending work. Use the file or mongodb backend.",
+    );
   }
 }

package/packages/core/src/request.ts

@@ -160,19 +160,40 @@ async function parseBody(req: Tina4Request): Promise<void> {
   const chunks: Buffer[] = [];
 
   await new Promise<void>((resolve, reject) => {
-    req.on("data", (chunk: Buffer) => chunks.push(chunk));
-    req.on("end", resolve);
+    // A RUNNING cap, checked per chunk.
+    //
+    // The content-length check above only sees what the client DECLARES. A
+    // chunked request declares nothing, so declaredLength is 0 and it sails
+    // through. Without this counter the body is buffered in full and only
+    // then measured, which means the limit cannot prevent the thing it exists
+    // to prevent. Measured against a 1MB limit: a 40MB chunked POST with no
+    // content-length was accepted whole and grew the server's RSS by exactly
+    // 40.0MB before it was refused.
+    //
+    // Same defect as PHP's unbounded read buffer, and the same fix: stop at
+    // the limit instead of measuring the damage afterwards.
+    let received = 0;
+    let refused = false;
+    req.on("data", (chunk: Buffer) => {
+      if (refused) return;
+      received += chunk.length;
+      if (received > TINA4_MAX_UPLOAD_SIZE) {
+        refused = true;
+        chunks.length = 0; // drop what we have; the request is dead
+        reject(new PayloadTooLargeError(received, TINA4_MAX_UPLOAD_SIZE));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!refused) resolve();
+    });
     req.on("error", reject);
   });
 
   const raw = Buffer.concat(chunks);
   if (raw.length === 0) return;
 
-  // Check actual body size against upload size limit
-  if (raw.length > TINA4_MAX_UPLOAD_SIZE) {
-    throw new PayloadTooLargeError(raw.length, TINA4_MAX_UPLOAD_SIZE);
-  }
-
   if (contentType.includes("multipart/form-data")) {
     const boundary = extractBoundary(contentType);
     if (boundary) {

package/packages/core/src/server.ts

@@ -378,9 +378,29 @@ function openBrowser(url: string) {
  * for backwards compatibility.
  */
 export function resolvePortAndHost(config?: { port?: number; host?: string }): { port: number; host: string } {
-  const port = config?.port
-    ?? (process.env.PORT ? parseInt(process.env.PORT, 10) : undefined)
-    ?? 7148;
+  // Port: explicit config > TINA4_PORT > PORT (deprecated) > default.
+  //
+  // This read PORT and nothing else, so TINA4_PORT - the name the CLI
+  // documents and prefers, and the one devAdmin.ts itself reads first - was
+  // IGNORED on the path that binds the socket. Setting it did nothing and said
+  // nothing.
+  //
+  // Bare PORT stays honoured so no deployment breaks, and warns so the
+  // migration happens. Removal is 3.14.
+  const tina4Port = process.env.TINA4_PORT;
+  const legacyPort = process.env.PORT;
+  let port: number;
+  if (config?.port !== undefined) {
+    port = config.port;
+  } else if (tina4Port && /^\d+$/.test(tina4Port)) {
+    port = parseInt(tina4Port, 10);
+  } else if (legacyPort && /^\d+$/.test(legacyPort)) {
+    port = parseInt(legacyPort, 10);
+    warnDeprecatedPort(port);
+  } else {
+    port = 7148;
+  }
+
   const host = config?.host
     ?? process.env.TINA4_HOST
     ?? process.env.HOST
@@ -388,6 +408,22 @@ export function resolvePortAndHost(config?: { port?: number; host?: string }): {
   return { port, host };
 }
 
+/**
+ * Warn ONCE that bare PORT was used instead of TINA4_PORT.
+ *
+ * Once, because resolvePortAndHost can be called more than once per process
+ * and a warning repeated on every call is a warning people filter out.
+ */
+let portDeprecationWarned = false;
+function warnDeprecatedPort(port: number): void {
+  if (portDeprecationWarned) return;
+  portDeprecationWarned = true;
+  Log.warning(
+    `PORT is deprecated and will be removed in 3.14 - use TINA4_PORT instead ` +
+    `(binding port ${port} from PORT)`,
+  );
+}
+
 /**
  * Whether the boot banner should be suppressed. Set TINA4_SUPPRESS=true to
  * silence the ASCII-art banner and route table on startup — useful in CI,
@@ -795,6 +831,67 @@ let _serverHandle: { close: () => void; router: Router; port: number } | null =
  * Start the Tina4 HTTP server.
  * Thin wrapper around startServer() for cross-framework parity with PHP and Ruby.
  */
+/**
+ * Watch for a handler that occupies the event loop, and say so.
+ *
+ * Node runs ONE loop. An `await`ing handler yields it and blocks nobody -
+ * measured, /fast answers in 0.030s while a route awaits a 2s timer. A
+ * CPU-BOUND handler does not yield, and everything else waits: the same /fast
+ * took 1.575s during a 2s busy loop.
+ *
+ * That is inherent to a single-loop runtime, not a bug to engineer away. PHP
+ * fixed its equivalent by forking per request because `sleep()` is the obvious
+ * thing to write there and it blocks; in JavaScript the obvious thing is
+ * `await`, which does not. So the exposure here is narrower - CPU-bound work
+ * and synchronous I/O - and the honest fix is to make it VISIBLE rather than
+ * to move handlers onto threads a closure cannot cross.
+ *
+ * The mechanism is loop lag: a timer set for TICK_MS fires late by however
+ * long the loop was blocked. If that lateness passes the threshold, something
+ * held the loop and the developer wants to know which.
+ *
+ * A 100ms repeating timer is the classic way to pin a process open forever, so
+ * there are two guards against it: close() stops the timer, and the timer is
+ * unref'd. Measured: either one alone is enough, and the signal path exits
+ * regardless of both. They are kept together because they cost nothing and
+ * cover different exits - close() covers the in-process handle, unref() covers
+ * a path that never reaches close() at all.
+ */
+const LOOP_WATCHDOG_TICK_MS = 100;
+
+function startLoopWatchdog(): { stop: () => void } {
+  const raw = (process.env.TINA4_LOOP_LAG_WARN_MS ?? "").trim();
+  // 0 or a negative value disables it; a non-numeric value falls to the
+  // default rather than silently disabling a diagnostic.
+  const threshold = /^\d+$/.test(raw) ? parseInt(raw, 10) : 250;
+  if (threshold <= 0) {
+    return { stop: () => {} };
+  }
+
+  let last = Date.now();
+  let warned = 0;
+  const timer = setInterval(() => {
+    const now = Date.now();
+    const lag = now - last - LOOP_WATCHDOG_TICK_MS;
+    last = now;
+    if (lag < threshold) return;
+
+    // Rate-limited: a handler that blocks on every request would otherwise
+    // produce a wall of identical warnings, which people filter out.
+    warned++;
+    if (warned > 5 && warned % 20 !== 0) return;
+    Log.warning(
+      `Event loop blocked for ${lag}ms. Node serves every request on one loop, ` +
+      `so a handler doing CPU-bound work or synchronous I/O stalls all the ` +
+      `others for that long. Move the work to Tina4's queue, or await it. ` +
+      `Set TINA4_LOOP_LAG_WARN_MS to change the ${threshold}ms threshold, or 0 to silence.`,
+    );
+  }, LOOP_WATCHDOG_TICK_MS);
+  timer.unref();
+
+  return { stop: () => clearInterval(timer) };
+}
+
 export async function start(config?: Tina4Config): Promise<{ close: () => void; router: Router; port: number }> {
   const isManaged = process.argv.includes('--managed');
   if (!isManaged && process.env.TINA4_OVERRIDE_CLIENT !== 'true') {
@@ -1390,8 +1487,18 @@ export async function startServer(config?: Tina4Config): Promise<{
   const host = resolved.host;
   let port = resolved.port;
 
-  // Claim the requested port — kill whatever is on it if needed
-  port = findAvailablePort(port);
+  // Claim the requested port — kill whatever is on it if needed.
+  //
+  // NOT in a cluster worker. A worker does not own the port: the primary binds
+  // it once and hands the handle down through cluster's IPC. A worker running
+  // this finds the port "in use" (the primary is holding it) and KILLS the
+  // process holding it, which is its own parent. Every worker did that, then
+  // died itself with `write EPIPE` from cluster._getServer because the primary
+  // it needed to ask for the socket was gone. Cluster mode never served a
+  // single request.
+  if (!cluster.isWorker) {
+    port = findAvailablePort(port);
+  }
 
   // Cluster mode for production: fork workers based on CPU count
   // Only when --production is explicitly set (via TINA4_PRODUCTION env var)
@@ -1703,8 +1810,26 @@ ${reset}
       await middleware.run(req, res);
       if (res.raw.writableEnded) return;
 
-      // Parse request body
-      await req.parseBody();
+      // Parse request body.
+      //
+      // A body that breaks a documented limit is the client's error, not the
+      // server's. PayloadTooLargeError already carried `statusCode = 413` and
+      // nothing read it, so an oversized upload answered 500 - which tells the
+      // caller to retry the exact request that will fail again.
+      try {
+        await req.parseBody();
+      } catch (err) {
+        const status = (err as { statusCode?: number })?.statusCode;
+        if (typeof status === "number" && status >= 400 && status < 500) {
+          if (!rawRes.writableEnded) {
+            rawRes.statusCode = status;
+            rawRes.setHeader("content-type", "application/json");
+            rawRes.end(JSON.stringify({ error: (err as Error).message }));
+          }
+          return;
+        }
+        throw err;
+      }
 
       const pathname = req.path;
 
@@ -2043,8 +2168,11 @@ ${reset}
       process.on("SIGTERM", onSigterm);
       process.on("SIGINT", onSigint);
 
+      const loopWatchdog = startLoopWatchdog();
+
       resolvePromise({
         close: () => {
+          loopWatchdog.stop();
           // An explicit close() is not a signal shutdown: drop the handlers so
           // a test that starts many servers in one process does not pile up
           // listeners (and trip Node's MaxListeners warning).

package/packages/core/src/session.ts

@@ -711,10 +711,17 @@ export class Session {
    *
    *   session.flash("message", "Saved!")  // set
    *   session.flash("message")            // get + auto-remove → "Saved!"
+   *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+   *
+   * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+   * READS and clears rather than STORING null. This matches the Python master
+   * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+   * (`if value.nil?`): passing the language's "no value" literal means GET. A
+   * caller wanting to persist an explicit null should store it with `set()`.
    */
   flash(key: string, value?: unknown): unknown {
     const flashKey = `${FLASH_PREFIX}${key}`;
-    if (value !== undefined) {
+    if (value !== undefined && value !== null) {
       // Set mode
       this.set(flashKey, value);
       return undefined;