secondboxclient

package
v0.5.2 Latest Latest
Warning

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

Go to latest
Published: Aug 20, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var GetSandboxOperation = operations["getSandbox"]

GetSandboxOperation is retained for callers that use the lower-level Do method.

Functions

func EncodeJSONBody

func EncodeJSONBody(value any) (io.Reader, error)

EncodeJSONBody encodes one request without buffering a second copy.

func ExecOutcomeError

func ExecOutcomeError(outcome ExecOutcome) error

ExecOutcomeError maps one terminal ExecOutcome to an error, or nil when the command exited with status zero. It is the single interpretation of the outcome union; buffered, streaming, and terminal callers all share it.

func NewIdempotencyKey

func NewIdempotencyKey() (string, error)

NewIdempotencyKey returns one unguessable single-use request key.

Callers that must replay a request across process restarts should supply their own durable key instead; a generated key lives only for one call.

func ProblemCodeOf

func ProblemCodeOf(err error) string

ProblemCodeOf returns the typed service problem code carried by err, or "".

func RevisionETag

func RevisionETag(revision int64) string

RevisionETag renders one Sandbox revision as its If-Match validator.

Types

type APIError

type APIError struct {
	StatusCode int
	Problem    *Problem
	Body       []byte
}

APIError is a non-successful response with its structured problem when available.

func (*APIError) Error

func (failure *APIError) Error() string

type AcquireLeaseRequest

type AcquireLeaseRequest = contracts.AcquireLeaseRequest

type ArgvCommand

type ArgvCommand struct {
	Arguments  []string `json:"arguments"`
	Executable string   `json:"executable"`
	Mode       string   `json:"mode"`
}

type BootStage

type BootStage = string
const (
	BootStageRunnerAdmission  BootStage = "runner_admission"
	BootStageArtifactVerify   BootStage = "artifact_verify"
	BootStageWorkspaceAttach  BootStage = "workspace_attach"
	BootStageNetworkSetup     BootStage = "network_setup"
	BootStageComputeLaunch    BootStage = "compute_launch"
	BootStageGuestNegotiation BootStage = "guest_negotiation"
	BootStageReady            BootStage = "ready"
)

type BootStageTiming

type BootStageTiming = contracts.BootStageTiming

type BootStageTimingSummary

type BootStageTimingSummary struct {
	Duration DurationPercentiles `json:"duration"`
	Stage    BootStage           `json:"stage"`
}

type BootTiming

type BootTiming = contracts.BootTiming

type BufferedExecRequest

type BufferedExecRequest struct {
	Command              Command        `json:"command"`
	Cwd                  *WorkspacePath `json:"cwd,omitempty"`
	DeadlineMilliseconds int64          `json:"deadlineMilliseconds"`
	Environment          StringMap      `json:"environment"`
	MaximumOutputBytes   int64          `json:"maximumOutputBytes"`
	StdinBase64          *string        `json:"stdinBase64,omitempty"`
}

type CallOptions

type CallOptions struct {
	PathParameters  map[string]string
	QueryParameters url.Values
	Headers         http.Header
	Body            io.Reader
	ContentType     string
}

CallOptions supplies public wire values to one generated operation.

type Client

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

Client is the thin dependency-free HTTP transport.

func NewSecondBoxClient

func NewSecondBoxClient(rawURL, token string, httpClient *http.Client) (*Client, error)

NewSecondBoxClient constructs a client for trusted administrative callers.

func NewSecondBoxSubjectClient

func NewSecondBoxSubjectClient(
	rawURL, token, tenantRef, subjectRef string,
	httpClient *http.Client,
) (*Client, error)

NewSecondBoxSubjectClient validates transport and caller ownership values.

func (*Client) AdoptSandbox

func (client *Client) AdoptSandbox(ctx context.Context, sandboxID OpaqueID) (*SandboxHandle, error)

AdoptSandbox attaches a caller-owned handle to an existing durable Sandbox.

func (*Client) CreateProfile

func (client *Client) CreateProfile(ctx context.Context, request CreateProfileRequest, idempotencyKey string) (Profile, error)

func (*Client) CreateRunnerPool

func (client *Client) CreateRunnerPool(ctx context.Context, request CreateRunnerPoolRequest) (RunnerPool, error)

func (*Client) CreateSandbox

func (client *Client) CreateSandbox(
	ctx context.Context,
	request CreateSandboxRequest,
	idempotencyKey string,
) (*SandboxHandle, Operation, error)

CreateSandbox admits one Sandbox and returns a handle to its representation.

The returned Sandbox is the freshly created resource, which is not yet ready; callers wait for the states they require.

func (*Client) DeleteSnapshot

func (client *Client) DeleteSnapshot(
	ctx context.Context,
	snapshotID string,
	idempotencyKey string,
) (Operation, error)

DeleteSnapshot admits one asynchronous Snapshot deletion.

func (*Client) DisableProfile

func (client *Client) DisableProfile(ctx context.Context, name ProfileName, expectedRevision int64, idempotencyKey string) (Profile, error)

func (*Client) Do

func (client *Client) Do(
	ctx context.Context,
	metadata OperationMetadata,
	options RequestOptions,
) (*http.Response, error)

Do sends one route and leaves successful response decoding to the caller.

func (*Client) GetProfile

func (client *Client) GetProfile(ctx context.Context, name ProfileName) (Profile, error)

func (*Client) GetRunnerPool

func (client *Client) GetRunnerPool(ctx context.Context, name ProfileName) (RunnerPool, error)

func (*Client) GetSnapshot

func (client *Client) GetSnapshot(ctx context.Context, snapshotID OpaqueID) (Snapshot, error)

func (*Client) ListProfiles

func (client *Client) ListProfiles(ctx context.Context, options PageOptions) (ProfilePage, error)

func (*Client) ListRunnerPools

func (client *Client) ListRunnerPools(ctx context.Context, options PageOptions) (RunnerPoolPage, error)

func (*Client) ListSandboxes

func (client *Client) ListSandboxes(ctx context.Context, options SandboxListOptions) (SandboxPage, error)

func (*Client) ReleaseLease

func (client *Client) ReleaseLease(
	ctx context.Context,
	leaseID string,
	idempotencyKey string,
) error

ReleaseLease surrenders Lease authority before its expiry.

The route requires an idempotency key; an empty one is generated.

