sandboxcontrol

package
v0.0.0-...-804b954 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrHostDenied deliberately merges absent, revoked, expired, quarantined,
	// incompatible and incorrectly authenticated hosts.
	ErrHostDenied = errors.New("sandbox host not found or denied")
	// ErrNoHostAssignment reports an authenticated host with no eligible work.
	ErrNoHostAssignment = errors.New("sandbox host has no assignment")
	// ErrHostProtocolViolation reports an authenticated but impossible message.
	ErrHostProtocolViolation = errors.New("sandbox host protocol violation")
	// ErrHostAttestationFailed reports a durably retained verifier refusal.
	ErrHostAttestationFailed = errors.New("sandbox host attestation failed")
)
View Source 
var (
	// ErrConflict reports a Principal-scoped Operation ID reused with different immutable input.
	ErrConflict = errors.New("sandbox control operation conflict")
	// ErrNotFoundOrDenied keeps guessed operation IDs indistinguishable from absent IDs.
	ErrNotFoundOrDenied = errors.New("sandbox control operation not found or denied")
	// ErrInvalidTransition reports a state change that cannot converge safely.
	ErrInvalidTransition = errors.New("sandbox control operation transition is invalid")
	// ErrStaleFence reports a host result from an expired or superseded assignment.
	ErrStaleFence = errors.New("sandbox control host result has a stale fence")
	// ErrOperationIDExpired reports an Operation ID retained as a tombstone.
	ErrOperationIDExpired = errors.New("sandbox control operation id is expired")
)

Functions

This section is empty.

Types

type Assignment 

type Assignment struct {
	HostID         string
	HostGeneration uint64
	AssignmentID   string
	LeaseEpoch     uint64
	FencingToken   uint64
	LeaseExpiresAt time.Time
}

Assignment binds an operation to one host and monotonic fencing authority.

type AttestationEvidence 

type AttestationEvidence struct {
	HostID            string
	Generation        uint64
	CertificateDigest string
	CapabilityDigest  string
	AttestationDigest string
	Evidence          []byte
}

AttestationEvidence is the bounded immutable input supplied transiently to a verifier. Only its digest and outcome may be persisted.

type AttestationInput 

type AttestationInput struct {
	Profile  AttestationProfile
	Evidence []byte
}

AttestationInput is raw, bounded enrollment evidence plus its explicit assurance profile. Evidence is verified transiently and never persisted.

type AttestationProfile 

type AttestationProfile string

AttestationProfile identifies the evidence assurance a host enrollment presents. Metadata-only local evidence is explicitly not a hardware or runtime integrity attestation. 

const (
	// AttestationProfileLocalMetadata records only operator-supplied metadata
	// for the unsafe local development profile.
	AttestationProfileLocalMetadata AttestationProfile = "local-metadata-v1"
	// AttestationProfileVerified requires the configured predicate to accept
	// bounded evidence before a production-capable host is admitted.
	AttestationProfileVerified AttestationProfile = "verified-v1"
)

type AttestationState 

type AttestationState string

AttestationState is the durable outcome of evaluating a host profile. 

const (
	// AttestationMetadataOnly makes the deliberately limited local profile
	// visible rather than representing it as verification.
	AttestationMetadataOnly AttestationState = "metadata-only"
	// AttestationVerified records an explicit successful verifier predicate.
	AttestationVerified AttestationState = "verified"
	// AttestationFailed records an explicit failed or unavailable predicate.
	AttestationFailed AttestationState = "failed"
)

type AttestationVerifier 

type AttestationVerifier interface {
	VerifyHostAttestation(context.Context, AttestationEvidence) error
}

AttestationVerifier evaluates the selected profile's evidence predicate. Evidence is borrowed only for the duration of the call. Implementations must not retain it; the store zeroes its owned verifier buffer afterward.

type AttestationVerifierFunc 

type AttestationVerifierFunc func(context.Context, AttestationEvidence) error

AttestationVerifierFunc adapts a function into an AttestationVerifier.

func (AttestationVerifierFunc) VerifyHostAttestation 

func (verifier AttestationVerifierFunc) VerifyHostAttestation(ctx context.Context, evidence AttestationEvidence) error

VerifyHostAttestation implements AttestationVerifier.

type BootProbeProfile 

type BootProbeProfile struct {
	VMID            string         `json:"vm_id"`
	FixtureVersion  string         `json:"fixture_version"`
	PlanDigest      sandbox.Digest `json:"plan_digest"`
	FixtureDigest   sandbox.Digest `json:"fixture_digest"`
	AuthorityDigest sandbox.Digest `json:"authority_digest"`
}

BootProbeProfile is the operator-owned stable portion of a trusted M4 identity. It deliberately excludes StageDigest, which M4 can produce only after its reviewed staging step.

type DeliverySeed 

type DeliverySeed struct {
	AssignmentID string
	EnvelopeID   string
	DeliveryID   string
	Nonce        string
}

DeliverySeed contains bounded unpredictable identities generated before a serializable claim/renew transaction. Store methods never invent identity.

type DurableStore 

type DurableStore interface {
	Accept(context.Context, Operation) (Operation, bool, error)
	Get(context.Context, string, string) (Operation, error)
	Transition(context.Context, string, string, uint64, State) (Operation, error)
	Assign(context.Context, string, string, string, time.Time) (Operation, error)
	RecordHostResult(context.Context, string, string, HostResult) (Operation, error)
	RecoverExpiredAssignments(context.Context, time.Time, int) ([]Operation, error)
	ClaimExpiredCleanup(context.Context, time.Time, int) ([]Operation, error)
	Reap(context.Context, time.Time, int) ([]Operation, error)
	ReadOutbox(context.Context, uint64, int) ([]OutboxRecord, error)
	ReadOperationOutbox(context.Context, string, string, uint64, int) ([]OutboxRecord, error)
}

