ports

package
v0.27.1 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package ports defines SecondBox control-plane persistence boundaries.

Index

Constants

View Source
const (
	TenantControllerBearerTokenPrefix = "secondbox_tenant_controller_"
	ApplicationBearerTokenPrefix      = "secondbox_application_"
)

Variables

View Source
var (
	ErrAuthenticationFailed         = errors.New("SecondBox credential authentication failed")
	ErrAuthorizationDenied          = errors.New("SecondBox authorization denied")
	ErrManagementUnavailable        = errors.New("SecondBox durable management store is unavailable")
	ErrManagementNotFound           = errors.New("SecondBox management resource not found")
	ErrManagementConflict           = errors.New("SecondBox management resource conflicts with current state")
	ErrInvalidLifecycleTransition   = errors.New("SecondBox management lifecycle transition is invalid")
	ErrResourceExpired              = errors.New("SecondBox management resource is expired")
	ErrTenantSuspended              = errors.New("SecondBox Tenant is suspended")
	ErrTenantEgressContextRequired  = errors.New("SecondBox Profile requires a Tenant egress context")
	ErrEgressContextUnavailable     = errors.New("SecondBox Sandbox egress context is unavailable")
	ErrGrantEscalationDenied        = errors.New("SecondBox management grant exceeds its Tenant ceiling")
	ErrProfilePolicyCeilingExceeded = errors.New("SecondBox lifecycle policy exceeds its Profile ceiling")
	ErrInvalidRequest               = errors.New("SecondBox request is invalid")
	ErrProfileNotFound              = errors.New("SecondBox Profile not found")
	ErrProfileDisabled              = errors.New("SecondBox Profile is disabled")
	ErrRunnerPoolNotFound           = errors.New("SecondBox RunnerPool not found")
	ErrRunnerPoolExists             = errors.New("SecondBox RunnerPool already exists")
	ErrRunnerNotFound               = errors.New("SecondBox Runner not found")
	ErrRunnerPoolUnavailable        = errors.New("SecondBox compatible runner pool unavailable")
	// ErrRunnerPoolBackendInUse refuses a backend unseal while any Runner of the
	// pool is not offline, holds an active connection, or owns a non-terminal
	// Assignment.
	ErrRunnerPoolBackendInUse = errors.New("SecondBox RunnerPool compute backend is in use")
	// ErrStartupModeUnsupported reports that the Profile's RunnerPool does not
	// declare the capability its startup mode requires. It is not retryable:
	// no Runner in that pool is admissible until an operator either declares the
	// capability on the pool or revises the Profile's startup mode.
	ErrStartupModeUnsupported        = errors.New("SecondBox RunnerPool does not support the Profile startup mode")
	ErrSandboxNotFound               = errors.New("SecondBox Sandbox not found")
	ErrWorkspaceFileNotFound         = errors.New("SecondBox Workspace file not found")
	ErrSandboxNameConflict           = errors.New("SecondBox Sandbox name is already in use")
	ErrIdempotencyConflict           = errors.New("SecondBox idempotency key payload conflict")
	ErrCredentialResponseUnavailable = errors.New("SecondBox credential response is unavailable")
	ErrQuotaExceeded                 = errors.New("SecondBox quota exceeded")
	// ErrImagePreparationTargetsExceeded reports that more eligible Runners than
	// one preparation Operation may carry answered admission. Waiting cannot help:
	// the request must select a Profile that narrows the eligible Runner set.
	ErrImagePreparationTargetsExceeded = errors.New("SecondBox image preparation eligible Runner set exceeds its target limit")
	ErrRevisionConflict                = errors.New("SecondBox resource revision conflict")
	ErrLifecycleUnavailable            = errors.New("SecondBox lifecycle unavailable without a runner assignment")
	ErrHomeRunnerUnavailable           = errors.New("SecondBox Sandbox home runner is unavailable")
	ErrWorkspaceMutation               = errors.New("SecondBox Workspace has a conflicting local mutation")
	ErrSandboxNotStopped               = errors.New("SecondBox Workspace relocation requires a stopped Sandbox")
	ErrRelocationTargetUnavailable     = errors.New("SecondBox Workspace relocation target is unavailable or incompatible")
	ErrRelocationSnapshotsPresent      = errors.New("SecondBox Workspace relocation requires all Snapshots to be deleted")
	ErrProfileSwitchSandboxNotStopped  = errors.New("SecondBox Sandbox Profile switch requires a stopped Sandbox")
	ErrProfileSwitchSnapshotsPresent   = errors.New("SecondBox Sandbox Profile switch requires all Snapshots to be deleted")
	// ErrSerializationContention reports that a transaction lost a serialization
	// race and the caller should try again later. It is an ordinary outcome of
	// serializable isolation under concurrency, not a fault: a caller that treats
	// it as one will fail whenever load rises.
	ErrSerializationContention = errors.New("SecondBox transaction lost a serialization race")
	ErrWorkspaceHomeConflict   = errors.New("SecondBox Workspace home runner differs from assigned authority")
	ErrGenerationFenced        = errors.New("SecondBox Sandbox generation is fenced")
	ErrLeaseNotFound           = errors.New("SecondBox Lease not found")
	ErrLeaseAlreadyActive      = errors.New("SecondBox Sandbox already has an active Lease")
	ErrLeaseInactive           = errors.New("SecondBox Lease is not active")
	ErrActivitySessionNotFound = errors.New("SecondBox activity session not found")
	ErrSnapshotNotFound        = errors.New("SecondBox Snapshot not found")
	ErrSnapshotUnavailable     = errors.New("SecondBox Snapshot requires stopped committed disk state")
	ErrSnapshotNameConflict    = errors.New("SecondBox Snapshot name is held by a ready Snapshot in this Sandbox")
	ErrPortSessionNotFound     = errors.New("SecondBox PortSession not found")
	ErrPortPolicyDenied        = errors.New("SecondBox exposed port is not approved by the pinned Profile")
	ErrPortTokenInvalid        = errors.New("SecondBox port tunnel token is invalid")
	ErrPortTokenConsumed       = errors.New("SecondBox port tunnel token was already consumed")
	ErrWaitExpired             = errors.New("SecondBox Sandbox wait deadline expired")
)
View Source
var ErrProfileIncompatible = errors.New("SecondBox target Profile is incompatible with the Sandbox")
View Source
var ErrResourcesExceedProfile = errors.New("SecondBox requested resources exceed Profile ceiling")
View Source
var ErrResourcesFixedByProfile = errors.New("SecondBox requested resources differ from the fixed Profile size")