func (*Client) RenewLease

func (client *Client) RenewLease(
	ctx context.Context,
	leaseID string,
	duration time.Duration,
	idempotencyKey string,
) (Lease, error)

RenewLease extends active Lease authority by a new bounded duration.

The route requires an idempotency key; an empty one is generated.

func (*Client) Request

func (client *Client) Request(ctx context.Context, operationID string, options CallOptions) (*http.Response, error)

Request invokes a generated operation by its stable OpenAPI operationId.

func (*Client) RequestJSON

func (client *Client) RequestJSON(ctx context.Context, operationID string, options CallOptions, target any) error

RequestJSON invokes a generated operation and decodes its successful JSON response.

func (*Client) ReviseProfile

func (client *Client) ReviseProfile(ctx context.Context, name ProfileName, expectedRevision int64, request ReviseProfileRequest, idempotencyKey string) (Profile, error)

func (*Client) Run

func (client *Client) Run(
	ctx context.Context,
	request RunRequest,
) (*SandboxHandle, RunResult, error)

Run creates a Sandbox, waits for it to become ready, and executes one command.

The Sandbox is deliberately left in place: this handle never deletes a Sandbox implicitly. Callers dispose of the returned handle themselves. The caller's context deadline bounds the wait for readiness.

func (*Client) UpdateRunnerPool

func (client *Client) UpdateRunnerPool(ctx context.Context, name ProfileName, expectedRevision int64, request UpdateRunnerPoolRequest) (RunnerPool, error)

func (*Client) ValidateProfile

func (client *Client) ValidateProfile(ctx context.Context, name ProfileName) (Profile, error)

ValidateProfile proves that a named Profile currently accepts new Sandboxes.

func (*Client) WaitOperation

func (client *Client) WaitOperation(ctx context.Context, operationID string, interval time.Duration) (Operation, error)

WaitOperation polls an asynchronous operation until it reaches a terminal state.

type Command

type Command struct {
	ShellCommand *ShellCommand `json:"-"`
	ArgvCommand  *ArgvCommand  `json:"-"`
}

func (Command) MarshalJSON

func (value Command) MarshalJSON() ([]byte, error)

func (*Command) UnmarshalJSON

func (value *Command) UnmarshalJSON(data []byte) error

type CorrelationID

type CorrelationID = string

type CreateDirectoryRequest

type CreateDirectoryRequest struct {
	Path      WorkspacePath `json:"path"`
	Recursive bool          `json:"recursive"`
}

type CreatePortSessionRequest

type CreatePortSessionRequest struct {
	DurationSeconds int64  `json:"durationSeconds"`
	Name            string `json:"name"`
}

type CreateProfileRequest

type CreateProfileRequest = contracts.CreateProfileRequest

type CreateRunnerPoolRequest

type CreateRunnerPoolRequest = contracts.CreateRunnerPoolRequest

type CreateSandboxRequest

type CreateSandboxRequest = contracts.CreateSandboxRequest

type CreateSnapshotRequest

type CreateSnapshotRequest = contracts.CreateSnapshotRequest

type CreateTerminalRequest

type CreateTerminalRequest struct {
	Columns              int            `json:"columns"`
	Command              Command        `json:"command"`
	Cwd                  *WorkspacePath `json:"cwd,omitempty"`
	DeadlineMilliseconds int64          `json:"deadlineMilliseconds"`
	Detachable           bool           `json:"detachable"`
	Environment          StringMap      `json:"environment"`
	Rows                 int            `json:"rows"`
}

type DeploymentTimingSummary

type DeploymentTimingSummary = contracts.DeploymentTimingSummary

type DirectoryListing

type DirectoryListing struct {
	Entries []FileStat    `json:"entries"`
	Path    WorkspacePath `json:"path"`
}

type DurationPercentiles

type DurationPercentiles = contracts.DurationPercentiles

type ExecCancelled

type ExecCancelled struct {
	Kind   string     `json:"kind"`
	Output ExecOutput `json:"output"`
}

type ExecDeadlineExceeded

type ExecDeadlineExceeded struct {
	ElapsedMilliseconds int64      `json:"elapsedMilliseconds"`
	Kind                string     `json:"kind"`
	Output              ExecOutput `json:"output"`
}

type ExecExited

type ExecExited struct {
	ElapsedMilliseconds int64      `json:"elapsedMilliseconds"`
	ExitCode            int        `json:"exitCode"`
	Kind                string     `json:"kind"`
	Output              ExecOutput `json:"output"`
	Signal              *int       `json:"signal,omitempty"`
}

type ExecFailure

type ExecFailure struct {
	Kind               string
	Message            string
	SpawnFailureReason SpawnFailureKind
	Output             ExecOutput
}

ExecFailure is one terminal ExecOutcome that did not reach an exit status.

func (*ExecFailure) Error

func (failure *ExecFailure) Error() string

type ExecInfrastructureFailed

type ExecInfrastructureFailed struct {
	Kind      string                    `json:"kind"`
	Message   string                    `json:"message"`
	Reason    InfrastructureFailureKind `json:"reason"`
	Retryable bool                      `json:"retryable"`
}

type ExecOutcome

type ExecOutcome struct {
	ExecExited               *ExecExited               `json:"-"`
	ExecSpawnFailed          *ExecSpawnFailed          `json:"-"`
	ExecDeadlineExceeded     *ExecDeadlineExceeded     `json:"-"`
	ExecCancelled            *ExecCancelled            `json:"-"`
	ExecOutputExhausted      *ExecOutputExhausted      `json:"-"`
	ExecInfrastructureFailed *ExecInfrastructureFailed `json:"-"`
}

func (ExecOutcome) MarshalJSON

func (value ExecOutcome) MarshalJSON() ([]byte, error)

func (*ExecOutcome) UnmarshalJSON

func (value *ExecOutcome) UnmarshalJSON(data []byte) error

type ExecOutput

type ExecOutput struct {
	StderrBase64 string `json:"stderrBase64"`
	StdoutBase64 string `json:"stdoutBase64"`
}

type ExecOutputExhausted

type ExecOutputExhausted struct {
	Kind       string     `json:"kind"`
	LimitBytes int64      `json:"limitBytes"`
	Output     ExecOutput `json:"output"`
}

type ExecResult

