secondboxclient

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 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 ApplicationAuthority added in v0.6.0 

type ApplicationAuthority struct {
	CreatedAt     Timestamp                `json:"createdAt"`
	ExpiresAt     *Timestamp               `json:"expiresAt,omitempty"`
	ID            AuthorityID              `json:"id"`
	Kind          ApplicationAuthorityKind `json:"kind"`
	LookupID      TokenLookupID            `json:"lookupId"`
	Metadata      Metadata                 `json:"metadata"`
	ProfileGrants ProfileGrantList         `json:"profileGrants"`
	Revision      int64                    `json:"revision"`
	Scopes        ApplicationScopeList     `json:"scopes"`
	State         AuthorityState           `json:"state"`
	SubjectRef    OwnershipRef             `json:"subjectRef"`
	TenantRef     OwnershipRef             `json:"tenantRef"`
	UpdatedAt     Timestamp                `json:"updatedAt"`
}

type ApplicationAuthorityKind added in v0.6.0 

type ApplicationAuthorityKind = string
const (
	ApplicationAuthorityKindApplication ApplicationAuthorityKind = "application"
)

type ApplicationAuthorityPage added in v0.6.0 

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

type ApplicationBearerToken added in v0.6.0 

type ApplicationBearerToken = string

ApplicationBearerToken Complete high-entropy application bearer credential returned only by a successful creation or rotation response. It cannot be recovered later.

type ApplicationCredentialResponse added in v0.6.0 

type ApplicationCredentialResponse struct {
	Authority   ApplicationAuthority   `json:"authority"`
	BearerToken ApplicationBearerToken `json:"bearerToken"`
}

type ApplicationScope added in v0.6.0 

type ApplicationScope = string
const (
	ApplicationScopeSandboxRead        ApplicationScope = "sandbox:read"
	ApplicationScopeSandboxLifecycle   ApplicationScope = "sandbox:lifecycle"
	ApplicationScopeSandboxExec        ApplicationScope = "sandbox:exec"
	ApplicationScopeSandboxFiles       ApplicationScope = "sandbox:files"
	ApplicationScopeSandboxPorts       ApplicationScope = "sandbox:ports"
	ApplicationScopeSandboxPortsDirect ApplicationScope = "sandbox:ports:direct"
)

type ApplicationScopeList added in v0.6.0 

type ApplicationScopeList = []ApplicationScope

type ArgvCommand 

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

type AuditAttribution added in v0.6.0 

type AuditAttribution struct {
	ActorAuthorityID    AuthorityID              `json:"actorAuthorityId"`
	ActorAuthorityKind  AuthorityKind            `json:"actorAuthorityKind"`
	CorrelationMetadata AuditCorrelationMetadata `json:"correlationMetadata"`
	Operation           string                   `json:"operation"`
	Result              AuditResult              `json:"result"`
	SubjectRef          *OwnershipRef            `json:"subjectRef,omitempty"`
	TenantRef           OwnershipRef             `json:"tenantRef"`
}

AuditAttribution Attribution recorded for every management mutation and denial. Credential bearer and verifier material is never recorded.

type AuditCorrelationMetadata added in v0.6.0 

type AuditCorrelationMetadata = map[string]string

AuditCorrelationMetadata Bounded external correlation metadata. Bearer tokens, verifiers, and other credential material are forbidden.

type AuditResult added in v0.6.0 

type AuditResult = string
const (
	AuditResultSucceeded AuditResult = "succeeded"
	AuditResultDenied    AuditResult = "denied"
	AuditResultFailed    AuditResult = "failed"
)

type AuthorityID added in v0.6.0 

type AuthorityID = string

type AuthorityKind added in v0.6.0 

type AuthorityKind = string

AuthorityKind The fixed authority hierarchy. Kinds cannot be selected or widened by a credential request. 

const (
	AuthorityKindPlatform         AuthorityKind = "platform"
	AuthorityKindTenantController AuthorityKind = "tenant_controller"
	AuthorityKindApplication      AuthorityKind = "application"
)

type AuthorityState added in v0.6.0 

type AuthorityState = string
const (
	AuthorityStateActive  AuthorityState = "active"
	AuthorityStateExpired AuthorityState = "expired"
	AuthorityStateRevoked AuthorityState = "revoked"
)

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 NewSecondBoxTenantControllerClient added in v0.6.0 

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

