backend

type Backend interface {
	// Name is the mechanism's name: "proc", "runc", "gvisor", "hyperlight".
	// It is a platform-parity fact: a checkpoint from one backend is
	// never offered to another.
	Name() string
	// Tier is the best this backend offers on this host, found at open.
	Tier() core.Tier
	Warm(ctx context.Context, spec WarmSpec) (Warm, error)
	// Unwarm ends a warm instance. Its fibers, if any survive it, are the
	// host's to kill through their cgroups.
	Unwarm(id string)
	Clone(ctx context.Context, warmID string, spec FiberSpec) (Fiber, error)
	// Park asks the fiber to stop serving and checkpoints it once it
	// has said so (ParkSpec). Resume brings a checkpoint back and
	// returns once the fiber says it serves again, under the spec's
	// deadline. A restored fiber that never says so is ended, and the
	// host routes nothing to it.
	Park(ctx context.Context, fiberID string, spec ParkSpec) error
	Resume(ctx context.Context, spec ResumeSpec) (Fiber, error)
	// Kill ends a fiber directly (the host also kills its cgroup).
	Kill(fiberID string) error
	// Exits delivers every fiber and warm-instance end, including those
	// the host asked for through Park or Kill: the host is what knows
	// whether an end was a death, and it cleans up on this signal. An
	// Unwarm may or may not be followed by the instance's Exit, so a host
	// that unwarms treats that Exit as cleanup it has already done.
	Exits() <-chan Exit
	Close()
}

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

type DeltaCodec interface {
	ImageBytes(dir string) (uint64, error)
	LoadParent(dir string) (Parent, error)
	// Compute rewrites the checkpoint in dir as a delta over parent.
	Compute(dir string, parent Parent) (DeltaInfo, error)
	HasDelta(dir string) bool
	ReadDeltaInfo(dir string) (DeltaInfo, error)
	// Merge rebuilds the full checkpoint in dir from the delta and parent.
	Merge(dir string, parent Parent) error
}

type DeltaInfo struct {
	ParentSHA256 string
	Bytes        uint64 // what the delta costs to move
}

type EndpointSchemer interface {
	EndpointSchemes() []string
}

type Exit struct {
	FiberID  string
	PooledID string
	WarmID   string
	Status   string // "exit:N" or "signal:NAME"; free text otherwise
	// Instance is, with WarmID, the Warm.Instance that ended. A backend
	// that names warms by grant reports the end of one the host dropped
	// after a later warm of the grant has the same WarmID, and the host
	// must not take it for the later one's.
	Instance uint64
}

type Fiber struct {
	ID  string
	PID int // root process; 0 when the backend has no process per fiber
	// Channel is the host's end of a handoff fiber's channel, on a
	// Handoffer. The backend made the pair where the fiber's checkpoint
	// can carry it, queued the incarnation record on it before the fiber
	// was born or was restored, and handed the fiber the other end. The
	// host owns this end from here, passes connections over it and
	// closes it when the fiber ends. nil for every other fiber, which
	// holds a pair of its own that the backend borrows an end of to
	// send a resume's record.
	Channel *os.File
	// Footprint is what the fiber's leaf counted on the backend's W
	// counter just before the fiber took its identity, for a backend
	// whose fibers carry a fixed footprint. The host subtracts it from
	// every later reading, because one restore of the same image can
	// settle MiB above or below another. 0 leaves the host to the
	// template's measured footprint.
	Footprint uint64
}