type ExecResult struct {
	Stdout              []byte
	Stderr              []byte
	ExitCode            int
	Signal              *int
	ElapsedMilliseconds int64
}

ExecResult is one successfully exited command and its decoded output.

func DecodeExecOutcome

func DecodeExecOutcome(outcome ExecOutcome) (ExecResult, error)

DecodeExecOutcome decodes the output any terminal outcome carries.

A non-zero exit status and every non-exited outcome are reported through the returned error while the decoded output is still returned, because a command that failed usually explains itself on standard error.

type ExecSpawnFailed

type ExecSpawnFailed struct {
	Kind    string           `json:"kind"`
	Message string           `json:"message"`
	Reason  SpawnFailureKind `json:"reason"`
}

type ExecStream

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

ExecStream owns one negotiated, sequenced streaming-exec WebSocket.

func (*ExecStream) Cancel

func (stream *ExecStream) Cancel() error

Cancel requests guest-process cancellation on the ordered stream.

func (*ExecStream) Close

func (stream *ExecStream) Close() error

Close detaches the WebSocket. A nonterminal detach requests server-side cancellation.

func (*ExecStream) CloseInput

func (stream *ExecStream) CloseInput() error

CloseInput closes guest standard input after all prior bytes.

func (*ExecStream) GrantOutput

func (stream *ExecStream) GrantOutput(bytes int64) error

GrantOutput grants the server explicit output bytes without exceeding its negotiated window.

func (*ExecStream) Receive

func (stream *ExecStream) Receive() (ExecStreamFrame, error)

Receive reads the next ordered output or terminal outcome frame.

func (*ExecStream) SendInput

func (stream *ExecStream) SendInput(data []byte) error

SendInput sends the next binary-safe standard-input frame.

func (*ExecStream) SendInputFrame

func (stream *ExecStream) SendInputFrame(data []byte, endOfInput bool) error

SendInputFrame sends bytes and can close guest standard input in the same ordered frame.

type ExecStreamFrame

type ExecStreamFrame struct {
	StreamInputFrame   *StreamInputFrame   `json:"-"`
	StreamOutputFrame  *StreamOutputFrame  `json:"-"`
	StreamCreditFrame  *StreamCreditFrame  `json:"-"`
	StreamSignalFrame  *StreamSignalFrame  `json:"-"`
	StreamCancelFrame  *StreamCancelFrame  `json:"-"`
	StreamOutcomeFrame *StreamOutcomeFrame `json:"-"`
}

func (ExecStreamFrame) MarshalJSON

func (value ExecStreamFrame) MarshalJSON() ([]byte, error)

func (*ExecStreamFrame) UnmarshalJSON

func (value *ExecStreamFrame) UnmarshalJSON(data []byte) error

type ExecStreamSession

type ExecStreamSession struct {
	ExpiresAt    Timestamp    `json:"expiresAt"`
	Generation   int64        `json:"generation"`
	ID           OpaqueID     `json:"id"`
	SandboxID    OpaqueID     `json:"sandboxId"`
	State        SessionState `json:"state"`
	Subprotocol  string       `json:"subprotocol"`
	WebsocketURL string       `json:"websocketUrl"`
}

type ExecTiming

type ExecTiming = contracts.ExecTiming

type ExecTimingSummary

type ExecTimingSummary struct {
	Duration DurationPercentiles `json:"duration"`
	Mode     string              `json:"mode"`
	Outcome  string              `json:"outcome"`
}

type ExecutionPolicy

type ExecutionPolicy = contracts.ExecutionPolicy

type FileExistsResult

type FileExistsResult struct {
	Exists bool          `json:"exists"`
	Path   WorkspacePath `json:"path"`
}

type FileKind

type FileKind = string
const (
	FileKindFile         FileKind = "file"
	FileKindDirectory    FileKind = "directory"
	FileKindSymbolicLink FileKind = "symbolic_link"
)

type FileStat

type FileStat struct {
	Kind       FileKind      `json:"kind"`
	ModifiedAt Timestamp     `json:"modifiedAt"`
	Path       WorkspacePath `json:"path"`
	SizeBytes  int64         `json:"sizeBytes"`
}

type FileWriteResult

type FileWriteResult struct {
	Path      WorkspacePath `json:"path"`
	SHA256    string        `json:"sha256"`
	SizeBytes int64         `json:"sizeBytes"`
}

type GuestLiveness

type GuestLiveness = string
const (
	GuestLivenessUnknown  GuestLiveness = "unknown"
	GuestLivenessStarting GuestLiveness = "starting"
	GuestLivenessReady    GuestLiveness = "ready"
	GuestLivenessLost     GuestLiveness = "lost"
	GuestLivenessStopped  GuestLiveness = "stopped"
)

type HTTPRouteTimingSummary

type HTTPRouteTimingSummary struct {
	Duration    DurationPercentiles `json:"duration"`
	Route       string              `json:"route"`
	StatusClass string              `json:"statusClass"`
}

type InfrastructureFailureKind

type InfrastructureFailureKind = string
const (
	InfrastructureFailureKindTransport        InfrastructureFailureKind = "transport"
	InfrastructureFailureKindAdmission        InfrastructureFailureKind = "admission"
	InfrastructureFailureKindGenerationFenced InfrastructureFailureKind = "generation_fenced"
	InfrastructureFailureKindLeaseFenced      InfrastructureFailureKind = "lease_fenced"
	InfrastructureFailureKindGuestAgent       InfrastructureFailureKind = "guest_agent"
	InfrastructureFailureKindExecutionNode    InfrastructureFailureKind = "execution_node"
	InfrastructureFailureKindService          InfrastructureFailureKind = "service"
)

type Instance

type Instance struct {
	CreatedAt         Timestamp                  `json:"createdAt"`
	Generation        int64                      `json:"generation"`
	GuestHeartbeatAt  *Timestamp                 `json:"guestHeartbeatAt,omitempty"`
	GuestLiveness     GuestLiveness              `json:"guestLiveness"`
	ID                OpaqueID                   `json:"id"`
	ReadyAt           *Timestamp                 `json:"readyAt,omitempty"`
	SandboxID         OpaqueID                   `json:"sandboxId"`
	State             InstanceState              `json:"state"`
	StoppedAt         *Timestamp                 `json:"stoppedAt,omitempty"`
	TerminationReason *InstanceTerminationReason `json:"terminationReason,omitempty"`
	UpdatedAt         Timestamp                  `json:"updatedAt"`
}

