initconfig

type CodeBuildParams struct {
	Region  string
	Project string
	// Environment decides this node's guest OS, which billet reports at
	// registration rather than taking a second answer from the config.
	Environment config.CodeBuildEnvironment
	// FleetARN selects reserved capacity. Empty means on-demand compute, which
	// three of the six environments do not offer at all.
	FleetARN string
	// ComputeTypes is the ordered catalogue, most preferred first, each entry
	// declaring what it holds and what it costs.
	ComputeTypes []config.RemoteShape
	// JITParameterPath is where each build's single-use registration is written.
	// It is an IAM boundary rather than a naming preference, so billet does not
	// guess one.
	JITParameterPath string
	JITKMSKeyID      string
	LogGroup         string
	PrivilegedMode   bool
	// AcceptCeiling is the operator having read what CodeBuild's own limits are.
	// Its absence is a refusal; see errCodeBuildNeedsCeiling.
	AcceptCeiling        bool
	BuildTimeoutMinutes  int
	QueuedTimeoutMinutes int
	// FleetCapacity is how many builds this fleet may run at once, and it is
	// REQUIRED for macOS and meaningless elsewhere.
	//
	// A macOS tier with no explicit max_concurrent inherits its host's limit,
	// which defaults to APPLE's two-guests-per-machine allowance — a rule about
	// hardware somebody owns, and not the rule here: on this backend the cap is
	// the fleet capacity, which billet cannot see and AWS defaults to ONE. So the
	// generation asks rather than inventing a number that reads as a licence
	// statement it is not.
	FleetCapacity int
	// NodeName is what this orchestrator is called in the deployment, and it is
	// REQUIRED for macOS for the same reason a tart generation requires one:
	// config validation refuses a macOS tier that names no node, because the
	// per-host guest limit cannot be enforced against a tier that is pinned to
	// nowhere.
	//
	// IT IS NOT THIS MACHINE'S HOSTNAME, and that is the difference from tart. A
	// tart node IS the Mac, so its hostname is at least a candidate; a codebuild
	// node is a small machine somewhere that calls an API, and its hostname says
	// nothing about the fleet the limit is actually about. So it is asked for
	// rather than derived, and a generation that guessed would name a host the
	// operator never chose — which they would meet again the first time
	// `billet ca issue` disagreed.
	NodeName string
}

type EC2Params struct {
	Region                  string
	SubnetID                string
	SecurityGroups          []string
	UntrustedSecurityGroups []string
	// Shapes are the instance types billet may buy, each already carrying what it
	// holds and its audited price. Tiers are derived so each fits a declared shape.
	Shapes []config.EC2InstanceType
}

type HostInputs struct {
	// KernelImage pins node.firecracker.kernel_image.
	KernelImage string
	// CephUser and CephKeyringPath name the RADOS identity, WITHOUT the `client.`
	// prefix. Empty leaves Ceph's own search path, which finds
	// /etc/ceph/ceph.<user>.keyring.
	CephUser        string
	CephKeyringPath string
	// CacheListen and CacheGuestEndpoint are node.cache, and are given together
	// or not at all.
	CacheListen        string
	CacheGuestEndpoint string
}

type HybridFacts struct {
	ControlPlanePrivateIP          string
	LedgerVolumeID                 string
	SubnetID                       string
	RunnerSecurityGroupID          string
	UntrustedRunnerSecurityGroupID string
	AMIPayloadBucket               string
	// Name and Region are consumed by no rendering — every one takes both from
	// HybridParams. They are read so the two can be COMPARED, because outputs
	// from another root otherwise render a config that signs against one
	// deployment and names another's subnet, security group, buckets and
	// controller, with nothing in the generation saying so.
	//
	// THEY DO NOT BIND TO A ROOT, and nothing available here can. Two generations
	// sharing a name and a region, in different accounts, are indistinguishable
	// from these outputs. What this catches is the ordinary mistake — the wrong
	// outputs.json, or a flag retyped — not a determined one.
	Name   string
	Region string
	// The cache facts, demanded only of a generation that asked for one.
	CacheBucket      string
	CachePrefix      string
	AvailabilityZone string
}

type HybridFiles map[string]string

type HybridNeeds struct {
	// Untrusted demands the untrusted runner group, which only an untrusted
	// generation's root declares.
	Untrusted bool
	// Cache demands the three cache facts, which only a --cache root declares.
	Cache bool
}