DurableStore is the control-plane persistence boundary used by routing, reconciliation and reaping. All methods require a principal-bound caller.

type EnvelopeSigner 

type EnvelopeSigner func(sandboxhostprotocol.Envelope) ([]byte, error)

EnvelopeSigner signs one complete immutable assignment while its ledger row is locked. Implementations must be deterministic and perform no I/O.

type HostAttestation 

type HostAttestation struct {
	Profile AttestationProfile
	State   AttestationState
	Digest  string
}

HostAttestation is the profile/state pair persisted with a host enrollment.

func VerifyHostAttestation 

func VerifyHostAttestation(ctx context.Context, input AttestationInput, host HostEnrollment, verifier AttestationVerifier) HostAttestation

VerifyHostAttestation calls the explicit profile predicate and returns a safe durable state. Verification failure is recorded as state, not exposed as unbounded verifier detail.

type HostControlStore 

type HostControlStore interface {
	ProvisionHost(context.Context, HostEnrollment, AttestationInput, AttestationVerifier) error
	RevokeHost(context.Context, string, uint64, time.Time) error
	AuthenticateHost(context.Context, HostIdentity, time.Time) (HostEnrollment, error)
	PullHostAssignment(context.Context, HostIdentity, time.Time, time.Time, DeliverySeed, EnvelopeSigner) (HostDispatch, error)
	AcknowledgeHostAssignment(context.Context, HostIdentity, string, uint64, string, time.Time) (bool, error)
	RenewHostAssignment(context.Context, HostIdentity, string, uint64, time.Time, time.Time, DeliverySeed, EnvelopeSigner) (HostDispatch, error)
	RecordAuthenticatedHostOutput(context.Context, HostIdentity, sandboxhostprotocol.Output, time.Time) (bool, error)
	RecordAuthenticatedDataPlaneReceipt(context.Context, HostIdentity, sandboxhostprotocol.DataPlaneReceipt, time.Time) (bool, error)
	RecordAuthenticatedHostResult(context.Context, HostIdentity, sandboxhostprotocol.Result, time.Time) (Operation, error)
	QuarantineHost(context.Context, HostIdentity, string, time.Time) ([]Operation, error)
	ConfirmHostCleanupAndRequeue(context.Context, string, string, uint64, time.Time) (Operation, error)
}

HostControlStore is the private enrolled-host authority seam.

type HostDispatch 

type HostDispatch struct {
	Operation      Operation
	Envelope       []byte
	EnvelopeDigest string
	ReceiptDigest  string
	AcknowledgedAt time.Time
}

HostDispatch is the persisted exact assignment and signed wire envelope.

type HostEnrollment 

type HostEnrollment struct {
	HostID            string
	Tenant            string
	Pool              string
	Generation        uint64
	ProtocolVersion   string
	CertificateDigest string
	SigningPublicKey  ed25519.PublicKey
	// ObservationPublicKey is the separately enrolled M4 observation key for
	// the v2 boot-probe stage-ready record. It is optional for v1 hosts, but
	// required before the v2 preparation route can create a session.
	ObservationPublicKey ed25519.PublicKey
	// BootProbeProfile is the operator-enrolled immutable M4 identity subset.
	// M4 supplies the stage digest only after it has staged reviewed resources.
	BootProbeProfile    BootProbeProfile
	CapabilityDigest    string
	AttestationDigest   string
	AttestationProfile  AttestationProfile
	AttestationState    AttestationState
	Status              HostStatus
	ExpiresAt           time.Time
	LastAuthenticatedAt time.Time
	QuarantineReason    string
}

HostEnrollment is operator-owned durable host identity metadata. It contains public verification material only, never a certificate or private key.

type HostIdentity 

type HostIdentity struct {
	HostID            string
	Generation        uint64
	CertificateDigest string
}

HostIdentity is derived from the mutually authenticated peer certificate.

type HostResult 

type HostResult struct {
	HostID       string
	FencingToken uint64
	State        State
	// ObservedAt is supplied by the control plane's injected clock, never by the host.
	ObservedAt time.Time
}

HostResult is a host acknowledgement guarded by its assigned fence.

type HostStatus 

type HostStatus string

HostStatus is the durable enrollment security state. 

const (
	HostActive      HostStatus = "active"
	HostRevoked     HostStatus = "revoked"
	HostQuarantined HostStatus = "quarantined"
	// HostAttestationFailed records a verifier refusal retained for operator
	// diagnosis. Failed hosts can never authenticate or receive work.
	HostAttestationFailed HostStatus = "attestation-failed"
)

type MemoryLedger 

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

MemoryLedger is a deterministic DurableStore used by hermetic lifecycle tests.

func NewMemoryLedger 

func NewMemoryLedger() *MemoryLedger

NewMemoryLedger constructs an empty deterministic operation ledger.

func (*MemoryLedger) Accept 

func (ledger *MemoryLedger) Accept(ctx context.Context, operation Operation) (Operation, bool, error)

Accept records an immutable operation or returns a prior identical record.

func (*MemoryLedger) AcknowledgeHostAssignment 

