core

package
v0.4.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// EventGap marks missing records, from failed writes (Lost names
	// their sequence numbers) or an unreadable line.
	EventGap = "gap"
	// EventCheckpoint signs the hash of the record before it.
	EventCheckpoint = "checkpoint"

	// DefaultCheckpointEvery is how many records a checkpoint covers.
	DefaultCheckpointEvery = 256
)

Events the spool writes itself.

View Source 
const (
	DefaultCreateDeadline = 50 * time.Millisecond
	DefaultResumeDeadline = 2 * time.Second
)

Default runtime deadlines when the caller sets none. A fork is millisecond work; a restore of a parked delta is sub-second work, so the two defaults differ. A caller with tighter needs sets its own.

View Source 
const (
	DefaultPSIShed = 10.0
	DefaultPSIPark = 25.0
)

Default watermarks, in PSI percent, used when a grant's policy leaves them zero. They are deliberately low: the point is to react before the home's own eviction (kubelet's memory.available, a hard memory.max) does, because the ladder can park state and eviction cannot.

View Source 
const (
	DefaultBaseRate = 200
	DefaultRefW     = 256 << 20
)

fiberd's clone rate limit is DefaultBaseRate clones/sec at W -> 0. It halves at DefaultRefW bytes of working set.

View Source 
const (
	// UIDPattern is the Kubernetes DNS-1123 label rule. The UID becomes a
	// cgroup and run-directory name beside kernel files like memory.max,
	// so it must be one plain path segment ("." and ".." never match).
	// Lowercase keeps names distinct on case-insensitive filesystems. The
	// length bound keeps paths under the unix socket limit.
	UIDPattern = `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$`

	// TenantPattern bounds a tenant name to one path segment of letters,
	// digits, ".", "_" and "-", at most 253 characters. The tenant is the
	// first half of the session domain "<tenant>/<class or digest>", so
	// "/" and whitespace are out and the domain splits at its first "/"
	// without ambiguity. A Kubernetes namespace and a Slurm account both
	// fit.
	TenantPattern = `^[A-Za-z0-9][A-Za-z0-9._-]{0,252}$`

	// TemplateDigestPattern is a full lowercase sha256 OCI digest. It is
	// what host.FormatTemplateFlag and the Kubernetes controller's CRD
	// marker require of an OCI digest. Validate itself asks only that a
	// template digest be a usable key into fiberd's template map.
	TemplateDigestPattern = `^sha256:[a-f0-9]{64}$`

	// CallerThumbprintPattern is the form of an RFC 7638 JWK thumbprint.
	// That is a SHA-256 hash in unpadded base64url, which is always 43
	// characters.
	CallerThumbprintPattern = `^[A-Za-z0-9_-]{43}$`
)

The patterns a grant's fields must match. They are exported because an issuer outside this module repeats them as schema literals, such as the Kubernetes controller's CRD markers, and tests that its copies stay equal to these.

View Source 
const DefaultRevokeTTL = 24 * time.Hour

DefaultRevokeTTL is how long a removed grant stays denied past its lease when the home has no -max-lease to bound its tokens by.

View Source 
const MaxPayload = 4096

Variables

View Source 
var (
	ErrPayloadTooLarge = errors.New("fiberd: payload exceeds 4096 bytes")
	ErrDeadline        = errors.New("fiberd: clone missed deadline")
	ErrWrongAudience   = errors.New("fiberd: grant audience is not this home")
	ErrNotReady        = errors.New("fiberd: template not ready on this home")
	// ErrDraining means fiberd got SIGTERM and is parking and ending its
	// fibers before it stops. Every clone is a miss from then on.
	ErrDraining = errors.New("fiberd: home is draining before it stops")
	// ErrVerifyUnavailable is wrapped by a Verifier that cannot decide
	// because its key material is missing or stale, not because the token
	// is bad. That is a reachability problem, so the answer is SHED (back
	// off), never Unauthenticated (give up).
	ErrVerifyUnavailable = errors.New("fiberd: cannot verify offline; key material unavailable")
	// ErrDeltaTooLarge means the session's parked state exceeds the
	// grant's W budget, so it stays put. The Miss names the home that has
	// it.
	ErrDeltaTooLarge = errors.New("fiberd: parked state exceeds w_budget_bytes; not moving it")
	// ErrIncompatible means the session's parked state was made on a
	// platform (architecture, kernel, libc) this home cannot restore. It
	// stays put, and the Miss names the home that has it.
	ErrIncompatible = errors.New("fiberd: parked state was made on an incompatible platform; not moving it")
	// ErrNeedsDevice means the grant needs a device this home's template
	// does not offer. Like a tier gap it is a FailedPrecondition, never a
	// silent CPU-only fiber.
	ErrNeedsDevice = errors.New("fiberd: grant needs a device class this home does not offer")
	// ErrDeviceMismatch means the session's parked device slice was saved
	// by an engine of another class or layout than the grant's engine
	// here, or the grant has no engine here. The session stays in the
	// registry, and like a tier gap it is a FailedPrecondition.
	ErrDeviceMismatch = errors.New("fiberd: parked device state needs an engine of another class or layout; not moving it")
	// ErrNeedsIsolation means the grant is untrusted and this home's
	// runtime does not sandbox fibers from the host kernel. It is a
	// FailedPrecondition, like a tier gap.
	ErrNeedsIsolation = errors.New("fiberd: untrusted grant needs a runtime that isolates tenants")
	// ErrNeedsHandoff means the grant wants handoff and this home does not
	// hand connections to fibers (no -handoff-listen, or a backend that
	// cannot). It is a FailedPrecondition, like a tier gap.
	ErrNeedsHandoff = errors.New("fiberd: handoff grant needs a home that hands connections to fibers")
	// ErrNeedsWorkspace means the grant sets a disk budget and this home's
	// runtime gives fibers no workspace. It is a FailedPrecondition, like
	// a tier gap.
	ErrNeedsWorkspace = errors.New("fiberd: grant with a disk budget needs a runtime that gives fibers a workspace")
	// ErrNoWorkspace means a file call named a fiber whose grant has no
	// disk budget, so the fiber has no workspace.
	ErrNoWorkspace = errors.New("fiberd: the fiber's grant has no workspace (disk_budget_bytes is zero)")
	// ErrDeltaQuota means parking the fiber would take the grant's parked
	// deltas past its quota on this home. The fiber keeps running, and the
	// caller backs off (SHED) or releases something.
	ErrDeltaQuota = errors.New("fiberd: grant's parked deltas would exceed its quota on this home")
	// ErrCallerMismatch means the grant is bound to a client key other
	// than the one the request arrived over.
	ErrCallerMismatch = errors.New("fiberd: grant is bound to another caller's key")
	// ErrUnboundGrant means the home requires bound grants and this one
	// names no caller key.
	ErrUnboundGrant = errors.New("fiberd: grant is not bound to a caller key")
	// ErrHandoffUnbound means a handoff grant names no caller key. A
	// handoff fiber pins its caller's certificate, so the grant needs a
	// caller.
	ErrHandoffUnbound = errors.New("fiberd: handoff grant is not bound to a caller key")
	// ErrNoTenant: a named session was cloned or parked under a grant
	// without a tenant. A named session is filed under its tenant, so
	// without one there is nothing to file it under or to look it up by.
	// It is a FailedPrecondition, like a tier gap. Anonymous fibers are
	// unaffected.
	ErrNoTenant = errors.New("fiberd: named session needs a grant with a tenant")
	// ErrAnonymousPark means Park named a fiber without a session. Its
	// delta could never be resumed, since a resume is a Clone by session
	// name, so nothing is parked. The caller releases the fiber.
	ErrAnonymousPark = errors.New("fiberd: a fiber without a session cannot be resumed, release it instead")
	// ErrSessionRunning means Discard named a session that runs. Its
	// state is in the fiber, not in a delta, so the caller releases the
	// fiber with discard instead.
	ErrSessionRunning = errors.New("fiberd: the session is running, release its fiber with discard instead")
	// ErrSessionUnknown means Discard named a session that is neither
	// parked on this home nor in the delta registry.
	ErrSessionUnknown = errors.New("fiberd: no parked session by that name")
	// ErrNoPool is a Pooler's answer for a grant whose template cannot be
	// restored ahead of its fibers. The refill loop remembers it.
	ErrNoPool = errors.New("pool: the grant's template cannot pool")
	// ErrYielded is a Pooler's answer for a fill it gave up because a
	// clone asked for the runtime meanwhile. The refill loop holds the
	// grant's next fill as it does after a failure.
	ErrYielded = errors.New("pool: the fill yielded to a clone")
)

Core errors.

View Source 
var (
	ErrAudit = errors.New("audit: record not durable")
	// ErrAuditChain means a spool's records do not chain (one was edited,
	// removed or reordered) or a checkpoint's signature does not hold.
	ErrAuditChain = errors.New("audit: spool does not verify")
)

Audit errors.

View Source 
var (
	ErrGrantUnknown = errors.New("ledger: grant not held by this home")
	// ErrGrantExpired means the lease lapsed. Revocation is lease
	// non-renewal, so this is lost capacity, not an auth failure.
	ErrGrantExpired = errors.New("ledger: grant lease expired")
	// ErrGrantRevoked means the home removed the grant. Its tokens
	// are refused until the deny-list entry lapses. Like an expired lease,
	// it is a capacity miss.
	ErrGrantRevoked = errors.New("ledger: grant revoked on this home")
	// ErrGrantChanged means a re-delivery of an admitted grant changes
	// a field other than its lease or its caller. The rest key what the
	// home holds for the grant, so they never change in place.
	ErrGrantChanged = errors.New("ledger: a grant uid may change only its lease and its caller")
	// ErrNeedsTier means the runtime's tier is below the grant's min_tier
	// or what the session needs (a parked delta requires TierCheckpoint).
	// A lesser mechanism never stands in.
	ErrNeedsTier = errors.New("ledger: runtime tier below what the grant or session requires")
	// ErrGrantFull means the grant's running fibers are at fibers.max. The
	// home never mints past the charged block.
	ErrGrantFull = errors.New("ledger: grant at fibers.max, no capacity for a new fiber")
	// ErrFiberUnknown means no fiber by that ID runs in this epoch. Every
	// fiber from before a restart is unknown by construction.
	ErrFiberUnknown = errors.New("ledger: fiber unknown in this epoch")
)

Ledger errors.

View Source 
var ErrPressure = errors.New("pressure: grant is shedding new clones")
View Source 
var ErrRateLimit = errors.New("rate limit: clone rate over f(W), retry later")

ErrRateLimit is backpressure, not failure. A misbehaving router degrades one node, never the fleet. Routers translate it to 429 + Retry-After.

Functions

func DeviceFits 

func DeviceFits(asked, class string, capacity uint64) error

DeviceFits is the class rule. An empty class asked takes any engine, and otherwise the classes must be equal. An engine with no capacity fits nothing. The refusal wraps ErrNeedsDevice and names both classes.

func GrantDeadlines 

func GrantDeadlines(rt Runtime, grantUID string) (create, resume time.Duration)

GrantDeadlines are the grant's create and resume deadlines: what the runtime advises for it (DeadlineAdvisor), else the defaults. They are the one source of a per-grant deadline, for a Clone without one of its own, for a pool fill, and for the runtime's own waits on a fiber, such as a park's wait for the fiber to stop serving.

Types

type Action 

type Action int

Action is the resolved outcome of Clone(S): one verb, three costs. 

const (
	ActCreate Action = iota // S unknown (or anonymous): fork zygote, ms
	ActAttach               // S running: return existing endpoint, ~free
	ActResume               // S parked: restore delta, sub-second
)

func (Action) String 

func (a Action) String() string

type AuditRecord 

type AuditRecord struct {
	Seq     uint64    `json:"seq"`
	Time    time.Time `json:"time"`
	Event   string    `json:"event"` // admit clone attach park release oom expire, gap checkpoint
	Fence   Fence     `json:"fence"`
	Session string    `json:"session,omitempty"`
	FiberID string    `json:"fiber_id,omitempty"`
	Detail  string    `json:"detail,omitempty"`
	// Scope is what the home asserts about where this happened
	// (namespace, service account, DRA claim, ...): facts a reader can
	// check integrity against, empty on a standalone host.
	Scope map[string]string `json:"scope,omitempty"`
	// Lost is the range of sequence numbers a gap stands for, when they
	// were assigned and not written.
	Lost *SeqRange `json:"lost,omitempty"`
	// Signer and Signature are a checkpoint's key ID and its Ed25519
	// signature over the previous record's sequence number and hash.
	Signer    string `json:"signer,omitempty"`
	Signature string `json:"signature,omitempty"`
	// PrevHash is the previous record's Hash. Hash is the SHA-256 of this
	// record with Hash empty. Both are empty before the chain started.
	PrevHash string `json:"prev_hash,omitempty"`
	Hash     string `json:"hash,omitempty"`
}

AuditRecord is one line of the spool. Every state transition writes one record carrying the fence before the caller is acked.

type Auditor 

type Auditor interface {
	Append(ctx context.Context, d Durability, rec AuditRecord) error
}

Auditor records state transitions. Under Sync, Append must not return until the record is durable on local disk. The caller acks after it.

type Checkpoints 

type Checkpoints struct {
	KeyID string
	Key   ed25519.PrivateKey
	// Every is the number of records between checkpoints. Zero means
	// DefaultCheckpointEvery. A spool also writes one on Close.
	Every int
}

Checkpoints is the key a spool signs checkpoints with and how often.

type CloneRequest 

type CloneRequest struct {
	GrantJWT []byte        // the signed grant; verified offline
	Session  string        // optional: "" = anonymous fiber
	Deadline time.Duration // hard budget for the runtime work
	Payload  []byte        // opaque, size-capped, delivered as data, never config
	// CallerThumbprint is the thumbprint of the key in the client
	// certificate the request arrived over, and CallerCert is that
	// certificate as DER.
	CallerThumbprint string
	CallerCert       []byte
}

CloneRequest is the ENTIRE clone-time surface. Admission completeness is structural, not policy: there is no field with which to shape a workload. Everything executable — image, command, env, mounts, security context, resources — was fixed by the template admitted at grant creation.

type CloneResponse 

type CloneResponse struct {
	FiberID  string
	Endpoint string
	Fence    Fence
	Kind     Action
	// RoutingKey, ServerKeySHA256 and ServerCert are set for a handoff
	// fiber. They are the TLS server name to send to Endpoint, the pin of
	// the key the fiber must present and the fiber's certificate as DER.
	RoutingKey      string
	ServerKeySHA256 string
	ServerCert      []byte
}

type CloneSource 

type CloneSource int

CloneSource selects the birth mechanism for a fiber. 

const (
	SourceZygote CloneSource = iota // fork the warm template
	SourceDelta                     // restore a parked per-fiber delta
)

type CloneSpec 

type CloneSpec struct {
	Grant    Grant
	Source   CloneSource
	Ref      string // delta ref when Source == SourceDelta
	Fence    Fence
	Deadline time.Duration // hard budget: exceeding it is an error, not a late fiber
	Payload  []byte        // opaque data handed to the fiber at birth
	Session  string        // the session the caller named, "" for an anonymous fiber
	// CallerCert is the DER certificate the clone arrived under, the one
	// a fresh handoff fiber is told to accept. A resumed fiber holds its
	// caller already and ignores it.
	CallerCert []byte
}

CloneSpec is everything the runtime needs to birth one fiber. Grant carries the template digest and the W budget; Fence is the identity the child adopts after the fork, never before.

type Core 

type Core struct {
	// NodeID is this home's identity; a grant's audience must match it.
	// Empty disables the check (tests).
	NodeID string
	// SelfAdmitUID is the one grant UID this home self-admits on Clone.
	// Empty admits any verified grant that names this home. Delivered
	// grants are not subject to it.
	SelfAdmitUID string
	// RequireBoundGrants refuses grants without a caller key binding. Set
	// it whenever the transport is mutual TLS.
	RequireBoundGrants bool

	Ledger    *Ledger
	RateLimit *RateLimit
	Runtime   Runtime
	Audit     Auditor
	Verify    Verifier
	Health    *SourceHealth
	// Pressure, when set, is consulted before any new fiber: a grant that
	// is shedding answers SHED. Nil means no pressure input.
	Pressure *PressureController
	// Store, when set, receives a ledger snapshot after every transition
	// a restart needs, so boot can re-admit grants and remember parked
	// sessions.
	Store *SnapshotStore
	// MobilityBudget overrides the grant's w_budget_bytes as the largest
	// parked state this home will pull (tests, or a home-level cap).
	MobilityBudget func(g Grant) uint64

	// StatusInterval paces the W sampler and the Watch stream. Zero means
	// one second.
	StatusInterval time.Duration

	// Scope, when set, is what the home asserts about where this fiberd
	// runs (namespace, service account, DRA claim, ...); it is stamped
	// on every audit record. Nil on a standalone host.
	Scope func() []ScopeClaim
	// Devices, when set, provisions a grant's device channel (the devices
	// its engine may use) before its template is warmed, and returns how
	// to release it. Nil means grants get no devices.
	Devices func(ctx context.Context, g Grant) (DeviceChannel, func(), error)
	// Epoch, when set, lets BumpEpoch revoke every fence in place.
	Epoch *EpochStore
	// Revoked, when set, is the deny-list Remove adds to and Admit
	// refuses from. Nil means a removed grant is re-admitted by the next
	// Clone that presents a valid token for it.
	Revoked *Revoked
	// contains filtered or unexported fields
}

Core wires the subcomponents. One per home instance; the same struct everywhere — only the injected Verifier, Runtime and health source vary.

func (*Core) Admit 

func (a *Core) Admit(ctx context.Context, g Grant) (StatusCode, error)

Admit records a verified grant and warms its template. Concurrent admissions of the same UID wait for the first and share its result. One that carries a longer lease, or finds the first failed, then admits itself. A second delivery of an already-admitted grant refreshes it in place, unless it changes the tenant, template or session class.

func (*Core) BumpEpoch 

func (a *Core) BumpEpoch(ctx context.Context, reason string) (uint64, error)

BumpEpoch is scope loss without a restart: the home has learned that what everything was minted under is gone (its namespace, its service-account issuer, a DRA claim) while fiberd lives. The epoch advances and is persisted, every running fiber is released with an audit record naming the reason, and every fence minted before is invalid from here: Park and Release answer NotFound, new clones carry the new epoch. Grants stay admitted and parked sessions keep their deltas; a home that lost a grant's own scope revokes that grant too.

func (*Core) Clone 

func (a *Core) Clone(ctx context.Context, req CloneRequest) (CloneResponse, StatusCode, error)

Clone is the warm path. Every hop below is home-local memory or disk.

func (*Core) Discard 

func (a *Core) Discard(ctx context.Context, req DiscardRequest) (StatusCode, error)

Discard deletes a parked session's delta, here and in the shared store, and forgets the session. The next Clone of it creates.

  • Parked here. The published copy is withdrawn first, then the local delta goes with the port it kept, and the session is forgotten.
  • Parked here but claimed elsewhere since. The stale copy goes as Clone drops it, and the store is asked as for an unknown session.
  • Running here. Refused, since its state is in the fiber. The caller releases the fiber with discard.
  • Unknown here. The store's copy is deleted while it is the one found, as a claim deletes it. Not in the store, or no store, is NotFound.

It runs under the session's gate, so a park or resume in flight finishes first.

func (*Core) Drain 

func (a *Core) Drain(ctx context.Context) DrainReport

Drain readies the home to stop. From its first line every Clone, attach included, is a DeferredFallback miss with ErrDraining, and the refill loop starts nothing. A drain is final. Nothing clears it, since the home is about to stop.

Then every running fiber is parked or ended, named sessions first, a few at a time. A named session is parked with sync, so its delta is durable and published before fiberd exits. An anonymous fiber has nothing to resume and is released. A fiber that is gone by the time the drain reaches it, parked by the pressure ladder or dead on its own, is skipped. Once ctx ends no more are started, and the rest count as Left. The calls under way carry ctx, so they end with it.

The park and release records are the audit trail. The drain writes no record of its own.

func (*Core) DrainPool 

func (a *Core) DrainPool(grantUID string, n int) int

DrainPool discards up to n of the grant's pooled sandboxes and returns how many went. The pressure ladder calls it before it parks a fiber.

func (*Core) Draining 

func (a *Core) Draining() bool

Draining reports whether Drain has been called.

func (*Core) OnExit 

func (a *Core) OnExit(ctx context.Context, ex FiberExit)

OnExit records a fiber that died without Park or Release. The slot is freed and an audit record written. Run feeds it from Runtime.Exits, and a Clone that commits replays an exit held for it. An exit for a fiber not yet committed is held until its Clone commits.

func (*Core) Park 

func (a *Core) Park(ctx context.Context, fiberID string, sync bool) (string, StatusCode, error)

Park checkpoints a named session's delta and frees its running tier. An anonymous fiber is refused as Invalid, since nothing could resume it.

The ledger follows the runtime. Once Runtime.Park returns a ref, the delta exists, so the session is parked in the ledger even if a later step fails. Otherwise the slot leaks and the delta is orphaned. A failed sync audit is returned only after the snapshot and watchers see it.

func (*Core) Reconcile 

func (a *Core) Reconcile(ctx context.Context, snap Snapshot) (ReconcileReport, error)

Reconcile is the boot step between epoch++ and opening the warm path.

  1. Each unexpired grant whose token verifies again is re-admitted and its template warmed again, because the old zygote died with the old fiberd process. An entry whose token fails, names another grant or home, or is missing is dropped. An entry the verifier cannot check yet is held. It is not admitted, but it stays in the snapshot for a redelivery or a later boot.
  2. Each parked session whose delta still exists is remembered, so a Clone(S) after restart resumes it under the new epoch.
  3. Each fiber the runtime still reports is from a prior epoch and is killed. Nothing minted before the restart validates after it.
  4. Each delta on the runtime's disk that no parked session names is removed, since nothing can resume it.

Reality wins over the snapshot at every step. The snapshot is a file on the home's disk, so only a grant's signature re-admits it, never the file.

func (*Core) Redeliver 

func (a *Core) Redeliver(ctx context.Context, grantUID string)

Redeliver lifts a removed grant's denial when the home delivers it again (GrantAdded). The home is the authority. A token that only arrives in a Clone request never lifts it.

func (*Core) Release 

func (a *Core) Release(ctx context.Context, fiberID string, discard bool) (StatusCode, error)

Release destroys a fiber and frees its name. discard also drops the delta the session was resumed from, here and in the store. The ledger knows that delta, not the runtime, since a park stores it under the parked incarnation and the running one has another fence. As in Park, a sync audit record that fails after the ledger changed is reported only after the snapshot and the watchers have seen the change.

func (*Core) Remove 

func (a *Core) Remove(ctx context.Context, grantUID string)

Remove is the home taking a grant away (GrantRemoved). The UID is denied until every token for it has expired. The grant is yielded so its running fibers stop now, not at lease expiry. Parked deltas stay on disk but cannot resume here while the UID is denied. They last until the next boot only. Reconcile drops a session whose grant it does not admit again and the sweep removes its delta, since the ledger keys a session by grant UID. Only a copy published to the registry outlives the grant, for another grant of the same tenant to claim.

func (*Core) Revoke 

func (a *Core) Revoke(grantUID string)

Revoke drops a grant and releases its device channel. Remove, the reaper and the ladder's last rung all go through it. It releases no fibers and denies nothing. Yield and Remove do that.

func (*Core) Run 

func (a *Core) Run(ctx context.Context)

Run drives the background loops until ctx ends: fiber exits from the runtime, the W sampler that feeds the ledger and the rate limit, and on a Pooler the refill loop.

func (*Core) Sweep 

func (a *Core) Sweep(ctx context.Context) int

Sweep is the lease reaper's step: every admitted grant whose lease has lapsed is yielded (fibers released, grant revoked). Parked deltas are kept; they are the only state that cannot be rebuilt.

func (*Core) Watch 

func (a *Core) Watch(ctx context.Context) <-chan []Status

Watch streams the per-grant status: on every change and at least every StatusInterval. The channel closes when ctx ends.

func (*Core) Yield 

func (a *Core) Yield(ctx context.Context, grantUID string, reason string)

Yield is the ladder's last rung and the reaper's verb: the grant is revoked and every running fiber under it is released, each with its audit record. Parked deltas stay, since they are the only state that cannot be rebuilt, and a valid token presented again re-admits the grant and resumes them. Only Remove denies it. They last until the next boot only. Reconcile drops a session whose grant it does not admit again and the sweep removes its delta, since the ledger keys a session by grant UID. Only a copy published to the registry outlives the grant, for another grant of the same tenant to claim.

type DeadlineAdvisor 

type DeadlineAdvisor interface {
	DefaultDeadlines(grantUID string) (create, resume time.Duration)
}

DeadlineAdvisor is implemented by runtimes whose create or resume is slower than a process fork: what a Clone without an explicit deadline is given, for the grant named, since a runtime may size it from what it measured when the grant's template warmed. The caller's own deadline is always honoured as is.

type DeltaChecker 

type DeltaChecker interface {
	HasDelta(ref string) bool
}

DeltaChecker is implemented by runtimes that can say whether a parked delta ref still exists. Without it, parked sessions are restored from the snapshot on trust.

type DeltaDeleter 

type DeltaDeleter interface {
	DeleteDelta(ctx context.Context, g Grant, session, handle string) (remote string, removed bool, err error)
}

DeltaDeleter is implemented by runtimes that can delete a session's published delta from the shared store without pulling it. handle is the RemoteDelta.Handle FindDelta returned, and the delete happens only while the store still holds it, as a claim's does. removed is false when the session is gone from the store or was parked again meanwhile. remote names what was deleted, for the audit record.

type DeltaDiscarder 

type DeltaDiscarder interface {
	DiscardDelta(ctx context.Context, deltaRef string) error
}

DeltaDiscarder is implemented by runtimes that can drop a local delta ref nothing will resume, such as a claim that found the session already here. Without it the copy is left in place and logged.

type DeltaFinder 

type DeltaFinder interface {
	FindDelta(ctx context.Context, g Grant, session string) (RemoteDelta, bool, error)
	ClaimDelta(ctx context.Context, g Grant, session string, rd RemoteDelta) (deltaRef string, err error)
	// Owned reports whether a locally parked delta is still ours: false
	// when another home has claimed the session since we published it.
	Owned(ctx context.Context, deltaRef string) bool
}

DeltaFinder is implemented by runtimes that can look a session up in the shared store and bring its delta here. Claim pulls the delta (and, if needed, the parent checkpoint it depends on), makes the remote copy unavailable to others, and returns a local delta ref for SourceDelta.

FindDelta may return a *RemoteMiss as its error when the session exists but this home must not take it (the state was made on an incompatible platform); fiberd turns that into a miss naming the preferred home. One wrapping ErrDeviceMismatch is a FailedPrecondition instead. Any other error means the store is unreachable.

type DeltaPublisher 

type DeltaPublisher interface {
	PublishDelta(ctx context.Context, deltaRef string, g Grant, session string) (remote string, err error)
}

DeltaPublisher is implemented by runtimes that can put a parked delta where other homes can find it. fiberd calls it after every park of a named session; the returned handle is remembered with the session.

type DeltaRetirer 

type DeltaRetirer interface {
	RetireDelta(ctx context.Context, deltaRef string) error
}

DeltaRetirer is implemented by runtimes that can withdraw a delta's published copy. fiberd calls it once the session resumes here, so the copy in the store no longer names state another home may take or a later Clone may fall back to, and again before a local delta is discarded. A delta never published, or whose tag a later park has replaced, is left alone.

type DeltaSweeper 

type DeltaSweeper interface {
	SweepDeltas(ctx context.Context, keep []string) (removed int, err error)
}

DeltaSweeper is implemented by runtimes that keep parked deltas on local disk. fiberd calls it once at boot, after the parked sessions are restored, with every delta ref a parked session names. The runtime removes every delta it holds that keep does not name, which no session can resume, and reports how many.

type DeviceAware 

type DeviceAware interface {
	AttachDevices(grantUID string, fc DeviceChannel)
}

DeviceAware is implemented by runtimes that pass a grant's device channel to its warm instance (as the engine's device environment).

