sandbox

package
v0.8.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: 19 Imported by: 0

Documentation

Index

Constants

View Source
const ExecDPort = 44772

ExecDPort is the standard port number for the ExecD agent inside sandboxes.

Variables

This section is empty.

Functions

func ValidateSandboxPath added in v0.8.0

func ValidateSandboxPath(p string, mode PathMode) error

ValidateSandboxPath validates that a path is safe for sandbox operations. Rules:

  • Must be absolute, starting with /sandbox/
  • No ".." components allowed
  • /sandbox/session/ → ReadWrite (workspace)
  • /sandbox/scripts/ → Read only
  • /sandbox/input/ → Read only
  • /sandbox/out/ → Write (and read)

Types

type Client

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

Client communicates with the OpenSandbox lifecycle API (sandbox CRUD) and the ExecD API (in-sandbox file and command operations).

func New

func New(lifecycleURL, apiKey string, httpClient *http.Client) *Client

New creates a Client. lifecycleURL is the base (e.g. "http://opensandbox:8080/v1").

func (*Client) CreateSandbox

func (c *Client) CreateSandbox(ctx context.Context, opts SandboxOpts) (*SandboxResponse, error)

CreateSandbox requests a new sandbox (HTTP 202, Pending state).

func (*Client) DeleteSandbox

func (c *Client) DeleteSandbox(ctx context.Context, id string) error

DeleteSandbox terminates and removes a sandbox (HTTP 204).

func (*Client) DiscoverExecD

func (c *Client) DiscoverExecD(ctx context.Context, sandboxID string) (string, map[string]string, error)

DiscoverExecD calls GetEndpoint for the standard ExecD port (44772).

func (*Client) DownloadFile

func (c *Client) DownloadFile(ctx context.Context, execdURL, path string) (io.ReadCloser, error)

DownloadFile retrieves a file from the sandbox. Caller must close the reader.

func (*Client) GetEndpoint

func (c *Client) GetEndpoint(ctx context.Context, sandboxID string, port int) (*Endpoint, error)

GetEndpoint discovers the externally reachable address for a sandbox port.

func (*Client) GetSandbox

func (c *Client) GetSandbox(ctx context.Context, id string) (*SandboxResponse, error)

GetSandbox retrieves the current state of a single sandbox.

func (*Client) ListSandboxes

func (c *Client) ListSandboxes(ctx context.Context, metadata map[string]string) ([]SandboxResponse, error)

ListSandboxes returns sandboxes matching the given metadata filters.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context, execdURL string) error

Ping performs a health check against the ExecD instance.

func (*Client) RunCommand

func (c *Client) RunCommand(ctx context.Context, execdURL, cmd, cwd string, timeout int) (*CommandResult, error)

RunCommand executes a command inside the sandbox. The SSE response uses non-standard framing: raw JSON + "\n\n", optionally "data:"-prefixed.

func (*Client) SearchFiles

func (c *Client) SearchFiles(ctx context.Context, execdURL, dir, pattern string) ([]FileInfo, error)

SearchFiles lists files in the sandbox matching a glob pattern.

func (*Client) UploadFiles

func (c *Client) UploadFiles(ctx context.Context, execdURL string, files []FileUpload) error

UploadFiles uploads files via ExecD's multipart endpoint (metadata+file pairs).

func (*Client) WaitReady

func (c *Client) WaitReady(ctx context.Context, id string) (*SandboxResponse, error)

WaitReady polls GetSandbox until "Running" or the context expires.

type CommandResult

type CommandResult struct {
	Stdout, Stderr string
	ExitCode       int
	Error          string
	Duration       time.Duration
}

CommandResult holds the outcome of an in-sandbox command execution.

type DirEntry added in v0.8.0

type DirEntry struct {
	Path  string `json:"path"`
	IsDir bool   `json:"is_dir"`
	Size  int64  `json:"size"`
}

DirEntry describes a single entry returned by ListDir.

type EgressRule

type EgressRule struct {
	Action string `json:"action"`
	Target string `json:"target"`
}

EgressRule describes a single egress permission.

type Endpoint

type Endpoint struct {
	Host    string
	Port    int
	URL     string
	Headers map[string]string
}

Endpoint describes a reachable port inside a running sandbox.

type FileInfo

type FileInfo struct {
	Path       string
	Size       int64
	ModifiedAt time.Time
}

FileInfo describes a file found by SearchFiles.

type FileUpload

type FileUpload struct {
	Path    string
	Content []byte
	Mode    int
}

FileUpload describes a single file to be uploaded into a sandbox.

type ManagedSandbox added in v0.8.0

