tina4-nodejs 3.13.95 → 3.13.96

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).