@rigkit/runtime-client 0.0.0-canary-20260518T014918-c5bc0c2

package/src/http.ts

@@ -0,0 +1,96 @@
+import { Effect } from "effect";
+import {
+  RuntimeApiVersionError,
+  RuntimeAuthError,
+  RuntimeConnectionError,
+  RuntimeHttpError,
+  type RuntimeClientError,
+  isRuntimeClientError,
+} from "./errors.ts";
+
+export const SUPPORTED_RUNTIME_API_VERSION = 1;
+
+export function runtimeStreamEffect(
+  baseUrl: string,
+  token: string,
+  path: string,
+  onEvent: (event: unknown) => Promise<void> | void,
+): Effect.Effect<void, RuntimeClientError> {
+  return Effect.tryPromise({
+    try: () => runtimeStreamUnsafe(baseUrl, token, path, onEvent),
+    catch: (cause) => toRuntimeTransportError(cause, { method: "GET", path }),
+  });
+}
+
+export function assertSupportedApiVersion(response: Response): void {
+  assertSupportedApiVersionHeader(response.headers.get("x-rigkit-api-version"));
+}
+
+export function assertSupportedApiVersionHeader(version: string | null | undefined): void {
+  if (version !== String(SUPPORTED_RUNTIME_API_VERSION)) {
+    throw new RuntimeApiVersionError({
+      version: version ?? null,
+      supportedVersion: SUPPORTED_RUNTIME_API_VERSION,
+    });
+  }
+}
+
+export function toRuntimeTransportError(
+  cause: unknown,
+  context: { method: string; path: string },
+): RuntimeClientError {
+  if (isRuntimeClientError(cause)) {
+    return cause;
+  }
+  return new RuntimeConnectionError({
+    method: context.method,
+    path: context.path,
+    cause,
+  });
+}
+
+async function runtimeStreamUnsafe(
+  baseUrl: string,
+  token: string,
+  path: string,
+  onEvent: (event: unknown) => Promise<void> | void,
+): Promise<void> {
+  const response = await fetch(`${baseUrl}${path}`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+  if (!response.ok || !response.body) {
+    throw runtimeHttpError("GET", path, response.status);
+  }
+  assertSupportedApiVersion(response);
+  await readSse(response.body, onEvent);
+}
+
+function runtimeHttpError(method: string, path: string, status: number, message?: string): RuntimeHttpError | RuntimeAuthError {
+  if (status === 401 || status === 403) {
+    return new RuntimeAuthError({ method, path, status, message });
+  }
+  return new RuntimeHttpError({ method, path, status, message });
+}
+
+async function readSse(body: ReadableStream<Uint8Array>, onEvent: (event: unknown) => Promise<void> | void): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    for (;;) {
+      const index = buffer.indexOf("\n\n");
+      if (index < 0) break;
+      const raw = buffer.slice(0, index);
+      buffer = buffer.slice(index + 2);
+      const data = raw.split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n");
+      if (data) await onEvent(JSON.parse(data));
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+export {
+  defaultRigkitHome,
+  getOrStartRuntime,
+  connectRemoteRuntime,
+  projectIdFor,
+  runtimeFingerprintFor,
+  runtimePaths,
+  getOrStartRuntimeEffect,
+  type GetOrStartRuntimeOptions,
+  type RemoteRuntimeOptions,
+  type RuntimeClient,
+  type RuntimePaths,
+  type RuntimeProjectOptions,
+} from "./manager.ts";
+export {
+  SUPPORTED_RUNTIME_API_VERSION,
+  assertSupportedApiVersion,
+  assertSupportedApiVersionHeader,
+} from "./http.ts";
+export {
+  createRuntimeHttpClient,
+  runtimeHttpClientEffect,
+  type RuntimeHttpClient,
+  type RuntimeHttpClientOptions,
+} from "./client.ts";
+export {
+  RuntimeControlHealthEffectSchema,
+  RuntimeControlHostResponseEffectSchema,
+  RuntimeControlMetadataEffectSchema,
+  RuntimeControlOkResponseEffectSchema,
+  RuntimeControlOperationCliEffectSchema,
+  RuntimeControlOperationEffectSchema,
+  RuntimeControlOperationsManifestEffectSchema,
+  RuntimeControlCacheEntryEffectSchema,
+  RuntimeControlCacheResponseEffectSchema,
+  RuntimeControlCacheClearRequestEffectSchema,
+  RuntimeControlCacheClearResponseEffectSchema,
+  RuntimeControlProjectInfoEffectSchema,
+  RuntimeControlRunEffectSchema,
+  RuntimeControlRunOperationRequestEffectSchema,
+  RuntimeControlRunStartedEffectSchema,
+  RuntimeControlRunsResponseEffectSchema,
+  RuntimeControlSnapshotsResponseEffectSchema,
+  RuntimeControlWorkflowSummaryEffectSchema,
+  RuntimeControlWorkflowsResponseEffectSchema,
+  RuntimeControlWorkspaceEffectSchema,
+  RuntimeControlWorkspacesResponseEffectSchema,
+  runtimeControlApi,
+  type RuntimeControlHealth,
+  type RuntimeControlHostResponse,
+  type RuntimeControlMetadata,
+  type RuntimeControlOkResponse,
+  type RuntimeControlOperation,
+  type RuntimeControlOperationCli,
+  type RuntimeControlOperationsManifest,
+  type RuntimeControlCacheEntry,
+  type RuntimeControlCacheResponse,
+  type RuntimeControlCacheClearRequest,
+  type RuntimeControlCacheClearResponse,
+  type RuntimeControlProjectInfo,
+  type RuntimeControlRun,
+  type RuntimeControlRunOperationRequest,
+  type RuntimeControlRunStarted,
+  type RuntimeControlRunsResponse,
+  type RuntimeControlSnapshotsResponse,
+  type RuntimeControlWorkflowSummary,
+  type RuntimeControlWorkflowsResponse,
+  type RuntimeControlWorkspace,
+  type RuntimeControlWorkspacesResponse,
+} from "./api.ts";
+export {
+  runtimeSessionEffect,
+  type RuntimeSessionConnection,
+  type RuntimeSessionHandlers,
+  type RuntimeSessionHello,
+} from "./session.ts";
+export {
+  RuntimeApiVersionError,
+  RuntimeAuthError,
+  RuntimeConnectionError,
+  RuntimeHttpError,
+  RuntimeProtocolError,
+  RuntimeSessionError,
+  RuntimeStartupError,
+  isRuntimeClientError,
+  type RuntimeClientError,
+  type RuntimeStartupErrorReason,
+} from "./errors.ts";
+export { RIGKIT_RUNTIME_CLIENT_VERSION } from "./version.ts";
+export {
+  RuntimeClientSchemaError,
+  RuntimeErrorResponseEffectSchema,
+  RuntimeHandleSchema,
+  RuntimeHandleEffectSchema,
+  RuntimeHealthSchema,
+  RuntimeHealthEffectSchema,
+  RuntimeMetadataSchema,
+  RuntimeMetadataEffectSchema,
+  RuntimeReadySchema,
+  RuntimeReadyEffectSchema,
+  type RuntimeHandle,
+  type RuntimeHealth,
+  type RuntimeMetadata,
+  type RuntimeReady,
+} from "./schemas.ts";

package/src/manager.test.ts

@@ -0,0 +1,347 @@
+import { describe, expect, test } from "bun:test";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  connectRemoteRuntime,
+  getOrStartRuntime,
+  projectIdFor,
+  runtimeFingerprintFor,
+  runtimePaths,
+  SUPPORTED_RUNTIME_API_VERSION,
+} from "./manager.ts";
+import {
+  RuntimeApiVersionError,
+  RuntimeAuthError,
+  RuntimeProtocolError,
+  RuntimeStartupError,
+} from "./errors.ts";
+
+describe("runtime manager", () => {
+  test("computes stable ids from project and config paths", () => {
+    const first = projectIdFor({
+      projectDir: "/tmp/project",
+      configPath: "/tmp/project/rig.config.ts",
+    });
+    const second = projectIdFor({
+      projectDir: "/tmp/project",
+      configPath: "/tmp/project/rig.config.ts",
+    });
+    const differentConfig = projectIdFor({
+      projectDir: "/tmp/project",
+      configPath: "/tmp/project/other.config.ts",
+    });
+    const differentSource = projectIdFor({
+      projectDir: "/tmp/project",
+      configPath: "/tmp/project/rig.config.ts",
+      source: { kind: "github", commitSha: "abc" },
+    });
+
+    expect(first).toBe(second);
+    expect(first.startsWith("sha256-")).toBe(true);
+    expect(differentConfig).not.toBe(first);
+    expect(differentSource).not.toBe(first);
+  });
+
+  test("keeps project ids stable while config fingerprints change", () => {
+    const root = mkdtempSync(join(tmpdir(), "rigkit-runtime-client-id-"));
+    try {
+      const projectDir = join(root, "project");
+      const configPath = join(projectDir, "rig.config.ts");
+      mkdirSync(projectDir, { recursive: true });
+      writeFileSync(configPath, "export default { name: 'one' }\n");
+
+      const first = projectIdFor({ projectDir, configPath });
+      const second = projectIdFor({ projectDir, configPath });
+      const firstFingerprint = runtimeFingerprintFor({ projectDir, configPath });
+      writeFileSync(configPath, "export default { name: 'two' }\n");
+      const changed = projectIdFor({ projectDir, configPath });
+      const changedFingerprint = runtimeFingerprintFor({ projectDir, configPath });
+
+      expect(second).toBe(first);
+      expect(changed).toBe(first);
+      expect(changedFingerprint).not.toBe(firstFingerprint);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("restarts local runtimes when the runtime fingerprint changes", async () => {
+    const root = mkdtempSync(join(tmpdir(), "rigkit-runtime-client-restart-"));
+    let first: Awaited<ReturnType<typeof getOrStartRuntime>> | undefined;
+    let second: Awaited<ReturnType<typeof getOrStartRuntime>> | undefined;
+
+    try {
+      const projectDir = join(root, "project");
+      const rigkitHome = join(root, "home");
+      const configPath = join(projectDir, "rig.config.ts");
+      mkdirSync(projectDir, { recursive: true });
+      writeFileSync(configPath, "export default { name: 'one' }\n");
+      writeFakeRuntimeBin(projectDir);
+
+      first = await getOrStartRuntime({
+        projectDir,
+        configPath,
+        rigkitHome,
+        idleMs: 60_000,
+      });
+      const firstHealth = await first.control.health();
+
+      writeFileSync(configPath, "export default { name: 'two' }\n");
+      second = await getOrStartRuntime({
+        projectDir,
+        configPath,
+        rigkitHome,
+        idleMs: 60_000,
+      });
+      const secondHealth = await second.control.health();
+
+      expect(second.handle.projectId).toBe(first.handle.projectId);
+      expect(second.paths.handlePath).toBe(first.paths.handlePath);
+      expect(second.handle.runtimeFingerprint).not.toBe(first.handle.runtimeFingerprint);
+      expect(second.handle.pid).not.toBe(first.handle.pid);
+      expect(secondHealth.runtimeFingerprint).toBe(second.handle.runtimeFingerprint);
+      expect(firstHealth.projectId).toBe(secondHealth.projectId);
+    } finally {
+      await second?.control.shutdown().catch(() => {});
+      await first?.control.shutdown().catch(() => {});
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("derives handle, token, and lock paths from rigkit home", () => {
+    const paths = runtimePaths("sha256-test", "/tmp/rigkit-home");
+
+    expect(paths.root).toBe(join("/tmp/rigkit-home", "runtimes"));
+    expect(paths.handlePath).toBe(join("/tmp/rigkit-home", "runtimes", "sha256-test.json"));
+    expect(paths.tokenPath).toBe(join("/tmp/rigkit-home", "runtimes", "sha256-test.token"));
+    expect(paths.lockPath).toBe(join("/tmp/rigkit-home", "runtimes", "sha256-test.lock"));
+  });
+
+  test("remote run event clients reject unsupported runtime API versions", async () => {
+    let path = "";
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: (request) => {
+        path = new URL(request.url).pathname;
+        return new Response("", {
+          headers: { "x-rigkit-api-version": String(SUPPORTED_RUNTIME_API_VERSION + 1) },
+        });
+      },
+    });
+
+    try {
+      const runtime = connectRemoteRuntime({
+        url: `http://127.0.0.1:${server.port}`,
+        token: "test-token",
+      });
+
+      await expect(runtime.runEvents("run/id", () => {})).rejects.toThrow("Unsupported Rigkit runtime API version");
+      await expect(runtime.runEvents("run/id", () => {})).rejects.toBeInstanceOf(RuntimeApiVersionError);
+      expect(path).toBe("/runs/run%2Fid/events");
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("remote control clients use the typed runtime API", async () => {
+    const metadata = {
+      apiVersion: SUPPORTED_RUNTIME_API_VERSION,
+      engineVersion: "engine-test",
+      runtimeVersion: "runtime-test",
+      protocolHash: "sha256:test",
+    };
+    let authorization = "";
+    let path = "";
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: (request) => {
+        authorization = request.headers.get("authorization") ?? "";
+        path = new URL(request.url).pathname;
+        return Response.json(metadata, {
+          headers: { "x-rigkit-api-version": String(SUPPORTED_RUNTIME_API_VERSION) },
+        });
+      },
+    });
+
+    try {
+      const runtime = connectRemoteRuntime({
+        url: `http://127.0.0.1:${server.port}`,
+        token: "test-token",
+      });
+
+      await expect(runtime.control.runtime()).resolves.toEqual(metadata);
+      expect(path).toBe("/runtime");
+      expect(authorization).toBe("Bearer test-token");
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("remote control clients reject unsupported runtime API versions", async () => {
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: () => Response.json(
+        {
+          apiVersion: SUPPORTED_RUNTIME_API_VERSION + 1,
+          engineVersion: "engine-test",
+          runtimeVersion: "runtime-test",
+          protocolHash: "sha256:test",
+        },
+        { headers: { "x-rigkit-api-version": String(SUPPORTED_RUNTIME_API_VERSION + 1) } },
+      ),
+    });
+
+    try {
+      const runtime = connectRemoteRuntime({
+        url: `http://127.0.0.1:${server.port}`,
+        token: "test-token",
+      });
+
+      await expect(runtime.control.runtime()).rejects.toThrow("Unsupported Rigkit runtime API version");
+      await expect(runtime.control.runtime()).rejects.toBeInstanceOf(RuntimeApiVersionError);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("remote clients expose typed auth failures", async () => {
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: () => Response.json(
+        { error: { message: "bad token" } },
+        {
+          status: 401,
+          headers: { "x-rigkit-api-version": String(SUPPORTED_RUNTIME_API_VERSION) },
+        },
+      ),
+    });
+
+    try {
+      const runtime = connectRemoteRuntime({
+        url: `http://127.0.0.1:${server.port}`,
+        token: "test-token",
+      });
+
+      await expect(runtime.control.runtime()).rejects.toThrow("bad token");
+      await expect(runtime.control.runtime()).rejects.toBeInstanceOf(RuntimeAuthError);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("remote clients expose typed protocol failures", async () => {
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: () => new Response("{", {
+        headers: { "x-rigkit-api-version": String(SUPPORTED_RUNTIME_API_VERSION) },
+      }),
+    });
+
+    try {
+      const runtime = connectRemoteRuntime({
+        url: `http://127.0.0.1:${server.port}`,
+        token: "test-token",
+      });
+
+      await expect(runtime.control.runtime()).rejects.toBeInstanceOf(RuntimeProtocolError);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("local manager exposes typed missing runtime failures", async () => {
+    const root = mkdtempSync(join(tmpdir(), "rigkit-runtime-client-"));
+    try {
+      const projectDir = join(root, "project");
+      const rigkitHome = join(root, "home");
+
+      await expect(getOrStartRuntime({
+        projectDir,
+        configPath: join(projectDir, "rig.config.ts"),
+        rigkitHome,
+      })).rejects.toBeInstanceOf(RuntimeStartupError);
+      await expect(getOrStartRuntime({
+        projectDir,
+        configPath: join(projectDir, "rig.config.ts"),
+        rigkitHome,
+      })).rejects.toMatchObject({ reason: "missing-runtime" });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+function writeFakeRuntimeBin(projectDir: string): void {
+  const binDir = join(projectDir, "node_modules", ".bin");
+  mkdirSync(binDir, { recursive: true });
+  const binPath = join(binDir, process.platform === "win32" ? "rigkit-project-runtime.cmd" : "rigkit-project-runtime");
+  writeFileSync(
+    binPath,
+    `#!/usr/bin/env bun
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const options = {};
+for (let i = 1; i < args.length; i += 2) {
+  options[args[i].replace(/^--/, "")] = args[i + 1];
+}
+
+const token = readFileSync(options.token, "utf8").trim();
+let server;
+server = Bun.serve({
+  hostname: "127.0.0.1",
+  port: 0,
+  fetch(request) {
+    const url = new URL(request.url);
+    if (request.headers.get("authorization") !== \`Bearer \${token}\`) {
+      return Response.json({ error: { message: "Unauthorized" } }, { status: 401 });
+    }
+    if (url.pathname === "/health") {
+      return Response.json({
+        ok: true,
+        projectId: options["project-id"],
+        runtimeFingerprint: options["runtime-fingerprint"],
+        projectDir: resolve(options["project-dir"]),
+        configPath: resolve(options.config),
+        statePath: options.state ? resolve(options.state) : undefined,
+        engineVersion: "engine-test",
+        runtimeVersion: "runtime-test",
+        expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      }, { headers: { "x-rigkit-api-version": "${SUPPORTED_RUNTIME_API_VERSION}" } });
+    }
+    if (url.pathname === "/shutdown") {
+      setTimeout(() => {
+        server.stop(true);
+        process.exit(0);
+      }, 0);
+      return Response.json({ ok: true }, { headers: { "x-rigkit-api-version": "${SUPPORTED_RUNTIME_API_VERSION}" } });
+    }
+    return Response.json({ error: { message: "Not found" } }, { status: 404 });
+  },
+});
+
+const handle = {
+  projectId: options["project-id"],
+  runtimeFingerprint: options["runtime-fingerprint"],
+  projectDir: resolve(options["project-dir"]),
+  configPath: resolve(options.config),
+  statePath: options.state ? resolve(options.state) : undefined,
+  pid: process.pid,
+  url: \`http://127.0.0.1:\${server.port}\`,
+  tokenPath: resolve(options.token),
+};
+mkdirSync(dirname(options.handle), { recursive: true });
+writeFileSync(options.handle, JSON.stringify(handle));
+console.log(JSON.stringify({ type: "ready", url: handle.url, token }));
+await new Promise(() => {});
+`,
+  );
+  chmodSync(binPath, 0o755);
+}