firecrackerbootprobev2

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: 14 Imported by: 0

Documentation

Overview

Package firecrackerbootprobev2 owns the private, persisted successor and acknowledgement contract for one sealed Firecracker boot-probe lease.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidState identifies malformed, widened, or non-canonical private boot-probe v2 state.
	ErrInvalidState = errors.New("invalid Firecracker boot-probe v2 state")
	// ErrSuccessorRefused identifies a stale, forked, cross-instance, or non-successive authenticated delivery.
	ErrSuccessorRefused = errors.New("Firecracker boot-probe v2 successor refused")
	// ErrInvalidAcknowledgement identifies a malformed acknowledgement that cannot be classified.
	ErrInvalidAcknowledgement = errors.New("invalid Firecracker boot-probe v2 acknowledgement")
)
View Source 
var (
	// ErrInvalidLifecycle identifies malformed, detached, or non-canonical private boot-probe v2 session lifecycle state.
	ErrInvalidLifecycle = errors.New("invalid Firecracker boot-probe v2 lifecycle")
	// ErrLifecycleTransitionRefused identifies a lifecycle transition that could relaunch a boot probe or skip required cleanup.
	ErrLifecycleTransitionRefused = errors.New("Firecracker boot-probe v2 lifecycle transition refused")
)
View Source 
var (
	// ErrStateConflict identifies an attempted initial create that reuses a host-instance session for different immutable state.
	ErrStateConflict = errors.New("Firecracker boot-probe v2 state conflict")
	// ErrVersionConflict identifies a compare-and-swap against a stale recovery snapshot.
	ErrVersionConflict = errors.New("Firecracker boot-probe v2 state version conflict")
	// ErrVersionOverflow identifies a compare-and-swap that cannot assign the next monotonic persistence version.
	ErrVersionOverflow = errors.New("Firecracker boot-probe v2 state version overflow")
)

Functions

func Encode 

func Encode(state State) ([]byte, error)

Encode writes canonical private boot-probe v2 state bytes suitable for caller-owned persistence.

func EncodeSession 

func EncodeSession(session Session) ([]byte, error)

EncodeSession writes one canonical private boot-probe v2 compound session suitable for persistence next to its CAS version.

Types

type Acknowledgement 

type Acknowledgement struct {
	HostInstanceSessionID string `json:"host_instance_session_id"`
	DeliveryID            string `json:"delivery_id"`
	Nonce                 string `json:"nonce"`
	LeaseEpoch            uint64 `json:"lease_epoch"`
	FencingToken          uint64 `json:"fencing_token"`
}

Acknowledgement identifies one host acknowledgement without carrying payload, output, credentials, or signatures.

type AcknowledgementClassification 

type AcknowledgementClassification string

AcknowledgementClassification tells a caller whether an exact acknowledgement is current, retained as superseded, or unknown. 

const (
	// AcknowledgementCurrent means the acknowledgement identifies State.Current exactly.
	AcknowledgementCurrent AcknowledgementClassification = "current"
	// AcknowledgementKnownSuperseded means the acknowledgement identifies a retained earlier delivery exactly and must not revive it.
	AcknowledgementKnownSuperseded AcknowledgementClassification = "known-superseded"
	// AcknowledgementUnknown means a valid acknowledgement is not part of this host-instance lease chain.
	AcknowledgementUnknown AcknowledgementClassification = "unknown"
)

type AcknowledgementResult 

type AcknowledgementResult struct {
	Snapshot       Snapshot
	Found          bool
	Classification AcknowledgementClassification
}

AcknowledgementResult is the recovered snapshot and effect-free classification for one valid acknowledgement. Found is false only when no state exists for the acknowledgement's host-instance session.

type Binding 

type Binding struct {
	HostID                 string         `json:"host_id"`
	HostGeneration         uint64         `json:"host_generation"`
	AssignmentID           string         `json:"assignment_id"`
	Tenant                 string         `json:"tenant"`
	Principal              string         `json:"principal"`
	SandboxID              string         `json:"sandbox_id"`
	OperationID            string         `json:"operation_id"`
	OperationKind          string         `json:"operation_kind"`
	EffectiveSpecDigest    sandbox.Digest `json:"effective_spec_digest"`
	CapabilityDigest       sandbox.Digest `json:"capability_digest"`
	CanonicalRequestDigest sandbox.Digest `json:"canonical_request_digest"`
}

Binding is the immutable, redacted control tuple shared by every delivery in one private boot-probe lease chain. It contains bounded opaque identities and digests, never a signed envelope, request payload, credential, or host path.

type Coordinator 

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

Coordinator composes the private boot-probe v2 state contract with its caller-owned persistence boundary. It only admits already-authenticated state transitions and classifies acknowledgements; it never launches a guest or performs acknowledgement effects.

func NewCoordinator 

func NewCoordinator(store StateStore) (*Coordinator, error)

NewCoordinator constructs a private boot-probe v2 coordinator over one required state store.

