tywrap 0.2.0 → 0.3.0

package/src/runtime/transport.ts

@@ -0,0 +1,278 @@
+/**
+ * Transport layer for BridgeProtocol.
+ *
+ * Provides an abstract I/O channel for all bridge communications across
+ * the JS-Python boundary. Concrete implementations handle different runtimes:
+ * - ProcessIO: Child process with stdio streams (Node.js)
+ * - HttpIO: HTTP POST requests (remote Python server)
+ * - PyodideIO: In-memory Pyodide calls (browser/WASM)
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+
+import type { Disposable } from './disposable.js';
+
+// =============================================================================
+// PROTOCOL CONSTANTS
+// =============================================================================
+
+/** Protocol identifier for tywrap communication */
+export const PROTOCOL_ID = 'tywrap/1';
+
+// =============================================================================
+// PROTOCOL TYPES
+// =============================================================================
+
+/**
+ * Protocol message format for all transports.
+ *
+ * Each method corresponds to a BridgeProtocol operation:
+ * - `call`: Invoke a module-level function
+ * - `instantiate`: Create a new class instance
+ * - `call_method`: Invoke a method on an existing instance
+ * - `dispose_instance`: Release an instance handle
+ * - `meta`: Get bridge metadata
+ */
+export interface ProtocolMessage {
+  /** Unique message identifier for request-response correlation */
+  id: number;
+
+  /** Protocol identifier (must be 'tywrap/1') */
+  protocol: typeof PROTOCOL_ID;
+
+  /** The method to invoke */
+  method: 'call' | 'instantiate' | 'call_method' | 'dispose_instance' | 'meta';
+
+  /** Method parameters */
+  params: {
+    /** Python module path (for call and instantiate) */
+    module?: string;
+
+    /** Function name (for call) */
+    functionName?: string;
+
+    /** Class name (for instantiate) */
+    className?: string;
+
+    /** Instance handle (for call_method and dispose_instance) */
+    handle?: string;
+
+    /** Method name (for call_method) */
+    methodName?: string;
+
+    /** Positional arguments */
+    args?: unknown[];
+
+    /** Keyword arguments */
+    kwargs?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Protocol response format from the Python side.
+ *
+ * A response contains either a result or an error, never both.
+ * The `id` field correlates the response to its originating request.
+ */
+export interface ProtocolResponse {
+  /** Message identifier matching the originating request */
+  id: number;
+
+  /** Protocol identifier (echoed back from request) */
+  protocol?: string;
+
+  /** Successful result value (undefined if error occurred) */
+  result?: unknown;
+
+  /** Error information (undefined if operation succeeded) */
+  error?: {
+    /** Python exception type name */
+    type: string;
+    /** Error message */
+    message: string;
+    /** Optional Python traceback for debugging */
+    traceback?: string;
+  };
+}
+
+// =============================================================================
+// TRANSPORT INTERFACE
+// =============================================================================
+
+/**
+ * Abstract transport for sending messages across the JS-Python boundary.
+ *
+ * Transport implementations handle the low-level I/O details while
+ * providing a consistent interface for the higher-level BridgeProtocol.
+ *
+ * Lifecycle:
+ * 1. Create transport instance
+ * 2. Call `init()` to establish the connection
+ * 3. Use `send()` to exchange messages
+ * 4. Call `dispose()` to release resources
+ *
+ * Implementations:
+ * - ProcessIO: Spawns a Python child process, communicates via stdio
+ * - HttpIO: Sends HTTP POST requests to a Python server
+ * - PyodideIO: Calls Pyodide directly in-memory (WASM)
+ *
+ * @example
+ * ```typescript
+ * const transport = new ProcessIO({ pythonPath: 'python3' });
+ * await transport.init();
+ *
+ * const response = await transport.send(
+ *   JSON.stringify({
+ *     id: 1,
+ *     protocol: 'tywrap/1',
+ *     method: 'call',
+ *     params: { module: 'math', functionName: 'sqrt', args: [16], kwargs: {} },
+ *   }),
+ *   5000
+ * );
+ *
+ * await transport.dispose();
+ * ```
+ */
+export interface Transport extends Disposable {
+  /**
+   * Initialize the transport.
+   *
+   * This method establishes the underlying connection (e.g., spawns a process,
+   * opens a connection). It must be called before `send()` can be used.
+   *
+   * This method should be idempotent - calling it multiple times after
+   * successful initialization should be a no-op.
+   *
+   * @throws BridgeError if initialization fails
+   */
+  init(): Promise<void>;
+
+  /**
+   * Send a message and wait for the response.
+   *
+   * @param message - The JSON-encoded protocol message to send
+   * @param timeoutMs - Timeout in milliseconds (0 = no timeout)
+   * @param signal - Optional AbortSignal for external cancellation
+   * @returns The raw response string (JSON-encoded ProtocolResponse)
+   *
+   * @throws BridgeTimeoutError if the operation times out or is aborted
+   * @throws BridgeDisposedError if the transport has been disposed
+   * @throws BridgeProtocolError if the message format is invalid
+   * @throws BridgeError for other transport-level failures
+   */
+  send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string>;
+
+  /**
+   * Whether the transport is ready to send messages.
+   *
+   * Returns `true` after successful `init()` and before `dispose()`.
+   * Returns `false` in all other states.
+   */
+  readonly isReady: boolean;
+}
+
+// =============================================================================
+// TRANSPORT OPTIONS
+// =============================================================================
+
+/**
+ * Base options for creating a Transport.
+ *
+ * Concrete transport implementations may extend this with
+ * additional configuration options.
+ */
+export interface TransportOptions {
+  /**
+   * Default timeout for operations in milliseconds.
+   *
+   * This timeout applies to individual `send()` calls when
+   * no explicit timeout is provided.
+   *
+   * @default 30000 (30 seconds)
+   */
+  defaultTimeoutMs?: number;
+}
+
+// =============================================================================
+// TYPE GUARDS
+// =============================================================================
+
+/**
+ * Type guard to check if a value implements the Transport interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has all required Transport methods and properties
+ *
+ * @example
+ * ```typescript
+ * function useTransport(maybeTransport: unknown) {
+ *   if (isTransport(maybeTransport)) {
+ *     await maybeTransport.init();
+ *     // TypeScript now knows maybeTransport is Transport
+ *   }
+ * }
+ * ```
+ */
+export function isTransport(value: unknown): value is Transport {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as Transport).init === 'function' &&
+    typeof (value as Transport).send === 'function' &&
+    typeof (value as Transport).dispose === 'function' &&
+    'isReady' in value
+  );
+}
+
+/**
+ * Type guard to check if a value is a valid ProtocolMessage.
+ *
+ * @param value - The value to check
+ * @returns True if the value conforms to the ProtocolMessage structure
+ */
+export function isProtocolMessage(value: unknown): value is ProtocolMessage {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const msg = value as ProtocolMessage;
+
+  return (
+    typeof msg.id === 'number' &&
+    msg.protocol === PROTOCOL_ID &&
+    typeof msg.method === 'string' &&
+    ['call', 'instantiate', 'call_method', 'dispose_instance', 'meta'].includes(msg.method) &&
+    typeof msg.params === 'object' &&
+    msg.params !== null
+  );
+}
+
+/**
+ * Type guard to check if a value is a valid ProtocolResponse.
+ *
+ * @param value - The value to check
+ * @returns True if the value conforms to the ProtocolResponse structure
+ */
+export function isProtocolResponse(value: unknown): value is ProtocolResponse {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const resp = value as ProtocolResponse;
+
+  if (typeof resp.id !== 'number') {
+    return false;
+  }
+
+  // Must have either result or error (or neither for void returns)
+  if (resp.error !== undefined) {
+    if (typeof resp.error !== 'object' || resp.error === null) {
+      return false;
+    }
+    const err = resp.error;
+    return typeof err.type === 'string' && typeof err.message === 'string';
+  }
+
+  return true;
+}