Functions

This section is empty.

Types

type ActivityInput

type ActivityInput struct {
	GenerationInput
	Session        contracts.ActivitySession
	LeaseID        string
	IdempotencyKey string
	RequestHash    string
}

ActivityInput records useful work without conflating guest liveness.

type AdminIdempotencyInput

type AdminIdempotencyInput struct {
	TenantRef   string
	SubjectRef  string
	Operation   string
	TargetID    string
	Key         string
	RequestHash string
	Now         time.Time
	Ends        time.Time
	AuditEvent  *contracts.AuditEvent
}

AdminIdempotencyInput binds one administrative mutation to an exact durable outcome.

type AdminIdempotencyResult

type AdminIdempotencyResult struct {
	Replayed bool
}

AdminIdempotencyResult reports whether a matching durable outcome was found.

type AuthenticatedApplicationAuthority added in v0.6.0

type AuthenticatedApplicationAuthority struct {
	ID            string
	TenantRef     string
	SubjectRef    string
	Scopes        []string
	ProfileGrants []string
}

AuthenticatedApplicationAuthority is the verified non-secret application authority used by HTTP admission.

type CreateSandboxInput

type CreateSandboxInput struct {
	Resources                *contracts.SandboxResourceRequest
	Principal                contracts.Principal
	Sandbox                  contracts.Sandbox
	Operation                contracts.Operation
	IdempotencyKey           string
	RequestHash              string
	IdempotencyEnds          time.Time
	WorkspaceEffectID        string
	WorkspaceCommandID       string
	FencingToken             []byte
	SourceSnapshotID         string
	LifecycleRequestMetadata map[string]string
}

CreateSandboxInput contains server-resolved identity and transaction evidence.

type GenerationInput

type GenerationInput struct {
	TenantRef  string
	SubjectRef string
	SandboxID  string
	Generation int64
	Now        time.Time
}

GenerationInput fences a lifecycle report to current Sandbox authority.

type HomeWorkspace

type HomeWorkspace struct {
	ID                   string
	SandboxID            string
	HomeRunnerID         string
	State                string
	LogicalCapacityBytes int64
	Generation           int64
	Mutation             WorkspaceMutation
	LocalReceipt         map[string]any
	CreatedAt            time.Time
	UpdatedAt            time.Time
}

HomeWorkspace is private durable ownership and local-store reconciliation state. It must never be projected into a public Sandbox or Workspace representation.

type ImagePreparationInput added in v0.15.0

type ImagePreparationInput struct {
	Principal     contracts.Principal
	Request       contracts.PrepareImageRequest
	ProfileGrants []string
	Operation     contracts.Operation
	Idempotency   AdminIdempotencyInput
}

type InvalidFieldError added in v0.20.0

type InvalidFieldError struct {
	Field  string
	Reason string
}

InvalidFieldError names the one public request input that made a request invalid. The HTTP API reports every InvalidFieldError in an error tree as an invalid_request Problem detail.