type DeviceBudget 

type DeviceBudget struct {
	Bytes uint64
	Class string // "gpu", "sim" (the reference engine's simulated device); "" = any
}

DeviceBudget is the per-fiber slice of the grant's engine device state a fiber may hold (its share of a KV cache, of VRAM): the device-side twin of WBudgetBytes. Zero bytes means the grant needs no device.

type DeviceCapable 

type DeviceCapable interface {
	DeviceOffer(grantUID string) (class string, capacity uint64)
}

DeviceCapable is implemented by runtimes that start a device engine for a grant, which holds device state for its fibers and reports their slices. DeviceOffer is the class and capacity the grant's engine declared before READY, and capacity 0 when the grant has none. A grant with a device budget is admitted only where DeviceFits holds.

type DeviceChannel 

type DeviceChannel struct {
	Kind    string   // "static", "dra", "gres", "" for none
	Devices []string // device paths or ids as the engine expects them
	Detail  string   // the claim, the allocation: for the audit record
}

DeviceChannel is what a home provisions for a grant's engine: the devices it may drive. Standalone: a static set; Kubernetes: a DRA claim; Slurm: the allocation's GRES. It is grant-scoped and released with the grant; nothing per fiber refers to it except through its fence.

type DeviceEngine 

type DeviceEngine struct {
	Grant    string `json:"grant"`
	Up       bool   `json:"up"`
	Class    string `json:"class"`
	Layout   string `json:"layout"`
	Version  string `json:"version"`
	GPU      string `json:"gpu"`
	CC       string `json:"cc"`
	Driver   string `json:"driver"`
	Capacity uint64 `json:"capacity"`
	Used     uint64 `json:"used"`
}

