@alienplatform/sdk 1.14.1 → 2.0.1

package/src/commands/errors.ts

@@ -1,126 +0,0 @@
-/**
- * Commands Client Error Definitions
- */
-
-import { defineError } from "@alienplatform/core"
-import { z } from "zod/v4"
-
-/**
- * Error thrown when command creation fails.
- */
-export const CommandCreationFailedError = defineError({
-  code: "COMMAND_CREATION_FAILED",
-  context: z.object({
-    deploymentId: z.string(),
-    command: z.string(),
-    reason: z.string(),
-  }),
-  message: ({ deploymentId, command, reason }) =>
-    `Failed to create command '${command}' for deployment '${deploymentId}': ${reason}`,
-  retryable: false,
-  internal: false,
-  httpStatusCode: 500,
-})
-
-/**
- * Error thrown when command execution times out.
- */
-export const CommandTimeoutError = defineError({
-  code: "COMMAND_TIMEOUT",
-  context: z.object({
-    commandId: z.string(),
-    command: z.string(),
-    timeoutMs: z.number(),
-    lastState: z.string(),
-  }),
-  message: ({ command, timeoutMs, lastState }) =>
-    `Command '${command}' timed out after ${timeoutMs}ms (last state: ${lastState})`,
-  retryable: true,
-  internal: false,
-  httpStatusCode: 504,
-})
-
-/**
- * Error thrown when the deployment returns an error response.
- */
-export const DeploymentCommandError = defineError({
-  code: "DEPLOYMENT_COMMAND_ERROR",
-  context: z.object({
-    commandId: z.string(),
-    command: z.string(),
-    errorCode: z.string(),
-    errorMessage: z.string(),
-    errorDetails: z.string().optional(),
-  }),
-  message: ({ command, errorCode, errorMessage }) =>
-    `Deployment command '${command}' failed: [${errorCode}] ${errorMessage}`,
-  retryable: false,
-  internal: false,
-  httpStatusCode: 500,
-})
-
-/**
- * Error thrown when command expires before completion.
- */
-export const CommandExpiredError = defineError({
-  code: "COMMAND_EXPIRED",
-  context: z.object({
-    commandId: z.string(),
-    command: z.string(),
-  }),
-  message: ({ command }) => `Command '${command}' expired before completion`,
-  retryable: false,
-  internal: false,
-  httpStatusCode: 410,
-})
-
-/**
- * Error thrown when storage upload/download fails.
- */
-export const StorageOperationFailedError = defineError({
-  code: "STORAGE_OPERATION_FAILED",
-  context: z.object({
-    operation: z.enum(["upload", "download"]),
-    url: z.string(),
-    reason: z.string(),
-  }),
-  message: ({ operation, reason }) => `Storage ${operation} failed: ${reason}`,
-  retryable: true,
-  internal: false,
-  httpStatusCode: 500,
-})
-
-/**
- * Error thrown when response decoding fails.
- */
-export const ResponseDecodingFailedError = defineError({
-  code: "RESPONSE_DECODING_FAILED",
-  context: z.object({
-    commandId: z.string(),
-    command: z.string(),
-    reason: z.string(),
-  }),
-  message: ({ command, reason }) => `Failed to decode response for command '${command}': ${reason}`,
-  retryable: false,
-  internal: false,
-  httpStatusCode: 500,
-})
-
-/**
- * Error thrown when Manager returns an HTTP error.
- */
-export const ManagerHttpError = defineError({
-  code: "MANAGER_HTTP_ERROR",
-  context: z.object({
-    method: z.string(),
-    url: z.string(),
-    status: z.number(),
-    statusText: z.string(),
-    body: z.string().optional(),
-  }),
-  message: ({ method, url, status, statusText }) =>
-    `Manager ${method} ${url} failed: ${status} ${statusText}`,
-  retryable: false,
-  internal: false,
-  httpStatusCode: 500,
-})

package/src/commands/index.ts

