store

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package store implements PostgreSQL-backed SecondBox control-plane authority.

Index

Constants

View Source 
const (
	StageDurableAdmission         = "durable_admission"
	StageLifecyclePickupNotify    = "lifecycle_pickup_notify"
	StageLifecyclePickupDeadline  = "lifecycle_pickup_deadline"
	StageLifecyclePickupImmediate = "lifecycle_pickup_immediate"
)

Control-plane orchestration milestone names owned by this package. The placement and startup milestones stay literals inside the transactions that establish them, and the teardown milestones belong to lifecycleprojection.

Variables

View Source 
var OrchestrationStages = []string{
	StageDurableAdmission,
	StageLifecyclePickupNotify,
	StageLifecyclePickupDeadline,
	StageLifecyclePickupImmediate,
	"workspace_ready",
	"placement_reconcile_started",
	"placement_effect_started",
	"placement_plan_ready",
	"placement_schedule_started",
	"placement_attempt_started",
	"placement_sandbox_locked",
	"placement_assignment_checked",
	"placement_candidates_locked",
	"placement_candidate_selected",
	"placement_ready",
	"startup_dispatched",
	"ready_projected",
	lifecycleprojection.StageTeardownDrainCommitted,
	lifecycleprojection.StageTeardownFenceDispatched,
	lifecycleprojection.StageTeardownFenceAcknowledged,
	lifecycleprojection.StageTeardownGenerationAdvanced,
	lifecycleprojection.StageTeardownStopCommitted,
	lifecycleprojection.StageTeardownWorkspaceDeleteDispatched,
	lifecycleprojection.StageTeardownFinalized,
}

OrchestrationStages is the complete ordered vocabulary of provider-neutral control-plane milestones persisted to secondbox.operation_stage_timings. The order is the causal order of one Sandbox lifecycle, so a timing response can break equal-timestamp ties deterministically. Every stage a control-plane transaction writes must appear here or it stays invisible to the timing routes.

LifecyclePickup* names carry why the lifecycle worker was awake when it first claimed the Operation's Sandbox: a PostgreSQL commit notification, the bounded recovery poll deadline, or an immediate re-claim after the worker had just finished other work. Encoding the wake trigger in the stage name keeps the evidence fixed-cardinality and needs no extra column.

Functions

This section is empty.

Types

type PostgresControlPlaneStore 

type PostgresControlPlaneStore struct {
	// contains filtered or unexported fields
}

PostgresControlPlaneStore persists standalone SecondBox authority.

func NewPostgresControlPlaneStore 

func NewPostgresControlPlaneStore(ctx context.Context, databaseURL string) (*PostgresControlPlaneStore, error)

NewPostgresControlPlaneStore connects to the required PostgreSQL authority.

func (*PostgresControlPlaneStore) AcquireLease 

func (store *PostgresControlPlaneStore) AcquireLease(
	ctx context.Context,
	input ports.LeaseInput,
) (contracts.Lease, error)

func (*PostgresControlPlaneStore) AcquireWorkspaceMutation 

func (store *PostgresControlPlaneStore) AcquireWorkspaceMutation(
	ctx context.Context,
	input ports.WorkspaceMutationInput,
) (ports.HomeWorkspace, bool, error)

AcquireWorkspaceMutation serializes all local workspace changes under the invariant row order Sandbox, Workspace, then Snapshot when present.

func (*PostgresControlPlaneStore) AppendAuditEvent 

func (store *PostgresControlPlaneStore) AppendAuditEvent(
	ctx context.Context,
	event contracts.AuditEvent,
) error

AppendAuditEvent persists service-layer mutation evidence.

func (*PostgresControlPlaneStore) ApplyLifecycleAction 

func (store *PostgresControlPlaneStore) ApplyLifecycleAction(
	ctx context.Context,
	claim ports.LifecycleReconcileClaim,
	action string,
	terminationReason string,
	now time.Time,
	nextReconcileAt time.Time,
) error

ApplyLifecycleAction commits one claimed transition only while owner and revision remain current.

A zero nextReconcileAt parks the Sandbox: the commit clears its durable deadline, which removes it from the claim scan until an external event schedules it again.

`revision` is the Sandbox's public ETag, and a `wait` changes no field a caller can observe, so a wait holds it — and updated_at with it — exactly where they were. Without that, a caller that reads a Sandbox and sends If-Match on what it read races a reconciliation it cannot see and loses the precondition to a transition that changed nothing.

The revision still fences the claim. Every action that changes durable state advances it, so a claim token that has committed such an action can never commit a second one, and a wait that holds the revision still requires reconcile_owner to name this claim's worker — which the commit clears.

func (*PostgresControlPlaneStore) ClaimLifecycle 

func (store *PostgresControlPlaneStore) ClaimLifecycle(
	ctx context.Context,
	workerID string,
	now time.Time,
	claimDuration time.Duration,
	wakeTrigger ports.LifecycleWakeTrigger,
) (ports.LifecycleReconcileClaim, bool, error)

ClaimLifecycle claims one due desired-state record with durable revision fencing.

func (*PostgresControlPlaneStore) ClaimLifecycleBatch 

func (store *PostgresControlPlaneStore) ClaimLifecycleBatch(
	ctx context.Context,
	workerID string,
	now time.Time,
	claimDuration time.Duration,
	batchSize int,
	wakeTrigger ports.LifecycleWakeTrigger,
) ([]ports.LifecycleReconcileClaim, error)

ClaimLifecycleBatch atomically claims a bounded ordered cohort. The caller still processes effects sequentially, so batching removes claim round trips without introducing concurrent serializable scheduler transactions.

func (*PostgresControlPlaneStore) Close 

func (store *PostgresControlPlaneStore) Close()

Close releases all PostgreSQL connections.

func (*PostgresControlPlaneStore) CloseActivitySession 

func (store *PostgresControlPlaneStore) CloseActivitySession(
	ctx context.Context,
	input ports.ActivityInput,
) (contracts.ActivitySession, error)

CloseActivitySession removes idle suppression but does not alter desired state.

func (*PostgresControlPlaneStore) CompleteGarbageObject 

func (store *PostgresControlPlaneStore) CompleteGarbageObject(
	ctx context.Context,
	object ports.GarbageObject,
	now time.Time,
) error

CompleteGarbageObject records terminal deletion evidence for a claimed object.

func (*PostgresControlPlaneStore) CompleteWorkspaceMutation 

func (store *PostgresControlPlaneStore) CompleteWorkspaceMutation(
	ctx context.Context,
	input ports.WorkspaceMutationCompletion,
) (ports.HomeWorkspace, error)

CompleteWorkspaceMutation records runner evidence and clears exactly the matching durable slot in one transaction.

func (*PostgresControlPlaneStore) CreateProfile 

func (store *PostgresControlPlaneStore) CreateProfile(
	ctx context.Context,
	profile contracts.Profile,
	idempotency ports.AdminIdempotencyInput,
) (contracts.Profile, ports.AdminIdempotencyResult, error)

func (*PostgresControlPlaneStore) CreateRunnerPool 

func (store *PostgresControlPlaneStore) CreateRunnerPool(
	ctx context.Context,
	pool contracts.RunnerPool,
) (contracts.RunnerPool, error)

CreateRunnerPool persists one new operator-owned placement boundary and audit event.

func (*PostgresControlPlaneStore) CreateSandbox 

func (store *PostgresControlPlaneStore) CreateSandbox(
	ctx context.Context,
	input ports.CreateSandboxInput,
) (contracts.Sandbox, contracts.Operation, bool, error)

func (*PostgresControlPlaneStore) CreateSnapshot 

func (store *PostgresControlPlaneStore) CreateSnapshot(
	ctx context.Context,
	input ports.SnapshotCreationInput,
) (contracts.Operation, error)

CreateSnapshot admits one asynchronous stopped-Sandbox local clone.

func (*PostgresControlPlaneStore) DeleteSnapshot 

func (store *PostgresControlPlaneStore) DeleteSnapshot(
	ctx context.Context,
	input ports.SnapshotDeletionInput,
) (contracts.Operation, error)

DeleteSnapshot admits one asynchronous local Snapshot deletion.

