@memberjunction/server 5.47.0 → 5.49.0

package/src/realtimeProxy/RealtimeProxyServer.ts

@@ -0,0 +1,265 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocket as WsClient, WebSocketServer, type RawData } from 'ws';
+import { BaseSingleton, ShutdownRegistry, type IShutdownable } from '@memberjunction/global';
+import { RealtimeProxyRegistry, REALTIME_PROXY_PATH, type RealtimeProxyTicketEntry } from '@memberjunction/ai';
+
+/**
+ * MJAPI's realtime websocket **proxy** — the transport half of the self-hosted realtime provider story.
+ *
+ * A provider driver (e.g. `HuggingFaceRealtime`) mints a one-time ticket into the shared
+ * {@link RealtimeProxyRegistry} pointing at an INTERNAL realtime endpoint, and hands the browser a
+ * `wss://<mjapi-public>{REALTIME_PROXY_PATH}?ticket=<id>` URL. The browser opens its socket HERE; this
+ * proxy consumes the ticket, opens the authenticated upstream leg (injecting any auth server-side), and
+ * pumps frames transparently in both directions. The internal endpoint + auth never reach the browser,
+ * and the internal box needs no browser-facing ingress — MJAPI stays the single ingress point.
+ *
+ * Deliberately provider-agnostic: it does no protocol translation (the same-keyed client driver owns the
+ * wire vocabulary) and knows nothing about any specific provider — it is a pure authenticated byte tunnel,
+ * reusable by any future self-hosted realtime provider that mints a ticket.
+ *
+ * A {@link BaseSingleton} + {@link IShutdownable}: it tracks live tunnels and closes them on graceful
+ * shutdown (drained by MJServer's `ShutdownRegistry` before `httpServer.close()`).
+ */
+export class RealtimeProxyServer extends BaseSingleton<RealtimeProxyServer> implements IShutdownable {
+    public readonly ShutdownName = 'RealtimeProxyServer';
+
+    /** `noServer` so THIS server never binds its own upgrade listener — MJServer routes upgrades to it by path. */
+    private readonly wss = new WebSocketServer({ noServer: true });
+
+    /** Live browser↔upstream tunnels, tracked for shutdown teardown. */
+    private readonly tunnels = new Set<RealtimeProxyTunnel>();
+
+    private registered = false;
+
+    protected constructor() {
+        super();
+    }
+
+    /** Process-wide singleton accessor. */
+    public static get Instance(): RealtimeProxyServer {
+        return super.getInstance<RealtimeProxyServer>();
+    }
+
+    /**
+     * Routes an HTTP `upgrade` for {@link REALTIME_PROXY_PATH} to the proxy. Returns `true` when it OWNS
+     * (handled/rejected) the request, `false` when the path is not the proxy's — so the caller leaves the
+     * socket for the GraphQL websocket server's own upgrade listener. NEVER destroys a socket it doesn't own.
+     */
+    public TryHandleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): boolean {
+        const url = RealtimeProxyServer.parseUrl(request.url);
+        if (!url || url.pathname !== REALTIME_PROXY_PATH) {
+            return false; // not ours — leave it for the GraphQL WS server
+        }
+        this.ensureRegistered();
+        // Optional Origin allowlist (MJ_REALTIME_PROXY_ALLOWED_ORIGINS: comma-separated origins).
+        // Unset ⇒ prior behavior (the single-use short-TTL ticket remains the primary guard);
+        // set ⇒ a browser page on a foreign origin cannot ride a leaked ticket id.
+        if (!RealtimeProxyServer.originAllowed(request.headers?.origin)) {
+            RealtimeProxyServer.rejectUpgrade(socket, 403, 'Forbidden');
+            return true;
+        }
+        const ticketId = url.searchParams.get('ticket') ?? '';
+        const entry = RealtimeProxyRegistry.Instance.Consume(ticketId);
+        if (!entry) {
+            RealtimeProxyServer.rejectUpgrade(socket, 401, 'Unauthorized');
+            return true;
+        }
+        this.wss.handleUpgrade(request, socket, head, (browserWs) => this.openTunnel(browserWs, entry));
+        return true;
+    }
+
+    /**
+     * Evaluates the optional Origin allowlist. Comparison is exact on the normalized origin
+     * (scheme://host[:port], lowercased, no trailing slash). An upgrade WITHOUT an Origin header
+     * (non-browser client, e.g. a native app or test rig) passes — the allowlist targets
+     * cross-origin BROWSER pages, which always send the header.
+     *
+     * @param origin The upgrade request's Origin header, if any.
+     * @returns True when allowed (or no allowlist is configured).
+     */
+    private static originAllowed(origin: string | undefined): boolean {
+        const raw = process.env['MJ_REALTIME_PROXY_ALLOWED_ORIGINS'];
+        if (!raw || raw.trim().length === 0) {
+            return true; // no allowlist configured — prior behavior
+        }
+        if (!origin) {
+            return true; // non-browser upgrade (no Origin header) — tickets remain the guard
+        }
+        const normalize = (value: string): string => value.trim().toLowerCase().replace(/\/+$/, '');
+        const allowed = raw.split(',').map(normalize).filter((v) => v.length > 0);
+        return allowed.includes(normalize(origin));
+    }
+
+    /** Opens the upstream leg and wires a bidirectional pump between the browser socket and it. */
+    private openTunnel(browserWs: WsClient, entry: RealtimeProxyTicketEntry): void {
+        const tunnel = new RealtimeProxyTunnel(browserWs, entry, () => this.tunnels.delete(tunnel));
+        this.tunnels.add(tunnel);
+        tunnel.Start();
+    }
+
+    /** Registers for graceful-shutdown draining exactly once (lazily, on first real use). */
+    private ensureRegistered(): void {
+        if (!this.registered) {
+            ShutdownRegistry.Instance.Register(this);
+            this.registered = true;
+        }
+    }
+
+    /** Closes every live tunnel and the proxy server. Idempotent; never throws. */
+    public Shutdown(): void {
+        for (const tunnel of [...this.tunnels]) {
+            tunnel.Close();
+        }
+        this.tunnels.clear();
+        try {
+            this.wss.close();
+        } catch {
+            /* already closing */
+        }
+    }
+
+    /** Parses `request.url` (a path+query) into a URL, or `null` when absent/unparseable. */
+    private static parseUrl(rawUrl: string | undefined): URL | null {
+        if (!rawUrl) {
+            return null;
+        }
+        try {
+            return new URL(rawUrl, 'http://internal'); // base is only for parsing path+query
+        } catch {
+            return null;
+        }
+    }
+
+    /** Writes a minimal HTTP error response and destroys the socket (used for a rejected upgrade). */
+    private static rejectUpgrade(socket: Duplex, code: number, reason: string): void {
+        try {
+            socket.write(`HTTP/1.1 ${code} ${reason}\r\nConnection: close\r\n\r\n`);
+        } catch {
+            /* socket already gone */
+        }
+        socket.destroy();
+    }
+}
+
+/**
+ * One live browser↔upstream tunnel. Buffers browser→upstream frames until the upstream socket is open,
+ * then pumps both directions byte-transparently (text and binary alike). Closing either side closes the other.
+ */
+class RealtimeProxyTunnel {
+    /** How long the upstream websocket may take to OPEN before the tunnel is torn down (ms). */
+    private static readonly UPSTREAM_OPEN_TIMEOUT_MS = 15_000;
+    /**
+     * Cap on frames buffered browser→upstream before the upstream opens. A half-connected
+     * upstream (TCP accepted, WS handshake never completes) must not let a browser streaming PCM
+     * grow an unbounded in-memory array on MJAPI; past the cap the OLDEST frames are dropped
+     * (voice frames are perishable — late delivery of stale audio is worthless anyway).
+     */
+    private static readonly MAX_PENDING_FRAMES = 512;
+
+    private upstream: WsClient | null = null;
+    /** Frames the browser sent before the upstream opened; flushed in order once it's ready. */
+    private readonly pending: Array<{ data: RawData; isBinary: boolean }> = [];
+    private openDeadline: ReturnType<typeof setTimeout> | null = null;
+    private droppedPendingFrames = 0;
+    private closed = false;
+
+    constructor(
+        private readonly browser: WsClient,
+        private readonly entry: RealtimeProxyTicketEntry,
+        private readonly onClosed: () => void
+    ) {}
+
+    /** Opens the upstream socket and wires both legs. */
+    public Start(): void {
+        const headers = this.entry.UpstreamAuthHeader ? { Authorization: this.entry.UpstreamAuthHeader } : undefined;
+        const upstream = new WsClient(this.entry.UpstreamUrl, { headers });
+        this.upstream = upstream;
+
+        // Deadline: an upstream that accepts TCP but never completes the WS handshake would
+        // otherwise hold the tunnel (and its buffer) open forever.
+        this.openDeadline = setTimeout(() => {
+            this.openDeadline = null;
+            if (!this.closed && upstream.readyState !== WsClient.OPEN) {
+                console.warn(`[RealtimeProxy] upstream did not open within ${RealtimeProxyTunnel.UPSTREAM_OPEN_TIMEOUT_MS}ms — closing tunnel`);
+                this.Close();
+            }
+        }, RealtimeProxyTunnel.UPSTREAM_OPEN_TIMEOUT_MS);
+        (this.openDeadline as { unref?: () => void }).unref?.();
+
+        upstream.on('open', () => {
+            if (this.openDeadline) {
+                clearTimeout(this.openDeadline);
+                this.openDeadline = null;
+            }
+            this.flushPending();
+        });
+        upstream.on('message', (data: RawData, isBinary: boolean) => this.forward(this.browser, data, isBinary));
+        upstream.on('close', () => this.Close());
+        upstream.on('error', () => this.Close());
+
+        this.browser.on('message', (data: RawData, isBinary: boolean) => this.fromBrowser(data, isBinary));
+        this.browser.on('close', () => this.Close());
+        this.browser.on('error', () => this.Close());
+    }
+
+    /** Browser→upstream: forward immediately when the upstream is open, else queue until it is. */
+    private fromBrowser(data: RawData, isBinary: boolean): void {
+        if (this.upstream && this.upstream.readyState === WsClient.OPEN) {
+            this.forward(this.upstream, data, isBinary);
+        } else {
+            this.pending.push({ data, isBinary });
+            if (this.pending.length > RealtimeProxyTunnel.MAX_PENDING_FRAMES) {
+                this.pending.shift(); // drop-oldest: stale voice frames are worthless anyway
+                this.droppedPendingFrames++;
+                if (this.droppedPendingFrames === 1 || this.droppedPendingFrames % 100 === 0) {
+                    console.warn(`[RealtimeProxy] pre-open buffer cap hit — dropped ${this.droppedPendingFrames} oldest frame(s) awaiting upstream open`);
+                }
+            }
+        }
+    }
+
+    /** Drains any frames queued before the upstream opened. */
+    private flushPending(): void {
+        if (!this.upstream) {
+            return;
+        }
+        for (const frame of this.pending) {
+            this.forward(this.upstream, frame.data, frame.isBinary);
+        }
+        this.pending.length = 0;
+    }
+
+    /** Sends one frame on a socket, preserving the text/binary distinction; failures close the tunnel. */
+    private forward(target: WsClient, data: RawData, isBinary: boolean): void {
+        if (target.readyState !== WsClient.OPEN) {
+            return;
+        }
+        try {
+            target.send(data, { binary: isBinary });
+        } catch {
+            this.Close();
+        }
+    }
+
+    /** Closes both legs and detaches the tunnel from the server. Idempotent. */
+    public Close(): void {
+        if (this.openDeadline) {
+            clearTimeout(this.openDeadline);
+            this.openDeadline = null;
+        }
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.pending.length = 0;
+        for (const sock of [this.browser, this.upstream]) {
+            try {
+                sock?.close();
+            } catch {
+                /* already closing */
+            }
+        }
+        this.onClosed();
+    }
+}

