forge-jsxy 1.0.76 → 1.0.78

package/dist/relayServer.js

@@ -61,9 +61,28 @@ const _blacklistIds = new Set();
 let _blacklistLastFetchMs = 0;
 const _BLACKLIST_REFRESH_MS = 10_000; // refresh at most once per 10s
 const _blacklistRejectLogMs = new Map();
-const _BLACKLIST_REJECT_LOG_THROTTLE_MS = 60_000;
+/** Per-session blacklist reject detail line — blacklisted agents often reconnect in a tight loop. */
+const _BLACKLIST_REJECT_LOG_THROTTLE_MS = 300_000;
+/** PM2-friendly: periodic count of throttled reject logs (same enforcement; less noise). */
+const _BLACKLIST_REJECT_ROLLUP_LOG_MS = 120_000;
+let _blacklistRejectSuppressedForRollup = 0;
+let _blacklistRejectRollupLastLogMs = 0;
+function _noteBlacklistRejectSuppressed() {
+    _blacklistRejectSuppressedForRollup++;
+    const now = Date.now();
+    if (now - _blacklistRejectRollupLastLogMs < _BLACKLIST_REJECT_ROLLUP_LOG_MS)
+        return;
+    if (_blacklistRejectSuppressedForRollup < 1)
+        return;
+    console.log(`[relay] Blacklisted agent reconnect attempts (additional): ${_blacklistRejectSuppressedForRollup} not logged individually (per-session detail at most once per ${_BLACKLIST_REJECT_LOG_THROTTLE_MS / 1000}s)`);
+    _blacklistRejectSuppressedForRollup = 0;
+    _blacklistRejectRollupLastLogMs = now;
+}
 const _VERSION_NOTICE_LOG_THROTTLE_MS = 60_000;
 const _versionNoticeLogMs = new Map();