@@ -1,41 +0,0 @@
-/**
- * Commands client — invoke commands on remote Alien deployments.
- *
- * @example
- * ```typescript
- * import { CommandsClient } from "@alienplatform/sdk/commands"
- *
- * const commands = new CommandsClient({
- *   managerUrl: "https://manager.example.com",
- *   deploymentId: "deployment_123",
- *   token: "bearer_token",
- * })
- *
- * const result = await commands.invoke("generate-report", {
- *   startDate: "2024-01-01",
- *   endDate: "2024-01-31",
- * })
- * ```
- */
-
-export { CommandsClient } from "./client.js"
-export type {
-  CommandsClientConfig,
-  BodySpec,
-  CommandResponse,
-  CommandState,
-  CommandStatusResponse,
-  CreateCommandResponse,
-  InvokeOptions,
-  PresignedRequest,
-  StorageUpload,
-} from "./types.js"
-export {
-  DeploymentCommandError,
-  ManagerHttpError,
-  CommandCreationFailedError,
-  CommandExpiredError,
-  CommandTimeoutError,
-  ResponseDecodingFailedError,
-  StorageOperationFailedError,
-} from "./errors.js"

package/src/commands/types.ts

@@ -1,52 +0,0 @@
-/**
- * Commands Protocol Types
- *
- * Core command types are re-exported from @alienplatform/core,
- * which auto-generates them from the Rust implementation.
- */
-
-// Re-export core command types from @alienplatform/core
-export type {
-  BodySpec,
-  CommandState,
-  CommandResponse,
-  CommandStatusResponse,
-  CreateCommandResponse,
-  PresignedRequest,
-  PresignedRequestBackend,
-  StorageUpload,
-} from "@alienplatform/core"
-
-/**
- * Options for invoking a command
- */
-export interface InvokeOptions {
-  /** Timeout in milliseconds (default: 60000) */
-  timeout?: number
-  /** Optional deadline for command completion */
-  deadline?: Date
-  /** Optional idempotency key */
-  idempotencyKey?: string
-  /** Polling interval in milliseconds (default: 500) */
-  pollInterval?: number
-  /** Maximum polling interval in milliseconds (default: 5000) */
-  maxPollInterval?: number
-  /** Polling backoff multiplier (default: 1.5) */
-  pollBackoff?: number
-}
-
-/**
- * Configuration for CommandsClient
- */
-export interface CommandsClientConfig {
-  /** Manager URL (e.g., "https://manager.example.com") */
-  managerUrl: string
-  /** Deployment ID to invoke commands on */
-  deploymentId: string
-  /** Authentication token (deployment token or workspace token) */
-  token: string
-  /** Default timeout in milliseconds (default: 60000) */
-  timeout?: number
-  /** Allow reading local files for storage responses (default: false, only for local dev) */
-  allowLocalStorage?: boolean
-}

package/src/commands.ts

@@ -1,76 +0,0 @@
-/**
- * Command handling for Alien bindings.
- *
- * Provides command registration and execution.
- */
-
-/**
- * Command definition.
- */
-export interface CommandDefinition {
-  /** Command name */
-  name: string
-  /** Handler function that receives params and returns a result */
-  handler: (params: unknown) => Promise<unknown>
-}
-
-// Internal storage for commands
-const commands: Map<string, CommandDefinition> = new Map()
-
-/**
- * Register a command.
- *
- * @param name - Command name
- * @param handler - Command handler function that receives params and returns a result
- *
- * @example
- * ```typescript
- * import { command } from "@alienplatform/sdk"
- *
- * command("echo", async ({ message }: { message: string }) => {
- *   return {
- *     message,
- *     timestamp: new Date().toISOString(),
- *   }
- * })
- *
- * command("process-data", async ({ data }: { data: string[] }) => {
- *   const result = await processData(data)
- *   return { processed: result.length }
- * })
- * ```
- */
-export function command<TParams = unknown, TResult = unknown>(
-  name: string,
-  handler: (params: TParams) => Promise<TResult>,
-): void {
-  commands.set(name, { name, handler: handler as (params: unknown) => Promise<unknown> })
-}
-
-/**
- * Get all registered commands.
- *
- * @internal
- */
-export function getCommands(): Map<string, CommandDefinition> {
-  return commands
-}
-
-/**
- * Execute a command by name.
- *
- * @param name - Command name to execute
- * @param params - Command parameters
- * @returns Command result
- *
- * @internal
- */
-export async function runCommand(name: string, params: unknown): Promise<unknown> {
-  const cmd = commands.get(name)
-
-  if (!cmd) {
-    throw new Error(`Unknown command: ${name}. Available: ${[...commands.keys()].join(", ")}`)
-  }
-
-  return await cmd.handler(params)
-}