DeviceEngine is one grant's engine as it declared itself. Up is false while it restarts. A fact the engine has not declared is "" or 0.

type DeviceEvent 

type DeviceEvent struct {
	Seq        uint64  `json:"seq"`
	T          string  `json:"t"`
	Kind       string  `json:"kind"`
	Grant      string  `json:"grant"`
	Session    string  `json:"session"`
	Fence      string  `json:"fence"`
	DeltaBytes uint64  `json:"delta_bytes"`
	SliceBytes uint64  `json:"slice_bytes"`
	MS         float64 `json:"ms"`
}

DeviceEvent is one park that saved a device slice (Kind "park", MS the SAVE time) or one resume that restored one (Kind "restore", MS the RESTORE time). Seq rises from 1 per fiberd process. DeltaBytes is the delta's W bytes at a park and 0 at a restore. Session is "" when the fiber is anonymous.

type DeviceReport 

type DeviceReport struct {
	Engines []DeviceEngine `json:"engines"`
	Events  []DeviceEvent  `json:"events"`
}

DeviceReport is the home's engines, sorted by grant, and its device events after a seq, oldest first. Neither list is nil, so both encode as [] when empty.

type DeviceReporter 

type DeviceReporter interface {
	DeviceReport(since uint64) DeviceReport
}