type ManagedSandbox struct {
	SandboxID  string
	ExecDURL   string
	SessionID  string // DB session ID
	TenantID   string
	ExternalID string // VectorChat session UUID
	CreatedAt  time.Time
	LastUsedAt time.Time
	Image      string
}

ManagedSandbox tracks a long-lived sandbox tied to a session.

type NetworkPolicy

type NetworkPolicy struct {
	DefaultAction string       `json:"defaultAction"`
	Egress        []EgressRule `json:"egress,omitempty"`
}

NetworkPolicy controls the sandbox's network access.

type PathMode added in v0.8.0

type PathMode int

PathMode represents the allowed access mode for a sandbox path.

const (
	PathModeRead PathMode = iota
	PathModeWrite
	PathModeReadWrite
)

type SandboxOpts

type SandboxOpts struct {
	Image          string
	Entrypoint     []string
	Env            map[string]string
	Metadata       map[string]string
	Timeout        int               // seconds (60-86400)
	ResourceLimits map[string]string // e.g. {"cpu":"500m","memory":"256Mi"}
	NetworkPolicy  *NetworkPolicy
}

SandboxOpts configures a new sandbox.

type SandboxResponse

type SandboxResponse struct {
	ID, State string
	ExpiresAt time.Time
	CreatedAt time.Time
	Metadata  map[string]string
}

SandboxResponse is returned after sandbox creation or retrieval.

type SandboxSessionOpts added in v0.8.0

type SandboxSessionOpts struct {
	Image   string
	Memory  string
	CPU     string
	Timeout int // sandbox TTL in seconds
}

SandboxSessionOpts configures sandbox creation for a session.

type SessionManager added in v0.8.0

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

SessionManager manages long-lived sandboxes tied to sessions.

func NewSessionManager added in v0.8.0

func NewSessionManager(client *Client, s *store.Store, col *artifacts.Collector, cfg *config.Config) *SessionManager

NewSessionManager creates a SessionManager with all required dependencies.

func (*SessionManager) Cleanup added in v0.8.0

func (sm *SessionManager) Cleanup(ctx context.Context, maxIdle time.Duration)

Cleanup finds sandboxes that have been idle longer than maxIdle, syncs their files, then deletes them from OpenSandbox and removes them from the managed map. Called by a background goroutine.

func (*SessionManager) Destroy added in v0.8.0

func (sm *SessionManager) Destroy(ctx context.Context, key string) error

Destroy tears down a specific session sandbox. It syncs files first, then deletes the sandbox and removes it from the managed map.

func (*SessionManager) Execute added in v0.8.0

func (sm *SessionManager) Execute(ctx context.Context, key string, command, workdir string, timeout int) (*CommandResult, error)

Execute runs a command in the managed sandbox identified by key.

func (*SessionManager) GetOrCreate added in v0.8.0

func (sm *SessionManager) GetOrCreate(ctx context.Context, tenantID, externalID string, opts SandboxSessionOpts) (*ManagedSandbox, error)

GetOrCreate finds an existing managed sandbox by key or creates a new one. When creating: calls store.GetOrCreateSession, creates sandbox with OpenSandbox API, waits for ready, discovers ExecD, mounts session files from MinIO, and creates placeholder directories. Returns cached sandbox on subsequent calls.

func (*SessionManager) ListDir added in v0.8.0

func (sm *SessionManager) ListDir(ctx context.Context, key string, dirPath string, maxDepth int) ([]DirEntry, error)

ListDir lists directory entries in the sandbox using SearchFiles, validating the path for read access. It infers directories from file paths.

func (*SessionManager) ReadFile added in v0.8.0

func (sm *SessionManager) ReadFile(ctx context.Context, key string, filePath string) ([]byte, error)

ReadFile downloads a file from the managed sandbox, validating the path for read access.

func (*SessionManager) Shutdown added in v0.8.0

func (sm *SessionManager) Shutdown(ctx context.Context)

Shutdown syncs all managed session files and deletes all managed sandboxes. Called during graceful server shutdown.

func (*SessionManager) SyncSessionFiles added in v0.8.0

func (sm *SessionManager) SyncSessionFiles(ctx context.Context, key string) error

SyncSessionFiles downloads files from /sandbox/out/session/ and /sandbox/session/ in the sandbox, uploads them to MinIO, and creates or updates file records in the DB.

func (*SessionManager) WriteFile added in v0.8.0

func (sm *SessionManager) WriteFile(ctx context.Context, key string, filePath, content string) error

WriteFile uploads a file to the managed sandbox, validating the path for write access.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL