Documentation
¶
Overview ¶
Package ports defines SecondBox control-plane persistence boundaries.
Index ¶
- Constants
- Variables
- type ActivityInput
- type AdminIdempotencyInput
- type AdminIdempotencyResult
- type AuthenticatedApplicationAuthority
- type CreateSandboxInput
- type GenerationInput
- type HomeWorkspace
- type ImagePreparationInput
- type InvalidFieldError
- type LeaseInput
- type LifecycleIntentInput
- type LifecycleReconcileClaim
- type LifecycleWakeTrigger
- type PoolCapacityScope
- type ProfileIncompatibleError
- type ResourcesExceedProfileError
- type ResourcesFixedByProfileError
- type SnapshotCreationInput
- type SnapshotDeletionInput
- type SnapshotRestoreInput
- type SnapshotRetentionInput
- type SwitchSandboxProfileInput
- type UpdateSandboxMetadataInput
- type WorkspaceMutation
- type WorkspaceMutationCompletion
- type WorkspaceMutationInput
- type WorkspaceRelocationInput
Constants ¶
const ( TenantControllerBearerTokenPrefix = "secondbox_tenant_controller_" ApplicationBearerTokenPrefix = "secondbox_application_" )
Variables ¶
var ( ErrAuthenticationFailed = errors.New("SecondBox credential authentication failed") ErrAuthorizationDenied = errors.New("SecondBox authorization denied") 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") 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") // 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") ErrQuotaExceeded = errors.New("SecondBox quota exceeded") // ErrComputeQuotaExceeded refuses admission on an axis that frees as other // work ends: active Instances, vCPU, memory, or concurrent operations, // including a Profile's per-Sandbox execution concurrency. It is an // ErrQuotaExceeded; the other axes (Sandboxes, Snapshots, port sessions) // free only by the caller's own action or an operator. ErrComputeQuotaExceeded = fmt.Errorf("%w on a compute axis", ErrQuotaExceeded) // 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") ErrWorkspaceMutation = errors.New("SecondBox Workspace has a conflicting local mutation") ErrSandboxNotStopped = errors.New("SecondBox Workspace relocation requires a stopped Sandbox") 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") 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") )
var ErrProfileIncompatible = errors.New("SecondBox target Profile is incompatible with the Sandbox")
var ErrResourcesExceedProfile = errors.New("SecondBox requested resources exceed Profile ceiling")
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
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 PoolCapacityScope ¶ added in v0.28.0
type PoolCapacityScope struct {
AllPools bool
TenantRef string
SubjectRef string
ProfileNames []string
TenantCeiling bool
}
PoolCapacityScope selects the RunnerPools one caller may observe: every pool, or the pools of the enabled Profiles it may use together with the pools its own Sandboxes are pinned to. An empty SubjectRef widens the Sandbox scope to the Tenant, and TenantCeiling takes the Profiles from the Tenant's ceiling.
type ProfileIncompatibleError ¶ added in v0.24.0
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.