contracts

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2026 License: MIT Imports: 10 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 (
	// EgressContextNameMaximumLength bounds an opaque operator-selected egress
	// routing context everywhere it is stored, transported, audited, or shown.
	EgressContextNameMaximumLength = 63
	// EgressContextNamePattern is the canonical ASCII syntax shared by HTTP,
	// persistence, Runner configuration and protocol, audit, and diagnostics.
	EgressContextNamePattern = `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$`
	// RunnerEgressContextSetMaximumSize bounds one registration snapshot.
	RunnerEgressContextSetMaximumSize = 64
)
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"
)
View Source 
const MaximumPolicyLimit int64 = 1<<53 - 1

Policy integers remain exact in every supported JSON SDK.

View Source 
const (
	RunnerCapabilityClientSelectedImage = "client-selected-image"
)
View Source 
const RunnerCapabilityPerExecAttribution = "per-exec-attribution"

RunnerCapabilityPerExecAttribution is advertised by a Runner with configured attributed gateway routing. Ordinary generations on it admit attributed execs.

View Source 
const RunnerCapabilityPhysicalStorageAdmission = "physical-storage-admission"

RunnerCapabilityPhysicalStorageAdmission indicates that the Runner admits Workspace creation and starts against measured filesystem pressure without charging the full logical capacity of each Workspace.

Variables

This section is empty.

Functions

func ExecutionImageDigestReference added in v0.15.0 

func ExecutionImageDigestReference(reference, digest string) string

func ValidateEgressContextName added in v0.8.0 

func ValidateEgressContextName(name string) error

ValidateEgressContextName validates one provider-neutral opaque context name. The name is an identifier only; it does not encode a hostname, address, CIDR, Tenant reference, gateway identity, or gateway mapping digest.

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 AttributedExecutionConnectionLimits added in v0.17.0 

type AttributedExecutionConnectionLimits struct {
	MaximumConnections int64 `json:"maximumConnections"`
}

AttributedExecutionConnectionLimits contains no routing or execution authority.

func (*AttributedExecutionConnectionLimits) UnmarshalJSON added in v0.17.0 

func (limits *AttributedExecutionConnectionLimits) UnmarshalJSON(data []byte) error

func (AttributedExecutionConnectionLimits) Validate added in v0.17.0 

func (limits AttributedExecutionConnectionLimits) Validate() error

type AttributedExecutionConnectionObservation added in v0.17.0 

type AttributedExecutionConnectionObservation struct {
	DefaultMaximumConnections int64 `json:"defaultMaximumConnections"`
	MaximumConnections        int64 `json:"maximumConnections"`
	MaximumConnectionsCeiling int64 `json:"maximumConnectionsCeiling"`
}

func (AttributedExecutionConnectionObservation) Resolve added in v0.17.0 

func (grant AttributedExecutionConnectionObservation) Resolve(selection *AttributedExecutionConnectionLimits) (AttributedExecutionConnectionObservation, error)

Resolve applies the same selection rule to current-head and pinned grants. A stored selection survives operator tightening; only the effective value clamps.

type AttributedExecutionPolicy added in v0.10.0 

type AttributedExecutionPolicy struct {
	Gateway            string `json:"gateway"`
	MaximumConnections int64  `json:"maximumConnections"`
}

AttributedExecutionPolicy lets execs in ordinary generations of the Profile request attribution through a Runner-owned forwarder to the named gateway. It adds no ordinary destination; each attributed exec gets its own listener.

type AttributedExecutionRequest added in v0.10.0 

type AttributedExecutionRequest struct {
	AuthorizationRef string    `json:"authorizationRef"`
	ExpiresAt        time.Time `json:"expiresAt"`
}

AttributedExecutionRequest binds one exec to application correlation and an absolute authority expiry. Neither field selects credentials.

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"`
	AttributedExecution  *AttributedExecutionRequest `json:"attributedExecution,omitempty"`
}

BufferedExecRequest is one bounded non-PTY execution.

func (*BufferedExecRequest) UnmarshalJSON added in v0.21.0 

func (request *BufferedExecRequest) UnmarshalJSON(data []byte) error

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"`
}

CreateRunnerPoolRequest declares one operator-owned runner placement boundary.

type CreateSandboxRequest 