package/src/realtimeWidget/WidgetRouter.ts

@@ -11,7 +11,7 @@
  */
 
 import { Router, json, type Request, type Response } from 'express';
-import { rateLimit } from 'express-rate-limit';
+import { rateLimit, ipKeyGenerator } from 'express-rate-limit';
 import { LogStatus } from '@memberjunction/core';
 import { configInfo, type WidgetConfig } from '../config.js';
 import { MagicLinkKeyManager } from '../auth/magicLink/MagicLinkKeys.js';
@@ -65,7 +65,11 @@ export function createWidgetHandler(publicUrl: string, config: WidgetConfig): {
     windowMs: config.rateLimitWindowMs,
     standardHeaders: 'draft-7',
     legacyHeaders: false,
-    keyGenerator: (req: Request) => `${readWidgetKey(req)}:${req.ip ?? 'noip'}`,
+    // ipKeyGenerator collapses IPv6 addresses to their /56 subnet before keying. Raw `req.ip`
+    // would give every IPv6 client a practically unlimited supply of distinct keys (one per
+    // address in their delegated prefix), letting them sidestep the per-IP bucket entirely —
+    // express-rate-limit v8 refuses to start with a keyGenerator that reads req.ip without it.
+    keyGenerator: (req: Request) => `${readWidgetKey(req)}:${req.ip ? ipKeyGenerator(req.ip) : 'noip'}`,
     limit: async (req: Request) => service.ResolvePerInstanceRateLimit(readWidgetKey(req)),
     message: { success: false, errorCode: 'rate_limited', error: 'Too many widget session requests. Try again later.' },
   });

