@smartspectra/node-sdk 3.2.0-rc.6

package/js/main/index.js

@@ -0,0 +1,404 @@
+// js/main/index.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Main-process IPC glue for `@smartspectra/node-sdk/renderer`. The renderer
+// owns a `MediaStream` and pumps decoded RGBA frames over a MessagePort
+// created by the preload bridge; this module instantiates a
+// `SmartSpectraSDK`, dispatches frames into `sendFrame()`, and forwards
+// SDK callbacks back through the same port.
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { ipcMain, app } = require('electron');
+
+const {
+    SmartSpectraSDK,
+    ProcessingStatus,
+} = require('../smartspectra');
+
+const ATTACH_CHANNEL = 'smartspectra:attach';
+
+let preconfigured = false;
+
+// Process-wide barrier serializing native session teardown against the next
+// session start. SDK state is process-global, so two SmartSpectra sessions
+// must never run concurrently. SmartSpectraSDK.destroy() defers native
+// teardown while a stopAsync() drains on a koffi worker thread, so a
+// configure/reload arriving mid-drain could otherwise stand up a new session
+// before the old one finishes winding down — including across a renderer
+// reload, where the replacement is a fresh connection that can't see the prior
+// connection's pending teardown. Every session start awaits this barrier;
+// every teardown folds itself in. (Process-scoped, not per-connection, for the
+// reload case.)
+let sessionTeardown = Promise.resolve();
+
+// Tear `sdk` down (no-op if null) and fold its possibly-deferred native
+// teardown into the barrier so the next start waits for it. Never rejects.
+function retireSession(sdk) {
+    if (!sdk) return;
+    let done;
+    try { done = sdk.destroy(); }
+    catch (e) { done = Promise.reject(e); }
+    sessionTeardown = Promise.allSettled([sessionTeardown, Promise.resolve(done)])
+        .then(() => {});
+}
+
+// Per-host base directory the SDK initializes against. Namespaced under
+// `app.getName()` to avoid collisions when multiple Electron hosts share
+// the OS-level base (e.g. unpackaged `electron .` dev runs on macOS).
+function defaultSdkDirectory() {
+    return path.join(app.getPath('cache'), app.getName(), 'SmartSpectraSDK');
+}
+
+// Idempotent one-time SDK initialization. Not exported.
+function ensurePreconfigured() {
+    if (preconfigured) return;
+    const { preconfigure: capiPreconfigure } = require('../ffi');
+    const sdkDirectory = defaultSdkDirectory();
+    // Pre-create the tree with restrictive permissions; Electron's
+    // app.getPath('cache') root isn't always present on first launch.
+    try {
+        fs.mkdirSync(sdkDirectory, { recursive: true, mode: 0o700 });
+    } catch (err) {
+        throw new Error(
+            `SmartSpectra: failed to prepare SDK directory ${sdkDirectory}: ` +
+            `${err.message || err}. Some metrics (arterial pressure, EDA, ` +
+            'micromotion) need this to initialize; other metrics will still ' +
+            'work.');
+    }
+    if (process.env.SMARTSPECTRA_DIAGNOSTICS === '1') {
+        console.log(`[smartspectra/main] preconfigure invoked`);
+    }
+    capiPreconfigure(sdkDirectory);
+    preconfigured = true;
+}
+
+const defaultLogger = (level, msg) => {
+    if (level === 'error')      console.error(`[smartspectra/main] ${msg}`);
+    else if (level === 'warn')  console.warn(`[smartspectra/main] ${msg}`);
+    else                         console.log(`[smartspectra/main] ${msg}`);
+};
+
+// The main process treats every IPC payload as untrusted: a BrowserWindow that
+// later loads remote content (or any frame inside the renderer) could post
+// messages on the bridge. Clamp the fields we forward into native code so a
+// hostile shape can't cause a multi-GB allocation in koffi or trip the SDK's
+// own sanity checks with an out-of-range value.
+const MAX_API_KEY_BYTES = 1024;
+const MAX_REQUESTED_METRICS = 128;     // current MetricType enum has ~30 values
+const MAX_INSIGHT_TEXT_BYTES = 8192;
+const MAX_FRAME_DIM = 8192;            // 8K resolution headroom
+const MAX_FRAME_BUFFER_BYTES = 256 * 1024 * 1024;  // 256 MiB — covers 8K RGBA + slack
+const SAFE_INT32 = 2147483647;
+
+function sanitizeOptions(raw) {
+    const opts = (raw && typeof raw === 'object') ? raw : {};
+    const out = {};
+
+    if (typeof opts.apiKey === 'string') {
+        out.apiKey = opts.apiKey.length > MAX_API_KEY_BYTES
+            ? opts.apiKey.slice(0, MAX_API_KEY_BYTES)
+            : opts.apiKey;
+    }
+
+    if (Array.isArray(opts.requestedMetrics)) {
+        const src = opts.requestedMetrics.length > MAX_REQUESTED_METRICS
+            ? opts.requestedMetrics.slice(0, MAX_REQUESTED_METRICS)
+            : opts.requestedMetrics;
+        const cleaned = [];
+        for (const v of src) {
+            if (typeof v === 'number' && Number.isFinite(v) &&
+                v >= -SAFE_INT32 - 1 && v <= SAFE_INT32) {
+                cleaned.push(v | 0);
+            }
+        }
+        if (cleaned.length > 0) out.requestedMetrics = cleaned;
+    }
+
+    out.enableAccumulatedOutput = !!opts.enableAccumulatedOutput;
+    return out;
+}
+
+function sanitizeInsightText(raw) {
+    if (typeof raw !== 'string') {
+        throw new TypeError('requestInsight: text must be a string');
+    }
+    if (raw.length > MAX_INSIGHT_TEXT_BYTES) {
+        throw new RangeError(
+            `requestInsight: text length ${raw.length} exceeds ${MAX_INSIGHT_TEXT_BYTES}`);
+    }
+    return raw;
+}
+
+/**
+ * Wires the per-window IPC channel that backs `@smartspectra/node-sdk/renderer`.
+ *
+ * Call once per `BrowserWindow`. The binding tracks the window via
+ * `'closed'` and releases its SDK + port automatically.
+ *
+ * @param {import('electron').BrowserWindow} window
+ * @param {{ logger?: (level: 'info' | 'warn' | 'error', msg: string) => void }} [options]
+ */
+function bindSmartSpectraIpc(window, options = {}) {
+    const log = options.logger || defaultLogger;
+    const wc = window.webContents;
+    if (!wc) throw new TypeError('bindSmartSpectraIpc: window has no webContents');
+
+    // Best-effort: preconfigure failures don't block the bind — basic metrics
+    // still work.
+    try {
+        ensurePreconfigured();
+    } catch (err) {
+        log('warn', `preconfigure failed: ${err.message || err}`);
+    }
+
+    const onAttach = (event, _payload) => {
+        if (event.sender !== wc) return;          // multi-window safety
+        const port = event.ports && event.ports[0];
+        if (!port) {
+            log('warn', 'attach message received without a MessagePort');
+            return;
+        }
+        handleConnection(port, log);
+    };
+
+    ipcMain.on(ATTACH_CHANNEL, onAttach);
+    window.once('closed', () => {
+        ipcMain.removeListener(ATTACH_CHANNEL, onAttach);
+    });
+}
+
+// Handle a single renderer connection. Owns one SDK instance for the port's
+// lifetime; the port stays open until the renderer closes it or the window
+// navigates / unloads.
+function handleConnection(port, log) {
+    let sdk = null;
+    let framesReceived = 0;
+    let framesDropped = 0;
+    const diagnostics = process.env.SMARTSPECTRA_DIAGNOSTICS === '1';
+    const FRAME_LOG_INTERVAL = 30;  // ~once per second at 30 fps
+
+    const safePost = (msg) => {
+        try { port.postMessage(msg); }
+        catch (e) { log('warn', `port.postMessage failed: ${e.message}`); }
+    };
+
+    // Buffer-bearing messages go through structured clone, not transfer:
+    // Electron's `MessagePortMain.postMessage` rejects ArrayBuffers in the
+    // transfer list with "Port at index 0 is not a valid port". The clone
+    // cost on the protobuf payload (~few KB per packet) is negligible.
+    const installCallbacks = () => {
+        sdk.on('processingStatus', (status) =>
+            safePost({ kind: 'processingStatus', status }));
+        sdk.on('validationStatus', (code, ts, hint) =>
+            safePost({ kind: 'validationStatus', code, timestampUs: ts, hint }));
+        sdk.on('metrics', (buf, ts) =>
+            safePost({ kind: 'metrics', buffer: toArrayBufferPayload(buf), timestampUs: ts }));
+        sdk.on('accumulatedMetrics', (buf, ts) =>
+            safePost({ kind: 'accumulatedMetrics', buffer: toArrayBufferPayload(buf), timestampUs: ts }));
+        sdk.on('insight', (buf, requestId) =>
+            safePost({ kind: 'insight', buffer: toArrayBufferPayload(buf), requestId }));
+        sdk.on('frameSentThrough', (sent, ts) =>
+            safePost({ kind: 'frameSentThrough', sent, timestampUs: ts }));
+        sdk.on('error', (code, message, retryable) =>
+            safePost({ kind: 'error', code, message, retryable }));
+    };
+
+    // start/stop/reset acks carry no payload; requestInsight carries
+    // `{ requestId }`.
+    const ackOk = (replyId, payload) =>
+        safePost({ kind: 'ack', replyId, ok: true, payload: payload || null });
+    const ackFail = (replyId, e) => safePost({
+        kind: 'ack',
+        replyId,
+        ok: false,
+        error: {
+            code:      typeof e.code === 'number' ? e.code : 0,
+            message:   e.message || String(e),
+            retryable: !!e.retryable,
+        },
+    });
+
+    port.on('message', (event) => {
+        const data = event && event.data;
+        if (diagnostics && (!data || typeof data.kind !== 'string')) {
+            log('warn', `dropped malformed port message: ` +
+                `data=${data === undefined ? 'undefined' : data === null ? 'null' : typeof data} ` +
+                `keys=${data && typeof data === 'object' ? Object.keys(data).join(',') : '-'}`);
+        }
+        if (!data || typeof data.kind !== 'string') return;
+        if (diagnostics && data.kind !== 'frame') {
+            // Frame messages have their own throttled counter below.
+            log('info', `<- ${data.kind}` +
+                (data.replyId !== undefined ? ` (replyId=${data.replyId})` : ''));
+        }
+        try {
+            switch (data.kind) {
+                case 'configure':
+                    // Retire the prior session (folding its teardown into the
+                    // barrier) before standing up the replacement. The new SDK
+                    // is lazy — no native session exists until start(), which
+                    // awaits the barrier — so the two never overlap natively.
+                    retireSession(sdk);
+                    sdk = new SmartSpectraSDK(sanitizeOptions(data.options));
+                    installCallbacks();
+                    return;
+
+                case 'start': {
+                    if (!sdk) throw new Error('start before configure');
+                    const target = sdk;
+                    const { replyId } = data;
+                    const frameTransform = data.frameTransform | 0;
+                    // Defer the native session creation until any prior
+                    // session's teardown has fully drained (see sessionTeardown).
+                    // Frames arriving in the meantime are dropped (no started
+                    // session yet) — the same as the normal pre-start window.
+                    sessionTeardown.then(() => {
+                        if (sdk !== target) {
+                            // A reconfigure/teardown superseded this start while
+                            // we waited; starting the detached session would
+                            // re-introduce the overlap we're guarding against.
+                            ackFail(replyId, new Error('session replaced before start completed'));
+                            return;
+                        }
+                        target.useCustomInput(frameTransform);
+                        target.start();
+                        ackOk(replyId);
+                    }).catch((e) => ackFail(replyId, e));
+                    return;
+                }
+
+                case 'stop':
+                    // sdk.stop() blocks until the processing pipeline drains
+                    // (can take multiple seconds). Run asynchronously so this
+                    // IPC handler returns immediately and the event loop
+                    // stays free.
+                    if (sdk) {
+                        sdk.stopAsync()
+                            .then(() => ackOk(data.replyId))
+                            .catch((e) => ackFail(data.replyId, e));
+                    } else {
+                        ackOk(data.replyId);
+                    }
+                    return;
+
+                case 'reset':
+                    if (sdk) sdk.reset();
+                    return ackOk(data.replyId);
+
+                case 'frame': {
+                    if (!sdk) return;
+                    const width  = data.width  | 0;
+                    const height = data.height | 0;
+                    if (width  <= 0 || width  > MAX_FRAME_DIM ||
+                        height <= 0 || height > MAX_FRAME_DIM ||
+                        !data.buffer ||
+                        typeof data.buffer.byteLength !== 'number' ||
+                        data.buffer.byteLength > MAX_FRAME_BUFFER_BYTES) {
+                        framesDropped++;
+                        if (framesDropped === 1 || framesDropped % FRAME_LOG_INTERVAL === 0) {
+                            log('warn',
+                                `dropped frame with out-of-range shape (${framesDropped} total)`);
+                        }
+                        return;
+                    }
+                    if (diagnostics && framesReceived === 0) {
+                        log('info', `received first frame ` +
+                            `(${width}x${height} fmt=${data.pixelFormat} ` +
+                            `bytes=${data.buffer.byteLength} ` +
+                            `ts=${data.timestampUs})`);
+                    }
+                    // Frames carry no replyId, so a throw would otherwise be
+                    // reported to the renderer as an 'error' event on every
+                    // offending frame (30 fps). Transient ordering failures
+                    // (non-monotonic timestamp, gap, post-stop) are expected
+                    // during start/stop churn — drop the frame and log at most
+                    // once per FRAME_LOG_INTERVAL instead of spamming 'error'.
+                    try {
+                        sdk.sendFrame(
+                            Buffer.from(data.buffer),
+                            width,
+                            height,
+                            data.stride | 0,
+                            data.pixelFormat | 0,
+                            data.timestampUs,
+                        );
+                    } catch (e) {
+                        framesDropped++;
+                        if (framesDropped === 1 || framesDropped % FRAME_LOG_INTERVAL === 0) {
+                            log('warn', `dropped frame (${framesDropped} total): ` +
+                                `${e.message || e}`);
+                        }
+                        return;
+                    }
+                    framesReceived++;
+                    if (diagnostics && framesReceived % FRAME_LOG_INTERVAL === 0) {
+                        log('info', `received ${framesReceived} frames ` +
+                            `(${data.width}x${data.height} fmt=${data.pixelFormat})`);
+                    }
+                    return;
+                }
+
+                case 'requestInsight': {
+                    if (!sdk) throw new Error('requestInsight before configure');
+                    const id = sdk.requestInsight(sanitizeInsightText(data.text));
+                    return ackOk(data.replyId, { requestId: id });
+                }
+
+                case 'destroy':
+                    retireSession(sdk);
+                    sdk = null;
+                    try { port.close(); } catch { /* already closed */ }
+                    return;
+
+                default:
+                    log('warn', `unknown message kind: ${data.kind}`);
+            }
+        } catch (e) {
+            if (typeof data.replyId === 'number') {
+                ackFail(data.replyId, e);
+            } else {
+                safePost({
+                    kind: 'error',
+                    code:      typeof e.code === 'number' ? e.code : 0,
+                    message:   e.message || String(e),
+                    retryable: !!e.retryable,
+                });
+            }
+        }
+    });
+
+    port.on('close', () => {
+        // Fold teardown into the barrier so a reload's replacement session
+        // (a fresh connection) waits for this one to finish winding down.
+        retireSession(sdk);
+        sdk = null;
+    });
+
+    port.start();
+}
+
+// Extract an ArrayBuffer from a Node Buffer for the structured-clone message
+// payload (the port clones, it does not transfer — see installCallbacks).
+// Returns the underlying ArrayBuffer directly when the Buffer spans it
+// exactly; otherwise tightens a sliced view into its own ArrayBuffer.
+function toArrayBufferPayload(buf) {
+    if (buf.byteOffset === 0 && buf.byteLength === buf.buffer.byteLength) {
+        return buf.buffer;
+    }
+    // Sliced Buffer view — make a tight ArrayBuffer.
+    const ab = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(ab).set(buf);
+    return ab;
+}
+
+module.exports = {
+    bindSmartSpectraIpc,
+    // Re-exported for consumers driving the low-level surface directly.
+    SmartSpectraSDK,
+    ProcessingStatus,
+};