type HybridParams struct {
	// Name is the Terraform module's name prefix: every AWS resource, the backup
	// bucket and the payload bucket derive from it.
	Name string
	// Region is where the controller and the fallback compute live.
	Region string
	// Org and the trusted-pool policy, exactly as for a single-host generation.
	// No policy renders `trust: untrusted` tiers, which the ec2 side serves from
	// an untrusted security group and the firecracker side from the untrusted
	// bridge.
	Org         string
	Repository  string
	RunnerGroup string
	Workflows   []string

	// ControlPlaneIP is the controller's private address, DECLARED. Empty leaves
	// it to AWS and renders a placeholder that the prepare render fills; a
	// declared one is written into server.listen and every server_addr before
	// the apply, which is the point of declaring it.
	ControlPlaneIP string

	// ControllerName and LocalName are the two hosts' names in the inventory
	// and in their certificates. The controller's is also the co-located ec2
	// node's name.
	ControllerName string
	LocalName      string

	// LocalVCPU and LocalMemory are what the Firecracker host HAS; its
	// contribution is that minus headroom, the same rule a measured host gets.
	LocalVCPU   int
	LocalMemory config.ByteSize

	// CloudVCPU and CloudMemory are the cloud budget, which IS the orchestrator's
	// ceiling: there is no machine to withhold headroom from.
	CloudVCPU   int
	CloudMemory config.ByteSize

	// Shapes are the EC2 instance types billet may buy, each carrying what it
	// holds and its audited price.
	Shapes []config.EC2InstanceType

	// SSHIngressCIDRs open the controller's SSH port to the machine that runs
	// Ansible; empty opens nothing, which is right for a route that ends on the
	// controller itself (the Systems Manager agent, a cloudflared tunnel or
	// route running on the host). IPv4 and canonical, because the root's rule
	// is cidr_ipv4 and AWS normalises host bits into a permanent diff.
	SSHIngressCIDRs []string
	// SSHKeyName is the EC2 key pair the controller launches with. Empty
	// attaches none, and then the only way onto a fresh Canonical image is EC2
	// Instance Connect, which the runbook spells out; with a key, Ansible's
	// ordinary SSH works the moment the instance answers.
	SSHKeyName string
	// LocalAnsibleUser is the account Ansible connects to the Firecracker host
	// as. Empty writes none, leaving the operator's SSH configuration to say:
	// owned hardware has no reason to carry the cloud image's `ubuntu`.
	LocalAnsibleUser string
	// LocalImage is the guest generation every tier boots on the Firecracker
	// host. Empty is DefaultFirecrackerImage, the x64 generation billet
	// publishes; an operator with another architecture or their own signed
	// generation names it, because the generator cannot see that machine.
	LocalImage string

	// Cache turns on the EBS+S3 site cache for the cloud half: the module
	// creates the bucket, the orchestrator gains node.ebs_s3 and the node.cache
	// listener its job instances fetch through, and both hosts declare the site
	// their storage belongs to.
	//
	// THE TWO HALVES CACHE IN DIFFERENT PLACES, which is what makes the sites
	// necessary rather than decorative: the Firecracker host's generations live
	// in its own Ceph pools, and an EC2 job cannot reach them across the WAN, so
	// the cloud half needs a store of its own and cache keys are scoped by site.
	Cache bool
	// LocalSite and CloudSite name those two places. Empty defaults to "home"
	// and to the region, which is what an operator would write anyway.
	LocalSite string
	CloudSite string

	// Builder grants the controller's own role what `billet ami build`
	// performs, so the image can be built ON the controller instead of from a
	// workstation holding an operator's AWS credentials — a second machine to
	// keep trustworthy for one step, on a deployment whose controller may be
	// reachable only through a tunnel. Off by default: it widens the identity
	// every job's instance is launched by.
	Builder bool

	// Host carries the Firecracker host's inputs billet cannot detect.
	Host HostInputs

	// Ref is the release every layer pins: the module's ?ref=, the collection's
	// version and billet_version. `main` for a development build.
	Ref string

	// Facts fill the placeholders; nil is the plan render.
	Facts *HybridFacts
	// Commission adds the ec2 node to the controller and lifts the prepare-only
	// hold. It needs Facts.
	Commission bool
	// AMI is what every tier's launch.ec2.image becomes on the commission
	// render; empty writes PlaceholderAMI, which loads and fails at launch by
	// naming what to do.
	AMI string

	// The App identity carried from an existing config; zero leaves the ids for
	// `billet github-app create`.
	AppID          int64
	InstallationID int64
	ClientID       string
}