type CreateSandboxRequest struct {
	Resources        *SandboxResourceRequest `json:"resources,omitempty"`
	Image            ExecutionImage          `json:"image,omitzero"`
	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.

func (*CreateSubjectRequest) UnmarshalJSON added in v0.13.0 

func (request *CreateSubjectRequest) UnmarshalJSON(data []byte) error

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"`
	EgressContext            *string            `json:"egressContext,omitempty"`
	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.

func (*CreateTenantRequest) UnmarshalJSON added in v0.13.0 

func (request *CreateTenantRequest) UnmarshalJSON(data []byte) error

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 EgressContextAssignmentGroup added in v0.8.0 

type EgressContextAssignmentGroup struct {
	EgressContext *string `json:"egressContext"`
	RunnerID      string  `json:"runnerId"`
	State         string  `json:"state"`
	Count         int64   `json:"count"`
}

type EgressContextPreflight added in v0.8.0 

type EgressContextPreflight struct {
	Ready             bool                           `json:"ready"`
	Truncated         bool                           `json:"truncated"`
	Requirements      []EgressContextRequirement     `json:"requirements"`
	Runners           []EgressContextRunner          `json:"runners"`
	ActiveAssignments []EgressContextAssignmentGroup `json:"activeAssignments"`
}

EgressContextPreflight is a read-only operator view of required context placement and active assignment impact.

type EgressContextRequirement added in v0.8.0 

type EgressContextRequirement struct {
	TenantRef           string   `json:"tenantRef"`
	ProfileName         string   `json:"profileName"`
	ProfileRevisionID   string   `json:"profileRevisionId"`
	PoolName            string   `json:"poolName"`
	EgressContext       *string  `json:"egressContext"`
	CompatibleRunnerIDs []string `json:"compatibleRunnerIds"`
	Status              string   `json:"status"`
}

type EgressContextRunner added in v0.8.0 

type EgressContextRunner struct {
	RunnerID           string   `json:"runnerId"`
	PoolName           string   `json:"poolName"`
	State              string   `json:"state"`
	Connected          bool     `json:"connected"`
	AdvertisedContexts []string `json:"advertisedContexts"`
}

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 ExecutionImage added in v0.15.0 

type ExecutionImage struct {
	Reference string `json:"reference"`
}

ExecutionImage selects one signed OCI execution bundle for a lifecycle operation.

func (ExecutionImage) LifecycleMetadata added in v0.15.0 

func (image ExecutionImage) LifecycleMetadata() map[string]string

func (*ExecutionImage) UnmarshalJSON added in v0.15.0 

func (image *ExecutionImage) UnmarshalJSON(data []byte) error

func (ExecutionImage) Validate added in v0.15.0 

func (image ExecutionImage) Validate() error

type ExecutionPolicy 

type ExecutionPolicy struct {
	MaximumDeadlineMilliseconds PolicyLimit `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 ExtendApplicationAuthorityRequest added in v0.20.0 

type ExtendApplicationAuthorityRequest struct {
	ProfileGrants []string `json:"profileGrants"`
	Scopes        []string `json:"scopes"`
}

ExtendApplicationAuthorityRequest adds Profile grants and scopes within the Tenant ceiling.

type ExtendTenantCeilingRequest added in v0.20.0 

type ExtendTenantCeilingRequest struct {
	ProfileGrants     []string `json:"profileGrants"`
	ApplicationScopes []string `json:"applicationScopes"`
}

ExtendTenantCeilingRequest adds Profile grants and application scopes to one Tenant ceiling.

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 ImagePreparation added in v0.15.0 

type ImagePreparation struct {
	Image           PublicExecutionImage `json:"image"`
	TargetRunners   int                  `json:"targetRunners"`
	PreparedRunners int                  `json:"preparedRunners"`
}

type Instance 

type Instance struct {
	GuestFeatures     []string             `json:"guestFeatures,omitempty"`
	Image             PublicExecutionImage `json:"image"`
	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            PolicyLimit `json:"idleSeconds"`
	MaximumDurationSeconds PolicyLimit `json:"maximumDurationSeconds"`
	LeaseSeconds           int64       `json:"leaseSeconds"`
}

LifecyclePolicy contains explicit Instance timing and initial-state policy.

func (*LifecyclePolicy) UnmarshalJSON added in v0.13.0 

func (policy *LifecyclePolicy) UnmarshalJSON(data []byte) error

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"`
	RequiresTenantEgressContext *bool                `json:"requiresTenantEgressContext"`
}

NetworkPolicy is an explicit deny-all or destination allow-list and states whether its immutable Profile revision requires the creating Tenant's pinned egress context. The pointer distinguishes explicit false from an omitted field; Profile validation rejects nil rather than supplying a default.

type Operation 

type Operation struct {
	ImagePreparation *ImagePreparation `json:"imagePreparation,omitempty"`
	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 PolicyLimit added in v0.13.0 

type PolicyLimit int64

PolicyLimit is a finite nonnegative ceiling or Unlimited. Its wire and SQL representation for Unlimited is null; zero remains a finite ceiling. 

const Unlimited PolicyLimit = -1

func MinimumPolicyLimit added in v0.13.0 

func MinimumPolicyLimit(left, right PolicyLimit) PolicyLimit

func (PolicyLimit) Allows added in v0.13.0 

func (limit PolicyLimit) Allows(value int64) bool

func (PolicyLimit) IsUnlimited added in v0.13.0 

func (limit PolicyLimit) IsUnlimited() bool

func (PolicyLimit) MarshalJSON added in v0.13.0 

func (limit PolicyLimit) MarshalJSON() ([]byte, error)

func (PolicyLimit) Remaining added in v0.13.0 

func (limit PolicyLimit) Remaining(used int64) PolicyLimit

func (*PolicyLimit) Scan added in v0.13.0 

func (limit *PolicyLimit) Scan(value any) error

func (*PolicyLimit) UnmarshalJSON added in v0.13.0 

func (limit *PolicyLimit) UnmarshalJSON(data []byte) error

func (PolicyLimit) Valid added in v0.13.0 

func (limit PolicyLimit) Valid(minimum int64) bool

func (PolicyLimit) Value added in v0.13.0 

func (limit PolicyLimit) Value() (driver.Value, error)

func (PolicyLimit) Within added in v0.13.0 

func (limit PolicyLimit) Within(parent PolicyLimit) bool

type PortPolicy 

type PortPolicy struct {
	Name                  string      `json:"name"`
	Port                  int64       `json:"port"`
	Protocol              string      `json:"protocol"`
	MaximumSessions       PolicyLimit `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 PositivePolicyLimit added in v0.13.0 

type PositivePolicyLimit = PolicyLimit

type PrepareImageRequest added in v0.15.0 

type PrepareImageRequest struct {
	Image   ExecutionImage `json:"image"`
	Profile string         `json:"profile,omitempty"`
}

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 {
	Ceiling                *SandboxResourceRequest `json:"ceiling,omitempty"`
	Requested              *SandboxResources       `json:"requested,omitempty"`
	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 ProfileResourceCeiling added in v0.11.0 

type ProfileResourceCeiling map[string]*int64

ProfileResourceCeiling preserves axis presence independently of null (unbounded). A present ceiling must name exactly vcpuCount, memoryBytes, and workspaceBytes.

func (*ProfileResourceCeiling) UnmarshalJSON added in v0.11.0 

func (ceiling *ProfileResourceCeiling) UnmarshalJSON(data []byte) error

UnmarshalJSON keeps an explicit null object from becoming an absent ceiling. Axis presence and bounds are validated when the revision is published.

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"`
	Resources           ResourcePolicy             `json:"resources"`
	ResourceCeiling     ProfileResourceCeiling     `json:"resourceCeiling,omitzero"`
	Startup             StartupPolicy              `json:"startup"`
	LifecycleCeiling    *SandboxLifecycleLimits    `json:"lifecycleCeiling,omitempty"`
	Lifecycle           LifecyclePolicy            `json:"lifecycle"`
	Retention           RetentionPolicy            `json:"retention"`
	Execution           ExecutionPolicy            `json:"execution"`
	Network             NetworkPolicy              `json:"network"`
	Ports               []PortPolicy               `json:"ports"`
	AttributedExecution *AttributedExecutionPolicy `json:"attributedExecution,omitempty"`
	// Zero represents omission; field decoding rejects explicit zero and null.
	AttributedExecutionCeiling AttributedExecutionConnectionLimits `json:"attributedExecutionCeiling,omitzero"`
}

ProfileRevisionSpec resolves every execution, durability, and placement bound.

func (ProfileRevisionSpec) AttributedConnectionGrant added in v0.17.0 

func (spec ProfileRevisionSpec) AttributedConnectionGrant() (*AttributedExecutionConnectionObservation, error)

AttributedConnectionGrant returns the numeric grant without exposing gateway authority. A missing ceiling restricts selection to this revision's default.

func (ProfileRevisionSpec) LifecycleCeilings added in v0.13.0 

func (spec ProfileRevisionSpec) LifecycleCeilings() SandboxLifecycleLimits

func (ProfileRevisionSpec) ResolveLifecycle added in v0.13.0 

func (spec ProfileRevisionSpec) ResolveLifecycle(selection *SandboxLifecycleLimits) (LifecyclePolicy, error)

func (ProfileRevisionSpec) ValidateLifecycleSelection added in v0.13.0 

func (spec ProfileRevisionSpec) ValidateLifecycleSelection(selection SandboxLifecycleLimits) error

ValidateLifecycleSelection rejects new finite requests above the current grant. Resolution still applies the current ceiling if an operator later tightens it.

type PublicExecutionImage added in v0.15.0 

type PublicExecutionImage struct {
	RequestedReference string `json:"requestedReference"`
	ResolvedDigest     string `json:"resolvedDigest,omitempty"`
}

PublicExecutionImage is the non-secret image identity returned by the API.

func ParseExecutionImageMetadata added in v0.15.0 

func ParseExecutionImageMetadata(metadata map[string]string) (PublicExecutionImage, error)

type QuotaConstrainingScopes added in v0.13.0 

type QuotaConstrainingScopes struct {
	Sandboxes            string `json:"sandboxes"`
	ActiveInstances      string `json:"activeInstances"`
	VCPUCount            string `json:"vcpuCount"`
	MemoryBytes          string `json:"memoryBytes"`
	Snapshots            string `json:"snapshots"`
	PortSessions         string `json:"portSessions"`
	ConcurrentOperations string `json:"concurrentOperations"`
}

type QuotaHeadroom added in v0.13.0 

type QuotaHeadroom struct {
	Sandboxes            PolicyLimit `json:"sandboxes"`
	ActiveInstances      PolicyLimit `json:"activeInstances"`
	VCPUCount            PolicyLimit `json:"vcpuCount"`
	MemoryBytes          PolicyLimit `json:"memoryBytes"`
	Snapshots            PolicyLimit `json:"snapshots"`
	PortSessions         PolicyLimit `json:"portSessions"`
	ConcurrentOperations PolicyLimit `json:"concurrentOperations"`
}

type QuotaLimits 

type QuotaLimits struct {
	MaxSandboxes            PolicyLimit `json:"maxSandboxes"`
	MaxActiveInstances      PolicyLimit `json:"maxActiveInstances"`
	MaxVCPUCount            PolicyLimit `json:"maxVcpuCount"`
	MaxMemoryBytes          PolicyLimit `json:"maxMemoryBytes"`
	MaxSnapshots            PolicyLimit `json:"maxSnapshots"`
	MaxPortSessions         PolicyLimit `json:"maxPortSessions"`
	MaxConcurrentOperations PolicyLimit `json:"maxConcurrentOperations"`
}

QuotaLimits bounds one subject's aggregate reservations.

func (*QuotaLimits) UnmarshalJSON added in v0.13.0 

func (quota *QuotaLimits) UnmarshalJSON(data []byte) error

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 RequestFieldError added in v0.20.0 

type RequestFieldError struct {
	Field  string
	Reason string
}

RequestFieldError reports a request value that a custom JSON decoder refused. Field is relative to the value whose decoder refused it and is empty when that value as a whole was refused; encoding/json does not tell a decoder where its value sits in the document, so the API locates the enclosing member path.

func (*RequestFieldError) Error added in v0.20.0 

func (err *RequestFieldError) Error() string

type ResourcePolicy 

type ResourcePolicy struct {
	VCPUCount            int64 `json:"vcpuCount"`
	MemoryBytes          int64 `json:"memoryBytes"`
	WorkspaceBytes       int64 `json:"workspaceBytes"`
	ConcurrentOperations int64 `json:"concurrentOperations"`
}

ResourcePolicy defines default allocations and the concurrent operation limit. Without resourceCeiling, these allocations are also the Profile size bounds.

type RestoreSnapshotRequest 

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

RestoreSnapshotRequest selects one Snapshot owned by the stopped Sandbox.

type RetentionPolicy 

type RetentionPolicy struct {
	SnapshotLimit            PolicyLimit `json:"snapshotLimit"`
	SnapshotRetentionSeconds PolicyLimit `json:"snapshotRetentionSeconds"`
}

RetentionPolicy bounds local Snapshot count and lifetime.

func (*RetentionPolicy) UnmarshalJSON added in v0.13.0 

func (policy *RetentionPolicy) UnmarshalJSON(data []byte) error

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"`
	SupportedEgressContexts     []string         `json:"supportedEgressContexts"`
	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"`
	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 {
	Image             *PublicExecutionImage `json:"image,omitempty"`
	Lifecycle         LifecyclePolicy       `json:"lifecycle"`
	Resources         SandboxResources      `json:"resources"`
	ID                string                `json:"id"`
	TenantRef         string                `json:"-"`
	SubjectRef        string                `json:"-"`
	EgressContext     *string               `json:"egressContext"`
	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 SandboxLifecycleLimits added in v0.13.0 

type SandboxLifecycleLimits struct {
	IdleSeconds            PolicyLimit `json:"idleSeconds"`
	MaximumDurationSeconds PolicyLimit `json:"maximumDurationSeconds"`
}

func (*SandboxLifecycleLimits) UnmarshalJSON added in v0.13.0 

func (limits *SandboxLifecycleLimits) UnmarshalJSON(data []byte) error

func (SandboxLifecycleLimits) Validate added in v0.13.0 

func (limits SandboxLifecycleLimits) Validate() error

type SandboxListFilter added in v0.14.0 

type SandboxListFilter struct {
	Metadata map[string]string `json:"metadata,omitempty"`
	States   []string          `json:"states,omitempty"`
	IDs      []string          `json:"ids,omitempty"`
}

SandboxListFilter intersects Metadata containment with optional state and ID sets.

func (SandboxListFilter) Normalize added in v0.14.0 

func (filter SandboxListFilter) Normalize() (SandboxListFilter, error)

Normalize validates bounded sets and canonicalizes their cursor identity.

type SandboxPage 

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

SandboxPage is one bounded stable Project Sandbox traversal page.

type SandboxResourceRequest added in v0.11.0 

type SandboxResourceRequest struct {
	VCPUCount      *int64 `json:"vcpuCount,omitempty"`
	MemoryBytes    *int64 `json:"memoryBytes,omitempty"`
	WorkspaceBytes *int64 `json:"workspaceBytes,omitempty"`
}

SandboxResourceRequest selects individual axes within the pinned Profile ceiling.

type SandboxResources added in v0.11.0 

type SandboxResources struct {
	VCPUCount      int64 `json:"vcpuCount"`
	MemoryBytes    int64 `json:"memoryBytes"`
	WorkspaceBytes int64 `json:"workspaceBytes"`
}

SandboxResources is the immutable compute and workspace allocation of a Sandbox.

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 StartSandboxRequest added in v0.10.0 

type StartSandboxRequest struct {
	Image ExecutionImage `json:"image,omitzero"`
}

func (*StartSandboxRequest) UnmarshalJSON added in v0.10.0 

func (request *StartSandboxRequest) UnmarshalJSON(data []byte) error

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 StoragePressureObservation added in v0.13.0 

type StoragePressureObservation struct {
	Status     string     `json:"status"`
	ObservedAt *time.Time `json:"observedAt,omitempty"`
}

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"`
	AttributedExecution  *AttributedExecutionRequest `json:"attributedExecution,omitempty"`
}

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

func (*StreamingExecRequest) UnmarshalJSON added in v0.21.0 

func (request *StreamingExecRequest) UnmarshalJSON(data []byte) error

type Subject added in v0.6.0 

type Subject struct {
	// QuotaObservation is the atomic post-update capacity snapshot, retained on idempotent replay.
	QuotaObservation *SubjectCapacity  `json:"quotaObservation,omitempty"`
	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 SubjectCapacity added in v0.13.0 

type SubjectCapacity struct {
	SubjectRef         string                  `json:"subjectRef"`
	Limits             QuotaLimits             `json:"limits"`
	ConstrainingScopes QuotaConstrainingScopes `json:"constrainingScopes"`
	Usage              QuotaUsage              `json:"usage"`
	Available          QuotaHeadroom           `json:"available"`
	ObservedAt         time.Time               `json:"observedAt"`
}

SubjectCapacity reveals only the caller's quota and admission headroom. Available is capped by both Subject and tenant quota, not a reservation.

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 SubjectSandboxPolicy added in v0.13.0 

type SubjectSandboxPolicy struct {
	Profile             string                               `json:"profile"`
	Lifecycle           SandboxLifecycleLimits               `json:"lifecycle"`
	AttributedExecution *AttributedExecutionConnectionLimits `json:"attributedExecution,omitempty"`
}

SubjectSandboxPolicy selects lifecycle for future Sandboxes and connection policy for future attributed Assignments of one Profile.

type SubjectSandboxPolicyObservation added in v0.13.0 

type SubjectSandboxPolicyObservation struct {
	SubjectRef          string                                    `json:"subjectRef"`
	Revision            int64                                     `json:"revision"`
	Profile             string                                    `json:"profile"`
	ProfileRevisionID   string                                    `json:"profileRevisionId"`
	Desired             *SubjectSandboxPolicy                     `json:"desired"`
	Effective           LifecyclePolicy                           `json:"effective"`
	Ceiling             SandboxLifecycleLimits                    `json:"ceiling"`
	Resources           ResourcePolicy                            `json:"resources"`
	ResourceCeiling     ProfileResourceCeiling                    `json:"resourceCeiling,omitzero"`
	Execution           ExecutionPolicy                           `json:"execution"`
	Retention           RetentionPolicy                           `json:"retention"`
	Quota               QuotaLimits                               `json:"quota"`
	TenantQuota         TenantQuota                               `json:"tenantQuota"`
	ObservedAt          time.Time                                 `json:"observedAt"`
	AttributedExecution *AttributedExecutionConnectionObservation `json:"attributedExecution"`
}

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"`
	EgressContext            *string            `json:"egressContext"`
	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              PolicyLimit `json:"maxSandboxes"`
	MaxActiveInstances        PolicyLimit `json:"maxActiveInstances"`
	MaxVCPUCount              PolicyLimit `json:"maxVcpuCount"`
	MaxMemoryBytes            PolicyLimit `json:"maxMemoryBytes"`
	MaxSnapshots              PolicyLimit `json:"maxSnapshots"`
	MaxPortSessions           PolicyLimit `json:"maxPortSessions"`
	MaxConcurrentOperations   PolicyLimit `json:"maxConcurrentOperations"`
	MaxActiveSubjects         PolicyLimit `json:"maxActiveSubjects"`
	MaxApplicationAuthorities PolicyLimit `json:"maxApplicationAuthorities"`
}

TenantQuota bounds aggregate tenant reservations and management resources.

func (*TenantQuota) UnmarshalJSON added in v0.13.0 

func (quota *TenantQuota) UnmarshalJSON(data []byte) error

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"`
}

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.

func (*UpdateSubjectQuotaRequest) UnmarshalJSON added in v0.13.0 

func (request *UpdateSubjectQuotaRequest) UnmarshalJSON(data []byte) error

type UpdateTenantEgressContextRequest added in v0.8.0 

type UpdateTenantEgressContextRequest struct {
	EgressContext *string `json:"egressContext"`
}

UpdateTenantEgressContextRequest replaces or clears the operator-owned routing context.

type UpdateTenantQuotaRequest added in v0.13.0 

type UpdateTenantQuotaRequest struct {
	AggregateQuota TenantQuota `json:"aggregateQuota"`
}

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 {
	StorageObservation WorkspaceStorageObservation `json:"storageObservation"`
	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.

type WorkspaceStorageObservation added in v0.13.0 

type WorkspaceStorageObservation struct {
	Status          string                     `json:"status"`
	ObservedAt      *time.Time                 `json:"observedAt,omitempty"`
	AllocatedBytes  *int64                     `json:"allocatedBytes,omitempty"`
	ExclusiveBytes  *int64                     `json:"exclusiveBytes,omitempty"`
	ExclusiveReason string                     `json:"exclusiveReason,omitempty"`
	Reason          string                     `json:"reason,omitempty"`
	Pressure        StoragePressureObservation `json:"pressure"`
}

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.