tywrap 0.2.1 → 0.4.0

package/src/runtime/safe-codec.ts

@@ -8,7 +8,7 @@
  * - Binary data handling
  */
 
-import { BridgeProtocolError, BridgeExecutionError } from './errors.js';
+import { BridgeCodecError, BridgeProtocolError, BridgeExecutionError } from './errors.js';
 import { containsSpecialFloat } from './validators.js';
 import { decodeValueAsync as decodeArrowValue } from '../utils/codec.js';
 import { PROTOCOL_ID } from './transport.js';
@@ -42,11 +42,25 @@ interface PythonErrorResponse {
   };
 }
 
+interface NormalizedPythonError {
+  type: string;
+  message: string;
+  traceback?: string;
+}
+
+interface ProtocolEnvelope {
+  id: number;
+  protocol?: string;
+  result?: unknown;
+  error?: unknown;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // CONSTANTS
 // ═══════════════════════════════════════════════════════════════════════════
 
 const DEFAULT_MAX_PAYLOAD_BYTES = 10 * 1024 * 1024; // 10MB
+const ERROR_PAYLOAD_SNIPPET_LENGTH = 200;
 
 // ═══════════════════════════════════════════════════════════════════════════
 // HELPER FUNCTIONS
@@ -75,12 +89,20 @@ function buildPath(basePath: string, key: string | number): string {
 
 /**
  * Recursively check for non-string keys in objects and Maps.
- * Throws BridgeProtocolError with path indication if found.
+ * Throws BridgeCodecError with path indication if found.
  */
-function assertStringKeys(value: unknown, path: string = ''): void {
+function assertStringKeys(
+  value: unknown,
+  path: string = '',
+  visited: WeakSet<object> = new WeakSet<object>()
+): void {
   if (value === null || typeof value !== 'object') {
     return;
   }
+  if (visited.has(value)) {
+    return;
+  }
+  visited.add(value);
 
   // Check Map instances for non-string keys
   if (value instanceof Map) {
@@ -88,22 +110,23 @@ function assertStringKeys(value: unknown, path: string = ''): void {
       if (typeof key !== 'string') {
         const keyDesc = typeof key === 'symbol' ? key.toString() : String(key);
         const location = path ? ` at ${path}` : '';
-        throw new BridgeProtocolError(
-          `Non-string key found in Map${location}: ${keyDesc} (${typeof key})`
+        throw new BridgeCodecError(
+          `Non-string key found in Map${location}: ${keyDesc} (${typeof key})`,
+          { codecPhase: 'encode' }
         );
       }
     }
     // Recurse into Map values
     for (const [key, val] of value.entries()) {
-      assertStringKeys(val, buildPath(path, key));
+      assertStringKeys(val, buildPath(path, key), visited);
     }
     return;
   }
 
   // Check arrays
   if (Array.isArray(value)) {
-    for (let i = 0; i < value.length; i++) {
-      assertStringKeys(value[i], buildPath(path, i));
+    for (const [index, item] of value.entries()) {
+      assertStringKeys(item, buildPath(path, index), visited);
     }
     return;
   }
@@ -116,14 +139,14 @@ function assertStringKeys(value: unknown, path: string = ''): void {
     if (firstSymbol !== undefined) {
       const symbolDesc = firstSymbol.toString();
       const location = path ? ` at ${path}` : '';
-      throw new BridgeProtocolError(
-        `Symbol key found in object${location}: ${symbolDesc}`
-      );
+      throw new BridgeCodecError(`Symbol key found in object${location}: ${symbolDesc}`, {
+        codecPhase: 'encode',
+      });
     }
 
     // Recurse into object values
-    for (const key of Object.keys(value)) {
-      assertStringKeys(value[key], buildPath(path, key));
+    for (const [key, item] of Object.entries(value)) {
+      assertStringKeys(item, buildPath(path, key), visited);
     }
   }
 }
@@ -144,22 +167,68 @@ function isPythonErrorResponse(value: unknown): value is PythonErrorResponse {
 }
 
 /**
- * Type guard for protocol result response.
- * Checks if the value is an object with an id and result field.
- * The protocol field is optional as Python may not always include it.
+ * Type guard for protocol response envelope.
+ * Envelopes must include a numeric id.
  */
-interface ProtocolResultResponse {
-  id: number;
-  protocol?: string;
-  result: unknown;
-}
-
-function isProtocolResultResponse(value: unknown): value is ProtocolResultResponse {
+function isProtocolEnvelope(value: unknown): value is ProtocolEnvelope {
   if (value === null || typeof value !== 'object') {
     return false;
   }
   const obj = value as Record<string, unknown>;
-  return typeof obj.id === 'number' && 'result' in obj;
+  return typeof obj.id === 'number';
+}
+
+function hasOwnKey(value: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function normalizeErrorPayload(err: unknown): NormalizedPythonError | null {
+  if (!err || typeof err !== 'object' || Array.isArray(err)) {
+    return null;
+  }
+  const candidate = err as Record<string, unknown>;
+  if (typeof candidate.type !== 'string' || typeof candidate.message !== 'string') {
+    return null;
+  }
+  if (hasOwnKey(candidate, 'traceback') && typeof candidate.traceback !== 'string') {
+    return null;
+  }
+  const normalized: NormalizedPythonError = {
+    type: candidate.type,
+    message: candidate.message,
+  };
+  if (typeof candidate.traceback === 'string') {
+    normalized.traceback = candidate.traceback;
+  }
+  return normalized;
+}
+
+function describeInvalidErrorPayload(err: unknown): string {
+  if (!err || typeof err !== 'object' || Array.isArray(err)) {
+    return 'expected an object with string "type" and "message" fields';
+  }
+  const candidate = err as Record<string, unknown>;
+  if (typeof candidate.type !== 'string') {
+    return '"type" must be a string';
+  }
+  if (typeof candidate.message !== 'string') {
+    return '"message" must be a string';
+  }
+  if (hasOwnKey(candidate, 'traceback') && typeof candidate.traceback !== 'string') {
+    return '"traceback" must be a string when provided';
+  }
+  return 'expected an object with string "type" and "message" fields';
+}
+
+function summarizePayloadForError(payload: string): string {
+  const trimmed = payload.trim();
+  if (!trimmed) {
+    return '[empty payload]';
+  }
+  if (trimmed.length <= ERROR_PAYLOAD_SNIPPET_LENGTH) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, ERROR_PAYLOAD_SNIPPET_LENGTH)}...`;
 }
 
 /**
@@ -189,21 +258,32 @@ function validateProtocolVersion(value: unknown): void {
  * Find the path to a special float in a value structure.
  * Returns undefined if no special float is found.
  */
-function findSpecialFloatPath(value: unknown, path: string = ''): string | undefined {
+function findSpecialFloatPath(
+  value: unknown,
+  path: string = '',
+  visited: WeakSet<object> = new WeakSet<object>()
+): string | undefined {
   if (typeof value === 'number' && !Number.isFinite(value)) {
     return path || 'root';
   }
+  if (value === null || typeof value !== 'object') {
+    return undefined;
+  }
+  if (visited.has(value)) {
+    return undefined;
+  }
+  visited.add(value);
   if (Array.isArray(value)) {
-    for (let i = 0; i < value.length; i++) {
-      const result = findSpecialFloatPath(value[i], buildPath(path, i));
+    for (const [index, item] of value.entries()) {
+      const result = findSpecialFloatPath(item, buildPath(path, index), visited);
       if (result !== undefined) {
         return result;
       }
     }
   }
   if (isPlainObject(value)) {
-    for (const key of Object.keys(value)) {
-      const result = findSpecialFloatPath(value[key], buildPath(path, key));
+    for (const [key, item] of Object.entries(value)) {
+      const result = findSpecialFloatPath(item, buildPath(path, key), visited);
       if (result !== undefined) {
         return result;
       }
@@ -239,12 +319,128 @@ export class SafeCodec {
   private readonly rejectNonStringKeys: boolean;
   private readonly maxPayloadBytes: number;
   private readonly bytesHandling: 'base64' | 'reject' | 'passthrough';
+  private readonly reviveValueBound: (key: string, value: unknown) => unknown;
+  private static readonly base64Pattern =
+    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 
   constructor(options: CodecOptions = {}) {
     this.rejectSpecialFloats = options.rejectSpecialFloats ?? true;
     this.rejectNonStringKeys = options.rejectNonStringKeys ?? true;
     this.maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
     this.bytesHandling = options.bytesHandling ?? 'base64';
+    this.reviveValueBound = this.reviveValue.bind(this);
+  }
+
+  private assertValidBase64(b64: string): void {
+    if (!SafeCodec.base64Pattern.test(b64)) {
+      throw new BridgeCodecError('Invalid base64 in bytes envelope', {
+        codecPhase: 'decode',
+        valueType: 'bytes',
+      });
+    }
+  }
+
+  /**
+   * Convert base64 string to Uint8Array.
+   *
+   * Why: Python bridge represents bytes/bytearray as base64 envelopes. Decoding them here
+   * restores ergonomic JS types at the boundary.
+   */
+  private fromBase64(b64: string): Uint8Array {
+    this.assertValidBase64(b64);
+
+    if (typeof Buffer !== 'undefined') {
+      const buf = Buffer.from(b64, 'base64');
+      return new Uint8Array(buf.buffer, buf.byteOffset, buf.length);
+    }
+    if (globalThis.atob) {
+      const bin = globalThis.atob(b64);
+      const arr = Array.from(bin, c => c.charCodeAt(0));
+      return new Uint8Array(arr);
+    }
+    throw new BridgeCodecError('Base64 decoding is not available in this runtime', {
+      codecPhase: 'decode',
+      valueType: 'bytes',
+    });
+  }
+
+  /**
+   * JSON.parse reviver that decodes bytes envelopes.
+   *
+   * Supported shapes:
+   * - { "__tywrap_bytes__": true, "b64": "..." } (JS SafeCodec.encodeRequest; also allowed in responses)
+   * - { "__type__": "bytes", "encoding": "base64", "data": "..." } (Python SafeCodec default encoder)
+   */
+  private reviveValue(_key: string, value: unknown): unknown {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      return value;
+    }
+    const obj = value as Record<string, unknown>;
+
+    if (obj.__tywrap_bytes__ === true && typeof obj.b64 === 'string') {
+      try {
+        return this.fromBase64(obj.b64);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        throw new BridgeCodecError(`Bytes envelope decode failed: ${errorMessage}`, {
+          codecPhase: 'decode',
+          valueType: 'bytes',
+        });
+      }
+    }
+
+    if (obj.__type__ === 'bytes' && obj.encoding === 'base64' && typeof obj.data === 'string') {
+      try {
+        return this.fromBase64(obj.data);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        throw new BridgeCodecError(`Bytes envelope decode failed: ${errorMessage}`, {
+          codecPhase: 'decode',
+          valueType: 'bytes',
+        });
+      }
+    }
+
+    return value;
+  }
+
+  private toBridgeExecutionError(error: NormalizedPythonError): BridgeExecutionError {
+    const bridgeError = new BridgeExecutionError(`${error.type}: ${error.message}`);
+    bridgeError.traceback = error.traceback;
+    return bridgeError;
+  }
+
+  private extractResultFromResponseEnvelope(parsed: unknown): unknown {
+    if (isProtocolEnvelope(parsed)) {
+      const envelope = parsed;
+      const hasResult = hasOwnKey(envelope, 'result');
+      const hasError = hasOwnKey(envelope, 'error');
+
+      if (hasResult && hasError) {
+        throw new BridgeProtocolError('Protocol response cannot include both "result" and "error"');
+      }
+
+      if (hasError) {
+        const normalizedError = normalizeErrorPayload(envelope.error);
+        if (!normalizedError) {
+          const details = describeInvalidErrorPayload(envelope.error);
+          throw new BridgeProtocolError(`Invalid response "error" payload: ${details}`);
+        }
+        throw this.toBridgeExecutionError(normalizedError);
+      }
+
+      if (!hasResult) {
+        throw new BridgeProtocolError('Protocol response missing "result" or "error" field');
+      }
+
+      return envelope.result;
+    }
+
+    if (isPythonErrorResponse(parsed)) {
+      throw this.toBridgeExecutionError(parsed.error);
+    }
+
+    return parsed;
   }
 
   /**
@@ -253,14 +449,15 @@ export class SafeCodec {
    *
    * @param message - The message to encode
    * @returns JSON string ready to send
-   * @throws BridgeProtocolError if validation fails or encoding fails
+   * @throws BridgeCodecError if validation fails or encoding fails
    */
   encodeRequest(message: unknown): string {
     // Validate special floats if enabled
     if (this.rejectSpecialFloats && containsSpecialFloat(message)) {
       const floatPath = findSpecialFloatPath(message);
-      throw new BridgeProtocolError(
-        `Cannot encode request: contains non-finite number (NaN or Infinity) at ${floatPath}`
+      throw new BridgeCodecError(
+        `Cannot encode request: contains non-finite number (NaN or Infinity) at ${floatPath}`,
+        { codecPhase: 'encode', valueType: 'number' }
       );
     }
 
@@ -277,8 +474,9 @@ export class SafeCodec {
         if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
           switch (this.bytesHandling) {
             case 'reject':
-              throw new BridgeProtocolError(
-                `Cannot encode request: binary data found at ${key || 'root'} (bytesHandling: reject)`
+              throw new BridgeCodecError(
+                `Cannot encode request: binary data found at ${key || 'root'} (bytesHandling: reject)`,
+                { codecPhase: 'encode', valueType: 'bytes' }
               );
             case 'base64': {
               const bytes = value instanceof ArrayBuffer ? new Uint8Array(value) : value;
@@ -293,18 +491,24 @@ export class SafeCodec {
         return value;
       });
     } catch (err) {
+      if (err instanceof BridgeCodecError) {
+        throw err;
+      }
       if (err instanceof BridgeProtocolError) {
         throw err;
       }
-      const message = err instanceof Error ? err.message : String(err);
-      throw new BridgeProtocolError(`JSON serialization failed: ${message}`);
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      throw new BridgeCodecError(`JSON serialization failed: ${errorMessage}`, {
+        codecPhase: 'encode',
+      });
     }
 
     // Check payload size
     const payloadBytes = new TextEncoder().encode(payload).length;
     if (payloadBytes > this.maxPayloadBytes) {
-      throw new BridgeProtocolError(
-        `Payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`
+      throw new BridgeCodecError(
+        `Payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`,
+        { codecPhase: 'encode', valueType: 'payload' }
       );
     }
 
@@ -317,47 +521,46 @@ export class SafeCodec {
    *
    * @param payload - The JSON string received from Python
    * @returns Decoded and validated result
-   * @throws BridgeProtocolError if payload is invalid
+   * @throws BridgeCodecError if payload is invalid or decoding fails
+   * @throws BridgeProtocolError if protocol envelope is invalid
    * @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 BridgeProtocolError(
-        `Response payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`
+      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);
+      parsed = JSON.parse(payload, this.reviveValueBound);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new BridgeProtocolError(`JSON parse failed: ${message}`);
+      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);
 
-    // Check for Python error response
-    if (isPythonErrorResponse(parsed)) {
-      const error = new BridgeExecutionError(
-        `${parsed.error.type}: ${parsed.error.message}`
-      );
-      error.traceback = parsed.error.traceback;
-      throw error;
-    }
-
-    // Extract the result field from the response envelope
-    const result = isProtocolResultResponse(parsed) ? parsed.result : parsed;
+    const result = this.extractResultFromResponseEnvelope(parsed);
 
     // Post-decode validation for special floats if enabled
     if (this.rejectSpecialFloats && containsSpecialFloat(result)) {
       const floatPath = findSpecialFloatPath(result);
-      throw new BridgeProtocolError(
-        `Response contains non-finite number (NaN or Infinity) at ${floatPath}`
+      throw new BridgeCodecError(
+        `Response contains non-finite number (NaN or Infinity) at ${floatPath}`,
+        { codecPhase: 'decode', valueType: 'number' }
       );
     }
 
@@ -370,57 +573,59 @@ export class SafeCodec {
    *
    * @param payload - The JSON string received from Python
    * @returns Decoded and validated result with Arrow decoding applied
-   * @throws BridgeProtocolError if payload is invalid
+   * @throws BridgeCodecError if payload is invalid or decoding fails
+   * @throws BridgeProtocolError if protocol envelope is invalid
    * @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 BridgeProtocolError(
-        `Response payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`
+      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);
+      parsed = JSON.parse(payload, this.reviveValueBound);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new BridgeProtocolError(`JSON parse failed: ${message}`);
+      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);
 
-    // Check for Python error response
-    if (isPythonErrorResponse(parsed)) {
-      const error = new BridgeExecutionError(
-        `${parsed.error.type}: ${parsed.error.message}`
-      );
-      error.traceback = parsed.error.traceback;
-      throw error;
-    }
-
-    // Extract the result field from the response envelope
-    const result = isProtocolResultResponse(parsed) ? parsed.result : parsed;
+    const result = this.extractResultFromResponseEnvelope(parsed);
 
     // Apply Arrow decoding to the result
     let decoded: unknown;
     try {
       decoded = await decodeArrowValue(result);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new BridgeProtocolError(`Arrow decoding failed: ${message}`);
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      throw new BridgeCodecError(`Arrow decoding failed: ${errorMessage}`, {
+        codecPhase: 'decode',
+        valueType: 'arrow',
+      });
     }
 
     // Post-decode validation for special floats if enabled
-    // Note: We check the result value since that's what we're returning
-    if (this.rejectSpecialFloats && containsSpecialFloat(result)) {
-      const floatPath = findSpecialFloatPath(result);
-      throw new BridgeProtocolError(
-        `Response contains non-finite number (NaN or Infinity) at ${floatPath}`
+    // 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' }
       );
     }
 
@@ -438,6 +643,9 @@ export class SafeCodec {
       const binary = String.fromCharCode(...bytes);
       return globalThis.btoa(binary);
     }
-    throw new BridgeProtocolError('Base64 encoding is not available in this runtime');
+    throw new BridgeCodecError('Base64 encoding is not available in this runtime', {
+      codecPhase: 'encode',
+      valueType: 'bytes',
+    });
   }
 }

package/src/runtime/transport.ts

@@ -122,7 +122,12 @@ export interface ProtocolResponse {
  * await transport.init();
  *
  * const response = await transport.send(
- *   JSON.stringify({ id: '1', type: 'call', module: 'math', functionName: 'sqrt', args: [16] }),
+ *   JSON.stringify({
+ *     id: 1,
+ *     protocol: 'tywrap/1',
+ *     method: 'call',
+ *     params: { module: 'math', functionName: 'sqrt', args: [16], kwargs: {} },
+ *   }),
  *   5000
  * );
  *

package/src/runtime/validators.ts

@@ -183,19 +183,30 @@ export function assertObject(value: unknown, name: string): Record<string, unkno
  * @param value - The value to check
  * @returns True if the value contains NaN or Infinity anywhere
  */
-export function containsSpecialFloat(value: unknown): boolean {
+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(containsSpecialFloat);
+    return value.some(item => containsSpecialFloatRecursive(item, visited));
   }
   if (isPlainObject(value)) {
-    return Object.values(value).some(containsSpecialFloat);
+    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.
  *