DeviceReporter is implemented by runtimes that start device engines. fiberd serves its report as GET /device on the admin socket. since is the last event seq the caller has seen, 0 for every event held. A runtime that does not implement it has no engine to report.

type DiscardRequest 

type DiscardRequest struct {
	GrantJWT []byte // the signed grant; verified offline
	Session  string
	// CallerThumbprint is the thumbprint of the key in the client
	// certificate the request arrived over.
	CallerThumbprint string
}

DiscardRequest names a parked session to delete. It carries the grant as CloneRequest does, since a parked session has no fiber to name.

type DrainReport 

type DrainReport struct {
	Parked    int // named sessions parked
	Published int // of those, the ones whose delta was published
	Shed      int // anonymous fibers released
	Failed    int // a park or release that returned an error, the fiber still running
	Left      int // fibers the drain did not reach before its context ended
}

DrainReport is what a drain did with the fibers it found running.

func (DrainReport) String 

func (r DrainReport) String() string

type Durability 

type Durability int

Durability selects when the audit record for an operation must be durable. It is chosen per grant and priced as activation latency. 

const (
	DurabilityUnspecified Durability = iota
	// BestEffort appends the record and acks the caller without an fsync.
	// A crash can lose records the OS has not flushed yet.
	BestEffort
	// Sync acks the caller only once the record is durable on local disk.
	Sync
)

