providers

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 4, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CustomProvider 

type CustomProvider struct {
	// contains filtered or unexported fields
}

CustomProvider forwards all Provider interface calls to a user-specified HTTP endpoint. This allows users to bring their own sandbox backend.

The remote endpoint is expected to expose the following paths: 

POST   /spawn           — create a new sandbox
POST   /exec            — execute a command
POST   /files           — write a file
GET    /files            — read a file  (query: sandbox_id, path)
GET    /files/list       — list files   (query: sandbox_id, path)
GET    /status/:id       — sandbox status
DELETE /sandboxes/:id    — destroy a sandbox
GET    /health           — health check

func NewCustomProvider 

func NewCustomProvider(cfg CustomProviderConfig) *CustomProvider

NewCustomProvider creates a new CustomProvider that forwards calls to the given HTTP endpoint.

func (*CustomProvider) ChmodFile 

func (p *CustomProvider) ChmodFile(ctx context.Context, sandboxID string, path string, mode string) error

func (*CustomProvider) ConsoleLog 

func (p *CustomProvider) ConsoleLog(_ context.Context, _ string, _ int) ([]string, error)

func (*CustomProvider) DeleteFile 

func (p *CustomProvider) DeleteFile(ctx context.Context, sandboxID string, path string, recursive bool) error

func (*CustomProvider) Destroy 

func (p *CustomProvider) Destroy(ctx context.Context, sandboxID string) error

Destroy tears down a sandbox. DELETE /sandboxes/:id

func (*CustomProvider) Exec 

func (p *CustomProvider) Exec(ctx context.Context, sandboxID string, opts ExecOptions) (*ExecResult, error)

Exec runs a command in the sandbox. POST /exec { sandbox_id, command, args, env, workdir } Expects response: { "exit_code": 0, "stdout": "...", "stderr": "..." }

func (*CustomProvider) ExecStream 

func (p *CustomProvider) ExecStream(ctx context.Context, sandboxID string, opts ExecOptions) (<-chan StreamChunk, error)

ExecStream runs a command and streams NDJSON output chunks. POST /exec { sandbox_id, command, args, env, workdir, stream: true } Expects NDJSON response: { "stream": "stdout"|"stderr", "data": "..." }

func (*CustomProvider) GlobFiles 

func (p *CustomProvider) GlobFiles(ctx context.Context, sandboxID string, pattern string) ([]string, error)

func (*CustomProvider) Healthy 

func (p *CustomProvider) Healthy(ctx context.Context) bool

Healthy returns true if the remote provider endpoint is reachable and reports itself as healthy. GET /health

func (*CustomProvider) ListFiles 

func (p *CustomProvider) ListFiles(ctx context.Context, sandboxID string, path string) ([]FileInfo, error)

ListFiles lists files at the given path in the sandbox. GET /files/list?sandbox_id=...&path=...

func (*CustomProvider) MoveFile 

func (p *CustomProvider) MoveFile(ctx context.Context, sandboxID string, oldPath, newPath string) error

func (*CustomProvider) Name 

func (p *CustomProvider) Name() string

func (*CustomProvider) ReadFile 

func (p *CustomProvider) ReadFile(ctx context.Context, sandboxID string, path string) (io.ReadCloser, error)

ReadFile reads a file from the sandbox. GET /files?sandbox_id=...&path=...

func (*CustomProvider) Spawn 

func (p *CustomProvider) Spawn(ctx context.Context, opts SpawnOptions) (string, error)

Spawn creates a new sandbox on the remote endpoint. POST /spawn { image, memory_mb, vcpus, disk_size_mb, metadata } Expects response: { "id": "..." }

func (*CustomProvider) StatFile 

func (p *CustomProvider) StatFile(ctx context.Context, sandboxID string, path string) (*FileInfo, error)

func (*CustomProvider) Status 

func (p *CustomProvider) Status(ctx context.Context, sandboxID string) (*SandboxStatus, error)

