runtime

type BuildOptions struct {
	// Tag is the image reference to produce (e.g.
	// "outpost-runtime:dev" or a registry-qualified name for push).
	// Empty defaults to DefaultImage.
	Tag string

	// TargetArch is the linux architecture of the runtime image
	// ("amd64" or "arm64"). Empty defaults to the host's arch — the
	// usual case, since the container runs on the same machine the
	// outpost daemon does. Override only when cross-building (e.g.
	// from an arm64 dev machine for an amd64 production host).
	TargetArch string

	// PodmanBin overrides the autodetected `podman`/`docker` binary
	// used to drive the build. Empty triggers the same PATH lookup
	// the supervisor uses (pickPodmanBin).
	PodmanBin string

	// Stdout / Stderr receive the podman build's output. Defaults
	// (when nil) route to os.Stdout / os.Stderr so the operator
	// sees the build progress interactively.
	Stdout, Stderr *os.File
}

type Options struct {
	// AgentName is the outpost's identity. The container's k3s-agent
	// joins as Node <AgentName>; the container itself is named
	// <AgentName>-runtime.
	AgentName string
	// HostName is the registered physical host that owns this Node.
	// It may differ from AgentName when the operator overrides the
	// cluster node-name prefix.
	HostName string

	// Image is the runtime container image (e.g. "outpost-runtime:dev").
	// Built once via `outpost cluster build-runtime` or pulled from a
	// registry. Empty defaults to DefaultImage.
	Image string

	// NodeToken is the k3s join token cloudbox handed out at pairing
	// (K10<ca-hash>::node:<secret>). Passed into the container via
	// the OUTPOST_NODE_TOKEN env var; never written to disk on the
	// host.
	NodeToken string

	// APIServer is the URL the container's k3s-agent dials. In the
	// cloudbox model this is the loopback STCP visitor inside the
	// container (see overlay package). Empty defaults to
	// "https://127.0.0.1:6443".
	APIServer string

	// CloudboxHost / CloudboxPort are where the container-side frpc
	// dials to establish the matrix-tunnel + STCP visitor. Required
	// for the kubelet-in-container model — entrypoint.sh runs frpc
	// to open 127.0.0.1:APIPort inside the container, tunneling to
	// cloudbox's embedded apiserver. e.g. "ai.dhnt.io" + 443.
	CloudboxHost string
	CloudboxPort int

	// STCPSecret authenticates the STCP visitor on the cloudbox side
	// (cluster.k3s-apiserver publisher). Cluster-wide secret minted
	// at pairing time; passed in via env.
	STCPSecret string

	// MatrixToken is the shared frp auth token (same value cloudbox
	// holds in MATRIX_TOKEN). Empty disables [auth] in frpc.toml.
	MatrixToken string

	// FRPProtocol / FRPServerUser select WHICH control plane this node
	// joins, without changing anything else about the runtime.
	//
	// Cloudbox is reached over "wss" (TLS terminated at its edge) and
	// publishes the apiserver as user "cloudbox". A peer-hosted plane is
	// reached over plain "tcp" (an frps on another of the user's own
	// machines, usually via loopback or LAN) and publishes as
	// "control-plane". The entrypoint defaults both to the cloudbox values,
	// so an empty pair renders a byte-identical frpc.toml to the one that
	// shipped before peer-hosted planes existed.
	//
	// The serverUser is not cosmetic: frp scopes STCP visibility BY USER, so
	// a visitor naming the wrong one is refused rather than misrouted.
	FRPProtocol   string
	FRPServerUser string

	// APIPort is the loopback port the STCP visitor binds inside the
	// container (must match cloudbox's ClusterAPIServerPort). Empty
	// defaults to 6443.
	APIPort int

	// APIBridgeHostPort publishes the in-container apiserver visitor on this
	// port of the HOST's loopback interface. Peer-plane virtual-kubelet
	// runners use it to reach the exact same authenticated visitor as the
	// physical agent. Zero preserves the historical cloudbox behavior: no
	// host port is published and the visitor remains container-local.
	//
	// The host bind address is deliberately not configurable. The peer
	// apiserver is never a LAN service.
	APIBridgeHostPort int

	// KubeletPort is the per-outpost port cloudbox allocated at
	// pairing time (fc.Cluster.KubeletProxyPort). Three things ride
	// on this same number so the apiserver→kubelet hop terminates:
	//   - kubelet binds + advertises this port (so the Node's
	//     daemonEndpoint.Port matches what's reachable);
	//   - the in-container frpc publishes 127.0.0.1:<port> to
	//     cloudbox's loopback at the same port number;
	//   - cloudbox's apiserver dials 127.0.0.1:<port> for this Node.
	// Empty (0) leaves the kubelet on its default 10250 with no
	// outbound publish — `kubectl exec`/`logs`/`port-forward` won't
	// work against this outpost, but the rest of cluster-agent mode
	// keeps functioning. Old pairings without KubeletProxyPort
	// allocated land here.
	KubeletPort int

	// PodCIDR is the per-outpost /24 carved by cloudbox at Exchange
	// time. Empty disables the outpost-cni conflist; k3s falls back
	// to its own defaults (--flannel-backend=none means no pod
	// networking, fine for control-plane-only smoke tests).
	PodCIDR string

	// OverlayLoginServer / OverlayAuthKey turn on tailscaled inside
	// the container. Both must be non-empty; both empty leaves the
	// overlay off (single-node mode).
	OverlayLoginServer string
	OverlayAuthKey     string

	// PeerFlannel selects the peer-hosted-DKS pod network: stock k3s
	// flannel VXLAN pinned to the tailnet underlay
	// (--flannel-iface=tailscale0), per
	// docs/adr-peer-dks-pod-network.md. Set when this node joins a
	// PEER-hosted control plane.
	//
	// It changes what the entrypoint does in three ways: no conflist is
	// written (flannel writes its own 10-flannel.conflist), any conflist
	// left behind by a previous mode is REMOVED (CNI picks the
	// lexically-first file, so a stale 10-bridge.conflist would
	// out-select flannel and silently misroute), and the agent refuses
	// to start until tailscale0 actually has an IPv4.
	//
	// Never set for the cloudbox-hosted plane — that path keeps using
	// outpost-cni + advertised routes, byte-for-byte as before.
	PeerFlannel bool

	// OverlayRelay* describe the SECOND frpc session a peer-joined worker's
	// container opens — directly to CLOUDBOX — for exactly one visitor: the
	// `overlay-control` STCP publisher that carries the ts2021 tailnet
	// registration (Cloudflare strips the Upgrade header on the public
	// HTTPS URL, so this tunnelled hop is the only path to Headscale).
	//
	// On the cloudbox-hosted plane these stay empty: there the MAIN frpc
	// session already dials cloudbox and carries the overlay-control
	// visitor, byte-for-byte as before. On a peer plane the main session
	// dials the PEER's frps, which publishes no overlay-control — hence
	// this dedicated relay session.
	//
	// Host/Port/Protocol/Token are the cloudbox PAIRING values
	// (fc.ServerAddr/ServerPort/Protocol/Token); Secret is cloudbox's
	// cluster STCP secret (conf.ClusterConfig.CloudSTCPSecret); User is
	// the publisher's frp user (conf.CloudboxPublisherUser). All-empty
	// disables the relay.
	OverlayRelayHost     string
	OverlayRelayPort     int
	OverlayRelayProtocol string
	OverlayRelayToken    string
	OverlayRelaySecret   string
	OverlayRelayUser     string

	// PodmanBin overrides the autodetected `podman`/`docker` binary.
	// Empty triggers PATH lookup; tests set it.
	PodmanBin string

	// ExtraEnv is appended to the container's env in KEY=VALUE form.
	// Escape hatch for development.
	ExtraEnv []string

	// ForceRecreate replaces an otherwise matching runtime. The caller sets
	// this when EnsureImage rebuilt the local image in this process.
	ForceRecreate bool
}

