Documentation
¶
Overview ¶
Package sandbox is an OPTIONAL convenience wrapper around *gobash.Bash that mimics the shape of Vercel's @vercel/sandbox SDK so code targeting that hosted runtime can swap to go-bash as a drop-in local mock.
The package adds NO new security boundary on top of the one Bash already provides — the security model is the same VFS + the same network allow-list. The "sandbox" name reflects the SDK shape, not an extra layer of isolation.
Cited surface: the spec
Index ¶
- Variables
- type Command
- type Finished
- type MkDirOptions
- type Options
- type RunCommandParams
- type Sandbox
- func (s *Sandbox) Bash() *gobash.Bash
- func (s *Sandbox) FS() gbfs.FileSystem
- func (s *Sandbox) MkDir(_ context.Context, path string, opts MkDirOptions) error
- func (s *Sandbox) ReadFile(_ context.Context, path string) (string, error)
- func (s *Sandbox) RunCommand(ctx context.Context, p RunCommandParams) (*Command, error)
- func (s *Sandbox) Stop(_ context.Context) error
- func (s *Sandbox) WriteFiles(_ context.Context, files map[string]string) error
Constants ¶
This section is empty.
Variables ¶
var ErrFSConflict = errors.New("sandbox: FS and OverlayRoot are mutually exclusive")
ErrFSConflict is returned by Create when both FS and OverlayRoot are supplied. Use errors.Is to test for it.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
// contains filtered or unexported fields
}
Command is a live (or completed) command handle. Stdout/Stderr/Wait all block until the underlying Exec returns; for synchronous (non-detached) invocations the Exec has already returned by the time RunCommand returns, so those methods do not block.
func (*Command) Stderr ¶
Stderr blocks until the underlying Exec completes and returns the captured stderr.
func (*Command) Stdout ¶
Stdout blocks until the underlying Exec completes and returns the captured stdout. If the Exec returned an error other than a non-zero exit code, that error is returned alongside the partial buffer.
func (*Command) Wait ¶
Wait blocks until the underlying Exec completes and returns the terminal Finished state. A non-nil error indicates the Exec itself failed (parse error, limit overrun, ctx cancellation, etc.); the script's own non-zero exit code is reported via Finished.ExitCode, not via the error return.
type Finished ¶
type Finished struct {
ExitCode int
}
Finished is the terminal state of a Command. ExitCode mirrors the underlying script's exit code (0 on success, non-zero otherwise).
type MkDirOptions ¶
MkDirOptions configures Sandbox.MkDir. Recursive mirrors `mkdir -p`; Perm defaults to 0o755 when zero.
type Options ¶
type Options struct {
// Cwd is the initial working directory inside the Sandbox.
// Empty defers to the Bash default ("/home/user" when Files is
// empty, "/" otherwise).
Cwd string
// Env seeds the persistent environment. Per-call RunCommand env
// overrides this map.
Env map[string]string
// Timeout caps the wall-clock duration of a single RunCommand.
// Zero disables the per-call timeout cap; ctx-side cancellation
// still applies.
Timeout time.Duration
// FS is a host-supplied virtual filesystem. Mutually exclusive
// with OverlayRoot. Nil + empty OverlayRoot → default memfs.
FS gbfs.FileSystem
// OverlayRoot mounts the named host directory read-only at /
// inside the Sandbox, with writes captured in an in-memory
// overlay. Mutually exclusive with FS.
OverlayRoot string
// Network is forwarded to BashOptions.Network. Nil leaves
// network disabled.
Network *network.Config
}
Options configures a Sandbox at construction time. FS and OverlayRoot are mutually exclusive: supply at most one. When both are empty the Sandbox uses the default in-memory filesystem.
type RunCommandParams ¶
type RunCommandParams struct {
Cmd string
Args []string
Cwd string
Env map[string]string
Sudo bool
Detached bool
Stdin io.Reader
}
RunCommandParams describes a single command invocation. Sudo is accepted for API parity with @vercel/sandbox but has no effect — the in-process runtime has no privilege boundary to elevate across. Detached runs the Exec on a background goroutine; the caller drives completion via Command.Wait().
type Sandbox ¶
type Sandbox struct {
// contains filtered or unexported fields
}
Sandbox wraps a *gobash.Bash and re-shapes its public API to match @vercel/sandbox. Concurrent RunCommand calls on the same Sandbox serialize through the underlying Bash mutex.
func Create ¶
Create constructs a Sandbox from opts. The ctx argument is reserved for API parity with the Vercel SDK; nothing in the construction path observes it today.
func (*Sandbox) Bash ¶
Bash returns the underlying *gobash.Bash. Hosts that need access to the full Bash surface (transform plugins, registry mutations, pre-test history seeding) can drop down through this accessor.
func (*Sandbox) FS ¶
func (s *Sandbox) FS() gbfs.FileSystem
FS returns the underlying virtual filesystem.
func (*Sandbox) MkDir ¶
MkDir creates path in the Sandbox's VFS. With opts.Recursive=true it behaves like `mkdir -p`; otherwise it errors if any parent component is missing.
func (*Sandbox) ReadFile ¶
ReadFile reads path from the Sandbox's VFS and returns the content as a string.
func (*Sandbox) RunCommand ¶
RunCommand executes p inside the Sandbox. The supplied Cmd plus Args are shell-quoted and joined into a single script line, which the Bash runtime parses and dispatches like any other script.
When p.Detached is true the call returns immediately and the Exec runs on a background goroutine; Stdout/Stderr/Wait block until completion. When false (the default) the Exec runs synchronously before RunCommand returns.
func (*Sandbox) Stop ¶
Stop is a no-op kept for API parity with @vercel/sandbox. The in-process runtime has no live container to tear down.
func (*Sandbox) WriteFiles ¶
WriteFiles writes every entry in files to the Sandbox's VFS. The containing directories are created (mode 0o755) as needed. The value is the file content; an empty string writes an empty file.
Source Files