package/src/runtime/validators.ts

@@ -0,0 +1,252 @@
+/**
+ * Pure validation functions for runtime value checking.
+ *
+ * These functions are used by BoundedContext and can also be used
+ * independently for validation in CLI tools, config loading, etc.
+ */
+
+/**
+ * Error thrown when validation fails.
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE GUARDS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a value is a finite number (not NaN, not Infinity).
+ */
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * Check if a value is a positive finite number.
+ */
+export function isPositiveNumber(value: unknown): value is number {
+  return isFiniteNumber(value) && value > 0;
+}
+
+/**
+ * Check if a value is a non-negative finite number.
+ */
+export function isNonNegativeNumber(value: unknown): value is number {
+  return isFiniteNumber(value) && value >= 0;
+}
+
+/**
+ * Check if a value is a non-empty string.
+ */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ASSERTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Assert that a value is a finite number.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a finite number
+ */
+export function assertFiniteNumber(value: unknown, name: string): number {
+  if (!isFiniteNumber(value)) {
+    const actual = typeof value === 'number' ? String(value) : typeof value;
+    throw new ValidationError(`${name} must be a finite number, got: ${actual}`);
+  }
+  return value;
+}
+
+/**
+ * Assert that a value is a positive number (> 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a positive number
+ */
+export function assertPositive(value: unknown, name: string): number {
+  const num = assertFiniteNumber(value, name);
+  if (num <= 0) {
+    throw new ValidationError(`${name} must be positive, got: ${num}`);
+  }
+  return num;
+}
+
+/**
+ * Assert that a value is a non-negative number (>= 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a non-negative number
+ */
+export function assertNonNegative(value: unknown, name: string): number {
+  const num = assertFiniteNumber(value, name);
+  if (num < 0) {
+    throw new ValidationError(`${name} must be non-negative, got: ${num}`);
+  }
+  return num;
+}
+
+/**
+ * Assert that a value is a string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a string
+ */
+export function assertString(value: unknown, name: string): string {
+  if (typeof value !== 'string') {
+    throw new ValidationError(`${name} must be a string, got: ${typeof value}`);
+  }
+  return value;
+}
+
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a non-empty string
+ */
+export function assertNonEmptyString(value: unknown, name: string): string {
+  const str = assertString(value, name);
+  if (str.length === 0) {
+    throw new ValidationError(`${name} must not be empty`);
+  }
+  return str;
+}
+
+/**
+ * Assert that a value is an array.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as an array
+ * @throws ValidationError if the value is not an array
+ */
+export function assertArray<T = unknown>(value: unknown, name: string): T[] {
+  if (!Array.isArray(value)) {
+    throw new ValidationError(`${name} must be an array, got: ${typeof value}`);
+  }
+  return value as T[];
+}
+
+/**
+ * Assert that a value is a plain object (not null, not array).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a Record
+ * @throws ValidationError if the value is not a plain object
+ */
+export function assertObject(value: unknown, name: string): Record<string, unknown> {
+  if (!isPlainObject(value)) {
+    const actual = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+    throw new ValidationError(`${name} must be an object, got: ${actual}`);
+  }
+  return value;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SPECIAL FLOAT DETECTION (for codec validation)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a value contains non-finite numbers (NaN, Infinity, -Infinity).
+ * Recursively checks arrays and objects.
+ *
+ * This is used to detect values that cannot be safely serialized to JSON,
+ * as JSON.stringify converts NaN/Infinity to null, which can cause
+ * silent data corruption.
+ *
+ * @param value - The value to check
+ * @returns True if the value contains NaN or Infinity anywhere
+ */
+function containsSpecialFloatRecursive(value: unknown, visited: WeakSet<object>): boolean {
+  if (typeof value === 'number') {
+    return !Number.isFinite(value);
+  }
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  if (visited.has(value)) {
+    return false;
+  }
+  visited.add(value);
+  if (Array.isArray(value)) {
+    return value.some(item => containsSpecialFloatRecursive(item, visited));
+  }
+  if (isPlainObject(value)) {
+    return Object.values(value).some(item => containsSpecialFloatRecursive(item, visited));
+  }
+  return false;
+}
+
+export function containsSpecialFloat(value: unknown): boolean {
+  return containsSpecialFloatRecursive(value, new WeakSet<object>());
+}
+
+/**
+ * Assert that a value does not contain non-finite numbers.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @throws ValidationError if the value contains NaN or Infinity
+ */
+export function assertNoSpecialFloats(value: unknown, name: string): void {
+  if (containsSpecialFloat(value)) {
+    throw new ValidationError(
+      `${name} contains non-finite numbers (NaN or Infinity) which cannot be serialized to JSON`
+    );
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATH VALIDATION (for CLI security)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Sanitize a string for use in a cache key filename.
+ * Removes or replaces characters that could cause path traversal or invalid filenames.
+ *
+ * @param value - The string to sanitize
+ * @returns A safe string for use in filenames
+ */
+export function sanitizeForFilename(value: string): string {
+  // Replace path separators and traversal patterns
+  return value
+    .replace(/\.\./g, '__')
+    .replace(/[/\\:*?"<>|]/g, '_')
+    .replace(/\s+/g, '_');
+}
+
+/**
+ * Check if a string looks like a path traversal attempt.
+ *
+ * @param value - The string to check
+ * @returns True if the string contains path traversal patterns
+ */
+export function containsPathTraversal(value: string): boolean {
+  return value.includes('..') || value.includes('/') || value.includes('\\');
+}