home

type EventKind ¶

type EventKind int

EventKind is what the home delivered.

const (
	// GrantAdded carries a signed token to pre-admit (warm the template
	// before the first Clone). fiberd verifies it like any other.
	GrantAdded EventKind = iota
	// GrantRemoved names a grant the home no longer holds. Its running
	// fibers are released and the UID is refused until every token for
	// it has expired, or the home delivers it again.
	GrantRemoved
)

type GrantEvent ¶

type GrantEvent struct {
	Kind  EventKind
	Token []byte // GrantAdded
	UID   string // GrantRemoved
}

type HealthPoll ¶

type HealthPoll struct {
	// Health is marked on every answered round. Required.
	Health *core.SourceHealth
	// Every is the interval between rounds and the timeout of one round.
	Every time.Duration
	// Clock drives the rounds and stamps the health. Required.
	Clock clock.WithTicker
	// Round asks the control plane once. Required.
	Round func(ctx context.Context) error
	// OnError and OnRecovered report transitions. Either may be nil.
	OnError     func(err error)
	OnRecovered func()
	// contains filtered or unexported fields
}

HealthPoll runs a round against a home's control plane every interval and turns the answers into the issuer health the miss codes key on. A round that answers marks the health sync at the clock's now, unless the poll is paused. A round that fails leaves the health alone, so the health goes stale on its own once the control plane has been silent for the stale TTL.

Run is serial. One round runs at a time, and the next waits for it. A round gets one interval to answer, then its context ends with ErrRoundTimeout as the cause. A Round that honours its context returns the context's error, and the poll reports it as ErrRoundTimeout. A Round that ignores its context delays the next round for as long as it runs. An error of the Round's own is reported as it is, even when the interval ran out while it was being returned.

The poll does not log. OnError is called once per distinct error message, OnRecovered once when a round answers after errors, so a home logs each transition once.

func (p *HealthPoll) Once(ctx context.Context) error

func (p *HealthPoll) Run(ctx context.Context)

func (p *HealthPoll) SetPaused(paused bool)

type Home ¶

type Home interface {
	Name() string
	// Grants delivers grants ahead of traffic and removals. A home
	// that delivers nothing returns a nil channel, and grants then arrive only
	// inside Clone requests. On a home that holds a grant of its own,
	// Clone admits that grant instead of the token it carries.
	Grants(ctx context.Context) (<-chan GrantEvent, error)
	// Health is the control-plane liveness the miss codes key on.
	Health() *core.SourceHealth
	// CgroupRoot is the delegated cgroup v2 subtree the runtime may carve.
	CgroupRoot() string
	// PublishReady tells the home's control plane that the grant's
	// template is warm (a readiness gate, a status stream, nothing).
	PublishReady(ctx context.Context, grantUID string, ready bool) error
	// Scope is what this home asserts about where it runs (namespace,
	// service account, DRA claim, job). Stamped on audit records;
	// nil on a standalone host. Scope is visible, never a third validity
	// term: a home that loses it revokes fences (Core.BumpEpoch) or
	// grants (GrantRemoved), and the core keeps min(lease, fence).
	Scope() []core.ScopeClaim
	// Devices provisions the grant's device channel, the devices its
	// engine may drive, and returns how to release it: a static set here,
	// a DRA claim under Kubernetes, the allocation's GRES under Slurm.
	Devices(ctx context.Context, g core.Grant) (core.DeviceChannel, func(), error)
	// Run drives whatever the home needs in the background (issuer polls,
	// watches) until ctx ends.
	Run(ctx context.Context)
}

Home is what cmd/fiberd wires around fiberd.

type ReadyGate ¶

type ReadyGate struct {
	// Publish sends the gate. warm holds the UIDs of the grants with a
	// warm template, sorted, and is empty when none has. Required.
	Publish func(ctx context.Context, warm []string) error
	// contains filtered or unexported fields
}

ReadyGate tracks which grants have a warm template and publishes the one readiness fact a control plane wants, "any template is warm", through Publish. Publish is called on the first PublishReady and whenever that fact flips. A failed publish leaves the published state as it was, so the next PublishReady or the next Republish sends it again.

One publish is in flight at a time and no lock is held across it. A PublishReady that arrives while another is in flight records its change and returns, and the publisher in flight sends the newest state once its call returns. The control plane therefore sees states in the order they were decided, never an older state after a newer one.

The gate does not log. Republish reports whether the outcome changed so the home logs each distinct failure, and the recovery, once.

func (g *ReadyGate) PublishReady(ctx context.Context, grantUID string, ready bool) error

func (g *ReadyGate) Ready() bool

func (g *ReadyGate) Republish(ctx context.Context) (changed bool, err error)

type ScopeLossQueue ¶

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

ScopeLossQueue hands scope-loss reasons to one callback, in the order they were detected, each reason once per lifetime. A home detects a loss inside a poll round and calls Lose. Delivery happens on the one goroutine Run owns, with the context Run was given, so a slow callback (an epoch bump that waits for fibers) never stalls a poll round and outlives the round that found the loss. Reasons detected before OnScopeLost is called wait in the queue and are delivered in order once a callback exists. The queue does not log. Lose reports whether a reason is new so the home can.

The zero value is ready to use.

func (q *ScopeLossQueue) Lose(reason string) bool

func (q *ScopeLossQueue) OnScopeLost(fn func(ctx context.Context, reason string))

func (q *ScopeLossQueue) Pending() int

func (q *ScopeLossQueue) Run(ctx context.Context)