tywrap 0.2.1 → 0.3.0

package/src/runtime/worker-pool.ts

@@ -39,6 +39,13 @@ export interface WorkerPoolOptions {
    * Use this for per-worker warmup (e.g., importing modules, running setup).
    */
   onWorkerReady?: (worker: PooledWorker) => Promise<void>;
+
+  /**
+   * Optional callback used only for background replacement workers after a
+   * fatal timeout/crash. This lets callers publish a replacement only after it
+   * is proven ready, without charging hidden work to normal request startup.
+   */
+  onReplacementWorkerReady?: (worker: PooledWorker) => Promise<void>;
 }
 
 /**
@@ -99,8 +106,12 @@ interface QueuedWaiter {
  * ```
  */
 export class WorkerPool extends BoundedContext {
-  private readonly options: Omit<Required<WorkerPoolOptions>, 'onWorkerReady'> & {
+  private readonly options: Omit<
+    Required<WorkerPoolOptions>,
+    'onWorkerReady' | 'onReplacementWorkerReady'
+  > & {
     onWorkerReady?: (worker: PooledWorker) => Promise<void>;
+    onReplacementWorkerReady?: (worker: PooledWorker) => Promise<void>;
   };
   private readonly workers: PooledWorker[] = [];
   private readonly waitQueue: QueuedWaiter[] = [];
@@ -135,6 +146,7 @@ export class WorkerPool extends BoundedContext {
       queueTimeoutMs: options.queueTimeoutMs ?? 30000,
       maxConcurrentPerWorker: options.maxConcurrentPerWorker ?? 1,
       onWorkerReady: options.onWorkerReady,
+      onReplacementWorkerReady: options.onReplacementWorkerReady,
     };
   }
 
@@ -319,8 +331,14 @@ export class WorkerPool extends BoundedContext {
    * - Process exited unexpectedly
    * - Pipe errors (EPIPE)
    * - Connection reset errors (ECONNRESET)
+   * - Request timeouts (the worker may still be busy with an uncancellable request)
    */
   private isFatalWorkerError(error: unknown): boolean {
+    // If a request times out, the underlying transport may still be executing it.
+    // Quarantine this worker so subsequent requests don't get stuck behind it.
+    if (error instanceof BridgeTimeoutError) {
+      return true;
+    }
     if (error instanceof BridgeProtocolError) {
       const msg = error.message.toLowerCase();
       return (
@@ -347,6 +365,7 @@ export class WorkerPool extends BoundedContext {
       worker.transport.dispose().catch(() => {
         // Ignore disposal errors for dead workers
       });
+      this.scheduleReplacementWorker();
     }
   }
 
@@ -386,13 +405,40 @@ export class WorkerPool extends BoundedContext {
     return this.workers.find(w => w.inFlightCount < this.options.maxConcurrentPerWorker);
   }
 
+  /**
+   * Replace a removed worker in the background so the next caller does not pay
+   * the full worker cold-start penalty after a timeout or crash.
+   */
+  private scheduleReplacementWorker(): void {
+    if (this.state !== 'ready') {
+      return;
+    }
+    if (this.workers.length + this.pendingCreations >= this.options.maxWorkers) {
+      return;
+    }
+
+    this.pendingCreations++;
+    const replacementReady = this.options.onReplacementWorkerReady ?? this.options.onWorkerReady;
+    this.createWorker(replacementReady)
+      .then(worker => {
+        // Reuse release() to wake queued callers if one is waiting.
+        this.release(worker);
+      })
+      .catch(() => {
+        // Ignore background replacement failures. A later acquire() can retry.
+      })
+      .finally(() => {
+        this.pendingCreations = Math.max(0, this.pendingCreations - 1);
+      });
+  }
+
   /**
    * Create a new worker and add it to the pool.
    *
    * If onWorkerReady is configured, calls it after the transport is initialized.
    * This is useful for per-worker warmup (importing modules, running setup).
    */
-  private async createWorker(): Promise<PooledWorker> {
+  private async createWorker(onWorkerReady = this.options.onWorkerReady): Promise<PooledWorker> {
     const transport = this.options.createTransport();
 
     // Initialize the transport
@@ -403,13 +449,28 @@ export class WorkerPool extends BoundedContext {
       inFlightCount: 0,
     };
 
-    this.workers.push(worker);
+    try {
+      // Call onWorkerReady callback if provided
+      if (onWorkerReady) {
+        await onWorkerReady(worker);
+      }
+    } catch (error) {
+      // Ensure partially initialized workers do not leak when warmup fails.
+      await transport.dispose().catch(() => {
+        // Ignore disposal failures during warmup failure handling.
+      });
+      throw error;
+    }
 
-    // Call onWorkerReady callback if provided
-    if (this.options.onWorkerReady) {
-      await this.options.onWorkerReady(worker);
+    if (this.state === 'disposing' || this.state === 'disposed') {
+      await transport.dispose().catch(() => {
+        // Ignore disposal failures if the pool was torn down mid-creation.
+      });
+      throw new BridgeExecutionError('Pool disposed during worker creation');
     }
 
+    this.workers.push(worker);
+
     return worker;
   }
 

package/src/types/global.d.ts

@@ -8,13 +8,20 @@ declare namespace DenoTypes {
     deno: string;
   }
 
+  interface CommandOptions {
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+  }
+
   interface DenoGlobal {
     version: Version;
     readTextFile(path: string): Promise<string>;
     writeTextFile(path: string, content: string): Promise<void>;
     Command: new (
       cmd: string,
-      options?: { args?: string[] }
+      options?: CommandOptions
     ) => {
       output(): Promise<{ code: number; stdout: Uint8Array; stderr: Uint8Array }>;
     };
@@ -37,12 +44,15 @@ declare namespace BunTypes {
       options?: {
         stdout?: string;
         stderr?: string;
+        cwd?: string;
+        env?: Record<string, string>;
       }
     ): {
       stdout: ReadableStream;
       stderr: ReadableStream;
       exitCode?: number;
       exited: Promise<void>;
+      kill(signal?: number | string): void;
     };
   }
 }

package/src/types/index.ts

@@ -8,6 +8,7 @@ export interface PythonModule {
   version?: string;
   functions: PythonFunction[];
   classes: PythonClass[];
+  typeAliases?: PythonTypeAlias[];
   imports: PythonImport[];
   exports: string[];
 }
@@ -19,6 +20,7 @@ export interface PythonFunction {
   decorators: string[];
   isAsync: boolean;
   isGenerator: boolean;
+  typeParameters?: PythonGenericParameter[];
   returnType: PythonType;
   parameters: Parameter[];
 }
@@ -31,6 +33,23 @@ export interface PythonClass {
   docstring?: string;
   decorators: string[];
   kind?: 'class' | 'protocol' | 'typed_dict' | 'namedtuple' | 'dataclass' | 'pydantic';
+  typeParameters?: PythonGenericParameter[];
+}
+
+export interface PythonTypeAlias {
+  name: string;
+  type: PythonType;
+  typeParameters?: PythonGenericParameter[];
+}
+
+export type PythonGenericParameterKind = 'typevar' | 'paramspec' | 'typevartuple';
+
+export interface PythonGenericParameter {
+  name: string;
+  kind: PythonGenericParameterKind;
+  bound?: PythonType;
+  constraints?: PythonType[];
+  variance?: 'covariant' | 'contravariant' | 'invariant';
 }
 
 export interface PythonImport {
@@ -47,12 +66,15 @@ export interface Parameter {
   defaultValue?: unknown;
   varArgs: boolean;
   kwArgs: boolean;
+  positionalOnly?: boolean;
+  keywordOnly?: boolean;
 }
 
 export interface Property {
   name: string;
   type: PythonType;
   readonly: boolean;
+  optional?: boolean;
   setter?: boolean;
   getter?: boolean;
 }
@@ -76,6 +98,11 @@ export type PythonType =
   | AnnotatedType
   | CustomType
   | TypeVarType
+  | ParamSpecType
+  | ParamSpecArgsType
+  | ParamSpecKwargsType
+  | TypeVarTupleType
+  | UnpackType
   | FinalType
   | ClassVarType;
 
@@ -103,6 +130,7 @@ export interface OptionalType {
 export interface GenericType {
   kind: 'generic';
   name: string;
+  module?: string;
   typeArgs: PythonType[];
 }
 
@@ -115,6 +143,7 @@ export interface CustomType {
 export interface CallableType {
   kind: 'callable';
   parameters: PythonType[];
+  parameterSpec?: ParamSpecType;
   returnType: PythonType;
 }
 
@@ -137,6 +166,31 @@ export interface TypeVarType {
   variance?: 'covariant' | 'contravariant' | 'invariant';
 }
 
+export interface ParamSpecType {
+  kind: 'paramspec';
+  name: string;
+}
+
+export interface ParamSpecArgsType {
+  kind: 'paramspec_args';
+  name: string;
+}
+
+export interface ParamSpecKwargsType {
+  kind: 'paramspec_kwargs';
+  name: string;
+}
+
+export interface TypeVarTupleType {
+  kind: 'typevartuple';
+  name: string;
+}
+
+export interface UnpackType {
+  kind: 'unpack';
+  type: PythonType;
+}
+
 export interface FinalType {
   kind: 'final';
   type: PythonType;
@@ -242,6 +296,11 @@ export type RuntimeStrategy = 'pyodide' | 'node' | 'http' | 'auto';
 
 export interface TywrapOptions {
   pythonModules: Record<string, PythonModuleConfig>;
+  /**
+   * Additional Python import paths to prepend to PYTHONPATH during code generation
+   * and discovery (IR extraction). Useful for local modules not installed in site-packages.
+   */
+  pythonImportPath?: string[];
   output: OutputConfig;
   runtime: RuntimeConfig;
   performance: PerformanceConfig;
@@ -255,6 +314,10 @@ export interface PythonModuleConfig {
   runtime: RuntimeStrategy;
   functions?: string[];
   classes?: string[];
+  /** Exclude specific exports by exact name. */
+  exclude?: string[];
+  /** Exclude exports matching one or more regex patterns (JavaScript RegExp source). */
+  excludePatterns?: string[];
   alias?: string;
   typeHints: 'strict' | 'loose' | 'ignore';
   watch?: boolean;