Status returns the current status of a sandbox. GET /status/:id

func (*CustomProvider) WriteFile 

func (p *CustomProvider) WriteFile(ctx context.Context, sandboxID string, path string, content io.Reader, mode string) error

WriteFile writes content to a file in the sandbox. POST /files { sandbox_id, path, content, mode }

type CustomProviderConfig 

type CustomProviderConfig struct {
	ProviderName string        `yaml:"name"     mapstructure:"name"`
	BaseURL      string        `yaml:"base_url" mapstructure:"base_url"`
	APIKey       string        `yaml:"api_key"  mapstructure:"api_key"`
	Timeout      time.Duration `yaml:"timeout"  mapstructure:"timeout"` // 0 means 60s default
}

CustomProviderConfig holds the configuration for a custom HTTP provider.

type E2BConfig 

type E2BConfig struct {
	APIKey  string `yaml:"api_key" mapstructure:"api_key"`
	BaseURL string `yaml:"base_url" mapstructure:"base_url"`
}

type E2BProvider 

type E2BProvider struct {
	// contains filtered or unexported fields
}

E2BProvider wraps the E2B REST API (no official Go SDK).

func NewE2BProvider 

func NewE2BProvider(cfg E2BConfig) *E2BProvider

func (*E2BProvider) ChmodFile 

func (p *E2BProvider) ChmodFile(ctx context.Context, sandboxID string, path string, mode string) error

func (*E2BProvider) ConsoleLog 

func (p *E2BProvider) ConsoleLog(_ context.Context, _ string, _ int) ([]string, error)

func (*E2BProvider) DeleteFile 

func (p *E2BProvider) DeleteFile(ctx context.Context, sandboxID string, path string, recursive bool) error

func (*E2BProvider) Destroy 

func (p *E2BProvider) Destroy(ctx context.Context, sandboxID string) error

func (*E2BProvider) Exec 

func (p *E2BProvider) Exec(ctx context.Context, sandboxID string, opts ExecOptions) (*ExecResult, error)

func (*E2BProvider) ExecStream 

func (p *E2BProvider) ExecStream(ctx context.Context, sandboxID string, opts ExecOptions) (<-chan StreamChunk, error)

func (*E2BProvider) GlobFiles 

func (p *E2BProvider) GlobFiles(ctx context.Context, sandboxID string, pattern string) ([]string, error)

func (*E2BProvider) Healthy 

func (p *E2BProvider) Healthy(ctx context.Context) bool

func (*E2BProvider) ListFiles 

func (p *E2BProvider) ListFiles(ctx context.Context, sandboxID string, path string) ([]FileInfo, error)

func (*E2BProvider) MoveFile 

func (p *E2BProvider) MoveFile(ctx context.Context, sandboxID string, oldPath, newPath string) error

func (*E2BProvider) Name 

func (p *E2BProvider) Name() string

func (*E2BProvider) ReadFile 

func (p *E2BProvider) ReadFile(ctx context.Context, sandboxID string, path string) (io.ReadCloser, error)

func (*E2BProvider) Spawn 

func (p *E2BProvider) Spawn(ctx context.Context, opts SpawnOptions) (string, error)

func (*E2BProvider) StatFile 

func (p *E2BProvider) StatFile(ctx context.Context, sandboxID string, path string) (*FileInfo, error)

func (*E2BProvider) Status 

func (p *E2BProvider) Status(ctx context.Context, sandboxID string) (*SandboxStatus, error)

func (*E2BProvider) WriteFile 

func (p *E2BProvider) WriteFile(ctx context.Context, sandboxID string, path string, content io.Reader, mode string) error

type ExecOptions 

type ExecOptions struct {
	Command string
	Args    []string
	Env     map[string]string
	WorkDir string
}

type ExecResult 

type ExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

type FileInfo 

type FileInfo struct {
	Path    string
	Size    int64
	Mode    string
	IsDir   bool
	ModTime string
}