func (ledger *MemoryLedger) AcknowledgeHostAssignment(ctx context.Context, identity HostIdentity, assignmentID string, fence uint64, receiptDigest string, now time.Time) (bool, error)

AcknowledgeHostAssignment persists one receipt digest. An identical retry is a safe duplicate; a changed receipt for the same fence is a violation.

func (*MemoryLedger) Assign 

func (ledger *MemoryLedger) Assign(ctx context.Context, principal, id, hostID string, leaseExpiresAt time.Time) (Operation, error)

Assign records a fresh fenced host assignment and expires any prior lease.

func (*MemoryLedger) AuthenticateHost 

func (ledger *MemoryLedger) AuthenticateHost(ctx context.Context, identity HostIdentity, now time.Time) (HostEnrollment, error)

AuthenticateHost verifies the complete identity derived from mTLS.

func (*MemoryLedger) ClaimExpiredCleanup 

func (ledger *MemoryLedger) ClaimExpiredCleanup(ctx context.Context, now time.Time, limit int) ([]Operation, error)

ClaimExpiredCleanup fences any outstanding host and records durable cleanup ownership for expired resources before a reaper performs destructive work.

func (*MemoryLedger) ConfirmHostCleanupAndRequeue 

func (ledger *MemoryLedger) ConfirmHostCleanupAndRequeue(ctx context.Context, principal, operationID string, version uint64, observedAt time.Time) (Operation, error)

ConfirmHostCleanupAndRequeue is the explicit reconciliation boundary after a fenced host can no longer act. It never guesses cleanup from liveness.

func (*MemoryLedger) Get 

func (ledger *MemoryLedger) Get(ctx context.Context, principal, id string) (Operation, error)

Get returns one authorized durable operation without revealing another principal's record.

func (*MemoryLedger) ProvisionHost 

func (ledger *MemoryLedger) ProvisionHost(ctx context.Context, enrollment HostEnrollment, input AttestationInput, verifier AttestationVerifier) error

ProvisionHost records an audited enrollment generation or idempotently reconnects the byte-equivalent current generation.

func (*MemoryLedger) PullHostAssignment 

func (ledger *MemoryLedger) PullHostAssignment(ctx context.Context, identity HostIdentity, now, leaseExpiresAt time.Time, seed DeliverySeed, signer EnvelopeSigner) (HostDispatch, error)

PullHostAssignment returns a current non-terminal envelope verbatim for lost receipt or result recovery, otherwise assigns the oldest eligible work.

func (*MemoryLedger) QuarantineHost 

func (ledger *MemoryLedger) QuarantineHost(ctx context.Context, identity HostIdentity, reason string, now time.Time) ([]Operation, error)

QuarantineHost atomically denies the host and fences every current operation.

func (*MemoryLedger) ReadOperationOutbox 

func (ledger *MemoryLedger) ReadOperationOutbox(ctx context.Context, principal, id string, afterVersion uint64, limit int) ([]OutboxRecord, error)

ReadOperationOutbox returns one authorized Operation's ordered state facts strictly after its durable version cursor.

func (*MemoryLedger) ReadOutbox 

func (ledger *MemoryLedger) ReadOutbox(ctx context.Context, afterID uint64, limit int) ([]OutboxRecord, error)

ReadOutbox returns ordered records strictly after afterID.

func (*MemoryLedger) Reap 

func (ledger *MemoryLedger) Reap(ctx context.Context, now time.Time, limit int) ([]Operation, error)

Reap tombstones only expired operations whose cleanup is either unnecessary or durably confirmed. Cleanup-pending records remain addressable.

func (*MemoryLedger) RecordAuthenticatedDataPlaneReceipt 

func (ledger *MemoryLedger) RecordAuthenticatedDataPlaneReceipt(ctx context.Context, identity HostIdentity, receipt sandboxhostprotocol.DataPlaneReceipt, receivedAt time.Time) (bool, error)

RecordAuthenticatedDataPlaneReceipt persists one reference-only terminal observation before the host can send a terminal result. Exact late retries remain idempotent; a changed receipt for the same assignment is refused.

func (*MemoryLedger) RecordAuthenticatedHostOutput 

func (ledger *MemoryLedger) RecordAuthenticatedHostOutput(ctx context.Context, identity HostIdentity, output sandboxhostprotocol.Output, receivedAt time.Time) (bool, error)

RecordAuthenticatedHostOutput assigns the next sequence atomically. Exact retries are idempotent; altered duplicates and gaps fail closed.

func (*MemoryLedger) RecordAuthenticatedHostResult 

func (ledger *MemoryLedger) RecordAuthenticatedHostResult(ctx context.Context, identity HostIdentity, result sandboxhostprotocol.Result, receivedAt time.Time) (Operation, error)

RecordAuthenticatedHostResult accepts only the current enrolled generation, assignment, lease epoch, fence, digests, scope and finite observed lease.

func (*MemoryLedger) RecordHostResult 

func (ledger *MemoryLedger) RecordHostResult(ctx context.Context, principal, id string, result HostResult) (Operation, error)

RecordHostResult accepts only the current host assignment's fenced result.

func (*MemoryLedger) RecoverExpiredAssignments 

func (ledger *MemoryLedger) RecoverExpiredAssignments(ctx context.Context, now time.Time, limit int) ([]Operation, error)

RecoverExpiredAssignments fences expired host authority and makes its uncertain outcome available for reconciliation.

func (*MemoryLedger) RenewHostAssignment 