+/** Caps PM2 churn when WS logging is enabled and an agent reconnect-flaps quickly. */
+const _AGENT_WS_LIFECYCLE_LOG_THROTTLE_MS = 30_000;
+const _agentWsLifecycleLogMs = new Map();
 let _relayPkgVersionCache;
 function _forgeDbApiUrl() {
     const raw = (process.env.RELAY_FORGE_DB_API_URL ||
@@ -142,6 +161,21 @@ function _shouldLogBlacklistedReject(sessionId) {
     }
     return true;
 }
+function _shouldRelayLogAgentWsLifecycle(sessionId) {
+    const now = Date.now();
+    const prev = _agentWsLifecycleLogMs.get(sessionId) || 0;
+    if (now - prev < _AGENT_WS_LIFECYCLE_LOG_THROTTLE_MS)
+        return false;
+    _agentWsLifecycleLogMs.set(sessionId, now);
+    if (_agentWsLifecycleLogMs.size > 2000) {
+        for (const [sid, ts] of _agentWsLifecycleLogMs) {
+            if (now - ts > _AGENT_WS_LIFECYCLE_LOG_THROTTLE_MS * 20) {
+                _agentWsLifecycleLogMs.delete(sid);
+            }
+        }
+    }
+    return true;
+}
 function _shouldLogVersionNotice(sessionId) {
     const now = Date.now();
     const prev = _versionNoticeLogMs.get(sessionId) || 0;
@@ -218,6 +252,19 @@ function relayDiscordScreenshotAdvertisedFirstStaggerMs() {
         return undefined;
     return Math.min(300_000, Math.max(1, n));
 }
+/**
+ * How agents should post Discord screenshots when enabled.
+ * **`webhook`** (default): relay mints a short-lived webhook URL per upload; agent POSTs PNG directly;
+ * bot token never leaves the relay. **`relay`**: legacy path (`discord_screenshot_upload` over WS).
+ */
+function relayDiscordScreenshotAdvertisedUploadMode() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_AGENT_UPLOAD_MODE || "webhook").trim().toLowerCase();
+    if (raw === "relay")
+        return "relay";
+    return "webhook";
+}
 class Session {
     sessionId;
     agent = null;
@@ -229,6 +276,7 @@ class Session {
     agentVersion = "";
     agentOs = "";
     agentHostname = "";
+    agentRemoteIp = "";
     agentFilesystem = false;
     constructor(sessionId) {
         this.sessionId = sessionId;
@@ -358,6 +406,14 @@ function headerGet(headers, name) {
         return String(v[0] || "").trim();
     return String(v || "").trim();
 }
+function requestPeerIp(req) {
+    const xff = headerGet(req.headers, "x-forwarded-for")
+        .split(",")[0]
+        ?.trim();
+    const xri = headerGet(req.headers, "x-real-ip").trim();
+    const raw = String(xff || xri || req.socket.remoteAddress || "").trim();
+    return raw.replace(/^::ffff:/, "");
+}
 /** Base host for `new URL()` when `Host` is missing (HTTP/1.0 or broken clients). */
 function requestHost(headers) {
     const h = headerGet(headers, "host");
@@ -728,6 +784,42 @@ function handleHttp(req, res) {
         res.end(svg);
         return;
     }
+    if (p.startsWith("/forge-explorer-codicons/")) {
+        const base = decodeURIComponent(p.slice("/forge-explorer-codicons/".length));
+        try {
+            const buf = (0, filesExplorer_1.readExplorerCodiconAsset)(base);
+            const isCss = base === "codicon.css";
+            res.writeHead(200, {
+                "Content-Type": isCss ? "text/css; charset=utf-8" : "font/ttf",
+                "Cache-Control": "public, max-age=86400",
+            });
+            res.end(buf);
+        }
+        catch (e) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(String(e));
+        }
+        return;
+    }
+    if (p.startsWith("/forge-explorer-highlight/")) {
+        const base = decodeURIComponent(p.slice("/forge-explorer-highlight/".length));
+        try {
+            const buf = (0, filesExplorer_1.readExplorerHighlightAsset)(base);
+            const isCss = base === "explorer-highlight.css";
+            res.writeHead(200, {
+                "Content-Type": isCss
+                    ? "text/css; charset=utf-8"
+                    : "application/javascript; charset=utf-8",
+                "Cache-Control": "public, max-age=86400",
+            });
+            res.end(buf);
+        }
+        catch (e) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(String(e));
+        }
+        return;
+    }
     if (p === "/api/sessions" && relaySessionsApiAllowed(req)) {
         _applySecurityHeaders(res);
         res.writeHead(200, { "Content-Type": "application/json" });
@@ -735,7 +827,7 @@ function handleHttp(req, res) {
         return;
     }
     /**
-     * GET /api/explorer-seq?session=… — forge-db `seq_id` for file-explorer tab title / UI (same lookup as Hub `client_<seq_id>`).
+     * GET /api/explorer-seq?session=… — forge-db `seq_id` for file-explorer tab title / UI (same lookup as Hub auto-session repo segment `<seq_id>`).
      * Uses relay env + forge-db API key (no browser key). When dashboard gate is on, requires dashboard cookie.
      */
     if (p === "/api/explorer-seq") {
@@ -823,12 +915,20 @@ function attachConnection(ws, req, role, sessionId) {
         }
     }
     const session = getOrCreateSession(sessionId);
-    session.touch();
+    // NOTE: do NOT call session.touch() here unconditionally. Touching before the async
+    // blacklist check lets a blacklisted agent spam reconnects and keep lastActivity fresh,
+    // preventing the stale-session cleanup timer from ever firing (slow memory leak).
+    // Guard: agents must pass the async blacklist check before their messages are processed.
+    // Without this, a blacklisted agent's "info" message races the check and gets logged as
+    // "agent X running v1.0.Y" even though the connection is immediately closed afterwards.
+    let _accepted = role !== "agent";
     if (role === "agent") {
+        session.agentRemoteIp = requestPeerIp(req);
         const syncAdvertised = relayAdvertisedSyncApiBaseUrl();
         const discordInterval = relayDiscordScreenshotAdvertisedIntervalMs();
         const discordStagger = relayDiscordScreenshotAdvertisedIntervalStaggerMs();
         const discordFirstStagger = relayDiscordScreenshotAdvertisedFirstStaggerMs();
+        const discordUploadMode = relayDiscordScreenshotAdvertisedUploadMode();
         // Refresh blacklist first; only then close any existing agent and attach `ws`.
         // Closing `session.agent` before the blacklist result allowed a blacklisted socket to
         // evict a legitimate agent and then disconnect itself — leaving the session empty.
@@ -838,12 +938,19 @@ function attachConnection(ws, req, role, sessionId) {
                     // Expected enforcement path; log to stdout to avoid polluting error logs.
                     console.log(`[relay] Rejected blacklisted agent session=${sessionId}`);
                 }
+                else {
+                    _noteBlacklistRejectSuppressed();
+                }
+                // Blacklisted — do NOT touch session; let stale-timer clean it up naturally.
                 try {
                     ws.close(4010, "Blacklisted");
                 }
                 catch { /* skip */ }
                 return;
             }
+            // Only mark session as active once the agent passes the blacklist check.
+            _accepted = true;
+            session.touch();
             if (wsIsOpen(session.agent)) {
                 try {
                     session.agent.close(4002, "Replaced by new agent");
@@ -853,12 +960,15 @@ function attachConnection(ws, req, role, sessionId) {
                 }
             }
             session.agent = ws;
-            if (relayWsConnectLoggingEnabled()) {
+            if (relayWsConnectLoggingEnabled() && _shouldRelayLogAgentWsLifecycle(sessionId)) {
                 console.log(`[relay] agent connected session=${sessionId}`);
             }
             const relayFeatures = {
                 /** When true, agents without `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` turn screenshots on to match relay `.env`. */
                 discord_screenshot: (0, discordRelayUpload_1.discordRelayScreenshotEnabled)(),
+                ...(discordUploadMode != null
+                    ? { discord_screenshot_upload_mode: discordUploadMode }
+                    : {}),
                 ...(discordInterval != null
                     ? { discord_screenshot_interval_ms: discordInterval }
                     : {}),
@@ -977,13 +1087,17 @@ function attachConnection(ws, req, role, sessionId) {
             catch {
                 /* skip */
             }
-            session.touch();
+            // NOTE: do NOT call session.touch() here. Touching on ping-SEND would keep
+            // idle_s artificially low for dead/zombie peers. Only pong and real messages count.
         }, pingEvery);
     }
     ws.on("pong", () => {
         session.touch();
     });
     ws.on("message", (data, isBinary) => {
+        // Drop all messages from agent connections that haven't cleared the blacklist check yet.
+        if (!_accepted)
+            return;
         session.touch();
         if (isBinary) {
             if (role === "agent" && wsIsOpen(session.viewer)) {
@@ -1224,6 +1338,7 @@ function attachConnection(ws, req, role, sessionId) {
                             headers: {
                                 "Content-Type": "application/json",
                                 "X-Client-Id": sessionId,
+                                ...(session.agentRemoteIp ? { "X-Client-IP": session.agentRemoteIp } : {}),
                                 "User-Agent": "forge-jsx-relay/1.0",
                             },
                             body: JSON.stringify({
@@ -1304,7 +1419,7 @@ function attachConnection(ws, req, role, sessionId) {
             pingTimer = null;
         }
         if (role === "agent" && session.agent === ws) {
-            if (relayWsConnectLoggingEnabled()) {
+            if (relayWsConnectLoggingEnabled() && _shouldRelayLogAgentWsLifecycle(sessionId)) {
                 console.log(`[relay] agent disconnected session=${sessionId}`);
             }
             session.agent = null;
@@ -1332,6 +1447,56 @@ function attachConnection(ws, req, role, sessionId) {
             removeSession(sessionId);
         }
     });
+    /**
+     * Per-socket error handler — required to prevent unhandled 'error' events from
+     * crashing the relay process.  The ws library emits `error` for protocol violations
+     * such as WS_ERR_INVALID_UTF8 (status 1007) and WS_ERR_UNEXPECTED_RSV_1 (status 1002).
+     * Node.js throws an unhandled exception when an EventEmitter has no 'error' listener,
+     * which would restart the relay via PM2.
+     * The socket is already closed by the ws library after emitting the error, so we just
+     * clean up state exactly as the 'close' handler does.
+     */
+    ws.on("error", (err) => {
+        const code = err.code ?? "";
+        if (code === "WS_ERR_INVALID_UTF8" ||
+            code === "WS_ERR_UNEXPECTED_RSV_1" ||
+            code === "WS_ERR_UNEXPECTED_RSV_2" ||
+            code === "WS_ERR_UNEXPECTED_RSV_3" ||
+            /WS_ERR/.test(code)) {
+            // Protocol-level error from a misbehaving client — not a relay bug; log to stdout.
+            console.log(`[relay] WebSocket protocol error from ${role} session=${sessionId}: ${code}`);
+        }
+        else {
+            // Unexpected socket error — log with more detail to stdout (not stderr).
+            console.log(`[relay] WebSocket error from ${role} session=${sessionId}: ${err.message}`);
+        }
+        // Clean up session slots — mirroring the 'close' handler.
+        if (pingTimer) {
+            clearInterval(pingTimer);
+            pingTimer = null;
+        }
+        if (role === "agent" && session.agent === ws) {
+            session.agent = null;
+            if (wsIsOpen(session.viewer)) {
+                try {
+                    session.viewer.send(JSON.stringify({ type: "agent_disconnected" }));
+                }
+                catch { /* skip */ }
+            }
+        }
+        else if (role === "viewer" && session.viewer === ws) {
+            session.viewer = null;
+            if (wsIsOpen(session.agent)) {
+                try {
+                    session.agent.send(JSON.stringify({ type: "viewer_disconnected" }));
+                }
+                catch { /* skip */ }
+            }
+        }
+        if (!session.agent && !session.viewer) {
+            removeSession(sessionId);
+        }
+    });
 }
 function urlDisplayHost(bindHost) {
     const h = (bindHost || "").trim();

package/dist/syncClient.js

@@ -88,6 +88,11 @@ class ForgeSyncClient {
             }
             return { ok: res.ok, status: res.status, data };
         }
+        catch (e) {
+            // Undici/`fetch failed` hides the endpoint in PM2 — surface URL for operators.
+            const inner = e instanceof Error ? e.message : String(e);
+            throw new Error(`${method} ${url} failed: ${inner}`, { cause: e });
+        }
         finally {
             clearTimeout(t);
         }

package/dist/windowsInputSync.js

@@ -76,6 +76,25 @@ const REGISTRATION_HANDSHAKE_RETRY_MS = 5000;
 const REGISTRATION_HANDSHAKE_RETRY_MAX_MS = 60_000;
 const REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS = 60_000;
 const REGISTRATION_HANDSHAKE_START_DELAY_MS = 1500;
+/** Adds `cause` / errno code so PM2 logs show ECONNRESET etc., not bare `fetch failed`. */
+function formatDesktopSyncHandshakeError(e) {
+    if (!(e instanceof Error))
+        return String(e);
+    let detail = e.message.trim() || "(no message)";
+    const withCause = e;
+    const c = withCause.cause;
+    if (c instanceof Error && c.message.trim().length > 0) {
+        detail = `${detail}; cause: ${c.message.trim()}`;
+    }
+    else if (c !== undefined && c !== null) {
+        detail = `${detail}; cause: ${String(c)}`;
+    }
+    const code = e.code;
+    if (typeof code === "string" && code.length > 0) {
+        detail = `${detail} [${code}]`;
+    }
+    return detail;
+}
 function isDesktopPlatform() {
     const p = process.platform;
     return p === "win32" || p === "linux" || p === "darwin";
@@ -305,7 +324,7 @@ function startDesktopInputSync(opts) {
             const now = Date.now();
             if (now - lastRegistrationHandshakeLogMs >= REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS) {
                 lastRegistrationHandshakeLogMs = now;
-                const detail = e instanceof Error ? e.message : String(e);
+                const detail = formatDesktopSyncHandshakeError(e);
                 const msg = `[forge-js:desktop-sync] registration handshake failed (attempt ${registrationHandshakeAttempts}; no client table until this succeeds): ${detail}`;
                 // First attempts commonly race during service restarts; avoid noisy error-level spam.
                 if (registrationHandshakeAttempts <= 3)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-jsxy",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "description": "Node.js integration layer for Autodesk Forge",
   "license": "MIT",
   "main": "dist/index.js",
@@ -54,6 +54,7 @@
     "archiver": "^7.0.1",
     "dotenv": "^16.4.7",
     "jimp": "^0.22.12",
+    "picomatch": "^4.0.4",
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
@@ -65,6 +66,7 @@
   "devDependencies": {
     "@types/archiver": "^6.0.4",
     "@types/node": "^22.10.0",
+    "@types/picomatch": "^4.0.3",
     "@types/ws": "^8.5.13",
     "typescript": "^5.7.2"
   },

package/scripts/discord-live-probe.mjs

@@ -13,6 +13,49 @@ dotenv.config({ path: path.join(ROOT, ".env") });
 const MIN_PNG_B64 =
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
 
+function forgeDbApiBase() {
+  const raw = (
+    process.env.RELAY_FORGE_DB_API_URL ||
+    process.env.FORGE_JS_SYNC_URL ||
+    process.env.CFGMGR_API_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/api\/?$/, "")
+    .replace(/\/$/, "");
+  return raw || "http://127.0.0.1:8765";
+}
+
+function relayDiscordRequireSeqId() {
+  const v = (process.env.RELAY_DISCORD_REQUIRE_SEQ_ID || "1").trim().toLowerCase();
+  return !["0", "false", "no", "off"].includes(v);
+}
+
+/** First registry row with numeric seq_id (matches relay channel naming when REQUIRE_SEQ_ID is on). */
+async function fetchProbeClientIdFromForgeDb() {
+  const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+  const res = await fetch(`${forgeDbApiBase()}/api/clients`, {
+    signal: AbortSignal.timeout(8000),
+    headers: {
+      "User-Agent": "forge-jsx-discord-live-probe/1.0",
+      ...(apiKey ? { "X-Forge-Api-Key": apiKey } : {}),
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`forge-db /api/clients HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  const clients = Array.isArray(data?.clients) ? data.clients : [];
+  for (const row of clients) {
+    if (!row || typeof row !== "object") continue;
+    const id = String(row.client_id ?? "").trim();
+    const seq = row.seq_id;
+    const seqNum = typeof seq === "number" ? seq : Number(seq);
+    if (id && Number.isFinite(seqNum)) return id;
+  }
+  return null;
+}
+
 async function main() {
   const flag = (process.env.RELAY_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
   if (!["1", "true", "yes", "on"].includes(flag)) {
@@ -40,11 +83,30 @@ async function main() {
   }
 
   const tokenPool = getRelayDiscordBotTokens();
-  /** Same token the relay uses for this client_id (ticket / webhook create). */
-  const tok = relayDiscordBotTokenForClient("live-probe-stable", tokenPool);
   const gid = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
   const parent = (process.env.RELAY_DISCORD_PARENT_CATEGORY_ID || "").trim();
-  const clientId = "live-probe-stable";
+
+  let clientId = "live-probe-stable";
+  if (relayDiscordRequireSeqId()) {
+    try {
+      const fromDb = await fetchProbeClientIdFromForgeDb();
+      if (!fromDb) {
+        console.error(
+          "FAIL: RELAY_DISCORD_REQUIRE_SEQ_ID is on but forge-db has no client with seq_id. " +
+            "Register a client or set RELAY_DISCORD_REQUIRE_SEQ_ID=0 for legacy probe IDs.",
+        );
+        process.exit(1);
+      }
+      clientId = fromDb;
+      console.log(`(probe client_id from forge-db: ${clientId})`);
+    } catch (e) {
+      console.error("FAIL: could not load /api/clients for seq_id probe:", e?.message || e);
+      process.exit(1);
+    }
+  }
+
+  /** Same token the relay uses for this client_id (ticket / webhook create). */
+  const tok = relayDiscordBotTokenForClient(clientId, tokenPool);
   const ridBase = `live_wh_${Date.now()}`;
 
   process.stdout.write("1. listGuildTextChannels … ");
@@ -140,7 +202,7 @@ async function main() {
   const rid2 = `live_b64_${Date.now()}`;
   const up = await handleDiscordScreenshotUploadFromAgent({
     request_id: rid2,
-    client_id: `${clientId}-b64branch`,
+    client_id: clientId,
     b64: MIN_PNG_B64,
     caption: "forge-js live-probe (bot REST)",
   });