tina4-nodejs 3.13.37 → 3.13.39

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;
         }
       }
     }
@@ -255,7 +345,7 @@ export class CorsMiddleware {
     const allowedHeaders = process.env.TINA4_CORS_HEADERS
       ?? "Content-Type,Authorization,X-Request-ID";
 
-    const credentials = process.env.TINA4_CORS_CREDENTIALS ?? "true";
+    const credentials = process.env.TINA4_CORS_CREDENTIALS ?? "false";
 
     const maxAge = process.env.TINA4_CORS_MAX_AGE
       ? parseInt(process.env.TINA4_CORS_MAX_AGE, 10)

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

@@ -9,6 +9,11 @@
  *   TINA4_KAFKA_BROKERS   (override; default: "localhost:9092")
  *   TINA4_KAFKA_GROUP_ID  (default: "tina4_consumer_group")
  *
+ *   TLS/SASL (each read as TINA4_KAFKA_<NAME> first, then bare KAFKA_<NAME>):
+ *   TINA4_KAFKA_SECURITY_PROTOCOL — e.g. SSL / SASL_SSL (default: PLAINTEXT)
+ *   TINA4_KAFKA_SSL_CA_LOCATION   — CA cert path for TLS brokers/proxies
+ *   TINA4_KAFKA_SASL_MECHANISM / TINA4_KAFKA_SASL_USERNAME / TINA4_KAFKA_SASL_PASSWORD — optional SASL
+ *
  * Precedence for brokers: specific TINA4_KAFKA_BROKERS var (if set)
  *   > value derived from TINA4_QUEUE_URL > existing default.
  */
@@ -24,6 +29,62 @@ export interface KafkaConfig {
   groupId?: string;
 }
 
+/**
+ * librdkafka-style SSL/SASL client config (a TLS broker/proxy). Mirrors the
+ * keys produced by Python's `KafkaConnector._security_config`. Every key is
+ * optional — an unset env var leaves the key OUT (librdkafka defaults to the
+ * PLAINTEXT protocol with no SASL).
+ */
+export interface KafkaSecurityConfig {
+  "security.protocol"?: string;
+  "ssl.ca.location"?: string;
+  "sasl.mechanism"?: string;
+  "sasl.username"?: string;
+  "sasl.password"?: string;
+}
+
+/** Resolved producer/consumer config — brokers, client id, and security keys. */
+export interface KafkaClientConfig extends KafkaSecurityConfig {
+  "bootstrap.servers": string;
+  "client.id": string;
+  "group.id"?: string;
+  "auto.offset.reset"?: string;
+  "enable.auto.commit"?: boolean;
+}
+
+/**
+ * Build the SSL/SASL client config from the environment (for a TLS broker or
+ * proxy in front of Kafka). Each setting is read from the Tina4-namespaced env
+ * var FIRST (`TINA4_KAFKA_SECURITY_PROTOCOL` …) and falls back to the bare
+ * librdkafka-convention name (`KAFKA_SECURITY_PROTOCOL` …) that many Kafka
+ * deployments already set. Honours security.protocol (e.g. SSL, SASL_SSL),
+ * ssl.ca.location, and optional SASL (mechanism / username / password). Unset
+ * keys are omitted so librdkafka keeps its PLAINTEXT defaults.
+ *
+ * Exported for testing/introspection — and exact parity with Python's
+ * `_security_config` (same key set, same precedence, same omit-when-unset).
+ */
+export function kafkaSecurityConfig(
+  env: NodeJS.ProcessEnv = process.env
+): KafkaSecurityConfig {
+  // rdkafka key -> env suffix (read as TINA4_KAFKA_<suffix>, then KAFKA_<suffix>)
+  const mapping: [keyof KafkaSecurityConfig, string][] = [
+    ["security.protocol", "SECURITY_PROTOCOL"],
+    ["ssl.ca.location", "SSL_CA_LOCATION"],
+    ["sasl.mechanism", "SASL_MECHANISM"],
+    ["sasl.username", "SASL_USERNAME"],
+    ["sasl.password", "SASL_PASSWORD"],
+  ];
+  const config: KafkaSecurityConfig = {};
+  for (const [rdk, suffix] of mapping) {
+    const value = env[`TINA4_KAFKA_${suffix}`] || env[`KAFKA_${suffix}`];
+    if (value) {
+      config[rdk] = value;
+    }
+  }
+  return config;
+}
+
 export interface QueueBackend {
   push(queue: string, payload: unknown, delay?: number): string;
   pop(queue: string): QueueJob | null;
@@ -77,6 +138,42 @@ export class KafkaBackend implements QueueBackend {
     return { brokers: this.brokers, groupId: this.groupId };
   }
 
+  /**
+   * Resolved SSL/SASL client config from the environment (PLAINTEXT default).
+   * Mirrors Python's `KafkaConnector._security_config`.
+   */
+  securityConfig(): KafkaSecurityConfig {
+    return kafkaSecurityConfig();
+  }
+
+  /**
+   * Full producer config — brokers + client id + the resolved security block.
+   * The security keys are applied to BOTH producer and consumer (matching
+   * Python's `_connect_confluent`).
+   */
+  producerConfig(): KafkaClientConfig {
+    return {
+      "bootstrap.servers": this.brokers,
+      "client.id": "tina4-nodejs",
+      ...this.securityConfig(),
+    };
+  }
+
+  /**
+   * Full consumer config — brokers + client id + group id + the SAME resolved
+   * security block applied to the producer.
+   */
+  consumerConfig(): KafkaClientConfig {
+    return {
+      "bootstrap.servers": this.brokers,
+      "client.id": "tina4-nodejs",
+      "group.id": this.groupId,
+      "auto.offset.reset": "earliest",
+      "enable.auto.commit": false,
+      ...this.securityConfig(),
+    };
+  }
+
   /**
    * Parse broker string into host:port.
    */
@@ -328,7 +425,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

@@ -67,6 +67,23 @@ interface CompiledRoute {
   template?: string;
 }
 
+/**
+ * Thin reference to a registered WebSocket route, enabling chained modifiers
+ * — the WS analogue of {@link RouteRef}.
+ *
+ * Usage:
+ *   router.websocket("/ws/secure", handler).secure();
+ */
+export class WsRouteRef {
+  constructor(private route: WebSocketRouteDefinition) {}
+
+  /** Mark this WS route as requiring a valid JWT on the upgrade handshake. */
+  secure(): this {
+    this.route.authRequired = true;
+    return this;
+  }
+}
+
 /**
  * Thin reference to a registered route, enabling chained modifiers.
  *
@@ -412,11 +429,29 @@ export class Router {
 
   /**
    * Register a WebSocket route.
+   *
+   * A WS route is PUBLIC by default (mirrors GET). It can be marked secured in
+   * EITHER way the HTTP routes support:
+   *   • imperatively — `websocket(path, fn, { secured: true })`, or chain the
+   *     returned ref: `websocket(path, fn).secure()`;
+   *   • decorator-style — a `_secured` flag on the handler function, set in
+   *     either order relative to registration (the ref keeps a back-reference
+   *     to the route so a later `.secure()` / `_secured` still flips it).
+   *
+   * When secured, the upgrade handshake requires a valid JWT (Authorization
+   * header / `bearer` subprotocol / `?token=`) or the upgrade is rejected.
    */
-  websocket(path: string, handler: WebSocketRouteHandler): void {
+  websocket(path: string, handler: WebSocketRouteHandler, options?: { secured?: boolean }): WsRouteRef {
     // Remove existing ws route with same pattern (for hot-reload)
     this.wsRoutes = this.wsRoutes.filter((r) => r.pattern !== path);
-    this.wsRoutes.push({ pattern: path, handler });
+    const route: WebSocketRouteDefinition = {
+      pattern: path,
+      handler,
+      // Public unless explicitly secured via options OR a handler `_secured` flag.
+      authRequired: Boolean(options?.secured ?? handler._secured ?? false),
+    };
+    this.wsRoutes.push(route);
+    return new WsRouteRef(route);
   }
 
   /**
@@ -503,8 +538,21 @@ export class Router {
   /**
    * Register a WebSocket route on the default global router.
    */
-  static websocket(path: string, handler: WebSocketRouteHandler): void {
-    defaultRouter.websocket(path, handler);
+  static websocket(path: string, handler: WebSocketRouteHandler, options?: { secured?: boolean }): WsRouteRef {
+    return defaultRouter.websocket(path, handler, options);
+  }
+
+  /**
+   * Match a WebSocket upgrade path against routes on the default global router.
+   * Returns the matched route definition (with its `authRequired` flag) or null.
+   */
+  static matchWebSocket(pathname: string): WebSocketRouteDefinition | null {
+    return defaultRouter.matchWebSocket(pathname);
+  }
+
+  /** All WebSocket route definitions on the default global router. */
+  static getWebSocketRoutes(): WebSocketRouteDefinition[] {
+    return defaultRouter.getWebSocketRoutes();
   }
 
   /**
@@ -615,10 +663,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];
@@ -816,8 +864,8 @@ export function any(path: string, handler: RouteHandler, middlewares?: Middlewar
   return defaultRouter.any(path, handler, middlewares, meta);
 }
 
-export function websocket(path: string, handler: WebSocketRouteHandler): void {
-  defaultRouter.websocket(path, handler);
+export function websocket(path: string, handler: WebSocketRouteHandler, options?: { secured?: boolean }): WsRouteRef {
+  return defaultRouter.websocket(path, handler, options);
 }
 
 // Re-export "del" as "delete" for developer convenience (use: import { delete as del } from "@tina4/core")