type FirecrackerProvider 

type FirecrackerProvider struct {
	// contains filtered or unexported fields
}

FirecrackerProvider manages Firecracker microVMs directly via the Firecracker REST API and a custom vsock guest agent.

func NewFirecrackerProvider 

func NewFirecrackerProvider(cfg FirecrackerProviderConfig, logger zerolog.Logger) *FirecrackerProvider

NewFirecrackerProvider creates a new provider.

func (*FirecrackerProvider) BuildImage 

func (p *FirecrackerProvider) BuildImage(image string) (string, error)

BuildImage pre-builds a rootfs for the given Docker image and caches it. Returns the path to the cached rootfs.

func (*FirecrackerProvider) CheckDockerAccess 

func (p *FirecrackerProvider) CheckDockerAccess()

CheckDockerAccess logs a warning if Docker is not accessible. Called at startup so the user knows image builds won't work.

func (*FirecrackerProvider) ChmodFile 

func (p *FirecrackerProvider) ChmodFile(ctx context.Context, sandboxID string, path string, mode string) error

func (*FirecrackerProvider) ConsoleLog 

func (p *FirecrackerProvider) ConsoleLog(ctx context.Context, sandboxID string, lines int) ([]string, error)

func (*FirecrackerProvider) DeleteFile 

func (p *FirecrackerProvider) DeleteFile(ctx context.Context, sandboxID string, path string, recursive bool) error

func (*FirecrackerProvider) Destroy 

func (p *FirecrackerProvider) Destroy(ctx context.Context, sandboxID string) error

func (*FirecrackerProvider) Exec 

func (p *FirecrackerProvider) Exec(ctx context.Context, sandboxID string, opts ExecOptions) (*ExecResult, error)

func (*FirecrackerProvider) ExecStream 

func (p *FirecrackerProvider) ExecStream(ctx context.Context, sandboxID string, opts ExecOptions) (<-chan StreamChunk, error)

func (*FirecrackerProvider) GlobFiles 

func (p *FirecrackerProvider) GlobFiles(ctx context.Context, sandboxID string, pattern string) ([]string, error)

func (*FirecrackerProvider) Healthy 

func (p *FirecrackerProvider) Healthy(ctx context.Context) bool

func (*FirecrackerProvider) ListFiles 

func (p *FirecrackerProvider) ListFiles(ctx context.Context, sandboxID string, path string) ([]FileInfo, error)

func (*FirecrackerProvider) ListSnapshots 

func (p *FirecrackerProvider) ListSnapshots() []SnapshotSummary

ListSnapshots returns all valid snapshots with their metadata.

func (*FirecrackerProvider) MoveFile 

func (p *FirecrackerProvider) MoveFile(ctx context.Context, sandboxID string, oldPath, newPath string) error

func (*FirecrackerProvider) Name 

func (p *FirecrackerProvider) Name() string

func (*FirecrackerProvider) ProviderConfig 

func (p *FirecrackerProvider) ProviderConfig() FirecrackerProviderConfig

ProviderConfig returns a copy of the provider's configuration.

func (*FirecrackerProvider) ReadFile 

func (p *FirecrackerProvider) ReadFile(ctx context.Context, sandboxID string, path string) (io.ReadCloser, error)

func (*FirecrackerProvider) Spawn 

func (p *FirecrackerProvider) Spawn(ctx context.Context, opts SpawnOptions) (string, error)

func (*FirecrackerProvider) StatFile 

func (p *FirecrackerProvider) StatFile(ctx context.Context, sandboxID string, path string) (*FileInfo, error)

func (*FirecrackerProvider) Status 

func (p *FirecrackerProvider) Status(ctx context.Context, sandboxID string) (*SandboxStatus, error)

func (*FirecrackerProvider) WriteFile 

func (p *FirecrackerProvider) WriteFile(ctx context.Context, sandboxID string, path string, content io.Reader, mode string) error

type FirecrackerProviderConfig 