type EndpointMode 

type EndpointMode int

EndpointMode is how callers reach a grant's fibers. 

const (
	// EndpointDirect means each fiber listens on its own endpoint.
	EndpointDirect EndpointMode = iota
	// EndpointHandoff means fiberd accepts each connection and passes
	// it to the fiber, which never listens.
	EndpointHandoff
)

func ParseEndpointMode 

func ParseEndpointMode(s string) (EndpointMode, error)

ParseEndpointMode accepts the proto names, case-insensitively.

func (EndpointMode) String 

func (m EndpointMode) String() string

type EpochStore 

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

EpochStore persists fiberd's incarnation counter. The epoch file is the only state that must never be lost silently: on any read failure the safe response is a large forward jump (timestamp-derived), which preserves the monotonicity guarantee at the cost of invalidating fences that were already invalid in spirit.

func OpenEpochStore 

func OpenEpochStore(dir string) (*EpochStore, error)

func (*EpochStore) Bump 

func (s *EpochStore) Bump() (uint64, error)

Bump advances the epoch without a restart: what a home does when the scope everything was minted under is gone while fiberd lives (a rotated service-account issuer, a released DRA claim). Every fence minted before is invalid from the moment the new value is durable.

func (*EpochStore) Current 

func (s *EpochStore) Current() uint64

type Fence 

type Fence struct {
	GrantUID string
	Epoch    uint64 // fiberd run, raised on every start
	Seq      uint64 // fiber incarnation within (grant, epoch)
}

Fence identifies one incarnation of a fiber. It is minted fresh on every resume and create, never reused, and every credential and claim is scoped to it: nothing outlives min(lease TTL, fence).

func ParseFence 

func ParseFence(s string) (Fence, error)

ParseFence is the inverse of String: "grant/epoch/seq". Fiber IDs on the wire are fence strings, so this is how a runtime or a home gets back to the triple.

func (Fence) Newer 

func (f Fence) Newer(o Fence) bool

Newer reports whether f supersedes o for the same grant. A caller holding an older fence is detectably stale regardless of which path it raced.

func (Fence) String 

func (f Fence) String() string

type FiberExit 

type FiberExit struct {
	FiberID string
	Reason  string // "oom" | "exit" | "signal"
	Detail  string
}

FiberExit is reported when a fiber dies on its own: the kernel killed it for exceeding its W budget (Reason "oom"), it exited, or was signalled.

type FiberHandle 

type FiberHandle struct {
	ID       string
	Endpoint string // host:port or unix socket path
	Pooled   bool   // born from a sandbox restored ahead of the clone
}

FiberHandle is what the runtime knows about a running fiber. Endpoint is returned directly to the caller; fibers never join any service registry.

type FiberInfo 

type FiberInfo struct {
	ID      string
	Session string // "" for anonymous
	WUsed   uint64
}

FiberInfo is what the ladder needs to pick a victim.

type FiberStats 

type FiberStats struct {
	WUsedBytes uint64
	// DeviceUsedBytes is the fiber's slice of the engine's device state,
	// as the engine reports it; 0 when the grant has no device.
	DeviceUsedBytes uint64
}

FiberStats is the runtime's measurement of one fiber. WUsedBytes is the dirtied working set: the fiber's private pages since fork.

type FileInfo 

type FileInfo struct {
	// Path is relative to the workspace, with forward slashes.
	Path string
	// Size is the apparent size in bytes, zero for a directory.
	Size int64
	// Mode holds the permission bits, and fs.ModeDir for a directory.
	Mode fs.FileMode
	// ModTime is the last modification time.
	ModTime time.Time
	// SHA256 is the content hash, set by Upload only.
	SHA256 []byte
}

FileInfo describes one entry of a fiber's workspace.

type FileReader 

type FileReader interface {
	io.ReadCloser
	Info() FileInfo
}

FileReader is a downloaded file, its bytes and what it was when opened.

type FileStore 

type FileStore interface {
	// Upload writes one regular file of size bytes read from r, with
	// the permission bits of mode, checked against sum when it is
	// not nil. Nothing of it appears until every check passed.
	Upload(ctx context.Context, fiberID, path string, size int64, mode fs.FileMode, sum []byte, r io.Reader) (FileInfo, error)
	// Download opens one regular file at offset. The reader ends at
	// the size the file had when opened.
	Download(ctx context.Context, fiberID, path string, offset int64) (FileReader, error)
	// ListFiles lists the regular files and directories of one
	// directory, "" for the workspace itself.
	ListFiles(ctx context.Context, fiberID, dir string) ([]FileInfo, error)
}

FileStore is implemented by runtimes that hold a workspace per fiber and move files into and out of it from the host side, never through the fiber. Paths are relative to the workspace. A fiber this runtime does not know answers ErrFiberUnknown, and one without a workspace ErrNoWorkspace. Any other error wraps a sentinel of the workspace file layer (pkg/runtime/host/wsfs) or fs.ErrNotExist, which the transport maps to its codes.

type Grant 

type Grant struct {
	UID            string
	Issuer         string // OIDC issuer URL; also what Miss.issuer reports
	Audience       string // the home that may exercise this grant
	TemplateDigest string // OCI digest of the zygote artifact or image
	// Tenant is who the grant belongs to at the issuer (a Kubernetes
	// namespace, a Slurm account). It is the first half of the session
	// domain: a parked session is filed under it, so another tenant's
	// grant on the same template never finds it. Empty means the grant
	// runs anonymous fibers only.
	Tenant       string
	FiberMax     int // <= 0 means unlimited (ceiling is the cgroup only)
	FiberWarm    int
	WBudgetBytes uint64 // per-fiber dirtied working set ceiling; 0 = unlimited
	MinTier      Tier
	LeaseExpiry  time.Time // zero = no expiry
	Policy       Policy
	DeviceBudget DeviceBudget
	// DiskBudgetBytes is the per-fiber workspace ceiling. Zero means the
	// grant's fibers get no workspace and every file call on them is
	// refused.
	DiskBudgetBytes uint64
	// CallerThumbprint is the RFC 7638 thumbprint of the one client key
	// the grant may be presented over, the token's cnf jkt.
	CallerThumbprint string
	// Token is the signed grant this value was verified from. fiberd
	// sets it on admit so the ledger snapshot carries the proof, not only
	// the claims. Boot verifies every entry's token again before
	// re-admitting it and drops an entry without one. A Verifier leaves it
	// empty.
	Token string
}

Grant is the home-invariant, proto-free twin of api/grant/v1 CapacityGrant. It is what a Verifier returns after checking the signed grant offline, and what the ledger stores. Its authenticated arrival is the proof that admission and billing already happened; nothing on the warm path re-checks that.

func (Grant) Expired 

func (g Grant) Expired(now time.Time) bool

Expired reports whether the lease has lapsed at now. Revocation is lease non-renewal: an expired grant is treated as capacity the home no longer holds, which is a miss keyed on control-plane health, not an auth error.

func (Grant) SessionDomain 

func (g Grant) SessionDomain() (string, error)

SessionDomain is the namespace a session name lives in when it is parked and when it moves between homes: the grant's tenant, then its session_class when the issuer set one, else the template digest. Two homes each hold their own grant; what they share is the tenant and the template (a session's state is a delta over its pages) or an issuer-chosen class. Grant UIDs cannot stand in for the tenant, because a session moves between homes whose grants differ. A grant without a tenant has no domain, so nothing named is ever filed under it or looked up for it.

func (Grant) Validate 

func (g Grant) Validate() error

Validate is the single check a grant passes before an issuer signs it. It reports every fault at once, each as a sentence that names the field in lowerCamelCase, the way a Kubernetes field path does.

Some fields may be left unset.

  • An empty Tenant is allowed. Such a grant runs anonymous fibers only.
  • An empty TemplateDigest or CallerThumbprint is allowed. The home then serves its default template, and the grant is not bound to a caller key.
  • A zero LeaseExpiry is allowed and means the lease never expires.
  • A zero FiberMax is allowed, since Grant documents it as unlimited. Only a negative one or one above math.MaxUint32 is refused.

A set TemplateDigest need not be a real sha256 digest. fiberd treats it as an opaque key into its -template digest=command map, so keys like "default", "sha256:conform" or "team-a/counter" work. It must be one token usable as that key, with no whitespace and no "=".

