@renderinc/sdk 0.1.0 → 0.2.1

package/src/workflows/registry.test.ts

@@ -0,0 +1,76 @@
+import { TaskRegistry } from "./registry.js";
+
+describe("TaskRegistry", () => {
+  let registry: TaskRegistry;
+
+  beforeEach(() => {
+    // Get a fresh registry for each test
+    registry = TaskRegistry.getInstance();
+    registry.clear();
+  });
+
+  describe("register", () => {
+    it("should register a task with timeout_seconds", () => {
+      const taskFn = () => 42;
+
+      registry.register(taskFn, {
+        name: "timeout_task",
+        timeoutSeconds: 120,
+      });
+
+      const task = registry.get("timeout_task");
+      expect(task).toBeDefined();
+      expect(task?.options?.timeout_seconds).toBe(120);
+    });
+
+    it("should register a task without timeout_seconds", () => {
+      const taskFn = () => 42;
+
+      registry.register(taskFn, {
+        name: "no_timeout_task",
+      });
+
+      const task = registry.get("no_timeout_task");
+      expect(task).toBeDefined();
+      expect(task?.options).toBeUndefined();
+    });
+
+    it("should register a task with both retry and timeout_seconds", () => {
+      const taskFn = () => 42;
+
+      registry.register(taskFn, {
+        name: "both_options_task",
+        timeoutSeconds: 300,
+        retry: {
+          maxRetries: 3,
+          waitDurationMs: 1000,
+          backoffScaling: 2.0,
+        },
+      });
+
+      const task = registry.get("both_options_task");
+      expect(task).toBeDefined();
+      expect(task?.options?.timeout_seconds).toBe(300);
+      expect(task?.options?.retry?.max_retries).toBe(3);
+      expect(task?.options?.retry?.wait_duration_ms).toBe(1000);
+      expect(task?.options?.retry?.factor).toBe(2.0);
+    });
+
+    it("should register a task with only retry options", () => {
+      const taskFn = () => 42;
+
+      registry.register(taskFn, {
+        name: "retry_only_task",
+        retry: {
+          maxRetries: 2,
+          waitDurationMs: 500,
+        },
+      });
+
+      const task = registry.get("retry_only_task");
+      expect(task).toBeDefined();
+      expect(task?.options?.retry?.max_retries).toBe(2);
+      expect(task?.options?.timeout_seconds).toBeUndefined();
+    });
+  });
+});

package/src/workflows/registry.ts

@@ -0,0 +1,88 @@
+import type { RegisterTaskOptions, TaskFunction, TaskMetadata, TaskOptions } from "./types.js";
+
+/**
+ * Global task registry
+ */
+export class TaskRegistry {
+  private static instance: TaskRegistry;
+  private readonly tasks: Map<string, TaskMetadata> = new Map();
+
+  private constructor() {}
+
+  static getInstance(): TaskRegistry {
+    if (!TaskRegistry.instance) {
+      TaskRegistry.instance = new TaskRegistry();
+    }
+    return TaskRegistry.instance;
+  }
+
+  /**
+   * Register a task with optional name and options
+   */
+  register(func: TaskFunction, options: RegisterTaskOptions): void {
+    const taskName = options.name;
+    if (!taskName) {
+      throw new Error("Task function must have a name or name must be provided");
+    }
+
+    let taskOptions: TaskOptions | undefined;
+
+    if (options.retry || options.timeoutSeconds || options.plan) {
+      taskOptions = {};
+
+      if (options.retry) {
+        taskOptions.retry = {
+          max_retries: options.retry.maxRetries,
+          wait_duration_ms: options.retry.waitDurationMs,
+          factor: options.retry.backoffScaling,
+        };
+      }
+
+      if (options.timeoutSeconds) {
+        taskOptions.timeout_seconds = options.timeoutSeconds;
+      }
+
+      if (options.plan) {
+        taskOptions.plan = options.plan;
+      }
+    }
+
+    this.tasks.set(taskName, {
+      name: taskName,
+      func,
+      options: taskOptions,
+    });
+  }
+
+  /**
+   * Get a task by name
+   */
+  get(name: string): TaskMetadata | undefined {
+    return this.tasks.get(name);
+  }
+
+  /**
+   * Get all registered task names
+   */
+  getAllTaskNames(): string[] {
+    return Array.from(this.tasks.keys());
+  }
+
+  getAllTasks(): TaskMetadata[] {
+    return Array.from(this.tasks.values());
+  }
+
+  /**
+   * Check if a task is registered
+   */
+  has(name: string): boolean {
+    return this.tasks.has(name);
+  }
+
+  /**
+   * Clear all registered tasks (useful for testing)
+   */
+  clear(): void {
+    this.tasks.clear();
+  }
+}

