tina4-nodejs 3.13.37 → 3.13.39

package/packages/core/src/websocketBackplane.ts

@@ -16,6 +16,7 @@
  *     backplane.publish("chat", '{"user":"A","text":"hello"}');
  *   }
  */
+import { randomUUID } from "node:crypto";
 
 /**
  * Base interface for scaling WebSocket broadcast across instances.
@@ -51,12 +52,16 @@ export class RedisBackplane implements WebSocketBackplane {
   private ready: Promise<void>;
 
   constructor(url?: string) {
-    this.url = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "redis://localhost:6379";
+    const resolvedUrl = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "redis://localhost:6379";
+    this.url = resolvedUrl;
 
     this.ready = (async () => {
       let redis: any;
       try {
-        redis = await import("redis");
+        // Optional peer dependency — resolved via a string specifier so the
+        // module isn't required at type-check time when it isn't installed.
+        const redisModule: string = "redis";
+        redis = await import(redisModule);
       } catch {
         throw new Error(
           "The 'redis' package is required for RedisBackplane. " +
@@ -64,14 +69,14 @@ export class RedisBackplane implements WebSocketBackplane {
         );
       }
 
-      this.publisher = redis.createClient({ url: this.url });
+      this.publisher = redis.createClient({ url: resolvedUrl });
       this.subscriber = this.publisher.duplicate();
 
       await Promise.all([
         this.publisher.connect(),
         this.subscriber.connect(),
       ]);
-      console.log(`[Tina4] RedisBackplane connected to ${this.url}`);
+      console.log(`[Tina4] RedisBackplane connected to ${resolvedUrl}`);
     })();
   }
 
@@ -115,12 +120,16 @@ export class NATSBackplane implements WebSocketBackplane {
   private ready: Promise<void>;
 
   constructor(url?: string) {
-    this.url = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "nats://localhost:4222";
+    const resolvedUrl = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "nats://localhost:4222";
+    this.url = resolvedUrl;
 
     this.ready = (async () => {
       let nats: any;
       try {
-        nats = await import("nats");
+        // Optional peer dependency — resolved via a string specifier so the
+        // module isn't required at type-check time when it isn't installed.
+        const natsModule: string = "nats";
+        nats = await import(natsModule);
       } catch {
         throw new Error(
           "The 'nats' package is required for NATSBackplane. " +
@@ -128,21 +137,23 @@ export class NATSBackplane implements WebSocketBackplane {
         );
       }
 
-      this.nc = await nats.connect({ servers: this.url });
-      console.log(`[Tina4] NATSBackplane connected to ${this.url}`);
+      this.nc = await nats.connect({ servers: resolvedUrl });
+      console.log(`[Tina4] NATSBackplane connected to ${resolvedUrl}`);
     })();
   }
 
   async publish(channel: string, message: string): Promise<void> {
     await this.ready;
-    const { StringCodec } = await import("nats");
+    const natsModule: string = "nats";
+    const { StringCodec } = await import(natsModule);
     const sc = StringCodec();
     this.nc.publish(channel, sc.encode(message));
   }
 
   async subscribe(channel: string, callback: (message: string) => void): Promise<void> {
     await this.ready;
-    const { StringCodec } = await import("nats");
+    const natsModule: string = "nats";
+    const { StringCodec } = await import(natsModule);
     const sc = StringCodec();
     const sub = this.nc.subscribe(channel);
     this.subs.set(channel, sub);
@@ -197,3 +208,192 @@ export function createBackplane(url?: string): WebSocketBackplane | null {
       throw new Error(`Unknown TINA4_WS_BACKPLANE value: '${backend}'`);
   }
 }
+
+// ── Multi-instance scaling (backplane manager) ───────────────
+
+/**
+ * The shared pub/sub channel name. Identical across all four Tina4 frameworks
+ * (cross-framework constant parity) so a Python, PHP, Ruby and Node instance
+ * can all relay each other's broadcasts over the same bus.
+ */
+export const WS_BACKPLANE_CHANNEL = "tina4:ws";
+
+/** What `kind` a broadcast envelope carries — mirrors the master design. */
+export type WsEnvelopeKind = "all" | "path" | "room";
+
+/**
+ * The JSON envelope published to the backplane channel. The wire shape is
+ * identical across all four frameworks. JSON can't carry bytes, so a string
+ * message rides under `text` and a binary message rides under `b64`
+ * (base64 of the bytes).
+ */
+export interface WsEnvelope {
+  /** Stable per-process instance id of the publisher (for the origin guard). */
+  src: string;
+  /** Delivery kind: every local conn / a path / a room. */
+  kind: WsEnvelopeKind;
+  /** Optional connection id to skip on delivery. */
+  exclude?: string | null;
+  /** Room name (only when kind === "room"). */
+  room?: string | null;
+  /** Path (only when kind === "path"). */
+  path?: string | null;
+  /** Text payload (str messages). */
+  text?: string;
+  /** Base64 payload (binary messages). */
+  b64?: string;
+}
+
+/**
+ * Wires a {@link WebSocketBackplane} into a local connection manager so a
+ * broadcast on one server instance reaches the local connections of every
+ * sibling instance.
+ *
+ * Node is single-threaded async, so — unlike Python's bg-thread →
+ * `run_coroutine_threadsafe` bridge — the subscribe callback can relay
+ * directly on the event loop. We still apply the two invariants that keep a
+ * cluster correct:
+ *
+ *   1. **Origin guard** — drop any envelope whose `src` is *this* instance's
+ *      id. We already delivered it locally on broadcast; relaying it again
+ *      would double-send.
+ *   2. **No re-publish** — the relay path only delivers to LOCAL connections;
+ *      it never publishes, so a message can't loop around the cluster.
+ *
+ * The manager is generic over the local-delivery callback (`relay`) so it can
+ * sit beside the WebSocketServer without importing it (no module cycle).
+ */
+export class WsBackplaneManager {
+  /** Stable per-process id so we can ignore our own echoes. */
+  readonly instanceId: string;
+  readonly channel: string;
+  private backplane: WebSocketBackplane | null = null;
+  private started = false;
+  /** Local-delivery callback, installed by the owner (WebSocketServer). */
+  private relay: ((env: WsEnvelope) => void) | null = null;
+
+  constructor(channel: string = WS_BACKPLANE_CHANNEL) {
+    this.instanceId = randomInstanceId();
+    this.channel = channel;
+  }
+
+  /** True once a backplane is actually attached (a network bus is configured). */
+  get active(): boolean {
+    return this.backplane !== null;
+  }
+
+  /**
+   * Lazily wire the configured backplane and subscribe. Idempotent and
+   * best-effort — a failure here logs and leaves the manager in local-only
+   * mode; it must NEVER crash a broadcast. The `relay` callback is invoked
+   * (on this same event loop) for every *remote* envelope that survives the
+   * origin guard.
+   */
+  async ensure(relay: (env: WsEnvelope) => void, log?: WsBackplaneLogger): Promise<void> {
+    if (this.started) return;
+    // Set immediately so we only ever attempt the wiring once, even if it
+    // fails (no retry storm on every broadcast).
+    this.started = true;
+    this.relay = relay;
+    try {
+      const backplane = createBackplane();
+      if (backplane === null) return; // No backplane configured — stay local-only.
+      this.backplane = backplane;
+      await backplane.subscribe(this.channel, (raw) => this.onMessage(raw));
+      log?.info(
+        `WebSocket backplane active (instance ${this.instanceId}, channel '${this.channel}')`,
+      );
+    } catch (err) {
+      this.backplane = null;
+      log?.error(
+        `WebSocket backplane wiring failed, continuing local-only: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * Handle a raw envelope arriving on the channel. Applies the origin guard
+   * then hands a *remote* envelope to the local relay. Never throws (a
+   * malformed envelope is dropped silently).
+   */
+  onMessage(raw: string): void {
+    let env: unknown;
+    try {
+      env = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (typeof env !== "object" || env === null) return;
+    const envelope = env as WsEnvelope;
+    // Origin guard: ignore our own broadcasts echoed back over the channel.
+    // We already delivered them locally; relaying again would double-send.
+    if (envelope.src === this.instanceId) return;
+    this.relay?.(envelope);
+  }
+
+  /**
+   * Publish a broadcast to the shared channel for sibling instances. No-op
+   * when no backplane is configured. Best-effort — a publish failure logs and
+   * is swallowed so the local broadcast that already happened is never undone
+   * by a flaky message bus.
+   */
+  publish(
+    kind: WsEnvelopeKind,
+    message: string | Buffer,
+    opts: { room?: string | null; path?: string | null; exclude?: string | null } = {},
+    log?: WsBackplaneLogger,
+  ): void {
+    if (!this.backplane) return;
+    const envelope = buildEnvelope(this.instanceId, kind, message, opts);
+    // publish() is async; we fire-and-forget but still catch a rejection so a
+    // dead bus can't produce an unhandled rejection that crashes the worker.
+    Promise.resolve(this.backplane.publish(this.channel, JSON.stringify(envelope))).catch(
+      (err) => log?.warn(`WebSocket backplane publish failed: ${(err as Error).message}`),
+    );
+  }
+
+  /**
+   * Reconstruct the original str/Buffer message from an envelope. JSON can't
+   * carry bytes, so `text` → string and `b64` → Buffer.
+   */
+  static decodeMessage(env: WsEnvelope): string | Buffer | null {
+    if (typeof env.text === "string") return env.text;
+    if (typeof env.b64 === "string") return Buffer.from(env.b64, "base64");
+    return null;
+  }
+}
+
+/** Minimal logger shape so the manager doesn't import the logger module. */
+export interface WsBackplaneLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+/** Build the cross-framework envelope. Exported for tests. */
+export function buildEnvelope(
+  src: string,
+  kind: WsEnvelopeKind,
+  message: string | Buffer,
+  opts: { room?: string | null; path?: string | null; exclude?: string | null } = {},
+): WsEnvelope {
+  const envelope: WsEnvelope = {
+    src,
+    kind,
+    exclude: opts.exclude ?? null,
+    room: opts.room ?? null,
+    path: opts.path ?? null,
+  };
+  // JSON can't carry bytes — encode a string as text, bytes as base64.
+  if (Buffer.isBuffer(message)) {
+    envelope.b64 = message.toString("base64");
+  } else {
+    envelope.text = message;
+  }
+  return envelope;
+}
+
+/** A stable, short per-process id (16 hex chars), matching the master. */
+function randomInstanceId(): string {
+  return randomUUID().replace(/-/g, "").slice(0, 16);
+}

package/packages/core/src/websocketConnection.ts

@@ -13,6 +13,12 @@ export interface WebSocketConnection {
   headers: Record<string, string>;
   /** Route parameters extracted from `{param}` segments in the path */
   params: Record<string, string>;
+  /**
+   * Verified JWT payload on a `@secured` / `.secure()` WebSocket route, or
+   * `null` on a public route (the default). Set on the upgrade after the token
+   * is validated — mirrors Python's `connection.auth`.
+   */
+  auth: Record<string, unknown> | null;
   /** Send a message to this connection only */
   send(message: string): void;
   /** Serialize an object to JSON and send it to this connection. Parity with Python/PHP. */

package/packages/core/src/wsdl.ts

@@ -19,6 +19,9 @@
  *   }
  */
 
+import { Log } from "./logger.js";
+import { isDebugMode } from "./errorOverlay.js";
+
 // ── Types ────────────────────────────────────────────────────
 
 export interface WSDLOperationMeta {
@@ -261,13 +264,27 @@ export abstract class WSDLService {
   private convertValue(value: string, typeName: string): unknown {
     switch (typeName) {
       case "int":
-      case "integer":
-        return parseInt(value, 10);
+      case "integer": {
+        // Match Python's int(value) — a non-numeric value RAISES rather than
+        // silently yielding NaN. The thrown Error is caught in handle() and
+        // becomes a Server fault.
+        const n = parseInt(value, 10);
+        if (Number.isNaN(n)) {
+          throw new Error(`invalid integer value: ${JSON.stringify(value)}`);
+        }
+        return n;
+      }
       case "float":
       case "double":
       case "number":
-      case "numeric":
-        return parseFloat(value);
+      case "numeric": {
+        // Match Python's float(value) — non-numeric raises (→ Server fault).
+        const f = parseFloat(value);
+        if (Number.isNaN(f)) {
+          throw new Error(`invalid numeric value: ${JSON.stringify(value)}`);
+        }
+        return f;
+      }
       case "bool":
       case "boolean":
         return ["true", "1", "yes"].includes(value.toLowerCase());
@@ -389,6 +406,16 @@ export abstract class WSDLService {
   async handle(soapXml: string = ""): Promise<string> {
     const ops = this.discoverOperations();
 
+    // SOAP 1.1 (§3) forbids a Document Type Declaration in a SOAP message.
+    // Rejecting any DOCTYPE/DTD up front — BEFORE the body is parsed — also
+    // closes the XML entity-expansion (billion-laughs) and external-entity
+    // (XXE) attack surface regardless of parser internals. The operation
+    // never runs. (Node's parser is hand-rolled and already immune; this is
+    // defence in depth + consistent fault behaviour across all 4 frameworks.)
+    if (/<!DOCTYPE/i.test(soapXml)) {
+      return this.soapFault("Client", "DOCTYPE declarations are not allowed in SOAP messages");
+    }
+
     // Parse SOAP body
     const body = extractSoapBody(soapXml);
     if (!body) {
@@ -413,33 +440,40 @@ export abstract class WSDLService {
       return this.soapFault("Client", `Operation not implemented: ${opName}`);
     }
 
-    // Extract parameters from the operation element
-    const children = extractChildren(operation.content);
-    const params: unknown[] = [];
-
-    if (opMeta.input) {
-      for (const [paramName, paramType] of Object.entries(opMeta.input)) {
-        const child = children.find((c) => c.name === paramName);
-        if (child) {
-          params.push(this.convertValue(child.value, paramType));
-        } else {
-          params.push(null);
-        }
-      }
-    }
-
     // Lifecycle hook: before invocation
     this.onRequest(soapXml);
 
-    // Invoke the method
+    // Invoke the method. Parameter conversion runs INSIDE the try so a
+    // non-numeric value for an int/float param (convertValue throws, matching
+    // Python's int()/float() raise) becomes a Server fault — not a silent NaN.
     try {
+      // Extract parameters from the operation element
+      const children = extractChildren(operation.content);
+      const params: unknown[] = [];
+
+      if (opMeta.input) {
+        for (const [paramName, paramType] of Object.entries(opMeta.input)) {
+          const child = children.find((c) => c.name === paramName);
+          if (child) {
+            params.push(this.convertValue(child.value, paramType));
+          } else {
+            params.push(null);
+          }
+        }
+      }
+
       const rawResult = await (method as (...args: unknown[]) => Promise<unknown>).call(this, ...params);
       // Lifecycle hook: after invocation — allow result transformation
       const result = this.onResult(rawResult as Record<string, unknown>);
       return this.soapResponse(opName, result);
     } catch (err) {
+      // Log the real cause, but only leak the detail to the client in debug
+      // mode — a resolver exception can carry internal state (DB credentials,
+      // file paths) that must not reach a SOAP client.
       const errMsg = err instanceof Error ? err.message : String(err);
-      return this.soapFault("Server", errMsg);
+      Log.error(`WSDL operation '${opName}' failed: ${errMsg}`);
+      const detail = isDebugMode() ? errMsg : "Internal server error";
+      return this.soapFault("Server", detail);
     }
   }
 

package/packages/orm/src/adapters/pg-types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Minimal ambient type surface for the optional `pg` (node-postgres) peer
+ * dependency. `@types/pg` is intentionally NOT a dependency (pg is an optional
+ * peer loaded lazily via createRequire), so without this declaration the
+ * `typeof import("pg")` references in postgres.ts resolve to an *implicit* any
+ * (TS7016) and collapse `this.client` to `never`.
+ *
+ * This declares only the subset of the pg API that the PostgresAdapter uses:
+ * the `Client` class (connect/query/end) and the global `types.setTypeParser`
+ * registry. It carries no runtime weight — purely a compile-time contract that
+ * matches node-postgres' real shape.
+ */
+declare module "pg" {
+  export interface QueryResultRow {
+    [column: string]: unknown;
+  }
+
+  export interface QueryResult<R extends QueryResultRow = QueryResultRow> {
+    rows: R[];
+    rowCount: number | null;
+    command: string;
+    oid: number;
+    fields: unknown[];
+  }
+
+  export interface ClientConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+  }
+
+  export class Client {
+    constructor(config?: ClientConfig | string);
+    connect(): Promise<void>;
+    query<R extends QueryResultRow = QueryResultRow>(
+      queryText: string,
+      values?: unknown[],
+    ): Promise<QueryResult<R>>;
+    end(): Promise<void>;
+  }
+
+  export class Pool {
+    constructor(config?: ClientConfig | string);
+    connect(): Promise<Client>;
+    query<R extends QueryResultRow = QueryResultRow>(
+      queryText: string,
+      values?: unknown[],
+    ): Promise<QueryResult<R>>;
+    end(): Promise<void>;
+  }
+
+  export interface TypeParsers {
+    setTypeParser(oid: number, parseFn: (value: string) => unknown): void;
+  }
+
+  export const types: TypeParsers;
+}

package/packages/orm/src/adapters/postgres.ts

@@ -86,7 +86,13 @@ export class PostgresAdapter implements DatabaseAdapter {
     await this.client!.connect();
   }
 
-  private ensureConnected(): asserts this is { client: NonNullable<PostgresAdapter["client"]> } {
+  // NOTE: a plain runtime guard, not an `asserts this is ...` predicate. A
+  // type-narrowing predicate that re-declares the private `client` member
+  // intersects the class with a structural literal and collapses `this` to
+  // `never` (TS treats the private brand as unsatisfiable). The non-null
+  // `this.client!` assertions at the (already-guarded) call sites carry the
+  // narrowing instead, so behaviour is unchanged.
+  private ensureConnected(): void {
     if (!this.client) {
       throw new Error("PostgreSQL adapter not connected. Call connect() first.");
     }
@@ -107,6 +113,22 @@ export class PostgresAdapter implements DatabaseAdapter {
     });
   }
 
+  /**
+   * Normalise an `id` column value (typed `unknown` because pg row values are
+   * `unknown`) into the `number | bigint | null` shape `_lastInsertId` /
+   * `DatabaseResult.lastInsertId` expect. At runtime PG returns numeric PKs as
+   * number/bigint (the int8/numeric type parsers above coerce them to Number);
+   * a numeric string is coerced, anything else (null/undefined/non-numeric)
+   * becomes null.
+   */
+  private normalizeId(value: unknown): number | bigint | null {
+    if (typeof value === "number" || typeof value === "bigint") return value;
+    if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+    return null;
+  }
+
   execute(sql: string, params?: unknown[]): unknown {
     this.ensureConnected();
     const convertedSql = this.convertPlaceholders(sql);
@@ -139,7 +161,7 @@ export class PostgresAdapter implements DatabaseAdapter {
     const convertedSql = this.convertPlaceholders(sql);
     const result = await this.client!.query(convertedSql, params);
     if (result.rows?.[0]?.id !== undefined) {
-      this._lastInsertId = result.rows[0].id;
+      this._lastInsertId = this.normalizeId(result.rows[0].id);
     }
     return result;
   }
@@ -194,12 +216,12 @@ export class PostgresAdapter implements DatabaseAdapter {
     try {
       const result = await this.client!.query(sql, values);
       const insertedRow = result.rows[0];
-      const id = insertedRow?.id ?? null;
+      const id = this.normalizeId(insertedRow?.id);
       if (id !== null) this._lastInsertId = id;
       return {
         success: true,
         rowsAffected: result.rowCount ?? 1,
-        lastInsertId: id,
+        lastInsertId: id ?? undefined,
       };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };