host

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

Documentation

Overview

Package host is the runtime every sandbox mechanism plugs into. It implements core.Runtime once, over a backend.Backend: templates are resolved from artifacts and gated on platform parity, every fiber is born in its own cgroup v2 leaf with memory.max = w_budget_bytes and memory.oom.group = 1 (the kernel is the executioner, the leaf's memory.current is W), grants get a block ceiling, PSI feeds the pressure ladder, parks become W-sized deltas over the template's checkpoint and travel to other homes through the delta registry. The backend only forks, checkpoints and restores.

Index

Constants

View Source 
const (
	// ExportDeltaFile holds the delta's files (the parked images and their
	// manifest), ExportParentFile the template checkpoint the delta is
	// relative to (absent when the park was a full checkpoint), and
	// ExportInfoFile describes both.
	ExportDeltaFile  = "fiberd-delta.tar"
	ExportParentFile = "fiberd-parent.tar"
	ExportInfoFile   = "fiberd-delta.json"
)
View Source 
const DefaultEngineMemoryMax = 1 << 30

DefaultEngineMemoryMax is memory.max of an engine's leaf when Config names none. A simulated engine holds its whole pool in host memory, so it must fit here.

View Source 
const DefaultEngineUID = 1<<30 - 1

DefaultEngineUID is the engine's uid when Config names none. It is one below the default -userns-pool (runcbackend.DefaultPool), so no runc grant's range holds it, and above the ranges hosts hand out by convention (useradd stops at 600100000). proc fibers run as fiberd's own uid.

Variables

View Source 
var (
	ErrNoTemplate  = errors.New("host: no template command for digest")
	ErrNotPrepared = errors.New("host: template not prepared for this grant")
	// ErrParity: an artifact's images or a published delta were made on
	// a host this one cannot restore them on (see artifact.Parity).
	ErrParity = errors.New("host: platform parity")
	// ErrNoHandoff means the grant's fibers are reached by handoff but
	// this home cannot pass them connections. Its backend cannot, or it
	// routes none (no Config.Handoff).
	ErrNoHandoff = errors.New("host: this home does not hand connections to fibers")
	// ErrNotHandoff means a connection was handed to a fiber that does not
	// take them (unknown, gone, or reached directly).
	ErrNotHandoff = errors.New("host: fiber does not take handed-off connections")
	// ErrHandoffBusy means the fiber's queue of handed-off connections is
	// full, so it is not accepting.
	ErrHandoffBusy = errors.New("host: fiber is not accepting handed-off connections")
)
View Source 
var DefaultFiberHide = []string{"/var/run/secrets/kubernetes.io/serviceaccount"}

DefaultFiberHide is hidden from every fiber. It holds the Kubernetes service-account token of the home's Pod.

View Source 
var ErrNoTier = errors.New("offers no tier")

ErrNoTier is New's refusal of a backend that offers no tier, because its tools or files are missing. Confinement fails closed, so fiberd does not start over such a backend.

View Source 
var ErrParentMissing = errors.New("host: parent checkpoint not in the store")

ErrParentMissing: a delta names a parent this home's store lacks.

View Source 
var ErrUnsupported = errors.New("host: not supported on this platform")

Functions

func DefaultCeiling 

func DefaultCeiling(g core.Grant, templateBytes uint64) uint64

DefaultCeiling is Config.Ceiling when unset.

func ExportDelta 

func ExportDelta(ctx context.Context, cfg Config, g core.Grant, session, dir string) ([]string, error)

ExportDelta moves the published delta of session under grant g from the registry into dir and returns the names of the files it wrote. The session's tag is deleted from the registry afterwards: the home that exported it forgets its copy on its next Clone of the name, and only what dir holds can bring the session back.

func FormatTemplateFlag 

func FormatTemplateFlag(digest string, command []string) (string, error)

FormatTemplateFlag is the -template value ParseTemplateFlag reads back as digest and command, "digest=cmd arg arg". digest must match core.TemplateDigestPattern. command must not be empty, and no element may be empty or hold whitespace, since Command splits the line on whitespace.

func ParseTemplateFlag 

func ParseTemplateFlag(m map[string]string, v string) error

ParseTemplateFlag parses "digest=path [args]" for -template.

Types

type Config 

type Config struct {
	// Backend is the sandbox mechanism (pkg/backend/proc, ...). Required.
	Backend backend.Backend
	// Templates maps a template digest to the template command line
	// ("path [args...]"). The key "default" serves digests not listed.
	Templates map[string]string
	// Registry, when set, resolves digests not in Templates by pulling
	// the template artifact "<Registry>@<digest>" into TemplateCache. A
	// registry starting with http:// is reached over plain HTTP.
	Registry string
	// TemplateCache holds pulled artifacts, one directory per digest
	// (default /var/lib/fiberd/templates), and the parent-checkpoint store.
	// It is hidden from fibers like PrivateDir and DeltaDir: a proc fiber
	// runs as fiberd's uid and could otherwise rewrite a cached
	// template between the host's check and the exec, or read another
	// grant's. A proc fiber still sees its own template's executable,
	// bound back read-only at its path inside the cover, because CRIU
	// names a mapped file by its path (sdk/c/template/core/src/mounts.rs).
	TemplateCache string
	// CgroupRoot is the delegated cgroup v2 subtree (from the home).
	CgroupRoot string
	// RunDir holds fiber endpoints (unix sockets); keep it short, the path
	// limit is 108 bytes.
	RunDir string
	// Endpoints is the address family fibers are served on: unix sockets
	// under RunDir (the zero value), or tcp on one declared address with
	// a port per fiber. A backend that lists "tcp" in EndpointSchemes
	// (proc) binds the port itself. Any other serves the unix socket and
	// fiberd relays the port to it (relay.go).
	Endpoints endpoint.Policy
	// DeltaDir holds parked images: <DeltaDir>/<grant>/<epoch>-<seq>/.
	DeltaDir string
	// WorkspaceDir holds the workspace of every running fiber whose
	// grant has a disk budget, <WorkspaceDir>/<grant>/<epoch>-<seq>/,
	// with the fiber's tree under root/ and fiberd's staging beside it
	// (default workspaces/ beside DeltaDir, so /var/lib/fiberd/workspaces
	// under the default DeltaDir). It is fiberd's alone, mode
	// 0700, and hidden from fibers like DeltaDir. Each fiber sees its
	// own tree alone, mounted at backend.WorkspaceMount.
	WorkspaceDir string
	// DeltaRegistry, when set, is the OCI repository prefix (host/prefix)
	// under which parked deltas are published (one repository per session
	// domain, one tag per session) and looked up by other homes. A prefix
	// starting with http:// is reached over plain HTTP.
	DeltaRegistry string
	// DeltaKeys signs every delta and parent checkpoint this home pushes to
	// DeltaRegistry. The home pulls or imports only those a trusted key
	// signed. Its Seal key encrypts each delta before it leaves the home, so
	// homes that move sessions between them share it. Signer and Seal are
	// required with DeltaRegistry.
	DeltaKeys artifact.Keys
	// Handoff routes callers' connections to the fibers of handoff-mode
	// grants, whose handles name its address. Nil refuses such grants
	// (ErrNoHandoff).
	Handoff *handoff.Router
	// HandoffKey derives each handoff grant's TLS identity. Homes that
	// move sessions between them share it. Required, at least 32 bytes,
	// when Handoff is set.
	HandoffKey []byte
	// HomeID names this home in published deltas, so a home that will not
	// pull a session can tell the caller where it is (Miss.preferred_home).
	HomeID string
	// Parity is how strictly an artifact's images or another home's delta
	// must match this host (architecture and backend always; kernel and
	// libc per level). The zero value is strict.
	Parity artifact.Parity
	// Platform overrides what this home believes about its own host, for
	// tests and for hosts whose uname is not what the checkpoints will
	// run under. Zero fields are filled by the backend, then detected
	// (ldd for the libc), so a Platform naming all three runs nothing.
	// Backend is always the backend's name.
	Platform artifact.Platform
	// Ceiling computes the grant's block ceiling in bytes from the grant
	// and the warm template's resident size; 0 means no ceiling. The
	// default is fibers.max * w_budget + template + 25%, and nothing when
	// either factor is unlimited. It is applied as memory.high (throttle,
	// which PSI reports and the ladder reacts to) with memory.max one W
	// budget above it as the hard stop.
	Ceiling func(g core.Grant, templateBytes uint64) uint64
	// FiberHide lists directories fibers must not see, besides
	// DefaultFiberHide, DeltaDir and PrivateDir, in backends that give a
	// fiber a mount namespace of its own. A directory holding RunDir is
	// never hidden, because fiber endpoints live there.
	FiberHide []string
	// PrivateDir is fiberd's private state (its keys, the ledger
	// snapshot, the epoch, the audit spool). Fibers run as fiberd's uid
	// and would pass the owner checks on its files, so it is always
	// hidden from them, like DeltaDir. Empty when fiberd has none.
	PrivateDir string
	// Engine is the device engine's command line, "path [args...]".
	// fiberd starts one engine for each grant with a device budget, with
	// --grant and --socket put after the path, and the grant is admitted
	// once it is READY. Empty starts none, and a grant with a device
	// budget is then refused.
	Engine []string
	// EngineUID is the uid and gid every engine runs as. It must not be
	// 0 and must be no fiber's uid (DefaultEngineUID when 0).
	EngineUID uint32
	// EngineMemoryMax is memory.max of each engine's leaf, <grant>/engine
	// (DefaultEngineMemoryMax when 0).
	EngineMemoryMax uint64
}

Config selects the backend, the templates and where the runtime may write.

func (Config) Command 

func (c Config) Command(digest string) ([]string, bool)

Command resolves the template command line for a digest from the Templates map, falling back to the "default" entry. Registry pulls are handled by the runtime (they need a context and a cache).

type ExportInfo 

type ExportInfo struct {
	Session           string            `json:"session"`
	Domain            string            `json:"domain"`
	Digest            string            `json:"digest"`
	Annotations       map[string]string `json:"annotations"`
	Parent            string            `json:"parent_sha256,omitempty"`
	ParentAnnotations map[string]string `json:"parent_annotations,omitempty"`
}

ExportInfo is what ExportDelta writes beside the archives. Domain tells whoever ships the files where the session came from. ImportDelta never believes it, because the destination grant's domain decides that. Annotations and ParentAnnotations are the signed manifests of the delta and its parent, which ImportDelta checks the archives against. An export without ParentAnnotations has its parent refused.

type Imported 

type Imported struct {
	Ref    string
	Digest string
}

Imported is what ImportDelta published: the session's tag and the digest it holds. A caller whose clone of the session fails can withdraw the tag if it still holds that digest.

func ImportDelta 

func ImportDelta(ctx context.Context, cfg Config, g core.Grant, session, dir string) (Imported, error)

ImportDelta publishes the files ExportDelta wrote in dir as session under grant g, so that Clone(session) on this home finds, claims and resumes it. The session name may differ from the exported one: a template's golden state imported under many names is many sessions.

type Runtime 

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

Runtime implements core.Runtime over one warm template instance per grant, provided by the backend.

func New 

func New(cfg Config) (*Runtime, error)

New opens the runtime over cfg.Backend. It refuses a backend that offers no tier (ErrNoTier), since confinement fails closed.

func (*Runtime) AttachDevices 

func (r *Runtime) AttachDevices(grantUID string, fc core.DeviceChannel)

AttachDevices implements core.DeviceAware: the grant's devices reach its warm instance's environment at PrepareTemplate.

func (*Runtime) CgroupRoot 

func (r *Runtime) CgroupRoot() string

CgroupRoot is where the runtime carves grant and fiber cgroups.

func (*Runtime) ClaimDelta 

func (r *Runtime) ClaimDelta(ctx context.Context, g core.Grant, session string, rd core.RemoteDelta) (string, error)

ClaimDelta implements core.DeltaFinder: pull by the digest that was found, open it for this session, fetch the parent if this home lacks it, then delete the tag so no other home can claim the same state. Content addressing makes what is pulled what FindDelta verified.

func (*Runtime) Clone 

func (r *Runtime) Clone(ctx context.Context, spec core.CloneSpec) (core.FiberHandle, error)

Clone births one fiber from the grant's pool or warm instance, or restores a parked delta.

func (*Runtime) Close 

func (r *Runtime) Close()

Close drains every pool, ends every warm instance and its fibers, and fiberd's relays.

func (*Runtime) DefaultDeadlines 

func (r *Runtime) DefaultDeadlines(grantUID string) (create, resume time.Duration)

DefaultDeadlines implements core.DeadlineAdvisor from the backend, for the grant's warm instance. A grant with none warm asks for no instance, which the backend answers with its floors.

func (*Runtime) DeleteDelta 

func (r *Runtime) DeleteDelta(ctx context.Context, g core.Grant, session, handle string) (string, bool, error)

DeleteDelta implements core.DeltaDeleter. It deletes the session's tag while the tag still holds the digest FindDelta found, as a claim does, and pulls nothing. The parent checkpoints the delta names stay, since other sessions of the domain may name them too.

func (*Runtime) Deliver 

func (r *Runtime) Deliver(fiberID string, conn *os.File) error

Deliver passes a connected socket to a handoff fiber, which serves it from fz_accept. It never blocks, so a full queue is ErrHandoffBusy. The caller still owns conn and closes its copy.

func (*Runtime) DeviceOffer 

func (r *Runtime) DeviceOffer(grantUID string) (string, uint64)

DeviceOffer implements core.DeviceCapable with what the grant's engine declared before READY.

func (*Runtime) DevicePressure 

func (r *Runtime) DevicePressure() core.PressureSource

DevicePressure is the ladder's second input: the engine's occupancy in percent of its capacity, for grants with an engine, and 0 for the rest. Combine with the PSI source through core.MaxPressure.

func (*Runtime) DeviceReport 

func (r *Runtime) DeviceReport(since uint64) core.DeviceReport

DeviceReport implements core.DeviceReporter: every grant's engine, sorted by grant, and the device events after since.

func (*Runtime) DiscardDelta 

func (r *Runtime) DiscardDelta(_ context.Context, ref string) error

DiscardDelta implements core.DeltaDiscarder. It removes a delta nothing will resume here: a claimed copy of a session that was already here, or a parked session another home claimed. Only a path inside this home's delta store is touched. A tcp port the parked fiber kept for its resume goes back with the delta.

func (*Runtime) Download 

func (r *Runtime) Download(_ context.Context, fiberID, path string, offset int64) (core.FileReader, error)

Download implements core.FileStore.

func (*Runtime) Drain 

func (r *Runtime) Drain(grantUID string, n int) int

Drain discards up to n pooled sandboxes of the grant, oldest first, every one when n < 0, and returns how many went.

func (*Runtime) DropTemplate 

func (r *Runtime) DropTemplate(grantUID string)

DropTemplate implements core.TemplateDropper. The yielded grant's pool drains, its warm instance ends and its pages lose their protection.

func (*Runtime) Exits 

func (r *Runtime) Exits() <-chan core.FiberExit

func (*Runtime) Fill 

func (r *Runtime) Fill(ctx context.Context, g core.Grant, deadline time.Duration) error

Fill restores one sandbox ahead of its fiber. It answers core.ErrNoPool, ErrNotPrepared, core.ErrPressure when the grant has no room for another fiber, or core.ErrYielded when a clone's restore took its place.

func (*Runtime) FindDelta 

func (r *Runtime) FindDelta(ctx context.Context, g core.Grant, session string) (core.RemoteDelta, bool, error)

FindDelta implements core.DeltaFinder: the manifest only.

func (*Runtime) HandoffRoute 

func (r *Runtime) HandoffRoute(fiberID string) (key, pin string, cert []byte, ok bool)

HandoffRoute implements core.HandoffRouter. It returns a handoff fiber's routing key, the pin of the key it serves TLS with and the certificate it presents.

func (*Runtime) HandsOff 

func (r *Runtime) HandsOff() bool

HandsOff implements core.HandoffRouter.

func (*Runtime) HasDelta 

func (r *Runtime) HasDelta(ref string) bool

HasDelta implements core.DeltaChecker: a parked ref is usable while its manifest exists.

func (*Runtime) HoldsWorkspaces 

func (r *Runtime) HoldsWorkspaces() bool

HoldsWorkspaces implements core.WorkspaceHolder with the backend's answer.

func (*Runtime) IsolatesTenants 

func (r *Runtime) IsolatesTenants() bool

IsolatesTenants implements core.Isolator with the backend's answer.

func (*Runtime) List 

func (r *Runtime) List(context.Context) ([]core.FiberHandle, error)

List reports every fiber leaf with live processes under the root, known to this runtime or not: reality for the ledger to reconcile.

func (*Runtime) ListFiles 

func (r *Runtime) ListFiles(_ context.Context, fiberID, dir string) ([]core.FileInfo, error)

ListFiles implements core.FileStore.

func (*Runtime) Owned 

func (r *Runtime) Owned(ctx context.Context, deltaRef string) bool

Owned implements core.DeltaFinder: a published delta is still ours while the tag holds the digest we pushed. Never published: ours.

func (*Runtime) Park 

func (r *Runtime) Park(ctx context.Context, fiberID string, sync bool) (string, error)

Park checkpoints the fiber into its delta directory and ends its running incarnation. sync: the fiber keeps running until the delta, its manifest and every file under the directory are durable (fsync), then it is killed. Otherwise the checkpoint ends it. Returns the delta directory as the ref.

func (*Runtime) Pooled 

func (r *Runtime) Pooled(grantUID string) int

Pooled is how many sandboxes wait in the grant's pool.

func (*Runtime) PooledExits 

func (r *Runtime) PooledExits() <-chan string

PooledExits names the grant each time a pooled sandbox dies before its hand-out, so the core backs its refill off.

func (*Runtime) PrepareTemplate 

func (r *Runtime) PrepareTemplate(ctx context.Context, g core.Grant) error

PrepareTemplate warms the grant's template: its cgroup, the backend's warm instance, the delta parent, the block ceiling. Idempotent per grant.

func (*Runtime) Pressure 

func (r *Runtime) Pressure(grantUID string) (float64, error)

Pressure implements core.PressureSource: PSI memory "some avg10" on the grant's cgroup, the one the ceiling is set on. It holds the fibers parent (warm instance and every fiber leaf) and the engine's leaf.

func (*Runtime) PruneGrants 

func (r *Runtime) PruneGrants(keep map[string]bool)

PruneGrants removes leftover cgroups of grants not in keep: the warm instance's cgroup (its process is gone or killed here), its fiber leaves, its pool, its fibers parent and the engine's leaf, each level the runtime makes and nothing deeper. A task killed here is still exiting when its cgroup is removed, so each removal is retried briefly. The grant's GPU guard goes with its parent.

func (*Runtime) PublishDelta 

func (r *Runtime) PublishDelta(ctx context.Context, deltaRef string, g core.Grant, session string) (string, error)

PublishDelta implements core.DeltaPublisher.

func (*Runtime) Relays 

func (r *Runtime) Relays() bool

Relays reports whether this home's tcp endpoints are relayed by the fiberd to fibers' unix sockets.

func (*Runtime) Release 

func (r *Runtime) Release(ctx context.Context, fiberID string, discard bool) error

Release kills the fiber's leaf and waits for it to be reaped. discard also deletes any parked delta stored under this fiber id. A fiber this runtime does not know (an orphan from a previous fiberd, found through List) is killed through its leaf as well.

func (*Runtime) RetireDelta 

func (r *Runtime) RetireDelta(ctx context.Context, deltaRef string) error

RetireDelta implements core.DeltaRetirer. The tag is deleted while it still holds the digest this home pushed for deltaRef. A tag a later park or another home's claim has moved on is left alone. The record of the publish goes either way, so Owned reads the delta as never published. A delta that was never published needs nothing.

func (*Runtime) ReturnDelta 

func (r *Runtime) ReturnDelta(ctx context.Context, g core.Grant, session, deltaRef string) error

ReturnDelta puts a delta whose resume failed back in the registry, so the session can resume on a home that fits. A claim deleted the tag and its publish record, and the copy at deltaRef is then the only one. It is published as a park here publishes, so this home keeps it parked until another home claims it (Owned). A delta with a publish record is in the registry already, or was claimed elsewhere since, and stays as it is. The push does not inherit the resume's deadline, which is often what failed.

func (*Runtime) Stats 

func (r *Runtime) Stats(_ context.Context, fiberID string) (core.FiberStats, error)

func (*Runtime) SweepDeltas 

func (r *Runtime) SweepDeltas(_ context.Context, keep []string) (int, error)

SweepDeltas implements core.DeltaSweeper. It removes every entry of <DeltaDir>/<grant>/ that keep does not name. That is a delta parked here or a claimed copy no session names, or the staging file a crashed park left. Names with a leading dot are scratch, which the store sweep at start owns, and are left alone, as is anything outside DeltaDir. Parents that only the removed deltas named are pruned once, at the end.

func (*Runtime) Tier 

func (r *Runtime) Tier() core.Tier

func (*Runtime) Upload 

func (r *Runtime) Upload(_ context.Context, fiberID, path string, size int64, mode fs.FileMode, sum []byte, rd io.Reader) (core.FileInfo, error)

Upload implements core.FileStore.

Source Files

View all Source files

Directories

Path Synopsis
Package wsfs is the file layer of a fiber's workspace.
 Package wsfs is the file layer of a fiber's workspace.

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.