@yolk-sdk/sandbox 0.1.0-canary.18

package/src/errors.ts

@@ -0,0 +1,71 @@
+import * as Schema from 'effect/Schema'
+
+export const SandboxInputErrorCause = Schema.Literals([
+  'empty_command',
+  'invalid_cwd',
+  'invalid_timeout'
+])
+export type SandboxInputErrorCause = typeof SandboxInputErrorCause.Type
+
+export class SandboxInputError extends Schema.TaggedErrorClass<SandboxInputError>()(
+  'SandboxInputError',
+  {
+    cause: SandboxInputErrorCause,
+    message: Schema.String
+  }
+) {}
+
+export class SandboxConfigError extends Schema.TaggedErrorClass<SandboxConfigError>()(
+  'SandboxConfigError',
+  {
+    message: Schema.String,
+    cause: Schema.String
+  }
+) {}
+
+export class SandboxExpiredError extends Schema.TaggedErrorClass<SandboxExpiredError>()(
+  'SandboxExpiredError',
+  {
+    message: Schema.String,
+    expiredAtMs: Schema.Number
+  }
+) {}
+
+export class SandboxStateError extends Schema.TaggedErrorClass<SandboxStateError>()(
+  'SandboxStateError',
+  {
+    message: Schema.String,
+    cause: Schema.String,
+    underlying: Schema.optional(Schema.Unknown)
+  }
+) {}
+
+export class SandboxStateStoreError extends Schema.TaggedErrorClass<SandboxStateStoreError>()(
+  'SandboxStateStoreError',
+  {
+    message: Schema.String,
+    operation: Schema.String,
+    underlying: Schema.optional(Schema.Unknown)
+  }
+) {}
+
+export class SandboxProviderError extends Schema.TaggedErrorClass<SandboxProviderError>()(
+  'SandboxProviderError',
+  {
+    provider: Schema.Literal('vercel'),
+    operation: Schema.String,
+    message: Schema.String,
+    underlying: Schema.optional(Schema.Unknown)
+  }
+) {}
+
+export type SandboxError =
+  | SandboxInputError
+  | SandboxConfigError
+  | SandboxExpiredError
+  | SandboxStateError
+  | SandboxStateStoreError
+  | SandboxProviderError
+
+export const unknownToMessage = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)

package/src/index.ts

@@ -0,0 +1,52 @@
+export {
+  backgroundSandboxProbeMs,
+  defaultSandboxCommandTimeoutMs,
+  defaultSandboxIdleTtlMs,
+  defaultSandboxInitialSource,
+  defaultSandboxLifecycle,
+  defaultSandboxMaxLifetimeMs,
+  defaultSandboxPorts,
+  defaultSandboxWorkspaceRoot,
+  maxSandboxCommandTimeoutMs,
+  normalizeWorkspaceCwd,
+  sandboxCommandTimeoutMs,
+  sandboxLifecycleOrDefault,
+  sandboxSourceOrDefault,
+  sandboxStateDecision,
+  sandboxTimeoutExtendDeltaMs,
+  sandboxToolOutputLimit,
+  touchSandboxState,
+  validateSandboxCommand
+} from './lifecycle.ts'
+export { makeVercelSandboxName } from './name.ts'
+export {
+  DisposableSandboxLifecycle,
+  EmptySandboxInitialSource,
+  GitSandboxInitialSource,
+  PersistentSandboxLifecycle,
+  SandboxCommandInput,
+  SandboxCommandResult,
+  SandboxInitialSource,
+  SandboxLifecycle,
+  SandboxPreviewUrl,
+  SandboxResources,
+  SandboxSnapshotRetention,
+  SandboxState,
+  SnapshotSandboxInitialSource,
+  TarballSandboxInitialSource,
+  VercelSandboxState
+} from './model.ts'
+export { Sandbox } from './service.ts'
+export { SandboxStateStore } from './state-store.ts'
+export {
+  SandboxConfigError,
+  SandboxExpiredError,
+  SandboxInputError,
+  SandboxInputErrorCause,
+  SandboxProviderError,
+  SandboxStateError,
+  SandboxStateStoreError
+} from './errors.ts'
+export type { SandboxError } from './errors.ts'
+export type { SandboxApi } from './service.ts'
+export type { SandboxStateStoreApi } from './state-store.ts'

