hypha-rpc 0.21.34 → 0.21.36

package/README.md

@@ -24,4 +24,75 @@ hyphaWebsocketClient.connectToServer({
       }
   )
 })
-```
+```
+
+### Keyword Arguments (kwargs)
+
+Hypha RPC supports Python-style keyword arguments when calling JavaScript services. This works seamlessly across Python→JS and JS→JS calls.
+
+#### Calling from Python to JavaScript
+
+When a Python client calls a JS service using keyword arguments, they are automatically unpacked into the matching positional parameters:
+
+```python
+# Python caller
+svc = await server.get_service("my-js-service")
+result = await svc.greet(name="Alice", greeting="Hello")
+```
+
+```javascript
+// JavaScript service — params are matched by name
+await api.registerService({
+  id: "my-js-service",
+  greet(name, greeting) {
+    return `${greeting}, ${name}!`;  // "Hello, Alice!"
+  }
+});
+```
+
+#### Calling from JavaScript to JavaScript
+
+Use the `_rkwargs: true` flag to send keyword arguments from JS:
+
+```javascript
+const svc = await api.getService("my-js-service");
+
+// Positional (traditional)
+await svc.greet("Alice", "Hello");
+
+// Keyword arguments — params matched by name, order doesn't matter
+await svc.greet({ greeting: "Hello", name: "Alice", _rkwargs: true });
+```
+
+#### With `require_context`
+
+When a service uses `require_context: true`, the `context` parameter is automatically injected by the server and cannot be overridden via kwargs:
+
+```javascript
+await api.registerService({
+  id: "secure-svc",
+  config: { require_context: true },
+  greet(name, greeting, context) {
+    console.log("Called by:", context.user);
+    return `${greeting}, ${name}!`;
+  }
+});
+
+// Caller — context is injected automatically, not passed by the caller
+await svc.greet({ name: "Alice", greeting: "Hello", _rkwargs: true });
+```
+
+#### With `kwargs_expansion`
+
+For convenience when calling server APIs, connect with `kwargs_expansion: true` to automatically convert the last object argument to kwargs:
+
+```javascript
+const api = await connectToServer({
+  server_url: "https://ai.imjoy.io",
+  kwargs_expansion: true,
+});
+// The last object arg is automatically sent as kwargs
+const token = await api.generateToken({ config: { workspace: "my-ws" } });
+```
+
+> **Note:** Kwargs unpacking relies on parsing function parameter names from source code. This works with regular functions, arrow functions, and async functions, but will not work with minified/bundled code where parameter names are mangled.

package/coverage/html/index.html

@@ -86,7 +86,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-10T16:00:13.893Z
+                at 2026-03-11T17:52:10.251Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/dist/hypha-rpc-websocket.js

@@ -2979,15 +2979,47 @@ class HTTPStreamingRPCConnection {
 
   /**
    * Process msgpack stream with 4-byte length prefix.
+   *
+   * Includes a read timeout to detect dead connections. The Hypha server
+   * sends pings every ~30s, so if no data arrives within READ_TIMEOUT_MS,
+   * the connection is considered dead and the stream is cancelled to
+   * trigger reconnection.
    */
   async _processMsgpackStream(response) {
     const reader = response.body.getReader();
+    // Expose the reader so external code (e.g. daemon heartbeat) can cancel it
+    this._reader = reader;
     // Growing buffer to avoid O(n^2) re-allocation on every chunk
     let buffer = new Uint8Array(4096);
     let bufferLen = 0;
 
+    // Read timeout: server sends pings every ~30s, so 120s = 4 missed pings = dead
+    const READ_TIMEOUT_MS = 120_000;
+
     while (!this._closed) {
-      const { done, value } = await reader.read();
+      let readResult;
+      let timeoutId;
+      try {
+        readResult = await Promise.race([
+          reader.read(),
+          new Promise((_, reject) => {
+            timeoutId = setTimeout(
+              () => reject(new Error("Stream read timeout (no data for 120s)")),
+              READ_TIMEOUT_MS,
+            );
+          }),
+        ]);
+        clearTimeout(timeoutId);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        console.warn(`Stream read error: ${error.message}`);
+        try {
+          reader.cancel();
+        } catch {}
+        break;
+      }
+
+      const { done, value } = readResult;
 
       if (done) break;
 
@@ -3067,6 +3099,8 @@ class HTTPStreamingRPCConnection {
         bufferLen = remaining;
       }
     }
+
+    this._reader = null;
   }
 
   /**
@@ -3405,7 +3439,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   API_VERSION: () => (/* binding */ API_VERSION),
 /* harmony export */   RPC: () => (/* binding */ RPC),