Validate does not check Issuer or Audience. The issuer sets the first and Sign refuses a grant without the second.

type HandoffRouter 

type HandoffRouter interface {
	HandsOff() bool
	HandoffRoute(fiberID string) (routingKey, serverKeySHA256 string, serverCert []byte, ok bool)
}

HandoffRouter is implemented by runtimes that route callers' connections to fibers (endpoint mode handoff). HandsOff reports whether this home can, given its backend and configuration. HandoffRoute returns a handoff fiber's routing key, which the caller sends as the TLS server name, the pin of the key the fiber serves with and the DER certificate it presents.

type Isolation 

type Isolation int

Isolation is whether the issuer trusts the grant's code with the host kernel. Unspecified is untrusted. 

const (
	IsolationUnspecified Isolation = iota
	// Untrusted means only a runtime that sandboxes fibers from the host
	// kernel (an Isolator reporting true) may serve the grant.
	Untrusted
	// Trusted means any runtime may serve the grant, even one whose
	// fibers share the host kernel and fiberd's uid.
	Trusted
)

func ParseIsolation 

func ParseIsolation(s string) (Isolation, error)

ParseIsolation accepts the proto names, case-insensitively.

func (Isolation) String 

func (i Isolation) String() string

func (Isolation) Untrusted 

func (i Isolation) Untrusted() bool

Untrusted reports whether i requires an isolating runtime.

type Isolator 

type Isolator interface {
	IsolatesTenants() bool
}

Isolator is implemented by runtimes that can say whether their fibers are sandboxed from the host kernel (a user-space kernel, a micro-VM). An untrusted grant is admitted only where this answers true. A runtime that does not implement it does not isolate.

type Ledger 

type Ledger struct {

	// Now is the clock used for lease expiry. Tests inject it.
	Now func() time.Time
	// contains filtered or unexported fields
}

Ledger is the home-authoritative record of grants and sessions. It is a cache of reality: at startup it is rebuilt from Runtime.List reconciled against the on-disk snapshot, and discrepancies resolve in favor of what is actually running (Phase 3.5 wires the snapshot).

func NewLedger 

func NewLedger(epoch uint64) *Ledger

func (*Ledger) AdmitGrant 

func (l *Ledger) AdmitGrant(g Grant)

AdmitGrant records a verified grant. Its authenticated arrival IS the proof that admission and quota already happened; nothing is re-checked on the warm path. Idempotent on the UID: a re-delivery refreshes the mutable fields in place and never resets nextSeq (fences would be reminted) or live (the ceiling would be corrupted). A grant admitted again after a revocation continues where it left off.

func (*Ledger) BumpEpoch 

func (l *Ledger) BumpEpoch(epoch uint64)

BumpEpoch moves the ledger to a new epoch in place: every fence minted from here on carries it, and every fence minted before is stale by construction. fiberd releases the running fibers after this call, and a clone in flight cannot commit under the old epoch. Parked sessions keep their deltas and resume under the new epoch.

func (*Ledger) Epoch 

func (l *Ledger) Epoch() uint64

func (*Ledger) Fiber 

func (l *Ledger) Fiber(fiberID string) (Fence, bool)

Fiber returns the fence of a running fiber, or false if the ID is not known in this epoch.

func (*Ledger) FiberSession 

func (l *Ledger) FiberSession(fiberID string) string

FiberSession is the session name a running fiber carries, "" for an anonymous or unknown fiber.

func (*Ledger) FibersOf 

func (l *Ledger) FibersOf(grantUID string) []FiberInfo

FibersOf lists the running fibers of one grant with their session name and last sampled W, for the pressure ladder.

func (*Ledger) ForgetSession 

func (l *Ledger) ForgetSession(grantUID, session string)

ForgetSession drops a parked session (its delta was claimed elsewhere).

func (*Ledger) Grant 

func (l *Ledger) Grant(uid string) (Grant, bool)

Grant returns the admitted grant, if any.

func (*Ledger) GrantBoundTo 

func (l *Ledger) GrantBoundTo(uid, thumbprint string) bool

GrantBoundTo reports whether the admitted grant uid is bound to the client certificate with this thumbprint. An unknown grant is bound to nobody.

func (*Ledger) OnFiberExit 

func (l *Ledger) OnFiberExit(fiberID string) (fence Fence, session, deltaRef string, ok bool)

OnFiberExit records a fiber that died on its own (OOM, exit, signal). The slot is freed and a named session is forgotten: its state is gone, and pretending it is parked would resume nothing. Returns the fence the fiber held and the session name, for the audit record, and the delta the fiber was resumed from, for a discard.

func (*Ledger) OnPark 

func (l *Ledger) OnPark(fiberID, deltaRef string) (session, superseded string)

OnPark records a successful runtime Park: the fiber leaves the running tier (freeing its slot) and, for a named session, the delta ref is kept so a later Clone(S) resolves to ActResume. Returns the session name ("" for an anonymous fiber, whose delta nobody can ask for) and the delta the parked incarnation was resumed from, which this park supersedes ("" after a create).

func (*Ledger) OnRelease 

func (l *Ledger) OnRelease(fiberID string) (session, deltaRef string)

OnRelease records a successful runtime Release: the slot is freed and the session name, if any, is forgotten. Returns that name and the delta the released incarnation was resumed from, for a discard ("" when there is none).

func (*Ledger) PoolRoom 

func (l *Ledger) PoolRoom(grantUID string) int

PoolRoom is how many more sandboxes the grant's pool may take: up to fibers.warm, and never past fibers.max together with the running fibers.

func (*Ledger) RestoreParked 

func (l *Ledger) RestoreParked(s SessionSnapshot) bool

RestoreParked re-registers a parked session from a snapshot or a claim from another home. Its old fence only records lineage, because Resume mints a new one. It returns false when the grant is not admitted or the ledger already holds the session, since a parked entry written over a live one would resume the session twice.

func (*Ledger) RevokeGrant 

func (l *Ledger) RevokeGrant(uid string)

RevokeGrant drops the grant. Fibers under it drain by lease non-renewal; the reaper (Phase 3.5) tears them down. The last minted seq is kept for a re-admission.

func (*Ledger) RunningFibers 

func (l *Ledger) RunningFibers() []string

RunningFibers lists the IDs of every running fiber, for the sampler.

func (*Ledger) SessionState 

func (l *Ledger) SessionState(grantUID, session string) (SessionState, string, bool)

SessionState reports a named session's state, if the ledger knows it.

func (*Ledger) SetFiberW 

func (l *Ledger) SetFiberW(fiberID string, bytes uint64)

SetFiberW records the latest dirtied-working-set measurement.

func (*Ledger) SetPooled 

func (l *Ledger) SetPooled(grantUID string, n int) bool

SetPooled records how many sandboxes wait in the grant's pool, and reports whether that changed.

func (*Ledger) Snapshot 

func (l *Ledger) Snapshot() Snapshot

Snapshot captures the ledger.

func (*Ledger) Statuses 

func (l *Ledger) Statuses() []Status

Statuses computes the view for every admitted grant, sorted by UID. One pass over the fibers and one over the sessions, however many grants there are.

type MaxPressure 

type MaxPressure []PressureSource

MaxPressure combines several sources into the ladder's one input: the highest reading wins, so kernel PSI on the grant's cgroup and the engine's device occupancy (used over capacity, in percent) drive the same rungs. A source that errors is skipped; all erroring is an error.

func (MaxPressure) Pressure 

func (m MaxPressure) Pressure(grantUID string) (float64, error)

type Policy 

type Policy struct {
	Durability       Durability
	SessionClass     string
	AuditClass       string
	PSISomeAvg10Shed float64
	PSISomeAvg10Park float64
	Isolation        Isolation
	EndpointMode     EndpointMode
}

Policy is the per-grant session, durability, pressure, isolation and endpoint class. The PSI watermarks are "memory some avg10" percentages on the grant's cgroup. The home sets them below its own eviction threshold so park fires first.

type Pooler 

type Pooler interface {
	Fill(ctx context.Context, g Grant, deadline time.Duration) error
	Drain(grantUID string, n int) int
	Pooled(grantUID string) int
	PooledExits() <-chan string
}