func (ledger *MemoryLedger) RenewHostAssignment(ctx context.Context, identity HostIdentity, assignmentID string, fence uint64, now, leaseExpiresAt time.Time, seed DeliverySeed, signer EnvelopeSigner) (HostDispatch, error)

RenewHostAssignment advances both lease epoch and fencing token and persists a newly signed envelope before returning it.

func (*MemoryLedger) ReplayOutput 

func (ledger *MemoryLedger) ReplayOutput(ctx context.Context, principal string, processID sandbox.ProcessID, after sandbox.OutputCursor) ([]sandbox.OutputEvent, error)

ReplayOutput returns the retained, signed host chunks owned by principal. A header-only legacy output record deliberately produces no event: it was created before the durable-byte protocol and must not be misrepresented as replayable content.

func (*MemoryLedger) RevokeHost 

func (ledger *MemoryLedger) RevokeHost(ctx context.Context, hostID string, generation uint64, now time.Time) error

RevokeHost fences one current generation before future authentication.

func (*MemoryLedger) Transition 

func (ledger *MemoryLedger) Transition(ctx context.Context, principal, id string, version uint64, next State) (Operation, error)

Transition records one optimistic-concurrency-checked lifecycle transition.

type MemoryResourceReadModel 

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

MemoryResourceReadModel is a hermetic, principal-scoped resource projection for control-plane tests. It is deliberately independent from MemoryLedger: callers must project complete resource facts as their state transitions are committed, rather than deriving resource state from an operation target.

It is not a substitute for the transactional PostgreSQL projection required by the production control path. In particular, it has no outbox, retention reaper, or host reconciliation responsibility.

func NewMemoryResourceReadModel 

func NewMemoryResourceReadModel() *MemoryResourceReadModel

NewMemoryResourceReadModel constructs an empty test-only resource projection.

func (*MemoryResourceReadModel) GetProcess 

func (model *MemoryResourceReadModel) GetProcess(ctx context.Context, principal string, id sandbox.ProcessID) (sandbox.ProcessInfo, error)

func (*MemoryResourceReadModel) GetSandbox 

func (model *MemoryResourceReadModel) GetSandbox(ctx context.Context, principal string, id sandbox.SandboxID) (sandbox.SandboxInfo, error)

func (*MemoryResourceReadModel) GetSnapshot 

func (model *MemoryResourceReadModel) GetSnapshot(ctx context.Context, principal string, id sandbox.SnapshotID) (sandbox.SnapshotInfo, error)

func (*MemoryResourceReadModel) GetVolume 

func (model *MemoryResourceReadModel) GetVolume(ctx context.Context, principal string, id sandbox.VolumeID) (sandbox.VolumeInfo, error)

func (*MemoryResourceReadModel) ListSnapshots 

func (model *MemoryResourceReadModel) ListSnapshots(ctx context.Context, principal string, page sandbox.Page) (sandbox.SnapshotPage, error)

func (*MemoryResourceReadModel) ListVolumes 

func (model *MemoryResourceReadModel) ListVolumes(ctx context.Context, principal string, page sandbox.Page) (sandbox.VolumePage, error)

func (*MemoryResourceReadModel) ProjectProcess 

func (model *MemoryResourceReadModel) ProjectProcess(ctx context.Context, principal string, value sandbox.ProcessInfo) error

ProjectProcess records the complete current process metadata for principal.

func (*MemoryResourceReadModel) ProjectSandbox 

func (model *MemoryResourceReadModel) ProjectSandbox(ctx context.Context, principal string, value sandbox.SandboxInfo) error

ProjectSandbox records the complete current sandbox metadata for principal.

func (*MemoryResourceReadModel) ProjectSnapshot 

func (model *MemoryResourceReadModel) ProjectSnapshot(ctx context.Context, principal string, value sandbox.SnapshotInfo) error

ProjectSnapshot records the complete current snapshot metadata for principal.

func (*MemoryResourceReadModel) ProjectVolume 

func (model *MemoryResourceReadModel) ProjectVolume(ctx context.Context, principal string, value sandbox.VolumeInfo) error

ProjectVolume records the complete current volume metadata for principal.

type Operation 

type Operation struct {
	Principal           string
	Tenant              string
	ID                  string
	Kind                string
	TargetKind          string
	TargetID            string
	InputDigest         string
	CanonicalDigest     string
	EffectiveSpecDigest string
	CapabilityDigest    string
	DispatchBody        string
	State               State
	Version             uint64
	AcceptedAt          time.Time
	RetentionExpiresAt  time.Time
	CleanupRequired     bool
	RetainedOutputBytes uint64
	// ResourceProjectionBinding, when present, is immutable admission metadata
	// for a complete resource snapshot. Resource-aware stores enforce it before
	// accepting or replacing any projection.
	ResourceProjectionBinding *ResourceProjectionBinding
	Assignment                Assignment
}

Operation is the bounded durable operation ledger record. CanonicalDigest and EffectiveSpecDigest are references only: unbounded input and output content belongs in their dedicated stores.

type OutboxEvent 

type OutboxEvent string

OutboxEvent is one bounded fact committed atomically with a ledger change. 

const (
	// OutboxAccepted records durable operation acceptance before dispatch.
	OutboxAccepted OutboxEvent = "accepted"
	// OutboxDispatched records a fresh fenced host assignment.
	OutboxDispatched OutboxEvent = "dispatched"
	// OutboxStateChanged records a non-assignment lifecycle transition.
	OutboxStateChanged OutboxEvent = "state-changed"
	// OutboxLeaseExpired records fencing of an expired host assignment.
	OutboxLeaseExpired OutboxEvent = "lease-expired"
	// OutboxTombstoned records final bounded identity retention.
	OutboxTombstoned OutboxEvent = "tombstoned"
)