type PodNetwork struct {
	// Mode is the classification. Never empty.
	Mode PodNetworkMode

	// PodCIDR is the range pods on this node get IPs from. In overlay
	// mode it is the cloudbox-allocated per-node CIDR; in fallback mode
	// it is the fixed range shared with every other node.
	PodCIDR string
}

type PodNetworkMode string

type ServerHealth struct {
	// Endpoint is the URL that was probed.
	Endpoint string `json:"endpoint"`
	// Serving is the load-bearing field: the apiserver answered in HTTP.
	//
	// ANY well-formed HTTP response counts, including 401 and 403. An
	// apiserver that denies anonymous requests still had to accept the
	// connection, complete a TLS handshake and route the request to say so —
	// which is the whole question. Only a transport error (refused, timed
	// out, TLS never completed) means dead. Treating a 401 as unhealthy
	// would have the supervisor restart a perfectly good, correctly-locked
	// down control plane in a loop.
	Serving bool `json:"serving"`
	// Status is the HTTP status code when Serving.
	Status int `json:"status,omitempty"`
	// Err is the transport error when not Serving.
	Err string `json:"err,omitempty"`
	// ContainerRunning / ContainerExists describe the container the plane
	// runs in. Populated by CheckServer, not by ProbeAPIServer.
	ContainerRunning bool `json:"container_running"`
	ContainerExists  bool `json:"container_exists"`

	CheckedAt time.Time `json:"checked_at"`
}