type InstanceState

type InstanceState = string
const (
	InstanceStateStarting InstanceState = "starting"
	InstanceStateReady    InstanceState = "ready"
	InstanceStateDraining InstanceState = "draining"
	InstanceStateStopping InstanceState = "stopping"
	InstanceStateStopped  InstanceState = "stopped"
	InstanceStateLost     InstanceState = "lost"
	InstanceStateFailed   InstanceState = "failed"
)

type InstanceTerminationReason

type InstanceTerminationReason = string
const (
	InstanceTerminationReasonRequestedDrain     InstanceTerminationReason = "requested_drain"
	InstanceTerminationReasonRequestedStop      InstanceTerminationReason = "requested_stop"
	InstanceTerminationReasonIdleTimeout        InstanceTerminationReason = "idle_timeout"
	InstanceTerminationReasonMaximumDuration    InstanceTerminationReason = "maximum_duration"
	InstanceTerminationReasonGuestShutdown      InstanceTerminationReason = "guest_shutdown"
	InstanceTerminationReasonResourceExhaustion InstanceTerminationReason = "resource_exhaustion"
	InstanceTerminationReasonGuestAgentLost     InstanceTerminationReason = "guest_agent_lost"
	InstanceTerminationReasonRunnerLost         InstanceTerminationReason = "runner_lost"
	InstanceTerminationReasonStartupFailed      InstanceTerminationReason = "startup_failed"
	InstanceTerminationReasonFenced             InstanceTerminationReason = "fenced"
	InstanceTerminationReasonInternalFailure    InstanceTerminationReason = "internal_failure"
)

type Lease

type Lease = contracts.Lease

type LeaseKeeper

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

LeaseKeeper holds one Lease active by renewing it before it expires.

func (*LeaseKeeper) Close

func (keeper *LeaseKeeper) Close() error

Close stops renewal and releases the Lease.

func (*LeaseKeeper) Err

func (keeper *LeaseKeeper) Err() error

Err reports the renewal failure that ended background renewal, if any.

func (*LeaseKeeper) ID

func (keeper *LeaseKeeper) ID() string

ID returns the held Lease identifier.

type LeaseState

type LeaseState = string
const (
	LeaseStateActive   LeaseState = "active"
	LeaseStateReleased LeaseState = "released"
	LeaseStateExpired  LeaseState = "expired"
	LeaseStateFenced   LeaseState = "fenced"
)

type LifecycleOptions

type LifecycleOptions struct {
	IdempotencyKey string
	// IfMatch overrides the handle's observed revision validator. Most callers
	// leave it empty and rely on the still-explicit observed revision fence.
	IfMatch string
}

LifecycleOptions carries required idempotency and optimistic-concurrency values.

type LifecyclePolicy

type LifecyclePolicy = contracts.LifecyclePolicy

type Metadata

type Metadata = map[string]string

type NetworkDestination

type NetworkDestination = contracts.NetworkDestination

type NetworkPolicy

type NetworkPolicy = contracts.NetworkPolicy

type OpaqueID

type OpaqueID = string

type Operation

type Operation = contracts.Operation

type OperationFailure

type OperationFailure struct {
	Operation Operation
}

OperationFailure is a terminal asynchronous operation that did not succeed.

func (*OperationFailure) Error

func (failure *OperationFailure) Error() string

type OperationKind

type OperationKind = string
const (
	OperationKindCreate          OperationKind = "create"
	OperationKindStart           OperationKind = "start"
	OperationKindDrain           OperationKind = "drain"
	OperationKindStop            OperationKind = "stop"
	OperationKindDelete          OperationKind = "delete"
	OperationKindRelocate        OperationKind = "relocate"
	OperationKindSnapshotCreate  OperationKind = "snapshot_create"
	OperationKindSnapshotDelete  OperationKind = "snapshot_delete"
	OperationKindSnapshotRestore OperationKind = "snapshot_restore"
	OperationKindCancelExec      OperationKind = "cancel_exec"
	OperationKindCancelTerminal  OperationKind = "cancel_terminal"
)

type OperationMediaType

type OperationMediaType struct {
	ContentType string
	Schema      string
}

OperationMediaType is one accepted request representation.

type OperationMetadata

type OperationMetadata struct {
	OperationID         string
	Method              string
	PathTemplate        string
	RequestBody         []OperationMediaType
	RequestBodyRequired bool
}

OperationMetadata is the compact generated route description used by the thin client.

func LookupOperation

func LookupOperation(operationID string) (OperationMetadata, bool)

LookupOperation resolves one supported generated operation.

type OperationStageTiming

type OperationStageTiming = contracts.OperationStageTiming

type OperationState

type OperationState = string
const (
	OperationStatePending   OperationState = "pending"
	OperationStateRunning   OperationState = "running"
	OperationStateSucceeded OperationState = "succeeded"
	OperationStateFailed    OperationState = "failed"
	OperationStateCancelled OperationState = "cancelled"
)

type OperationTiming

type OperationTiming = contracts.OperationTiming

type OperationTimingSummary

type OperationTimingSummary struct {
	Execution DurationPercentiles `json:"execution"`
	Kind      OperationKind       `json:"kind"`
	Queue     DurationPercentiles `json:"queue"`
	State     OperationState      `json:"state"`
	Total     DurationPercentiles `json:"total"`
}

type OwnershipRef

type OwnershipRef = string

type PageOptions

type PageOptions struct {
	Limit  int
	Cursor string
}

PageOptions bounds one SDK list request and carries its opaque continuation.

type PingResult

type PingResult struct {
	Generation int64     `json:"generation"`
	Healthy    bool      `json:"healthy"`
	ObservedAt Timestamp `json:"observedAt"`
	SandboxID  OpaqueID  `json:"sandboxId"`
}

type PortPolicy

type PortPolicy = contracts.PortPolicy

type PortSession

type PortSession struct {
	CertificateSpkiSha256 *string   `json:"certificateSpkiSha256,omitempty"`
	CreatedAt             Timestamp `json:"createdAt"`
	Endpoint              string    `json:"endpoint"`
	ExpiresAt             Timestamp `json:"expiresAt"`
	Generation            int64     `json:"generation"`
	ID                    OpaqueID  `json:"id"`
	Name                  string    `json:"name"`
	Protocol              string    `json:"protocol"`
	SandboxID             OpaqueID  `json:"sandboxId"`
	State                 string    `json:"state"`
	Transport             string    `json:"transport"`
}