NewSecondBoxTenantControllerClient constructs a tenant-controller client without caller-supplied ownership assertions.

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) CleanupSubject added in v0.6.0 

func (client *Client) CleanupSubject(ctx context.Context, subjectRef OwnershipRef, expectedRevision int64, idempotencyKey string) (Operation, error)

func (*Client) CloseSubject added in v0.6.0 

func (client *Client) CloseSubject(ctx context.Context, subjectRef OwnershipRef, expectedRevision int64, idempotencyKey string) (Subject, error)

func (*Client) CreateApplicationAuthority added in v0.6.0 

func (client *Client) CreateApplicationAuthority(ctx context.Context, request CreateApplicationAuthorityRequest, idempotencyKey string) (ApplicationCredentialResponse, error)

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) CreateSubject added in v0.6.0 

func (client *Client) CreateSubject(ctx context.Context, request CreateSubjectRequest, idempotencyKey string) (Subject, error)

func (*Client) CreateTenant added in v0.6.0 

func (client *Client) CreateTenant(ctx context.Context, request CreateTenantRequest, idempotencyKey string) (Tenant, error)

func (*Client) CreateTenantControllerAuthority added in v0.6.0 

func (client *Client) CreateTenantControllerAuthority(ctx context.Context, tenantRef OwnershipRef, request CreateTenantControllerAuthorityRequest, idempotencyKey string) (TenantControllerCredentialResponse, error)

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) GetApplicationAuthority added in v0.6.0 

func (client *Client) GetApplicationAuthority(ctx context.Context, authorityID AuthorityID) (ApplicationAuthority, error)

func (*Client) GetDeploymentUsage added in v0.6.0 

func (client *Client) GetDeploymentUsage(ctx context.Context, options PageOptions) (DeploymentUsage, error)

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) GetSubject added in v0.6.0 

func (client *Client) GetSubject(ctx context.Context, subjectRef OwnershipRef) (Subject, error)

func (*Client) GetTenant added in v0.6.0 

func (client *Client) GetTenant(ctx context.Context, tenantRef OwnershipRef) (Tenant, error)

func (*Client) GetTenantControllerAuthority added in v0.6.0 

func (client *Client) GetTenantControllerAuthority(ctx context.Context, tenantRef OwnershipRef, authorityID AuthorityID) (TenantControllerAuthority, error)

func (*Client) GetTenantUsage added in v0.6.0 

func (client *Client) GetTenantUsage(ctx context.Context, supplied ...PageOptions) (TenantUsage, error)

func (*Client) ListApplicationAuthorities added in v0.6.0 

func (client *Client) ListApplicationAuthorities(ctx context.Context, subjectRef OwnershipRef, options PageOptions) (ApplicationAuthorityPage, 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) ListSubjects added in v0.6.0 

func (client *Client) ListSubjects(ctx context.Context, options PageOptions) (SubjectPage, error)

func (*Client) ListTenantControllerAuthorities added in v0.6.0 

func (client *Client) ListTenantControllerAuthorities(ctx context.Context, tenantRef OwnershipRef, options PageOptions) (TenantControllerAuthorityPage, error)

func (*Client) ListTenants added in v0.6.0 

func (client *Client) ListTenants(ctx context.Context, options PageOptions) (TenantPage, error)

func (*Client) ReactivateTenant added in v0.6.0 

func (client *Client) ReactivateTenant(ctx context.Context, tenantRef OwnershipRef, expectedRevision int64, idempotencyKey string) (Tenant, 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) RevokeApplicationAuthority added in v0.6.0 

func (client *Client) RevokeApplicationAuthority(ctx context.Context, authorityID AuthorityID, expectedRevision int64, idempotencyKey string) (ApplicationAuthority, error)

func (*Client) RevokeTenantControllerAuthority added in v0.6.0 

func (client *Client) RevokeTenantControllerAuthority(ctx context.Context, tenantRef OwnershipRef, authorityID AuthorityID, expectedRevision int64, idempotencyKey string) (TenantControllerAuthority, error)

func (*Client) RotateApplicationAuthority added in v0.6.0 

func (client *Client) RotateApplicationAuthority(ctx context.Context, authorityID AuthorityID, expectedRevision int64, idempotencyKey string) (ApplicationCredentialResponse, error)

