tywrap 0.2.1 → 0.3.0

package/src/runtime/process-io.ts

@@ -21,6 +21,7 @@ import {
   BridgeTimeoutError,
   BridgeExecutionError,
 } from './errors.js';
+import { TimedOutRequestTracker } from './timed-out-request-tracker.js';
 import type { Transport } from './transport.js';
 
 // =============================================================================
@@ -36,6 +37,9 @@ const MAX_STDERR_BYTES = 8 * 1024;
 /** Default write queue timeout: 30 seconds */
 const DEFAULT_WRITE_QUEUE_TIMEOUT_MS = 30_000;
 
+/** Track timed-out/cancelled request IDs long enough to ignore late responses. */
+const TIMED_OUT_REQUEST_TTL_MS = 10 * 60 * 1000;
+
 /** Regex for ANSI escape sequences */
 const ANSI_ESCAPE_RE = /\u001b\[[0-9;]*[A-Za-z]/g;
 
@@ -106,13 +110,27 @@ function sanitizeStderr(value: string): string {
 }
 
 /**
- * Extract message ID from a JSON string without full parsing.
+ * Extract top-level message ID from a JSON string.
  * Returns null if ID cannot be extracted.
  */
 function extractMessageId(json: string): number | null {
-  // Look for "id": <number> (integer IDs)
-  const match = json.match(/"id"\s*:\s*(-?\d+)/);
-  return match?.[1] ? parseInt(match[1], 10) : null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const id = (parsed as { id?: unknown }).id;
+  if (typeof id !== 'number' || !Number.isInteger(id)) {
+    return null;
+  }
+
+  return id;
 }
 
 // =============================================================================
@@ -165,6 +183,9 @@ export class ProcessIO extends BoundedContext implements Transport {
 
   // Request tracking
   private readonly pending = new Map<number, PendingRequest>();
+  private readonly timedOutRequests = new TimedOutRequestTracker({
+    ttlMs: TIMED_OUT_REQUEST_TTL_MS,
+  });
   private requestCount = 0;
   private needsRestart = false;
 
@@ -227,12 +248,15 @@ export class ProcessIO extends BoundedContext implements Transport {
 
     // Extract message ID for response correlation
     const messageId = extractMessageId(message);
-    if (!messageId) {
+    if (messageId === null) {
       throw new BridgeProtocolError('Message must contain an "id" field');
     }
 
     // Check for restart condition (either scheduled restart or forced by stream error)
-    if (this.needsRestart || (this.restartAfterRequests > 0 && this.requestCount >= this.restartAfterRequests)) {
+    if (
+      this.needsRestart ||
+      (this.restartAfterRequests > 0 && this.requestCount >= this.restartAfterRequests)
+    ) {
       await this.restartProcess();
     }
 
@@ -243,6 +267,7 @@ export class ProcessIO extends BoundedContext implements Transport {
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pending.delete(messageId);
+          this.timedOutRequests.mark(messageId);
           const stderrTail = this.getStderrTail();
           const baseMsg = `Operation timed out after ${timeoutMs}ms`;
           const msg = stderrTail ? `${baseMsg}. Recent stderr:\n${stderrTail}` : baseMsg;
@@ -256,6 +281,7 @@ export class ProcessIO extends BoundedContext implements Transport {
           clearTimeout(timer);
         }
         this.pending.delete(messageId);
+        this.timedOutRequests.mark(messageId);
         reject(new BridgeTimeoutError('Operation aborted'));
       };
 
@@ -318,9 +344,7 @@ export class ProcessIO extends BoundedContext implements Transport {
   protected async doDispose(): Promise<void> {
     // Reject all pending requests
     const stderrTail = this.getStderrTail();
-    const msg = stderrTail
-      ? `Transport disposed. Stderr:\n${stderrTail}`
-      : 'Transport disposed';
+    const msg = stderrTail ? `Transport disposed. Stderr:\n${stderrTail}` : 'Transport disposed';
     const error = new BridgeDisposedError(msg);
 
     for (const [, pending] of this.pending) {
@@ -344,6 +368,7 @@ export class ProcessIO extends BoundedContext implements Transport {
     // Clear buffers
     this.stdoutBuffer = '';
     this.stderrBuffer = '';
+    this.timedOutRequests.clear();
     this.requestCount = 0;
   }
 
@@ -539,16 +564,10 @@ export class ProcessIO extends BoundedContext implements Transport {
     this.stdoutBuffer += chunk.toString();
 
     // Check for excessive line length without newline
-    if (
-      this.stdoutBuffer.length > this.maxLineLength &&
-      !this.stdoutBuffer.includes('\n')
-    ) {
+    if (this.stdoutBuffer.length > this.maxLineLength && !this.stdoutBuffer.includes('\n')) {
       const snippet = this.stdoutBuffer.slice(0, 500);
       this.stdoutBuffer = '';
-      this.handleProtocolError(
-        `Response line exceeded ${this.maxLineLength} bytes`,
-        snippet
-      );
+      this.handleProtocolError(`Response line exceeded ${this.maxLineLength} bytes`, snippet);
       return;
     }
 
@@ -566,10 +585,7 @@ export class ProcessIO extends BoundedContext implements Transport {
       // Check line length
       if (line.length > this.maxLineLength) {
         const snippet = line.slice(0, 500);
-        this.handleProtocolError(
-          `Response line exceeded ${this.maxLineLength} bytes`,
-          snippet
-        );
+        this.handleProtocolError(`Response line exceeded ${this.maxLineLength} bytes`, snippet);
         return;
       }
 
@@ -583,15 +599,19 @@ export class ProcessIO extends BoundedContext implements Transport {
   private handleResponseLine(line: string): void {
     // Extract ID to find pending request
     const messageId = extractMessageId(line);
-    if (!messageId) {
+    if (messageId === null) {
       this.handleProtocolError('Response missing "id" field', line);
       return;
     }
 
     const pending = this.pending.get(messageId);
     if (!pending) {
-      // Response for unknown request - could be for a timed-out request
-      // Log but don't fail
+      // Ignore expected late responses from timed-out/cancelled requests.
+      if (this.timedOutRequests.consume(messageId)) {
+        return;
+      }
+      // Unknown IDs while requests are pending indicate protocol desync.
+      this.handleProtocolError(`Unexpected response id ${messageId}`, line);
       return;
     }
 
@@ -616,9 +636,7 @@ export class ProcessIO extends BoundedContext implements Transport {
 
       // Keep only the tail
       if (this.stderrBuffer.length > MAX_STDERR_BYTES) {
-        this.stderrBuffer = this.stderrBuffer.slice(
-          this.stderrBuffer.length - MAX_STDERR_BYTES
-        );
+        this.stderrBuffer = this.stderrBuffer.slice(this.stderrBuffer.length - MAX_STDERR_BYTES);
       }
     } catch {
       // Ignore stderr buffering errors
@@ -676,7 +694,7 @@ export class ProcessIO extends BoundedContext implements Transport {
    */
   private handleStdinError(err: Error): void {
     // EPIPE means process died
-    const error = new BridgeProtocolError(`stdin error: ${err.message}`);
+    const error = new BridgeProtocolError(this.withStderrTail(`stdin error: ${err.message}`));
 
     // Reject all pending writes
     for (const queued of this.writeQueue) {
@@ -697,7 +715,7 @@ export class ProcessIO extends BoundedContext implements Transport {
    * This can occur during pipe errors or when the process crashes.
    */
   private handleStdoutError(err: Error): void {
-    const error = new BridgeProtocolError(`stdout error: ${err.message}`);
+    const error = new BridgeProtocolError(this.withStderrTail(`stdout error: ${err.message}`));
     this.rejectAllPending(error);
     this.markForRestart();
   }
@@ -708,7 +726,7 @@ export class ProcessIO extends BoundedContext implements Transport {
    */
   private handleStderrError(err: Error): void {
     // Stderr errors are less critical but still indicate process health issues
-    const error = new BridgeProtocolError(`stderr error: ${err.message}`);
+    const error = new BridgeProtocolError(this.withStderrTail(`stderr error: ${err.message}`));
     this.rejectAllPending(error);
     this.markForRestart();
   }
@@ -735,14 +753,18 @@ export class ProcessIO extends BoundedContext implements Transport {
       const index = this.writeQueue.indexOf(entry);
       if (index !== -1) {
         this.writeQueue.splice(index, 1);
-        reject(new BridgeTimeoutError(
-          `Write queue timeout: entry waited ${this.writeQueueTimeoutMs}ms without drain`
-        ));
+        reject(
+          new BridgeTimeoutError(
+            `Write queue timeout: entry waited ${this.writeQueueTimeoutMs}ms without drain`
+          )
+        );
       }
     }, this.writeQueueTimeoutMs);
 
-    // Unref the timer so it doesn't keep the process alive
-    entry.timeoutHandle.unref();
+    // Unref the timer so it doesn't keep the process alive (best-effort for non-Node runtimes)
+    if (typeof entry.timeoutHandle.unref === 'function') {
+      entry.timeoutHandle.unref();
+    }
 
     return entry;
   }
@@ -763,7 +785,7 @@ export class ProcessIO extends BoundedContext implements Transport {
   private writeToStdin(data: string): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       if (!this.process?.stdin || this.processExited) {
-        reject(new BridgeProtocolError('Process stdin not available'));
+        reject(new BridgeProtocolError(this.withStderrTail('Process stdin not available')));
         return;
       }
 
@@ -780,14 +802,16 @@ export class ProcessIO extends BoundedContext implements Transport {
         if (canWrite) {
           resolve();
         } else {
-          // Backpressure - queue this write and set draining flag
+          // Backpressure - current write is accepted by Node's stream buffer.
+          // We only pause subsequent writes until "drain".
           this.draining = true;
-          this.writeQueue.push(this.createQueuedWrite(data, resolve, reject));
+          resolve();
         }
       } catch (err) {
         // Synchronous write error (e.g., EPIPE)
         this.markForRestart();
-        reject(new BridgeProtocolError(`Write error: ${err instanceof Error ? err.message : 'unknown'}`));
+        const errorMessage = err instanceof Error ? err.message : 'unknown';
+        reject(new BridgeProtocolError(this.withStderrTail(`Write error: ${errorMessage}`)));
       }
     });
   }
@@ -803,7 +827,7 @@ export class ProcessIO extends BoundedContext implements Transport {
         // Process died - reject all queued writes
         for (const q of this.writeQueue) {
           this.clearQueuedWriteTimeout(q);
-          q.reject(new BridgeProtocolError('Process stdin not available'));
+          q.reject(new BridgeProtocolError(this.withStderrTail('Process stdin not available')));
         }
         this.writeQueue.length = 0;
         this.markForRestart();
@@ -820,9 +844,11 @@ export class ProcessIO extends BoundedContext implements Transport {
 
       // Check for write queue timeout (fallback check, timer should have handled this)
       if (now - queued.queuedAt > this.writeQueueTimeoutMs) {
-        queued.reject(new BridgeTimeoutError(
-          `Write queue timeout: entry waited ${now - queued.queuedAt}ms (limit: ${this.writeQueueTimeoutMs}ms)`
-        ));
+        queued.reject(
+          new BridgeTimeoutError(
+            `Write queue timeout: entry waited ${now - queued.queuedAt}ms (limit: ${this.writeQueueTimeoutMs}ms)`
+          )
+        );
         continue; // Process next entry
       }
 
@@ -832,20 +858,16 @@ export class ProcessIO extends BoundedContext implements Transport {
         if (canWrite) {
           queued.resolve();
         } else {
-          // Still under pressure - put it back with a new timeout
-          this.writeQueue.unshift(this.createQueuedWrite(
-            queued.data,
-            queued.resolve,
-            queued.reject
-          ));
+          // Backpressure - this write has been accepted by stream buffer.
+          // Pause further queued writes until the next "drain" event.
+          queued.resolve();
           this.draining = true;
           return;
         }
       } catch (err) {
         // Synchronous write error (e.g., EPIPE) - reject this and all remaining writes
-        const error = new BridgeProtocolError(
-          `Write error: ${err instanceof Error ? err.message : 'unknown'}`
-        );
+        const errorMessage = err instanceof Error ? err.message : 'unknown';
+        const error = new BridgeProtocolError(this.withStderrTail(`Write error: ${errorMessage}`));
         queued.reject(error);
         for (const q of this.writeQueue) {
           this.clearQueuedWriteTimeout(q);
@@ -869,13 +891,19 @@ export class ProcessIO extends BoundedContext implements Transport {
     return this.stderrBuffer.trim();
   }
 
+  /**
+   * Append stderr context when available.
+   */
+  private withStderrTail(message: string): string {
+    const stderrTail = this.getStderrTail();
+    return stderrTail ? `${message}. Stderr:\n${stderrTail}` : message;
+  }
+
   /**
    * Handle a protocol error by rejecting all pending requests.
    */
   private handleProtocolError(details: string, line?: string): void {
-    const snippet = line
-      ? line.length > 500 ? `${line.slice(0, 500)}...` : line
-      : undefined;
+    const snippet = line ? (line.length > 500 ? `${line.slice(0, 500)}...` : line) : undefined;
 
     const hint = 'Ensure Python code does not print to stdout and bridge outputs only JSON lines.';
 

package/src/runtime/pyodide-io.ts

@@ -16,7 +16,12 @@
 
 import { BoundedContext } from './bounded-context.js';
 import { BridgeExecutionError, BridgeProtocolError } from './errors.js';
-import { PROTOCOL_ID, type Transport, type ProtocolMessage, type ProtocolResponse } from './transport.js';
+import {
+  PROTOCOL_ID,
+  type Transport,
+  type ProtocolMessage,
+  type ProtocolResponse,
+} from './transport.js';
 
 // =============================================================================
 // TYPES
@@ -55,7 +60,7 @@ interface PyodideInstance {
 // =============================================================================
 
 /** Default Pyodide CDN URL */
-const DEFAULT_INDEX_URL = 'https://cdn.jsdelivr.net/pyodide/v0.24.1/full/';
+const DEFAULT_INDEX_URL = 'https://cdn.jsdelivr.net/pyodide/v0.28.0/full/';
 
 /**
  * Bootstrap Python code that sets up the dispatch function.
@@ -70,6 +75,27 @@ import json
 import importlib
 
 __tywrap_instances = {}
+__tywrap_protocol = 'tywrap/1'
+
+def __tywrap_require_str(params, key):
+    value = params.get(key)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f'Missing {key}')
+    return value
+
+def __tywrap_coerce_list(value, key):
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise ValueError(f'Invalid {key}')
+    return value
+
+def __tywrap_coerce_dict(value, key):
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f'Invalid {key}')
+    return value
 
 def __tywrap_dispatch(message_json):
     """
@@ -82,48 +108,76 @@ def __tywrap_dispatch(message_json):
         JSON-encoded ProtocolResponse string
     """
     msg = None
+    msg_id = -1
     try:
         msg = json.loads(message_json)
-        msg_id = msg['id']
-        msg_type = msg['type']
-
-        if msg_type == 'call':
-            mod = importlib.import_module(msg['module'])
-            fn = getattr(mod, msg['functionName'])
-            result = fn(*msg.get('args', []), **msg.get('kwargs', {}))
-            return json.dumps({'id': msg_id, 'result': result})
-
-        elif msg_type == 'instantiate':
-            mod = importlib.import_module(msg['module'])
-            cls = getattr(mod, msg['className'])
-            obj = cls(*msg.get('args', []), **msg.get('kwargs', {}))
+        if not isinstance(msg, dict):
+            raise ValueError('Invalid request payload')
+
+        msg_id = msg.get('id')
+        if not isinstance(msg_id, int):
+            raise ValueError(f'Invalid request id: {msg_id}')
+
+        protocol = msg.get('protocol')
+        if protocol != __tywrap_protocol:
+            raise ValueError(f'Invalid protocol: {protocol}')
+
+        method = msg.get('method')
+        if not isinstance(method, str):
+            raise ValueError('Missing method')
+
+        params = __tywrap_coerce_dict(msg.get('params'), 'params')
+
+        if method == 'call':
+            module_name = __tywrap_require_str(params, 'module')
+            function_name = __tywrap_require_str(params, 'functionName')
+            args = __tywrap_coerce_list(params.get('args'), 'args')
+            kwargs = __tywrap_coerce_dict(params.get('kwargs'), 'kwargs')
+            mod = importlib.import_module(module_name)
+            fn = getattr(mod, function_name)
+            result = fn(*args, **kwargs)
+
+        elif method == 'instantiate':
+            module_name = __tywrap_require_str(params, 'module')
+            class_name = __tywrap_require_str(params, 'className')
+            args = __tywrap_coerce_list(params.get('args'), 'args')
+            kwargs = __tywrap_coerce_dict(params.get('kwargs'), 'kwargs')
+            mod = importlib.import_module(module_name)
+            cls = getattr(mod, class_name)
+            obj = cls(*args, **kwargs)
             handle = str(id(obj))
             __tywrap_instances[handle] = obj
-            return json.dumps({'id': msg_id, 'result': handle})
-
-        elif msg_type == 'call_method':
-            obj = __tywrap_instances[msg['handle']]
-            method = getattr(obj, msg['methodName'])
-            result = method(*msg.get('args', []), **msg.get('kwargs', {}))
-            return json.dumps({'id': msg_id, 'result': result})
-
-        elif msg_type == 'dispose_instance':
-            __tywrap_instances.pop(msg['handle'], None)
-            return json.dumps({'id': msg_id, 'result': None})
+            result = handle
+
+        elif method == 'call_method':
+            handle = __tywrap_require_str(params, 'handle')
+            method_name = __tywrap_require_str(params, 'methodName')
+            args = __tywrap_coerce_list(params.get('args'), 'args')
+            kwargs = __tywrap_coerce_dict(params.get('kwargs'), 'kwargs')
+            if handle not in __tywrap_instances:
+                raise ValueError(f'Unknown instance handle: {handle}')
+            obj = __tywrap_instances[handle]
+            bound_method = getattr(obj, method_name)
+            result = bound_method(*args, **kwargs)
+
+        elif method == 'dispose_instance':
+            handle = __tywrap_require_str(params, 'handle')
+            result = __tywrap_instances.pop(handle, None) is not None
 
         else:
-            return json.dumps({
-                'id': msg_id,
-                'error': {
-                    'type': 'ValueError',
-                    'message': f'Unknown message type: {msg_type}'
-                }
-            })
+            raise ValueError(f'Unknown method: {method}')
+
+        return json.dumps({
+            'id': msg_id,
+            'protocol': __tywrap_protocol,
+            'result': result
+        })
 
     except Exception as e:
         import traceback
         return json.dumps({
-            'id': msg.get('id', 'unknown') if msg else 'unknown',
+            'id': msg_id,
+            'protocol': __tywrap_protocol,
             'error': {
                 'type': type(e).__name__,
                 'message': str(e),
@@ -149,11 +203,10 @@ def __tywrap_dispatch(message_json):
  *
  * const response = await transport.send(
  *   JSON.stringify({
- *     id: '1',
- *     type: 'call',
- *     module: 'math',
- *     functionName: 'sqrt',
- *     args: [16]
+ *     id: 1,
+ *     protocol: 'tywrap/1',
+ *     method: 'call',
+ *     params: { module: 'math', functionName: 'sqrt', args: [16], kwargs: {} }
  *   }),
  *   5000
  * );
@@ -262,7 +315,13 @@ export class PyodideIO extends BoundedContext implements Transport {
         }
 
         // Validate required fields
-        if (!parsed.id || !parsed.method) {
+        if (typeof parsed.id !== 'number' || !Number.isInteger(parsed.id)) {
+          throw new BridgeProtocolError('Message missing required fields: id, method');
+        }
+        if (parsed.protocol !== PROTOCOL_ID || typeof parsed.method !== 'string') {
+          throw new BridgeProtocolError('Message missing required fields: id, method');
+        }
+        if (!parsed.params || typeof parsed.params !== 'object' || Array.isArray(parsed.params)) {
           throw new BridgeProtocolError('Message missing required fields: id, method');
         }
 
@@ -280,6 +339,14 @@ export class PyodideIO extends BoundedContext implements Transport {
           // Validate response is valid JSON
           try {
             const response = JSON.parse(responseJson) as ProtocolResponse;
+            if (typeof response.id !== 'number' || !Number.isInteger(response.id)) {
+              throw new BridgeProtocolError('Invalid response from Python: missing numeric id');
+            }
+            if (response.protocol !== undefined && response.protocol !== PROTOCOL_ID) {
+              throw new BridgeProtocolError(
+                `Invalid protocol version: expected "${PROTOCOL_ID}", got "${response.protocol}"`
+              );
+            }
             if (response.error) {
               // Return the response as-is; let the caller handle the error
               return responseJson;
@@ -449,10 +516,9 @@ export class PyodideIO extends BoundedContext implements Transport {
     const response = JSON.parse(responseJson) as ProtocolResponse;
 
     if (response.error) {
-      const err = new BridgeExecutionError(
-        `${response.error.type}: ${response.error.message}`,
-        { code: response.error.type }
-      );
+      const err = new BridgeExecutionError(`${response.error.type}: ${response.error.message}`, {
+        code: response.error.type,
+      });
       err.traceback = response.error.traceback;
       throw err;
     }