type PortTunnel

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

PortTunnel is a bidirectional byte stream over either the proxied WebSocket or the Runner's SPKI-pinned direct TLS endpoint.

func (*PortTunnel) Close

func (tunnel *PortTunnel) Close() error

func (*PortTunnel) Read

func (tunnel *PortTunnel) Read(payload []byte) (int, error)

func (*PortTunnel) Write

func (tunnel *PortTunnel) Write(payload []byte) (int, error)

type Problem

type Problem = contracts.Problem

type ProblemCode

type ProblemCode = string
const (
	ProblemCodeInvalidRequest                       ProblemCode = "invalid_request"
	ProblemCodeAuthenticationFailed                 ProblemCode = "authentication_failed"
	ProblemCodeAuthorizationFailed                  ProblemCode = "authorization_failed"
	ProblemCodeNotFound                             ProblemCode = "not_found"
	ProblemCodeIdempotencyConflict                  ProblemCode = "idempotency_conflict"
	ProblemCodePreconditionFailed                   ProblemCode = "precondition_failed"
	ProblemCodeStateConflict                        ProblemCode = "state_conflict"
	ProblemCodeWorkspaceMutationConflict            ProblemCode = "workspace_mutation_conflict"
	ProblemCodeGenerationFenced                     ProblemCode = "generation_fenced"
	ProblemCodeLeaseFenced                          ProblemCode = "lease_fenced"
	ProblemCodeProfileUnavailable                   ProblemCode = "profile_unavailable"
	ProblemCodeStartupModeUnsupported               ProblemCode = "startup_mode_unsupported"
	ProblemCodeHomeRunnerUnavailable                ProblemCode = "home_runner_unavailable"
	ProblemCodeSandboxNotStopped                    ProblemCode = "sandbox_not_stopped"
	ProblemCodeWorkspaceRelocationSnapshotsPresent  ProblemCode = "workspace_relocation_snapshots_present"
	ProblemCodeWorkspaceRelocationTargetUnavailable ProblemCode = "workspace_relocation_target_unavailable"
	ProblemCodeQuotaExceeded                        ProblemCode = "quota_exceeded"
	ProblemCodeLimitExceeded                        ProblemCode = "limit_exceeded"
	ProblemCodeGuestUnavailable                     ProblemCode = "guest_unavailable"
	ProblemCodeExecutionNodeUnavailable             ProblemCode = "execution_node_unavailable"
	ProblemCodeDependencyUnavailable                ProblemCode = "dependency_unavailable"
	ProblemCodeInternalError                        ProblemCode = "internal_error"
	ProblemCodeTerminalReplayEvicted                ProblemCode = "terminal_replay_evicted"
	ProblemCodeWaitExpired                          ProblemCode = "wait_expired"
)

type ProblemDetail

type ProblemDetail struct {
	Field  string `json:"field"`
	Reason string `json:"reason"`
}

type Profile

type Profile = contracts.Profile

type ProfileName

type ProfileName = string

type ProfilePage

type ProfilePage struct {
	Items      []Profile `json:"items"`
	NextCursor *string   `json:"nextCursor,omitempty"`
}

type ProfileRevision

type ProfileRevision struct {
	CreatedAt Timestamp           `json:"createdAt"`
	ID        OpaqueID            `json:"id"`
	Number    int64               `json:"number"`
	Spec      ProfileRevisionSpec `json:"spec"`
}

type ProfileRevisionSpec

type ProfileRevisionSpec = contracts.ProfileRevisionSpec

type ProfileState

type ProfileState = string
const (
	ProfileStateEnabled  ProfileState = "enabled"
	ProfileStateDisabled ProfileState = "disabled"
)

type RelocateSandboxRequest

type RelocateSandboxRequest struct {
	RunnerPool     *ProfileName `json:"runnerPool,omitempty"`
	TargetRunnerID *RunnerID    `json:"targetRunnerId,omitempty"`
}

type RemovePathRequest

type RemovePathRequest struct {
	Force     bool          `json:"force"`
	Path      WorkspacePath `json:"path"`
	Recursive bool          `json:"recursive"`
}

type RenewLeaseRequest

type RenewLeaseRequest = contracts.RenewLeaseRequest

type RequestOptions

type RequestOptions struct {
	PathParameters  map[string]string
	QueryParameters url.Values
	Headers         http.Header
	Body            io.Reader
	ContentType     string
}

RequestOptions supplies wire values to Do.

type ResourcePolicy

type ResourcePolicy = contracts.ResourcePolicy

type RestoreSnapshotRequest

type RestoreSnapshotRequest = contracts.RestoreSnapshotRequest

type RetentionPolicy

type RetentionPolicy = contracts.RetentionPolicy

type ReviseProfileRequest

type ReviseProfileRequest struct {
	Spec ProfileRevisionSpec `json:"spec"`
}

type RunRequest

type RunRequest struct {
	Profile              ProfileName
	Metadata             Metadata
	SourceSnapshotID     string
	Command              Command
	Cwd                  *WorkspacePath
	Environment          StringMap
	StdinBase64          *string
	DeadlineMilliseconds int64
	MaximumOutputBytes   int64
}

RunRequest is one create-then-execute request against a fresh Sandbox.

type RunResult

type RunResult struct {
	Sandbox Sandbox
	Outcome ExecOutcome
	Result  ExecResult
}

RunResult carries the Sandbox that ran the command and its decoded output.

type Runner

type Runner = contracts.Runner

type RunnerArchitectureList

type RunnerArchitectureList = []string

type RunnerCapabilityList

type RunnerCapabilityList = []string

type RunnerCapacityPolicy

type RunnerCapacityPolicy = map[string]int64

type RunnerID

type RunnerID = string

type RunnerPage

type RunnerPage = contracts.RunnerPage

type RunnerPool

type RunnerPool = contracts.RunnerPool

type RunnerPoolPage

type RunnerPoolPage = contracts.RunnerPoolPage

type RunnerPoolState

type RunnerPoolState = string
const (
	RunnerPoolStateReady    RunnerPoolState = "ready"
	RunnerPoolStateDraining RunnerPoolState = "draining"
	RunnerPoolStateOffline  RunnerPoolState = "offline"
)

