@renderinc/sdk 0.1.0 → 0.2.0

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>;
+}

package/src/workflows/types.ts

@@ -0,0 +1,89 @@
+import type { components } from "./schema.js";
+
+/**
+ * Task function signature
+ */
+export type TaskFunction<TArgs extends any[] = any[], TResult = any> = (
+  ...args: TArgs
+) => TResult | Promise<TResult>;
+
+export type TaskOptions = components["schemas"]["TaskOptions"];
+
+/**
+ * Task metadata
+ */
+export interface TaskMetadata {
+  name: string;
+  func: TaskFunction;
+  options?: TaskOptions;
+}
+
+/**
+ * Task context for executing subtasks
+ */
+export interface TaskContext {
+  executeTask<TArgs extends any[], TResult>(
+    task: TaskFunction<TArgs, TResult>,
+    taskName: string,
+    ...args: TArgs
+  ): TaskResult<TResult>;
+}
+
+/**
+ * Result of a task execution
+ */
+export interface TaskResult<T> {
+  get(): Promise<T>;
+}
+
+/**
+ * Task input from the workflow system
+ */
+export interface TaskInput {
+  task_name: string;
+  input: any[];
+}
+
+/**
+ * Task callback request/response types
+ */
+
+export type CallbackRequest = components["schemas"]["CallbackRequest"];
+
+export type GetInputResponse = components["schemas"]["InputResponse"];
+
+export type RunSubtaskRequest = components["schemas"]["RunSubtaskRequest"];
+
+export type RunSubtaskResponse = components["schemas"]["RunSubtaskResponse"];
+
+export type GetSubtaskResultRequest = components["schemas"]["SubtaskResultRequest"];
+
+export type GetSubtaskResultResponse = components["schemas"]["SubtaskResultResponse"];
+
+export type RegisterTasksRequest = components["schemas"]["Tasks"];
+
+/**
+ * Retry configuration for task execution
+ */
+export interface Retry {
+  maxRetries: number;
+  waitDurationMs: number;
+  backoffScaling?: number; // default 1.5
+}
+
+/**
+ * Task execution options
+ */
+export interface RegisterTaskOptions {
+  retry?: Retry;
+  timeoutSeconds?: number;
+  /**
+   * Resource plan for task execution.
+   * Common plans include:
+   * - "starter": 0.5 CPU, 512MB memory
+   * - "standard": 1 CPU, 2GB memory (default)
+   * - "pro": 2 CPU, 4GB memory
+   */
+  plan?: string;
+  name: string;
+}