-/* harmony export */   _applyEncryptionKeyToService: () => (/* binding */ _applyEncryptionKeyToService)
+/* harmony export */   _applyEncryptionKeyToService: () => (/* binding */ _applyEncryptionKeyToService),
+/* harmony export */   getParamNames: () => (/* binding */ getParamNames)
 /* harmony export */ });
 /* harmony import */ var _utils_index_js__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./utils/index.js */ "./src/utils/index.js");
 /* harmony import */ var _utils_schema_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./utils/schema.js */ "./src/utils/schema.js");
@@ -3422,6 +3457,35 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+/**
+ * Extract parameter names from a function's source text.
+ * Works with regular functions, arrow functions, async functions,
+ * destructured params, default values, and rest params.
+ * Note: will not work with minified/bundled code where param names are mangled.
+ * @param {Function} fn - The function to inspect.
+ * @returns {string[]} Array of parameter names.
+ */
+function getParamNames(fn) {
+  const src = fn.toString();
+  // Match: function(a, b), async function name(a, b), (a, b) =>, async (a, b) =>
+  // Also handles single param arrow without parens: a =>
+  const match = src.match(
+    /^(?:async\s+)?(?:function\s*\w*)?\s*\(([^)]*)\)|^(?:async\s+)?(\w+)\s*=>/,
+  );
+  if (!match) return [];
+  const paramStr = match[1] !== undefined ? match[1] : match[2];
+  if (!paramStr || !paramStr.trim()) return [];
+  return paramStr
+    .split(",")
+    .map((p) =>
+      p
+        .trim()
+        .replace(/\s*=.*$/, "") // strip default values
+        .replace(/^\.\.\.\s*/, ""), // strip rest operator
+    )
+    .filter(Boolean);
+}
+
 /**
  * Apply an out-of-band encryption public key to all remote methods in a service.
  * @param {Object} svc - The decoded service object.
@@ -4002,12 +4066,10 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
 
           try {
             // Get fresh manager service (one RPC roundtrip, ~50-100ms)
-            const _t0 = Date.now();
             const manager = await this.get_manager_service({
               timeout: 20,
               case_conversion: "camel",
             });
-            console.error(`[DEBUG] get_manager_service took ${Date.now() - _t0}ms`);
 
             // Fire manager_refreshed IMMEDIATELY — before service re-registration.
             // This allows connectToServer's wm proxy to be updated as soon as
@@ -4015,7 +4077,7 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
             this._fire("manager_refreshed", { manager });
 
             const services = Object.values(this._services);
-            const servicesCount = services.length;
+            let servicesCount = services.length;
             let registeredCount = 0;
             const failedServices = [];
 
@@ -4032,14 +4094,12 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
                 continue;
               }
               try {
-                const _t1 = Date.now();
                 const serviceInfo = this._extract_service_info(service);
                 await withTimeout(
                   manager.registerService(serviceInfo),
                   serviceRegistrationTimeout,
                   `Timeout registering service ${service.id || "unknown"}`,
                 );
-                console.error(`[DEBUG] registerService(${service.id}) took ${Date.now() - _t1}ms`);
                 registeredCount++;
               } catch (serviceError) {
                 failedServices.push(service.id || "unknown");
@@ -4075,6 +4135,11 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
               failed: failedServices,
             });
 
+            // Track whether all services were registered so the
+            // reconnection loop can detect partial failures and retry.
+            this._connection._services_registered_ok =
+              failedServices.length === 0;
+
             // Subscribe to client_disconnected events if the manager supports it
             try {
               if (
@@ -4167,6 +4232,9 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
               error: managerError.toString(),
               total_services: Object.keys(this._services).length,
             });
+            // Mark registration as failed so the reconnection loop
+            // can detect and retry
+            this._connection._services_registered_ok = false;
           }
         } else {
           // console.debug("Connection established", connectionInfo);
@@ -4184,10 +4252,11 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
       // This ensures no remote function call hangs forever when the connection drops
       if (typeof connection.on_disconnected === "function") {
         connection.on_disconnected((reason) => {
-          // If reconnection is enabled, don't reject pending calls immediately.
-          // The timeout mechanism will handle them if reconnection fails,
-          // allowing calls to succeed after a successful reconnection.
-          if (connection._enable_reconnect) {
+          // If reconnection is enabled AND the connection is not permanently closed,
+          // don't reject pending calls immediately — they may succeed after reconnect.
+          // When _closed is true (max retries exhausted or server refused reconnect),
+          // we must reject immediately so callers are not left hanging forever.
+          if (connection._enable_reconnect && !connection._closed) {
             this._logger.info(
               `Connection lost (${reason}), reconnection enabled - pending calls will be handled by timeout`,
             );
@@ -4541,7 +4610,15 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
     delete this._rintfCallerIndex[clientId];
     let cleaned = 0;
     for (const sid of serviceIds) {
-      if (this._services[sid]) {
+      const svc = this._services[sid];
+      if (svc) {
+        if (typeof svc._dispose === "function") {
+          try {
+            svc._dispose();
+          } catch (e) {
+            /* ignore errors from dispose handlers */
+          }
+        }
         delete this._services[sid];
         cleaned++;
       }
