SandboxError

Errors a sandbox provider reports for operations on the sandbox itself: creating, resuming, stopping, and configuring it. File and process operations inside a sandbox fail with Effect’s PlatformError instead, as FileSystem and ChildProcessSpawner define.

SandboxError says which provider failed and holds the reason, so callers can recover from one reason with Effect.catchReason("SandboxError", "NotFoundError", ...). The operation that failed is the one the caller ran, which its span names. Each reason has a description, what happened in the provider’s words, and says with isRetryable whether trying again may succeed, as the reasons of AiError do.

Since v0.1.0

Errors

AlreadyExistsError (class)

A sandbox with the id create was given exists already.

Signature

declare class AlreadyExistsError

Source

Since v0.1.0

AuthenticationError (class)

The provider’s credentials are missing, invalid, or not authorized for the operation.

Signature

declare class AuthenticationError

Source

Since v0.1.0

InvalidOptionsError (class)

The options under the provider’s id in CreateOptions.providerOptions are not what the provider takes.

Signature

declare class InvalidOptionsError

Source

Since v0.1.0

NotFoundError (class)

The sandbox does not exist, as for an unknown or destroyed id, or it does not expose the port.

Signature

declare class NotFoundError

Source

Since v0.1.0

SandboxError (class)

The error every operation on a sandbox fails with: which provider failed, and why.

Example (Recovering from one reason)

import { Sandbox, SandboxProvider } from "@amends-dev/sandbox"
import { Effect } from "effect"

declare const id: Sandbox.SandboxId

// The sandbox with this id, created if it does not exist yet.
const sandbox = Effect.gen(function* () {
  const sandboxProvider = yield* SandboxProvider.SandboxProvider
  return yield* sandboxProvider
    .resume(id)
    .pipe(Effect.catchReason("SandboxError", "NotFoundError", () => sandboxProvider.create({ id })))
})

Signature

declare class SandboxError

Source

Since v0.1.0

SandboxErrorReason

Why a sandbox operation failed: one of the errors above, which SandboxError.reason holds.

Signature

declare const SandboxErrorReason: Schema.toTaggedUnion<
  "_tag",
  readonly [
    typeof AuthenticationError,
    typeof NotFoundError,
    typeof AlreadyExistsError,
    typeof InvalidOptionsError,
    typeof UnsupportedError,
    typeof UnavailableError,
    typeof UnknownError
  ]
>

Source

Since v0.1.0

SandboxErrorReason (type alias)

Signature

type SandboxErrorReason = typeof SandboxErrorReason.Type

Source

Since v0.1.0

UnavailableError (class)

The provider cannot be reached right now, or asks for fewer requests. Trying again may succeed.

Signature

declare class UnavailableError

Source

Since v0.1.0

UnknownError (class)

The provider failed for a reason none of the others names.

Signature

declare class UnknownError

Source

Since v0.1.0

UnsupportedError (class)

The provider cannot do this on its platform, such as enforce a network policy, transform requests, or expose a port once the sandbox exists.

Signature

declare class UnsupportedError

Source

Since v0.1.0