func (*Coordinator) AuthorizeLaunch 

func (coordinator *Coordinator) AuthorizeLaunch(ctx context.Context, expected Snapshot, now time.Time) (Snapshot, error)

AuthorizeLaunch atomically records a private launch authorization for the current unexpired delivery or converges expiry to cleanup-pending.

func (*Coordinator) BeginCleanup 

func (coordinator *Coordinator) BeginCleanup(ctx context.Context, expected Snapshot, now time.Time) (Snapshot, error)

BeginCleanup atomically marks the private session non-launchable while cleanup is required.

func (*Coordinator) ClassifyAcknowledgement 

func (coordinator *Coordinator) ClassifyAcknowledgement(ctx context.Context, acknowledgement Acknowledgement) (AcknowledgementResult, error)

ClassifyAcknowledgement recovers the lease chain and classifies one valid acknowledgement without mutating state or acknowledging a host.

func (*Coordinator) ConfirmCleanup 

func (coordinator *Coordinator) ConfirmCleanup(ctx context.Context, expected Snapshot, now time.Time) (Snapshot, error)

ConfirmCleanup atomically records terminal private cleanup confirmation.

func (*Coordinator) Create 

func (coordinator *Coordinator) Create(ctx context.Context, binding Binding, hostInstanceSessionID string, initial Delivery, now time.Time) (Snapshot, bool, error)

Create atomically seals and persists an initial already-authenticated delivery or recovers its identical existing snapshot.

func (*Coordinator) Load 

func (coordinator *Coordinator) Load(ctx context.Context, hostInstanceSessionID string) (Snapshot, bool, error)

Load recovers one canonical private boot-probe v2 snapshot without producing a sandbox effect.

func (*Coordinator) RecordLaunchStarted 

func (coordinator *Coordinator) RecordLaunchStarted(ctx context.Context, expected Snapshot, now time.Time) (Snapshot, error)

RecordLaunchStarted atomically records one irreversible private launch start for the exact authorized current delivery.

func (*Coordinator) RenewAuthenticated 

func (coordinator *Coordinator) RenewAuthenticated(ctx context.Context, expected Snapshot, successor Delivery, now time.Time) (Snapshot, error)

RenewAuthenticated constructs and atomically persists exactly the next already-authenticated delivery from the expected recovery snapshot.

type Delivery 

type Delivery struct {
	EnvelopeID   string    `json:"envelope_id"`
	DeliveryID   string    `json:"delivery_id"`
	Nonce        string    `json:"nonce"`
	IssuedAt     time.Time `json:"issued_at"`
	ExpiresAt    time.Time `json:"expires_at"`
	LeaseEpoch   uint64    `json:"lease_epoch"`
	FencingToken uint64    `json:"fencing_token"`
}

Delivery is the bounded metadata for one already-authenticated control delivery. Nonce is canonical raw base64url text, so encoding differences cannot create distinct delivery identities.

type Lifecycle 

type Lifecycle struct {
	Phase          LifecyclePhase `json:"phase"`
	LaunchDelivery *Delivery      `json:"launch_delivery,omitempty"`
}

Lifecycle is the effect-free irreversible part of one private boot-probe session. LaunchDelivery identifies the delivery that was allowed to start once; it remains nil when cleanup began before any launch authorization.

type LifecyclePhase 

type LifecyclePhase string

LifecyclePhase is one irreversible private boot-probe session lifecycle phase. 

const (
	// LifecyclePrepared means the delivery chain exists but no launch has been authorized.
	LifecyclePrepared LifecyclePhase = "prepared"
	// LifecycleLaunchAuthorized means exactly State.Current was authorized for one possible launch.
	LifecycleLaunchAuthorized LifecyclePhase = "launch-authorized"
	// LifecycleLaunchStarted means the exact authorized current delivery recorded an irreversible launch start.
	LifecycleLaunchStarted LifecyclePhase = "launch-started"
	// LifecycleCleanupPending means future launch is prohibited until the host records cleanup completion.
	LifecycleCleanupPending LifecyclePhase = "cleanup-pending"
	// LifecycleCleanupConfirmed means cleanup completed and this session can never authorize or start another launch.
	LifecycleCleanupConfirmed LifecyclePhase = "cleanup-confirmed"
)

type MemoryStateStore 

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

MemoryStateStore is a deterministic, hermetic StateStore implementation for private boot-probe v2 compound-session tests.

func NewMemoryStateStore 

func NewMemoryStateStore() *MemoryStateStore

NewMemoryStateStore constructs an empty deterministic private boot-probe v2 state store.

func (*MemoryStateStore) CompareAndSwap 

func (store *MemoryStateStore) CompareAndSwap(ctx context.Context, expected Snapshot, successor Session, now time.Time) (Snapshot, error)

CompareAndSwap atomically stores precisely one next compound-session transition of expected or refuses without mutation.

