tina4-nodejs 3.13.37 → 3.13.38

package/packages/core/src/middleware.ts

@@ -22,32 +22,45 @@ export class MiddlewareChain {
     this.middlewares.push(fn);
   }
 
+  /**
+   * Run the chain in REGISTRATION order — each middleware runs exactly once,
+   * in the order it was attached via use(). The chain advances from ONE
+   * source only: `next()`. (The old runner double-advanced — a for-loop index
+   * AND next() both incremented — so every other middleware was silently
+   * skipped. Fixed by driving the chain purely by next(), mirroring Python's
+   * _make_mw_continuation Russian-doll continuation.)
+   *
+   * A middleware may stop the chain by:
+   *   - not calling next() (it owns the response), or
+   *   - ending the response (res.raw.writableEnded).
+   * Returns true when the whole chain ran to completion (handler may proceed),
+   * false when it was short-circuited.
+   */
   async run(req: Tina4Request, res: Tina4Response): Promise<boolean> {
-    let index = 0;
-    let completed = true;
+    const dispatch = async (i: number): Promise<void> => {
+      if (i >= this.middlewares.length) return;
+      let advanced = false;
 
-    const next = (): void => {
-      index++;
-    };
+      const next = (): void => {
+        advanced = true;
+      };
 
-    for (index = 0; index < this.middlewares.length; index++) {
-      const prevIndex = index;
-      await this.middlewares[index](req, res, next);
+      await this.middlewares[i](req, res, next);
 
-      // If response was already sent, stop the chain
-      if (res.raw.writableEnded) {
-        completed = false;
-        break;
-      }
+      // The middleware owns the response — stop the chain.
+      if (res.raw.writableEnded) return;
 
-      // If next() wasn't called, stop the chain
-      if (index === prevIndex) {
-        // next() increments index, so if it wasn't called, index stays the same
-        // But we increment in the for loop, so we need to check differently
+      // next() was called → advance to the following middleware (exactly one
+      // step). next() not called → the middleware short-circuited; stop here.
+      if (advanced) {
+        await dispatch(i + 1);
       }
-    }
+    };
 
-    return completed;
+    await dispatch(0);
+
+    // Completed (handler may proceed) iff no middleware ended the response.
+    return !res.raw.writableEnded;
   }
 }
 
