tywrap 0.4.0 → 0.5.0

package/src/runtime/{bridge-protocol.ts → rpc-client.ts}

@@ -1,24 +1,26 @@
 /**
- * BridgeProtocol - Unified abstraction for JS<->Python communication.
+ * RpcClient - the single correlated-RPC client for JS<->Python communication.
  *
- * Combines BoundedContext + SafeCodec + Transport into a single base class
- * that handles all cross-boundary concerns:
- * - Lifecycle management (init/dispose state machine)
- * - Request/response encoding with validation
- * - Transport-agnostic message passing
- * - Bounded execution (timeout, retry, abort)
+ * It HOLDS a Transport and a codec (SafeCodec) and is, in turn, HELD by the
+ * bridge facades (NodeBridge/HttpBridge/PyodideBridge) via composition — it is
+ * NOT a base class bridges extend. It owns the one place where the wire frame
+ * is built and correlated: id generation, {id, protocol} stamping, codec
+ * encode/decode, and transport.send. It composes DisposableBase to obtain its
+ * lifecycle (init/dispose) and bounded execution (timeout/retry/abort), but it
+ * carries no PythonRuntime contract obligation — the facade implements
+ * PythonRuntime and delegates the four RPC methods to this client.
  *
- * Subclasses (NodeBridge, HttpBridge, PyodideBridge) only need to:
- * 1. Create their transport in their constructor
- * 2. Pass it to super() via BridgeProtocolOptions
- * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ * Why composition (not inheritance): inheritance previously forced the RPC
+ * contract onto a lifecycle base, leaking throwing RPC stubs into transports.
+ * Holding one RpcClient keeps exactly one encode/decode/correlation site and
+ * lets transports stay pure byte-movers.
  *
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
 import type { BridgeInfo } from '../types/index.js';
 
-import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { DisposableBase, type ExecuteOptions } from './bounded-context.js';
 import { BridgeProtocolError } from './errors.js';
 import { SafeCodec, type CodecOptions } from './safe-codec.js';
 import { TYWRAP_PROTOCOL_VERSION } from './protocol.js';
@@ -37,9 +39,9 @@ export interface GetBridgeInfoOptions {
 }
 
 /**
- * Configuration options for BridgeProtocol.
+ * Configuration options for RpcClient.
  */