type FirecrackerProviderConfig struct {
	FirecrackerPath string
	KernelPath      string
	DefaultRootfs   string
	AgentPath       string
	DataDir         string
	DefaultMemoryMB int
}

FirecrackerProviderConfig holds configuration for the provider.

type ImageCache 

type ImageCache struct {
	// contains filtered or unexported fields
}

ImageCache manages cached rootfs images built from Docker images. Each unique Docker image is built once and stored as an ext4 file. The build process uses Docker for all privileged operations (mount, ext4 populate) so no root/sudo access is needed on the host — only Docker.

func NewImageCache 

func NewImageCache(cacheDir, agentPath string, diskMB int, logger zerolog.Logger) *ImageCache

NewImageCache creates a new image cache.

func (*ImageCache) Get 

func (ic *ImageCache) Get(image string) (string, error)

Get returns the path to a cached rootfs for the given Docker image. If the rootfs doesn't exist yet, it builds it from the Docker image. Returns ("", nil) if the image name is empty.

type MockProvider 

type MockProvider struct {
	// contains filtered or unexported fields
}

MockProvider implements Provider using temp directories and os/exec.

func NewMockProvider 

func NewMockProvider() *MockProvider

func (*MockProvider) ChmodFile 

func (m *MockProvider) ChmodFile(ctx context.Context, sandboxID string, path string, mode string) error

func (*MockProvider) ConsoleLog 

func (m *MockProvider) ConsoleLog(ctx context.Context, sandboxID string, lines int) ([]string, error)

func (*MockProvider) DeleteFile 

func (m *MockProvider) DeleteFile(ctx context.Context, sandboxID string, path string, recursive bool) error

func (*MockProvider) Destroy 

func (m *MockProvider) Destroy(ctx context.Context, sandboxID string) error

func (*MockProvider) Exec 

func (m *MockProvider) Exec(ctx context.Context, sandboxID string, opts ExecOptions) (*ExecResult, error)

func (*MockProvider) ExecStream 

func (m *MockProvider) ExecStream(ctx context.Context, sandboxID string, opts ExecOptions) (<-chan StreamChunk, error)

func (*MockProvider) GlobFiles 

func (m *MockProvider) GlobFiles(ctx context.Context, sandboxID string, pattern string) ([]string, error)

func (*MockProvider) Healthy 

func (m *MockProvider) Healthy(ctx context.Context) bool

func (*MockProvider) ListFiles 

func (m *MockProvider) ListFiles(ctx context.Context, sandboxID string, path string) ([]FileInfo, error)

func (*MockProvider) MoveFile 

func (m *MockProvider) MoveFile(ctx context.Context, sandboxID string, oldPath, newPath string) error

func (*MockProvider) Name 

func (m *MockProvider) Name() string

func (*MockProvider) ReadFile 

func (m *MockProvider) ReadFile(ctx context.Context, sandboxID string, path string) (io.ReadCloser, error)

func (*MockProvider) Spawn 

func (m *MockProvider) Spawn(ctx context.Context, opts SpawnOptions) (string, error)

func (*MockProvider) StatFile 

func (m *MockProvider) StatFile(ctx context.Context, sandboxID string, path string) (*FileInfo, error)

func (*MockProvider) Status 

func (m *MockProvider) Status(ctx context.Context, sandboxID string) (*SandboxStatus, error)

func (*MockProvider) WriteFile 

func (m *MockProvider) WriteFile(ctx context.Context, sandboxID string, path string, content io.Reader, mode string) error

type Provider 