type Sandbox

type Sandbox = contracts.Sandbox

type SandboxDesiredState

type SandboxDesiredState = string
const (
	SandboxDesiredStateRunning SandboxDesiredState = "running"
	SandboxDesiredStateStopped SandboxDesiredState = "stopped"
	SandboxDesiredStateDeleted SandboxDesiredState = "deleted"
)

type SandboxHandle

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

SandboxHandle retains a caller-owned Sandbox identity and its latest observed representation.

func NewSandboxHandle

func NewSandboxHandle(client *Client, sandbox Sandbox) *SandboxHandle

NewSandboxHandle attaches SDK behavior without taking ownership of Sandbox lifetime.

func (*SandboxHandle) AcquireLease

func (handle *SandboxHandle) AcquireLease(
	ctx context.Context,
	duration time.Duration,
	idempotencyKey string,
) (Lease, error)

AcquireLease obtains bounded exclusive authority over the observed generation.

func (*SandboxHandle) CancelTerminal

func (handle *SandboxHandle) CancelTerminal(
	ctx context.Context,
	sessionID OpaqueID,
	idempotencyKey string,
) (TerminalSession, error)

CancelTerminal durably requests process cancellation for one stable Terminal ID.

func (*SandboxHandle) ClosePortSession

func (handle *SandboxHandle) ClosePortSession(ctx context.Context, sessionID OpaqueID, idempotencyKey string) error

func (*SandboxHandle) ConnectExecStream

func (handle *SandboxHandle) ConnectExecStream(
	ctx context.Context,
	session ExecStreamSession,
	dialer *websocket.Dialer,
) (*ExecStream, error)

ConnectExecStream attaches to a session returned by CreateExecStream.

func (*SandboxHandle) ConnectPortTunnel

func (handle *SandboxHandle) ConnectPortTunnel(ctx context.Context, session PortSession, websocketDialer *websocket.Dialer, directDialer *net.Dialer) (*PortTunnel, error)

ConnectPortTunnel consumes one PortSession credential and selects only the transport declared by that session.

func (*SandboxHandle) ConnectTerminal

func (handle *SandboxHandle) ConnectTerminal(
	ctx context.Context,
	session TerminalSession,
	dialer *websocket.Dialer,
) (*Terminal, error)

ConnectTerminal attaches to a session returned by CreateTerminal or reconnect lookup.

func (*SandboxHandle) ConnectTerminalAfter

func (handle *SandboxHandle) ConnectTerminalAfter(
	ctx context.Context,
	session TerminalSession,
	afterSequence int64,
	dialer *websocket.Dialer,
) (*Terminal, error)

ConnectTerminalAfter attaches and replays output after the last sequence the caller received successfully. Pass -1 when no output has been received.

func (*SandboxHandle) CreateDirectory

func (handle *SandboxHandle) CreateDirectory(ctx context.Context, path WorkspacePath, recursive bool, idempotencyKey, leaseID string) error

func (*SandboxHandle) CreateExecStream

func (handle *SandboxHandle) CreateExecStream(
	ctx context.Context,
	request StreamingExecRequest,
	idempotencyKey string,
	leaseID string,
) (ExecStreamSession, error)

CreateExecStream negotiates a streaming-exec WebSocket session.

The generated transport deliberately leaves WebSocket ownership to the caller.

func (*SandboxHandle) CreatePortSession

func (handle *SandboxHandle) CreatePortSession(ctx context.Context, request CreatePortSessionRequest, idempotencyKey, leaseID string) (PortSession, error)

func (*SandboxHandle) CreateSnapshot

func (handle *SandboxHandle) CreateSnapshot(
	ctx context.Context,
	options LifecycleOptions,
	request CreateSnapshotRequest,
) (Operation, error)

CreateSnapshot admits one asynchronous Snapshot clone.

func (*SandboxHandle) CreateTerminal

func (handle *SandboxHandle) CreateTerminal(
	ctx context.Context,
	request CreateTerminalRequest,
	idempotencyKey string,
	leaseID string,
) (TerminalSession, error)

CreateTerminal negotiates a terminal WebSocket session.

The generated transport deliberately leaves WebSocket ownership to the caller.

func (*SandboxHandle) Delete

func (handle *SandboxHandle) Delete(ctx context.Context, options LifecycleOptions) (Operation, error)

Delete requests deletion; it is never called implicitly by this handle.

func (*SandboxHandle) Drain

func (handle *SandboxHandle) Drain(ctx context.Context, options LifecycleOptions) (Operation, error)

Drain rejects new Sandbox data-plane operations before stop or deletion.

func (*SandboxHandle) Execute

func (handle *SandboxHandle) Execute(
	ctx context.Context,
	request BufferedExecRequest,
	idempotencyKey string,
	leaseID string,
) (ExecOutcome, error)

Execute runs one bounded buffered command against the observed Sandbox generation.

func (*SandboxHandle) FileExists

func (handle *SandboxHandle) FileExists(ctx context.Context, path WorkspacePath, leaseID string) (bool, error)

func (*SandboxHandle) GenerationHeaders

func (handle *SandboxHandle) GenerationHeaders(leaseID string) http.Header

GenerationHeaders binds a data-plane request to the handle's observed generation.

func (*SandboxHandle) GetPortSession

func (handle *SandboxHandle) GetPortSession(ctx context.Context, sessionID OpaqueID) (PortSession, error)

func (*SandboxHandle) GetTerminal

func (handle *SandboxHandle) GetTerminal(
	ctx context.Context,
	sessionID OpaqueID,
) (TerminalSession, error)

GetTerminal returns the current reconnect descriptor for one stable Terminal ID.

func (*SandboxHandle) KeepLease

func (handle *SandboxHandle) KeepLease(
	ctx context.Context,
	duration time.Duration,
) (*LeaseKeeper, error)

KeepLease acquires a Lease and renews it until the keeper is closed.

Renewal is driven by the expiry the service actually granted rather than by the requested duration, because the pinned Profile bounds Lease length.

func (*SandboxHandle) ListDirectory

func (handle *SandboxHandle) ListDirectory(ctx context.Context, path WorkspacePath, leaseID string) (DirectoryListing, error)

func (*SandboxHandle) ListSnapshots