package/src/resolvers/AdhocQueryResolver.ts

@@ -6,6 +6,7 @@ import { AppContext } from '../types.js';
 import { GetReadOnlyDataSource, GetReadOnlyProvider } from '../util.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { RunQueryResultType } from './QueryResolver.js';
+import { exactTotalFromPage, resolveAdhocTotalRowCount } from './adhoc-query-helpers.js';
 import sql from 'mssql';
 
 /**
@@ -23,7 +24,7 @@ class AdhocQueryInput {
     @Field(() => Int, { nullable: true, description: 'Maximum number of rows to return; applied at the database via the render pipeline.' })
     MaxRows?: number;
 
-    @Field(() => Int, { nullable: true, description: 'Zero-based offset for pagination. When > 0, the row cap switches to OFFSET/FETCH pagination.' })
+    @Field(() => Int, { nullable: true, description: 'Zero-based offset for pagination. Whenever MaxRows > 0 the query is paged via OFFSET/FETCH — including the first page (StartRow 0).' })
     StartRow?: number;
 }
 
@@ -76,55 +77,53 @@ export class AdhocQueryResolver extends ResolverBase {
             // 4. Route the SQL through RenderPipeline so composition tokens
             // resolve, comments and templates are processed, and the row cap
             // is applied at the database (via TOP / LIMIT / OFFSET-FETCH).
-            const startRow = input.StartRow ?? 0;
+            //
+            // Page whenever a positive MaxRows is requested — INCLUDING the first
+            // page (StartRow 0). This yields OFFSET/FETCH data SQL *and* a
+            // COUNT(*) query so the response reports the true total row count
+            // rather than just the returned page size. It mirrors the saved-query
+            // path (GenericDatabaseProvider.InternalRunQuery → WrapWithPaging).
+            // (Previously paging was gated on StartRow > 0, so page 1 fell back to
+            // a TOP-N cap with TotalRowCount = page size — hiding the pager.)
+            // Clamp StartRow to a non-negative integer. A negative offset must not slip
+            // past the paging gate (which would then run the query with no row cap at all).
+            const startRow = Math.max(0, Number.isInteger(input.StartRow) ? input.StartRow! : 0);
             const maxRows = input.MaxRows;
-            const usePaging =
-                maxRows != null &&
-                Number.isInteger(maxRows) &&
-                maxRows > 0 &&
-                Number.isInteger(startRow) &&
-                startRow > 0;
-            let executableSql: string;
+            const usePaging = maxRows != null && Number.isInteger(maxRows) && maxRows > 0;
+
+            let dataSQL: string;
+            let countSQL: string | null = null;
             try {
                 const rendered = RenderPipeline.Run(input.SQL, {
                     Platform: platform,
                     ContextUser: contextUser,
-                    ...(usePaging
-                        ? { Paging: { StartRow: startRow, MaxRows: maxRows! } }
-                        : maxRows != null && maxRows > 0
-                            ? { MaxRows: maxRows }
-                            : {}),
+                    ...(usePaging ? { Paging: { StartRow: startRow, MaxRows: maxRows! } } : {}),
                 });
-                executableSql = rendered.FinalSQL;
+                dataSQL = rendered.FinalSQL;
+                countSQL = rendered.PagingResult?.CountSQL ?? null;
             } catch (renderErr) {
                 const renderMsg = renderErr instanceof Error ? renderErr.message : String(renderErr);
                 return this.buildErrorResult(`Ad-hoc query rendering failed: ${renderMsg}`);
             }
 
-            // 5. Execute with timeout
-            const timeoutMs = (input.TimeoutSeconds ?? 30) * 1000;
-            const request = new sql.Request(readOnlyDS);
-
-            const result = await Promise.race([
-                request.query(executableSql),
-                new Promise<never>((_, reject) =>
-                    setTimeout(() => reject(new Error('Query timeout exceeded')), timeoutMs)
-                )
-            ]);
+            // 5. Execute the page (and, only when a full page needs it, the count) under
+            // a shared wall-clock deadline derived from the request's timeout budget.
+            const deadline = startTime + (input.TimeoutSeconds ?? 30) * 1000;
+            const { recordset, totalRowCount } = await this.executeDataAndCount(
+                readOnlyDS, dataSQL, countSQL, startRow, usePaging ? maxRows! : null, deadline
+            );
             const executionTimeMs = Date.now() - startTime;
 
             // 6. Return as RunQueryResultType
-            const recordset = result.recordset ?? [];
-
             return {
                 QueryID: '',
                 QueryName: 'Ad-Hoc Query',
                 Success: true,
                 Results: JSON.stringify(recordset),
                 RowCount: recordset.length,
-                TotalRowCount: recordset.length,
-                PageNumber: maxRows != null && maxRows > 0 ? Math.floor(startRow / maxRows) + 1 : undefined,
-                PageSize: maxRows ?? undefined,
+                TotalRowCount: totalRowCount,
+                PageNumber: usePaging ? Math.floor(startRow / maxRows!) + 1 : undefined,
+                PageSize: usePaging ? maxRows! : undefined,
                 ExecutionTime: executionTimeMs,
                 ErrorMessage: ''
             };
@@ -164,6 +163,74 @@ export class AdhocQueryResolver extends ResolverBase {
         }
     }
 
+    /**
+     * Runs the page's data SQL, then — only when the page is FULL (so more rows may
+     * exist) — a COUNT(*) for the true total. A short (or unpaged) page needs no
+     * count: the exact total is `startRow + rowsReturned` (see {@link exactTotalFromPage}).
+     *
+     * The count is NON-FATAL: some queries page fine but cannot be counted — e.g.
+     * duplicate column names are legal in a result set but rejected inside the COUNT
+     * CTE wrap. A count failure must never sink the whole result, so we log it and
+     * report a lower-bound total (`startRow + rowsReturned`) and let the data render.
+     */
+    private async executeDataAndCount(
+        ds: sql.ConnectionPool,
+        dataSQL: string,
+        countSQL: string | null,
+        startRow: number,
+        maxRows: number | null,
+        deadline: number,
+    ): Promise<{ recordset: Record<string, unknown>[]; totalRowCount: number }> {
+        const dataResult = await this.runSqlWithDeadline<Record<string, unknown>>(ds, dataSQL, deadline);
+        const recordset = (dataResult.recordset ?? []) as Record<string, unknown>[];
+
+        // Total already known from the page alone (unpaged, or a short page)? Skip the count.
+        const exact = exactTotalFromPage(startRow, recordset.length, maxRows);
+        if (exact != null || !countSQL) {
+            return { recordset, totalRowCount: exact ?? recordset.length };
+        }
+
+        // Full page — a COUNT(*) is required to know the true total.
+        const lowerBound = startRow + recordset.length;
+        try {
+            const countResult = await this.runSqlWithDeadline<{ TotalRowCount: number }>(ds, countSQL, deadline);
+            return { recordset, totalRowCount: resolveAdhocTotalRowCount(countResult.recordset, lowerBound) };
+        } catch (countErr) {
+            const msg = countErr instanceof Error ? countErr.message : String(countErr);
+            LogError(`Ad-hoc query row-count failed; reporting a lower-bound total (${lowerBound}). ${msg}`);
+            return { recordset, totalRowCount: lowerBound };
+        }
+    }
+
+    /**
+     * Executes one SQL statement on the read-only pool, racing it against the shared
+     * wall-clock `deadline`. The timer is always cleared on completion so a settled
+     * query never leaves a dangling timeout armed.
+     */
+    private async runSqlWithDeadline<T>(
+        ds: sql.ConnectionPool,
+        sqlText: string,
+        deadline: number,
+    ): Promise<sql.IResult<T>> {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw new Error('Query timeout exceeded');
+        }
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        try {
+            return await Promise.race([
+                new sql.Request(ds).query<T>(sqlText),
+                new Promise<never>((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('Query timeout exceeded')), remaining);
+                }),
+            ]);
+        } finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    }
+
     private buildErrorResult(errorMessage: string): RunQueryResultType {
         return {
             QueryID: '',

package/src/resolvers/GetDataResolver.ts

@@ -281,8 +281,37 @@ export class GetDataAccessToken {
     TokenUses: TokenUseLog[];
 }
 const __accessTokens: GetDataAccessToken[] = [];
-const __defaultTokenLifeSpan = 1000 * 60 * 5; // 5 minutes  
+const __defaultTokenLifeSpan = 1000 * 60 * 5; // 5 minutes
+
+/**
+ * Removes every token whose `ExpiresAt` has already passed (and its `TokenUses`
+ * log along with it). Without this sweep `__accessTokens` grows forever — nothing
+ * else in this module ever removes an expired token, `deleteAccessToken()` has no
+ * production caller (tokens are consumed implicitly via short-lived `GetData`
+ * calls, never explicitly released by the requesting system), and `isTokenValid()`
+ * only checks the expiry timestamp without pruning it. Called from
+ * `registerAccessToken()` — the natural "allocation" moment — so the array
+ * self-bounds to roughly "tokens registered within one lifespan window" instead
+ * of growing with total lifetime registrations (Memory Leak Audit Round 7,
+ * Critical finding).
+ * @param now injectable for tests; defaults to the real current time
+ */
+export function pruneExpiredTokens(now: Date = new Date()): void {
+    for (let i = __accessTokens.length - 1; i >= 0; i--) {
+        if (__accessTokens[i].ExpiresAt <= now) {
+            __accessTokens.splice(i, 1);
+        }
+    }
+}
+
+/** Number of tokens currently tracked (post-sweep, at last mutation). Exposed for tests/diagnostics. */
+export function getAccessTokenCount(): number {
+    return __accessTokens.length;
+}
+
 export function registerAccessToken(token?: string, lifeSpan: number = __defaultTokenLifeSpan, requestorPayload?: any): GetDataAccessToken {
+    pruneExpiredTokens();
+
     const tokenToUse = token || uuidv4();
 
     if (tokenExists(tokenToUse)) {