package/src/context.ts

@@ -1,368 +0,0 @@
-/**
- * AlienContext - Main entry point for Alien bindings.
- *
- * Provides access to all bindings and control plane functionality.
- */
-
-import type { StorageEvent } from "@alienplatform/core"
-import { AlienError } from "@alienplatform/core"
-import type { Channel } from "nice-grpc"
-import { createClient } from "nice-grpc"
-import { ArtifactRegistry } from "./bindings/artifact-registry.js"
-import { Build } from "./bindings/build.js"
-import { Kv } from "./bindings/kv.js"
-import { Queue } from "./bindings/queue.js"
-import { ServiceAccount } from "./bindings/service-account.js"
-import { Storage } from "./bindings/storage.js"
-import { Vault } from "./bindings/vault.js"
-import { WorkerBinding } from "./bindings/worker.js"
-import { createGrpcChannel, getOrCreateChannel } from "./channel.js"
-import { command } from "./commands.js"
-import { InvalidBindingConfigError } from "./errors.js"
-import {
-  type CronEvent,
-  EventLoop,
-  type QueueMessageEvent,
-  onCronEvent,
-  onQueueMessage,
-  onStorageEvent,
-} from "./events.js"
-import { ControlServiceDefinition } from "./generated/control.js"
-import { wrapGrpcCall } from "./grpc-utils.js"
-import type { AlienBindingsConfig, AlienBindingsProvider } from "./types.js"
-import { type WaitUntilManager, initWaitUntilManager, waitUntil } from "./wait-until.js"
-
-/**
- * Instance ID for this worker process.
- */
-function generateInstanceId(): string {
-  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`
-}
-
-/**
- * AlienContext provides the main entry point for accessing Alien bindings
- * and control plane functionality.
- *
- * @example
- * ```typescript
- * import { AlienContext } from "@alienplatform/sdk"
- *
- * // Create context from environment
- * const ctx = AlienContext.fromEnv()
- *
- * // Access bindings
- * const bucket = ctx.storage("my-bucket")
- * await bucket.put("hello.txt", "Hello, World!")
- *
- * // Register event handlers
- * ctx.onStorageEvent("uploads", async (event) => {
- *   console.log("File uploaded:", event.key)
- * })
- *
- * // Start the runtime
- * await ctx.run()
- * ```
- */
-export class AlienContext implements AlienBindingsProvider {
-  private readonly channel: Channel
-  private readonly instanceId: string
-  private readonly bindingCache = new Map<string, unknown>()
-  private eventLoop: EventLoop | undefined
-  private waitUntilManager: WaitUntilManager | undefined
-
-  private constructor(channel: Channel, instanceId?: string) {
-    this.channel = channel
-    this.instanceId = instanceId ?? generateInstanceId()
-  }
-
-  /**
-   * Create a context from environment variables.
-   *
-   * Reads the ALIEN_BINDINGS_GRPC_ADDRESS environment variable.
-   */
-  static async fromEnv(): Promise<AlienContext> {
-    const address = process.env.ALIEN_BINDINGS_GRPC_ADDRESS
-
-    if (!address) {
-      throw new AlienError(
-        InvalidBindingConfigError.create({
-          message: "ALIEN_BINDINGS_GRPC_ADDRESS environment variable is not set",
-          suggestion:
-            "Make sure you're running inside an Alien worker or set the variable manually",
-        }),
-      )
-    }
-
-    const channel = await getOrCreateChannel(address)
-    return new AlienContext(channel)
-  }
-
-  /**
-   * Create a context with explicit configuration.
-   */
-  static async create(config: AlienBindingsConfig): Promise<AlienContext> {
-    if (!config.grpcAddress) {
-      throw new AlienError(
-        InvalidBindingConfigError.create({
-          message: "gRPC address is required",
-          suggestion: "Provide grpcAddress in the config",
-        }),
-      )
-    }
-
-    const channel = await createGrpcChannel(config.grpcAddress)
-    return new AlienContext(channel)
-  }
-
-  /**
-   * Create a context for connecting to a remote agent.
-   *
-   * @param address - gRPC address of the remote agent
-   */
-  // TODO: Implement remote agent connection
-  static async forRemoteAgent(address: string): Promise<AlienContext> {
-    const channel = await createGrpcChannel(address)
-    return new AlienContext(channel)
-  }
-
-  /**
-   * Get or create a cached binding instance.
-   */
-  private getBinding<T>(key: string, factory: () => T): T {
-    let binding = this.bindingCache.get(key) as T | undefined
-    if (!binding) {
-      binding = factory()
-      this.bindingCache.set(key, binding)
-    }
-    return binding
-  }
-
-  // ============================================================================
-  // Binding Accessors
-  // ============================================================================
-
-  /**
-   * Get a storage binding.
-   *
-   * @param name - Binding name
-   * @returns Storage binding instance
-   */
-  storage(name: string): Storage {
-    return this.getBinding(`storage:${name}`, () => new Storage(this.channel, name))
-  }
-
-  /**
-   * Get a KV binding.
-   *
-   * @param name - Binding name
-   * @returns KV binding instance
-   */
-  kv(name: string): Kv {
-    return this.getBinding(`kv:${name}`, () => new Kv(this.channel, name))
-  }
-
-  /**
-   * Get a queue binding.
-   *
-   * @param name - Binding name
-   * @returns Queue binding instance
-   */
-  queue(name: string): Queue {
-    return this.getBinding(`queue:${name}`, () => new Queue(this.channel, name))
-  }
-
-  /**
-   * Get a vault binding.
-   *
-   * @param name - Binding name
-   * @returns Vault binding instance
-   */
-  vault(name: string): Vault {
-    return this.getBinding(`vault:${name}`, () => new Vault(this.channel, name))
-  }
-
-  /**
-   * Get a build binding.
-   *
-   * @param name - Binding name
-   * @returns Build binding instance
-   */
-  build(name: string): Build {
-    return this.getBinding(`build:${name}`, () => new Build(this.channel, name))
-  }
-
-  /**
-   * Get an artifact registry binding.
-   *
-   * @param name - Binding name
-   * @returns ArtifactRegistry binding instance
-   */
-  artifactRegistry(name: string): ArtifactRegistry {
-    return this.getBinding(
-      `artifact-registry:${name}`,
-      () => new ArtifactRegistry(this.channel, name),
-    )
-  }
-
-  /**
-   * Get a worker binding.
-   *
-   * @param name - Binding name
-   * @returns Worker binding instance
-   */
-  worker(name: string): WorkerBinding {
-    return this.getBinding(`worker:${name}`, () => new WorkerBinding(this.channel, name))
-  }
-
-  /**
-   * Get a service account binding.
-   *
-   * @param name - Binding name
-   * @returns ServiceAccount binding instance
-   */
-  serviceAccount(name: string): ServiceAccount {
-    return this.getBinding(`service-account:${name}`, () => new ServiceAccount(this.channel, name))
-  }
-
-  // ============================================================================
-  // Event Handlers
-  // ============================================================================
-
-  /**
-   * Register a storage event handler.
-   *
-   * @param bucket - Bucket name
-   * @param handler - Event handler
-   * @param options - Handler options
-   * @returns Unsubscribe function
-   */
-  onStorageEvent(
-    bucket: string,
-    handler: (event: StorageEvent) => Promise<void>,
-    options?: { prefix?: string },
-  ): () => void {
-    return onStorageEvent(bucket, handler, options)
-  }
-
-  /**
-   * Register a cron event handler.
-   *
-   * @param schedule - Cron schedule expression
-   * @param handler - Event handler
-   * @returns Unsubscribe function
-   */
-  onCronEvent(schedule: string, handler: (event: CronEvent) => Promise<void>): () => void {
-    return onCronEvent(schedule, handler)
-  }
-
-  /**
-   * Register a queue message handler.
-   *
-   * @param queueName - Queue name
-   * @param handler - Message handler
-   * @returns Unsubscribe function
-   */
-  onQueueMessage<T = unknown>(
-    queueName: string,
-    handler: (message: QueueMessageEvent<T>) => Promise<void>,
-  ): () => void {
-    return onQueueMessage(queueName, handler)
-  }
-
-  // ============================================================================
-  // Commands
-  // ============================================================================
-
-  /**
-   * Register a command.
-   *
-   * @param name - Command name
-   * @param handler - Command handler that receives params and returns a result
-   */
-  command<TParams = unknown, TResult = unknown>(
-    name: string,
-    handler: (params: TParams) => Promise<TResult>,
-  ): void {
-    command(name, handler)
-  }
-
-  // ============================================================================
-  // HTTP Server Registration
-  // ============================================================================
-
-  /**
-   * Register an HTTP server with the control plane.
-   *
-   * @param port - Port the server is listening on
-   */
-  async registerHttpServer(port: number): Promise<void> {
-    const client = createClient(ControlServiceDefinition, this.channel)
-
-    await wrapGrpcCall(
-      "ControlService",
-      "RegisterHttpServer",
-      async () => {
-        await client.registerHttpServer({ port })
-      },
-      {},
-    )
-  }
-
-  // ============================================================================
-  // WaitUntil
-  // ============================================================================
-
-  /**
-   * Register a background task.
-   *
-   * @param promise - The promise to track
-   */
-  waitUntil(promise: Promise<unknown>): void {
-    waitUntil(promise)
-  }
-
-  // ============================================================================
-  // Lifecycle
-  // ============================================================================
-
-  /**
-   * Start the Alien runtime.
-   *
-   * This initializes event handlers, registers with the control plane,
-   * and starts processing events.
-   */
-  async run(): Promise<void> {
-    // Initialize wait-until manager
-    this.waitUntilManager = initWaitUntilManager(this.channel, this.instanceId)
-
-    // Initialize event loop
-    this.eventLoop = new EventLoop(this.channel, this.instanceId)
-
-    // Register event handlers with the control plane
-    await this.eventLoop.registerHandlers()
-
-    // Start event loop (handles commands, events, etc.)
-    await this.eventLoop.start()
-  }
-
-  /**
-   * Stop the runtime gracefully.
-   */
-  async shutdown(): Promise<void> {
-    // Stop event loop
-    this.eventLoop?.stop()
-
-    // Wait for all background tasks
-    await this.waitUntilManager?.waitForAll()
-
-    // Notify drain complete
-    const tasks = this.waitUntilManager?.getTasks()
-    if (tasks) {
-      const taskArray = Array.from(tasks.values())
-      const tasksDrained = taskArray.length
-      const allSuccess = taskArray.every(t => !t.error)
-      const errorMessage = taskArray.find(t => t.error)?.error?.message
-      await this.waitUntilManager?.notifyDrainComplete(tasksDrained, allSuccess, errorMessage)
-    }
-  }
-}