type FiberSpec struct {
	Fence string // the fiber's id; the backend reports exits under it
	// Endpoint is what the fiber must serve on: an absolute unix socket
	// path under the grant's run directory, or "tcp://host:port" for a
	// backend that lists "tcp" in EndpointSchemes.
	Endpoint string
	CgroupFD int // the fiber's leaf; -1 when the host has none
	Deadline time.Duration
	Payload  []byte
	// Session is the name the caller gave the Clone, "" for an anonymous
	// fiber. The fiber learns it at birth.
	Session string
	// Generation is the fiber's place in its lineage, which the host
	// counts. A fiber born from the warm instance, forked or restored
	// from its image, is 1. A fiber resumed from a park is the parked
	// one's plus one (ResumeSpec). A backend that tells its fibers who
	// they are hands the number over with the identity.
	Generation int
	// OwnPIDNS asks for the fiber to be the init of its own pid namespace
	// so its checkpoint restores anywhere. Backends that always isolate
	// ignore it.
	OwnPIDNS bool
	// Identity is a handoff fiber's TLS identity, which rides on its
	// incarnation record, and the fiber then serves the connections the
	// host passes over its channel instead of Endpoint. nil for every
	// other fiber. Only a Handoffer is given one.
	Identity *Identity
	// Workspace is the fiber's workspace root on the host, a directory
	// fiberd owns and the fiber will own every name under, which the
	// backend mounts at WorkspaceMount in the fiber. "" gives the fiber
	// no workspace. Only a WorkspaceHolder is given one.
	Workspace string
}

type Handoffer interface {
	Handoff() bool
}

type IDMapper interface {
	// MappedRoot is the host uid the root of a grant with range key key
	// maps to. It fails when the grant cannot have its range on this home
	// because an admitted grant of another key holds it.
	MappedRoot(key string) (uint32, error)
}

type Identity struct {
	KeyPEM    string
	CertPEM   string
	Caller    string
	CallerPEM string
}

type Incarnation struct {
	Generation int
	Kind       string
	Fence      string
	Endpoint   string
	Payload    []byte
	Session    string
	Identity   *Identity
	Seed       []byte
}

type Isolator interface {
	IsolatesTenants() bool
}

type Overheader interface {
	FiberOverheadBytes() uint64
}

type Parent interface {
	SHA256() string
	Close()
}

type ParkSpec struct {
	Dir  string
	Sync bool
	// Deadline bounds the wait for the fiber to stop serving, the
	// grant's resume deadline. Zero waits as long as the context allows.
	Deadline time.Duration
	// Channel is the host's end of a handoff fiber's channel, where
	// that fiber says it has stopped. nil for every other fiber, which
	// says so on a pair of its own that the backend borrows an end of.
	Channel *os.File
	// Capture, when set, runs after the checkpoint while the fiber is
	// stopped, before it is ended or runs on, so what it records matches
	// the images exactly. The host captures the fiber's workspace with
	// it. A Capture that fails fails the park, and the fiber runs on as
	// after any other failed park.
	Capture func() error
	// CgroupFD is an open fd of the fiber's leaf, which a backend that
	// stops the tree for a Capture continues or ends process by
	// process. -1 when the host has none.
	CgroupFD int
}

type Platformer interface {
	Platform() artifact.Platform
}

type PoolSpec struct {
	CgroupFD int // the leaf it is born in, which the fiber keeps; -1 when the host has none
	Deadline time.Duration
}

type Pooled struct {
	ID  string
	PID int
}

type Pooler interface {
	Pool(ctx context.Context, warmID string, spec PoolSpec) (Pooled, error)
	Bind(ctx context.Context, pooledID string, spec FiberSpec) (Fiber, error)
	Discard(pooledID string)
}

type Prober interface {
	// ProbeErr is why the backend offers no tier, nil when it offers one.
	ProbeErr() error
}

type ResumeSpec struct {
	Dir      string
	Fence    string
	Endpoint string // the endpoint the checkpoint served on (as in FiberSpec); recreated by the restore
	CgroupFD int
	Deadline time.Duration
	// WarmID names the grant's warm instance the fiber is resumed under
	// (its template, and for a launcher its container's root and mounts).
	WarmID string
	// RangeKey picks the grant's host id range (WarmSpec.RangeKey).
	RangeKey string
	// WorkDir is the grant's run directory (WarmSpec.WorkDir).
	WorkDir string
	// Session is the name the caller gave the Clone that resumes the
	// fiber, "" when anonymous. A backend whose resumed fiber takes a
	// fresh identity hands it over again.
	Session string
	// Generation is the parked fiber's generation plus one, read from
	// the park's manifest (FiberSpec.Generation).
	Generation int
	// Handoff says the checkpoint's fiber serves handoff, so it holds a
	// channel the restore replaces with a fresh one (Fiber.Channel). A
	// backend sends every resumed fiber its record, kind "resume" with
	// Fence, Generation and Session, on its channel, and waits for the
	// fiber's ack, which says it has taken the record and serves again.
	Handoff bool
	// Workspace is the resumed fiber's workspace root on the host,
	// filled from the park's capture, which the backend mounts at
	// WorkspaceMount where the parked fiber had its own. "" when the
	// parked fiber had none.
	Workspace string
	// EnginePath is the host path of the grant's device engine socket
	// (WarmSpec.EnginePath), for a backend that links the engine per
	// fiber and may resume with no warm instance (cloudhv). "" when the
	// grant has no engine. Other backends ignore it.
	EnginePath string
}

