tywrap 0.2.0 → 0.2.1

package/src/runtime/bridge-protocol.ts

@@ -0,0 +1,319 @@
+/**
+ * BridgeProtocol - Unified abstraction 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)
+ *
+ * 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
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+
+import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { SafeCodec, type CodecOptions } from './safe-codec.js';
+import { PROTOCOL_ID, type Transport, type ProtocolMessage } from './transport.js';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Configuration options for BridgeProtocol.
+ */
+export interface BridgeProtocolOptions {
+  /** The transport to use for communication */
+  transport: Transport;
+
+  /** Codec options for validation/serialization */
+  codec?: CodecOptions;
+
+  /** Default timeout for operations in ms. Default: 30000 (30s) */
+  defaultTimeoutMs?: number;
+}
+
+// =============================================================================
+// BRIDGE PROTOCOL BASE CLASS
+// =============================================================================
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * class NodeBridge extends BridgeProtocol {
+ *   constructor(options: NodeBridgeOptions) {
+ *     const transport = new ProcessIO(options);
+ *     super({ transport, defaultTimeoutMs: options.timeout });
+ *   }
+ * }
+ * ```
+ */
+export class BridgeProtocol extends BoundedContext {
+  /** Codec instance for validation and serialization */
+  protected readonly codec: SafeCodec;
+
+  /** Transport instance for message passing */
+  protected readonly transport: Transport;
+
+  /** Default timeout for operations in milliseconds */
+  protected readonly defaultTimeoutMs: number;
+
+  /** Counter for generating unique request IDs */
+  private requestId = 0;
+
+  /**
+   * Create a new BridgeProtocol instance.
+   *
+   * @param options - Configuration options including transport and codec settings
+   */
+  constructor(options: BridgeProtocolOptions) {
+    super();
+    this.codec = new SafeCodec(options.codec);
+    this.transport = options.transport;
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
+
+    // Track the transport for automatic cleanup during dispose
+    this.trackResource(this.transport);
+  }
+
+  // ===========================================================================
+  // LIFECYCLE
+  // ===========================================================================
+
+  /**
+   * Initialize the protocol.
+   *
+   * Initializes the underlying transport. Subclasses can override this
+   * to add additional initialization logic, but must call super.doInit().
+   */
+  protected async doInit(): Promise<void> {
+    await this.transport.init();
+  }
+
+  /**
+   * Dispose the protocol.
+   *
+   * 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.
+   */
+  protected async doDispose(): Promise<void> {
+    // Transport is tracked and will be disposed by BoundedContext
+    // Subclasses can override to add additional cleanup
+  }
+
+  // ===========================================================================
+  // MESSAGE SENDING
+  // ===========================================================================
+
+  /**
+   * Send a protocol message and receive a typed response.
+   *
+   * This method:
+   * 1. Generates a unique request ID
+   * 2. Encodes the request with validation (special float rejection, etc.)
+   * 3. Sends via transport with timeout/abort support
+   * 4. Decodes and validates the response
+   *
+   * @param message - The protocol message (without id field)
+   * @param options - Execution options (timeout, retries, validation)
+   * @returns The typed response from Python
+   *
+   * @throws BridgeProtocolError if encoding/decoding fails
+   * @throws BridgeExecutionError if Python returns an error
+   * @throws BridgeTimeoutError if the operation times out
+   */
+  protected async sendMessage<T>(
+    message: Omit<ProtocolMessage, 'id' | 'protocol'>,
+    options?: ExecuteOptions<T>
+  ): Promise<T> {
+    const fullMessage: ProtocolMessage = {
+      ...message,
+      id: this.generateId(),
+      protocol: PROTOCOL_ID,
+    };
+
+    return this.execute(async () => {
+      // 1. Encode request (validates args)
+      const encoded = this.codec.encodeRequest(fullMessage);
+
+      // 2. Send via transport
+      const responseStr = await this.transport.send(
+        encoded,
+        options?.timeoutMs ?? this.defaultTimeoutMs,
+        options?.signal
+      );
+
+      // 3. Decode response (validates result)
+      return this.codec.decodeResponse<T>(responseStr);
+    }, options);
+  }
+
+  /**
+   * Async version that uses decodeResponseAsync for Arrow support.
+   *
+   * Use this method when the response may contain encoded DataFrames,
+   * ndarrays, or other Arrow-encoded data structures.
+   *
+   * @param message - The protocol message (without id field)
+   * @param options - Execution options (timeout, retries, validation)
+   * @returns The typed response from Python with Arrow decoding applied
+   *
+   * @throws BridgeProtocolError if encoding/decoding fails
+   * @throws BridgeExecutionError if Python returns an error
+   * @throws BridgeTimeoutError if the operation times out
+   */
+  protected async sendMessageAsync<T>(
+    message: Omit<ProtocolMessage, 'id' | 'protocol'>,
+    options?: ExecuteOptions<T>
+  ): Promise<T> {
+    const fullMessage: ProtocolMessage = {
+      ...message,
+      id: this.generateId(),
+      protocol: PROTOCOL_ID,
+    };
+
+    return this.execute(async () => {
+      // 1. Encode request (validates args)
+      const encoded = this.codec.encodeRequest(fullMessage);
+
+      // 2. Send via transport
+      const responseStr = await this.transport.send(
+        encoded,
+        options?.timeoutMs ?? this.defaultTimeoutMs,
+        options?.signal
+      );
+
+      // 3. Decode response with Arrow support
+      return this.codec.decodeResponseAsync<T>(responseStr);
+    }, options);
+  }
+
+  /**
+   * Generate a unique request ID.
+   *
+   * Returns a monotonically increasing integer that ensures uniqueness
+   * within a process lifetime.
+   */
+  private generateId(): number {
+    return ++this.requestId;
+  }
+
+  // ===========================================================================
+  // RUNTIME EXECUTION INTERFACE
+  // ===========================================================================
+
+  /**
+   * Call a Python function.
+   *
+   * @param module - Python module path (e.g., 'numpy', 'mypackage.submodule')
+   * @param functionName - Function name to call
+   * @param args - Positional arguments
+   * @param kwargs - Keyword arguments
+   * @returns The function result
+   */
+  async call<T = unknown>(
+    module: string,
+    functionName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    return this.sendMessageAsync<T>({
+      method: 'call',
+      params: {
+        module,
+        functionName,
+        args,
+        kwargs,
+      },
+    });
+  }
+
+  /**
+   * Instantiate a Python class.
+   *
+   * @param module - Python module path containing the class
+   * @param className - Class name to instantiate
+   * @param args - Positional constructor arguments
+   * @param kwargs - Keyword constructor arguments
+   * @returns A handle to the created instance
+   */
+  async instantiate<T = unknown>(
+    module: string,
+    className: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    return this.sendMessageAsync<T>({
+      method: 'instantiate',
+      params: {
+        module,
+        className,
+        args,
+        kwargs,
+      },
+    });
+  }
+
+  /**
+   * Call a method on a Python instance.
+   *
+   * @param handle - Instance handle returned from instantiate()
+   * @param methodName - Method name to call
+   * @param args - Positional arguments
+   * @param kwargs - Keyword arguments
+   * @returns The method result
+   */
+  async callMethod<T = unknown>(
+    handle: string,
+    methodName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    return this.sendMessageAsync<T>({
+      method: 'call_method',
+      params: {
+        handle,
+        methodName,
+        args,
+        kwargs,
+      },
+    });
+  }
+
+  /**
+   * Dispose a Python instance.
+   *
+   * Releases the instance handle on the Python side, allowing
+   * the object to be garbage collected.
+   *
+   * @param handle - Instance handle to dispose
+   */
+  async disposeInstance(handle: string): Promise<void> {
+    await this.sendMessageAsync<void>({
+      method: 'dispose_instance',
+      params: {
+        handle,
+      },
+    });
+  }
+}

package/src/runtime/disposable.ts

@@ -0,0 +1,65 @@
+/**
+ * Disposable interface for resources that need cleanup.
+ *
+ * This interface enables the BoundedContext resource tracking system
+ * to automatically dispose of owned resources when the context is disposed.
+ */
+
+/**
+ * Interface for resources that require explicit cleanup.
+ */
+export interface Disposable {
+  /**
+   * Release resources held by this object.
+   * This method should be idempotent (safe to call multiple times).
+   */
+  dispose(): Promise<void>;
+}
+
+/**
+ * Type guard to check if a value implements the Disposable interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has a dispose method
+ */
+export function isDisposable(value: unknown): value is Disposable {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as Disposable).dispose === 'function'
+  );
+}
+
+/**
+ * Safely dispose a value if it implements Disposable.
+ * Does nothing if the value is not disposable.
+ *
+ * @param value - The value to dispose
+ * @returns Promise that resolves when disposal is complete
+ */
+export async function safeDispose(value: unknown): Promise<void> {
+  if (isDisposable(value)) {
+    await value.dispose();
+  }
+}
+
+/**
+ * Dispose multiple resources, collecting any errors.
+ * All resources will be attempted even if some fail.
+ *
+ * @param resources - Iterable of Disposable resources
+ * @returns Array of errors that occurred during disposal (empty if all succeeded)
+ */
+export async function disposeAll(resources: Iterable<Disposable>): Promise<Error[]> {
+  const errors: Error[] = [];
+
+  for (const resource of resources) {
+    try {
+      await resource.dispose();
+    } catch (e) {
+      errors.push(e instanceof Error ? e : new Error(String(e)));
+    }
+  }
+
+  return errors;
+}

package/src/runtime/http-io.ts

@@ -0,0 +1,244 @@
+/**
+ * HTTP Transport for BridgeProtocol.
+ *
+ * Provides stateless HTTP POST-based communication with a Python server.
+ * Each request is independent - no connection state is maintained.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+
+import {
+  BridgeDisposedError,
+  BridgeExecutionError,
+  BridgeProtocolError,
+  BridgeTimeoutError,
+} from './errors.js';
+import type { Transport } from './transport.js';
+
+// =============================================================================
+// OPTIONS
+// =============================================================================
+
+/**
+ * Configuration options for HttpIO transport.
+ */
+export interface HttpIOOptions {
+  /** Base URL for the Python server (e.g., 'http://localhost:8000') */
+  baseURL: string;
+
+  /** Additional headers to include in each request */
+  headers?: Record<string, string>;
+
+  /** Default timeout in milliseconds. Default: 30000 (30 seconds) */
+  defaultTimeoutMs?: number;
+}
+
+// =============================================================================
+// HTTP TRANSPORT
+// =============================================================================
+
+/**
+ * HTTP-based transport for BridgeProtocol.
+ *
+ * This transport sends protocol messages as HTTP POST requests to a Python
+ * server. It is stateless - each request is independent and the transport
+ * is always ready after construction.
+ *
+ * Features:
+ * - Stateless design (init/dispose are no-ops)
+ * - Timeout handling via AbortController
+ * - External signal support for cancellation
+ * - Proper error classification
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpIO({ baseURL: 'http://localhost:8000' });
+ * await transport.init(); // No-op but follows Transport contract
+ *
+ * const response = await transport.send(
+ *   JSON.stringify({ id: '1', type: 'call', module: 'math', functionName: 'sqrt', args: [16] }),
+ *   5000
+ * );
+ *
+ * await transport.dispose(); // Marks as disposed
+ * ```
+ */
+export class HttpIO implements Transport {
+  private readonly baseURL: string;
+  private readonly headers: Record<string, string>;
+  private readonly defaultTimeoutMs: number;
+  private _isDisposed = false;
+
+  constructor(options: HttpIOOptions) {
+    // Normalize URL - remove trailing slash
+    this.baseURL = options.baseURL.replace(/\/$/, '');
+    this.headers = {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    };
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
+  }
+
+  // ===========================================================================
+  // LIFECYCLE
+  // ===========================================================================
+
+  /**
+   * Initialize the transport.
+   *
+   * HTTP is stateless, so this is a no-op. The transport is ready
+   * immediately after construction.
+   */
+  async init(): Promise<void> {
+    // HTTP is stateless - nothing to initialize
+  }
+
+  /**
+   * Dispose the transport.
+   *
+   * Marks the transport as disposed. Subsequent send() calls will fail.
+   */
+  async dispose(): Promise<void> {
+    this._isDisposed = true;
+  }
+
+  /**
+   * Whether the transport is ready to send messages.
+   *
+   * Returns true unless dispose() has been called.
+   */
+  get isReady(): boolean {
+    return !this._isDisposed;
+  }
+
+  // ===========================================================================
+  // SEND
+  // ===========================================================================
+
+  /**
+   * Send a message to the Python server and wait for the response.
+   *
+   * @param message - The JSON-encoded protocol message to send
+   * @param timeoutMs - Timeout in milliseconds (0 = no timeout, negative = use default)
+   * @param signal - Optional AbortSignal for external cancellation
+   * @returns The raw response string (JSON-encoded ProtocolResponse)
+   *
+   * @throws BridgeDisposedError if the transport has been disposed
+   * @throws BridgeTimeoutError if the operation times out or is aborted
+   * @throws BridgeExecutionError if the server returns a non-2xx status
+   * @throws BridgeProtocolError if the response cannot be read
+   */
+  async send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string> {
+    if (this._isDisposed) {
+      throw new BridgeDisposedError('Transport has been disposed');
+    }
+
+    // Determine effective timeout
+    // 0 = no timeout (per interface contract), negative = use default
+    const effectiveTimeout = timeoutMs === 0 ? 0 : timeoutMs > 0 ? timeoutMs : this.defaultTimeoutMs;
+
+    // Create abort controller for timeout
+    const controller = new AbortController();
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    // Set up timeout if enabled
+    if (effectiveTimeout > 0) {
+      timeoutId = setTimeout(() => {
+        controller.abort();
+      }, effectiveTimeout);
+    }
+
+    // Handle external signal - abort our controller when external aborts
+    const externalAbortHandler = (): void => {
+      controller.abort();
+    };
+
+    if (signal) {
+      // Check if already aborted
+      if (signal.aborted) {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+        }
+        throw new BridgeTimeoutError('Operation aborted');
+      }
+      signal.addEventListener('abort', externalAbortHandler, { once: true });
+    }
+
+    try {
+      const response = await fetch(this.baseURL, {
+        method: 'POST',
+        headers: this.headers,
+        body: message,
+        signal: controller.signal,
+      });
+
+      // Handle non-2xx status codes
+      if (!response.ok) {
+        const errorBody = await this.safeReadText(response);
+        throw new BridgeExecutionError(
+          `HTTP ${response.status}: ${errorBody || response.statusText}`,
+          { code: `HTTP_${response.status}` }
+        );
+      }
+
+      // Read response body
+      const responseText = await response.text();
+      return responseText;
+    } catch (error) {
+      // Handle abort errors (timeout or external signal)
+      if (error instanceof Error && error.name === 'AbortError') {
+        // Determine if it was timeout or external abort
+        if (signal?.aborted) {
+          throw new BridgeTimeoutError('Operation aborted');
+        }
+        throw new BridgeTimeoutError(`Request timed out after ${effectiveTimeout}ms`);
+      }
+
+      // Re-throw bridge errors as-is
+      if (
+        error instanceof BridgeTimeoutError ||
+        error instanceof BridgeExecutionError ||
+        error instanceof BridgeProtocolError
+      ) {
+        throw error;
+      }
+
+      // Wrap network errors
+      if (error instanceof TypeError) {
+        // fetch throws TypeError for network failures
+        throw new BridgeExecutionError(`Network error: ${error.message}`, { cause: error });
+      }
+
+      // Wrap unknown errors
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BridgeExecutionError(`Request failed: ${errorMessage}`, {
+        cause: error instanceof Error ? error : undefined,
+      });
+    } finally {
+      // Clean up timeout
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+
+      // Clean up external signal listener
+      if (signal) {
+        signal.removeEventListener('abort', externalAbortHandler);
+      }
+    }
+  }
+
+  // ===========================================================================
+  // HELPERS
+  // ===========================================================================
+
+  /**
+   * Safely read response body as text, returning empty string on failure.
+   */
+  private async safeReadText(response: Response): Promise<string> {
+    try {
+      return await response.text();
+    } catch {
+      return '';
+    }
+  }
+}