provider

type GuestVolumeLocator interface {
	GuestVolumeDevice(slot int, device string) string
}

type Instance struct {
	// ID is the backend's own handle — a container id, a microVM id, an EC2
	// instance id. Opaque to everything above.
	ID string
	// Name echoes the spec, so a caller holding only an Instance can still say
	// which runner it is.
	Name string

	// Running reports whether the instance is still executing.
	//
	// The difference between "this job is in progress" and "this job is over and
	// the container is a corpse holding a name and a disk", which is exactly the
	// question an adopted instance has to be asked repeatedly. A backend that
	// cannot tell should report true: treating an unknown state as finished would
	// destroy live work, and treating it as running only delays a cleanup.
	Running bool

	// Terminal reports that the backend positively observed this compute reach a
	// state from which it cannot execute or return to running. It is stronger than
	// !Running: a stopped instance is not executing but still exists and may retain
	// disks. The zero value is deliberately not proof.
	Terminal bool
}

type InterruptionNotice struct {
	InstanceID string
	Action     string
	Receipt    string
	// Problem is set when the queue delivered something that was not a usable
	// interruption event. It is safe diagnostic prose, never the message body.
	Problem string
}

type InterruptionSource interface {
	NextInterruption(ctx context.Context) (*InterruptionNotice, error)
	AcknowledgeInterruption(ctx context.Context, notice *InterruptionNotice) error
}

type Provider interface {
	// Accepts reports whether this backend may run work of that trust class.
	//
	// Separate from Launch so a caller can ask BEFORE doing anything expensive or
	// irreversible. Minting a runner registration and then being refused leaves
	// that registration on GitHub with nothing to consume it — one orphan per
	// pull request, accumulating quietly.
	Accepts(trust TrustClass) error

	// Kind reports which backend this is. Placement compares it against what a
	// lease requires, so a Firecracker lease cannot land on a Tart host.
	Kind() config.ProviderKind

	// Launch starts one instance running the job its JIT config names.
	//
	// It returns when the instance has been CREATED, not when the runner inside
	// it is ready. Readiness is a separate question with a separate timeout, and
	// conflating them is how a slow image pull becomes a launch failure.
	Launch(ctx context.Context, spec Spec) (*Instance, error)

	// Find reports the instance with that name, and whether there was one.
	//
	// This is what makes a failed launch answerable rather than guessed at. An
	// error from Launch does not prove nothing started — a cancelled context can
	// kill the CLI after the daemon accepted the request, and a remote API can
	// commit and lose the response — so the only honest way to find out is to
	// ask. Retrying instead is how one job becomes two runners.
	//
	// The bool is explicit rather than a nil pointer, because the caller's next
	// move on a hit is to DESTROY: "there is nothing here" and "something went
	// wrong and you got a zero value" must not look alike at a call site with
	// that consequence.
	Find(ctx context.Context, name string) (*Instance, bool, error)

	// List reports every instance this backend is running for billet.
	//
	// The input to reconciliation: anything here whose lease is no longer open is
	// an orphan, and orphans are the residue of every crash between starting an
	// instance and recording it.
	List(ctx context.Context) ([]*Instance, error)

	// Destroy removes an instance and everything it owns.
	//
	// MUST be idempotent: destroying an id that is already gone is success, not
	// an error. Teardown runs on paths that have already failed once, and an
	// error there turns a recoverable state into a stuck one.
	//
	// The Teardown says whether the compute is CONFIRMED gone or merely asked to
	// go, and the two are not the same fact — see Teardown. A backend must not
	// report TeardownStopped on the strength of an API accepting the request, and
	// must not report it on the strength of an absence its own service is allowed
	// to be wrong about.
	Destroy(ctx context.Context, id string) (Teardown, error)
}

type Quota struct {
	// Name is what the vendor calls it, and Code is the identifier an operator
	// types into a console or a support request. Both are carried so a report is
	// actionable without translating billet's wording back into the vendor's.
	Name string
	Code string
	// Limit and Unit are the ceiling and what it counts.
	Limit float64
	Unit  string
	// Scope says, in billet's own terms, what the limit is about — "concurrent
	// builds of BUILD_GENERAL1_MEDIUM", "running on-demand instances" — so a
	// reader can see which of their settings it bounds.
	Scope string
	// Shape names the declared shape this limit is about, empty for one that is
	// not about a shape at all.
	//
	// THE COMPARISON IS NOT MADE HERE, and this field is why. A backend knows
	// the vendor's codes; it does not know the deployment's budget —
	// node.max_vcpu and node.max_memory are NodeConfig's, not the backend
	// block's — so working out how many of a shape that budget could escrow is
	// billet's own arithmetic and belongs where the whole config is visible.
	// Naming the shape is what lets `billet check` do it without the backend
	// having to know.
	Shape string
}

