@triflux/remote 10.28.1 → 10.30.0

package/hub/workers/lib/jsonrpc-core.mjs

@@ -0,0 +1,299 @@
+// hub/workers/lib/jsonrpc-core.mjs
+// Shared JSON-RPC request/notification dispatch core for transport clients.
+
+/**
+ * Thrown when the peer emits a malformed JSON-RPC frame.
+ */
+export class JsonRpcProtocolError extends Error {
+  /** @param {string} message @param {{ cause?: unknown }} [options] */
+  constructor(message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "JsonRpcProtocolError";
+  }
+}
+
+export class JsonRpcDispatchBase {
+  /**
+   * @param {object} options
+   * @param {(err: Error) => void} [options.onError] Protocol error sink.
+   * @param {string} options.closedMessage Error message for closed requests.
+   */
+  constructor({ onError, closedMessage }) {
+    this._onError = typeof onError === "function" ? onError : null;
+    this._closedMessage = closedMessage;
+    /** @type {'idle'|'running'|'closing'|'closed'} */
+    this._state = "closed";
+    this._nextRequestId = 1;
+    /** @type {Map<number, { resolve: Function, reject: Function, timer: any, method: string }>} */
+    this._pendingRequests = new Map();
+    /** @type {Map<string, Set<Function>>} */
+    this._notificationHandlers = new Map();
+  }
+
+  /**
+   * Issue a JSON-RPC request and resolve with the server's `result`.
+   * Rejects on error response, timeout, malformed payload, or close().
+   * @param {string} method
+   * @param {unknown} params
+   * @param {number} [timeoutMs=60000]
+   * @returns {Promise<any>}
+   */
+  request(method, params, timeoutMs = 60000) {
+    if (this._state !== "running") {
+      return Promise.reject(new Error(this._closedMessage));
+    }
+
+    const id = this._nextRequestId++;
+    // P1 #1 wire framing: omit `jsonrpc: "2.0"` on outbound. Peer decode remains
+    // lenient (OpenAI App Server JSONL variant spec).
+    const frame = { id, method };
+    if (params !== undefined) frame.params = params;
+
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        timer = setTimeout(() => {
+          const pending = this._pendingRequests.get(id);
+          if (!pending) return;
+          this._pendingRequests.delete(id);
+          reject(
+            new Error(
+              `JSON-RPC request timed out after ${timeoutMs}ms: ${method}`,
+            ),
+          );
+        }, timeoutMs);
+      }
+
+      this._pendingRequests.set(id, { resolve, reject, timer, method });
+
+      try {
+        this._encodeAndSend(frame);
+      } catch (err) {
+        this._pendingRequests.delete(id);
+        if (timer) clearTimeout(timer);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Send a JSON-RPC notification (no id, no response expected).
+   * Silently drops if the client is not in `running`.
+   * @param {string} method
+   * @param {unknown} [params]
+   */
+  notify(method, params) {
+    if (this._state !== "running") return;
+    // P1 #1 wire framing: omit jsonrpc header (outbound).
+    const frame = { method };
+    if (params !== undefined) frame.params = params;
+    try {
+      this._encodeAndSend(frame);
+    } catch (err) {
+      this._emitError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+
+  /**
+   * Subscribe to inbound notifications. Use `"*"` for a catch-all handler
+   * which receives `(params, method)`. Targeted handlers receive `(params)`.
+   * @param {string} method
+   * @param {(params: any, method?: string) => void} callback
+   * @returns {() => void} unsubscribe
+   */
+  onNotification(method, callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("onNotification requires a callback function");
+    }
+    let set = this._notificationHandlers.get(method);
+    if (!set) {
+      set = new Set();
+      this._notificationHandlers.set(method, set);
+    }
+    set.add(callback);
+    return () => {
+      const handlers = this._notificationHandlers.get(method);
+      if (!handlers) return;
+      handlers.delete(callback);
+      if (handlers.size === 0) this._notificationHandlers.delete(method);
+    };
+  }
+
+  /**
+   * Close the client. `reason === "closing"` transitions to an intermediate
+   * graceful state where a subsequent EOF is treated as normal. Idempotent.
+   * @param {string} [reason]
+   */
+  close(reason) {
+    if (this._state === "closed") return;
+
+    if (reason === "closing" && this._state === "running") {
+      this._state = "closing";
+      this._onEnterClosing();
+      return;
+    }
+    this._closeWith("closed");
+  }
+
+  /**
+   * @returns {boolean} True if the client accepts new requests.
+   */
+  isOpen() {
+    return this._state === "running";
+  }
+
+  /**
+   * @returns {'idle'|'running'|'closing'|'closed'}
+   */
+  getState() {
+    return this._state;
+  }
+
+  _handleInboundMessage(line) {
+    if (this._state === "closed") return;
+    if (line.length === 0) return;
+
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch (err) {
+      const pErr = new JsonRpcProtocolError(
+        `JSON-RPC parse error: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err },
+      );
+      this._emitError(pErr);
+      // P1 #3 fail-fast: malformed frame during running -> reject in-flight + close
+      if (this._state === "running") this._closeWith("closed", pErr);
+      return;
+    }
+
+    if (!frame || typeof frame !== "object") {
+      const pErr = new JsonRpcProtocolError(
+        "JSON-RPC protocol error: frame is not an object",
+      );
+      this._emitError(pErr);
+      if (this._state === "running") this._closeWith("closed", pErr);
+      return;
+    }
+
+    // Response: has id + (result | error)
+    if (
+      Object.hasOwn(frame, "id") &&
+      frame.id !== null &&
+      (Object.hasOwn(frame, "result") || Object.hasOwn(frame, "error"))
+    ) {
+      this._dispatchResponse(frame);
+      return;
+    }
+
+    /*
+     * FUTURE-EXTENSION: server->client requests (inbound frames with both
+     * `id` and `method`) can dispatch from this shared routing point later,
+     * for example via a `_dispatchServerRequest(frame)` branch, so backlog #1
+     * only needs to touch the base. Do not implement that branch here.
+     */
+
+    // Notification: method + no id (or id === null for responses we treated above)
+    if (typeof frame.method === "string" && !Object.hasOwn(frame, "id")) {
+      this._dispatchNotification(frame);
+      return;
+    }
+
+    // Unknown / malformed envelope - surface but keep loop alive during running.
+    // Fail-fast only on structural errors (JSON parse, EOF, max-line).
+    this._emitError(
+      new JsonRpcProtocolError(
+        "JSON-RPC protocol error: unrecognized frame shape",
+      ),
+    );
+  }
+
+  _dispatchResponse(frame) {
+    const pending = this._pendingRequests.get(frame.id);
+    if (!pending) {
+      // Stray response - drop silently (notify() path, or late after timeout).
+      return;
+    }
+    this._pendingRequests.delete(frame.id);
+    if (pending.timer) clearTimeout(pending.timer);
+
+    if (Object.hasOwn(frame, "error") && frame.error) {
+      const { code, message, data } = frame.error;
+      const err = new Error(
+        `JSON-RPC error${typeof code === "number" ? ` ${code}` : ""}: ${message || "unknown"}`,
+      );
+      if (code !== undefined) err.code = code;
+      if (data !== undefined) err.data = data;
+      pending.reject(err);
+      return;
+    }
+
+    pending.resolve(frame.result);
+  }
+
+  _dispatchNotification(frame) {
+    const method = frame.method;
+    const params = frame.params;
+
+    const targeted = this._notificationHandlers.get(method);
+    if (targeted && targeted.size > 0) {
+      for (const cb of targeted) {
+        try {
+          cb(params);
+        } catch (err) {
+          this._emitError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+    }
+
+    const wildcard = this._notificationHandlers.get("*");
+    if (wildcard && wildcard.size > 0) {
+      for (const cb of wildcard) {
+        try {
+          cb(params, method);
+        } catch (err) {
+          this._emitError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+    }
+  }
+
+  _closeWith(target, rejectReason = null) {
+    if (this._state === "closed") return;
+    this._state = target;
+
+    this._beforeRejectPending();
+
+    const rejectErr =
+      rejectReason instanceof Error
+        ? rejectReason
+        : new Error(this._closedMessage);
+
+    for (const [, pending] of this._pendingRequests) {
+      if (pending.timer) clearTimeout(pending.timer);
+      pending.reject(rejectErr);
+    }
+    this._pendingRequests.clear();
+
+    this._teardownTransport();
+  }
+
+  _emitError(err) {
+    if (!this._onError) return;
+    try {
+      this._onError(err);
+    } catch {
+      // Never throw out of the dispatch loop.
+    }
+  }
+
+  _encodeAndSend() {
+    throw new Error("JsonRpcDispatchBase._encodeAndSend not implemented");
+  }
+
+  _onEnterClosing() {}
+
+  _beforeRejectPending() {}
+
+  _teardownTransport() {}
+}

package/hub/workers/lib/jsonrpc-stdio.mjs

@@ -27,6 +27,10 @@
 
 import { createInterface } from "node:readline";
 
+import { JsonRpcDispatchBase } from "./jsonrpc-core.mjs";
+
+export { JsonRpcProtocolError } from "./jsonrpc-core.mjs";
+
 const DEFAULT_MAX_LINE_SIZE = 1024 * 1024; // 1 MiB
 const CLOSED_MESSAGE = "JsonRpcStdioClient closed";
 
@@ -46,18 +50,6 @@ export class MaxLineSizeExceededError extends Error {
   }
 }
 
-/**
- * Thrown (and used to reject in-flight execute()) when the peer emits a
- * malformed frame or the transport layer hits a structural error.
- */
-export class JsonRpcProtocolError extends Error {
-  /** @param {string} message @param {{ cause?: unknown }} [options] */
-  constructor(message, options = {}) {
-    super(message, { cause: options.cause });
-    this.name = "JsonRpcProtocolError";
-  }
-}
-
 /**
  * Thrown when the underlying stream closes unexpectedly (EOF outside `closing`).
  */
@@ -72,7 +64,7 @@ export class JsonRpcTransportError extends Error {
 /**
  * Line-delimited JSON-RPC 2.0 client over a pair of Node streams.
  */
-export class JsonRpcStdioClient {
+export class JsonRpcStdioClient extends JsonRpcDispatchBase {
   /**
    * @param {object} options
    * @param {NodeJS.ReadableStream} options.stdin Server -> client bytes.
@@ -88,9 +80,10 @@ export class JsonRpcStdioClient {
       throw new TypeError("JsonRpcStdioClient requires a writable stdout");
     }
 
+    super({ onError, closedMessage: CLOSED_MESSAGE });
+
     this._stdin = stdin;
     this._stdout = stdout;
-    this._onError = typeof onError === "function" ? onError : null;
     this._maxLineSize =
       Number.isFinite(maxLineSize) && maxLineSize > 0
         ? maxLineSize
@@ -98,11 +91,6 @@ export class JsonRpcStdioClient {
 
     /** @type {'running'|'closing'|'closed'} */
     this._state = "running";
-    this._nextRequestId = 1;
-    /** @type {Map<number, { resolve: Function, reject: Function, timer: any, method: string }>} */
-    this._pendingRequests = new Map();
-    /** @type {Map<string, Set<Function>>} */
-    this._notificationHandlers = new Map();
 
     // AC18: track bytes since last newline at the raw stream layer so an
     // oversized line is rejected *before* readline concatenates it internally.
@@ -124,7 +112,7 @@ export class JsonRpcStdioClient {
     }
 
     this._rl = createInterface({ input: this._stdin, crlfDelay: Infinity });
-    this._rl.on("line", (line) => this._handleLine(line));
+    this._rl.on("line", (line) => this._handleInboundMessage(line));
     // readline re-emits the input stream 'error' on itself; the raw stdin
     // handler above already converts it into a JsonRpcTransportError, so
     // suppress the re-emit to avoid an unhandled 'error' on the Interface.
@@ -146,145 +134,21 @@ export class JsonRpcStdioClient {
     });
   }
 
-  /**
-   * Issue a JSON-RPC request and resolve with the server's `result`.
-   * Rejects on error response, timeout, malformed payload, or close().
-   * @param {string} method
-   * @param {unknown} params
-   * @param {number} [timeoutMs=60000]
-   * @returns {Promise<any>}
-   */
-  request(method, params, timeoutMs = 60000) {
-    if (this._state !== "running") {
-      return Promise.reject(new Error(CLOSED_MESSAGE));
-    }
-
-    const id = this._nextRequestId++;
-    // P1 #1 wire framing: omit `jsonrpc: "2.0"` on outbound. Peer decode remains
-    // lenient (OpenAI App Server JSONL variant spec).
-    const frame = { id, method };
-    if (params !== undefined) frame.params = params;
-
-    return new Promise((resolve, reject) => {
-      let timer = null;
-      if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
-        timer = setTimeout(() => {
-          const pending = this._pendingRequests.get(id);
-          if (!pending) return;
-          this._pendingRequests.delete(id);
-          reject(
-            new Error(
-              `JSON-RPC request timed out after ${timeoutMs}ms: ${method}`,
-            ),
-          );
-        }, timeoutMs);
-      }
-
-      this._pendingRequests.set(id, { resolve, reject, timer, method });
-
-      try {
-        this._writeFrame(frame);
-      } catch (err) {
-        this._pendingRequests.delete(id);
-        if (timer) clearTimeout(timer);
-        reject(err);
-      }
-    });
-  }
+  // --- internals ---------------------------------------------------------
 
-  /**
-   * Send a JSON-RPC notification (no id, no response expected).
-   * Silently drops if the client is not in `running`.
-   * @param {string} method
-   * @param {unknown} [params]
-   */
-  notify(method, params) {
-    if (this._state !== "running") return;
-    // P1 #1 wire framing: omit jsonrpc header (outbound).
-    const frame = { method };
-    if (params !== undefined) frame.params = params;
+  _encodeAndSend(frame) {
+    if (this._state === "closed") return;
+    const line = `${JSON.stringify(frame)}\n`;
     try {
-      this._writeFrame(frame);
+      this._stdout.write(line, (err) => {
+        if (err) this._handleStreamError("stdout-write", err);
+      });
     } catch (err) {
-      this._emitError(err);
-    }
-  }
-
-  /**
-   * Subscribe to inbound notifications. Use `"*"` for a catch-all handler
-   * which receives `(params, method)`. Targeted handlers receive `(params)`.
-   * @param {string} method
-   * @param {(params: any, method?: string) => void} callback
-   * @returns {() => void} unsubscribe
-   */
-  onNotification(method, callback) {
-    if (typeof callback !== "function") {
-      throw new TypeError("onNotification requires a callback function");
-    }
-    let set = this._notificationHandlers.get(method);
-    if (!set) {
-      set = new Set();
-      this._notificationHandlers.set(method, set);
-    }
-    set.add(callback);
-    return () => {
-      const handlers = this._notificationHandlers.get(method);
-      if (!handlers) return;
-      handlers.delete(callback);
-      if (handlers.size === 0) this._notificationHandlers.delete(method);
-    };
-  }
-
-  /**
-   * Close the client: reject all pending requests, stop tracking input,
-   * and release the readline interface. Idempotent.
-   *
-   * Optional `reason` = `"closing"` transitions to the intermediate `closing`
-   * state *without* terminating the readline loop, so a graceful shutdown can
-   * issue a final request (e.g. `thread/unsubscribe`) before EOF triggers
-   * full closure. Any subsequent EOF in `closing` is treated as normal.
-   *
-   * @param {string} [reason]
-   */
-  close(reason) {
-    if (this._state === "closed") return;
-
-    if (reason === "closing" && this._state === "running") {
-      this._state = "closing";
-      return;
+      this._handleStreamError("stdout-write", err);
     }
-    this._closeWith("closed");
-  }
-
-  /**
-   * @returns {boolean} True if the client accepts new requests.
-   */
-  isOpen() {
-    return this._state === "running";
-  }
-
-  /**
-   * @returns {'running'|'closing'|'closed'}
-   */
-  getState() {
-    return this._state;
   }
 
-  // --- internals ---------------------------------------------------------
-
-  _closeWith(target, rejectReason = null) {
-    if (this._state === "closed") return;
-    this._state = target;
-
-    const rejectErr =
-      rejectReason instanceof Error ? rejectReason : new Error(CLOSED_MESSAGE);
-
-    for (const [, pending] of this._pendingRequests) {
-      if (pending.timer) clearTimeout(pending.timer);
-      pending.reject(rejectErr);
-    }
-    this._pendingRequests.clear();
-
+  _teardownTransport() {
     try {
       this._stdin.off?.("data", this._onStdinData);
     } catch {
@@ -297,18 +161,6 @@ export class JsonRpcStdioClient {
     }
   }
 
-  _writeFrame(frame) {
-    if (this._state === "closed") return;
-    const line = `${JSON.stringify(frame)}\n`;
-    try {
-      this._stdout.write(line, (err) => {
-        if (err) this._handleStreamError("stdout-write", err);
-      });
-    } catch (err) {
-      this._handleStreamError("stdout-write", err);
-    }
-  }
-
   /**
    * Convert a raw stream error into a JsonRpcTransportError, emit it to the
    * error sink, and close the client so pending requests are rejected.
@@ -349,115 +201,4 @@ export class JsonRpcStdioClient {
       }
     }
   }
-
-  _handleLine(line) {
-    if (this._state === "closed") return;
-    if (line.length === 0) return;
-
-    let frame;
-    try {
-      frame = JSON.parse(line);
-    } catch (err) {
-      const pErr = new JsonRpcProtocolError(
-        `JSON-RPC parse error: ${err instanceof Error ? err.message : String(err)}`,
-        { cause: err },
-      );
-      this._emitError(pErr);
-      // P1 #3 fail-fast: malformed frame during running → reject in-flight + close
-      if (this._state === "running") this._closeWith("closed", pErr);
-      return;
-    }
-
-    if (!frame || typeof frame !== "object") {
-      const pErr = new JsonRpcProtocolError(
-        "JSON-RPC protocol error: frame is not an object",
-      );
-      this._emitError(pErr);
-      if (this._state === "running") this._closeWith("closed", pErr);
-      return;
-    }
-
-    // Response: has id + (result | error)
-    if (
-      Object.hasOwn(frame, "id") &&
-      frame.id !== null &&
-      (Object.hasOwn(frame, "result") || Object.hasOwn(frame, "error"))
-    ) {
-      this._dispatchResponse(frame);
-      return;
-    }
-
-    // Notification: method + no id (or id === null for responses we treated above)
-    if (typeof frame.method === "string" && !Object.hasOwn(frame, "id")) {
-      this._dispatchNotification(frame);
-      return;
-    }
-
-    // Unknown / malformed envelope — surface but keep loop alive during running.
-    // Fail-fast only on structural errors (JSON parse, EOF, max-line).
-    this._emitError(
-      new JsonRpcProtocolError(
-        "JSON-RPC protocol error: unrecognized frame shape",
-      ),
-    );
-  }
-
-  _dispatchResponse(frame) {
-    const pending = this._pendingRequests.get(frame.id);
-    if (!pending) {
-      // Stray response — drop silently (notify() path, or late after timeout).
-      return;
-    }
-    this._pendingRequests.delete(frame.id);
-    if (pending.timer) clearTimeout(pending.timer);
-
-    if (Object.hasOwn(frame, "error") && frame.error) {
-      const { code, message, data } = frame.error;
-      const err = new Error(
-        `JSON-RPC error${typeof code === "number" ? ` ${code}` : ""}: ${message || "unknown"}`,
-      );
-      if (code !== undefined) err.code = code;
-      if (data !== undefined) err.data = data;
-      pending.reject(err);
-      return;
-    }
-
-    pending.resolve(frame.result);
-  }
-
-  _dispatchNotification(frame) {
-    const method = frame.method;
-    const params = frame.params;
-
-    const targeted = this._notificationHandlers.get(method);
-    if (targeted && targeted.size > 0) {
-      for (const cb of targeted) {
-        try {
-          cb(params);
-        } catch (err) {
-          this._emitError(err instanceof Error ? err : new Error(String(err)));
-        }
-      }
-    }
-
-    const wildcard = this._notificationHandlers.get("*");
-    if (wildcard && wildcard.size > 0) {
-      for (const cb of wildcard) {
-        try {
-          cb(params, method);
-        } catch (err) {
-          this._emitError(err instanceof Error ? err : new Error(String(err)));
-        }
-      }
-    }
-  }
-
-  _emitError(err) {
-    if (!this._onError) return;
-    try {
-      this._onError(err);
-    } catch {
-      // Never throw out of the dispatch loop.
-    }
-  }
 }