func (*Client) RotateTenantControllerAuthority added in v0.6.0 

func (client *Client) RotateTenantControllerAuthority(ctx context.Context, tenantRef OwnershipRef, authorityID AuthorityID, expectedRevision int64, idempotencyKey string) (TenantControllerCredentialResponse, 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) SuspendTenant added in v0.6.0 

func (client *Client) SuspendTenant(ctx context.Context, tenantRef OwnershipRef, expectedRevision int64, idempotencyKey string) (Tenant, error)

func (*Client) UpdateRunnerPool 

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

func (*Client) UpdateSubjectQuota added in v0.6.0 

func (client *Client) UpdateSubjectQuota(ctx context.Context, subjectRef OwnershipRef, request UpdateSubjectQuotaRequest, expectedRevision int64, idempotencyKey string) (Subject, 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 CreateApplicationAuthorityRequest added in v0.6.0 

type CreateApplicationAuthorityRequest struct {
	ExpiresAt     Timestamp            `json:"expiresAt"`
	Metadata      Metadata             `json:"metadata"`
	ProfileGrants ProfileGrantList     `json:"profileGrants"`
	Scopes        ApplicationScopeList `json:"scopes"`
	SubjectRef    OwnershipRef         `json:"subjectRef"`
}

CreateApplicationAuthorityRequest Creates only an application authority in the authenticated tenant. Kind and tenant cannot be supplied, and scopes and Profile grants must be subsets of the tenant ceiling.

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 CreateSubjectRequest added in v0.6.0 

type CreateSubjectRequest struct {
	ExpiresAt *Timestamp   `json:"expiresAt,omitempty"`
	Metadata  Metadata     `json:"metadata"`
	Quota     SubjectQuota `json:"quota"`
	Ref       OwnershipRef `json:"ref"`
}

type CreateTenantControllerAuthorityRequest added in v0.6.0 

type CreateTenantControllerAuthorityRequest struct {
	ExpiresAt Timestamp `json:"expiresAt"`
	Metadata  Metadata  `json:"metadata"`
}

CreateTenantControllerAuthorityRequest The platform selects only metadata and expiry; the authority kind, tenant binding, and code-owned management grant cannot be caller-selected.

type CreateTenantRequest added in v0.6.0 

type CreateTenantRequest struct {
	AggregateQuota           TenantQuota          `json:"aggregateQuota"`
	AllowedApplicationScopes ApplicationScopeList `json:"allowedApplicationScopes"`
	AllowedProfileGrants     ProfileGrantList     `json:"allowedProfileGrants"`
	ExpiresAt                *Timestamp           `json:"expiresAt,omitempty"`
	ExpiryPolicy             TenantExpiryPolicy   `json:"expiryPolicy"`
	Metadata                 Metadata             `json:"metadata"`
	Ref                      OwnershipRef         `json:"ref"`
}

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 DeploymentUsage added in v0.6.0 

type DeploymentUsage struct {
	NextCursor *string                `json:"nextCursor,omitempty"`
	ObservedAt Timestamp              `json:"observedAt"`
	Tenants    []TenantAggregateUsage `json:"tenants"`
	Usage      TenantQuotaUsage       `json:"usage"`
}

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"
	OperationKindSubjectCleanup  OperationKind = "subject_cleanup"
	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"
	ProblemCodeAuthorityKindMismatch                ProblemCode = "authority_kind_mismatch"
	ProblemCodeManagementUnavailable                ProblemCode = "management_unavailable"
	ProblemCodeCredentialResponseUnavailable        ProblemCode = "credential_response_unavailable"
	ProblemCodeNotFound                             ProblemCode = "not_found"
	ProblemCodeIdempotencyConflict                  ProblemCode = "idempotency_conflict"
	ProblemCodePreconditionFailed                   ProblemCode = "precondition_failed"
	ProblemCodeStateConflict                        ProblemCode = "state_conflict"
	ProblemCodeInvalidLifecycleTransition           ProblemCode = "invalid_lifecycle_transition"
	ProblemCodeResourceExpired                      ProblemCode = "resource_expired"
	ProblemCodeTenantSuspended                      ProblemCode = "tenant_suspended"
	ProblemCodeGrantEscalationDenied                ProblemCode = "grant_escalation_denied"
	ProblemCodeCleanupStateConflict                 ProblemCode = "cleanup_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 ProfileGrantList added in v0.6.0 

type ProfileGrantList = []ProfileName

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 QuotaUsage added in v0.6.0 

type QuotaUsage struct {
	ActiveInstances      int64 `json:"activeInstances"`
	ConcurrentOperations int64 `json:"concurrentOperations"`
	MemoryBytes          int64 `json:"memoryBytes"`
	PortSessions         int64 `json:"portSessions"`
	Sandboxes            int64 `json:"sandboxes"`
	Snapshots            int64 `json:"snapshots"`
	VcpuCount            int64 `json:"vcpuCount"`
}

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 Subject added in v0.6.0 

type Subject struct {
	CleanupState SubjectCleanupState `json:"cleanupState"`
	CreatedAt    Timestamp           `json:"createdAt"`
	ExpiresAt    *Timestamp          `json:"expiresAt,omitempty"`
	Metadata     Metadata            `json:"metadata"`
	Quota        SubjectQuota        `json:"quota"`
	Ref          OwnershipRef        `json:"ref"`
	Revision     int64               `json:"revision"`
	State        SubjectState        `json:"state"`
	TenantRef    OwnershipRef        `json:"tenantRef"`
	UpdatedAt    Timestamp           `json:"updatedAt"`
}

type SubjectCleanupState added in v0.6.0 

type SubjectCleanupState = string
const (
	SubjectCleanupStateNone      SubjectCleanupState = "none"
	SubjectCleanupStatePending   SubjectCleanupState = "pending"
	SubjectCleanupStateRunning   SubjectCleanupState = "running"
	SubjectCleanupStateSucceeded SubjectCleanupState = "succeeded"
	SubjectCleanupStateFailed    SubjectCleanupState = "failed"
)

type SubjectPage added in v0.6.0 

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

type SubjectQuota added in v0.6.0 

type SubjectQuota struct {
	MaxActiveInstances      int64 `json:"maxActiveInstances"`
	MaxConcurrentOperations int64 `json:"maxConcurrentOperations"`
	MaxMemoryBytes          int64 `json:"maxMemoryBytes"`
	MaxPortSessions         int64 `json:"maxPortSessions"`
	MaxSandboxes            int64 `json:"maxSandboxes"`
	MaxSnapshots            int64 `json:"maxSnapshots"`
	MaxVcpuCount            int64 `json:"maxVcpuCount"`
}

type SubjectState added in v0.6.0 

type SubjectState = string
const (
	SubjectStateActive  SubjectState = "active"
	SubjectStateClosing SubjectState = "closing"
	SubjectStateClosed  SubjectState = "closed"
	SubjectStateExpired SubjectState = "expired"
)

type SubjectUsage added in v0.6.0 

type SubjectUsage struct {
	Limits     SubjectQuota `json:"limits"`
	SubjectRef OwnershipRef `json:"subjectRef"`
	Usage      QuotaUsage   `json:"usage"`
}

type Tenant added in v0.6.0 

type Tenant struct {
	AggregateQuota           TenantQuota          `json:"aggregateQuota"`
	AllowedApplicationScopes ApplicationScopeList `json:"allowedApplicationScopes"`
	AllowedProfileGrants     ProfileGrantList     `json:"allowedProfileGrants"`
	CreatedAt                Timestamp            `json:"createdAt"`
	ExpiresAt                *Timestamp           `json:"expiresAt,omitempty"`
	ExpiryPolicy             TenantExpiryPolicy   `json:"expiryPolicy"`
	Metadata                 Metadata             `json:"metadata"`
	Ref                      OwnershipRef         `json:"ref"`
	Revision                 int64                `json:"revision"`
	State                    TenantState          `json:"state"`
	UpdatedAt                Timestamp            `json:"updatedAt"`
}

type TenantAggregateUsage added in v0.6.0 

type TenantAggregateUsage struct {
	Limits    TenantQuota      `json:"limits"`
	TenantRef OwnershipRef     `json:"tenantRef"`
	Usage     TenantQuotaUsage `json:"usage"`
}

type TenantControllerAuthority added in v0.6.0 

type TenantControllerAuthority struct {
	CreatedAt Timestamp                     `json:"createdAt"`
	ExpiresAt *Timestamp                    `json:"expiresAt,omitempty"`
	Grant     TenantControllerGrant         `json:"grant"`
	ID        AuthorityID                   `json:"id"`
	Kind      TenantControllerAuthorityKind `json:"kind"`
	LookupID  TokenLookupID                 `json:"lookupId"`
	Metadata  Metadata                      `json:"metadata"`
	Revision  int64                         `json:"revision"`
	State     AuthorityState                `json:"state"`
	TenantRef OwnershipRef                  `json:"tenantRef"`
	UpdatedAt Timestamp                     `json:"updatedAt"`
}

type TenantControllerAuthorityKind added in v0.6.0 

type TenantControllerAuthorityKind = string
const (
	TenantControllerAuthorityKindTenantController TenantControllerAuthorityKind = "tenant_controller"
)

type TenantControllerAuthorityPage added in v0.6.0 

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

type TenantControllerBearerToken added in v0.6.0 

type TenantControllerBearerToken = string

TenantControllerBearerToken Complete high-entropy tenant-controller bearer credential returned only by a successful creation or rotation response. It cannot be recovered later.

type TenantControllerCredentialResponse added in v0.6.0 

type TenantControllerCredentialResponse struct {
	Authority   TenantControllerAuthority   `json:"authority"`
	BearerToken TenantControllerBearerToken `json:"bearerToken"`
}

type TenantControllerGrant added in v0.6.0 

type TenantControllerGrant = string
const (
	TenantControllerGrantTenantManagement TenantControllerGrant = "tenant_management"
)

type TenantExpiryPolicy added in v0.6.0 

type TenantExpiryPolicy struct {
	MaximumAuthorityLifetimeSeconds int64 `json:"maximumAuthorityLifetimeSeconds"`
	MaximumSubjectLifetimeSeconds   int64 `json:"maximumSubjectLifetimeSeconds"`
}

type TenantPage added in v0.6.0 

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

type TenantQuota added in v0.6.0 

type TenantQuota struct {
	MaxActiveInstances        int64 `json:"maxActiveInstances"`
	MaxActiveSubjects         int64 `json:"maxActiveSubjects"`
	MaxApplicationAuthorities int64 `json:"maxApplicationAuthorities"`
	MaxConcurrentOperations   int64 `json:"maxConcurrentOperations"`
	MaxMemoryBytes            int64 `json:"maxMemoryBytes"`
	MaxPortSessions           int64 `json:"maxPortSessions"`
	MaxSandboxes              int64 `json:"maxSandboxes"`
	MaxSnapshots              int64 `json:"maxSnapshots"`
	MaxVcpuCount              int64 `json:"maxVcpuCount"`
}

type TenantQuotaUsage added in v0.6.0 

type TenantQuotaUsage struct {
	ActiveInstances        int64 `json:"activeInstances"`
	ActiveSubjects         int64 `json:"activeSubjects"`
	ApplicationAuthorities int64 `json:"applicationAuthorities"`
	ConcurrentOperations   int64 `json:"concurrentOperations"`
	MemoryBytes            int64 `json:"memoryBytes"`
	PortSessions           int64 `json:"portSessions"`
	Sandboxes              int64 `json:"sandboxes"`
	Snapshots              int64 `json:"snapshots"`
	VcpuCount              int64 `json:"vcpuCount"`
}

type TenantState added in v0.6.0 

type TenantState = string
const (
	TenantStateActive    TenantState = "active"
	TenantStateSuspended TenantState = "suspended"
	TenantStateExpired   TenantState = "expired"
)

type TenantUsage added in v0.6.0 

type TenantUsage struct {
	Limits     TenantQuota      `json:"limits"`
	NextCursor *string          `json:"nextCursor,omitempty"`
	ObservedAt Timestamp        `json:"observedAt"`
	Subjects   []SubjectUsage   `json:"subjects"`
	TenantRef  OwnershipRef     `json:"tenantRef"`
	Usage      TenantQuotaUsage `json:"usage"`
}

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 TokenLookupID added in v0.6.0 

type TokenLookupID = string

TokenLookupID Public non-secret token lookup identifier. It is safe to return from read and list operations and cannot authenticate by itself.

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 UpdateSubjectQuotaRequest added in v0.6.0 

type UpdateSubjectQuotaRequest struct {
	Quota SubjectQuota `json:"quota"`
}

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

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.