type Provider interface {
	// Name returns the unique provider identifier.
	Name() string

	// Spawn creates a new sandbox and returns its ID.
	Spawn(ctx context.Context, opts SpawnOptions) (string, error)

	// Exec runs a command in the sandbox and returns the result.
	Exec(ctx context.Context, sandboxID string, opts ExecOptions) (*ExecResult, error)

	// ExecStream runs a command and streams output chunks.
	ExecStream(ctx context.Context, sandboxID string, opts ExecOptions) (<-chan StreamChunk, error)

	// WriteFile writes content to a file in the sandbox.
	WriteFile(ctx context.Context, sandboxID string, path string, content io.Reader, mode string) error

	// ReadFile reads a file from the sandbox.
	ReadFile(ctx context.Context, sandboxID string, path string) (io.ReadCloser, error)

	// ListFiles lists files at the given path in the sandbox.
	ListFiles(ctx context.Context, sandboxID string, path string) ([]FileInfo, error)

	// DeleteFile deletes a file or directory in the sandbox.
	DeleteFile(ctx context.Context, sandboxID string, path string, recursive bool) error

	// MoveFile moves/renames a file in the sandbox.
	MoveFile(ctx context.Context, sandboxID string, oldPath, newPath string) error

	// ChmodFile changes file permissions in the sandbox.
	ChmodFile(ctx context.Context, sandboxID string, path string, mode string) error

	// StatFile returns info about a single file in the sandbox.
	StatFile(ctx context.Context, sandboxID string, path string) (*FileInfo, error)

	// GlobFiles returns paths matching a glob pattern in the sandbox.
	GlobFiles(ctx context.Context, sandboxID string, pattern string) ([]string, error)

	// Status returns the current status of a sandbox.
	Status(ctx context.Context, sandboxID string) (*SandboxStatus, error)

	// Destroy tears down a sandbox.
	Destroy(ctx context.Context, sandboxID string) error

	// ConsoleLog returns the last n lines of the sandbox's console output.
	ConsoleLog(ctx context.Context, sandboxID string, lines int) ([]string, error)

	// Healthy returns true if the provider is operational.
	Healthy(ctx context.Context) bool
}

Provider defines the interface for sandbox execution backends.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages available providers.

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Default 

func (r *Registry) Default() string

Default returns the default provider name.

func (*Registry) Get 

func (r *Registry) Get(name string) (Provider, error)

Get returns a provider by name, or the default if name is empty.

func (*Registry) List 

func (r *Registry) List() []string

List returns all registered provider names.

func (*Registry) Register 

func (r *Registry) Register(p Provider)

Register adds a provider to the registry.

func (*Registry) SetDefault 

func (r *Registry) SetDefault(name string) error

SetDefault sets the default provider name.

type RingBuffer 

type RingBuffer struct {
	// contains filtered or unexported fields
}

RingBuffer is a thread-safe ring buffer that stores the last N lines of text. It implements io.Writer so it can be used as cmd.Stdout/Stderr.

func NewRingBuffer 

func NewRingBuffer(maxLines int) *RingBuffer

NewRingBuffer creates a ring buffer that stores up to maxLines lines.

func (*RingBuffer) Lines 

func (rb *RingBuffer) Lines(n int) []string

Lines returns the last n lines. If n <= 0 or n > stored, returns all stored lines.

func (*RingBuffer) Write 

func (rb *RingBuffer) Write(p []byte) (int, error)

Write implements io.Writer. It splits input by newlines and stores complete lines.

type SandboxStatus 

type SandboxStatus struct {
	ID    string
	State string
}

type SnapshotLister 

type SnapshotLister interface {
	ListSnapshots() []SnapshotSummary
}

SnapshotLister is an optional interface that providers can implement to expose their cached snapshots.

type SnapshotSummary 

type SnapshotSummary struct {
	Image     string    `json:"image"`
	Provider  string    `json:"provider"`
	CreatedAt time.Time `json:"created_at"`
}

SnapshotSummary describes a pre-built VM snapshot available for fast restore.

type SpawnOptions 

type SpawnOptions struct {
	Image      string
	MemoryMB   int
	VCPUs      int
	DiskSizeMB int
	Metadata   map[string]string
}

type StreamChunk 

type StreamChunk struct {
	Stream string `json:"stream"` // "stdout" or "stderr"
	Data   string `json:"data"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.