contracts

package
v0.1.3 Latest Latest
Warning

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

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

Documentation

Overview

Package contracts defines the public and persisted SecondBox domain language.

Index

Constants

View Source 
const (
	ProfileStateEnabled  = "enabled"
	ProfileStateDisabled = "disabled"

	RunnerPoolStateReady    = "ready"
	RunnerPoolStateDraining = "draining"
	RunnerPoolStateOffline  = "offline"

	SandboxStateCreating = "creating"
	SandboxStateStopped  = "stopped"
	SandboxStateStarting = "starting"
	SandboxStateReady    = "ready"
	SandboxStateDraining = "draining"
	SandboxStateStopping = "stopping"
	SandboxStateFailed   = "failed"
	SandboxStateDeleting = "deleting"
	SandboxStateDeleted  = "deleted"

	SandboxDesiredStateRunning = "running"
	SandboxDesiredStateStopped = "stopped"
	SandboxDesiredStateDeleted = "deleted"

	OperationStatePending   = "pending"
	OperationStateRunning   = "running"
	OperationStateSucceeded = "succeeded"
	OperationStateFailed    = "failed"
	OperationStateCancelled = "cancelled"

	LeaseStateActive   = "active"
	LeaseStateReleased = "released"
	LeaseStateExpired  = "expired"
	LeaseStateFenced   = "fenced"

	// SandboxNameMetadataKey is the reserved Metadata key that names a Sandbox.
	// It is unique per tenant and subject among Sandboxes that are not deleted,
	// so a name resolves to exactly one Sandbox.
	SandboxNameMetadataKey = "secondbox.dev/name"

	// SandboxIDPrefix is the fixed prefix every minted Sandbox identifier
	// carries. Clients tell an identifier from a name by it, so a reserved name
	// may not begin with it.
	SandboxIDPrefix = "sbx_"

	GuestLivenessUnknown  = "unknown"
	GuestLivenessStarting = "starting"
	GuestLivenessReady    = "ready"
	GuestLivenessLost     = "lost"
	GuestLivenessStopped  = "stopped"

	ActivitySessionStateActive = "active"
	ActivitySessionStateClosed = "closed"
	ActivitySessionKindExec    = "exec"
	ActivitySessionKindFile    = "file"
	ActivitySessionKindPTY     = "pty"
	ActivitySessionKindPort    = "port"

	PortSessionStateOpen    = "open"
	PortSessionStateClosing = "closing"
	PortSessionStateClosed  = "closed"
	PortSessionStateExpired = "expired"
	PortSessionStateFenced  = "fenced"

	// PortTransportRelay proxies Port bytes through the control plane without
	// persisting payloads. It is the only transport an ordinary caller receives.
	PortTransportRelay = "relay"
	// PortTransportDirect carries Port bytes on a live socket to the home
	// Runner. Admission stays PostgreSQL-authoritative and fenced; only the
	// transport between the caller and the Runner differs.
	PortTransportDirect = "direct"

	DataPlaneTransportProxied = "proxied"
	DataPlaneTransportDirect  = "direct"

	ObjectStateStaging         = "staging"
	ObjectStateVerified        = "verified"
	ObjectStatePublished       = "published"
	ObjectStateIntegrityFailed = "integrity_failed"
	ObjectStateQuotaFailed     = "quota_failed"
	ObjectStateGarbagePending  = "garbage_pending"
	ObjectStateGarbageDeleting = "garbage_deleting"
	ObjectStateDeleted         = "deleted"

	TerminationReasonRequestedDrain     = "requested_drain"
	TerminationReasonRequestedStop      = "requested_stop"
	TerminationReasonIdleTimeout        = "idle_timeout"
	TerminationReasonMaximumDuration    = "maximum_duration"
	TerminationReasonGuestShutdown      = "guest_shutdown"
	TerminationReasonResourceExhaustion = "resource_exhaustion"
	TerminationReasonGuestAgentLost     = "guest_agent_lost"
	TerminationReasonRunnerLost         = "runner_lost"
	TerminationReasonStartupFailed      = "startup_failed"
	TerminationReasonFenced             = "fenced"
	TerminationReasonInternalFailure    = "internal_failure"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AcquireLeaseRequest 

type AcquireLeaseRequest struct {
	DurationSeconds int64 `json:"durationSeconds"`
	ReplaceActive   bool  `json:"replaceActive,omitempty"`
}

AcquireLeaseRequest selects a duration within the pinned Profile policy.

type ActivitySession 

type ActivitySession struct {
	ID             string     `json:"id"`
	TenantRef      string     `json:"tenantRef"`
	SubjectRef     string     `json:"subjectRef"`
	SandboxID      string     `json:"sandboxId"`
	Generation     int64      `json:"generation"`
	Kind           string     `json:"kind"`
	State          string     `json:"state"`
	LeaseID        string     `json:"leaseId,omitempty"`
	LastActivityAt time.Time  `json:"lastActivityAt"`
	CreatedAt      time.Time  `json:"createdAt"`
	ClosedAt       *time.Time `json:"closedAt,omitempty"`
}

ActivitySession is useful generation-bound work that prevents idle reclamation.

type Artifact 

type Artifact struct {
	ID                 string            `json:"id"`
	TenantRef          string            `json:"-"`
	SubjectRef         string            `json:"-"`
	SandboxID          string            `json:"sandboxId"`
	SourceGeneration   int64             `json:"generation"`
	Name               string            `json:"name"`
	MediaType          string            `json:"mediaType"`
	SizeBytes          int64             `json:"sizeBytes"`
	SHA256             string            `json:"sha256"`
	State              string            `json:"-"`
	Metadata           map[string]string `json:"metadata"`
	RetainUntil        time.Time         `json:"expiresAt"`
	CreatedAt          time.Time         `json:"createdAt"`
	PublishedAt        *time.Time        `json:"-"`
	GarbageCollectedAt *time.Time        `json:"-"`
}

Artifact is immutable application exchange evidence.

type ArtifactPage 

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

ArtifactPage is one bounded, newest-first immutable Artifact page.

type Assignment 

type Assignment struct {
	ID                 string
	SandboxID          string
	InstanceID         string
	RunnerID           string
	Generation         int64
	FencingToken       []byte
	State              string
	CapabilitySnapshot map[string]string
	ResolvedArtifacts  map[string]string
	ReleaseProof       map[string]string
	ClaimExpiresAt     time.Time
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

Assignment is internal writer authority for one Sandbox generation.

type AuditEvent 

type AuditEvent struct {
	ID           string            `json:"id"`
	TenantRef    string            `json:"tenantRef,omitempty"`
	SubjectRef   string            `json:"subjectRef,omitempty"`
	ActorKind    string            `json:"actorKind"`
	ActorID      string            `json:"actorId"`
	Action       string            `json:"action"`
	ResourceKind string            `json:"resourceKind"`
	ResourceID   string            `json:"resourceId"`
	Outcome      string            `json:"outcome"`
	RequestID    string            `json:"requestId"`
	Details      map[string]string `json:"details"`
	CreatedAt    time.Time         `json:"createdAt"`
}

AuditEvent is immutable security and administration evidence without secrets.

type BootStageDurationMetric 

type BootStageDurationMetric struct {
	Stage     string
	Histogram MetricDurationHistogram
}

BootStageDurationMetric is one bounded startup-stage series.

type BootStageTiming 

type BootStageTiming struct {
	Stage                  string    `json:"stage"`
	ObservedAt             time.Time `json:"observedAt"`
	ReceivedAt             time.Time `json:"receivedAt"`
	ElapsedMilliseconds    float64   `json:"elapsedMilliseconds"`
	CumulativeMilliseconds float64   `json:"cumulativeMilliseconds"`
}

BootStageTiming attributes one provider-neutral Sandbox startup milestone.

type BootStageTimingSummary 

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

BootStageTimingSummary aggregates one provider-neutral startup stage.

type BootTiming 

type BootTiming struct {
	Generation           int64             `json:"generation"`
	DurationMilliseconds float64           `json:"durationMilliseconds"`
	Completed            bool              `json:"completed"`
	Stages               []BootStageTiming `json:"stages"`
}

BootTiming is one Sandbox generation's bounded startup attribution.

type BufferedExecRequest 

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

BufferedExecRequest is one bounded non-PTY execution.

type CreateDirectoryRequest 

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

type CreatePortSessionRequest 

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

CreatePortSessionRequest requests one pinned Profile port by name.

type CreateProfileRequest 

type CreateProfileRequest struct {
	Name string              `json:"name"`
	Spec ProfileRevisionSpec `json:"spec"`
}

CreateProfileRequest creates a stable Profile and its first immutable revision.

type CreateRunnerPoolRequest 

type CreateRunnerPoolRequest struct {
	Name           string           `json:"name"`
	State          string           `json:"state"`
	Architectures  []string         `json:"architectures"`
	Capabilities   []string         `json:"capabilities"`
	CapacityPolicy map[string]int64 `json:"capacityPolicy"`
}

CreateRunnerPoolRequest declares one operator-owned runner placement boundary.

type CreateSandboxRequest 

type CreateSandboxRequest struct {
	Profile          string            `json:"profile"`
	Metadata         map[string]string `json:"metadata"`
	SourceSnapshotID string            `json:"sourceSnapshotId,omitempty"`
}

CreateSandboxRequest contains a caller-selected Profile, bounded metadata, and an optional retained Snapshot used to seed generation one.

type CreateSnapshotRequest 

type CreateSnapshotRequest struct {
	Name     string            `json:"name"`
	Metadata map[string]string `json:"metadata"`
}

CreateSnapshotRequest names one immutable projection of the current committed disk state.

type CreateTerminalRequest 

type CreateTerminalRequest struct {
	Command              ExecCommand       `json:"command"`
	Cwd                  *string           `json:"cwd,omitempty"`
	Environment          map[string]string `json:"environment"`
	Rows                 int64             `json:"rows"`
	Columns              int64             `json:"columns"`
	DeadlineMilliseconds int64             `json:"deadlineMilliseconds"`
	Detachable           bool              `json:"detachable"`
}

CreateTerminalRequest starts one real PTY under the pinned Profile policy.

type DeploymentTimingSummary 

type DeploymentTimingSummary struct {
	WindowSeconds     int64                    `json:"windowSeconds"`
	ObservedAt        time.Time                `json:"observedAt"`
	Boot              DurationPercentiles      `json:"boot"`
	BootStages        []BootStageTimingSummary `json:"bootStages"`
	DominantBootStage *BootStageTimingSummary  `json:"dominantBootStage,omitempty"`
	Exec              DurationPercentiles      `json:"exec"`
	ExecSeries        []ExecTimingSummary      `json:"execSeries"`
	API               DurationPercentiles      `json:"api"`
	APISeries         []HTTPRouteTimingSummary `json:"apiSeries"`
	Operations        []OperationTimingSummary `json:"operations"`
}

DeploymentTimingSummary is one bounded current-deployment timing projection.

type DirectoryListing 

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

type DurationPercentiles 

type DurationPercentiles struct {
	Count           int64    `json:"count"`
	P50Milliseconds *float64 `json:"p50Milliseconds,omitempty"`
	P95Milliseconds *float64 `json:"p95Milliseconds,omitempty"`
	P99Milliseconds *float64 `json:"p99Milliseconds,omitempty"`
}

DurationPercentiles is one bounded duration distribution.

type ExecCancelled 

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

type ExecCommand 

type ExecCommand struct {
	Mode       string
	Command    string
	Executable string
	Arguments  []string
}

ExecCommand is the frozen shell-or-argv command union.

func (ExecCommand) MarshalJSON 

func (command ExecCommand) MarshalJSON() ([]byte, error)

func (*ExecCommand) UnmarshalJSON 

func (command *ExecCommand) UnmarshalJSON(data []byte) error

type ExecDeadlineExceeded 

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

type ExecDurationMetric 

type ExecDurationMetric struct {
	Mode      string
	Outcome   string
	Histogram MetricDurationHistogram
}

ExecDurationMetric is one bounded Exec mode and outcome series.

type ExecExited 

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

type ExecInfrastructureFailed 

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

type ExecOutput 

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

type ExecOutputExhausted 

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

type ExecSpawnFailed 

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

type ExecStreamSession 

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

ExecStreamSession is the durable public streaming-exec negotiation result.

type ExecTiming 

type ExecTiming struct {
	SessionID           string    `json:"sessionId"`
	Mode                string    `json:"mode"`
	Outcome             string    `json:"outcome"`
	ElapsedMilliseconds int64     `json:"elapsedMilliseconds"`
	CreatedAt           time.Time `json:"createdAt"`
	CompletedAt         time.Time `json:"completedAt"`
}

ExecTiming reports one completed buffered or streaming execution.

type ExecTimingSummary 

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

ExecTimingSummary aggregates one fixed Exec mode and outcome.

type ExecutionPolicy 

type ExecutionPolicy struct {
	MaximumDeadlineMilliseconds int64  `json:"maximumDeadlineMilliseconds"`
	MaximumBufferedOutputBytes  int64  `json:"maximumBufferedOutputBytes"`
	StreamWindowBytes           int64  `json:"streamWindowBytes"`
	MaximumTransferBytes        int64  `json:"maximumTransferBytes"`
	TerminalDetachSeconds       int64  `json:"terminalDetachSeconds"`
	DataPlaneTransport          string `json:"dataPlaneTransport"`
}

ExecutionPolicy bounds exec, transfer, terminal, and port-session resources.

type FileExistsResult 

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

type FileStat 

type FileStat struct {
	Path       string    `json:"path"`
	Kind       string    `json:"kind"`
	SizeBytes  int64     `json:"sizeBytes"`
	ModifiedAt time.Time `json:"modifiedAt"`
}

type FileWriteResult 

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

type HTTPRouteTimingSummary 

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

HTTPRouteTimingSummary aggregates one fixed route-template and status-class series.

type Instance 

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

Instance is replaceable compute evidence without runner or backend authority.

type Lease 

type Lease struct {
	ID         string    `json:"id"`
	TenantRef  string    `json:"-"`
	SubjectRef string    `json:"-"`
	SandboxID  string    `json:"sandboxId"`
	Generation int64     `json:"generation"`
	State      string    `json:"state"`
	ExpiresAt  time.Time `json:"expiresAt"`
	Revision   int64     `json:"-"`
	CreatedAt  time.Time `json:"createdAt"`
	UpdatedAt  time.Time `json:"updatedAt"`
}

Lease is bounded Project authority for one Sandbox generation.

type LifecyclePolicy 

type LifecyclePolicy struct {
	InitialState           string `json:"initialState"`
	DrainGraceSeconds      int64  `json:"drainGraceSeconds"`
	IdleSeconds            int64  `json:"idleSeconds"`
	MaximumDurationSeconds int64  `json:"maximumDurationSeconds"`
	LeaseSeconds           int64  `json:"leaseSeconds"`
}

LifecyclePolicy contains explicit Instance timing and initial-state policy.

type MetricDurationHistogram 

type MetricDurationHistogram struct {
	Count        uint64
	SumSeconds   float64
	BucketCounts []uint64
}

MetricDurationHistogram is one cumulative duration histogram.

type MetricsSnapshot 

type MetricsSnapshot struct {
	SandboxStates      map[string]int64
	OperationStates    map[string]int64
	OperationDurations []OperationDurationMetric
	BootDuration       MetricDurationHistogram
	BootStageDurations []BootStageDurationMetric
	ExecDurations      []ExecDurationMetric
}

MetricsSnapshot contains only fixed-cardinality state, outcome, and timing signals.

type NetworkDestination 

type NetworkDestination struct {
	Protocol string `json:"protocol"`
	Domain   string `json:"domain,omitempty"`
	CIDR     string `json:"cidr,omitempty"`
	Port     int64  `json:"port"`
}

NetworkDestination is one bounded protocol and host or CIDR allowance.

type NetworkPolicy 

type NetworkPolicy struct {
	Mode         string               `json:"mode"`
	Destinations []NetworkDestination `json:"destinations"`
}

NetworkPolicy is an explicit deny-all or destination allow-list.

type Operation 

type Operation struct {
	ID              string            `json:"id"`
	TenantRef       string            `json:"-"`
	SubjectRef      string            `json:"-"`
	SandboxID       string            `json:"sandboxId"`
	Kind            string            `json:"kind"`
	State           string            `json:"state"`
	RequestID       string            `json:"requestId"`
	RequestMetadata map[string]string `json:"-"`
	Sandbox         *Sandbox          `json:"sandbox,omitempty"`
	Snapshot        *Snapshot         `json:"snapshot,omitempty"`
	Error           *Problem          `json:"error,omitempty"`
	CreatedAt       time.Time         `json:"createdAt"`
	StartedAt       *time.Time        `json:"startedAt,omitempty"`
	CompletedAt     *time.Time        `json:"completedAt,omitempty"`
	UpdatedAt       time.Time         `json:"updatedAt"`
}

Operation is durable asynchronous mutation evidence.

type OperationDurationMetric 

type OperationDurationMetric struct {
	Kind          string
	TerminalState string
	Histogram     MetricDurationHistogram
}

OperationDurationMetric is one bounded Operation kind and terminal-state series.

type OperationStageTiming 

type OperationStageTiming struct {
	Stage                  string    `json:"stage"`
	ObservedAt             time.Time `json:"observedAt"`
	ElapsedMilliseconds    float64   `json:"elapsedMilliseconds"`
	CumulativeMilliseconds float64   `json:"cumulativeMilliseconds"`
}

OperationStageTiming attributes one provider-neutral orchestration milestone.

type OperationTiming 

type OperationTiming struct {
	OperationID           string                 `json:"operationId"`
	SandboxID             string                 `json:"sandboxId"`
	Kind                  string                 `json:"kind"`
	State                 string                 `json:"state"`
	CreatedAt             time.Time              `json:"createdAt"`
	StartedAt             *time.Time             `json:"startedAt,omitempty"`
	CompletedAt           *time.Time             `json:"completedAt,omitempty"`
	QueueMilliseconds     *int64                 `json:"queueMilliseconds,omitempty"`
	ExecutionMilliseconds *int64                 `json:"executionMilliseconds,omitempty"`
	TotalMilliseconds     *int64                 `json:"totalMilliseconds,omitempty"`
	Orchestration         []OperationStageTiming `json:"orchestration"`
	Boots                 []BootTiming           `json:"boots"`
}

OperationTiming separates durable queue and execution time.

type OperationTimingSummary 

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

OperationTimingSummary aggregates one fixed Operation kind and terminal state.

type PingResult 

type PingResult struct {
	SandboxID  string    `json:"sandboxId"`
	Generation int64     `json:"generation"`
	Healthy    bool      `json:"healthy"`
	ObservedAt time.Time `json:"observedAt"`
}

PingResult reports guest health without renewing useful activity.

type PortPolicy 

type PortPolicy struct {
	Name                  string `json:"name"`
	Port                  int64  `json:"port"`
	Protocol              string `json:"protocol"`
	MaximumSessions       int64  `json:"maximumSessions"`
	MaximumSessionSeconds int64  `json:"maximumSessionSeconds"`
}

PortPolicy is one profile-approved guest port and session bound.

type PortSession 

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

PortSession is an authenticated, expiring control-plane tunnel.

type Principal 

type Principal struct {
	Kind       string `json:"kind"`
	ID         string `json:"id"`
	TenantRef  string `json:"tenantRef,omitempty"`
	SubjectRef string `json:"subjectRef,omitempty"`
}

Principal is the platform-asserted ownership scope for one request.

type Problem 

type Problem struct {
	Type                   string          `json:"type"`
	Title                  string          `json:"title"`
	Status                 int             `json:"status"`
	Code                   string          `json:"code"`
	RequestID              string          `json:"requestId"`
	Retryable              bool            `json:"retryable"`
	RetryAfterMilliseconds *int64          `json:"retryAfterMilliseconds,omitempty"`
	Details                []ProblemDetail `json:"details,omitempty"`
}

Problem is the stable typed failure envelope.

type ProblemDetail 

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

ProblemDetail identifies one bounded invalid field.

type Profile 

type Profile struct {
	Name            string            `json:"name"`
	State           string            `json:"state"`
	CurrentRevision ProfileRevision   `json:"currentRevision"`
	Revisions       []ProfileRevision `json:"revisions"`
	Revision        int64             `json:"revision"`
	CreatedAt       time.Time         `json:"createdAt"`
	UpdatedAt       time.Time         `json:"updatedAt"`
}

Profile is the stable name and mutable head for immutable policy revisions.

type ProfilePage 

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

ProfilePage is one bounded stable Profile traversal page.

type ProfileRevision 

type ProfileRevision struct {
	ID        string              `json:"id"`
	Number    int64               `json:"number"`
	Spec      ProfileRevisionSpec `json:"spec"`
	CreatedAt time.Time           `json:"createdAt"`
}

ProfileRevision is immutable policy selected by future Sandbox creation.

type ProfileRevisionSpec 

type ProfileRevisionSpec struct {
	Pool                  string          `json:"pool"`
	Architecture          string          `json:"architecture"`
	RuntimeBundleDigest   string          `json:"runtimeBundleDigest"`
	ToolchainBundleDigest string          `json:"toolchainBundleDigest"`
	Resources             ResourcePolicy  `json:"resources"`
	Lifecycle             LifecyclePolicy `json:"lifecycle"`
	Retention             RetentionPolicy `json:"retention"`
	Execution             ExecutionPolicy `json:"execution"`
	Network               NetworkPolicy   `json:"network"`
	Ports                 []PortPolicy    `json:"ports"`
}

ProfileRevisionSpec resolves every execution, durability, and placement bound.

type QuotaLimits 

type QuotaLimits struct {
	MaxSandboxes            int64 `json:"maxSandboxes"`
	MaxActiveInstances      int64 `json:"maxActiveInstances"`
	MaxCPUMillis            int64 `json:"maxCpuMillis"`
	MaxMemoryBytes          int64 `json:"maxMemoryBytes"`
	MaxArtifactBytes        int64 `json:"maxArtifactBytes"`
	MaxSnapshots            int64 `json:"maxSnapshots"`
	MaxArtifacts            int64 `json:"maxArtifacts"`
	MaxPortSessions         int64 `json:"maxPortSessions"`
	MaxConcurrentOperations int64 `json:"maxConcurrentOperations"`
}

QuotaLimits bounds one subject's aggregate reservations.

type QuotaUsage 

type QuotaUsage struct {
	Sandboxes            int64 `json:"sandboxes"`
	ActiveInstances      int64 `json:"activeInstances"`
	CPUMillis            int64 `json:"cpuMillis"`
	MemoryBytes          int64 `json:"memoryBytes"`
	ArtifactBytes        int64 `json:"artifactBytes"`
	Snapshots            int64 `json:"snapshots"`
	Artifacts            int64 `json:"artifacts"`
	PortSessions         int64 `json:"portSessions"`
	ConcurrentOperations int64 `json:"concurrentOperations"`
}

QuotaUsage projects one subject's aggregate persisted reservations.

type RelocateSandboxRequest 

type RelocateSandboxRequest struct {
	TargetRunnerID string `json:"targetRunnerId,omitempty"`
	RunnerPool     string `json:"runnerPool,omitempty"`
}

RelocateSandboxRequest selects one compatible target Runner explicitly or by pool.

type RemovePathRequest 

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

type RenewLeaseRequest 

type RenewLeaseRequest struct {
	DurationSeconds int64 `json:"durationSeconds"`
}

RenewLeaseRequest selects a new bounded duration for active Lease authority.

type ResourcePolicy 

type ResourcePolicy struct {
	CPUMillis            int64 `json:"cpuMillis"`
	MemoryBytes          int64 `json:"memoryBytes"`
	WorkspaceBytes       int64 `json:"workspaceBytes"`
	ProcessLimit         int64 `json:"processLimit"`
	ConcurrentOperations int64 `json:"concurrentOperations"`
}

ResourcePolicy contains per-Sandbox enforceable compute and workspace limits.

type RestoreSnapshotRequest 

type RestoreSnapshotRequest struct {
	SnapshotID string `json:"snapshotId"`
}

RestoreSnapshotRequest selects one Snapshot owned by the stopped Sandbox.

type RetentionPolicy 

type RetentionPolicy struct {
	SnapshotLimit            int64 `json:"snapshotLimit"`
	SnapshotRetentionSeconds int64 `json:"snapshotRetentionSeconds"`
	ArtifactRetentionSeconds int64 `json:"artifactRetentionSeconds"`
}

RetentionPolicy bounds local Snapshot count/lifetime and Artifact retention.

type ReviseProfileRequest 

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

ReviseProfileRequest appends an immutable Profile revision.

type Runner 

type Runner struct {
	ID                          string           `json:"id"`
	PoolName                    string           `json:"poolName"`
	Name                        string           `json:"name"`
	State                       string           `json:"state"`
	CredentialState             string           `json:"credentialState"`
	Architectures               []string         `json:"architectures"`
	Capabilities                []string         `json:"capabilities"`
	Capacity                    map[string]int64 `json:"capacity"`
	ProtocolVersions            []string         `json:"protocolVersions"`
	SandboxStartSampleCount     int64            `json:"sandboxStartSampleCount"`
	SandboxStartP95Milliseconds int64            `json:"sandboxStartP95Milliseconds"`
	LastSeenAt                  *time.Time       `json:"lastSeenAt,omitempty"`
	Revision                    int64            `json:"revision"`
	CreatedAt                   time.Time        `json:"createdAt"`
	UpdatedAt                   time.Time        `json:"updatedAt"`
}

Runner is enrolled execution identity and fixed-capacity evidence.

type RunnerPage 

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

RunnerPage is one bounded stable administrative Runner traversal page.

type RunnerPool 

type RunnerPool struct {
	Name             string           `json:"name"`
	State            string           `json:"state"`
	Architectures    []string         `json:"architectures"`
	Capabilities     []string         `json:"capabilities"`
	CapacityPolicy   map[string]int64 `json:"capacityPolicy"`
	ReadyRunnerCount int64            `json:"readyRunnerCount"`
	Revision         int64            `json:"revision"`
	CreatedAt        time.Time        `json:"createdAt"`
	UpdatedAt        time.Time        `json:"updatedAt"`
}

RunnerPool is the operator-owned placement and trust boundary.

type RunnerPoolPage 

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

RunnerPoolPage is one bounded stable administrative placement traversal page.

type Sandbox 

type Sandbox struct {
	ID                string            `json:"id"`
	TenantRef         string            `json:"-"`
	SubjectRef        string            `json:"-"`
	Profile           string            `json:"profile"`
	ProfileRevisionID string            `json:"profileRevisionId"`
	State             string            `json:"state"`
	DesiredState      string            `json:"desiredState"`
	Generation        int64             `json:"generation"`
	Workspace         Workspace         `json:"workspace"`
	Instance          *Instance         `json:"instance,omitempty"`
	Metadata          map[string]string `json:"metadata"`
	LastActivityAt    *time.Time        `json:"lastActivityAt,omitempty"`
	Revision          int64             `json:"revision"`
	CreatedAt         time.Time         `json:"createdAt"`
	UpdatedAt         time.Time         `json:"updatedAt"`
	DeletedAt         *time.Time        `json:"deletedAt,omitempty"`
}

Sandbox is durable Project intent pinned to one immutable ProfileRevision.

type SandboxInspection 

type SandboxInspection struct {
	SandboxID      string    `json:"sandboxId"`
	Generation     int64     `json:"generation"`
	GuestHealthy   bool      `json:"guestHealthy"`
	ActiveSessions int64     `json:"activeSessions"`
	ObservedAt     time.Time `json:"observedAt"`
}

SandboxInspection is persisted guest and useful-session evidence.

type SandboxPage 

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

SandboxPage is one bounded stable Project Sandbox traversal page.

type SandboxTiming 

type SandboxTiming struct {
	SandboxID  string            `json:"sandboxId"`
	Operations []OperationTiming `json:"operations"`
	Execs      []ExecTiming      `json:"execs"`
}

SandboxTiming is a bounded per-Sandbox timing history.

type Snapshot 

type Snapshot struct {
	ID                 string            `json:"id"`
	TenantRef          string            `json:"-"`
	SubjectRef         string            `json:"-"`
	SandboxID          string            `json:"sandboxId"`
	WorkspaceID        string            `json:"-"`
	SourceGeneration   int64             `json:"generation"`
	Name               string            `json:"name"`
	SizeBytes          int64             `json:"sizeBytes"`
	State              string            `json:"state"`
	Metadata           map[string]string `json:"metadata"`
	RetainUntil        *time.Time        `json:"expiresAt,omitempty"`
	CreatedAt          time.Time         `json:"createdAt"`
	RetentionEndedAt   *time.Time        `json:"-"`
	GarbageCollectedAt *time.Time        `json:"-"`
}

Snapshot is one immutable runner-local projection of a committed Workspace.

type SnapshotPage 

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

SnapshotPage is one bounded, newest-first retained Snapshot page.

type StreamCancelFrame 

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

type StreamCreditFrame 

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

type StreamInputFrame 

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

type StreamOutcomeFrame 

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

type StreamOutputFrame 

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

type StreamingExecRequest 

type StreamingExecRequest struct {
	Command              ExecCommand       `json:"command"`
	Cwd                  *string           `json:"cwd,omitempty"`
	Environment          map[string]string `json:"environment"`
	DeadlineMilliseconds int64             `json:"deadlineMilliseconds"`
	MaximumOutputBytes   int64             `json:"maximumOutputBytes"`
	WindowBytes          int64             `json:"windowBytes"`
}

StreamingExecRequest starts one non-PTY command controlled by WebSocket frames.

type SubjectUsage 

type SubjectUsage struct {
	TenantRef  string      `json:"tenantRef"`
	SubjectRef string      `json:"subjectRef"`
	Limits     QuotaLimits `json:"limits"`
	Usage      QuotaUsage  `json:"usage"`
}

SubjectUsage reports one trusted caller subject's limits and current usage.

type TerminalInputFrame 

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

type TerminalOutputFrame 

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

type TerminalResizeFrame 

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

type TerminalSession 

type TerminalSession struct {
	ID           string `json:"id"`
	SandboxID    string `json:"sandboxId"`
	Generation   int64  `json:"generation"`
	State        string `json:"state"`
	WebsocketURL string `json:"websocketUrl"`
	Subprotocol  string `json:"subprotocol"`
	// StreamWindowBytes is the pinned ProfileRevision bound on outstanding
	// output credit. A client cannot grant more than this, so it is published
	// rather than left for the client to guess.
	StreamWindowBytes  int64     `json:"streamWindowBytes"`
	NextClientSequence int64     `json:"nextClientSequence"`
	ExpiresAt          time.Time `json:"expiresAt"`
}

TerminalSession is the durable public terminal negotiation result.

type TouchResult 

type TouchResult struct {
	SandboxID      string    `json:"sandboxId"`
	Generation     int64     `json:"generation"`
	LastActivityAt time.Time `json:"lastActivityAt"`
}

TouchResult reports the durable useful-activity timestamp.

type UpdateRunnerPoolRequest 

type UpdateRunnerPoolRequest struct {
	State          *string           `json:"state,omitempty"`
	Architectures  *[]string         `json:"architectures,omitempty"`
	Capabilities   *[]string         `json:"capabilities,omitempty"`
	CapacityPolicy *map[string]int64 `json:"capacityPolicy,omitempty"`
}

UpdateRunnerPoolRequest changes explicit runner admission policy under revision control.

type UpdateSandboxMetadataRequest 

type UpdateSandboxMetadataRequest struct {
	Metadata map[string]string `json:"metadata"`
}

UpdateSandboxMetadataRequest replaces bounded application correlation metadata.

type WaitSandboxRequest 

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

WaitSandboxRequest bounds lifecycle observation without renewing activity.

type Workspace 

type Workspace struct {
	ID         string    `json:"id"`
	TenantRef  string    `json:"-"`
	SubjectRef string    `json:"-"`
	Generation int64     `json:"generation"`
	State      string    `json:"state"`
	SizeBytes  int64     `json:"sizeBytes"`
	CreatedAt  time.Time `json:"createdAt"`
	UpdatedAt  time.Time `json:"updatedAt"`
}

Workspace is public retained-workspace evidence without a provider location.

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.