type ServerOptions struct {
	// AgentName identifies the host; the container is <AgentName>-control-plane.
	AgentName string
	// Image defaults to DefaultImage — the SAME image the agent runtime uses,
	// so an operator never has to keep two images in step.
	Image string

	// TunnelToken gates worker frpc logins.
	TunnelToken string
	// STCPSecret authorizes visitors of the published apiserver proxy.
	STCPSecret string

	// TunnelBindAddr / TunnelBindPort are where the container PUBLISHES its
	// frps to the host. Defaults 127.0.0.1:7000 — loopback, so enabling a
	// control plane never silently exposes it to the network.
	TunnelBindAddr string
	TunnelBindPort int

	// APIPort is the apiserver's port, used BOTH inside the container and as
	// the published host port so the kubeconfig k3s writes is valid on the
	// host unmodified.
	//
	// DEFAULT 16443, NOT 6443, and the difference is load-bearing. A host that
	// JOINS a cluster already binds 127.0.0.1:6443 — that is where its STCP
	// visitor puts the apiserver it joins. A host that also HOSTS a plane
	// would collide, and the collision is silent and vicious: kubectl reaches
	// whichever listener won the port while presenting the OTHER cluster's CA,
	// so it reports `certificate signed by unknown authority` and every
	// instinct says "bad certificate" rather than "wrong server".
	//
	// Hosting and joining are independent decisions, so they must not contend
	// for one port.
	APIPort int

	// KubeconfigDir is a HOST directory the container writes its admin
	// kubeconfig into. This is what makes the cluster operable without
	// `podman exec`, and what cluster.control_plane_kubeconfig points at.
	KubeconfigDir string

	// TLSSANs are extra apiserver certificate SANs, comma-separated. Needed
	// when workers reach this plane by an address other than loopback.
	TLSSANs string

	ClusterCIDR string
	ServiceCIDR string

	PodmanBin     string
	ForceRecreate bool
}

type SupervisorConfig struct {
	// CheckInterval is how often the readiness probe runs once the container
	// is up.
	CheckInterval time.Duration
	// UnhealthyGrace is how long the apiserver must be continuously unhealthy
	// (container gone, or up but not serving) before the container is
	// recreated. A single missed probe is not a restart: k3s can be briefly
	// unresponsive under load, and a hair-trigger supervisor is its own
	// outage.
	UnhealthyGrace time.Duration
	// FirstBackoff / MaxBackoff bound the retry after a bring-up or recreate
	// failure — e.g. a container engine still cold at boot, the same reason
	// the join side retries rather than treating the first failure as fatal.
	FirstBackoff time.Duration
	MaxBackoff   time.Duration
}