Pooler is implemented by runtimes that restore sandboxes ahead of their fibers. Drain discards up to n, every one when n < 0. PooledExits names the grant of each pooled sandbox that dies before its hand-out.

type PressureController 

type PressureController struct {
	Ledger   *Ledger
	Source   PressureSource
	Interval time.Duration
	// Drain, when set, discards up to n of the grant's pooled sandboxes
	// and returns how many went. It is tried before any fiber is parked.
	Drain   func(grantUID string, n int) int
	Park    func(ctx context.Context, fiberID string) error
	Release func(ctx context.Context, fiberID string) error
	Yield   func(ctx context.Context, grantUID string)
	// contains filtered or unexported fields
}

PressureController is the two-input, one-ladder controller from the design, reduced to its first input (kernel PSI; the device ledger input arrives with the GPU work). Cheapest reaction first: 

shed    refuse new clones for the grant (Clone consults Shedding)
drain   discard one pooled sandbox, which holds no state
park    checkpoint the running named session with the largest W
release kill the anonymous fiber with the largest W
yield   nothing left to reclaim and pressure persists: take the grant

Park and Release are fiberd's own verbs so every rung writes its audit record; Yield revokes the grant.

func (*PressureController) Run 

func (c *PressureController) Run(ctx context.Context)

Run evaluates every admitted grant each Interval until ctx ends.

func (*PressureController) Shedding 

func (c *PressureController) Shedding(grantUID string) bool

Shedding is the predicate Clone consults.

func (*PressureController) Tick 

func (c *PressureController) Tick(ctx context.Context)

Tick runs one evaluation. Exported so tests drive it deterministically.

type PressureSource 

type PressureSource interface {
	Pressure(grantUID string) (someAvg10 float64, err error)
}

PressureSource reports memory pressure for a grant as PSI "some avg10" in percent: the share of the last ten seconds in which at least one task in the grant's cgroup was stalled on memory. The runtime supplies it; the core never reads a kernel file.

type RateLimit 

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

RateLimit enforces the clone rate limit, the maximum sustainable activation rate as a function of working-set size W. Density is stock and this is flow. The same measured quantity, the dirtied working set, prices both churn and parking.

Model (placeholder until the fork-storm rig produces the real curve): 

rate(W) = base / (1 + W/refW)

implemented as a token bucket refilled at rate(W).

func NewRateLimit 

func NewRateLimit(baseClonesPerSec, refWBytes float64) *RateLimit

func (*RateLimit) ObserveWorkingSet 

func (b *RateLimit) ObserveWorkingSet(bytes float64)

ObserveWorkingSet feeds the current W estimate (from park-delta sizes and PSI-adjacent stats).

func (*RateLimit) Take 

func (b *RateLimit) Take() error

Take is called by the frontend before any work happens.

type ReconcileReport 

type ReconcileReport struct {
	GrantsReadmitted int
	GrantsExpired    int
	// GrantsUnverified counts snapshot entries whose token did not verify
	// again at boot, or that carried none. They are not re-admitted.
	GrantsUnverified int
	// GrantsUnavailable counts snapshot entries whose token the verifier
	// could not check at boot (ErrVerifyUnavailable, as when the key set
	// was never loaded). They are not re-admitted, but they stay in the
	// snapshot with their parked sessions until the grant is admitted again
	// or a later boot finds it expired.
	GrantsUnavailable int
	ParkedRestored    int
	ParkedDropped     int
	// ParkedHeld counts parked sessions kept in the snapshot under a grant
	// the verifier could not check.
	ParkedHeld    int
	OrphansKilled int
	// DeltasSwept counts deltas the runtime removed at boot because no
	// parked session names them.
	DeltasSwept int
}

ReconcileReport says what boot found.

type RemoteDelta 

type RemoteDelta struct {
	WBytes uint64
	Home   string
	Handle string // opaque; passed back to Claim
}

RemoteDelta is what a finder learns about a parked session elsewhere without pulling it: how much it costs to move, and where it lives.

type RemoteMiss 

type RemoteMiss struct {
	Err           error
	PreferredHome string
}