func (*PostgresControlPlaneStore) DisableProfile 

func (store *PostgresControlPlaneStore) DisableProfile(
	ctx context.Context,
	name string,
	expectedRevision int64,
	now time.Time,
	idempotency ports.AdminIdempotencyInput,
) (contracts.Profile, ports.AdminIdempotencyResult, error)

func (*PostgresControlPlaneStore) EndArtifactRetention 

func (store *PostgresControlPlaneStore) EndArtifactRetention(
	ctx context.Context,
	input ports.ArtifactRetentionInput,
) error

EndArtifactRetention hides public metadata and leaves provider deletion to two-phase garbage collection.

func (*PostgresControlPlaneStore) GetArtifactObject 

func (store *PostgresControlPlaneStore) GetArtifactObject(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	artifactID string,
	now time.Time,
) (ports.ArtifactObject, error)

GetArtifactObject resolves retained public metadata and its private immutable key.

func (*PostgresControlPlaneStore) GetLeaseByID 

func (store *PostgresControlPlaneStore) GetLeaseByID(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	leaseID string,
) (contracts.Lease, error)

GetLeaseByID reads one Lease without accepting a caller-supplied Sandbox scope.

func (*PostgresControlPlaneStore) GetOperation 

func (store *PostgresControlPlaneStore) GetOperation(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	operationID string,
) (contracts.Operation, error)

func (*PostgresControlPlaneStore) GetProfile 

func (store *PostgresControlPlaneStore) GetProfile(ctx context.Context, name string) (contracts.Profile, error)

func (*PostgresControlPlaneStore) GetRunner 

func (store *PostgresControlPlaneStore) GetRunner(
	ctx context.Context,
	runnerID string,
) (contracts.Runner, error)

GetRunner returns one administrative runner projection without credential material.

func (*PostgresControlPlaneStore) GetRunnerPool 

func (store *PostgresControlPlaneStore) GetRunnerPool(
	ctx context.Context,
	name string,
) (contracts.RunnerPool, error)

GetRunnerPool returns one administrative placement boundary.

func (*PostgresControlPlaneStore) GetSandbox 

func (store *PostgresControlPlaneStore) GetSandbox(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	sandboxID string,
) (contracts.Sandbox, error)

func (*PostgresControlPlaneStore) GetSandboxLifecyclePolicy 

func (store *PostgresControlPlaneStore) GetSandboxLifecyclePolicy(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	sandboxID string,
) (contracts.LifecyclePolicy, contracts.RetentionPolicy, error)

GetSandboxLifecyclePolicy reads the immutable ProfileRevision pinned by the Sandbox.

func (*PostgresControlPlaneStore) GetSnapshot 

func (store *PostgresControlPlaneStore) GetSnapshot(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	snapshotID string,
	now time.Time,
) (contracts.Snapshot, error)

func (*PostgresControlPlaneStore) GetSubjectUsage 

func (store *PostgresControlPlaneStore) GetSubjectUsage(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
) (contracts.SubjectUsage, error)

GetSubjectUsage reads one subject's current quota and aggregate reservations.

func (*PostgresControlPlaneStore) ListArtifacts 

func (store *PostgresControlPlaneStore) ListArtifacts(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	sandboxID string,
	limit int,
	cursor string,
	now time.Time,
) (contracts.ArtifactPage, error)

ListArtifacts returns retained, published Artifact metadata in deterministic newest-first order.

func (*PostgresControlPlaneStore) ListAuditEvents 

func (store *PostgresControlPlaneStore) ListAuditEvents(
	ctx context.Context,
	tenantRef string,
	limit int,
) ([]contracts.AuditEvent, error)

func (*PostgresControlPlaneStore) ListGarbageObjectsDue 

func (store *PostgresControlPlaneStore) ListGarbageObjectsDue(
	ctx context.Context,
	now time.Time,
	grace time.Duration,
	limit int,
) ([]ports.GarbageObject, error)

func (*PostgresControlPlaneStore) ListProfiles 

func (store *PostgresControlPlaneStore) ListProfiles(
	ctx context.Context,
	limit int,
	cursor string,
) (contracts.ProfilePage, error)

