boot

Documentation

Overview

Package boot tracks the agent's startup phases as one monotonically advancing sequence. Each phase records that an externally observable guarantee now holds: once Sequencer.Advance returns, the previous phase's invariant is established.

It is also a cross-goroutine barrier — Sequencer.Await blocks until a named phase is reached, which is how the ghost sweep avoids evicting before the WAL merged. If boot aborts, Sequencer.Fail releases every awaiter rather than leaving them parked.

docs/architecture/boot-and-recovery.md#boot-sequence

Index

• type Phase
  • func (p Phase) String() string
• type Sequencer
  • func New() *Sequencer
  • func (s *Sequencer) Advance(next Phase) error
  • func (s *Sequencer) Await(ctx context.Context, p Phase) error
  • func (s *Sequencer) Current() Phase
  • func (s *Sequencer) Fail(p Phase, err error)

Types

type Phase

type Phase int

Phase identifies a named milestone in the agent's startup sequence. Phases advance monotonically from PhaseInit through PhaseStateRestored; skipping or rewinding is a programmer error.

const (
	// PhaseInit is the implicit starting phase: the sequencer
	// has been constructed but no milestone has been reached.
	PhaseInit Phase = iota

	// PhaseBPFLoaded marks the BPF collection as loaded and
	// validated against the Go-side max-entries constants.
	PhaseBPFLoaded

	// PhaseMetadataReady marks the Neutron cold-start as
	// complete: the LPM trie and mac_tenant_map reflect the
	// cluster's current state and the first packet through the
	// kernel hot path will classify against a populated trie.
	PhaseMetadataReady

	// PhaseAttached marks the TC clsact qdisc and ingress/egress
	// programs as installed. Packets begin classifying after this
	// phase, never before.
	//
	// Boot sequence: docs/architecture/boot-and-recovery.md#boot-sequence
	PhaseAttached

	// PhaseStateRestored marks the WAL load as complete:
	// GlobalState's LastEbpfRaw values are seeded so the first
	// scrape computes deltas correctly. Safe to start the
	// scraper, the WAL flush goroutine, and /metrics after this.
	PhaseStateRestored
)

func (Phase) String

func (p Phase) String() string

String returns the snake-case phase name, suitable for log attributes and (eventually) Prometheus label values.

type Sequencer

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

Sequencer tracks the current boot phase and lets other goroutines block until a phase is reached. Construct with New; the zero value is not usable.

func New

func New() *Sequencer

New returns a sequencer at PhaseInit. Phase-advance events log to slog.Default, which the runtime package configures via logging.Init before Bootstrap runs.

func (*Sequencer) Advance

func (s *Sequencer) Advance(next Phase) error

Advance moves to next, which must be EXACTLY one greater — skipping is a programmer error, so a new phase goes in the enum rather than being jumped over. Closes next's channel, releasing its awaiters.

func (*Sequencer) Await

func (s *Sequencer) Await(ctx context.Context, p Phase) error

Await blocks until phase p has been reached, ctx is cancelled, or a Sequencer.Fail aborts the boot. It returns nil once p is reached (even if a later phase subsequently fails — p's guarantee already holds), ctx.Err() on cancellation, or the Fail error if the boot aborts before p. An out-of-range phase is a programmer error and returns immediately.

func (*Sequencer) Current

func (s *Sequencer) Current() Phase

Current returns the most recently advanced phase. Safe to call from any goroutine.

func (*Sequencer) Fail

func (s *Sequencer) Fail(p Phase, err error)

Fail records that the boot aborted at phase p with err and releases every goroutine blocked in Sequencer.Await for a not-yet-reached phase. Only the first call takes effect; later calls are no-ops, so the earliest (root) failure is the one reported. Safe to call from any goroutine.