package/src/lifecycle.ts

@@ -0,0 +1,186 @@
+import { Effect, Option } from 'effect'
+import { SandboxInputError } from './errors.ts'
+import {
+  DisposableSandboxLifecycle,
+  EmptySandboxInitialSource,
+  type SandboxInitialSource,
+  type SandboxLifecycle,
+  type SandboxState,
+  VercelSandboxState
+} from './model.ts'
+
+export const defaultSandboxIdleTtlMs = 30 * 60_000
+export const defaultSandboxMaxLifetimeMs = 45 * 60_000
+export const defaultSandboxCommandTimeoutMs = 120_000
+export const maxSandboxCommandTimeoutMs = 600_000
+export const backgroundSandboxProbeMs = 2_000
+export const sandboxToolOutputLimit = 50_000
+export const defaultSandboxPorts: ReadonlyArray<number> = [3000, 5173, 4321, 8000]
+export const defaultSandboxWorkspaceRoot = '/vercel/sandbox'
+
+export const defaultSandboxLifecycle = DisposableSandboxLifecycle.make({
+  idleTtlMs: defaultSandboxIdleTtlMs,
+  maxLifetimeMs: defaultSandboxMaxLifetimeMs
+})
+
+export const defaultSandboxInitialSource = EmptySandboxInitialSource.make({})
+
+export type SandboxRecreateReason = 'idle_expired' | 'max_expired' | 'name_mismatch'
+
+export type SandboxStateDecision =
+  | {
+      readonly _tag: 'UseExisting'
+      readonly state: SandboxState
+    }
+  | {
+      readonly _tag: 'Create'
+      readonly workspaceReset: boolean
+      readonly reason?: SandboxRecreateReason
+    }
+
+const positiveOr = (value: number | undefined, fallback: number) =>
+  value === undefined || !Number.isFinite(value) || value <= 0 ? fallback : Math.floor(value)
+
+export const sandboxLifecycleOrDefault = (lifecycle?: SandboxLifecycle): SandboxLifecycle =>
+  lifecycle ?? defaultSandboxLifecycle
+
+export const sandboxSourceOrDefault = (source?: SandboxInitialSource): SandboxInitialSource =>
+  source ?? defaultSandboxInitialSource
+
+export const sandboxCommandTimeoutMs = (timeoutMs?: number) =>
+  Math.min(maxSandboxCommandTimeoutMs, positiveOr(timeoutMs, defaultSandboxCommandTimeoutMs))
+
+export const validateSandboxCommand = (command: string) => {
+  if (command.trim().length === 0) {
+    return Effect.fail(
+      new SandboxInputError({
+        cause: 'empty_command',
+        message: 'Sandbox command must not be empty'
+      })
+    )
+  }
+
+  return Effect.succeed(command)
+}
+
+export const normalizeWorkspaceCwd = (cwd?: string | null): Effect.Effect<string, SandboxInputError> => {
+  if (cwd === undefined || cwd === null || cwd.trim().length === 0) {
+    return Effect.succeed('.')
+  }
+
+  const trimmed = cwd.trim()
+
+  if (trimmed.startsWith('/') || trimmed.includes('\0')) {
+    return Effect.fail(
+      new SandboxInputError({
+        cause: 'invalid_cwd',
+        message: 'cwd must be workspace-relative'
+      })
+    )
+  }
+
+  const parts: Array<string> = []
+
+  for (const segment of trimmed.split('/')) {
+    if (segment.length === 0 || segment === '.') {
+      continue
+    }
+
+    if (segment === '..') {
+      const previous = parts.pop()
+      if (previous === undefined) {
+        return Effect.fail(
+          new SandboxInputError({
+            cause: 'invalid_cwd',
+            message: 'cwd must not escape the workspace'
+          })
+        )
+      }
+      continue
+    }
+
+    parts.push(segment)
+  }
+
+  return Effect.succeed(parts.length === 0 ? '.' : parts.join('/'))
+}
+
+export const absoluteSandboxCwd = (workspaceRoot: string, normalizedCwd: string) =>
+  normalizedCwd === '.' ? workspaceRoot : `${workspaceRoot}/${normalizedCwd}`
+
+export const initialSandboxState = (input: {
+  readonly name: string
+  readonly nowMs: number
+  readonly lifecycle: SandboxLifecycle
+}) => {
+  switch (input.lifecycle._tag) {
+    case 'Disposable':
+      return VercelSandboxState.make({
+        name: input.name,
+        createdAtMs: input.nowMs,
+        lastUsedAtMs: input.nowMs,
+        expiresAtMs: input.nowMs + input.lifecycle.idleTtlMs,
+        maxExpiresAtMs: input.nowMs + input.lifecycle.maxLifetimeMs
+      })
+    case 'Persistent':
+      return VercelSandboxState.make({
+        name: input.name,
+        createdAtMs: input.nowMs,
+        lastUsedAtMs: input.nowMs,
+        expiresAtMs: input.nowMs + input.lifecycle.idleTtlMs,
+        maxExpiresAtMs: Number.MAX_SAFE_INTEGER
+      })
+  }
+}
+
+export const touchSandboxState = (input: {
+  readonly state: SandboxState
+  readonly nowMs: number
+  readonly lifecycle: SandboxLifecycle
+}) => {
+  switch (input.lifecycle._tag) {
+    case 'Disposable':
+      return VercelSandboxState.make({
+        ...input.state,
+        lastUsedAtMs: input.nowMs,
+        expiresAtMs: Math.min(input.nowMs + input.lifecycle.idleTtlMs, input.state.maxExpiresAtMs)
+      })
+    case 'Persistent':
+      return VercelSandboxState.make({
+        ...input.state,
+        lastUsedAtMs: input.nowMs,
+        expiresAtMs: input.nowMs + input.lifecycle.idleTtlMs
+      })
+  }
+}
+
+export const sandboxTimeoutExtendDeltaMs = (input: {
+  readonly before: SandboxState
+  readonly after: SandboxState
+}) => Math.max(0, input.after.expiresAtMs - input.before.expiresAtMs)
+
+export const sandboxStateDecision = (input: {
+  readonly state: Option.Option<SandboxState>
+  readonly name: string
+  readonly nowMs: number
+}): SandboxStateDecision => {
+  if (Option.isNone(input.state)) {
+    return { _tag: 'Create', workspaceReset: false }
+  }
+
+  const state = input.state.value
+
+  if (state.name !== input.name) {
+    return { _tag: 'Create', workspaceReset: true, reason: 'name_mismatch' }
+  }
+
+  if (input.nowMs >= state.maxExpiresAtMs) {
+    return { _tag: 'Create', workspaceReset: true, reason: 'max_expired' }
+  }
+
+  if (input.nowMs >= state.expiresAtMs) {
+    return { _tag: 'Create', workspaceReset: true, reason: 'idle_expired' }
+  }
+
+  return { _tag: 'UseExisting', state }
+}