func (*MemoryStateStore) Load 

func (store *MemoryStateStore) Load(ctx context.Context, hostInstanceSessionID string) (Snapshot, bool, error)

Load returns a copied canonical recovery snapshot for one host-instance session.

func (*MemoryStateStore) LoadOrCreate 

func (store *MemoryStateStore) LoadOrCreate(ctx context.Context, initial Session) (Snapshot, bool, error)

LoadOrCreate atomically persists one prepared initial session or returns its identical existing recovery snapshot.

type Session 

type Session struct {
	Version   string    `json:"version"`
	Delivery  State     `json:"delivery"`
	Lifecycle Lifecycle `json:"lifecycle"`
}

Session binds the private lifecycle to its one canonical v2 delivery chain so a durable store can persist both under one CAS record. It is a value object: its transitions return a new Session and never cause a launch or cleanup effect.

func DecodeSession 

func DecodeSession(wire []byte) (Session, error)

DecodeSession reads one canonical private boot-probe v2 compound session.

func NewSession 

func NewSession(delivery State) (Session, error)

NewSession creates a prepared lifecycle bound to an already-valid private boot-probe v2 delivery state.

func (Session) AcceptAuthenticatedSuccessor 

func (session Session) AcceptAuthenticatedSuccessor(successor Delivery, now time.Time) (Session, error)

AcceptAuthenticatedSuccessor advances the delivery chain without letting a renewed delivery reuse a stale launch authorization. A prepared session remains prepared; an authorized-but-not-started session converges to cleanup-pending; terminal cleanup cannot renew.

func (Session) AuthorizeLaunch 

func (session Session) AuthorizeLaunch(now time.Time) (Session, error)

AuthorizeLaunch records that the exact current delivery may start one launch. It is a pure authorization transition; durable CAS and all host effects belong to later adapters.

func (Session) BeginCleanup 

func (session Session) BeginCleanup() (Session, error)

BeginCleanup irreversibly prohibits launch and records that cleanup must be completed. It may be used before launch when authority becomes ambiguous, expired, or revoked.

func (Session) ConfirmCleanup 

func (session Session) ConfirmCleanup() (Session, error)

ConfirmCleanup records the terminal cleanup confirmation after cleanup was required.

func (Session) RecordLaunchStarted 

func (session Session) RecordLaunchStarted(now time.Time) (Session, error)

RecordLaunchStarted records an irreversible launch start only for the exact authorized delivery while it remains current and unexpired. When authorization has expired, it returns cleanup-pending instead of recording a launch start.

func (Session) Validate 

func (session Session) Validate() error

Validate verifies that the lifecycle has no separate delivery identity or legal relaunch path.

type Snapshot 

type Snapshot struct {
	Version uint64
	Session Session
	Wire    []byte
}

Snapshot is one immutable recovery view of a private boot-probe v2 compound session record. Wire is the exact canonical session encoding retained by the store; callers receive a copy.

type State 

type State struct {
	Version               string     `json:"version"`
	Binding               Binding    `json:"binding"`
	HostInstanceSessionID string     `json:"host_instance_session_id"`
	Current               Delivery   `json:"current"`
	Superseded            []Delivery `json:"superseded"`
}

State is the canonical private persisted state for one host-instance session. Superseded is ordered oldest first and retained only to classify delayed exact acknowledgements; it is not a launch queue.

func Decode 

func Decode(wire []byte) (State, error)

Decode reads one canonical private boot-probe v2 state snapshot.

func NewState 

func NewState(binding Binding, hostInstanceSessionID string, initial Delivery, now time.Time) (State, error)

NewState seals one already-authenticated initial delivery under its immutable control binding and host-instance session.

func (State) AcceptAuthenticatedSuccessor 

func (state State) AcceptAuthenticatedSuccessor(hostInstanceSessionID string, successor Delivery, now time.Time) (State, error)

AcceptAuthenticatedSuccessor appends exactly the next authenticated delivery for this same host-instance session. Authentication and durable compare-and-swap are caller-owned; this pure contract neither launches a guest nor stores state.

func (State) ClassifyAcknowledgement 

func (state State) ClassifyAcknowledgement(acknowledgement Acknowledgement) (AcknowledgementClassification, error)

ClassifyAcknowledgement identifies a current, known-superseded, or unknown exact acknowledgement without producing effects.

func (State) Validate 

func (state State) Validate() error

Validate verifies State is one linear, immutable boot-probe delivery chain with no reusable delivery identity.

type StateStore 

type StateStore interface {
	LoadOrCreate(context.Context, Session) (Snapshot, bool, error)
	Load(context.Context, string) (Snapshot, bool, error)
	CompareAndSwap(context.Context, Snapshot, Session, time.Time) (Snapshot, error)
}

StateStore is the private persistence boundary for one host-instance boot-probe v2 compound session. It atomically creates the lifecycle with its delivery chain and admits exactly one validated session transition through compare-and-swap.

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.