tywrap 0.6.0 → 0.7.0

package/src/runtime/base-bridge.ts

@@ -0,0 +1,106 @@
+/**
+ * BasePythonBridge - shared RPC delegation for the bridge facades.
+ *
+ * The three bridge facades (NodeBridge/HttpBridge/PyodideBridge) all extend
+ * DisposableBase (lifecycle/resources) and implement PythonRuntime by HOLDING
+ * an RpcClient. The PythonRuntime delegation was byte-identical across all
+ * three: each method does `await this.ensureReady()` then forwards to the held
+ * RpcClient. This base collapses that duplication onto a single
+ * `getRpcClient()` accessor while leaving each facade free to own its own
+ * RpcClient field (for constructor wiring, resource tracking, and — in
+ * NodeBridge's case — a caching override of call()).
+ *
+ * It carries no transport/codec/lifecycle specifics: doInit/doDispose remain
+ * abstract on DisposableBase and stay per-facade.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+
+import type { PythonRuntime, BridgeInfo } from '../types/index.js';
+
+import { DisposableBase } from './bounded-context.js';
+import type { RpcClient, GetBridgeInfoOptions } from './rpc-client.js';
+import type { TransportCapabilities } from './transport.js';
+
+/**
+ * Shared base for the bridge facades. Implements the PythonRuntime RPC
+ * delegation (plus getBridgeInfo) over a single held RpcClient, exposed by the
+ * abstract {@link getRpcClient} accessor. Lifecycle (doInit/doDispose) and the
+ * RpcClient's construction/ownership remain the subclass's responsibility.
+ */
+export abstract class BasePythonBridge extends DisposableBase implements PythonRuntime {
+  /**
+   * Return the held RpcClient that the shared delegating methods forward to.
+   * Subclasses construct, track, and own the RpcClient; this accessor lets the
+   * base reach it without dictating how it is stored.
+   */
+  protected abstract getRpcClient(): RpcClient;
+
+  // ===========================================================================
+  // RPC METHODS (delegate to the held RpcClient)
+  // ===========================================================================
+
+  async call<T = unknown>(
+    module: string,
+    functionName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    return this.getRpcClient().call<T>(module, functionName, args, kwargs);
+  }
+
+  async instantiate<T = unknown>(
+    module: string,
+    className: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    return this.getRpcClient().instantiate<T>(module, className, args, kwargs);
+  }
+
+  async callMethod<T = unknown>(
+    handle: string,
+    methodName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    return this.getRpcClient().callMethod<T>(handle, methodName, args, kwargs);
+  }
+
+  async disposeInstance(handle: string): Promise<void> {
+    await this.ensureReady();
+    return this.getRpcClient().disposeInstance(handle);
+  }
+
+  /**
+   * Fetch bridge diagnostics and feature availability.
+   */
+  async getBridgeInfo(options?: GetBridgeInfoOptions): Promise<BridgeInfo> {
+    await this.ensureReady();
+    return this.getRpcClient().getBridgeInfo(options);
+  }
+
+  /**
+   * Describe this backend's transport-level capabilities (Arrow/binary/chunking/
+   * streaming support, max frame size). The descriptor is static and does NOT
+   * depend on lifecycle state, so this intentionally does not `ensureReady()` —
+   * callers can query it before connecting to decide how to use the bridge.
+   */
+  capabilities(): TransportCapabilities {
+    return this.getRpcClient().capabilities();
+  }
+
+  /**
+   * Ensure the facade is initialized before delegating an RPC. Replicates the
+   * auto-init that the bounded execute path provided pre-composition, so the
+   * facade's own doInit pre-work runs before any RPC.
+   */
+  protected async ensureReady(): Promise<void> {
+    if (!this.isReady) {
+      await this.init();
+    }
+  }
+}

package/src/runtime/bridge-codec.ts

@@ -410,6 +410,60 @@ export class BridgeCodec {
     return bridgeError;
   }
 