func (*PostgresControlPlaneStore) ListRunnerPools 

func (store *PostgresControlPlaneStore) ListRunnerPools(
	ctx context.Context,
	limit int,
	cursor string,
) (contracts.RunnerPoolPage, error)

ListRunnerPools returns a bounded stable administrative page.

func (*PostgresControlPlaneStore) ListRunners 

func (store *PostgresControlPlaneStore) ListRunners(
	ctx context.Context,
	poolName string,
	limit int,
	cursor string,
) (contracts.RunnerPage, error)

ListRunners returns stable runner projections optionally filtered by one exact pool.

func (*PostgresControlPlaneStore) ListSandboxes 

func (store *PostgresControlPlaneStore) ListSandboxes(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	limit int,
	cursor string,
	metadata map[string]string,
) (contracts.SandboxPage, error)

func (*PostgresControlPlaneStore) ListSnapshots 

func (store *PostgresControlPlaneStore) ListSnapshots(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	sandboxID string,
	limit int,
	cursor string,
	now time.Time,
) (contracts.SnapshotPage, error)

func (*PostgresControlPlaneStore) OpenActivitySession 

func (store *PostgresControlPlaneStore) OpenActivitySession(
	ctx context.Context,
	input ports.ActivityInput,
) (contracts.ActivitySession, error)

OpenActivitySession admits one useful generation-bound session.

func (*PostgresControlPlaneStore) Ping 

func (store *PostgresControlPlaneStore) Ping(ctx context.Context) error

Ping proves the PostgreSQL authority is reachable.

func (*PostgresControlPlaneStore) PingGuest 

func (store *PostgresControlPlaneStore) PingGuest(
	ctx context.Context,
	input ports.GenerationInput,
	liveness string,
) (contracts.Instance, error)

func (*PostgresControlPlaneStore) PublishArtifact 

func (store *PostgresControlPlaneStore) PublishArtifact(
	ctx context.Context,
	input ports.ArtifactPublicationInput,
	now time.Time,
) (contracts.Artifact, error)

PublishArtifact atomically exposes metadata only after provider hash and size verification.

func (*PostgresControlPlaneStore) QueueExpiredSnapshotDelete 

func (store *PostgresControlPlaneStore) QueueExpiredSnapshotDelete(
	ctx context.Context,
	input ports.SnapshotRetentionInput,
) (bool, error)

QueueExpiredSnapshotDelete admits at most one due retention deletion through the same asynchronous local effect path as an explicit API deletion.

func (*PostgresControlPlaneStore) ReadDeploymentTiming 

func (store *PostgresControlPlaneStore) ReadDeploymentTiming(
	ctx context.Context,
	since time.Time,
	until time.Time,
) (contracts.DeploymentTimingSummary, error)

ReadDeploymentTiming returns bounded aggregate database timing evidence.

func (*PostgresControlPlaneStore) ReadMetricsSnapshot 

func (store *PostgresControlPlaneStore) ReadMetricsSnapshot(
	ctx context.Context,
) (contracts.MetricsSnapshot, error)

func (*PostgresControlPlaneStore) ReadOperationTiming 

func (store *PostgresControlPlaneStore) ReadOperationTiming(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	operationID string,
) (contracts.OperationTiming, error)

ReadOperationTiming returns subject-owned timing evidence for one Operation.

func (*PostgresControlPlaneStore) ReadSandboxInspection 

func (store *PostgresControlPlaneStore) ReadSandboxInspection(
	ctx context.Context,
	input ports.GenerationInput,
) (contracts.SandboxInspection, error)

ReadSandboxInspection projects current persisted guest and useful-session evidence.

func (*PostgresControlPlaneStore) ReadSandboxTiming 

func (store *PostgresControlPlaneStore) ReadSandboxTiming(
	ctx context.Context,
	tenantRef string,
	subjectRef string,
	sandboxID string,
	limit int,
) (contracts.SandboxTiming, error)

ReadSandboxTiming returns one explicitly bounded subject-owned timing history.

func (*PostgresControlPlaneStore) RegisterRunnerPool 