type OutboxRecord 

type OutboxRecord struct {
	ID               uint64
	Principal        string
	OperationID      string
	OperationVersion uint64
	Event            OutboxEvent
	State            State
}

OutboxRecord is an ordered, at-least-once publication input. It contains no request, output, secret, or backend content.

type OutputReplayStore 

type OutputReplayStore interface {
	ReplayOutput(context.Context, string, sandbox.ProcessID, sandbox.OutputCursor) ([]sandbox.OutputEvent, error)
}

OutputReplayStore is the separately authenticated, durable output window behind the public replay transport. It returns only retained redacted bytes; callers cannot derive output from host metadata headers.

type PostgresLedger 

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

PostgresLedger is the production DurableStore. Its constructor never creates or migrates infrastructure; an audited operator must apply the declared schema before the control role starts.

func NewPostgresLedger 

func NewPostgresLedger(pool *pgxpool.Pool) (*PostgresLedger, error)

NewPostgresLedger binds an already configured PostgreSQL pool.

func (*PostgresLedger) Accept 

func (ledger *PostgresLedger) Accept(ctx context.Context, operation Operation) (Operation, bool, error)

Accept records an immutable operation and its publication fact in one serializable transaction, or reconnects to the prior identical record.

func (*PostgresLedger) AcknowledgeHostAssignment 

func (ledger *PostgresLedger) AcknowledgeHostAssignment(ctx context.Context, identity HostIdentity, assignmentID string, fence uint64, receiptDigest string, now time.Time) (bool, error)

AcknowledgeHostAssignment stores a stable receipt or classifies an identical retry as a duplicate without starting another effect.

func (*PostgresLedger) Assign 

func (ledger *PostgresLedger) Assign(ctx context.Context, principal, id, hostID string, leaseExpiresAt time.Time) (Operation, error)

Assign records a fresh finite host lease and monotonically advances fencing authority before dispatch publication.

func (*PostgresLedger) AuthenticateHost 

func (ledger *PostgresLedger) AuthenticateHost(ctx context.Context, identity HostIdentity, now time.Time) (HostEnrollment, error)

AuthenticateHost verifies durable enrollment against identity derived from the TLS peer certificate and records only a safe last-authenticated instant.

func (*PostgresLedger) ClaimExpiredCleanup 

func (ledger *PostgresLedger) ClaimExpiredCleanup(ctx context.Context, now time.Time, limit int) ([]Operation, error)

ClaimExpiredCleanup fences outstanding authority and records durable cleanup ownership before the reaper performs destructive work.

func (*PostgresLedger) ConfirmHostCleanupAndRequeue 

func (ledger *PostgresLedger) ConfirmHostCleanupAndRequeue(ctx context.Context, principal, operationID string, version uint64, observedAt time.Time) (Operation, error)

ConfirmHostCleanupAndRequeue records explicit cleanup evidence before a previously uncertain operation becomes eligible for reassignment.

func (*PostgresLedger) CreateBootProbeSession 

func (ledger *PostgresLedger) CreateBootProbeSession(ctx context.Context, identity HostIdentity, principal, operationID, hostInstanceSessionID string, initial firecrackerbootprobev2.Delivery, now time.Time) (firecrackerbootprobev2.Snapshot, bool, error)

CreateBootProbeSession creates the distinct v2 lifecycle only after the durable current enrolled host assignment has been locked and compared.

func (*PostgresLedger) Get 

func (ledger *PostgresLedger) Get(ctx context.Context, principal, id string) (Operation, error)

Get returns one authorized durable operation without revealing records under another Principal.

func (*PostgresLedger) LoadBootProbeSession 

func (ledger *PostgresLedger) LoadBootProbeSession(ctx context.Context, hostInstanceSessionID string) (firecrackerbootprobev2.Snapshot, error)

LoadBootProbeSession recovers the canonical v2 session for a host instance.

func (*PostgresLedger) ProvisionHost 

func (ledger *PostgresLedger) ProvisionHost(ctx context.Context, enrollment HostEnrollment, input AttestationInput, verifier AttestationVerifier) error

ProvisionHost records one operator-reconciled enrollment generation. The runtime host API never calls this method.

func (*PostgresLedger) PullHostAssignment 

func (ledger *PostgresLedger) PullHostAssignment(ctx context.Context, identity HostIdentity, now, leaseExpiresAt time.Time, seed DeliverySeed, signer EnvelopeSigner) (HostDispatch, error)

PullHostAssignment atomically persists routing, signed envelope and outbox before returning. A current non-terminal delivery is returned verbatim so either a lost receipt or lost result can be recovered without re-execution.

func (*PostgresLedger) QuarantineHost 

func (ledger *PostgresLedger) QuarantineHost(ctx context.Context, identity HostIdentity, reason string, now time.Time) ([]Operation, error)

QuarantineHost denies the host and fences all non-terminal assignments.

func (*PostgresLedger) ReadOperationOutbox 

func (ledger *PostgresLedger) ReadOperationOutbox(ctx context.Context, principal, id string, afterVersion uint64, limit int) ([]OutboxRecord, error)

ReadOperationOutbox returns one authorized Operation's ordered state facts strictly after its durable version cursor.

func (*PostgresLedger) ReadOutbox 