+  /**
+   * Shared prelude for both decode paths: size guard, JSON parse (with bytes
+   * revival), protocol-version validation, and RPC-envelope unwrapping.
+   *
+   * Behavior-preserving extraction of the common head of decodeResponse and
+   * decodeResponseAsync; the only divergence between the two is what they do
+   * with the returned result (sync returns it as-is, async applies Arrow
+   * decoding) and so that divergence stays in the callers.
+   */
+  private parseResponseResult(payload: string): unknown {
+    // Check payload size first
+    const payloadBytes = new TextEncoder().encode(payload).length;
+    if (payloadBytes > this.maxPayloadBytes) {
+      throw new BridgeCodecError(
+        `Response payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`,
+        { codecPhase: 'decode', valueType: 'payload' }
+      );
+    }
+
+    // Parse JSON
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(payload, this.reviveValueBound);
+    } catch (err) {
+      if (err instanceof BridgeCodecError || err instanceof BridgeProtocolError) {
+        throw err;
+      }
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      throw new BridgeCodecError(
+        `JSON parse failed: ${errorMessage}. Payload snippet: ${summarizePayloadForError(payload)}`,
+        { codecPhase: 'decode', valueType: 'json' }
+      );
+    }
+
+    // Validate protocol version (if present)
+    validateProtocolVersion(parsed);
+
+    return this.extractResultFromRpcResponse(parsed);
+  }
+
+  /**
+   * Post-decode guard: reject non-finite numbers (NaN/Infinity) when enabled.
+   * Shared by both decode paths.
+   */
+  private assertNoSpecialFloats(value: unknown): void {
+    if (this.rejectSpecialFloats && containsSpecialFloat(value)) {
+      const floatPath = findSpecialFloatPath(value);
+      throw new BridgeCodecError(
+        `Response contains non-finite number (NaN or Infinity) at ${floatPath}`,
+        { codecPhase: 'decode', valueType: 'number' }
+      );
+    }
+  }
+
   private extractResultFromRpcResponse(parsed: unknown): unknown {
     if (isRpcResponse(parsed)) {
       const response = parsed;
@@ -526,43 +580,10 @@ export class BridgeCodec {
    * @throws BridgeExecutionError if response contains a Python error
    */
   decodeResponse<T>(payload: string): T {
-    // Check payload size first
-    const payloadBytes = new TextEncoder().encode(payload).length;
-    if (payloadBytes > this.maxPayloadBytes) {
-      throw new BridgeCodecError(
-        `Response payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`,
-        { codecPhase: 'decode', valueType: 'payload' }
-      );
-    }
-
-    // Parse JSON
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(payload, this.reviveValueBound);
-    } catch (err) {
-      if (err instanceof BridgeCodecError || err instanceof BridgeProtocolError) {
-        throw err;
-      }
-      const errorMessage = err instanceof Error ? err.message : String(err);
-      throw new BridgeCodecError(
-        `JSON parse failed: ${errorMessage}. Payload snippet: ${summarizePayloadForError(payload)}`,
-        { codecPhase: 'decode', valueType: 'json' }
-      );
-    }
-
-    // Validate protocol version (if present)
-    validateProtocolVersion(parsed);
-
-    const result = this.extractResultFromRpcResponse(parsed);
+    const result = this.parseResponseResult(payload);
 
     // Post-decode validation for special floats if enabled
-    if (this.rejectSpecialFloats && containsSpecialFloat(result)) {
-      const floatPath = findSpecialFloatPath(result);
-      throw new BridgeCodecError(
-        `Response contains non-finite number (NaN or Infinity) at ${floatPath}`,
-        { codecPhase: 'decode', valueType: 'number' }
-      );
-    }
+    this.assertNoSpecialFloats(result);
 
     return result as T;
   }
@@ -578,34 +599,7 @@ export class BridgeCodec {
    * @throws BridgeExecutionError if response contains a Python error
    */
   async decodeResponseAsync<T>(payload: string): Promise<T> {
-    // Check payload size first
-    const payloadBytes = new TextEncoder().encode(payload).length;
-    if (payloadBytes > this.maxPayloadBytes) {
-      throw new BridgeCodecError(
-        `Response payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`,
-        { codecPhase: 'decode', valueType: 'payload' }
-      );
-    }
-
-    // Parse JSON
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(payload, this.reviveValueBound);
-    } catch (err) {
-      if (err instanceof BridgeCodecError || err instanceof BridgeProtocolError) {
-        throw err;
-      }
-      const errorMessage = err instanceof Error ? err.message : String(err);
-      throw new BridgeCodecError(
-        `JSON parse failed: ${errorMessage}. Payload snippet: ${summarizePayloadForError(payload)}`,
-        { codecPhase: 'decode', valueType: 'json' }
-      );
-    }
-
-    // Validate protocol version (if present)
-    validateProtocolVersion(parsed);
-
-    const result = this.extractResultFromRpcResponse(parsed);
+    const result = this.parseResponseResult(payload);
 
     // Apply Arrow decoding to the result
     let decoded: unknown;
@@ -621,13 +615,7 @@ export class BridgeCodec {
 
     // Post-decode validation for special floats if enabled
     // Note: Arrow decoders can introduce NaN/Infinity from binary representations.
-    if (this.rejectSpecialFloats && containsSpecialFloat(decoded)) {
-      const floatPath = findSpecialFloatPath(decoded);
-      throw new BridgeCodecError(
-        `Response contains non-finite number (NaN or Infinity) at ${floatPath}`,
-        { codecPhase: 'decode', valueType: 'number' }
-      );
-    }
+    this.assertNoSpecialFloats(decoded);
 
     return decoded as T;
   }

package/src/runtime/http-transport.ts

@@ -13,7 +13,7 @@ import {
   BridgeProtocolError,
   BridgeTimeoutError,
 } from './errors.js';
-import type { Transport } from './transport.js';
+import type { Transport, TransportCapabilities } from './transport.js';
 
 // =============================================================================
 // OPTIONS
@@ -111,6 +111,26 @@ export class HttpTransport implements Transport {
     return !this._isDisposed;
   }
 
+  /**
+   * Static capability descriptor for the HTTP backend.
+   *
+   * The Python server can return Arrow IPC and arbitrary binary (bytes
+   * envelopes) in the HTTP response body. Chunking/streaming are not implemented
+   * (0.8.0). HTTP imposes no transport-level frame ceiling — the whole body is
+   * read in one shot — so `maxFrameBytes` is `Number.POSITIVE_INFINITY` (a higher
+   * layer, e.g. the codec payload limit, may still cap the size).
+   */
+  capabilities(): TransportCapabilities {
+    return {
+      backend: 'http',
+      supportsArrow: true,
+      supportsBinary: true,
+      supportsChunking: false,
+      supportsStreaming: false,
+      maxFrameBytes: Number.POSITIVE_INFINITY,
+    };
+  }
+
   // ===========================================================================
   // SEND
   // ===========================================================================

package/src/runtime/http.ts

@@ -8,11 +8,10 @@
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
-import type { PythonRuntime, BridgeInfo } from '../types/index.js';
 import { autoRegisterArrowDecoder } from '../utils/codec.js';
 
-import { DisposableBase } from './bounded-context.js';
-import { RpcClient, type GetBridgeInfoOptions } from './rpc-client.js';
+import { BasePythonBridge } from './base-bridge.js';
+import { RpcClient } from './rpc-client.js';
 import { HttpTransport } from './http-transport.js';
 import type { CodecOptions } from './bridge-codec.js';
 
@@ -65,7 +64,7 @@ export interface HttpBridgeOptions {
  * await bridge.dispose();
  * ```
  */
-export class HttpBridge extends DisposableBase implements PythonRuntime {
+export class HttpBridge extends BasePythonBridge {
   private readonly rpc: RpcClient;
 
   /**
@@ -110,56 +109,13 @@ export class HttpBridge extends DisposableBase implements PythonRuntime {
   }
 
   // ===========================================================================
-  // RPC METHODS (delegate to the held RpcClient)
+  // RPC DELEGATION (the held RpcClient)
   // ===========================================================================
 
-  async call<T = unknown>(
-    module: string,
-    functionName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.rpc.call<T>(module, functionName, args, kwargs);
-  }
-
-  async instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.rpc.instantiate<T>(module, className, args, kwargs);
-  }
-
-  async callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.rpc.callMethod<T>(handle, methodName, args, kwargs);
-  }
-
-  async disposeInstance(handle: string): Promise<void> {
-    await this.ensureReady();
-    return this.rpc.disposeInstance(handle);
-  }
-
-  async getBridgeInfo(options?: GetBridgeInfoOptions): Promise<BridgeInfo> {
-    await this.ensureReady();
-    return this.rpc.getBridgeInfo(options);
-  }
-
   /**
-   * Ensure the facade is initialized before delegating an RPC, replicating the
-   * auto-init that the bounded execute path provided pre-composition.
+   * Expose the held RpcClient to BasePythonBridge's shared delegating methods.
    */
-  private async ensureReady(): Promise<void> {
-    if (!this.isReady) {
-      await this.init();
-    }
+  protected getRpcClient(): RpcClient {
+    return this.rpc;
   }
 }

package/src/runtime/index.ts

@@ -15,6 +15,7 @@ export { BridgeCodec, type CodecOptions } from './bridge-codec.js';
 // Transport contract — abstract I/O channel interface and guards
 export type {
   Transport,
+  TransportCapabilities,
   TransportOptions,
   ProtocolMessage,
   ProtocolResponse,

package/src/runtime/node.ts

@@ -13,14 +13,13 @@ import { delimiter, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 
-import type { PythonRuntime, BridgeInfo } from '../types/index.js';
 import { autoRegisterArrowDecoder } from '../utils/codec.js';
 import { getDefaultPythonPath } from '../utils/python.js';
 import { getVenvBinDir, getVenvPythonExe } from '../utils/runtime.js';
 import { globalCache } from '../utils/cache.js';
 
-import { DisposableBase } from './bounded-context.js';
-import { RpcClient, type GetBridgeInfoOptions } from './rpc-client.js';
+import { BasePythonBridge } from './base-bridge.js';
+import { RpcClient } from './rpc-client.js';
 import { BridgeCodecError, BridgeExecutionError, BridgeProtocolError } from './errors.js';
 import { SubprocessTransport } from './subprocess-transport.js';
 import { PooledTransport } from './pooled-transport.js';
@@ -305,7 +304,7 @@ function normalizeWarmupCommands(commands: NodeBridgeOptions['warmupCommands']):
  * await pooledBridge.init();
  * ```
  */
-export class NodeBridge extends DisposableBase implements PythonRuntime {
+export class NodeBridge extends BasePythonBridge {
   private readonly resolvedOptions: ResolvedOptions;
   private readonly pooledTransport: PooledTransport;
   private readonly rpc: RpcClient;
@@ -433,16 +432,26 @@ export class NodeBridge extends DisposableBase implements PythonRuntime {
   }
 
   // ===========================================================================
-  // RPC METHODS (delegate to the held RpcClient)
+  // RPC DELEGATION (the held RpcClient)
   // ===========================================================================
 
+  /**
+   * Expose the held RpcClient to BasePythonBridge's shared delegating methods
+   * (instantiate/callMethod/disposeInstance/getBridgeInfo). call() is
+   * overridden below to layer caching on top.
+   */
+  protected getRpcClient(): RpcClient {
+    return this.rpc;
+  }
+
   /**
    * Call a Python function, with optional result caching.
    *
-   * Cache lookup stays FIRST so cache hits return without forcing init,
-   * preserving the pre-composition behavior.
+   * Overrides BasePythonBridge.call() to layer the cache lookup/writeback on
+   * top of the shared delegation. Cache lookup stays FIRST so cache hits return
+   * without forcing init, preserving the pre-composition behavior.
    */
-  async call<T = unknown>(
+  override async call<T = unknown>(
     module: string,
     functionName: string,
     args: unknown[],
@@ -479,50 +488,6 @@ export class NodeBridge extends DisposableBase implements PythonRuntime {
     return this.rpc.call<T>(module, functionName, args, kwargs);
   }
 
-  async instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.rpc.instantiate<T>(module, className, args, kwargs);
-  }
-
-  async callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.rpc.callMethod<T>(handle, methodName, args, kwargs);
-  }
-
-  async disposeInstance(handle: string): Promise<void> {
-    await this.ensureReady();
-    return this.rpc.disposeInstance(handle);
-  }
-
-  /**
-   * Fetch bridge diagnostics and feature availability.
-   */
-  async getBridgeInfo(options?: GetBridgeInfoOptions): Promise<BridgeInfo> {
-    await this.ensureReady();
-    return this.rpc.getBridgeInfo(options);
-  }
-
-  /**
-   * Ensure the facade is initialized before delegating an RPC. Replicates the
-   * auto-init that BoundedContext.execute() gave for free, so the facade's
-   * own doInit pre-work (script check, Arrow decoder) runs before any RPC.
-   */
-  private async ensureReady(): Promise<void> {
-    if (!this.isReady) {
-      await this.init();
-    }
-  }
-
   // ===========================================================================
   // POOL STATISTICS
   // ===========================================================================

package/src/runtime/pooled-transport.ts

@@ -10,7 +10,7 @@
 
 import { DisposableBase } from './bounded-context.js';
 import { BridgeDisposedError, BridgeExecutionError } from './errors.js';
-import type { Transport } from './transport.js';
+import type { Transport, TransportCapabilities } from './transport.js';
 import { TransportPool, type TransportLease } from './transport-pool.js';
 
 // =============================================================================
@@ -21,7 +21,13 @@ import { TransportPool, type TransportLease } from './transport-pool.js';
  * Options for creating a PooledTransport.
  */
 export interface PooledTransportOptions {
-  /** Factory function to create transports for each worker */
+  /**
+   * Factory function to create transports for each worker.
+   *
+   * Construction MUST be side-effect-free — spawn processes/open connections in
+   * `init()`/`send()`, never in the constructor. The pool may build a probe
+   * instance solely to read its {@link Transport.capabilities} descriptor.
+   */
   createTransport: () => Transport;
 
   /** Maximum number of workers in the pool. Default: 1 */
@@ -91,6 +97,8 @@ export class PooledTransport extends DisposableBase implements Transport {
     onReplacementWorkerReady?: (worker: TransportLease) => Promise<void>;
   };
   private pool?: TransportPool;
+  /** Memoized capability descriptor — built at most once (see {@link capabilities}). */
+  private cachedCapabilities?: TransportCapabilities;
 
   /**
    * Create a new PooledTransport.
@@ -181,6 +189,21 @@ export class PooledTransport extends DisposableBase implements Transport {
     });
   }
 
+  /**
+   * Static capability descriptor for the pool.
+   *
+   * A pool's wire behavior is exactly that of the workers it distributes across,
+   * so this reads the descriptor from one probe transport built by the same
+   * factory. `createTransport` MUST be construction-side-effect-free — the
+   * built-in transports spawn nothing until `init()`/`send()`. The result is
+   * memoized so at most one probe is ever built regardless of call count, and
+   * this stays safe to call at any lifecycle point.
+   */
+  capabilities(): TransportCapabilities {
+    this.cachedCapabilities ??= this.poolOptions.createTransport().capabilities();
+    return this.cachedCapabilities;
+  }
+
   // ===========================================================================
   // POOL STATISTICS
   // ===========================================================================