func (handle *SandboxHandle) ListSnapshots(ctx context.Context, options PageOptions) (SnapshotPage, error)

func (*SandboxHandle) ReadFile

func (handle *SandboxHandle) ReadFile(ctx context.Context, path WorkspacePath, maximumBytes int64, leaseID string) ([]byte, error)

ReadFile reads a workspace-relative file under an explicit output bound.

func (*SandboxHandle) Refresh

func (handle *SandboxHandle) Refresh(ctx context.Context) (Sandbox, error)

Refresh retrieves and retains the current Sandbox representation.

func (*SandboxHandle) Relocate

func (handle *SandboxHandle) Relocate(
	ctx context.Context,
	options LifecycleOptions,
	request RelocateSandboxRequest,
) (Operation, error)

Relocate moves one stopped Snapshot-free Sandbox Workspace to a compatible Runner.

func (*SandboxHandle) RemovePath

func (handle *SandboxHandle) RemovePath(ctx context.Context, path WorkspacePath, recursive, force bool, idempotencyKey, leaseID string) error

func (*SandboxHandle) Restore

func (handle *SandboxHandle) Restore(
	ctx context.Context,
	options LifecycleOptions,
	snapshotID string,
) (Operation, error)

Restore replaces the stopped Sandbox workspace with a writable Snapshot copy.

func (*SandboxHandle) Snapshot

func (handle *SandboxHandle) Snapshot() Sandbox

Snapshot returns the latest representation observed through this handle.

func (*SandboxHandle) Start

func (handle *SandboxHandle) Start(ctx context.Context, options LifecycleOptions) (Operation, error)

Start requests that the caller-owned Sandbox become ready.

func (*SandboxHandle) StatFile

func (handle *SandboxHandle) StatFile(ctx context.Context, path WorkspacePath, leaseID string) (FileStat, error)

func (*SandboxHandle) Stop

func (handle *SandboxHandle) Stop(ctx context.Context, options LifecycleOptions) (Operation, error)

Stop requests compute teardown while retaining the durable Sandbox.

func (*SandboxHandle) TakeoverLease

func (handle *SandboxHandle) TakeoverLease(
	ctx context.Context,
	duration time.Duration,
	idempotencyKey string,
) (Lease, error)

TakeoverLease atomically fences prior Lease authority and acquires its replacement.

func (*SandboxHandle) UpdateMetadata

func (handle *SandboxHandle) UpdateMetadata(ctx context.Context, metadata Metadata) (Sandbox, error)

UpdateMetadata replaces Metadata using the handle's observed revision. It never refreshes or replays after a failed optimistic-concurrency check.

func (*SandboxHandle) Wait

func (handle *SandboxHandle) Wait(
	ctx context.Context,
	states []SandboxState,
	deadline time.Duration,
) (Sandbox, error)

Wait asks the service to wait for one of the explicitly supplied Sandbox states.

func (*SandboxHandle) WaitFor

func (handle *SandboxHandle) WaitFor(
	ctx context.Context,
	states ...SandboxState,
) (Sandbox, error)

WaitFor blocks until the Sandbox reaches one of the supplied states.

The service bounds a single wait request, so this issues repeated bounded waits against the caller's context deadline and reports the last observed state when that deadline passes.

func (*SandboxHandle) WriteFile

func (handle *SandboxHandle) WriteFile(ctx context.Context, path WorkspacePath, content []byte, idempotencyKey, leaseID string) (FileWriteResult, error)

type SandboxInspection

type SandboxInspection struct {
	ActiveSessions int64     `json:"activeSessions"`
	Generation     int64     `json:"generation"`
	GuestHealthy   bool      `json:"guestHealthy"`
	ObservedAt     Timestamp `json:"observedAt"`
	SandboxID      OpaqueID  `json:"sandboxId"`
}

type SandboxListOptions

type SandboxListOptions struct {
	PageOptions
	Metadata Metadata
}

SandboxListOptions adds exact Metadata-containment filters to pagination.

type SandboxPage

type SandboxPage = contracts.SandboxPage

type SandboxState

type SandboxState = string
const (
	SandboxStateCreating SandboxState = "creating"
	SandboxStateStopped  SandboxState = "stopped"
	SandboxStateStarting SandboxState = "starting"
	SandboxStateReady    SandboxState = "ready"
	SandboxStateDraining SandboxState = "draining"
	SandboxStateStopping SandboxState = "stopping"
	SandboxStateFailed   SandboxState = "failed"
	SandboxStateDeleting SandboxState = "deleting"
	SandboxStateDeleted  SandboxState = "deleted"
)

type SandboxTiming

type SandboxTiming = contracts.SandboxTiming

type SessionState

type SessionState = string
const (
	SessionStateOpen     SessionState = "open"
	SessionStateDetached SessionState = "detached"
	SessionStateClosing  SessionState = "closing"
	SessionStateClosed   SessionState = "closed"
)

type ShellCommand

type ShellCommand struct {
	Command string `json:"command"`
	Mode    string `json:"mode"`
}

type Snapshot

type Snapshot = contracts.Snapshot

type SnapshotPage

type SnapshotPage = contracts.SnapshotPage

type SpawnFailureKind

type SpawnFailureKind = string
const (
	SpawnFailureKindNotFound            SpawnFailureKind = "not_found"
	SpawnFailureKindPermissionDenied    SpawnFailureKind = "permission_denied"
	SpawnFailureKindInvalidCwd          SpawnFailureKind = "invalid_cwd"
	SpawnFailureKindMalformedExecutable SpawnFailureKind = "malformed_executable"
)

type StartupMode added in v0.3.0

type StartupMode = string

StartupMode cold_boot starts a Sandbox by booting its guest. snapshot_resume resumes a prepared, identity-neutral guest, admits only onto Runners advertising the snapshot-resume capability, and never falls back to cold_boot.

const (
	StartupModeColdBoot       StartupMode = "cold_boot"
	StartupModeSnapshotResume StartupMode = "snapshot_resume"
)

type StartupPolicy added in v0.3.0

type StartupPolicy = contracts.StartupPolicy

StartupPolicy How every Instance of this Profile revision reaches ready. There is no default; an operator states the mode on every Profile revision and the immutable revision pins it.

type StreamCancelFrame

