nodeclient

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

type Compute interface {
	Launch(ctx context.Context, lease *alloc.Lease, tier *nodeapi.TierSpec, job server.Job) error
	Destroy(ctx context.Context, requestID int64) error
	Recover(ctx context.Context) error

	// Instances are the lease ids this host is actually running, read from the
	// provider rather than from anything the control plane said.
	//
	// SENT AT REGISTRATION AS PROOF. A lease whose holder stopped heartbeating is
	// quarantined rather than terminalized, so its capacity stays charged until
	// the compute is confirmed gone — and the sweep that would confirm it only
	// fires for a container that still exists. A host that rebooted has none, so
	// without this its quarantined capacity would never come back.
	Instances(ctx context.Context) ([]string, error)
	Sweep(ctx context.Context) error

	// KeepAlive renews held leases on its own clock until the context ends.
	KeepAlive(ctx context.Context)
	// Tend advances custody entries: adopted work that finished, discarded work
	// whose cleanup is now confirmed.
	Tend(ctx context.Context) error

	// AssumeCustody takes a lease whose launch succeeded but whose result could
	// not be delivered, because the control plane will assume custody too.
	AssumeCustody(ctx context.Context, lease *alloc.Lease, requestID int64) error

	// Holding reports whether this node is still responsible for compute, which
	// is what decides whether a superseded process may stop.
	Holding() bool

	// Superseded moves running work into custody, because after supersession the
	// control plane routes its completions to somebody else.
	Superseded()
}

type LoopOptions struct {
	Provider   config.ProviderKind
	GuestOS    []config.GuestOS
	Deployment string
	// Site is where this machine is, or empty in a deployment with one place.
	Site string
	// VCPU and Memory are what this host CONTRIBUTES, which is what it detected
	// unless its own config said otherwise.
	//
	// Required. The control plane refuses a registration that offers nothing,
	// because a node contributing zero joins the fleet, is never chosen, and
	// produces no error for anyone to find.
	VCPU   int
	Memory config.ByteSize
	// EC2Shapes are the ordered purchasable shapes of whichever REMOTE backend this
	// node runs. Empty for a host-backed provider.
	EC2Shapes []config.RemoteShape
	// CodeBuildFleet is the reserved-capacity CodeBuild fleet this node draws on,
	// or empty for on-demand compute.
	CodeBuildFleet string
	// CodeBuildJITParameterPath and CodeBuildRegion are where a codebuild node
	// stages runner registrations, reported so the control plane can sweep the
	// ones a dead node left behind. Empty for every other backend.
	CodeBuildJITParameterPath string
	CodeBuildRegion           string
	Log                       *slog.Logger
	// SweepEvery bounds how often the node looks for compute nothing is asking
	// about. Zero disables it.
	SweepEvery time.Duration
	// Identity is this node's rotating certificate, when it has one. Nil on a
	// loopback wire, where there are no certificates to renew.
	//
	// GIVEN TO THE LOOP RATHER THAN RENEWED BY THE CALLER, because renewal has to
	// happen while the node is RUNNING. A check at startup would leave a host that
	// is up for a year to expire in place, and the failure is total: an expired
	// certificate cannot renew — renewal is authenticated by the certificate being
	// renewed — so the node has to be re-enrolled by hand.
	Identity *wirecert.Rotating

	// Hurry, when closed, ends the drain's wait early. It is the operator's
	// second signal: stop waiting, but still stop properly.
	Hurry <-chan struct{}
	// DrainTimeout is when a stopping node starts REPORTING that it is still
	// waiting for the compute it holds. It is not a deadline — nothing bounds
	// that wait but the work finishing or a second signal. Zero uses a default of
	// six hours, which is how long GitHub lets a job run.
	DrainTimeout time.Duration
	// Backoff is how long to wait after a failed registration or poll. Zero uses
	// a default.
	//
	// It governs BOTH registration and poll failures, so a caller lengthening it
	// to calm a flapping link is not left hammering the poll endpoint.
	Backoff time.Duration
}

type Options struct {
	// Base is the control plane's address, as a URL or a bare host:port.
	//
	// A bare address takes its scheme from whether TLS is configured, which is the
	// only place that answer is known. Config carries host:port because that is
	// what an operator writes and what the address can be validated as; a URL
	// there would let someone write http:// beside a certificate and get a node
	// that quietly never used it.
	Base string
	// Node is this host's name, which must match its entry in the server's
	// fleet configuration.
	Node string
	// HTTP is the transport. A caller supplies one so timeouts are decided once
	// rather than here.
	HTTP *http.Client
	// TLS is the node's side of the wire: its certificate, and the deployment
	// authority it verifies the control plane against.
	//
	// Nil serves loopback, and nothing else — a control plane bound to a network
	// address refuses to start without a certificate, so a node reaching one over
	// the network without this fails at the handshake rather than half-connecting.
	TLS *tls.Config
	// RequestTimeout bounds an ordinary request. Zero uses requestTimeout.
	//
	// Configuration rather than a test hook: a node on a slow or distant link
	// legitimately needs longer, and the alternative is every such deployment
	// discovering the constant by hitting it.
	RequestTimeout time.Duration
}

type Registration struct {
	Provider   config.ProviderKind
	GuestOS    []config.GuestOS
	Deployment string
	Site       string
	// VCPU and Memory are what this host contributes.
	VCPU      int
	Memory    config.ByteSize
	EC2Shapes []config.RemoteShape
	// CodeBuildFleet is the reserved-capacity fleet this node's builds run on, or
	// empty for on-demand compute. The control plane refuses a second live node
	// naming the same one, because its capacity is shared.
	CodeBuildFleet string
	// CodeBuildJITParameterPath and CodeBuildRegion are where a codebuild node
	// stages runner registrations, so the control plane can sweep the ones a dead
	// node left behind. Empty for every other backend.
	CodeBuildJITParameterPath string
	CodeBuildRegion           string
	// Instances are the lease ids this host is actually running, and
	// InventoryKnown says the list is complete rather than absent. See
	// nodeapi.RegisterRequest.
	Instances      []string
	InventoryKnown bool
}