ports

package

v0.2.2 Latest Latest Go to latest Published: Aug 6, 2026 License: MIT Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/SecondStack-AI/SecondBox

Links

Open Source Insights

Documentation ¶

Overview ¶

Package ports defines SecondBox control-plane persistence boundaries.

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrAuthenticationFailed        = errors.New("SecondBox credential authentication failed")
	ErrAuthorizationDenied         = errors.New("SecondBox authorization denied")
	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")
	ErrSandboxNotFound             = errors.New("SecondBox Sandbox 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")
	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")
	// 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")
	ErrArtifactIntegrity       = errors.New("SecondBox Artifact integrity failed")
	ErrArtifactNotFound        = errors.New("SecondBox Artifact not found")
	ErrArtifactStorage         = errors.New("SecondBox Artifact storage unavailable")
	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")
	ErrPortBackpressure        = errors.New("SecondBox port tunnel has no available byte credit")
	ErrWaitExpired             = errors.New("SecondBox Sandbox wait deadline expired")
)

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
}

AdminIdempotencyInput binds one administrative mutation to an exact durable response.

type AdminIdempotencyResult ¶

type AdminIdempotencyResult struct {
	Replayed bool
}

AdminIdempotencyResult reports whether a stored response was replayed.

type ArtifactObject ¶

type ArtifactObject struct {
	Artifact   contracts.Artifact
	StorageKey string
}

ArtifactObject binds public metadata to its private immutable provider key.

type ArtifactPublicationInput ¶

type ArtifactPublicationInput struct {
	Artifact           contracts.Artifact
	StorageKey         string
	ExpectedGeneration int64
	LeaseID            string
	IdempotencyKey     string
	RequestHash        string
	IdempotencyEnds    time.Time
}

ArtifactPublicationInput publishes immutable application exchange evidence.

type ArtifactRetentionInput ¶

type ArtifactRetentionInput struct {
	TenantRef       string
	SubjectRef      string
	ArtifactID      string
	IdempotencyKey  string
	RequestHash     string
	IdempotencyEnds time.Time
	Now             time.Time
}

ArtifactRetentionInput ends public reachability idempotently before provider garbage collection.

type CreateSandboxInput ¶

type CreateSandboxInput struct {
	Principal          contracts.Principal
	SubjectQuota       contracts.QuotaLimits
	Sandbox            contracts.Sandbox
	Workspace          contracts.Workspace
	Operation          contracts.Operation
	IdempotencyKey     string
	RequestHash        string
	IdempotencyEnds    time.Time
	WorkspaceEffectID  string
	WorkspaceCommandID string
	FencingToken       []byte
	SourceSnapshotID   string
}

CreateSandboxInput contains server-resolved identity and transaction evidence.

type GarbageObject ¶

type GarbageObject struct {
	Kind       string
	ID         string
	StorageKey string
	SHA256     string
	SizeBytes  int64
}

GarbageObject is private provider evidence for one unreachable immutable object.

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

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
}

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

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 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.

Source Files ¶

View all Source files

ports.go

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