func (store *PostgresControlPlaneStore) RegisterRunnerPool(
	ctx context.Context,
	pool contracts.RunnerPool,
) error

func (*PostgresControlPlaneStore) ReleaseLease 

func (store *PostgresControlPlaneStore) ReleaseLease(
	ctx context.Context,
	input ports.LeaseInput,
) (contracts.Lease, error)

ReleaseLease revokes activity authority without changing Sandbox desired state.

func (*PostgresControlPlaneStore) RelocateSandbox 

func (store *PostgresControlPlaneStore) RelocateSandbox(
	ctx context.Context,
	input ports.WorkspaceRelocationInput,
) (contracts.Operation, error)

RelocateSandbox admits one stopped Workspace transfer under its mutation slot.

func (*PostgresControlPlaneStore) RenewLease 

func (store *PostgresControlPlaneStore) RenewLease(
	ctx context.Context,
	input ports.LeaseInput,
) (contracts.Lease, error)

RenewLease extends only active, unexpired current-generation authority.

func (*PostgresControlPlaneStore) RestoreSnapshot 

func (store *PostgresControlPlaneStore) RestoreSnapshot(
	ctx context.Context,
	input ports.SnapshotRestoreInput,
) (contracts.Operation, error)

RestoreSnapshot admits the prepare phase of one stopped-Sandbox in-place restore.

func (*PostgresControlPlaneStore) ReviseProfile 

func (store *PostgresControlPlaneStore) ReviseProfile(
	ctx context.Context,
	name string,
	revision contracts.ProfileRevision,
	expectedRevision int64,
	now time.Time,
	idempotency ports.AdminIdempotencyInput,
) (contracts.Profile, ports.AdminIdempotencyResult, error)

func (*PostgresControlPlaneStore) SetSandboxDesiredState 

func (store *PostgresControlPlaneStore) SetSandboxDesiredState(
	ctx context.Context,
	input ports.LifecycleIntentInput,
) (contracts.Operation, error)

SetSandboxDesiredState records intent without claiming runner-side completion.

func (*PostgresControlPlaneStore) StageArtifact 

func (store *PostgresControlPlaneStore) StageArtifact(
	ctx context.Context,
	input ports.ArtifactPublicationInput,
) (contracts.Artifact, error)

func (*PostgresControlPlaneStore) SweepSessionAccounting added in v0.2.0 

func (store *PostgresControlPlaneStore) SweepSessionAccounting(
	ctx context.Context,
	now time.Time,
	activityRetention time.Duration,
	limit int,
) (int64, error)

SweepSessionAccounting removes at most limit expired accounting records.

func (*PostgresControlPlaneStore) TouchActivity 

func (store *PostgresControlPlaneStore) TouchActivity(
	ctx context.Context,
	input ports.ActivityInput,
) (time.Time, error)

TouchActivity records explicit useful activity for the current generation.

func (*PostgresControlPlaneStore) UpdateRunnerPool 

func (store *PostgresControlPlaneStore) UpdateRunnerPool(
	ctx context.Context,
	name string,
	update contracts.UpdateRunnerPoolRequest,
	expectedRevision int64,
	now time.Time,
) (contracts.RunnerPool, error)

UpdateRunnerPool changes explicit scheduling policy under optimistic concurrency.

func (*PostgresControlPlaneStore) UpdateSandboxMetadata 

func (store *PostgresControlPlaneStore) UpdateSandboxMetadata(
	ctx context.Context,
	input ports.UpdateSandboxMetadataInput,
) (contracts.Sandbox, error)

UpdateSandboxMetadata replaces application correlation metadata under the Sandbox revision fence without changing any lifecycle or runner authority.

Source Files

View all Source files

Directories

Path Synopsis
Package lifecycleprojection owns PostgreSQL projections shared by durable lifecycle transitions and the runner evidence transactions that establish those transitions' prerequisites.
 Package lifecycleprojection owns PostgreSQL projections shared by durable lifecycle transitions and the runner evidence transactions that establish those transitions' prerequisites.
Package rowlock owns the invariant PostgreSQL lock order for local Workspace mutations.
 Package rowlock owns the invariant PostgreSQL lock order for local Workspace mutations.

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.