-export interface BridgeProtocolOptions {
+export interface RpcClientOptions {
   /** The transport to use for communication */
   transport: Transport;
 
@@ -174,43 +176,37 @@ function validateBridgeInfoPayload(value: unknown): BridgeInfo {
 }
 
 // =============================================================================
-// BRIDGE PROTOCOL BASE CLASS
+// RPC CLIENT
 // =============================================================================
 
 /**
- * BridgeProtocol combines BoundedContext + SafeCodec + Transport
- * into a unified abstraction for all JS<->Python communication.
- *
- * This class provides:
- * - Automatic transport lifecycle management
- * - Request encoding with guardrails (special float rejection, key validation)
- * - Response decoding with Arrow support
- * - Full RuntimeExecution interface implementation
- *
- * Subclasses should:
- * 1. Create their transport in their constructor
- * 2. Pass it to super() via BridgeProtocolOptions
- * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ * RpcClient holds a SafeCodec + Transport and composes DisposableBase for
+ * lifecycle/bounded-execution. It is the one correlated-RPC client; bridge
+ * facades HOLD an instance and delegate their PythonRuntime methods to it.
  *
  * @example
  * ```typescript
- * class NodeBridge extends BridgeProtocol {
+ * class NodeBridge extends DisposableBase implements PythonRuntime {
+ *   private readonly rpc: RpcClient;
  *   constructor(options: NodeBridgeOptions) {
+ *     super();
  *     const transport = new ProcessIO(options);
- *     super({ transport, defaultTimeoutMs: options.timeout });
+ *     this.rpc = new RpcClient({ transport, defaultTimeoutMs: options.timeout });
+ *     this.trackResource(this.rpc);
  *   }
+ *   // call/instantiate/callMethod/disposeInstance delegate to this.rpc.*
  * }
  * ```
  */
-export class BridgeProtocol extends BoundedContext {
+export class RpcClient extends DisposableBase {
   /** Codec instance for validation and serialization */
-  protected readonly codec: SafeCodec;
+  readonly codec: SafeCodec;
 
   /** Transport instance for message passing */
-  protected readonly transport: Transport;
+  readonly transport: Transport;
 
   /** Default timeout for operations in milliseconds */
-  protected readonly defaultTimeoutMs: number;
+  readonly defaultTimeoutMs: number;
 
   /** Counter for generating unique request IDs */
   private requestId = 0;
@@ -219,11 +215,11 @@ export class BridgeProtocol extends BoundedContext {
   private bridgeInfoCache?: BridgeInfo;
 
   /**
-   * Create a new BridgeProtocol instance.
+   * Create a new RpcClient instance.
    *
    * @param options - Configuration options including transport and codec settings
    */
-  constructor(options: BridgeProtocolOptions) {
+  constructor(options: RpcClientOptions) {
     super();
     this.codec = new SafeCodec(options.codec);
     this.transport = options.transport;
@@ -238,26 +234,22 @@ export class BridgeProtocol extends BoundedContext {
   // ===========================================================================
 
   /**
-   * Initialize the protocol.
-   *
-   * Initializes the underlying transport. Subclasses can override this
-   * to add additional initialization logic, but must call super.doInit().
+   * Initialize the client by initializing the underlying transport.
+   * Driven by the holding facade's lifecycle (facade.init() -> rpc.init()).
    */
   protected async doInit(): Promise<void> {
     await this.transport.init();
   }
 
   /**
-   * Dispose the protocol.
+   * Dispose the client.
    *
-   * The transport is tracked as a resource and will be disposed automatically
-   * by BoundedContext. Subclasses can override this to add additional cleanup,
-   * but should not need to dispose the transport manually.
+   * The transport is tracked as a resource and is disposed automatically by
+   * DisposableBase. Here we only clear the cached bridge info.
    */
   protected async doDispose(): Promise<void> {
     this.bridgeInfoCache = undefined;
-    // Transport is tracked and will be disposed by BoundedContext
-    // Subclasses can override to add additional cleanup
+    // Transport is tracked and will be disposed by DisposableBase.
   }
 
   // ===========================================================================
@@ -281,7 +273,7 @@ export class BridgeProtocol extends BoundedContext {
    * @throws BridgeExecutionError if Python returns an error
    * @throws BridgeTimeoutError if the operation times out
    */
-  protected async sendMessage<T>(
+  async sendMessage<T>(
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     options?: ExecuteOptions<T>
   ): Promise<T> {
@@ -321,7 +313,7 @@ export class BridgeProtocol extends BoundedContext {
    * @throws BridgeExecutionError if Python returns an error
    * @throws BridgeTimeoutError if the operation times out
    */
-  protected async sendMessageAsync<T>(
+  async sendMessageAsync<T>(
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     options?: ExecuteOptions<T>
   ): Promise<T> {
@@ -347,6 +339,41 @@ export class BridgeProtocol extends BoundedContext {
     }, options);
   }
 
+  /**
+   * Send a message over an EXPLICIT transport (not this.transport) with the
+   * same id-generation + codec encode/decode as the normal send path, but
+   * WITHOUT this.execute() and WITHOUT auto-init.
+   *
+   * This is the warmup path: NodeBridge runs warmup commands inside
+   * transport.init() (worker spawn -> onWorkerReady), which happens DURING
+   * rpc.init(). Routing those through this.execute() would auto-init this same
+   * client and re-await the in-flight init() that is itself waiting on warmup,
+   * deadlocking. So sendOn deliberately skips lifecycle: it only unifies the
+   * id counter + codec, never the state machine.
+   *
+   * @param transport - The specific worker transport to send on
+   * @param message - The protocol message (without id/protocol; stamped here)
+   * @param opts - Optional timeout / abort signal
+   */
+  async sendOn<T>(
+    transport: Transport,
+    message: Omit<ProtocolMessage, 'id' | 'protocol'>,
+    opts?: { timeoutMs?: number; signal?: AbortSignal }
+  ): Promise<T> {
+    const fullMessage: ProtocolMessage = {
+      ...message,
+      id: this.generateId(),
+      protocol: PROTOCOL_ID,
+    };
+    const encoded = this.codec.encodeRequest(fullMessage);
+    const responseStr = await transport.send(
+      encoded,
+      opts?.timeoutMs ?? this.defaultTimeoutMs,
+      opts?.signal
+    );
+    return this.codec.decodeResponseAsync<T>(responseStr);
+  }
+
   /**
    * Generate a unique request ID.
    *
@@ -358,7 +385,7 @@ export class BridgeProtocol extends BoundedContext {
   }
 
   // ===========================================================================
-  // RUNTIME EXECUTION INTERFACE
+  // RPC METHODS (delegated to by the facade's PythonRuntime implementation)
   // ===========================================================================
 
   /**

package/src/runtime/worker-pool.ts

@@ -7,7 +7,7 @@
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
-import { BoundedContext } from './bounded-context.js';
+import { DisposableBase } from './bounded-context.js';
 import { BridgeTimeoutError, BridgeExecutionError, BridgeProtocolError } from './errors.js';
 import type { Transport } from './transport.js';
 
@@ -105,7 +105,7 @@ interface QueuedWaiter {
  * await pool.dispose();
  * ```
  */
-export class WorkerPool extends BoundedContext {
+export class WorkerPool extends DisposableBase {
   private readonly options: Omit<
     Required<WorkerPoolOptions>,
     'onWorkerReady' | 'onReplacementWorkerReady'
@@ -535,60 +535,4 @@ export class WorkerPool extends BoundedContext {
       this.waitQueue.push({ resolve, reject, timer });
     });
   }
-
-  // ===========================================================================
-  // RUNTIME EXECUTION (Not implemented - WorkerPool is just for worker management)
-  // ===========================================================================
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   * Use the BridgeProtocol layer with a pooled worker's transport.
-   */
-  async call<T = unknown>(
-    _module: string,
-    _functionName: string,
-    _args: unknown[],
-    _kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement call() - use withWorker() to get a transport'
-    );
-  }
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   */
-  async instantiate<T = unknown>(
-    _module: string,
-    _className: string,
-    _args: unknown[],
-    _kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement instantiate() - use withWorker() to get a transport'
-    );
-  }
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   */
-  async callMethod<T = unknown>(
-    _handle: string,
-    _methodName: string,
-    _args: unknown[],
-    _kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement callMethod() - use withWorker() to get a transport'
-    );
-  }
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   */
-  async disposeInstance(_handle: string): Promise<void> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement disposeInstance() - use withWorker() to get a transport'
-    );
-  }
 }

package/src/types/index.ts

@@ -364,12 +364,16 @@ export interface TypeMappingConfig {
   presets?: TypePreset[];
 }
 
+/** Known bridge backends. Each speaks the identical "tywrap/1" protocol. */
+export type BridgeBackend = 'python-subprocess' | 'pyodide' | 'http';
+
 export interface BridgeInfo {
   protocol: string;
   protocolVersion: number;
-  bridge: 'python-subprocess';
+  bridge: BridgeBackend;
   pythonVersion: string;
-  pid: number;
+  /** OS process id for subprocess backends; null for in-WASM (Pyodide). */
+  pid: number | null;
   codecFallback: 'json' | 'none';
   arrowAvailable: boolean;
   scipyAvailable: boolean;
@@ -424,8 +428,14 @@ export interface GenerationMetadata {
   optimizations: string[];
 }
 
-// Runtime bridge interface
-export interface RuntimeExecution {
+// PythonRuntime — the four cross-boundary RPC methods generated wrappers call.
+// This is the contract that, after the composition rework, is implemented ONLY
+// by the bridge facades (NodeBridge/HttpBridge/PyodideBridge); the facades
+// satisfy it by delegating to an owned RpcClient. It deliberately carries NO
+// lifecycle method — dispose() is a separate lifecycle concern (see Disposable
+// in runtime/disposable.ts), so transports and the lifecycle base class
+// (DisposableBase) never have to stub these methods.
+export interface PythonRuntime {
   call<T = unknown>(
     module: string,
     functionName: string,
@@ -448,7 +458,13 @@ export interface RuntimeExecution {
   ): Promise<T>;
 
   disposeInstance(handle: string): Promise<void>;
+}
 
+// Runtime bridge interface — the four RPC methods plus lifecycle dispose().
+// Kept as PythonRuntime + dispose() so getRuntimeBridge() and every existing
+// `RuntimeExecution` reference (registry, dev.ts) compile with zero churn. The
+// RuntimeExecution -> PythonRuntime symbol rename is deferred to the T9 pass.
+export interface RuntimeExecution extends PythonRuntime {
   dispose(): Promise<void>;
 }
 

package/dist/runtime/bridge-core.d.ts

@@ -1,65 +0,0 @@
-import { BridgeProtocolError, BridgeTimeoutError } from './errors.js';
-export type RpcMethod = 'call' | 'instantiate' | 'call_method' | 'dispose_instance' | 'meta';
-export interface RpcRequest {
-    id: number;
-    protocol: string;
-    method: RpcMethod;
-    params: unknown;
-}
-export interface RpcResponse<T = unknown> {
-    id: number;
-    protocol: string;
-    result?: T;
-    error?: {
-        type: string;
-        message: string;
-        traceback?: string;
-    };
-}
-export interface BridgeCoreTransport {
-    write: (data: string) => void;
-}
-export interface BridgeCoreOptions {
-    timeoutMs: number;
-    maxLineLength?: number;
-    maxStderrBytes?: number;
-    protocol?: string;
-    protocolVersion?: number;
-    decodeValue?: (value: unknown) => Promise<unknown>;
-    onFatalError?: (error: BridgeProtocolError) => void;
-    onTimeout?: (error: BridgeTimeoutError) => void;
-}
-export declare class BridgeCore {
-    private readonly transport;
-    private readonly options;
-    private readonly timedOutRequests;
-    private readonly pending;
-    private nextId;
-    private stdoutBuffer;
-    private stderrBuffer;
-    private protocolError;
-    constructor(transport: BridgeCoreTransport, options: BridgeCoreOptions);
-    getStderrTail(): string;
-    getPendingCount(): number;
-    clear(): void;
-    send<T>(payload: Omit<RpcRequest, 'id' | 'protocol'>): Promise<T>;
-    handleStdoutData(chunk: Buffer | string): void;
-    handleStderrData(chunk: Buffer | string): void;
-    handleProcessExit(): void;
-    handleProcessError(err: Error): void;
-    private handleResponseLine;
-    private errorFrom;
-    private normalizeErrorPayload;
-    private describeInvalidErrorPayload;
-    private failRequest;
-    private rejectAll;
-    private handleProtocolError;
-    private handleFatalError;
-}
-export declare function validateBridgeInfo(info: unknown): void;
-export declare function getPathKey(...envs: Array<Record<string, string | undefined>>): string;
-export declare function ensurePythonEncoding(env: NodeJS.ProcessEnv): void;
-export declare function ensureJsonFallback(env: NodeJS.ProcessEnv, enabled: boolean): void;
-export declare function getMaxLineLengthFromEnv(env: NodeJS.ProcessEnv): number | undefined;
-export declare function normalizeEnv(baseEnv: Record<string, string | undefined>, overrides: Record<string, string | undefined>): NodeJS.ProcessEnv;
-//# sourceMappingURL=bridge-core.d.ts.map

package/dist/runtime/bridge-core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bridge-core.d.ts","sourceRoot":"","sources":["../../src/runtime/bridge-core.ts"],"names":[],"mappings":"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"}