tywrap 0.2.0 → 0.2.1

package/src/runtime/http.ts

@@ -1,132 +1,86 @@
 /**
- * HTTP runtime bridge
+ * HTTP runtime bridge for BridgeProtocol.
+ *
+ * HttpBridge extends BridgeProtocol and uses HttpIO transport for
+ * stateless HTTP POST-based communication with a Python server.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
  */
 
-import { decodeValueAsync } from '../utils/codec.js';
+import { BridgeProtocol, type BridgeProtocolOptions } from './bridge-protocol.js';
+import { HttpIO } from './http-io.js';
+import type { CodecOptions } from './safe-codec.js';
 
-import { RuntimeBridge } from './base.js';
+// =============================================================================
+// OPTIONS
+// =============================================================================
 
+/**
+ * Configuration options for HttpBridge.
+ */
 export interface HttpBridgeOptions {
+  /** Base URL for the Python server (e.g., 'http://localhost:8000') */
   baseURL: string;
-  headers?: Record<string, string>;
-  timeoutMs?: number;
-}
-
-interface HttpCallPayload {
-  module: string;
-  functionName: string;
-  args: unknown[];
-  kwargs?: Record<string, unknown>;
-}
 
-interface HttpInstantiatePayload {
-  module: string;
-  className: string;
-  args: unknown[];
-  kwargs?: Record<string, unknown>;
-}
+  /** Additional headers to include in each request */
+  headers?: Record<string, string>;
 
-interface HttpCallMethodPayload {
-  handle: string;
-  methodName: string;
-  args: unknown[];
-  kwargs?: Record<string, unknown>;
-}
+  /** Timeout in ms for requests. Default: 30000 (30 seconds) */
+  timeoutMs?: number;
 
-interface HttpDisposePayload {
-  handle: string;
+  /** Codec options for validation/serialization */
+  codec?: CodecOptions;
 }
 
-export class HttpBridge extends RuntimeBridge {
-  private readonly baseURL: string;
-  private readonly headers: Record<string, string>;
-  private readonly timeoutMs: number;
-
-  constructor(options: HttpBridgeOptions = { baseURL: 'http://localhost:8000' }) {
-    super();
-    this.baseURL = options.baseURL.replace(/\/$/, '');
-    this.headers = { 'content-type': 'application/json', ...(options.headers ?? {}) };
-    this.timeoutMs = options.timeoutMs ?? 30000;
-  }
-
-  async call<T = unknown>(
-    module: string,
-    functionName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    const payload: HttpCallPayload = { module, functionName, args, kwargs };
-    const res = await this.post(`${this.baseURL}/call`, payload);
-    return (await decodeValueAsync(res)) as T;
-  }
-
-  async instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    const payload: HttpInstantiatePayload = { module, className, args, kwargs };
-    const res = await this.post(`${this.baseURL}/instantiate`, payload);
-    return (await decodeValueAsync(res)) as T;
-  }
-
-  async callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    const payload: HttpCallMethodPayload = { handle, methodName, args, kwargs };
-    const res = await this.post(`${this.baseURL}/call_method`, payload);
-    return (await decodeValueAsync(res)) as T;
-  }
-
-  async disposeInstance(handle: string): Promise<void> {
-    const payload: HttpDisposePayload = { handle };
-    await this.post(`${this.baseURL}/dispose_instance`, payload);
-  }
+// =============================================================================
+// HTTP BRIDGE
+// =============================================================================
 
-  async dispose(): Promise<void> {
-    // stateless
-  }
-
-  private async post(url: string, body: unknown): Promise<unknown> {
-    const controller = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
-    const timer = controller ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;
-    try {
-      const resp = await fetch(url, {
-        method: 'POST',
-        headers: this.headers,
-        body: JSON.stringify(body),
-        signal: controller?.signal,
-      });
-      if (!resp.ok) {
-        const text = await safeText(resp);
-        throw new Error(`HTTP ${resp.status}: ${text || resp.statusText}`);
-      }
-      const ct = resp.headers.get('content-type') ?? '';
-      if (ct.includes('application/json')) {
-        return (await resp.json()) as unknown;
-      }
-      const text = await resp.text();
-      try {
-        return JSON.parse(text) as unknown;
-      } catch {
-        return text as unknown;
-      }
-    } finally {
-      if (timer) {
-        clearTimeout(timer);
-      }
-    }
-  }
-}
-
-async function safeText(resp: Response): Promise<string> {
-  try {
-    return await resp.text();
-  } catch {
-    return '';
+/**
+ * HTTP-based runtime bridge for executing Python code.
+ *
+ * HttpBridge provides a stateless HTTP transport for communication with
+ * a Python server. Each request is independent - no connection state is
+ * maintained between calls.
+ *
+ * Features:
+ * - Stateless HTTP POST communication
+ * - Timeout handling via AbortController
+ * - Full SafeCodec validation (NaN/Infinity rejection, key validation)
+ * - Automatic Arrow decoding for DataFrames/ndarrays
+ *
+ * @example
+ * ```typescript
+ * const bridge = new HttpBridge({ baseURL: 'http://localhost:8000' });
+ * await bridge.init();
+ *
+ * const result = await bridge.call('math', 'sqrt', [16]);
+ * console.log(result); // 4.0
+ *
+ * await bridge.dispose();
+ * ```
+ */
+export class HttpBridge extends BridgeProtocol {
+  /**
+   * Create a new HttpBridge instance.
+   *
+   * @param options - Configuration options for the bridge
+   */
+  constructor(options: HttpBridgeOptions) {
+    // Create HTTP transport
+    const transport = new HttpIO({
+      baseURL: options.baseURL,
+      headers: options.headers,
+      defaultTimeoutMs: options.timeoutMs,
+    });
+
+    // Initialize BridgeProtocol with transport and codec options
+    const protocolOptions: BridgeProtocolOptions = {
+      transport,
+      codec: options.codec,
+      defaultTimeoutMs: options.timeoutMs,
+    };
+
+    super(protocolOptions);
   }
 }