type StreamCancelFrame struct {
	Sequence int64  `json:"sequence"`
	Type     string `json:"type"`
}

type StreamCreditFrame

type StreamCreditFrame struct {
	Bytes    int64  `json:"bytes"`
	Sequence int64  `json:"sequence"`
	Type     string `json:"type"`
}

type StreamInputFrame

type StreamInputFrame struct {
	DataBase64 string `json:"dataBase64"`
	EndOfInput bool   `json:"endOfInput"`
	Sequence   int64  `json:"sequence"`
	Type       string `json:"type"`
}

type StreamOutcomeFrame

type StreamOutcomeFrame struct {
	Outcome  ExecOutcome `json:"outcome"`
	Sequence int64       `json:"sequence"`
	Type     string      `json:"type"`
}

type StreamOutputFrame

type StreamOutputFrame struct {
	DataBase64 string `json:"dataBase64"`
	Sequence   int64  `json:"sequence"`
	Stream     string `json:"stream"`
	Type       string `json:"type"`
}

type StreamSignalFrame

type StreamSignalFrame struct {
	Sequence int64  `json:"sequence"`
	Signal   int    `json:"signal"`
	Type     string `json:"type"`
}

type StreamingExecRequest

type StreamingExecRequest struct {
	Command              Command        `json:"command"`
	Cwd                  *WorkspacePath `json:"cwd,omitempty"`
	DeadlineMilliseconds int64          `json:"deadlineMilliseconds"`
	Environment          StringMap      `json:"environment"`
	MaximumOutputBytes   int64          `json:"maximumOutputBytes"`
	WindowBytes          int64          `json:"windowBytes"`
}

type StringMap

type StringMap = map[string]string

type Terminal

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

Terminal owns one authenticated, ordered Terminal WebSocket attachment.

func (*Terminal) Cancel

func (terminal *Terminal) Cancel() error

Cancel requests guest-process cancellation on the ordered terminal stream.

func (*Terminal) Close

func (terminal *Terminal) Close() error

Close detaches the WebSocket without deleting the Sandbox.

func (*Terminal) GrantOutput

func (terminal *Terminal) GrantOutput(bytes int64) error

GrantOutput grants the server explicit terminal output bytes.

func (*Terminal) Receive

func (terminal *Terminal) Receive() (TerminalFrame, error)

Receive reads the next ordered terminal output or outcome frame.

func (*Terminal) Resize

func (terminal *Terminal) Resize(rows int, columns int) error

Resize applies the next ordered terminal dimensions.

func (*Terminal) SendInput

func (terminal *Terminal) SendInput(data []byte) error

SendInput sends the next binary-safe terminal-input frame.

type TerminalAttachedFrame added in v0.2.0

type TerminalAttachedFrame struct {
	NextClientSequence *int64 `json:"nextClientSequence,omitempty"`
	Type               string `json:"type"`
}

type TerminalFrame

type TerminalFrame struct {
	TerminalAttachedFrame *TerminalAttachedFrame `json:"-"`
	TerminalInputFrame    *TerminalInputFrame    `json:"-"`
	TerminalOutputFrame   *TerminalOutputFrame   `json:"-"`
	TerminalResizeFrame   *TerminalResizeFrame   `json:"-"`
	StreamCreditFrame     *StreamCreditFrame     `json:"-"`
	StreamCancelFrame     *StreamCancelFrame     `json:"-"`
	StreamOutcomeFrame    *StreamOutcomeFrame    `json:"-"`
}

func (TerminalFrame) MarshalJSON

func (value TerminalFrame) MarshalJSON() ([]byte, error)

func (*TerminalFrame) UnmarshalJSON

func (value *TerminalFrame) UnmarshalJSON(data []byte) error

type TerminalInputFrame

type TerminalInputFrame struct {
	DataBase64 string `json:"dataBase64"`
	Sequence   int64  `json:"sequence"`
	Type       string `json:"type"`
}

type TerminalOutputFrame

type TerminalOutputFrame struct {
	DataBase64 string `json:"dataBase64"`
	Sequence   int64  `json:"sequence"`
	Type       string `json:"type"`
}

type TerminalResizeFrame

type TerminalResizeFrame struct {
	Columns  int    `json:"columns"`
	Rows     int    `json:"rows"`
	Sequence int64  `json:"sequence"`
	Type     string `json:"type"`
}

type TerminalSession

type TerminalSession struct {
	ExpiresAt          Timestamp    `json:"expiresAt"`
	Generation         int64        `json:"generation"`
	ID                 OpaqueID     `json:"id"`
	NextClientSequence int64        `json:"nextClientSequence"`
	SandboxID          OpaqueID     `json:"sandboxId"`
	State              SessionState `json:"state"`
	StreamWindowBytes  int64        `json:"streamWindowBytes"`
	Subprotocol        string       `json:"subprotocol"`
	WebsocketURL       string       `json:"websocketUrl"`
}

type Timestamp

type Timestamp = time.Time

type TouchResult

type TouchResult struct {
	Generation     int64     `json:"generation"`
	LastActivityAt Timestamp `json:"lastActivityAt"`
	SandboxID      OpaqueID  `json:"sandboxId"`
}

type UpdateRunnerPoolRequest

type UpdateRunnerPoolRequest struct {
	Architectures  RunnerArchitectureList `json:"architectures,omitempty"`
	Capabilities   RunnerCapabilityList   `json:"capabilities,omitempty"`
	CapacityPolicy RunnerCapacityPolicy   `json:"capacityPolicy,omitempty"`
	State          *RunnerPoolState       `json:"state,omitempty"`
}

type UpdateSandboxMetadataRequest

type UpdateSandboxMetadataRequest struct {
	Metadata Metadata `json:"metadata"`
}

type WaitSandboxRequest

type WaitSandboxRequest struct {
	DeadlineMilliseconds int64          `json:"deadlineMilliseconds"`
	States               []SandboxState `json:"states"`
}

type Workspace

type Workspace struct {
	CreatedAt  Timestamp `json:"createdAt"`
	Generation int64     `json:"generation"`
	ID         OpaqueID  `json:"id"`
	SizeBytes  int64     `json:"sizeBytes"`
	State      string    `json:"state"`
	UpdatedAt  Timestamp `json:"updatedAt"`
}

type WorkspacePath

type WorkspacePath = string

Jump to

Keyboard shortcuts

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