Field is the public JSON path in dotted camelCase (spec.resources.memoryBytes), a query parameter by name (limit), a header by its canonical name (If-Match), or body when the request body as a whole is malformed. Reason is a bounded client-facing predicate that completes the sentence "<Field> <Reason>"; it never embeds wrapped internal errors.

func ResourceAlignmentError added in v0.11.0

func ResourceAlignmentError(field string) *InvalidFieldError

ResourceAlignmentError identifies a public size field refused before allocation.

func (*InvalidFieldError) Error added in v0.20.0

func (err *InvalidFieldError) Error() string

func (*InvalidFieldError) Unwrap added in v0.20.0

func (err *InvalidFieldError) Unwrap() error

type LeaseInput

type LeaseInput struct {
	Lease           contracts.Lease
	TenantRef       string
	SubjectRef      string
	SandboxID       string
	Generation      int64
	ExpiresAt       time.Time
	Now             time.Time
	IdempotencyKey  string
	RequestHash     string
	IdempotencyEnds time.Time
	ReplaceActive   bool
}

LeaseInput creates or renews bounded activity authority.

type LifecycleIntentInput

type LifecycleIntentInput struct {
	Principal        contracts.Principal
	SandboxID        string
	DesiredState     string
	Operation        contracts.Operation
	Now              time.Time
	IdempotencyKey   string
	RequestHash      string
	IdempotencyEnds  time.Time
	ExpectedRevision int64
	// AuditEvent records this request, original or replayed, in the
	// admission transaction.
	AuditEvent contracts.AuditEvent
}

LifecycleIntentInput records desired state and one durable asynchronous operation.

type LifecycleReconcileClaim

type LifecycleReconcileClaim struct {
	SandboxID                 string
	WorkerID                  string
	Revision                  int64
	ObservedState             string
	DesiredState              string
	IntentKind                string
	IntentTerminationReason   string
	StopEffectState           string
	GuestLiveness             string
	InstanceTerminationReason string
	HasInstance               bool
	ActiveSessions            int64
	DrainStartedAt            *time.Time
	ReadyAt                   *time.Time
	LastActivityAt            *time.Time
	DrainGraceSeconds         int64
	IdleSeconds               int64
	MaximumDurationSeconds    int64
	// AssignmentDeadline is the current Instance's Assignment operation
	// deadline, when one exists.
	AssignmentDeadline *time.Time
}

LifecycleReconcileClaim is one revision-fenced desired-state work item.

type LifecycleWakeTrigger added in v0.3.0

type LifecycleWakeTrigger string

LifecycleWakeTrigger names why the lifecycle worker was running when it claimed a cohort. It is attribution evidence only: PostgreSQL remains the sole work authority, and every trigger reaches the same fenced claim query.

const (
	// LifecycleWakeTriggerNotify means a PostgreSQL commit notification made
	// the worker run before its poll deadline.
	LifecycleWakeTriggerNotify LifecycleWakeTrigger = "notify"
	// LifecycleWakeTriggerDeadline means no notification arrived and the
	// bounded recovery poll interval elapsed. A transition that leaves work
	// immediately available should never be followed by this trigger.
	LifecycleWakeTriggerDeadline LifecycleWakeTrigger = "deadline"
	// LifecycleWakeTriggerImmediate means the worker never waited: it had just
	// completed a claim and re-ran its claim query directly.
	LifecycleWakeTriggerImmediate LifecycleWakeTrigger = "immediate"
)

type ProfileIncompatibleError added in v0.24.0

type ProfileIncompatibleError struct {
	Property string
	Reason   string
}

ProfileIncompatibleError names the pinned Sandbox property that the target Profile revision cannot serve.

func (*ProfileIncompatibleError) Error added in v0.24.0

func (err *ProfileIncompatibleError) Error() string

func (*ProfileIncompatibleError) Unwrap added in v0.24.0

func (err *ProfileIncompatibleError) Unwrap() error

type ResourcesExceedProfileError added in v0.11.0

type ResourcesExceedProfileError struct {
	Ceiling   contracts.SandboxResourceRequest
	Requested contracts.SandboxResources
}

ResourcesExceedProfileError preserves the resolved request and its immutable ceiling.

func (*ResourcesExceedProfileError) Error added in v0.11.0

func (err *ResourcesExceedProfileError) Error() string

func (*ResourcesExceedProfileError) Unwrap added in v0.11.0

func (err *ResourcesExceedProfileError) Unwrap() error

type ResourcesFixedByProfileError added in v0.11.0

type ResourcesFixedByProfileError struct {
	Fixed     contracts.SandboxResourceRequest
	Requested contracts.SandboxResources
}

ResourcesFixedByProfileError identifies the exact allocation required for resume.

func (*ResourcesFixedByProfileError) Error added in v0.11.0

