@alienplatform/bindings 1.0.0

package/src/bindings/build.ts

@@ -0,0 +1,195 @@
+/**
+ * Build binding implementation.
+ *
+ * Provides build execution capabilities.
+ */
+
+import type { BuildStatus } from "@alienplatform/core"
+import { type Channel, createClient } from "nice-grpc"
+import {
+  type BuildConfig as BuildConfigProto,
+  type BuildExecution as BuildExecutionProto,
+  BuildServiceDefinition,
+  BuildStatus as BuildStatusProto,
+  ComputeType,
+  type BuildServiceClient as GeneratedBuildServiceClient,
+} from "../generated/build.js"
+import { wrapGrpcCall } from "../grpc-utils.js"
+import type { BuildExecution, BuildStartConfig } from "../types.js"
+
+// Map proto status to core BuildStatus (matches Rust: Unspecified → Failed)
+const statusMap: Record<number, BuildStatus> = {
+  [BuildStatusProto.BUILD_STATUS_UNSPECIFIED]: "FAILED",
+  [BuildStatusProto.BUILD_STATUS_QUEUED]: "QUEUED",
+  [BuildStatusProto.BUILD_STATUS_RUNNING]: "RUNNING",
+  [BuildStatusProto.BUILD_STATUS_SUCCEEDED]: "SUCCEEDED",
+  [BuildStatusProto.BUILD_STATUS_FAILED]: "FAILED",
+  [BuildStatusProto.BUILD_STATUS_CANCELLED]: "CANCELLED",
+  [BuildStatusProto.BUILD_STATUS_TIMED_OUT]: "TIMED_OUT",
+}
+
+// Map compute type to proto
+const computeTypeMap: Record<string, ComputeType> = {
+  small: ComputeType.COMPUTE_TYPE_SMALL,
+  medium: ComputeType.COMPUTE_TYPE_MEDIUM,
+  large: ComputeType.COMPUTE_TYPE_LARGE,
+  "x-large": ComputeType.COMPUTE_TYPE_XLARGE,
+}
+
+/**
+ * Build binding for executing build operations.
+ *
+ * @example
+ * ```typescript
+ * import { build } from "@alienplatform/bindings"
+ *
+ * const builder = build("my-builder")
+ *
+ * // Start a build
+ * const execution = await builder.start({
+ *   script: "npm run build",
+ *   computeType: "medium",
+ *   timeoutSeconds: 600,
+ * })
+ *
+ * // Wait for completion
+ * const result = await builder.waitForCompletion(execution.id)
+ * console.log("Build status:", result.status)
+ * ```
+ */
+export class Build {
+  private readonly client: GeneratedBuildServiceClient
+  private readonly bindingName: string
+
+  constructor(channel: Channel, bindingName: string) {
+    this.client = createClient(BuildServiceDefinition, channel)
+    this.bindingName = bindingName
+  }
+
+  /**
+   * Start a new build.
+   *
+   * @param config - Build configuration
+   * @returns Build execution information
+   */
+  async start(config: BuildStartConfig): Promise<BuildExecution> {
+    const protoConfig = this.toProtoConfig(config)
+
+    return await wrapGrpcCall(
+      "BuildService",
+      "StartBuild",
+      async () => {
+        const response = await this.client.startBuild({
+          bindingName: this.bindingName,
+          config: protoConfig,
+        })
+        return this.fromProtoExecution(response.execution!)
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Get the status of a build.
+   *
+   * @param buildId - Build execution ID
+   * @returns Build execution information
+   */
+  async getStatus(buildId: string): Promise<BuildExecution> {
+    return await wrapGrpcCall(
+      "BuildService",
+      "GetBuildStatus",
+      async () => {
+        const response = await this.client.getBuildStatus({
+          bindingName: this.bindingName,
+          buildId,
+        })
+        return this.fromProtoExecution(response.execution!)
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Stop a running build.
+   *
+   * @param buildId - Build execution ID
+   */
+  async stop(buildId: string): Promise<void> {
+    await wrapGrpcCall(
+      "BuildService",
+      "StopBuild",
+      async () => {
+        await this.client.stopBuild({
+          bindingName: this.bindingName,
+          buildId,
+        })
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Wait for a build to complete.
+   *
+   * @param buildId - Build execution ID
+   * @param options - Polling options
+   * @returns Final build execution information
+   */
+  async waitForCompletion(
+    buildId: string,
+    options?: { pollIntervalMs?: number; timeoutMs?: number },
+  ): Promise<BuildExecution> {
+    const pollInterval = options?.pollIntervalMs ?? 5000
+    const timeout = options?.timeoutMs ?? 30 * 60 * 1000 // 30 minutes default
+    const startTime = Date.now()
+
+    while (Date.now() - startTime < timeout) {
+      const execution = await this.getStatus(buildId)
+
+      if (
+        execution.status === "SUCCEEDED" ||
+        execution.status === "FAILED" ||
+        execution.status === "CANCELLED" ||
+        execution.status === "TIMED_OUT"
+      ) {
+        return execution
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollInterval))
+    }
+
+    throw new Error(`Build ${buildId} did not complete within timeout`)
+  }
+
+  // Private helpers
+
+  private toProtoConfig(config: BuildStartConfig): BuildConfigProto {
+    return {
+      script: config.script,
+      environment: config.environment ?? {},
+      computeType: config.computeType
+        ? (computeTypeMap[config.computeType] ?? ComputeType.COMPUTE_TYPE_UNSPECIFIED)
+        : ComputeType.COMPUTE_TYPE_UNSPECIFIED,
+      timeoutSeconds: config.timeoutSeconds,
+      monitoring: config.monitoring
+        ? {
+            endpoint: config.monitoring.endpoint,
+            headers: config.monitoring.headers ?? {},
+            logsUri: config.monitoring.logsUri ?? "/v1/logs",
+            tlsEnabled: config.monitoring.tlsEnabled ?? true,
+            tlsVerify: config.monitoring.tlsVerify ?? true,
+          }
+        : undefined,
+    }
+  }
+
+  private fromProtoExecution(proto: BuildExecutionProto): BuildExecution {
+    return {
+      id: proto.id,
+      status: statusMap[proto.status] ?? "QUEUED",
+      startTime: proto.startTime ? new Date(proto.startTime) : undefined,
+      endTime: proto.endTime ? new Date(proto.endTime) : undefined,
+    }
+  }
+}

package/src/bindings/function.ts

@@ -0,0 +1,164 @@
+/**
+ * Function binding implementation.
+ *
+ * Provides direct function-to-function invocation.
+ */
+
+import { type Channel, createClient } from "nice-grpc"
+import {
+  FunctionServiceDefinition,
+  type FunctionServiceClient as GeneratedClient,
+} from "../generated/function.js"
+import { wrapGrpcCall } from "../grpc-utils.js"
+import type { FunctionInvokeRequest, FunctionInvokeResponse } from "../types.js"
+
+/**
+ * Function binding for direct function invocation.
+ *
+ * @example
+ * ```typescript
+ * import { func } from "@alienplatform/bindings"
+ *
+ * const processor = func("image-processor")
+ *
+ * // Invoke with JSON body
+ * const response = await processor.invokeJson("resize-image", {
+ *   imageUrl: "https://...",
+ *   width: 800,
+ *   height: 600,
+ * })
+ *
+ * // Get function URL
+ * const url = await processor.getUrl()
+ * ```
+ */
+export class FunctionBinding {
+  private readonly client: GeneratedClient
+  private readonly bindingName: string
+
+  constructor(channel: Channel, bindingName: string) {
+    this.client = createClient(FunctionServiceDefinition, channel)
+    this.bindingName = bindingName
+  }
+
+  /**
+   * Invoke a function with raw request data.
+   *
+   * @param request - Invocation request
+   * @returns Function response
+   */
+  async invoke(request: FunctionInvokeRequest): Promise<FunctionInvokeResponse> {
+    return await wrapGrpcCall(
+      "FunctionService",
+      "Invoke",
+      async () => {
+        const response = await this.client.invoke({
+          bindingName: this.bindingName,
+          targetFunction: request.targetFunction,
+          method: request.method,
+          path: request.path,
+          headers: request.headers ?? {},
+          body: request.body ?? new Uint8Array(),
+          timeoutSeconds: request.timeoutMs ? Math.floor(request.timeoutMs / 1000) : undefined,
+        })
+        return {
+          status: response.status,
+          headers: response.headers,
+          body: response.body,
+        }
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Invoke a function with a JSON body.
+   *
+   * @param targetFunction - Target function identifier
+   * @param body - JSON body
+   * @param options - Optional request options
+   * @returns Parsed JSON response
+   */
+  async invokeJson<TRequest, TResponse = unknown>(
+    targetFunction: string,
+    body: TRequest,
+    options?: {
+      method?: string
+      path?: string
+      headers?: Record<string, string>
+      timeoutMs?: number
+    },
+  ): Promise<TResponse> {
+    const response = await this.invoke({
+      targetFunction,
+      method: options?.method ?? "POST",
+      path: options?.path ?? "/",
+      headers: {
+        "content-type": "application/json",
+        ...options?.headers,
+      },
+      body: new TextEncoder().encode(JSON.stringify(body)),
+      timeoutMs: options?.timeoutMs,
+    })
+
+    if (response.status >= 400) {
+      const errorText = new TextDecoder().decode(response.body)
+      throw new Error(`Function invocation failed with status ${response.status}: ${errorText}`)
+    }
+
+    const responseText = new TextDecoder().decode(response.body)
+    return JSON.parse(responseText) as TResponse
+  }
+
+  /**
+   * Invoke a function with GET request.
+   *
+   * @param targetFunction - Target function identifier
+   * @param path - Request path
+   * @param options - Optional request options
+   * @returns Parsed JSON response
+   */
+  async get<TResponse = unknown>(
+    targetFunction: string,
+    path = "/",
+    options?: {
+      headers?: Record<string, string>
+      timeoutMs?: number
+    },
+  ): Promise<TResponse> {
+    const response = await this.invoke({
+      targetFunction,
+      method: "GET",
+      path,
+      headers: options?.headers,
+      timeoutMs: options?.timeoutMs,
+    })
+
+    if (response.status >= 400) {
+      const errorText = new TextDecoder().decode(response.body)
+      throw new Error(`Function GET failed with status ${response.status}: ${errorText}`)
+    }
+
+    const responseText = new TextDecoder().decode(response.body)
+    return JSON.parse(responseText) as TResponse
+  }
+
+  /**
+   * Get the public URL of the function.
+   *
+   * @returns Function URL if available
+   */
+  async getUrl(): Promise<string | undefined> {
+    return await wrapGrpcCall(
+      "FunctionService",
+      "GetFunctionUrl",
+      async () => {
+        const response = await this.client.getFunctionUrl({
+          bindingName: this.bindingName,
+        })
+        return response.url
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+}

package/src/bindings/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Binding exports.
+ */
+
+export { Storage } from "./storage.js"
+export { Kv } from "./kv.js"
+export { Queue } from "./queue.js"
+export { Vault } from "./vault.js"
+export { Build } from "./build.js"
+export { ArtifactRegistry } from "./artifact-registry.js"
+export { FunctionBinding } from "./function.js"
+export { ServiceAccount } from "./service-account.js"

package/src/bindings/kv.ts

@@ -0,0 +1,240 @@
+/**
+ * KV binding implementation.
+ *
+ * Provides key-value storage operations with TTL support.
+ */
+
+import { type Channel, createClient } from "nice-grpc"
+import {
+  type KvServiceClient as GeneratedKvServiceClient,
+  KvServiceDefinition,
+} from "../generated/kv.js"
+import { wrapGrpcCall } from "../grpc-utils.js"
+import type { KvPutOptions, KvScanResult } from "../types.js"
+
+/**
+ * KV binding for key-value storage operations.
+ *
+ * @example
+ * ```typescript
+ * import { kv } from "@alienplatform/bindings"
+ *
+ * const cache = kv("my-cache")
+ *
+ * // Set a value
+ * await cache.set("user:123", { name: "John", email: "john@example.com" })
+ *
+ * // Get a value
+ * const user = await cache.getJson<User>("user:123")
+ *
+ * // Set with TTL (expires in 1 hour)
+ * await cache.set("session:abc", sessionData, { ttlMs: 60 * 60 * 1000 })
+ *
+ * // Delete
+ * await cache.delete("user:123")
+ *
+ * // Scan by prefix
+ * for await (const { key, value } of cache.scan("user:")) {
+ *   console.log(key, value)
+ * }
+ * ```
+ */
+export class Kv {
+  private readonly client: GeneratedKvServiceClient
+  private readonly bindingName: string
+
+  constructor(channel: Channel, bindingName: string) {
+    this.client = createClient(KvServiceDefinition, channel)
+    this.bindingName = bindingName
+  }
+
+  /**
+   * Get a value by key.
+   *
+   * @param key - Key to retrieve
+   * @returns Value as Uint8Array, or undefined if not found
+   */
+  async get(key: string): Promise<Uint8Array | undefined> {
+    return await wrapGrpcCall(
+      "KvService",
+      "Get",
+      async () => {
+        const response = await this.client.get({
+          bindingName: this.bindingName,
+          key,
+        })
+        return response.value
+      },
+      { bindingName: this.bindingName, key },
+    )
+  }
+
+  /**
+   * Get a value as a UTF-8 string.
+   *
+   * @param key - Key to retrieve
+   * @returns Value as string, or undefined if not found
+   */
+  async getText(key: string): Promise<string | undefined> {
+    const value = await this.get(key)
+    return value ? new TextDecoder().decode(value) : undefined
+  }
+
+  /**
+   * Get a value and parse as JSON.
+   *
+   * @param key - Key to retrieve
+   * @returns Parsed JSON value, or undefined if not found
+   */
+  async getJson<T = unknown>(key: string): Promise<T | undefined> {
+    const text = await this.getText(key)
+    return text ? (JSON.parse(text) as T) : undefined
+  }
+
+  /**
+   * Set a value.
+   *
+   * @param key - Key to store
+   * @param value - Value to store (string, Uint8Array, or object for JSON)
+   * @param options - Optional put options (TTL, ifNotExists)
+   * @returns True if stored, false if ifNotExists was true and key already exists
+   */
+  async set(
+    key: string,
+    value: string | Uint8Array | object,
+    options?: KvPutOptions,
+  ): Promise<boolean> {
+    let bytes: Uint8Array
+
+    if (typeof value === "string") {
+      bytes = new TextEncoder().encode(value)
+    } else if (value instanceof Uint8Array) {
+      bytes = value
+    } else {
+      bytes = new TextEncoder().encode(JSON.stringify(value))
+    }
+
+    return await wrapGrpcCall(
+      "KvService",
+      "Put",
+      async () => {
+        const response = await this.client.put({
+          bindingName: this.bindingName,
+          key,
+          value: bytes,
+          options: options
+            ? {
+                ttlSeconds: options.ttlMs ? Math.floor(options.ttlMs / 1000) : undefined,
+                ifNotExists: options.ifNotExists ?? false,
+              }
+            : undefined,
+        })
+        return response.success
+      },
+      { bindingName: this.bindingName, key },
+    )
+  }
+
+  /**
+   * Delete a key.
+   *
+   * @param key - Key to delete
+   */
+  async delete(key: string): Promise<void> {
+    await wrapGrpcCall(
+      "KvService",
+      "Delete",
+      async () => {
+        await this.client.delete({
+          bindingName: this.bindingName,
+          key,
+        })
+      },
+      { bindingName: this.bindingName, key },
+    )
+  }
+
+  /**
+   * Check if a key exists.
+   *
+   * @param key - Key to check
+   * @returns True if the key exists
+   */
+  async exists(key: string): Promise<boolean> {
+    return await wrapGrpcCall(
+      "KvService",
+      "Exists",
+      async () => {
+        const response = await this.client.exists({
+          bindingName: this.bindingName,
+          key,
+        })
+        return response.exists
+      },
+      { bindingName: this.bindingName, key },
+    )
+  }
+
+  /**
+   * Scan keys with a prefix.
+   *
+   * @param prefix - Prefix to scan for
+   * @param options - Optional scan options (limit)
+   * @returns Async iterable of key-value pairs
+   *
+   * @example
+   * ```typescript
+   * // Scan all users
+   * for await (const { key, value } of cache.scan("user:")) {
+   *   console.log(key, new TextDecoder().decode(value))
+   * }
+   * ```
+   */
+  async *scan(
+    prefix: string,
+    options?: { limit?: number },
+  ): AsyncIterable<{ key: string; value: Uint8Array }> {
+    let cursor: string | undefined
+
+    do {
+      const result = await this.scanPage(prefix, options?.limit, cursor)
+
+      for (const item of result.items) {
+        yield item
+      }
+
+      cursor = result.nextCursor
+    } while (cursor)
+  }
+
+  /**
+   * Scan a single page of results.
+   *
+   * @param prefix - Prefix to scan for
+   * @param limit - Maximum items to return
+   * @param cursor - Pagination cursor
+   * @returns Scan result with items and next cursor
+   */
+  async scanPage(prefix: string, limit?: number, cursor?: string): Promise<KvScanResult> {
+    return await wrapGrpcCall(
+      "KvService",
+      "ScanPrefix",
+      async () => {
+        const response = await this.client.scanPrefix({
+          bindingName: this.bindingName,
+          prefix,
+          limit,
+          cursor,
+        })
+        return {
+          items: response.items.map(item => ({
+            key: item.key,
+            value: item.value,
+          })),
+          nextCursor: response.nextCursor,
+        }
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+}