func (ledger *PostgresLedger) ReadOutbox(ctx context.Context, afterID uint64, limit int) ([]OutboxRecord, error)

ReadOutbox returns bounded ordered publication inputs strictly after afterID.

func (*PostgresLedger) Reap 

func (ledger *PostgresLedger) Reap(ctx context.Context, now time.Time, limit int) ([]Operation, error)

Reap tombstones only expired terminal records for which cleanup is either unnecessary or durably confirmed.

func (*PostgresLedger) RecordAuthenticatedDataPlaneReceipt 

func (ledger *PostgresLedger) RecordAuthenticatedDataPlaneReceipt(ctx context.Context, identity HostIdentity, receipt sandboxhostprotocol.DataPlaneReceipt, receivedAt time.Time) (bool, error)

RecordAuthenticatedDataPlaneReceipt persists one exact reference-only terminal receipt while the assignment remains live. Late duplicate replay is accepted only when its immutable bytes already exist.

func (*PostgresLedger) RecordAuthenticatedHostOutput 

func (ledger *PostgresLedger) RecordAuthenticatedHostOutput(ctx context.Context, identity HostIdentity, output sandboxhostprotocol.Output, receivedAt time.Time) (bool, error)

RecordAuthenticatedHostOutput persists the next control-owned output sequence while the assignment row is locked. Exact retries are idempotent.

func (*PostgresLedger) RecordAuthenticatedHostResult 

func (ledger *PostgresLedger) RecordAuthenticatedHostResult(ctx context.Context, identity HostIdentity, result sandboxhostprotocol.Result, receivedAt time.Time) (Operation, error)

RecordAuthenticatedHostResult performs durable assignment and digest checks.

func (*PostgresLedger) RecordHostResult 

func (ledger *PostgresLedger) RecordHostResult(ctx context.Context, principal, id string, result HostResult) (Operation, error)

RecordHostResult accepts only a result observed within the current host's finite fencing lease.

func (*PostgresLedger) RecoverExpiredAssignments 

func (ledger *PostgresLedger) RecoverExpiredAssignments(ctx context.Context, now time.Time, limit int) ([]Operation, error)

RecoverExpiredAssignments atomically fences expired host authority and exposes the operation as uncertain for bounded reconciliation.

func (*PostgresLedger) RenewBootProbeSession 

func (ledger *PostgresLedger) RenewBootProbeSession(ctx context.Context, identity HostIdentity, expected firecrackerbootprobev2.Snapshot, successor firecrackerbootprobev2.Delivery, now time.Time) (firecrackerbootprobev2.Snapshot, error)

RenewBootProbeSession admits exactly one successor only while the original enrolled host, assignment, lease, and fence are still authoritative.

func (*PostgresLedger) RenewHostAssignment 

func (ledger *PostgresLedger) RenewHostAssignment(ctx context.Context, identity HostIdentity, assignmentID string, fence uint64, now, leaseExpiresAt time.Time, seed DeliverySeed, signer EnvelopeSigner) (HostDispatch, error)

RenewHostAssignment advances epoch/fence and replaces the exact envelope.

func (*PostgresLedger) ReplayOutput 

func (ledger *PostgresLedger) ReplayOutput(ctx context.Context, principal string, processID sandbox.ProcessID, after sandbox.OutputCursor) ([]sandbox.OutputEvent, error)

ReplayOutput reads the retained redacted chunks after authenticating the caller by the principal-scoped process target. The operation join means an assignment identifier never becomes an output-read capability.

func (*PostgresLedger) RevokeHost 

func (ledger *PostgresLedger) RevokeHost(ctx context.Context, hostID string, generation uint64, now time.Time) error

RevokeHost denies the current generation and fences all of its operations.

func (*PostgresLedger) SealBootProbeStageReady 

func (ledger *PostgresLedger) SealBootProbeStageReady(ctx context.Context, identity HostIdentity, verified firecrackerbootprobeprotocol.VerifiedStageReady, stageWire []byte, controlPrivateKey ed25519.PrivateKey, now time.Time) ([]byte, error)

SealBootProbeStageReady atomically validates the active enrollment, exact prepared snapshot, and operator profile before persisting the M3-signed M4 command. A byte-identical StageReady retry returns the prior command.

func (*PostgresLedger) Transition 

func (ledger *PostgresLedger) Transition(ctx context.Context, principal, id string, version uint64, next State) (Operation, error)

Transition records one optimistic-concurrency-checked lifecycle transition.

type PostgresResourceReadModel 

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

PostgresResourceReadModel persists sandbox and process metadata together with the operation lifecycle transition that observed it. It is deliberately separate from PostgresLedger: callers must opt into these projection-aware methods rather than allowing a bare operation target to become a resource response.

It currently has no public transport wiring. Output replay remains a separate prerequisite because host output receipts retain only metadata, not redacted bytes.

func NewPostgresResourceReadModel 

func NewPostgresResourceReadModel(pool *pgxpool.Pool) (*PostgresResourceReadModel, error)

NewPostgresResourceReadModel binds a preconfigured pool. The operator must have applied the sandbox-control migrations before it is used.

func (*PostgresResourceReadModel) Accept 

func (model *PostgresResourceReadModel) Accept(ctx context.Context, operation Operation) (Operation, bool, error)

The ordinary ledger methods remain available so this model can be used as the control service's single durable store. Resource-aware callers opt into the typed methods below; all other operations retain the ledger behavior.

func (*PostgresResourceReadModel) AcceptProcess 

