sandbox

Documentation

Index

• Constants
• type Client
  • func New(lifecycleURL, apiKey string, httpClient *http.Client) *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 EgressRule
• type Endpoint
• type FileInfo
• type FileUpload
• type NetworkPolicy
• type SandboxOpts
• type SandboxResponse

Constants

const ExecDPort = 44772

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

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 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 NetworkPolicy

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

NetworkPolicy controls the sandbox's network access.

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.