@@ -6357,6 +6434,24 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
       } else {
         args = [];
       }
+
+      // Unpack kwargs into positional arguments when with_kwargs is set.
+      // This mirrors Python's _handle_method which pops the last arg as
+      // a kwargs dict and passes it via **kwargs. Since JS doesn't have
+      // **kwargs, we map the dict keys to the function's parameter names.
+      if (data.with_kwargs && args.length > 0) {
+        const kwargs = args.pop();
+        if (typeof kwargs === "object" && kwargs !== null) {
+          const paramNames = getParamNames(method);
+          // Filter out 'context' — it's handled separately by require_context
+          const mappableParams = paramNames.filter((n) => n !== "context");
+          args = mappableParams.map((name) => kwargs[name]);
+        } else {
+          // Not a dict — push it back (shouldn't happen, but be safe)
+          args.push(kwargs);
+        }
+      }
+
       if (
         this._method_annotations.has(method) &&
         this._method_annotations.get(method).require_context
@@ -10713,6 +10808,19 @@ class WebsocketRPCConnection {
               throw new Error("Connection lost during reconnection settle");
             }
 
+            // Check if service re-registration succeeded.
+            // The on_connected callback sets this flag; if any
+            // services failed to register, retry instead of
+            // declaring success with missing services.
+            if (this._services_registered_ok === false) {
+              this._logger.warn(
+                "Service re-registration failed, retrying...",
+              );
+              throw new Error(
+                "Service re-registration failed after reconnection",
+              );
+            }
+
             this._logger.warn(
               `Successfully reconnected to server ${this._server_url} (services re-registered)`,
             );
@@ -11059,9 +11167,7 @@ async function connectToServer(config) {
     config.ping_interval,
     config.logger,
   );
-  const _tOpen = Date.now();
   const connection_info = await connection.open();
-  console.error(`[DEBUG] connection.open() took ${Date.now() - _tOpen}ms`);
   (0,_utils_index_js__WEBPACK_IMPORTED_MODULE_2__.assert)(
     connection_info,
     "Failed to connect to the server, no connection info obtained. This issue is most likely due to an outdated Hypha server version. Please use `imjoy-rpc` for compatibility, or upgrade the Hypha server to the latest version.",
@@ -11095,7 +11201,6 @@ async function connectToServer(config) {
   }
 
   const workspace = connection_info.workspace;
-  const _tRpc = Date.now();
   const rpc = new _rpc_js__WEBPACK_IMPORTED_MODULE_0__.RPC(connection, {
     client_id: clientId,
     workspace,
@@ -11112,17 +11217,12 @@ async function connectToServer(config) {
     encryption_private_key: config.encryption_private_key || null,
     encryption_public_key: config.encryption_public_key || null,
   });
-  console.error(`[DEBUG] RPC constructor took ${Date.now() - _tRpc}ms`);
-  const _tWait = Date.now();
   await rpc.waitFor("services_registered", config.method_timeout || 120);
-  console.error(`[DEBUG] waitFor('services_registered') took ${Date.now() - _tWait}ms`);
-  const _tWm = Date.now();
   const wm = await rpc.get_manager_service({
     timeout: config.method_timeout,
     case_conversion: "camel",
     kwargs_expansion: config.kwargs_expansion || false,
   });
-  console.error(`[DEBUG] get_manager_service (connectToServer) took ${Date.now() - _tWm}ms`);
   wm.rpc = rpc;
 
   // Auto-refresh workspace manager proxy after reconnection.