package/src/workflows/runner.ts

@@ -0,0 +1,38 @@
+import { RenderError } from "../errors.js";
+import { TaskExecutor } from "./executor.js";
+import { markServerStarted } from "./task.js";
+
+/**
+ * Start the task server and listen for task execution requests
+ */
+export async function startTaskServer(): Promise<void> {
+  const mode = process.env.RENDER_SDK_MODE || "run";
+  const socketPath = process.env.RENDER_SDK_SOCKET_PATH;
+
+  if (!socketPath) {
+    throw new RenderError("RENDER_SDK_SOCKET_PATH environment variable is required");
+  }
+
+  const executor = new TaskExecutor(socketPath);
+
+  // Mark server as started to warn about late task registrations
+  markServerStarted();
+
+  if (mode === "register") {
+    // Register tasks mode
+    await executor.registerTasks();
+  } else if (mode === "run") {
+    // Run task mode
+    await executor.executeTask();
+  } else {
+    throw new RenderError(`Unknown SDK mode: ${mode}`);
+  }
+}
+
+/**
+ * Run a specific task (for testing or direct execution)
+ */
+export async function run(socketPath: string): Promise<void> {
+  const executor = new TaskExecutor(socketPath);
+  await executor.executeTask();
+}

package/src/workflows/schema.ts

@@ -0,0 +1,348 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+  "/input": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /** Get the task name and input for a task run */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description Input received */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["InputResponse"];
+          };
+        };
+        /** @description Internal server error */
+        500: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/callback": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /** Receive a callback from a workflow */
+    post: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: {
+        content: {
+          "application/json": components["schemas"]["CallbackRequest"];
+        };
+      };
+      responses: {
+        /** @description Callback received */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+        /** @description Bad request */
+        400: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+        /** @description Unauthorized */
+        401: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+        /** @description Forbidden */
+        403: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+        /** @description Internal server error */
+        500: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+      };
+    };
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/register-tasks": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /** Publish registered tasks */
+    post: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: {
+        content: {
+          "application/json": components["schemas"]["Tasks"];
+        };
+      };
+      responses: {
+        /** @description Callback received */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+        /** @description Bad request */
+        400: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+        /** @description Internal server error */
+        500: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+      };
+    };
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/run-subtask": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /** Trigger a subtask */
+    post: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: {
+        content: {
+          "application/json": components["schemas"]["RunSubtaskRequest"];
+        };
+      };
+      responses: {
+        /** @description OK */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["RunSubtaskResponse"];
+          };
+        };
+        /** @description Internal server error */
+        500: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+      };
+    };
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/get-subtask-result": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /** Fetch the results for a subtask */
+    post: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: {
+        content: {
+          "application/json": components["schemas"]["SubtaskResultRequest"];
+        };
+      };
+      responses: {
+        /** @description OK */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["SubtaskResultResponse"];
+          };
+        };
+        /** @description Internal server error */
+        500: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+      };
+    };
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+  schemas: {
+    CallbackRequest: {
+      error?: components["schemas"]["TaskError"];
+      complete?: components["schemas"]["TaskComplete"];
+    };
+    TaskError: {
+      details: string;
+      stack_trace?: string;
+    };
+    TaskComplete: {
+      /** Format: byte */
+      output: string;
+    };
+    RunSubtaskRequest: {
+      task_name: string;
+      /** Format: byte */
+      input?: string;
+    };
+    RunSubtaskResponse: {
+      task_run_id: string;
+    };
+    SubtaskResultRequest: {
+      task_run_id: string;
+    };
+    SubtaskResultResponse: {
+      still_running: boolean;
+      error?: components["schemas"]["TaskError"];
+      complete?: components["schemas"]["TaskComplete"];
+    };
+    InputResponse: {
+      task_name: string;
+      /** Format: byte */
+      input: string;
+    };
+    Tasks: {
+      tasks: components["schemas"]["Task"][];
+    };
+    Task: {
+      name: string;
+      options?: components["schemas"]["TaskOptions"];
+      /** @description Parameter schema extracted from the task function signature */
+      parameters?: components["schemas"]["TaskParameter"][];
+    };
+    /** @description Information about a task parameter extracted from function signature */
+    TaskParameter: {
+      /** @description Parameter name */
+      name: string;
+      /** @description String representation of the parameter type hint */
+      type?: string;
+      /** @description Whether the parameter has a default value */
+      has_default: boolean;
+      /** @description JSON-encoded default value (if has_default is true) */
+      default_value?: string;
+    };
+    TaskOptions: {
+      retry?: components["schemas"]["RetryConfig"];
+      /**
+       * Format: int64
+       * @description Task execution timeout in seconds (30-86400)
+       */
+      timeout_seconds?: number;
+      /** @description Resource plan for task execution */
+      plan?: string;
+    };
+    RetryConfig: {
+      /** @description Maximum number of retry attempts */
+      max_retries?: number;
+      /**
+       * Format: int64
+       * @description Initial wait duration between retries (in milliseconds)
+       */
+      wait_duration_ms?: number;
+      /** @description Backoff factor for exponential retry */
+      factor?: number;
+    };
+  };
+  responses: never;
+  parameters: never;
+  requestBodies: never;
+  headers: never;
+  pathItems: never;
+}
+export type $defs = Record<string, never>;
+export type operations = Record<string, never>;