package/src/model.ts

@@ -0,0 +1,122 @@
+import * as Schema from 'effect/Schema'
+
+const NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()))
+const NonNegativeInteger = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)))
+const PositiveInteger = Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)))
+const PositiveNumber = Schema.Number.pipe(Schema.check(Schema.isGreaterThan(0)))
+
+export class SandboxCommandInput extends Schema.Class<SandboxCommandInput>(
+  'SandboxCommandInput'
+)({
+  command: Schema.String,
+  cwd: Schema.optional(Schema.String),
+  stdin: Schema.optional(Schema.String),
+  timeoutMs: Schema.optional(PositiveInteger),
+  background: Schema.optional(Schema.Boolean)
+}) {}
+
+export class SandboxPreviewUrl extends Schema.Class<SandboxPreviewUrl>('SandboxPreviewUrl')({
+  port: PositiveInteger,
+  url: NonEmptyTrimmedString
+}) {}
+
+export class VercelSandboxState extends Schema.TaggedClass<VercelSandboxState>()(
+  'Vercel',
+  {
+    name: NonEmptyTrimmedString,
+    createdAtMs: NonNegativeInteger,
+    lastUsedAtMs: NonNegativeInteger,
+    expiresAtMs: NonNegativeInteger,
+    maxExpiresAtMs: NonNegativeInteger
+  }
+) {}
+
+export const SandboxState = Schema.Union([VercelSandboxState])
+export type SandboxState = typeof SandboxState.Type
+
+export class SandboxCommandResult extends Schema.Class<SandboxCommandResult>(
+  'SandboxCommandResult'
+)({
+  exitCode: Schema.NullOr(Schema.Int),
+  stdout: Schema.String,
+  stderr: Schema.String,
+  durationMs: NonNegativeInteger,
+  timedOut: Schema.Boolean,
+  workspaceReset: Schema.Boolean,
+  backgroundId: Schema.optional(NonEmptyTrimmedString),
+  previewUrls: Schema.Array(SandboxPreviewUrl),
+  state: SandboxState
+}) {}
+
+export class DisposableSandboxLifecycle extends Schema.TaggedClass<DisposableSandboxLifecycle>()(
+  'Disposable',
+  {
+    idleTtlMs: PositiveInteger,
+    maxLifetimeMs: PositiveInteger
+  }
+) {}
+
+export class SandboxSnapshotRetention extends Schema.Class<SandboxSnapshotRetention>(
+  'SandboxSnapshotRetention'
+)({
+  count: PositiveInteger,
+  expirationMs: Schema.optional(NonNegativeInteger),
+  deleteEvicted: Schema.optional(Schema.Boolean)
+}) {}
+
+export class PersistentSandboxLifecycle extends Schema.TaggedClass<PersistentSandboxLifecycle>()(
+  'Persistent',
+  {
+    idleTtlMs: PositiveInteger,
+    snapshotExpirationMs: Schema.optional(NonNegativeInteger),
+    keepLastSnapshots: Schema.optional(SandboxSnapshotRetention)
+  }
+) {}
+
+export const SandboxLifecycle = Schema.Union([
+  DisposableSandboxLifecycle,
+  PersistentSandboxLifecycle
+])
+export type SandboxLifecycle = typeof SandboxLifecycle.Type
+
+export class EmptySandboxInitialSource extends Schema.TaggedClass<EmptySandboxInitialSource>()(
+  'Empty',
+  {}
+) {}
+
+export class SnapshotSandboxInitialSource extends Schema.TaggedClass<SnapshotSandboxInitialSource>()(
+  'Snapshot',
+  {
+    snapshotId: NonEmptyTrimmedString
+  }
+) {}
+
+export class GitSandboxInitialSource extends Schema.TaggedClass<GitSandboxInitialSource>()(
+  'Git',
+  {
+    url: NonEmptyTrimmedString,
+    username: Schema.optional(NonEmptyTrimmedString),
+    password: Schema.optional(NonEmptyTrimmedString),
+    depth: Schema.optional(PositiveInteger),
+    revision: Schema.optional(NonEmptyTrimmedString)
+  }
+) {}
+
+export class TarballSandboxInitialSource extends Schema.TaggedClass<TarballSandboxInitialSource>()(
+  'Tarball',
+  {
+    url: NonEmptyTrimmedString
+  }
+) {}
+
+export const SandboxInitialSource = Schema.Union([
+  EmptySandboxInitialSource,
+  SnapshotSandboxInitialSource,
+  GitSandboxInitialSource,
+  TarballSandboxInitialSource
+])
+export type SandboxInitialSource = typeof SandboxInitialSource.Type
+
+export class SandboxResources extends Schema.Class<SandboxResources>('SandboxResources')({
+  vcpus: PositiveNumber
+}) {}

