tina4-nodejs 3.13.38 → 3.13.40

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();
   }
 
   /**
@@ -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")

package/packages/core/src/server.ts

@@ -20,7 +20,7 @@ import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector, WsTracker } from "./devAdmin.js";
-import { devReloadWs } from "./websocket.js";
+import { devReloadWs, serveWebSocketRoute, wsRouteManager } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
 import { stopAllBackgroundTasks } from "./background.js";
@@ -34,6 +34,72 @@ const BUILTIN_ERROR_TEMPLATES_DIR = resolve(__dirname, "..", "templates");
 /** Built-in public directory for framework-bundled static assets. */
 const BUILTIN_PUBLIC_DIR = resolve(__dirname, "..", "public");
 
+/**
+ * Apply pending DB migrations on startup — NON-BREAKING.
+ *
+ * When a `migrations/` folder exists (with at least one `.sql` file, excluding
+ * `.down.sql`) and `TINA4_AUTO_MIGRATE` is not disabled (default "true";
+ * false/0/no/off disable), pending migrations are applied during boot so the
+ * schema is current with no manual `tina4 migrate` step. A failure here is
+ * logged LOUD via `Log.error` and the service STILL starts — a bad migration
+ * must never take the backend down. (The explicit `tina4 migrate` CLI stays
+ * fail-fast so CI still gets a non-zero exit. Only this startup hook swallows.)
+ *
+ * Disable with `TINA4_AUTO_MIGRATE=false` — e.g. multi-instance production that
+ * migrates as a separate deploy step (concurrent first-apply can race).
+ *
+ * @param migrationDir - migrations directory (default "migrations", relative to base)
+ * @param base - project root used to resolve the migrations directory
+ */
+export async function autoMigrateOnStartup(
+  migrationDir = "migrations",
+  base = process.cwd(),
+): Promise<void> {
+  const dir = resolve(base, migrationDir);
+
+  // Gate 1: a migrations/ folder with at least one .sql (non-down) file.
+  if (!existsSync(dir)) return;
+  let hasSql = false;
+  try {
+    hasSql = readdirSync(dir).some((f) => f.endsWith(".sql") && !f.endsWith(".down.sql"));
+  } catch {
+    return; // unreadable dir → nothing to do (silent)
+  }
+  if (!hasSql) return;
+
+  // Gate 2: TINA4_AUTO_MIGRATE not falsy (default "true").
+  const flag = process.env.TINA4_AUTO_MIGRATE;
+  if (flag != null && !isTruthy(flag)) {
+    Log.debug("TINA4_AUTO_MIGRATE is off — skipping startup migrations");
+    return;
+  }
+
+  // Gate 3: a DB adapter must be resolvable. (initDatabase() has already run by
+  // the time this is called from startServer.)
+  let orm: typeof import("../../orm/src/index.js");
+  try {
+    orm = await import("../../orm/src/index.js");
+    orm.getAdapter(); // throws if no adapter configured
+  } catch (err) {
+    Log.debug(`Startup migrations skipped (no database configured): ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+
+  // Run the EXISTING migrate runner inside try/catch — NEVER re-raise out of
+  // the startup hook (non-breaking).
+  try {
+    const result = await orm.migrate(undefined, { migrationsDir: dir });
+    if (result.applied.length > 0) {
+      Log.info(`Applied ${result.applied.length} pending migration(s) on startup`);
+    }
+  } catch (err) {
+    Log.error(
+      `Startup auto-migration failed: ${err instanceof Error ? err.message : String(err)} — ` +
+      "the service is starting anyway. Run `tina4 migrate` to retry.",
+    );
+  }
+}
+
 /** Read version from root package.json so the banner always matches the published version. */
 function readPackageVersion(): string {
   try {
@@ -117,8 +183,13 @@ export function _checkLegacyEnvVars(): void {
   }
   lines.push(
     "",
-    "Run `tina4 env --migrate` to rewrite your .env automatically,",
-    "or rename manually. See https://tina4.com/release/3.12.0",
+    "Note: these may come from a .env file loaded by dotenv, not just",
+    "the runtime environment — check your image / build context (a .env",
+    "baked into a Docker image is loaded at startup) as well as k8s/CI env.",
+    "",
+    "FIX: run `tina4 env --migrate` to rewrite your .env automatically",
+    "(it renames every legacy name to its TINA4_ form in place).",
+    "Or rename manually. See https://tina4.com/release/3.12.0",
     "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
     bar,
     "",
@@ -884,6 +955,12 @@ ${reset}
     } catch (err) {
       console.warn(`\n  ORM not available (install @tina4/orm to enable):`, err);
     }
+
+    // Auto-run pending migrations on startup — AFTER initDatabase()/model sync,
+    // BEFORE the server listens. Non-breaking: a failure is logged and boot
+    // continues (the helper never throws). Gated on a migrations/ dir + the
+    // TINA4_AUTO_MIGRATE flag (default on) + a resolvable DB adapter.
+    await autoMigrateOnStartup("migrations", base);
   }
 
   // Initialize Swagger — gated on TINA4_SWAGGER_ENABLED (default: enabled
@@ -1415,31 +1492,52 @@ ${reset}
   // posts /__dev/api/reload to the MAIN port. Matches Python (master).
   const server = createServer(dispatch);
 
-  // WebSocket-primary DevReload: accept and hold /__dev_reload upgrades on the
-  // MAIN port (debug only) so POST /__dev/api/reload can push an instant reload.
-  // Mirrors Python's _register_dev_reload_ws + _ws_manager.broadcast(path=…).
-  // Without this the handshake 404s and the whole stack silently falls back to
-  // polling. Track connections in WsTracker so they appear in the dev-admin list.
+  // WebSocket upgrade handling on the MAIN port. Two responsibilities:
+  //
+  //  1. WebSocket-primary DevReload (debug only): accept and hold /__dev_reload
+  //     upgrades so POST /__dev/api/reload can push an instant reload. Mirrors
+  //     Python's _register_dev_reload_ws + _ws_manager.broadcast(path=…).
+  //
+  //  2. USER WS ROUTES (always): a route registered via Router.websocket() /
+  //     WebSocketServer.route() is dispatched to a live open/message/close
+  //     lifecycle on the real connection — parity with Python/PHP/Ruby. Per-route
+  //     auth is enforced here on the upgrade (serveWebSocketRoute): a @secured /
+  //     .secure() route rejects a missing/invalid JWT before accepting; public
+  //     routes pass. Previously the integrated server only handled /__dev_reload,
+  //     so user WS routes never reached a live connection.
+  //
+  // Tracking goes through WsTracker so connections show in the dev-admin list.
   if (isDevMode()) {
     devReloadWs.setTracker(
       (remoteAddress, p) => WsTracker.add(remoteAddress, p),
       (id) => { WsTracker.remove(id); },
     );
-    server.on("upgrade", (req: IncomingMessage, socket: Socket, head: Buffer) => {
-      const upPath = (req.url ?? "/").split("?")[0];
-      if (upPath === "/__dev_reload") {
-        devReloadWs.handleUpgrade(req, socket, head);
-        return;
-      }
-      // Not a dev-reload upgrade — refuse cleanly rather than leaving it hanging.
-      try {
-        socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
-        socket.destroy();
-      } catch {
-        /* socket already gone */
-      }
-    });
+    wsRouteManager.setTracker(
+      (remoteAddress, p) => WsTracker.add(remoteAddress, p),
+      (id) => { WsTracker.remove(id); },
+    );
   }
+  server.on("upgrade", (req: IncomingMessage, socket: Socket, head: Buffer) => {
+    const upPath = (req.url ?? "/").split("?")[0];
+    // Dev-reload channel (debug only).
+    if (isDevMode() && upPath === "/__dev_reload") {
+      devReloadWs.handleUpgrade(req, socket, head);
+      return;
+    }
+    // User-registered WS route — enforces per-route auth, then drives the
+    // open/message/close lifecycle on this connection. Returns false only when
+    // no WS route matches this path.
+    if (serveWebSocketRoute(req, socket, head)) {
+      return;
+    }
+    // No dev-reload and no matching user route — refuse cleanly.
+    try {
+      socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+      socket.destroy();
+    } catch {
+      /* socket already gone */
+    }
+  });
 
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {

package/packages/core/src/sessionHandlers/mongoHandler.ts

@@ -66,8 +66,10 @@ export class MongoSessionHandler implements SessionHandler {
       ?? (process.env.TINA4_SESSION_MONGO_PORT
         ? parseInt(process.env.TINA4_SESSION_MONGO_PORT, 10)
         : 27017);
+    // Canonical TINA4_SESSION_MONGO_URI; TINA4_SESSION_MONGO_URL is a legacy alias.
     this.uri = config?.uri
       ?? process.env.TINA4_SESSION_MONGO_URI
+      ?? process.env.TINA4_SESSION_MONGO_URL
       ?? "";
     this.username = config?.username
       ?? process.env.TINA4_SESSION_MONGO_USERNAME

package/packages/core/src/types.ts

@@ -134,6 +134,10 @@ export interface RouteMeta {
   description?: string;
   tags?: string[];
   responses?: Record<string, { description: string }>;
+  /** Request-body example surfaced in the OpenAPI requestBody. */
+  example?: unknown;
+  /** Marks the operation deprecated in the spec. */
+  deprecated?: boolean;
 }
 
 export interface Tina4Config {
@@ -179,13 +183,28 @@ export type MiddlewareSpec = Middleware | string;
  * event — one of "open", "message", or "close".
  * data — the incoming text message (only present for "message" events).
  */
-export type WebSocketRouteHandler = (
+export type WebSocketRouteHandler = ((
   connection: import("./websocketConnection.js").WebSocketConnection,
   event: "open" | "message" | "close",
   data: string,
-) => void | Promise<void>;
+) => void | Promise<void>) & {
+  /**
+   * Decorator-style secured flag — mirrors Python's `handler._secured`. When
+   * truthy the WS route requires a valid JWT on the upgrade. `Router.websocket`
+   * reads this into the route's `authRequired`. Lets a handler be marked
+   * secured in EITHER order (before or after registration).
+   */
+  _secured?: boolean;
+};
 
 export interface WebSocketRouteDefinition {
   pattern: string;
   handler: WebSocketRouteHandler;
+  /**
+   * True when this WS route requires a valid JWT on the upgrade. Public by
+   * default (mirrors GET). Set imperatively via `Router.websocket(path, fn,
+   * { secured: true })` / the returned `.secure()`, or by a `_secured` flag on
+   * the handler (decorator style).
+   */
+  authRequired?: boolean;
 }