package/src/workflows/task.ts

@@ -0,0 +1,117 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { TaskRegistry } from "./registry.js";
+import type { RegisterTaskOptions, TaskContext, TaskFunction } from "./types.js";
+
+/**
+ * Storage for the current task execution context
+ */
+const taskContextStorage = new AsyncLocalStorage<TaskContext>();
+
+/**
+ * Flag to track if auto-start has been scheduled
+ */
+let autoStartScheduled = false;
+
+/**
+ * Flag to track if the server has started (set after startTaskServer completes)
+ */
+let serverStarted = false;
+
+/**
+ * Mark the server as started (called by runner after successful start)
+ */
+export function markServerStarted(): void {
+  serverStarted = true;
+}
+
+/**
+ * Check if auto-start should be enabled based on environment
+ */
+function shouldAutoStart(): boolean {
+  // Must be in a workflow environment (socket path set)
+  if (!process.env.RENDER_SDK_SOCKET_PATH) {
+    return false;
+  }
+
+  // Check for opt-out via RENDER_SDK_AUTO_START=false
+  const autoStartEnv = process.env.RENDER_SDK_AUTO_START;
+  if (autoStartEnv !== undefined && autoStartEnv.toLowerCase() === "false") {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Get the current task context (only available during task execution)
+ */
+export function getCurrentContext(): TaskContext | undefined {
+  return taskContextStorage.getStore();
+}
+
+/**
+ * Set the current task context (used internally by executor)
+ */
+export function setCurrentContext<T>(context: TaskContext, fn: () => Promise<T>): Promise<T> {
+  return taskContextStorage.run(context, fn);
+}
+
+/**
+ * Register a task with the workflow system.
+ *
+ * When running in a workflow environment (RENDER_SDK_SOCKET_PATH is set),
+ * the task server will automatically start after all synchronously-defined
+ * tasks are registered. This can be disabled by setting RENDER_SDK_AUTO_START=false.
+ *
+ * @param func Task function
+ * @param options Optional task options
+ * @returns The registered function with the same signature
+ */
+export function task<TArgs extends any[], TResult>(
+  options: RegisterTaskOptions,
+  func: TaskFunction<TArgs, TResult>,
+): TaskFunction<TArgs, TResult> {
+  // Warn if task is registered after server has started. This is possible if
+  // the task is loaded via dynamic import.
+  if (serverStarted) {
+    console.warn(
+      `Warning: Task '${options.name}' was registered after the task server started. ` +
+        `This task will not be available for execution. ` +
+        `Ensure all tasks are defined synchronously at module level.`,
+    );
+  }
+
+  const registry = TaskRegistry.getInstance();
+  registry.register(func, options);
+
+  // Schedule auto-start on first task registration when in workflow environment
+  if (!autoStartScheduled && shouldAutoStart()) {
+    autoStartScheduled = true;
+    setImmediate(async () => {
+      const { startTaskServer } = await import("./runner.js");
+      try {
+        await startTaskServer();
+      } catch (error) {
+        console.error("Failed to start task server:", error);
+        process.exit(1);
+      }
+    });
+  }
+
+  // Return a wrapper function that executes the task as a subtask
+  return ((...args: TArgs): TResult | Promise<TResult> => {
+    const context = getCurrentContext();
+
+    if (!context) {
+      // If we're not in a task execution context, just run the function directly
+      // This allows for testing and direct invocation
+      return func(...args);
+    }
+
+    // Execute as a subtask through the context
+    const result = context.executeTask(func, options.name, ...args);
+
+    // Return the result wrapped in a promise that awaits the subtask
+    return result.get();
+  }) as TaskFunction<TArgs, TResult>;
+}