func (model *PostgresResourceReadModel) AcceptProcess(ctx context.Context, operation Operation, value sandbox.ProcessInfo) (Operation, bool, error)

AcceptProcess durably accepts a process operation and its initial complete metadata in one transaction.

func (*PostgresResourceReadModel) AcceptSandbox 

func (model *PostgresResourceReadModel) AcceptSandbox(ctx context.Context, operation Operation, value sandbox.SandboxInfo) (Operation, bool, error)

AcceptSandbox durably accepts a sandbox operation and its initial complete metadata in one transaction. The operation target is bound to the resource ID, so a caller cannot attach metadata to a guessed resource.

func (*PostgresResourceReadModel) AcceptVolume 

func (model *PostgresResourceReadModel) AcceptVolume(ctx context.Context, operation Operation, value sandbox.VolumeInfo) (Operation, bool, error)

AcceptVolume durably accepts a volume operation and its initial complete metadata in one transaction.

func (*PostgresResourceReadModel) Assign 

func (model *PostgresResourceReadModel) Assign(ctx context.Context, principal, id, hostID string, expiresAt time.Time) (Operation, error)

func (*PostgresResourceReadModel) ClaimExpiredCleanup 

func (model *PostgresResourceReadModel) ClaimExpiredCleanup(ctx context.Context, now time.Time, limit int) ([]Operation, error)

func (*PostgresResourceReadModel) Get 

func (model *PostgresResourceReadModel) Get(ctx context.Context, principal, id string) (Operation, error)

func (*PostgresResourceReadModel) GetProcess 

func (model *PostgresResourceReadModel) GetProcess(ctx context.Context, principal string, id sandbox.ProcessID) (sandbox.ProcessInfo, error)

func (*PostgresResourceReadModel) GetSandbox 

func (model *PostgresResourceReadModel) GetSandbox(ctx context.Context, principal string, id sandbox.SandboxID) (sandbox.SandboxInfo, error)

func (*PostgresResourceReadModel) GetVolume 

func (model *PostgresResourceReadModel) GetVolume(ctx context.Context, principal string, id sandbox.VolumeID) (sandbox.VolumeInfo, error)

GetVolume returns the complete principal-scoped volume projection.

func (*PostgresResourceReadModel) ListVolumes 

func (model *PostgresResourceReadModel) ListVolumes(ctx context.Context, principal string, page sandbox.Page) (sandbox.VolumePage, error)

ListVolumes returns a bounded, stable page of principal-scoped volume projections.

func (*PostgresResourceReadModel) ReadOperationOutbox 

func (model *PostgresResourceReadModel) ReadOperationOutbox(ctx context.Context, principal, id string, after uint64, limit int) ([]OutboxRecord, error)

func (*PostgresResourceReadModel) ReadOutbox 

func (model *PostgresResourceReadModel) ReadOutbox(ctx context.Context, after uint64, limit int) ([]OutboxRecord, error)

func (*PostgresResourceReadModel) Reap 

func (model *PostgresResourceReadModel) Reap(ctx context.Context, now time.Time, limit int) ([]Operation, error)

func (*PostgresResourceReadModel) RecordHostResult 

func (model *PostgresResourceReadModel) RecordHostResult(ctx context.Context, principal, id string, result HostResult) (Operation, error)

func (*PostgresResourceReadModel) RecoverExpiredAssignments 

func (model *PostgresResourceReadModel) RecoverExpiredAssignments(ctx context.Context, now time.Time, limit int) ([]Operation, error)

func (*PostgresResourceReadModel) ReplayOutput 

func (model *PostgresResourceReadModel) ReplayOutput(ctx context.Context, principal string, processID sandbox.ProcessID, after sandbox.OutputCursor) ([]sandbox.OutputEvent, error)

func (*PostgresResourceReadModel) Transition 

func (model *PostgresResourceReadModel) Transition(ctx context.Context, principal, id string, version uint64, next State) (Operation, error)

func (*PostgresResourceReadModel) TransitionProcess 

func (model *PostgresResourceReadModel) TransitionProcess(ctx context.Context, principal, operationID string, version uint64, next State, value sandbox.ProcessInfo) (Operation, error)

TransitionProcess changes one process operation and replaces its complete metadata projection atomically.

func (*PostgresResourceReadModel) TransitionSandbox 

func (model *PostgresResourceReadModel) TransitionSandbox(ctx context.Context, principal, operationID string, version uint64, next State, value sandbox.SandboxInfo) (Operation, error)

TransitionSandbox changes one sandbox operation and replaces its complete metadata projection atomically.

func (*PostgresResourceReadModel) TransitionVolume 

func (model *PostgresResourceReadModel) TransitionVolume(ctx context.Context, principal, operationID string, version uint64, next State, value sandbox.VolumeInfo) (Operation, error)

TransitionVolume changes one volume operation and replaces its complete metadata projection atomically.

type ProcessReadModel 

type ProcessReadModel interface {
	GetProcess(context.Context, string, sandbox.ProcessID) (sandbox.ProcessInfo, error)
}

ProcessReadModel is the narrow durable projection required to serve public process inspection. It does not imply that process admission or execution is implemented by the configured control service.

type ResourceAdmissionStore 

type ResourceAdmissionStore interface {
	DurableStore
	AcceptVolume(context.Context, Operation, sandbox.VolumeInfo) (Operation, bool, error)
	TransitionVolume(context.Context, string, string, uint64, State, sandbox.VolumeInfo) (Operation, error)
}