RemoteMiss wraps a capacity miss with the home the caller should prefer (where the session's state lives). pkg/rpc copies it into Miss.

func (*RemoteMiss) Error 

func (m *RemoteMiss) Error() string

func (*RemoteMiss) Unwrap 

func (m *RemoteMiss) Unwrap() error

type Revoked 

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

Revoked is the home's deny-list of grant UIDs the home removed. Each stays until every token for it has expired. Admit refuses them, so a token a caller still holds cannot re-admit what the home took away. It lives in its own file, not the ledger snapshot, because an unreadable snapshot is treated as empty and a deny-list must never be.

func OpenRevoked 

func OpenRevoked(path string, ttl time.Duration, now time.Time) (*Revoked, error)

OpenRevoked loads the deny-list at path (none yet is an empty one) and drops the entries that lapsed. A file that does not read is an error. ttl is how long an entry is kept past the latest lease it knows. Set it to the longest lease the issuer may sign.

func (*Revoked) Add 

func (r *Revoked) Add(uid string, lease, now time.Time) error

Add denies uid until the later of lease and now plus the ttl, or for good when lease is zero (no lease).

func (*Revoked) Clear 

func (r *Revoked) Clear(uid string) (bool, error)

Clear lifts uid's entry and reports whether there was one. It runs when the home delivers the grant again.

func (*Revoked) Denied 

func (r *Revoked) Denied(uid string, lease, now time.Time) bool

Denied reports whether uid is denied at now. A denied token whose lease runs past the entry extends it, so that token stays refused.

type Runtime 

type Runtime interface {
	Tier() Tier

	// PrepareTemplate makes the grant's template warm on this home (boots
	// the zygote, pulls the artifact). Idempotent. Grant readiness is this
	// call returning nil.
	PrepareTemplate(ctx context.Context, g Grant) error

	// Clone births a fiber. spec.Deadline is a hard budget.
	Clone(ctx context.Context, spec CloneSpec) (FiberHandle, error)

	// Park checkpoints the fiber's delta over the zygote and releases its
	// running-tier resources. sync means the delta is durable before the
	// call returns. Returns the delta ref for a later SourceDelta clone.
	Park(ctx context.Context, fiberID string, sync bool) (deltaRef string, err error)

	// Release destroys the fiber; discard also deletes any parked delta
	// belonging to the same session.
	Release(ctx context.Context, fiberID string, discard bool) error

	// List rebuilds the ledger's view of reality at startup; discrepancies
	// resolve in favor of what is actually running.
	List(ctx context.Context) ([]FiberHandle, error)

	// Stats measures one running fiber.
	Stats(ctx context.Context, fiberID string) (FiberStats, error)

	// Exits delivers fibers that died without a Park or Release. fiberd
	// frees their ledger slot and writes the audit record.
	Exits() <-chan FiberExit
}

Runtime is the seam between the invariant core and a mechanism. This interface is what keeps the core identical across homes and tiers.

type ScopeClaim 

type ScopeClaim struct {
	Name  string
	Value string
}

ScopeClaim is one fact a home asserts about where it runs: the namespace and service account of a grant Pod, the DRA claim behind a device channel, the Slurm job. The core never interprets a claim; it stamps them on audit records (and, later, on fiber credentials) so a reader can check integrity against facts the home vouched for.

type SeqRange 

type SeqRange struct {
	From uint64 `json:"from"`
	To   uint64 `json:"to"`
}

SeqRange is an inclusive range of sequence numbers.

type Session 

type Session struct {
	Name     string
	GrantUID string
	State    SessionState
	Fence    Fence
	Handle   FiberHandle // valid when StateRunning
	// DeltaRef is the parked delta, or, while running, the delta this
	// incarnation was resumed from ("" after a create). That delta stays
	// until the next park supersedes it or a Release discards it.
	DeltaRef string
}

Session couples a stable identity (Name — what "my worker" refers to) with a mutable incarnation (Fence — what credentials and claims bind to). The name survives incarnations; nothing else does.

type SessionSnapshot 

type SessionSnapshot struct {
	Name     string       `json:"name"`
	GrantUID string       `json:"grant_uid"`
	State    SessionState `json:"state"`
	Fence    Fence        `json:"fence"`
	DeltaRef string       `json:"delta_ref,omitempty"`
	FiberID  string       `json:"fiber_id,omitempty"`
}

type SessionState 

type SessionState int

SessionState is the ladder: it is the same triple as the density budget. 

const (
	StateRunning SessionState = iota // running tier: cgroup, fds, address
	StateParked                      // activatable tier: delta on disk
)

type Snapshot 

type Snapshot struct {
	Epoch    uint64            `json:"epoch"`
	SavedAt  time.Time         `json:"saved_at"`
	Grants   []Grant           `json:"grants"`
	Sessions []SessionSnapshot `json:"sessions"`
	// contains filtered or unexported fields
}

Snapshot is the on-disk cache of the ledger. It is a cache: at boot the runtime's view of reality wins, and the snapshot only tells fiberd which grants to re-admit and which parked sessions to remember.

type SnapshotStore 

type SnapshotStore struct {
	Path string
	// contains filtered or unexported fields
}

SnapshotStore persists snapshots atomically at Path. Each write goes to its own temporary file and is renamed into place, so a reader never sees a mix. It is safe for concurrent use. Use it by pointer.

func (*SnapshotStore) Load 

func (st *SnapshotStore) Load() (Snapshot, error)

Load returns the snapshot, or an empty one when none exists.

func (*SnapshotStore) Persist 

func (st *SnapshotStore) Persist(snapshot func() Snapshot) error

Persist writes snapshot() so the file reflects every change made before the call. Writes run one at a time and capture the ledger inside the lock, so a later write never holds an older snapshot. A caller that arrived before a write started shares that write's result.

type SourceHealth 

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

SourceHealth tracks whether the issuer is reachable. Core-owned so the staleness rule is identical under every adapter; adapters only MarkSync.

func NewSourceHealth 

func NewSourceHealth(stale time.Duration, now time.Time) *SourceHealth

NewSourceHealth: stale should default to the grant lease TTL — the same horizon that already bounds revocation. recover < stale gives hysteresis.

func (*SourceHealth) Healthy 

func (h *SourceHealth) Healthy(now time.Time) bool

func (*SourceHealth) MarkSync 

func (h *SourceHealth) MarkSync(now time.Time)

type Spool 

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

Spool is the at-least-once, sequence-numbered, hash-chained local log under <dir>/audit.jsonl. A Sync record is fsynced before Append returns. A BestEffort record is not. Once an fsync has failed the spool refuses every Sync record until the process restarts, because the kernel drops the pages a failed fsync could not write and a later fsync does not retry them.

func OpenSpool 

func OpenSpool(dir string, cp *Checkpoints) (*Spool, error)

OpenSpool opens or creates the spool, resumes the sequence and the chain from the last record on disk, and writes a gap for a torn last line. A nil cp writes no checkpoints.

func (*Spool) Append 

func (s *Spool) Append(_ context.Context, d Durability, rec AuditRecord) error

Append assigns the next sequence number and writes the line. A Sync record is then fsynced before Append returns, or refused with the failure once an fsync has failed. A write that fails leaves a gap the next one records.

func (*Spool) Close 

func (s *Spool) Close() error

Close signs what the last checkpoint does not cover, fsyncs and closes the file. A poisoned spool still closes, and Close returns the fsync failure instead of fsyncing again.

func (*Spool) Poisoned 

func (s *Spool) Poisoned() error

Poisoned returns the fsync failure that poisoned the spool, or nil. A poisoned spool refuses every Sync record until fiberd restarts, so fiberd reports it on /healthz. It takes no lock.

type SpoolReport 

type SpoolReport struct {
	// Records is the number of chained records, gaps and checkpoints
	// included. Unchained is how many came before the chain started.
	Records, Unchained int
	Gaps               []AuditRecord
	Checkpoints        int
	// SignedSeq is the last record a checkpoint covers. Unsigned is how
	// many chained records follow it. A spool cut after its last
	// checkpoint still verifies. Only a copy held elsewhere can show it.
	SignedSeq uint64
	Unsigned  int
	// TornTail means the last line is unreadable and no gap follows it
	// yet. The spool records one when it is next opened.
	TornTail bool
}

SpoolReport is what VerifySpool found.

func VerifySpool 

func VerifySpool(path string, trust map[string]ed25519.PublicKey) (SpoolReport, error)

VerifySpool checks the spool at path. Every record's hash must hold and chain to the last, so no edit, removal or reordering goes unnoticed. Sequence numbers advance by one except across a gap that names the missing ones. An unreadable line must be followed by a gap. Every checkpoint must be signed by a key in trust.

type Status 

type Status struct {
	GrantUID   string
	Running    int // fibers only, never pooled sandboxes
	Parked     int
	Pooled     int // sandboxes restored ahead of a clone, inside fibers.max
	WUsedBytes uint64
	Latest     Fence // the most recently minted fence for the grant
}

Status is the batched, per-grant view a home publishes. It is the only thing a control plane ever sees; never individual fibers.

type StatusCode 

type StatusCode int

StatusCode is the transport-agnostic outcome. pkg/rpc maps it to gRPC codes and attaches a Miss detail to the two miss codes. 

const (
	OK StatusCode = iota
	// DeferredFallback: miss while the control plane is healthy — the
	// caller falls back to its home's ordinary provisioning path.
	DeferredFallback
	// Shed: miss while the control plane is unreachable, or clone rate
	// backpressure. Back off; never queue on a dead control plane.
	Shed
	// Invalid: the request itself is malformed (payload too large).
	Invalid
	// Unauthenticated: the grant did not verify, or is not for this home.
	Unauthenticated
	// NeedsTier: the grant or session demands a tier this runtime lacks,
	// or the grant lacks what a named session needs (a tenant). Never
	// satisfied by a lesser mechanism.
	NeedsTier
	// NotFound: no such fiber in this epoch.
	NotFound
	// NoWorkspace: a file call on a fiber whose grant has no workspace.
	// Not a tier gap, since the grant itself asked for none.
	NoWorkspace
	// OverBudget: a file larger than the grant's disk budget. Not a
	// miss, so it carries no Miss detail.
	OverBudget
	// Internal: the runtime or audit spool failed in a way that is not a
	// capacity question.
	Internal
)

type TemplateDropper 

type TemplateDropper interface {
	DropTemplate(grantUID string)
}

TemplateDropper is implemented by runtimes that can end a grant's warm template. fiberd calls it at the end of a yield, once the grant's fibers are released, so a revoked grant holds no pages. The next admission warms the template again.

type Tier 

type Tier int

Tier is advertised runtime capability. Values match api/grant/v1 Tier so a grant's min_tier compares directly. Conformance to the verbs does not imply the mechanics; grants are placed against the tier, and Clone(S) on a parked session MUST fail rather than silently fork a fresh amnesiac fiber when the runtime lacks TierCheckpoint. 

const (
	TierUnspecified Tier = iota
	// TierBasic: create a worker in an existing warm sandbox. Correct
	// semantics, pod-class latency. Every runtime qualifies.
	TierBasic
	// TierWarm: zygote fork, copy-on-write. Millisecond activation and
	// density. Single-tenant per grant by definition.
	TierWarm
	// TierCheckpoint: per-fiber delta checkpoint + restore. Park/resume,
	// the entire session model, requires this.
	TierCheckpoint
	// TierSnapshot: microVM or gVisor snapshot-restore per fiber.
	// Multi-tenant per node.
	TierSnapshot
)

func ParseTier 

func ParseTier(s string) (Tier, error)

ParseTier accepts the proto enum names (FIBER_WARM) and short forms (warm), case-insensitively.

func (Tier) String 

func (t Tier) String() string

type Verifier 

type Verifier interface {
	Verify(ctx context.Context, token []byte) (Grant, error)
}

Verifier checks a signed grant offline and returns its contents. Never a control-plane round trip: cached JWKS, or a public key held locally.

type WorkspaceHolder 

type WorkspaceHolder interface {
	HoldsWorkspaces() bool
}

WorkspaceHolder is implemented by runtimes that can give each fiber a private workspace. A grant with a disk budget is admitted only where this answers true. A runtime that does not implement it has none.

Source Files

View all Source files

Directories

Path Synopsis
Package coretest holds helpers for tests of code built on pkg/core.
 Package coretest holds helpers for tests of code built on pkg/core.

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.