type Params struct {
	// Org is the GitHub organization these runners serve, or Repository the one
	// repository as owner/name — exactly one, or neither at generation time,
	// when `github-app create` supplies it alongside the App ids.
	Org        string
	Repository string
	// Provider is the compute backend. Docker, Firecracker and EC2 are all rendered.
	Provider config.ProviderKind
	// Image is the tier's image, handed verbatim to the backend: a container
	// reference for docker, a published guest generation for firecracker. Empty
	// selects the provider-appropriate default.
	Image string
	// VCPU and Memory are what this machine has, detected by the caller, and the
	// generated ceiling is these minus headroom — EXCEPT for ec2, where there is no
	// host to detect and these carry the operator's declared cloud budget, which
	// IS the ceiling (no headroom is withheld from a machine that does not exist).
	VCPU   int
	Memory config.ByteSize

	// RunnerGroup and Workflows are the trusted-pool policy. REQUIRED for Docker,
	// which shares the host kernel and so refuses any workload that is not trusted
	// — and a trusted pool needs a non-default runner group and an exact workflow
	// allowlist. Empty here is not "untrusted by default": for Docker that is a
	// config that loads and then refuses its first job, so it is refused up front.
	RunnerGroup string
	Workflows   []string

	// Tart carries the Apple-silicon inputs, set only when Provider is
	// ProviderTart: which guest kinds this Mac serves, its name in the deployment,
	// and the image each guest kind boots. There is nothing to fetch and nothing
	// to detect — a Mac's capacity is measured like any other host-run backend —
	// so unlike EC2Params this is entirely what the operator asked for.
	Tart *TartParams

	// CodeBuild carries the CodeBuild placement inputs, set only when Provider is
	// ProviderCodeBuild. Like EC2Params it is entirely declared: there is no
	// machine to measure and no API that reports what a compute type holds, so
	// the shapes arrive already carrying their vcpu, memory and audited price.
	CodeBuild *CodeBuildParams

	// EC2 carries the cloud-backend placement inputs, set only when Provider is
	// ProviderEC2. Its Shapes must arrive fully populated (type, vcpu, memory,
	// price) — resolved by the caller from a live fetch or explicit flags — because
	// billet ships no table of EC2 shapes and a shape smaller than the lease chosen
	// for it overcommits a host nobody can see.
	EC2 *EC2Params

	// State selects where the control-plane LEDGER lives. Nil writes the
	// `state_dir` shorthand, which is what almost every generation wants; set it
	// to render `identity_dir` plus an explicit `state:` block instead. The two
	// spellings are mutually exclusive at load, so this is a choice the generator
	// has to make rather than a value it can add beside the default.
	State *StateParams

	// Profile selects the path shape (see Profile). Empty means ProfileLocal.
	Profile Profile
	// GOOS is the platform whose SERVICE shape a local-service generation is
	// for. Empty means this machine's, which is what a real run wants; a caller
	// generating for another host — or a test asserting both shapes on one
	// machine — names it.
	//
	// THE SERVICE SHAPE ONLY. The user-session shape's state and key paths come
	// from os.UserConfigDir() of the process running this, so they describe THIS
	// machine whatever is named here — there is no target user directory to ask
	// about. tartTargetPlatform is where that distinction decides something.
	GOOS string
	// Host carries the values a host must provide that billet cannot detect. See
	// HostInputs; every one is optional and omitting all of them generates
	// exactly what this package generated before they existed.
	Host HostInputs

	// Listen is the loopback address the server binds and the node dials — ONE
	// value for both, because they must agree or the node dials a listener that
	// does not exist. Empty means DefaultListen. A non-loopback address is
	// refused: a local profile's whole guarantee is that nothing is exposed to
	// the network, and a control plane other machines reach is configured with
	// `billet ca issue` and a hand-written node section instead.
	Listen string
	// contains filtered or unexported fields
}

type Profile string

type ReRun int

type StateParams struct {
	// Backend is the engine the ledger lives in.
	Backend config.StateBackend
	// DSNEnv names the environment variable holding the PostgreSQL connection
	// string. Required for the postgres backend and refused for any other, because
	// billet reads the DSN from the environment rather than from the file: it
	// carries a password, and a secret written into a config ends up in a backup.
	DSNEnv string
}

type TartParams struct {
	// GuestOS are the guest kinds this Mac serves. Rendered in a CANONICAL order
	// (macOS first) rather than the order they arrived, so two spellings of the
	// same request generate identical bytes — `billet init` re-run against its own
	// output converges on a byte comparison, and an order-sensitive catalogue
	// would make that depend on how the flags were typed.
	//
	// macOS first is also the allocation order, and that is not arbitrary: a macOS
	// guest has a hard floor Apple's hypervisor enforces and a per-machine licence
	// cap, so it is the constrained one. Fitting it first means the flag order
	// selects what is generated without also deciding what fits.
	GuestOS []config.GuestOS

	// NodeName is what this Mac calls itself in the deployment.
	//
	// REQUIRED when GuestOS includes macOS, because a macOS tier must pin a host —
	// Apple's limit is two concurrent guests per PHYSICAL machine, so billet has
	// to know which machine to count a guest against — and a pin can only name
	// what the node calls itself. Empty is legal for a linux-only generation,
	// where the node takes its hostname like any other host-run backend.
	NodeName string

	// MacOSImage and LinuxImage override the measured defaults above.
	//
	// TWO FIELDS RATHER THAN Params.Image, because one image is not a coherent
	// idea for a backend that boots two operating systems: a macOS generation and
	// an arm64 Linux generation name different artifacts and no single string can
	// be both. Same reason a multi-provider tier writes launch.<provider>.image
	// instead of image.
	MacOSImage, LinuxImage string
}