contracts

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: 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"

	// StartupModeColdBoot starts every Instance by booting its guest.
	StartupModeColdBoot = "cold_boot"
	// StartupModeSnapshotResume starts every Instance by resuming a prepared,
	// identity-neutral guest. It has no cold-boot fallback and admits only onto
	// Runners advertising RunnerCapabilitySnapshotResume.
	StartupModeSnapshotResume = "snapshot_resume"

	// RunnerCapabilitySnapshotResume is advertised by a Runner that can start a
	// Sandbox by resuming a prepared guest: it is configured with a template
	// cache root and holds an admitted template built from the exact signed
	// bundle the Runner itself verified.
	RunnerCapabilitySnapshotResume = "snapshot-resume"

	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"

	// PortTransportProxied proxies Port bytes through the control plane without
	// persisting payloads. It is the only transport an ordinary caller receives.
	PortTransportProxied = "proxied"
	// 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"

	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"
)
View Source 
const (
	AuthorityKindPlatform         = "platform"
	AuthorityKindTenantController = "tenant_controller"
	AuthorityKindApplication      = "application"

	AuthorityStateActive  = "active"
	AuthorityStateExpired = "expired"
	AuthorityStateRevoked = "revoked"

	TenantStateActive    = "active"
	TenantStateSuspended = "suspended"
	TenantStateExpired   = "expired"

	SubjectStateActive  = "active"
	SubjectStateClosing = "closing"
	SubjectStateClosed  = "closed"
	SubjectStateExpired = "expired"

	SubjectCleanupStateNone      = "none"
	SubjectCleanupStatePending   = "pending"
	SubjectCleanupStateRunning   = "running"
	SubjectCleanupStateSucceeded = "succeeded"
	SubjectCleanupStateFailed    = "failed"

	TenantControllerGrantManagement = "tenant_management"
)

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

type ApplicationAuthority struct {
	ID            string            `json:"id"`
	LookupID      string            `json:"lookupId"`
	Kind          string            `json:"kind"`
	TenantRef     string            `json:"tenantRef"`
	SubjectRef    string            `json:"subjectRef"`
	State         string            `json:"state"`
	Scopes        []string          `json:"scopes"`
	ProfileGrants []string          `json:"profileGrants"`
	Metadata      map[string]string `json:"metadata"`
	ExpiresAt     *time.Time        `json:"expiresAt,omitempty"`
	Revision      int64             `json:"revision"`
	CreatedAt     time.Time         `json:"createdAt"`
	UpdatedAt     time.Time         `json:"updatedAt"`
}

ApplicationAuthority is the non-secret projection of one application credential.

type ApplicationAuthorityPage added in v0.6.0 

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

ApplicationAuthorityPage is one bounded stable application-authority traversal page.

type ApplicationCredentialResponse added in v0.6.0 

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

ApplicationCredentialResponse carries bearer material only on successful creation or rotation.

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

type CreateApplicationAuthorityRequest struct {
	SubjectRef    string            `json:"subjectRef"`
	Scopes        []string          `json:"scopes"`
	ProfileGrants []string          `json:"profileGrants"`
	Metadata      map[string]string `json:"metadata"`
	ExpiresAt     time.Time         `json:"expiresAt"`
}

CreateApplicationAuthorityRequest supplies a subject-bound application grant.

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

type CreateSubjectRequest struct {
	Ref       string            `json:"ref"`
	Quota     QuotaLimits       `json:"quota"`
	Metadata  map[string]string `json:"metadata"`
	ExpiresAt *time.Time        `json:"expiresAt,omitempty"`
}

CreateSubjectRequest supplies one tenant-scoped subject and its quota.

type CreateTenantControllerAuthorityRequest added in v0.6.0 

type CreateTenantControllerAuthorityRequest struct {
	Metadata  map[string]string `json:"metadata"`
	ExpiresAt time.Time         `json:"expiresAt"`
}

CreateTenantControllerAuthorityRequest supplies bounded non-secret controller attributes.

type CreateTenantRequest added in v0.6.0 

type CreateTenantRequest struct {
	Ref                      string             `json:"ref"`
	AllowedProfileGrants     []string           `json:"allowedProfileGrants"`
	AllowedApplicationScopes []string           `json:"allowedApplicationScopes"`
	AggregateQuota           TenantQuota        `json:"aggregateQuota"`
	ExpiryPolicy             TenantExpiryPolicy `json:"expiryPolicy"`
	Metadata                 map[string]string  `json:"metadata"`
	ExpiresAt                *time.Time         `json:"expiresAt,omitempty"`
}

CreateTenantRequest supplies the complete operator-owned Tenant boundary.

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

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