ResourceAdmissionStore is the durable admission seam for a complete resource projection. It deliberately has no public transport of its own: callers must still pass a canonical operation through the control service.

type ResourceProjectionBinding 

type ResourceProjectionBinding struct {
	Kind                   ResourceProjectionKind
	ResourceID             string
	AdmittedSnapshotDigest string
	Transition             ResourceProjectionTransition
}

ResourceProjectionBinding is the immutable admission-time contract between an operation and a resource read-model. AdmittedSnapshotDigest identifies the exact initial complete snapshot; it is not recomputed from later state.

This is an internal storage seam only. It does not make resource inspection public or infer host observations that have not been durably supplied.

func NewResourceProjectionBinding 

func NewResourceProjectionBinding(ctx context.Context, principal string, kind ResourceProjectionKind, resourceID string, value any) (ResourceProjectionBinding, error)

NewResourceProjectionBinding derives the immutable admission-time binding from exactly the complete metadata that will be persisted. It is useful to the control admission layer before it selects the typed durable method.

type ResourceProjectionKind 

type ResourceProjectionKind string

ResourceProjectionKind is the closed set of resource snapshots that can be durably attached to an operation at admission. It is intentionally narrower than an operation target: a target identifies routing, while this binding authorizes one complete resource read-model snapshot. 

const (
	ResourceProjectionSandbox ResourceProjectionKind = "sandbox"
	ResourceProjectionProcess ResourceProjectionKind = "process"
	// ResourceProjectionVolume binds a named-volume lifecycle operation to the
	// complete principal-scoped volume projection admitted with it.
	ResourceProjectionVolume ResourceProjectionKind = "volume"
	// ResourceProjectionSnapshot reserves the matching typed binding for a
	// future snapshot source/result authority. It is not an execution claim.
	ResourceProjectionSnapshot ResourceProjectionKind = "snapshot"
)

type ResourceProjectionTransition 

type ResourceProjectionTransition string

ResourceProjectionTransition declares how the admitted resource snapshot is maintained as its operation advances. The value is persisted with the immutable binding, so an adapter cannot silently change the projection model after acceptance. 

const (
	// ResourceProjectionReplaceSnapshot requires each lifecycle transition to
	// atomically replace the complete current resource snapshot.
	ResourceProjectionReplaceSnapshot ResourceProjectionTransition = "replace-complete-snapshot"
)

type ResourceReadModel 

type ResourceReadModel interface {
	GetSandbox(context.Context, string, sandbox.SandboxID) (sandbox.SandboxInfo, error)
	GetProcess(context.Context, string, sandbox.ProcessID) (sandbox.ProcessInfo, error)
	GetVolume(context.Context, string, sandbox.VolumeID) (sandbox.VolumeInfo, error)
	ListVolumes(context.Context, string, sandbox.Page) (sandbox.VolumePage, error)
	GetSnapshot(context.Context, string, sandbox.SnapshotID) (sandbox.SnapshotInfo, error)
	ListSnapshots(context.Context, string, sandbox.Page) (sandbox.SnapshotPage, error)
}

ResourceReadModel is the durable, principal-scoped projection required before sandbox.control/v1 can serve public resource-inspection endpoints.

DurableStore deliberately contains only the immutable operation ledger and its bounded routing metadata. In particular, an operation target is not a SandboxInfo or ProcessInfo: it cannot report desired/actual state, admitted image and limits, process result, or object retention without inventing state. Implementations must persist those projections atomically with their control-plane transitions and apply the same not-found-or-denied semantics as DurableStore.Get. Output replay is intentionally not included here because it additionally needs retained, redacted bytes rather than host-output digests and sizes.

The control API must not expose a resource endpoint until its configured store implements this interface. Keeping it separate from DurableStore makes that storage/migration prerequisite explicit for both the in-memory and PostgreSQL control paths.

type State 

type State string

State is one durable sandbox operation lifecycle state. 

const (
	// StateAccepted records an immutable request before host routing.
	StateAccepted State = "accepted"
	// StateDispatched records a currently fenced host assignment.
	StateDispatched State = "dispatched"
	// StateStarted records host acknowledgement that work began.
	StateStarted State = "started"
	// StateSucceeded records a terminal successful outcome.
	StateSucceeded State = "succeeded"
	// StateFailed records a terminal failed outcome.
	StateFailed State = "failed"
	// StateCancelled records a terminal caller-authorized cancellation.
	StateCancelled State = "cancelled"
	// StateUncertain records an outcome whose external effect requires reconciliation.
	StateUncertain State = "uncertain"
	// StateCleanupPending records durable cleanup work owned by the reaper.
	StateCleanupPending State = "cleanup-pending"
	// StateCleanupConfirmed records successful cleanup before retention expiry.
	StateCleanupConfirmed State = "cleanup-confirmed"
	// StateExpired records expired retention before a tombstone is emitted.
	StateExpired State = "expired"
	// StateTombstoned records the bounded retained identity after cleanup/expiry.
	StateTombstoned State = "tombstoned"
)

type VolumeReadModel 

type VolumeReadModel interface {
	GetVolume(context.Context, string, sandbox.VolumeID) (sandbox.VolumeInfo, error)
	ListVolumes(context.Context, string, sandbox.Page) (sandbox.VolumePage, error)
}

VolumeReadModel is the narrow durable projection required to serve the public volume inspection endpoints. It intentionally does not imply that sandbox, process, or snapshot projections are ready for transport.

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.
⌂ 换网址