@@ -64,6 +77,39 @@ export class MiddlewareChain {
  * If a "before" method returns a response whose status code is >= 400
  * the chain short-circuits and runBefore returns shouldContinue = false.
  */
+/**
+ * Produce the deterministic clean 500 for a throwing class-based middleware
+ * (M2). Mirrors Python's _middleware_500: LOG via Log.error (class + method +
+ * error type + message — never silent) then return a 500 with the exact JSON
+ * body shape shared across all four frameworks. The worker never crashes and
+ * no unhandled exception leaks.
+ */
+function middleware500(
+  res: Tina4Response,
+  mwClass: any,
+  methodName: string,
+  error: unknown,
+): Tina4Response {
+  const clsName = mwClass?.name ?? mwClass?.constructor?.name ?? "Middleware";
+  const err = error as { name?: string; message?: string };
+  const type = err?.name ?? (error as object)?.constructor?.name ?? "Error";
+  const message = err?.message ?? String(error);
+  try {
+    Log.error(`Middleware ${clsName}.${methodName} raised ${type}: ${message}`);
+  } catch {
+    /* never let a broken logger swallow the 500 */
+  }
+  // res is callable (json) in real Response; tolerate either shape.
+  if (typeof (res as any).json === "function") {
+    (res as any).json({ error: "Internal Server Error", status: 500 }, 500);
+  } else if (typeof (res as any) === "function") {
+    (res as any)({ error: "Internal Server Error", status: 500 }, 500);
+  } else if (typeof (res as any).status === "function") {
+    (res as any).status(500);
+  }
+  return res;
+}
+
 export class MiddlewareRunner {
   /** Globally registered middleware classes (parity with PHP/Ruby/Python orchestrators). */
   private static globalMiddleware: any[] = [];
@@ -90,16 +136,43 @@ export class MiddlewareRunner {
   }
 
   /**
-   * Execute every beforeX static method found on the supplied classes,
-   * in order. Returns the (possibly mutated) request and response pair and a
-   * boolean indicating whether the route handler should still run.
+   * Discover the before-prefixed / after-prefixed method names on a
+   * middleware class in DEFINITION order (M1).
+   * `Object.getOwnPropertyNames` returns a class's own
+   * static method names in source-declaration order — we deliberately do NOT
+   * sort() them, so within a class the hooks run in the order they were
+   * written (parity with Python walking __dict__, PHP get_class_methods, Ruby
+   * instance_methods(false)). Cross-class order is the natural iteration of
+   * the registered classes = REGISTRATION order.
+   */
+  private static methodNames(cls: any, prefix: string): string[] {
+    return Object.getOwnPropertyNames(cls).filter(
+      (name) => typeof cls[name] === "function" && name.startsWith(prefix),
+    );
+  }
+
+  /**
+   * Execute every beforeX static method found on the supplied classes.
+   *
+   * ORDER (M1): cross-class = REGISTRATION order (the order classes were
+   * attached via Router.use / MiddlewareRunner.use); within a class =
+   * DEFINITION order (source order, never alphabetical). before_* run before
+   * the handler.
+   *
+   * THROW (M2): each before* call is wrapped — a throwing middleware is
+   * LOGGED and produces a deterministic clean 500 (it never crashes the
+   * worker / leaks an unhandled exception), and the chain short-circuits
+   * (skip = true, handler skipped).
    *
-   * Short-circuits when a before method sets a status >= 400.
+   * Short-circuits (skip = true, handler skipped) when a before* sets a
+   * status >= 400 or ends/500s the response.
    *
    * ASYNC — each hook is awaited so middleware can perform async work (e.g.
    * the distributed responseCache before-hook awaiting `backend.get`). Awaiting
    * a synchronous hook that returns an array is harmless (the array resolves
    * immediately), so existing sync hooks keep working unchanged.
+   *
+   * Returns [req, res, shouldContinue].
    */
   static async runBefore(
     classes: any[],
@@ -107,13 +180,16 @@ export class MiddlewareRunner {
     res: Tina4Response,
   ): Promise<[Tina4Request, Tina4Response, boolean]> {
     for (const cls of classes) {
-      const methods = Object.getOwnPropertyNames(cls).filter(
-        (name) => typeof cls[name] === "function" && name.startsWith("before"),
-      );
-      for (const method of methods) {
-        const result = await cls[method](req, res);
-        if (Array.isArray(result)) {
-          [req, res] = result as [Tina4Request, Tina4Response];
+      for (const method of MiddlewareRunner.methodNames(cls, "before")) {
+        try {
+          const result = await cls[method](req, res);
+          if (Array.isArray(result)) {
+            [req, res] = result as [Tina4Request, Tina4Response];
+          }
+        } catch (error) {
+          // Throw → logged clean 500, skip the handler (deterministic).
+          res = middleware500(res, cls, method, error);
+          return [req, res, false];
         }
         // Short-circuit if the middleware set an error status
         if (res.raw.statusCode >= 400 || res.raw.writableEnded) {
@@ -125,8 +201,19 @@ export class MiddlewareRunner {
   }
 
   /**
-   * Execute every afterX static method found on the supplied classes,
-   * in order. Returns the (possibly mutated) request and response pair.
+   * Execute every afterX static method found on the supplied classes.
+   *
+   * ORDER (M1): cross-class = REGISTRATION order; within a class = DEFINITION
+   * order. after_* run after the handler.
+   *
+   * THROW (M2): each after* call is wrapped — a throwing after middleware is
+   * LOGGED and produces a clean 500, then the remaining after* STILL run
+   * (they may add headers / logging). No unhandled exception leaks.
+   *
+   * AFTER-ON-4xx RULE (M2): after_* ALWAYS run, even when a before_*
+   * short-circuited with status >= 400 and the handler was skipped — so they
+   * can still add headers / logging. The dispatcher calls runAfter
+   * unconditionally after the before/handler block (see server.ts).
    *
    * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
    * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
@@ -138,13 +225,16 @@ export class MiddlewareRunner {
     res: Tina4Response,
   ): Promise<[Tina4Request, Tina4Response]> {
     for (const cls of classes) {
-      const methods = Object.getOwnPropertyNames(cls).filter(
-        (name) => typeof cls[name] === "function" && name.startsWith("after"),
-      );
-      for (const method of methods) {
-        const result = await cls[method](req, res);
-        if (Array.isArray(result)) {
-          [req, res] = result as [Tina4Request, Tina4Response];
+      for (const method of MiddlewareRunner.methodNames(cls, "after")) {
+        try {
+          const result = await cls[method](req, res);
+          if (Array.isArray(result)) {
+            [req, res] = result as [Tina4Request, Tina4Response];
+          }
+        } catch (error) {
+          // Throw → logged clean 500, but remaining after* STILL run.
+          res = middleware500(res, cls, method, error);
+          continue;
         }
       }
     }

package/packages/core/src/plan.ts

@@ -487,7 +487,7 @@ export const Plan = {
         }),
         signal: AbortSignal.timeout(120_000),
       });
-      result = await resp.json();
+      result = (await resp.json()) as Record<string, unknown>;
     } catch (e) {
       return { ok: false, error: `AI backend unreachable: ${(e as Error).message}` };
     }

package/packages/core/src/queue.ts

@@ -71,7 +71,7 @@ export interface QueueBackendInterface {
   push(queue: string, payload: unknown, delay?: number): string;
   pop(queue: string): QueueJob | null;
   size(queue: string): number;
-  clear(queue: string): number;
+  clear(queue: string): void;
 }
 
 // ── Queue ────────────────────────────────────────────────────

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

@@ -328,7 +328,7 @@ export class KafkaBackend implements QueueBackend {
     const id = randomUUID();
     const now = new Date().toISOString();
 
-    const job: QueueJob = {
+    const job = {
       id,
       payload,
       status: "pending",

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

@@ -198,7 +198,7 @@ export class MongoBackend implements QueueBackend {
     const id = randomUUID();
     const now = new Date().toISOString();
 
-    const job: QueueJob = {
+    const job = {
       id,
       payload,
       status: "pending",

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

@@ -510,7 +510,7 @@ export class RabbitMQBackend implements QueueBackend {
     const id = randomUUID();
     const now = new Date().toISOString();
 
-    const job: QueueJob = {
+    const job = {
       id,
       payload,
       status: "pending",

package/packages/core/src/rateLimiter.ts

@@ -172,7 +172,7 @@ export class RateLimiter {
 
   /** Apply rate limiting to a request/response pair. Sets headers and 429 if exceeded. */
   apply(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response] {
-    const ip = (request as Record<string, unknown>).ip as string ?? "unknown";
+    const ip = request.ip ?? "unknown";
     const result = this.check(ip);
 
     response.header("X-RateLimit-Limit", String(result.limit));

package/packages/core/src/response.ts

@@ -1,8 +1,29 @@
 import type { ServerResponse } from "node:http";
 import fs from "node:fs";
 import nodePath from "node:path";
+import { once } from "node:events";
 import type { Tina4Response, CookieOptions } from "./types.js";
 
+/**
+ * Best-effort close of a streaming source on client disconnect or a mid-stream
+ * error. Async generators expose `.return()`; some custom iterables expose
+ * `.close()`/`.aclose()`. Any failure here is swallowed — cleanup is advisory.
+ */
+async function closeSource(source: AsyncIterable<unknown>): Promise<void> {
+  const s = source as {
+    return?: () => unknown;
+    close?: () => unknown;
+    aclose?: () => unknown;
+  };
+  try {
+    if (typeof s.return === "function") await s.return();
+    else if (typeof s.aclose === "function") await s.aclose();
+    else if (typeof s.close === "function") await s.close();
+  } catch {
+    /* cleanup is best-effort */
+  }
+}
+
 /** Cache Frond instances by template directory to avoid repeated instantiation. */
 const _frondCache = new Map<string, InstanceType<any>>();
 
@@ -116,8 +137,15 @@ function toJsonable(data: unknown): unknown {
 export function createResponse(res: ServerResponse): Tina4Response {
 
   // ── Guard: prevent writing after headers are sent ──
-  const safeEnd = (...args: Parameters<typeof res.end>) => {
-    if (!res.headersSent) (res.end as Function)(...args);
+  const safeEnd = (chunk?: string | Buffer, encoding?: BufferEncoding) => {
+    if (res.headersSent) return;
+    if (chunk === undefined) {
+      res.end();
+    } else if (encoding === undefined) {
+      res.end(chunk);
+    } else {
+      res.end(chunk, encoding);
+    }
   };
   const safeSetHeader = (name: string, value: string | number | readonly string[]) => {
     if (!res.headersSent) res.setHeader(name, value);
@@ -354,12 +382,68 @@ export function createResponse(res: ServerResponse): Tina4Response {
       "X-Accel-Buffering": "no",
     });
 
-    for await (const chunk of source) {
-      const data = typeof chunk === "string" ? chunk : chunk.toString();
-      res.write(data);
+    // True once the client has gone away (socket destroyed) or the response
+    // has been finished — keep checking so we bail cleanly mid-stream rather
+    // than writing into a dead socket or buffering forever.
+    const streamClosed = (): boolean =>
+      res.writableEnded || (res.socket?.destroyed ?? false);
+
+    // Keep-alive heartbeat: periodically write a ':' SSE comment line on a
+    // long-lived stream so proxies/load-balancers don't reap an idle but
+    // healthy connection. Opt-out via TINA4_SSE_HEARTBEAT=0 (any non-positive
+    // value disables it). The interval is unref'd so it never holds the
+    // process open on its own.
+    const heartbeatSeconds = parseFloat(process.env.TINA4_SSE_HEARTBEAT ?? "15");
+    let heartbeat: ReturnType<typeof setInterval> | null = null;
+    if (Number.isFinite(heartbeatSeconds) && heartbeatSeconds > 0) {
+      heartbeat = setInterval(() => {
+        if (streamClosed()) return;
+        try {
+          res.write(": keep-alive\n\n");
+        } catch {
+          /* write race with a closing socket — the loop's guard handles it */
+        }
+      }, heartbeatSeconds * 1000);
+      heartbeat.unref?.();
+    }
+
+    const stopHeartbeat = (): void => {
+      if (heartbeat !== null) {
+        clearInterval(heartbeat);
+        heartbeat = null;
+      }
+    };
+
+    try {
+      for await (const chunk of source) {
+        // Client disconnected mid-stream — stop cleanly. Closing the source
+        // (best-effort) lets the producer release resources.
+        if (streamClosed()) {
+          await closeSource(source);
+          break;
+        }
+        const data = typeof chunk === "string" ? chunk : chunk.toString();
+        const ok = res.write(data);
+        // Slow-client backpressure: when write() returns false the kernel
+        // buffer is full. Wait for it to drain before pulling the next chunk
+        // so we don't unboundedly buffer ahead of a client that can't keep up.
+        if (!ok && !streamClosed()) {
+          await once(res, "drain").catch(() => {
+            /* socket errored/closed while waiting — loop guard handles it */
+          });
+        }
+      }
+    } catch (err) {
+      // The generator/source itself raised mid-stream. Log and stop cleanly —
+      // end the stream rather than crashing the request handler/worker.
+      const { Log } = await import("./logger.js");
+      Log.error(`SSE/stream source error: ${err instanceof Error ? err.message : String(err)}`);
+      await closeSource(source);
+    } finally {
+      stopHeartbeat();
     }
 
-    res.end();
+    if (!res.writableEnded) res.end();
     return response;
   };
 

package/packages/core/src/router.ts

@@ -615,10 +615,10 @@ export class RouteGroup {
   constructor(
     private router: Router,
     private prefix: string,
-    private groupMiddlewares?: Middleware[],
+    private groupMiddlewares?: MiddlewareSpec[],
   ) {}
 
-  private mergeMiddlewares(routeMiddlewares?: Middleware[]): Middleware[] | undefined {
+  private mergeMiddlewares(routeMiddlewares?: MiddlewareSpec[]): MiddlewareSpec[] | undefined {
     const group = this.groupMiddlewares ?? [];
     const route = routeMiddlewares ?? [];
     const merged = [...group, ...route];

package/packages/core/src/server.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { execFileSync, exec } from "node:child_process";
 import cluster from "node:cluster";
 import os from "node:os";
+import type { Socket } from "node:net";
 import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
 import { Router, defaultRouter, runRouteMiddlewares } from "./router.js";
 import { validToken, getPayload, refreshToken } from "./auth.js";
@@ -675,9 +676,23 @@ export async function startServer(config?: Tina4Config): Promise<{
   router: Router;
   port: number;
 }> {
-  // Load .env early so TINA4_DEBUG is available for cluster decision
+  // Load env early so TINA4_DEBUG is available for the cluster decision.
+  // Precedence MUST be: real environment (set before boot) > .env.local > .env.
+  // loadEnv(override=false) is first-wins (only sets a key not already present),
+  // so load .env.local BEFORE .env — both with override=false. A real env var
+  // set before boot is already present and wins over both; .env.local fills
+  // local-only keys; .env fills whatever neither set. Loading .env.local with
+  // override=true would let a stray gitignored .env.local clobber an explicitly
+  // set real env var (e.g. a production TINA4_SECRET) — never do that.
+  loadEnv(".env.local");
   loadEnv();
 
+  // Auto-generate a per-machine dev secret to a gitignored .env.local when one
+  // is missing (dev only, never CI/prod). Must run after env load and before
+  // any auth use. Local import avoids a load-time cycle through auth.
+  const { ensureDevSecret } = await import("./auth.js");
+  ensureDevSecret();
+
   // Refuse to boot with pre-3.12 un-prefixed env vars set.
   _checkLegacyEnvVars();
 
@@ -972,8 +987,8 @@ ${reset}
           rawRes.setHeader("Content-Length", String(accumulated));
         }
         const realCb = typeof chunk === "function" ? chunk : cb;
-        return origEnd(undefined, undefined, realCb);
         void origWrite; // referenced to keep tsc happy
+        return typeof realCb === "function" ? origEnd(realCb) : origEnd();
       }) as typeof rawRes.end;
     }
 
@@ -1151,7 +1166,14 @@ ${reset}
         ];
         if (globalMiddleware.length > 0) {
           const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
-          if (!proceed || res.raw.writableEnded) return;
+          if (!proceed || res.raw.writableEnded) {
+            // AFTER-ON-4xx RULE (M2): after_* ALWAYS run even when a before_*
+            // short-circuited (4xx / clean 500 / response ended), so they can
+            // still add headers / logging. Run them, then stop the handler.
+            await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+            if (!res.raw.writableEnded) res.raw.end();
+            return;
+          }
         }
 
         // Run per-route middlewares if any
@@ -1403,7 +1425,7 @@ ${reset}
       (remoteAddress, p) => WsTracker.add(remoteAddress, p),
       (id) => { WsTracker.remove(id); },
     );
-    server.on("upgrade", (req: IncomingMessage, socket, head) => {
+    server.on("upgrade", (req: IncomingMessage, socket: Socket, head: Buffer) => {
       const upPath = (req.url ?? "/").split("?")[0];
       if (upPath === "/__dev_reload") {
         devReloadWs.handleUpgrade(req, socket, head);