package/src/name.ts

@@ -0,0 +1,23 @@
+const fnvOffsetBasis32 = 0x811c9dc5
+const fnvPrime32 = 0x01000193
+
+const fnv1a32 = (value: string, seed: number) => {
+  let hash = seed
+
+  for (const character of value) {
+    hash ^= character.codePointAt(0) ?? 0
+    hash = Math.imul(hash, fnvPrime32)
+  }
+
+  return (hash >>> 0).toString(36).padStart(7, '0')
+}
+
+const stableHash = (value: string) => {
+  const first = fnv1a32(value, fnvOffsetBasis32)
+  const second = fnv1a32([...value].reverse().join(''), fnvOffsetBasis32 ^ 0x9e3779b9)
+
+  return `${first}${second}`
+}
+
+export const makeVercelSandboxName = (sandboxSessionId: string) =>
+  `sandbox-${stableHash(sandboxSessionId)}`

package/src/service.ts

@@ -0,0 +1,19 @@
+import { Context } from 'effect'
+import type { Effect, Option } from 'effect'
+import type {
+  SandboxError,
+  SandboxProviderError,
+  SandboxStateError,
+  SandboxStateStoreError
+} from './errors.ts'
+import type { SandboxCommandInput, SandboxCommandResult, SandboxState } from './model.ts'
+
+export type SandboxApi = {
+  readonly run: (input: SandboxCommandInput) => Effect.Effect<SandboxCommandResult, SandboxError>
+  readonly currentState: Effect.Effect<Option.Option<SandboxState>, SandboxStateStoreError | SandboxStateError>
+  readonly delete: Effect.Effect<void, SandboxProviderError | SandboxStateStoreError | SandboxStateError>
+}
+
+export class Sandbox extends Context.Service<Sandbox, SandboxApi>()(
+  '@yolk-sdk/sandbox/Sandbox'
+) {}