type QuotaReporter interface {
	// Quotas reports the external ceilings this node's configuration runs
	// against.
	//
	// IT MAY RETURN BOTH a partial slice AND an error, and callers print both:
	// several lookups make several calls, and one that failed must not discard
	// the ones that answered. That is the same shape `billet check` already uses
	// for its advisory probes.
	Quotas(ctx context.Context) ([]Quota, error)
}

type Spec struct {
	// Name is BILLET's handle for the instance, and it must encode the lease.
	//
	// Not GitHub's runner name, which is a different thing that can differ. This
	// is what reconciliation reads back: after a crash the only surviving link
	// between a running instance and the lease that authorised it is the name the
	// instance carries, so a name that does not encode the lease makes an orphan
	// unattributable. See InstanceName.
	Name string
	// Image is the tier's image reference, interpreted by the backend: a
	// container image for docker, a rootfs for firecracker, an AMI for ec2.
	Image string

	VCPU   int
	Memory config.ByteSize
	// InstanceType is the EC2 shape selected and charged at escrow. Empty for
	// host-backed providers.
	InstanceType string
	// AuthorizeShape atomically changes that charge before EC2 attempts a
	// fallback. ok=false means the shape would exceed a budget; err means the
	// ledger could not make the decision and the launch must stop.
	AuthorizeShape func(context.Context, string, int, config.ByteSize) (ok bool, err error)
	// Disk is the root volume capacity. Firecracker grows its per-job RBD clone
	// and ext4 filesystem to at least this size; EC2 requests it from EBS. Zero
	// means the backend's image default. Host Docker ignores it.
	Disk config.ByteSize
	// SHM sizes /dev/shm. It is a tier parameter rather than a constant because
	// Postgres service containers and Chromium both fail on the default 64MB in
	// ways that look like unrelated crashes.
	SHM config.ByteSize
	// Volumes are cache devices known before boot. A cache endpoint reserves the
	// remaining slots so a cooperative guest can request them at runtime.
	Volumes []VolumeMount
	// CacheEndpoint and CacheToken let the managed guest request runtime volumes
	// from its node. The token is a session identity, not a boundary within the
	// guest: workflow code has passwordless sudo and Docker-root equivalence.
	CacheEndpoint string
	CacheToken    string
	// ActionsProxy and ActionsCAPEM opt this guest into the authenticated results
	// proxy. Both must be present or absent together.
	ActionsProxy string
	ActionsCAPEM string
	// BuildKitCacheMountLimit is the tier's byte ceiling for each persistent
	// BuildKit cache-mount record. It is meaningful only with CacheEndpoint.
	BuildKitCacheMountLimit config.ByteSize
	// RegistryMirrors are site-local public pull-through caches made available to
	// a managed guest. The zero value sends the guest directly upstream.
	RegistryMirrors config.RegistryMirrors

	// Command starts the runner inside the instance.
	//
	// REQUIRED, and backends refuse an empty one, for the same reason Trust's zero
	// value is refused: the alternative is not a failure but a SUCCESS that does
	// nothing. A container image's default command is usually a shell, so
	// launching without this starts a container that exits immediately — the CLI
	// reports success, billet logs a started runner, and the job sits queued
	// forever. Found on the first job billet was ever given.
	//
	// A []string rather than a string so no backend has to guess at word
	// splitting, and so an image needing arguments does not have to smuggle them
	// through a shell.
	Command []string

	// Trust is how much this workload is trusted. The zero value is UNKNOWN and
	// backends refuse it, which is what makes an unclassified job impossible to
	// route somewhere weak by omission rather than by decision.
	Trust TrustClass

	// JITConfig is the single-use runner registration.
	//
	// IT IS A CREDENTIAL until the runner consumes it, and it is the reason this
	// struct is passed by value to a method rather than assembled into a command
	// line by the caller. A backend MUST NOT put it in argv, where every process
	// on the host can read it, and MUST NOT log it. Both mistakes look like
	// working code.
	JITConfig string
}

type StagedCredentialReaper interface {
	ReapStagedCredential(ctx context.Context, instanceName string) error
}

type Teardown int

type TrustClass int

type VolumeAttacher interface {
	AttachVolume(ctx context.Context, instanceID string, slot int, device string) error
	DetachVolume(ctx context.Context, instanceID string, slot int, device string) error
}

type VolumeMount struct {
	// Device is the mapped host block-device path.
	Device string
	// Path is where the cooperative guest mounts it.
	Path string
}