func (err *ResourcesFixedByProfileError) Error() string

func (*ResourcesFixedByProfileError) Unwrap added in v0.11.0

func (err *ResourcesFixedByProfileError) Unwrap() error

type SnapshotCreationInput

type SnapshotCreationInput struct {
	Snapshot         contracts.Snapshot
	Operation        contracts.Operation
	EffectID         string
	CommandID        string
	FencingToken     []byte
	IdempotencyKey   string
	RequestHash      string
	IdempotencyEnds  time.Time
	ExpectedRevision int64
}

SnapshotCreationInput admits one asynchronous runner-local Snapshot clone.

type SnapshotDeletionInput

type SnapshotDeletionInput struct {
	TenantRef       string
	SubjectRef      string
	SnapshotID      string
	Operation       contracts.Operation
	EffectID        string
	CommandID       string
	FencingToken    []byte
	IdempotencyKey  string
	RequestHash     string
	IdempotencyEnds time.Time
	Now             time.Time
}

SnapshotDeletionInput admits one asynchronous runner-local Snapshot deletion.

type SnapshotRestoreInput

type SnapshotRestoreInput struct {
	TenantRef         string
	SubjectRef        string
	SandboxID         string
	SnapshotID        string
	Operation         contracts.Operation
	RestoreID         string
	PrepareEffectID   string
	SwapEffectID      string
	FinalizeEffectID  string
	AbortEffectID     string
	PrepareCommandID  string
	SwapCommandID     string
	FinalizeCommandID string
	AbortCommandID    string
	FencingToken      []byte
	IdempotencyKey    string
	RequestHash       string
	IdempotencyEnds   time.Time
	ExpectedRevision  int64
	Now               time.Time
}

SnapshotRestoreInput admits one stopped-Sandbox in-place restore.

type SnapshotRetentionInput

type SnapshotRetentionInput struct {
	OperationID  string
	EffectID     string
	CommandID    string
	RequestID    string
	FencingToken []byte
	Now          time.Time
}

SnapshotRetentionInput identifies one internally generated expiration deletion attempt. The store selects the due Snapshot while preserving the ordinary asynchronous delete transaction and lock order.

type SwitchSandboxProfileInput added in v0.24.0

type SwitchSandboxProfileInput struct {
	Principal contracts.Principal
	SandboxID string
	Profile   string
	// ProfileGrants is nil for a caller without an application authority and
	// otherwise lists the authority's grants, which must name both Profiles.
	ProfileGrants    []string
	ExpectedRevision int64
	IdempotencyKey   string
	RequestHash      string
	IdempotencyEnds  time.Time
	AuditEvent       contracts.AuditEvent
	Now              time.Time
}

SwitchSandboxProfileInput repins one stopped Sandbox to another Profile's current revision at one Sandbox revision.

type UpdateSandboxMetadataInput

type UpdateSandboxMetadataInput struct {
	Principal        contracts.Principal
	SandboxID        string
	Metadata         map[string]string
	ExpectedRevision int64
	Now              time.Time
}

UpdateSandboxMetadataInput replaces consumer correlation metadata at one revision.

type WorkspaceMutation

type WorkspaceMutation struct {
	Kind               string
	ID                 string
	EffectID           string
	OperationID        string
	ExpectedGeneration int64
	TargetGeneration   int64
	State              string
}

WorkspaceMutation is the single durable local-storage mutation barrier.

type WorkspaceMutationCompletion

type WorkspaceMutationCompletion struct {
	WorkspaceMutationInput
	WorkspaceState      string
	CommittedGeneration int64
	LocalReceipt        map[string]any
}

WorkspaceMutationCompletion atomically records durable runner evidence and releases the matching mutation barrier.

type WorkspaceMutationInput

type WorkspaceMutationInput struct {
	TenantRef          string
	SubjectRef         string
	SandboxID          string
	WorkspaceID        string
	SnapshotID         string
	HomeRunnerID       string
	Kind               string
	MutationID         string
	EffectID           string
	OperationID        string
	ExpectedGeneration int64
	TargetGeneration   int64
	Now                time.Time
}

WorkspaceMutationInput acquires or replays the one Workspace mutation slot.

type WorkspaceRelocationInput

type WorkspaceRelocationInput struct {
	Principal        contracts.Principal
	SandboxID        string
	TargetRunnerID   string
	RunnerPool       string
	Operation        contracts.Operation
	RelocationID     string
	ExportCommandID  string
	FencingToken     []byte
	Now              time.Time
	IdempotencyKey   string
	RequestHash      string
	IdempotencyEnds  time.Time
	ExpectedRevision int64
}

WorkspaceRelocationInput admits one stopped-Sandbox home transfer.

Jump to

Keyboard shortcuts

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