Documentation
¶
Overview ¶
Package sandbox provides isolation for untrusted tool/skill execution.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶ added in v0.3.0
type Backend string
Backend identifies a sandbox backend type.
func ParseBackend ¶ added in v0.3.0
ParseBackend parses a backend string.
type Config ¶ added in v0.3.0
type Config struct {
Backend Backend `json:"backend"`
WorkDir string `json:"work_dir,omitempty"`
// Container-specific
Image string `json:"image,omitempty"`
Network string `json:"network,omitempty"`
// K8s-specific
Namespace string `json:"namespace,omitempty"`
ServiceAcc string `json:"service_account,omitempty"`
// WASM-specific
WASMPath string `json:"wasm_path,omitempty"`
}
Config holds configuration for sandbox creation.
type ContainerConfig ¶
type ContainerConfig struct {
Image string
SocketPath string
MemoryBytes int64
CPUQuota int64
NetworkMode string
}
ContainerConfig holds container sandbox configuration.
type ContainerPool ¶ added in v0.3.0
type ContainerPool struct {
// contains filtered or unexported fields
}
ContainerPool maintains a pool of pre-warmed containers for reduced cold-start latency.
func NewPool ¶ added in v0.3.0
func NewPool(cfg PoolConfig) (*ContainerPool, error)
NewPool creates a ContainerPool with the given configuration.
func (*ContainerPool) Acquire ¶ added in v0.3.0
func (p *ContainerPool) Acquire() (Sandbox, error)
Acquire returns a ready sandbox from the pool. If the pool is empty, a new sandbox is created. Returns immediately if a warm container is available.
func (*ContainerPool) Close ¶ added in v0.3.0
func (p *ContainerPool) Close() error
Close shuts down the pool and all containers.
func (*ContainerPool) InUse ¶ added in v0.3.0
func (p *ContainerPool) InUse() int
InUse returns the number of containers currently in use.
func (*ContainerPool) Release ¶ added in v0.3.0
func (p *ContainerPool) Release(sb Sandbox) error
Release returns a sandbox to the pool. If the pool is full, the sandbox is closed.
func (*ContainerPool) Size ¶ added in v0.3.0
func (p *ContainerPool) Size() int
Size returns the current number of available containers.
type ContainerSandbox ¶
type ContainerSandbox struct {
Image string
// Resource limits
MemoryBytes int64
CPUQuota int64
NetworkMode string
// contains filtered or unexported fields
}
ContainerSandbox implements Sandbox using Docker Engine API for production-grade isolation.
func NewContainerSandbox ¶
func NewContainerSandbox(cfg ContainerConfig) *ContainerSandbox
NewContainerSandbox creates a Docker-based sandbox.
func (*ContainerSandbox) Close ¶
func (c *ContainerSandbox) Close() error
type K8sJobConfig ¶ added in v0.3.0
K8sJobConfig holds Kubernetes Job sandbox configuration.
type K8sJobSandbox ¶ added in v0.3.0
type K8sJobSandbox struct {
// contains filtered or unexported fields
}
K8sJobSandbox implements Sandbox using Kubernetes Jobs for cluster-level isolation. Each execution creates a Kubernetes Job, waits for completion, and collects output.
func NewK8sJobSandbox ¶ added in v0.3.0
func NewK8sJobSandbox(cfg K8sJobConfig) *K8sJobSandbox
NewK8sJobSandbox creates a Kubernetes Job-based sandbox.
func (*K8sJobSandbox) Close ¶ added in v0.3.0
func (s *K8sJobSandbox) Close() error
type PoolConfig ¶ added in v0.3.0
type PoolConfig struct {
// MaxSize is the maximum number of containers in the pool (default 5).
MaxSize int
// MaxIdleTime is how long an idle container is kept before being destroyed (default 5m).
MaxIdleTime time.Duration
// Factory creates new sandbox instances.
Factory func() (Sandbox, error)
}
PoolConfig configures a container pool.
type ProcessSandbox ¶
type ProcessSandbox struct {
WorkDir string
}
ProcessSandbox runs commands in a subprocess with timeouts. For production, replace with container-based isolation (gVisor, Firecracker, etc.).
func NewProcessSandbox ¶
func NewProcessSandbox(workDir string) *ProcessSandbox
func (*ProcessSandbox) Close ¶
func (s *ProcessSandbox) Close() error
type Result ¶
type Result struct {
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
ExitCode int `json:"exit_code"`
}
Result captures the output of a sandboxed execution.
type Sandbox ¶
type Sandbox interface {
Execute(ctx context.Context, command string, args []string, timeout time.Duration) (*Result, error)
Close() error
}
Sandbox defines the interface for executing untrusted code.
func NewFromConfig ¶ added in v0.3.0
NewFromConfig creates a sandbox based on the configuration. This is the factory function that selects the backend by config string.
type WASMSandbox ¶ added in v0.3.0
type WASMSandbox struct {
// contains filtered or unexported fields
}
WASMSandbox implements Sandbox using WebAssembly (WASI) for lightweight isolation. This provides near-native performance with memory safety guarantees.
func NewWASMSandbox ¶ added in v0.3.0
func NewWASMSandbox(wasmPath string) *WASMSandbox
NewWASMSandbox creates a WASM-based sandbox. wasmPath is the path to the WASM module to execute.
func (*WASMSandbox) Close ¶ added in v0.3.0
func (s *WASMSandbox) Close() error