type SelfCheckpointer interface {
	CheckpointWarm(ctx context.Context, warmID, dir string) error
}

type SnapshotRestorer interface {
	ImagesFormat() string
}

type Template struct {
	Digest    string
	Argv      []string
	Dir       string // artifact directory; empty for a bare command
	ImagesDir string // checkpoint of the warm template, when the artifact has one
	// SnapshotDir is the template's own snapshot, opened for this warm
	// alone and read-only, when the artifact carries one in a format the
	// backend restores (SnapshotRestorer). The host removes it when the
	// warm instance ends.
	SnapshotDir string
	// ZygoteSHA256 is the hash the host verified the executable at
	// Argv[0] to have. A backend that runs the template somewhere other
	// than the host (gvisor binds a copy into the sandbox) checks what it
	// runs against it, so nothing between the host's check and the run
	// can swap the file.
	ZygoteSHA256 string
}

type WMeter interface {
	WCounter() string
}

type WReporter interface {
	FiberW(fiberID string) (uint64, bool)
}

type Warm struct {
	ID  string // backend's handle, passed back to Clone and Unwarm
	PID int    // the process, for logs; 0 when there is none
	// Instance tells this warm instance from another with the same ID,
	// and comes back on its Exit. 0 from a backend that does not number
	// its warms, whose stale end of a dropped warm is not told apart from
	// its successor's.
	Instance uint64
	// Bytes is what one fiber of this template costs in the W counter
	// (see WMeter) before it dirties anything, when the backend can
	// measure it (a sandbox restored from the template image); 0 lets the
	// host use the warm cgroup's count.
	Bytes uint64
	// TotalBytes is the same fiber's whole footprint (memory.current),
	// what its leaf's memory.max must leave room for besides the budget.
	// 0 means the same as Bytes.
	TotalBytes uint64
}

type WarmSpec struct {
	GrantUID string
	// RangeKey picks the grant's host id range on an IDMapper. It is the
	// grant's session domain, which every home's grant for a moving
	// session shares, or the grant uid for a grant without a tenant, so
	// a checkpoint restores on another home with the map it was dumped
	// with. Grants with one key share the range on a home.
	RangeKey string
	Template Template
	// CgroupFD is an open fd of the cgroup the warm instance must be born
	// in (its own leaf under the grant). -1 when the host has none.
	CgroupFD int
	// WorkDir is the grant's run directory: the instance's cwd, its log,
	// and where fiber endpoints live.
	WorkDir string
	// Devices names the devices the grant's device channel provisions for
	// its engine (device paths or ids), for the warm instance's
	// environment; nil when the grant has none.
	Devices []string
	// EnginePath is the host path of the grant's device engine socket,
	// which the warm instance gets as FIBERD_ENGINE_PATH and hands every
	// fiber as FIBERD_ENGINE. A backend whose fibers are copies of the
	// warm instance (gvisor) sets FIBERD_ENGINE itself. "" when the grant
	// has no engine.
	EnginePath string
	// ProbeCgroupFD is an open fd of an empty cgroup a backend may use
	// to measure what one fiber of this template costs (Warm.Bytes), by
	// starting one there and reading the cgroup; the host removes it
	// afterwards. -1 when the host offers none.
	ProbeCgroupFD int
	// Hide lists absolute directories a fiber must not see. A backend
	// that gives fibers a mount namespace of their own covers them there.
	Hide []string
}

type WorkspaceHolder interface {
	HoldsWorkspaces() bool
}