package/src/state-store.ts

@@ -0,0 +1,17 @@
+import { Context } from 'effect'
+import type { Effect, Option } from 'effect'
+import type { SandboxStateStoreError } from './errors.ts'
+import type { SandboxState } from './model.ts'
+
+export type SandboxStateStoreApi = {
+  readonly load: (sandboxSessionId: string) => Effect.Effect<Option.Option<SandboxState>, SandboxStateStoreError>
+  readonly save: (input: {
+    readonly sandboxSessionId: string
+    readonly state: SandboxState
+  }) => Effect.Effect<void, SandboxStateStoreError>
+  readonly clear: (sandboxSessionId: string) => Effect.Effect<void, SandboxStateStoreError>
+}
+
+export class SandboxStateStore extends Context.Service<SandboxStateStore, SandboxStateStoreApi>()(
+  '@yolk-sdk/sandbox/SandboxStateStore'
+) {}

package/src/testing/index.ts

@@ -0,0 +1,63 @@
+import { Effect, Layer, Option, Ref } from 'effect'
+import type { SandboxCommandInput, SandboxCommandResult, SandboxState } from '../model.ts'
+import { Sandbox } from '../service.ts'
+import { SandboxStateStore } from '../state-store.ts'
+import type { SandboxError } from '../errors.ts'
+
+export type FakeSandboxRun = (
+  input: SandboxCommandInput
+) => Effect.Effect<SandboxCommandResult, SandboxError>
+
+export type FakeSandboxOptions = {
+  readonly run: FakeSandboxRun
+  readonly initialState?: SandboxState
+}
+
+export const makeFakeSandboxLayer = (options: FakeSandboxOptions) =>
+  Layer.effect(
+    Sandbox,
+    Ref.make(Option.fromNullishOr(options.initialState)).pipe(
+      Effect.map(stateRef =>
+        Sandbox.of({
+          run: input =>
+            options.run(input).pipe(
+              Effect.tap(result => Ref.set(stateRef, Option.some(result.state)))
+            ),
+          currentState: Ref.get(stateRef),
+          delete: Ref.set(stateRef, Option.none())
+        })
+      )
+    )
+  )
+
+export type InMemorySandboxStateStoreEntry = {
+  readonly sandboxSessionId: string
+  readonly state: SandboxState
+}
+
+export const makeInMemorySandboxStateStoreLayer = (
+  initial: ReadonlyArray<InMemorySandboxStateStoreEntry> = []
+) =>
+  Layer.effect(
+    SandboxStateStore,
+    Effect.gen(function* () {
+      const states = yield* Ref.make(
+        new Map(initial.map(entry => [entry.sandboxSessionId, entry.state]))
+      )
+
+      return SandboxStateStore.of({
+        load: sandboxSessionId =>
+          Ref.get(states).pipe(
+            Effect.map(current => Option.fromNullishOr(current.get(sandboxSessionId)))
+          ),
+        save: input =>
+          Ref.update(states, current => new Map([...current, [input.sandboxSessionId, input.state]])),
+        clear: sandboxSessionId =>
+          Ref.update(states, current => {
+            const next = new Map(current)
+            next.delete(sandboxSessionId)
+            return next
+          })
+      })
+    })
+  )