DeploymentUsage reports deployment-wide reservations and one Tenant page.

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
	LiveDataPlaneDroppedRouteNotFoundFrames uint64
}

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,omitempty"`
	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"`
	Startup               StartupPolicy   `json:"startup"`
	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"`
	MaxVCPUCount            int64 `json:"maxVcpuCount"`
	MaxMemoryBytes          int64 `json:"maxMemoryBytes"`
	MaxSnapshots            int64 `json:"maxSnapshots"`
	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"`
	VCPUCount            int64 `json:"vcpuCount"`
	MemoryBytes          int64 `json:"memoryBytes"`
	Snapshots            int64 `json:"snapshots"`
	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 {
	VCPUCount            int64 `json:"vcpuCount"`
	MemoryBytes          int64 `json:"memoryBytes"`
	WorkspaceBytes       int64 `json:"workspaceBytes"`
	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"`
}

RetentionPolicy bounds local Snapshot count and lifetime.

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 StartupPolicy added in v0.3.0 

type StartupPolicy struct {
	Mode string `json:"mode"`
}

StartupPolicy states how an Instance of a Profile revision reaches ready. There is no application default: an operator states the mode on every Profile revision, and the mode is pinned by the immutable revision a Sandbox resolves at creation.

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

type Subject struct {
	TenantRef    string            `json:"tenantRef"`
	Ref          string            `json:"ref"`
	State        string            `json:"state"`
	CleanupState string            `json:"cleanupState"`
	Quota        QuotaLimits       `json:"quota"`
	Metadata     map[string]string `json:"metadata"`
	ExpiresAt    *time.Time        `json:"expiresAt,omitempty"`
	Revision     int64             `json:"revision"`
	CreatedAt    time.Time         `json:"createdAt"`
	UpdatedAt    time.Time         `json:"updatedAt"`
}

Subject is one tenant-scoped application ownership identity.

type SubjectPage added in v0.6.0 

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

SubjectPage is one bounded stable tenant-scoped Subject traversal page.

type SubjectUsage 

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

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

type Tenant added in v0.6.0 

type Tenant struct {
	Ref                      string             `json:"ref"`
	State                    string             `json:"state"`
	AllowedProfileGrants     []string           `json:"allowedProfileGrants"`
	AllowedApplicationScopes []string           `json:"allowedApplicationScopes"`
	AggregateQuota           TenantQuota        `json:"aggregateQuota"`
	ExpiryPolicy             TenantExpiryPolicy `json:"expiryPolicy"`
	Metadata                 map[string]string  `json:"metadata"`
	ExpiresAt                *time.Time         `json:"expiresAt,omitempty"`
	Revision                 int64              `json:"revision"`
	CreatedAt                time.Time          `json:"createdAt"`
	UpdatedAt                time.Time          `json:"updatedAt"`
}

Tenant is one stable management and aggregate-admission boundary.

type TenantAggregateUsage added in v0.6.0 

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

TenantAggregateUsage reports aggregate reservations for one tenant.

type TenantControllerAuthority added in v0.6.0 

type TenantControllerAuthority struct {
	ID        string            `json:"id"`
	LookupID  string            `json:"lookupId"`
	Kind      string            `json:"kind"`
	TenantRef string            `json:"tenantRef"`
	Grant     string            `json:"grant"`
	State     string            `json:"state"`
	Metadata  map[string]string `json:"metadata"`
	ExpiresAt *time.Time        `json:"expiresAt,omitempty"`
	Revision  int64             `json:"revision"`
	CreatedAt time.Time         `json:"createdAt"`
	UpdatedAt time.Time         `json:"updatedAt"`
}

TenantControllerAuthority is the non-secret projection of one tenant controller.

type TenantControllerAuthorityPage added in v0.6.0 

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

TenantControllerAuthorityPage is one bounded stable controller traversal page.

type TenantControllerCredentialResponse added in v0.6.0 

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

TenantControllerCredentialResponse carries bearer material only on successful creation or rotation.

type TenantExpiryPolicy added in v0.6.0 

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

TenantExpiryPolicy bounds tenant-local subject and authority lifetimes.

type TenantPage added in v0.6.0 

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

TenantPage is one bounded stable Tenant traversal page.

type TenantQuota added in v0.6.0 

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

TenantQuota bounds aggregate tenant reservations and management resources.

type TenantQuotaUsage added in v0.6.0 

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

TenantQuotaUsage projects one tenant's aggregate persisted reservations.

type TenantUsage added in v0.6.0 

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

TenantUsage reports aggregate and per-Subject reservations for one tenant.

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

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

UpdateSubjectQuotaRequest replaces one Subject's complete quota set.

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.