@yolk-sdk/sandbox 0.1.0-canary.18

package/src/vercel/client.ts

@@ -0,0 +1,223 @@
+import { Context, Layer } from 'effect'
+import { APIError, Sandbox as VercelSdkSandbox, type Command, type CommandFinished, type NetworkPolicy } from '@vercel/sandbox'
+import type { SandboxInitialSource, SandboxResources, SandboxSnapshotRetention } from '../model.ts'
+
+export type VercelSandboxRuntime = 'node22' | 'node24' | 'node26' | 'python3.13'
+export type VercelNetworkPolicy = NetworkPolicy
+
+export type VercelCommandOutput = {
+  readonly stdout: string
+  readonly stderr: string
+}
+
+export type VercelCommandSignal = 'SIGTERM' | 'SIGKILL'
+
+export type VercelFinishedCommand = {
+  readonly id: string
+  readonly exitCode: number
+  readonly output: () => Promise<VercelCommandOutput>
+}
+
+export type VercelDetachedCommand = {
+  readonly id: string
+  readonly exitCode: number | null
+  readonly wait: () => Promise<VercelFinishedCommand>
+  readonly kill: (signal: VercelCommandSignal) => Promise<void>
+  readonly output: () => Promise<VercelCommandOutput>
+}
+
+export type VercelSandboxFile = {
+  readonly path: string
+  readonly content: string
+  readonly mode?: number
+}
+
+export type VercelRunCommandInput = {
+  readonly cmd: string
+  readonly args?: ReadonlyArray<string>
+  readonly cwd?: string
+}
+
+export type VercelSandboxCreateInput = {
+  readonly name: string
+  readonly source: SandboxInitialSource
+  readonly ports: ReadonlyArray<number>
+  readonly timeoutMs: number
+  readonly resources: SandboxResources
+  readonly runtime: VercelSandboxRuntime
+  readonly env?: Readonly<Record<string, string>>
+  readonly persistent: boolean
+  readonly snapshotExpirationMs?: number
+  readonly keepLastSnapshots?: SandboxSnapshotRetention
+  readonly networkPolicy?: VercelNetworkPolicy
+}
+
+export type VercelSandboxGetInput = {
+  readonly name: string
+}
+
+export type VercelSandboxHandle = {
+  readonly name: string
+  readonly writeFiles: (files: ReadonlyArray<VercelSandboxFile>) => Promise<void>
+  readonly runDetachedCommand: (input: VercelRunCommandInput) => Promise<VercelDetachedCommand>
+  readonly getCommand: (id: string) => Promise<VercelDetachedCommand>
+  readonly extendTimeout: (durationMs: number) => Promise<void>
+  readonly delete: () => Promise<void>
+  readonly domain: (port: number) => string
+}
+
+export type VercelSandboxClientApi = {
+  readonly get: (input: VercelSandboxGetInput) => Promise<VercelSandboxHandle | null>
+  readonly create: (input: VercelSandboxCreateInput) => Promise<VercelSandboxHandle>
+}
+
+export class VercelSandboxClient extends Context.Service<VercelSandboxClient, VercelSandboxClientApi>()(
+  '@yolk-sdk/sandbox/vercel/VercelSandboxClient'
+) {}
+
+export const isVercelMissingSandboxError = (error: unknown) =>
+  error instanceof APIError && (error.response.status === 404 || error.response.status === 410)
+
+const commandOutput = (command: Command | CommandFinished): Promise<VercelCommandOutput> =>
+  Promise.all([command.stdout(), command.stderr()]).then(([stdout, stderr]) => ({ stdout, stderr }))
+
+const toFinishedCommand = (command: CommandFinished): VercelFinishedCommand => ({
+  id: command.cmdId,
+  exitCode: command.exitCode,
+  output: () => commandOutput(command)
+})
+
+const toDetachedCommand = (command: Command): VercelDetachedCommand => ({
+  id: command.cmdId,
+  exitCode: command.exitCode,
+  wait: () => command.wait().then(toFinishedCommand),
+  kill: signal => command.kill(signal),
+  output: () => commandOutput(command)
+})
+
+const toHandle = (sandbox: VercelSdkSandbox): VercelSandboxHandle => ({
+  name: sandbox.name,
+  writeFiles: files =>
+    sandbox.writeFiles(files.map(file => ({
+      path: file.path,
+      content: file.content,
+      ...(file.mode === undefined ? {} : { mode: file.mode })
+    }))),
+  runDetachedCommand: input =>
+    sandbox.runCommand({
+      cmd: input.cmd,
+      args: input.args === undefined ? [] : [...input.args],
+      ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+      detached: true
+    }).then(toDetachedCommand),
+  getCommand: id => sandbox.getCommand(id).then(toDetachedCommand),
+  extendTimeout: durationMs => sandbox.extendTimeout(durationMs).then(() => undefined),
+  delete: () => sandbox.delete().then(() => undefined),
+  domain: port => sandbox.domain(port)
+})
+
+const envObject = (env?: Readonly<Record<string, string>>) =>
+  env === undefined ? undefined : Object.fromEntries(Object.entries(env))
+
+const retentionObject = (retention?: SandboxSnapshotRetention) =>
+  retention === undefined
+    ? undefined
+    : {
+        count: retention.count,
+        ...(retention.expirationMs === undefined ? {} : { expiration: retention.expirationMs }),
+        ...(retention.deleteEvicted === undefined ? {} : { deleteEvicted: retention.deleteEvicted })
+      }
+
+type AnonymousGitSource = {
+  readonly type: 'git'
+  readonly url: string
+  readonly depth?: number
+  readonly revision?: string
+}
+
+type BasicAuthGitSource = AnonymousGitSource & {
+  readonly username: string
+  readonly password: string
+}
+
+const commonCreateOptions = (input: VercelSandboxCreateInput) => ({
+  name: input.name,
+  ports: [...input.ports],
+  timeout: input.timeoutMs,
+  resources: { vcpus: input.resources.vcpus },
+  env: envObject(input.env),
+  persistent: input.persistent,
+  networkPolicy: input.networkPolicy,
+  snapshotExpiration: input.snapshotExpirationMs,
+  keepLastSnapshots: retentionObject(input.keepLastSnapshots)
+})
+
+const gitSource = (
+  source: Extract<SandboxInitialSource, { readonly _tag: 'Git' }>
+): AnonymousGitSource | BasicAuthGitSource => {
+  if ((source.username === undefined) !== (source.password === undefined)) {
+    throw new Error('Vercel git source requires both username and password when using basic auth')
+  }
+
+  if (source.username !== undefined && source.password !== undefined) {
+    return {
+      type: 'git',
+      url: source.url,
+      username: source.username,
+      password: source.password,
+      ...(source.depth === undefined ? {} : { depth: source.depth }),
+      ...(source.revision === undefined ? {} : { revision: source.revision })
+    }
+  }
+
+  return {
+    type: 'git',
+    url: source.url,
+    ...(source.depth === undefined ? {} : { depth: source.depth }),
+    ...(source.revision === undefined ? {} : { revision: source.revision })
+  }
+}
+
+const createSandbox = (input: VercelSandboxCreateInput) => {
+  const common = commonCreateOptions(input)
+
+  switch (input.source._tag) {
+    case 'Empty':
+      return VercelSdkSandbox.create({
+        ...common,
+        runtime: input.runtime
+      })
+    case 'Snapshot':
+      return VercelSdkSandbox.create({
+        ...common,
+        source: { type: 'snapshot', snapshotId: input.source.snapshotId }
+      })
+    case 'Git':
+      return VercelSdkSandbox.create({
+        ...common,
+        runtime: input.runtime,
+        source: gitSource(input.source)
+      })
+    case 'Tarball':
+      return VercelSdkSandbox.create({
+        ...common,
+        runtime: input.runtime,
+        source: { type: 'tarball', url: input.source.url }
+      })
+  }
+}
+
+export const VercelSandboxClientLive = Layer.succeed(
+  VercelSandboxClient,
+  VercelSandboxClient.of({
+    get: input =>
+      VercelSdkSandbox.get({ name: input.name }).then(toHandle).catch(error => {
+        if (isVercelMissingSandboxError(error)) {
+          return null
+        }
+
+        throw error
+      }),
+    create: input => createSandbox(input).then(toHandle)
+  })
+)

