Documentation
¶
Index ¶
- Constants
- func ValidateSandboxPath(p string, mode PathMode) error
- type Client
- func (c *Client) CreateSandbox(ctx context.Context, opts SandboxOpts) (*SandboxResponse, error)
- func (c *Client) DeleteSandbox(ctx context.Context, id string) error
- func (c *Client) DiscoverExecD(ctx context.Context, sandboxID string) (string, map[string]string, error)
- func (c *Client) DownloadFile(ctx context.Context, execdURL, path string) (io.ReadCloser, error)
- func (c *Client) GetEndpoint(ctx context.Context, sandboxID string, port int) (*Endpoint, error)
- func (c *Client) GetSandbox(ctx context.Context, id string) (*SandboxResponse, error)
- func (c *Client) ListSandboxes(ctx context.Context, metadata map[string]string) ([]SandboxResponse, error)
- func (c *Client) Ping(ctx context.Context, execdURL string) error
- func (c *Client) RunCommand(ctx context.Context, execdURL, cmd, cwd string, timeout int) (*CommandResult, error)
- func (c *Client) SearchFiles(ctx context.Context, execdURL, dir, pattern string) ([]FileInfo, error)
- func (c *Client) UploadFiles(ctx context.Context, execdURL string, files []FileUpload) error
- func (c *Client) WaitReady(ctx context.Context, id string) (*SandboxResponse, error)
- type CommandResult
- type DirEntry
- type EgressRule
- type Endpoint
- type FileInfo
- type FileUpload
- type ManagedSandbox
- type NetworkPolicy
- type PathMode
- type SandboxOpts
- type SandboxResponse
- type SandboxSessionOpts
- type SessionManager
- func (sm *SessionManager) Cleanup(ctx context.Context, maxIdle time.Duration)
- func (sm *SessionManager) Destroy(ctx context.Context, key string) error
- func (sm *SessionManager) Execute(ctx context.Context, key string, command, workdir string, timeout int) (*CommandResult, error)
- func (sm *SessionManager) GetOrCreate(ctx context.Context, tenantID, externalID string, opts SandboxSessionOpts) (*ManagedSandbox, error)
- func (sm *SessionManager) ListDir(ctx context.Context, key string, dirPath string, maxDepth int) ([]DirEntry, error)
- func (sm *SessionManager) ReadFile(ctx context.Context, key string, filePath string) ([]byte, error)
- func (sm *SessionManager) Shutdown(ctx context.Context)
- func (sm *SessionManager) SyncSessionFiles(ctx context.Context, key string) error
- func (sm *SessionManager) WriteFile(ctx context.Context, key string, filePath, content string) error
Constants ¶
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
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 ¶
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 ¶
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 ¶
DownloadFile retrieves a file from the sandbox. Caller must close the reader.
func (*Client) GetEndpoint ¶
GetEndpoint discovers the externally reachable address for a sandbox port.
func (*Client) GetSandbox ¶
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) 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 ¶
UploadFiles uploads files via ExecD's multipart endpoint (metadata+file pairs).
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 ¶
EgressRule describes a single egress permission.
type FileUpload ¶
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.
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.