package/src/vercel/index.ts

@@ -0,0 +1,24 @@
+export {
+  isVercelMissingSandboxError,
+  VercelSandboxClient,
+  VercelSandboxClientLive
+} from './client.ts'
+export {
+  makeVercelSandboxLayer,
+  makeVercelSandboxLayerWithClient
+} from './layer.ts'
+export type {
+  VercelCommandOutput,
+  VercelCommandSignal,
+  VercelDetachedCommand,
+  VercelFinishedCommand,
+  VercelNetworkPolicy,
+  VercelRunCommandInput,
+  VercelSandboxClientApi,
+  VercelSandboxCreateInput,
+  VercelSandboxFile,
+  VercelSandboxGetInput,
+  VercelSandboxHandle,
+  VercelSandboxRuntime
+} from './client.ts'
+export type { VercelSandboxLayerConfig } from './layer.ts'

package/src/vercel/layer.ts

@@ -0,0 +1,396 @@
+import { Array as Arr, Clock, Duration, Effect, Layer, Option, Ref, Semaphore } from 'effect'
+import {
+  absoluteSandboxCwd,
+  backgroundSandboxProbeMs,
+  defaultSandboxPorts,
+  defaultSandboxWorkspaceRoot,
+  initialSandboxState,
+  normalizeWorkspaceCwd,
+  sandboxCommandTimeoutMs,
+  sandboxLifecycleOrDefault,
+  sandboxSourceOrDefault,
+  sandboxStateDecision,
+  sandboxTimeoutExtendDeltaMs,
+  touchSandboxState,
+  validateSandboxCommand
+} from '../lifecycle.ts'
+import { makeVercelSandboxName } from '../name.ts'
+import {
+  SandboxCommandResult,
+  type SandboxCommandInput,
+  SandboxPreviewUrl,
+  SandboxResources,
+  type SandboxInitialSource,
+  type SandboxLifecycle,
+  type SandboxState
+} from '../model.ts'
+import { Sandbox } from '../service.ts'
+import { SandboxStateStore } from '../state-store.ts'
+import { SandboxProviderError, unknownToMessage } from '../errors.ts'
+import type { SandboxError } from '../errors.ts'
+import {
+  VercelSandboxClient,
+  VercelSandboxClientLive,
+  type VercelDetachedCommand,
+  type VercelNetworkPolicy,
+  type VercelSandboxHandle,
+  type VercelSandboxRuntime
+} from './client.ts'
+
+export type VercelSandboxLayerConfig = {
+  readonly sandboxSessionId: string
+  readonly lifecycle?: SandboxLifecycle
+  readonly source?: SandboxInitialSource
+  readonly env?: Readonly<Record<string, string>>
+  readonly ports?: ReadonlyArray<number>
+  readonly resources?: SandboxResources
+  readonly runtime?: VercelSandboxRuntime
+  readonly networkPolicy?: VercelNetworkPolicy
+  readonly workspaceRoot?: string
+}
+
+type ActiveSandbox = {
+  readonly handle: VercelSandboxHandle
+  readonly state: SandboxState
+  readonly workspaceReset: boolean
+}
+
+type CommandRunOutput = {
+  readonly exitCode: number | null
+  readonly stdout: string
+  readonly stderr: string
+  readonly timedOut: boolean
+  readonly backgroundId?: string
+}
+
+const defaultVercelResources = SandboxResources.make({ vcpus: 2 })
+const defaultVercelRuntime: VercelSandboxRuntime = 'node24'
+
+const providerError = (operation: string, error: unknown) =>
+  new SandboxProviderError({
+    provider: 'vercel',
+    operation,
+    message: `Vercel Sandbox ${operation} failed: ${unknownToMessage(error)}`,
+    underlying: error
+  })
+
+const tryProvider = <A>(operation: string, body: () => Promise<A>) =>
+  Effect.tryPromise({
+    try: body,
+    catch: error => providerError(operation, error)
+  })
+
+const lifecycleTimeoutMs = (lifecycle: SandboxLifecycle) => {
+  switch (lifecycle._tag) {
+    case 'Disposable':
+      return Math.min(lifecycle.idleTtlMs, lifecycle.maxLifetimeMs)
+    case 'Persistent':
+      return lifecycle.idleTtlMs
+  }
+}
+
+const persistentFlag = (lifecycle: SandboxLifecycle) => lifecycle._tag === 'Persistent'
+
+const snapshotExpirationMs = (lifecycle: SandboxLifecycle) =>
+  lifecycle._tag === 'Persistent' ? lifecycle.snapshotExpirationMs : undefined
+
+const keepLastSnapshots = (lifecycle: SandboxLifecycle) =>
+  lifecycle._tag === 'Persistent' ? lifecycle.keepLastSnapshots : undefined
+
+const previewUrls = (handle: VercelSandboxHandle, ports: ReadonlyArray<number>) =>
+  Effect.forEach(ports, port =>
+    Effect.try({
+      try: () => handle.domain(port),
+      catch: error => error
+    }).pipe(
+      Effect.match({
+        onFailure: () => Option.none<SandboxPreviewUrl>(),
+        onSuccess: url => Option.some(SandboxPreviewUrl.make({ port, url }))
+      })
+    )
+  ).pipe(Effect.map(Arr.getSomes))
+
+const commandOutputOrEmpty = (command: VercelDetachedCommand) =>
+  tryProvider('command.output', command.output).pipe(
+    Effect.catchTag('SandboxProviderError', error =>
+      Effect.succeed({
+        stdout: '',
+        stderr: error.message
+      })
+    )
+  )
+
+const finishedCommandOutputOrEmpty = (command: {
+  readonly output: () => Promise<{ readonly stdout: string; readonly stderr: string }>
+}) =>
+  tryProvider('command.output', command.output).pipe(
+    Effect.catchTag('SandboxProviderError', error =>
+      Effect.succeed({
+        stdout: '',
+        stderr: error.message
+      })
+    )
+  )
+
+const waitForegroundCommand = (
+  command: VercelDetachedCommand,
+  timeoutMs: number
+): Effect.Effect<CommandRunOutput, SandboxProviderError> =>
+  tryProvider('command.wait', command.wait).pipe(
+    Effect.flatMap(finished =>
+      finishedCommandOutputOrEmpty(finished).pipe(
+        Effect.map(output => ({
+          exitCode: finished.exitCode,
+          stdout: output.stdout,
+          stderr: output.stderr,
+          timedOut: false
+        }))
+      )
+    ),
+    Effect.timeoutOrElse({
+      duration: Duration.millis(timeoutMs),
+      orElse: () =>
+        Effect.gen(function* () {
+          yield* tryProvider('command.kill', () => command.kill('SIGKILL')).pipe(
+            Effect.catchTag('SandboxProviderError', () => Effect.void)
+          )
+          const output = yield* commandOutputOrEmpty(command)
+
+          return {
+            exitCode: null,
+            stdout: output.stdout,
+            stderr: output.stderr,
+            timedOut: true
+          }
+        })
+    })
+  )
+
+const probeBackgroundCommand = (
+  handle: VercelSandboxHandle,
+  command: VercelDetachedCommand
+): Effect.Effect<CommandRunOutput, SandboxProviderError> =>
+  Effect.sleep(Duration.millis(backgroundSandboxProbeMs)).pipe(
+    Effect.flatMap(() => tryProvider('command.get', () => handle.getCommand(command.id))),
+    Effect.flatMap(current => {
+      if (current.exitCode === null) {
+        return Effect.succeed({
+          exitCode: null,
+          stdout: '',
+          stderr: '',
+          timedOut: false,
+          backgroundId: command.id
+        })
+      }
+
+      return commandOutputOrEmpty(current).pipe(
+        Effect.map(output => ({
+          exitCode: current.exitCode,
+          stdout: output.stdout,
+          stderr: output.stderr,
+          timedOut: false
+        }))
+      )
+    })
+  )
+
+const createCommandFiles = (input: {
+  readonly commandId: string
+  readonly workspaceRoot: string
+  readonly command: string
+  readonly stdin?: string
+}) => {
+  const commandDir = `${input.workspaceRoot}/.yolk/commands/${input.commandId}`
+  const commandPath = `${commandDir}/command.sh`
+  const stdinPath = `${commandDir}/stdin.txt`
+  const wrapperPath = `${commandDir}/wrapper.sh`
+
+  return {
+    wrapperPath,
+    files: [
+      {
+        path: commandPath,
+        content: `#!/usr/bin/env bash\n${input.command}\n`,
+        mode: 0o755
+      },
+      {
+        path: stdinPath,
+        content: input.stdin ?? ''
+      },
+      {
+        path: wrapperPath,
+        content: `#!/usr/bin/env bash\nbash ${JSON.stringify(commandPath)} < ${JSON.stringify(stdinPath)}\n`,
+        mode: 0o755
+      }
+    ]
+  }
+}
+
+export const makeVercelSandboxLayerWithClient = (config: VercelSandboxLayerConfig) =>
+  Layer.effect(
+    Sandbox,
+    Effect.gen(function* () {
+      const store = yield* SandboxStateStore
+      const client = yield* VercelSandboxClient
+      const semaphore = yield* Semaphore.make(1)
+      const commandCounter = yield* Ref.make(0)
+      const lifecycle = sandboxLifecycleOrDefault(config.lifecycle)
+      const source = sandboxSourceOrDefault(config.source)
+      const ports = config.ports ?? defaultSandboxPorts
+      const resources = config.resources ?? defaultVercelResources
+      const runtime = config.runtime ?? defaultVercelRuntime
+      const workspaceRoot = config.workspaceRoot ?? defaultSandboxWorkspaceRoot
+      const name = makeVercelSandboxName(config.sandboxSessionId)
+
+      const deleteNamedSandbox = (sandboxName: string) =>
+        tryProvider('get', () => client.get({ name: sandboxName })).pipe(
+          Effect.flatMap(handle =>
+            handle === null
+              ? Effect.void
+              : tryProvider('delete', () => handle.delete())
+          )
+        )
+
+      const createSandbox = (input: { readonly nowMs: number; readonly workspaceReset: boolean }) =>
+        Effect.gen(function* () {
+          const handle = yield* tryProvider('create', () =>
+            client.create({
+              name,
+              source,
+              ports,
+              timeoutMs: lifecycleTimeoutMs(lifecycle),
+              resources,
+              runtime,
+              env: config.env,
+              persistent: persistentFlag(lifecycle),
+              snapshotExpirationMs: snapshotExpirationMs(lifecycle),
+              keepLastSnapshots: keepLastSnapshots(lifecycle),
+              networkPolicy: config.networkPolicy
+            })
+          )
+          const state = initialSandboxState({ name, nowMs: input.nowMs, lifecycle })
+          yield* store.save({ sandboxSessionId: config.sandboxSessionId, state })
+
+          return { handle, state, workspaceReset: input.workspaceReset }
+        })
+
+      const touchExistingSandbox = (input: {
+        readonly handle: VercelSandboxHandle
+        readonly state: SandboxState
+        readonly nowMs: number
+        readonly workspaceReset: boolean
+      }) =>
+        Effect.gen(function* () {
+          const touched = touchSandboxState({
+            state: input.state,
+            nowMs: input.nowMs,
+            lifecycle
+          })
+          const deltaMs = sandboxTimeoutExtendDeltaMs({ before: input.state, after: touched })
+
+          if (deltaMs > 0) {
+            yield* tryProvider('extendTimeout', () => input.handle.extendTimeout(deltaMs))
+          }
+
+          yield* store.save({ sandboxSessionId: config.sandboxSessionId, state: touched })
+
+          return {
+            handle: input.handle,
+            state: touched,
+            workspaceReset: input.workspaceReset
+          }
+        })
+
+      const ensureSandbox = (nowMs: number): Effect.Effect<ActiveSandbox, SandboxError> =>
+        Effect.gen(function* () {
+          const loaded = yield* store.load(config.sandboxSessionId)
+          const decision = sandboxStateDecision({ state: loaded, name, nowMs })
+
+          if (decision._tag === 'Create') {
+            if (Option.isSome(loaded) && decision.workspaceReset) {
+              yield* deleteNamedSandbox(loaded.value.name)
+              yield* store.clear(config.sandboxSessionId)
+            }
+
+            return yield* createSandbox({ nowMs, workspaceReset: decision.workspaceReset })
+          }
+
+          const handle = yield* tryProvider('get', () => client.get({ name }))
+
+          if (handle === null) {
+            yield* store.clear(config.sandboxSessionId)
+            return yield* createSandbox({ nowMs, workspaceReset: true })
+          }
+
+          return yield* touchExistingSandbox({
+            handle,
+            state: decision.state,
+            nowMs,
+            workspaceReset: false
+          })
+        })
+
+      const nextCommandId = Ref.updateAndGet(commandCounter, value => value + 1).pipe(
+        Effect.map(value => `command-${value}`)
+      )
+
+      const runUnlocked = (input: SandboxCommandInput) =>
+        Effect.gen(function* () {
+          yield* validateSandboxCommand(input.command)
+          const normalizedCwd = yield* normalizeWorkspaceCwd(input.cwd)
+          const timeoutMs = sandboxCommandTimeoutMs(input.timeoutMs)
+          const nowMs = yield* Clock.currentTimeMillis
+          const active = yield* ensureSandbox(nowMs)
+          const id = yield* nextCommandId
+          const commandFiles = createCommandFiles({
+            commandId: id,
+            workspaceRoot,
+            command: input.command,
+            stdin: input.stdin
+          })
+
+          yield* tryProvider('writeFiles', () => active.handle.writeFiles(commandFiles.files))
+
+          const startedAtMs = yield* Clock.currentTimeMillis
+          const command = yield* tryProvider('runCommand', () =>
+            active.handle.runDetachedCommand({
+              cmd: 'bash',
+              args: [commandFiles.wrapperPath],
+              cwd: absoluteSandboxCwd(workspaceRoot, normalizedCwd)
+            })
+          )
+          const output = yield* (input.background === true
+            ? probeBackgroundCommand(active.handle, command)
+            : waitForegroundCommand(command, timeoutMs))
+          const endedAtMs = yield* Clock.currentTimeMillis
+          const urls = yield* previewUrls(active.handle, ports)
+
+          return SandboxCommandResult.make({
+            exitCode: output.exitCode,
+            stdout: output.stdout,
+            stderr: output.stderr,
+            durationMs: Math.max(0, endedAtMs - startedAtMs),
+            timedOut: output.timedOut,
+            workspaceReset: active.workspaceReset,
+            ...(output.backgroundId === undefined ? {} : { backgroundId: output.backgroundId }),
+            previewUrls: urls,
+            state: active.state
+          })
+        })
+
+      return Sandbox.of({
+        run: input => semaphore.withPermits(1)(runUnlocked(input)),
+        currentState: store.load(config.sandboxSessionId),
+        delete: Effect.gen(function* () {
+          const loaded = yield* store.load(config.sandboxSessionId)
+          if (Option.isSome(loaded)) {
+            yield* deleteNamedSandbox(loaded.value.name)
+          }
+          yield* store.clear(config.sandboxSessionId)
+        })
+      })
+    })
+  )
+
+export const makeVercelSandboxLayer = (config: VercelSandboxLayerConfig) =>
+  makeVercelSandboxLayerWithClient(config).pipe(Layer.provide(VercelSandboxClientLive))