orchestrator

type AppSpec struct {
	Ref

	ReleaseID     string
	ConfigVersion int64
	Image         string
	Replicas      int32

	// Port the container listens on. Zero means the workload takes no traffic.
	Port int32

	Env map[string]string

	// Resource requests and limits, as Kubernetes quantity strings. Empty
	// fields fall back to the namespace LimitRange.
	CPURequest    string
	CPULimit      string
	MemoryRequest string
	MemoryLimit   string

	// WritableRootFilesystem disables the read-only root filesystem.
	//
	// The default (false) is correct and should stay the default: it is one of
	// the cheapest real defences available. But some images genuinely cannot
	// run without writing outside /tmp, and the honest choice is an explicit,
	// visible escape hatch rather than silently weakening the default for
	// everyone. /tmp is always writable — see the k8s implementation.
	WritableRootFilesystem bool

	// Hosts are the hostnames routed to this workload. Empty means the
	// workload is reachable only inside the cluster.
	//
	// Plain strings rather than a richer type: the orchestrator's job is to
	// route a name, and which names are legitimate — platform-issued or
	// customer-claimed — is a decision that belongs above this seam.
	Hosts []string

	// Internal keeps the workload off the public internet: no hostname, and a
	// Service on the port it actually listens on rather than the fixed one.
	Internal bool

	// RunAsUser is the uid the container runs as. Zero leaves it to the image.
	//
	// Needed because the security posture requires a non-root user and most
	// stock images do not name one — the kubelet then refuses the pod with
	// "image will run as root" rather than picking something. A source that
	// knows its image knows the uid; an arbitrary image does not, and gets
	// nothing here.
	RunAsUser int64

	// FSGroup owns the mounted volumes.
	//
	// A freshly provisioned claim belongs to root, so a container running as
	// anyone else cannot write to it. This is what makes a volume usable by a
	// non-root process, and without it storage and the security posture are
	// mutually exclusive.
	FSGroup int64

	// ScratchPaths are writable empty directories inside the container.
	//
	// The root filesystem is read-only, which most software is fine with until
	// it wants one specific path — a socket directory, a lock file. Naming
	// those is what lets the read-only default stay the default.
	ScratchPaths []string

	// HealthPath is an HTTP path on the workload's own port that reports
	// whether it is ready to serve. Empty means no probe.
	//
	// One path drives both probes, because an app that answers differently on
	// two paths is answering a question nobody asked it.
	HealthPath string

	// Liveness turns the same path into a restart condition as well.
	//
	// Off by default, and deliberately a separate switch. Readiness only
	// withholds traffic; liveness kills the container. A probe that is a little
	// too impatient turns a slow-starting app into a restart loop, which
	// presents as the app being broken rather than as the probe being wrong.
	Liveness bool

	// Secrets are environment values that must not appear in the pod template.
	//
	// They become a Kubernetes Secret the container reads with envFrom, rather
	// than literals in the Deployment — so they are absent from
	// `kubectl get deploy -o yaml`, which is the copy people read, paste into
	// issues, and check into repositories.
	Secrets map[string]string

	// Volumes are storage the workload keeps across redeploys.
	//
	// Attaching any forces the workload to recreate rather than roll on
	// deploy, and limits it to one replica — both because a ReadWriteOnce
	// claim mounts on one node at a time. See VolumeSpec.
	Volumes []VolumeSpec

	// TLSHosts are the hostnames terminated TLS is requested for.
	//
	// A subset of Hosts, not all of them, and that is the whole point. The
	// certificate this relies on is the ingress controller's own default — a
	// wildcard for the platform domain — so listing a hostname it cannot match
	// does not produce a certificate, it produces a TLS handshake the browser
	// refuses. A custom domain is never under the platform domain, so it never
	// belongs here.
	//
	// It carries no certificate reference. An Ingress's TLS Secret must live in
	// the Ingress's own namespace, and every app has its own namespace, so one
	// pre-provisioned wildcard cannot be referenced from all of them.
	//
	// Empty leaves the TLS block off entirely.
	TLSHosts []string

	// IssuedHosts are hostnames that each get a certificate of their own,
	// issued by CertIssuer — the answer for a name the platform wildcard can
	// never cover, which is every custom domain.
	//
	// A subset of Hosts and disjoint from TLSHosts. One certificate per name
	// rather than one listing them all, because a certificate is issued whole
	// or not at all: a single domain whose DNS has drifted would otherwise hold
	// every other domain on the app hostage.
	//
	// Each lands in the Secret CertSecretName names, in the app's own
	// namespace, which is where an Ingress can reference it.
	IssuedHosts []string

	// CertIssuer is the cluster-wide issuer IssuedHosts are requested from.
	// Empty means the install has none, and IssuedHosts must be empty too.
	CertIssuer string

	// CNAMETarget, when set, becomes the ExternalDNS target annotation, so that
	// controller publishes a CNAME rather than the nodes' own addresses as A
	// records. Empty leaves the annotation off: an install running no
	// ExternalDNS should not carry configuration for one.
	CNAMETarget string

	// HTTPSOnly routes through the ingress controller's secure entrypoint only.
	HTTPSOnly bool

	// RegistryAuth is a Docker config.json for pulling this app's image, when
	// it comes from a private registry. Empty leaves the namespace without a
	// pull secret, which is right for a public image.
	RegistryAuth []byte
}

type AppStatus struct {
	Phase              Phase
	ReleaseID          string
	ConfigVersion      int64
	Generation         int64
	ObservedGeneration int64
	Desired            int32
	Updated            int32
	Ready              int32
	Available          int32
	AvailableCondition bool
	Terminal           bool
	Reason             string
	Message            string
}

type BuildRequest struct {
	// Owner scopes the build's own resources, so a Job can be found and
	// cleaned up by the team it belongs to.
	Owner OwnerID

	// App is the app being built, for naming and labelling only.
	App string

	// Image is where the result must be pushed, fully qualified. Decided by
	// the caller rather than here: the path encodes which team owns the image,
	// and a builder choosing it could put one team's build in another's path.
	Image string

	// RepoURL, Ref and Subdir are what to build.
	RepoURL string
	Ref     string
	Subdir  string

	// Insecure means the registry speaks plain HTTP, so the push has to be
	// told not to expect TLS. Both build strategies need it and neither
	// discovers it, so it travels with the request.
	Insecure bool

	// RegistryAuth is a Docker config.json authorising the push. Passed per
	// build rather than held by the orchestrator, so the credential lives in
	// the one package allowed to unseal it and crosses this seam only when a
	// build actually needs it.
	RegistryAuth []byte

	// Log receives output as it arrives. A build that only reported at the end
	// would be silent for the several minutes it is most worth watching.
	Log func(chunk string)
}

type BuildResult struct {
	// CommitSHA is what was actually built. A branch moves; this is the answer
	// to "what is running" a week later.
	CommitSHA string

	// RunAsUser is the numeric uid the image runs as, resolved during the
	// build. Zero when it could not be worked out, which leaves the decision
	// where it was before.
	RunAsUser int64
}

type BuildState struct {
	// Found is false when there is no such Job. That means it finished and was
	// cleaned up, or it never started — either way nothing is running, which
	// is the answer the reconciler needs.
	Found bool

	// Done and Failed describe a Job that is still there.
	Done   bool
	Failed bool
	Reason string
}

type Builder interface {
	Build(ctx context.Context, req BuildRequest) (BuildResult, error)

	// BuildJobName is the name the Job for a request will have, known before
	// the build starts so it can be recorded. Deriving it here rather than
	// passing one in keeps the naming in the layer that has to make it a legal
	// Kubernetes object name.
	BuildJobName(req BuildRequest) string

	// BuildState reports what the cluster says about a build that was started
	// earlier, by name.
	//
	// This is what makes an interrupted build recoverable: the goroutine that
	// started it does not survive a restart and never existed on the other
	// replicas, but the Job is there for all of them to read.
	BuildState(ctx context.Context, jobName string) (BuildState, error)

	// CancelBuild removes a Job by the stable name BuildJobName returned. The
	// operation is idempotent: a Job already gone is a cancelled build too.
	CancelBuild(ctx context.Context, jobName string) error
}

type Certificate struct {
	// Issued is true once a certificate for the host is in place. False
	// covers both "still being issued" and "failing to issue": the Secret is
	// only written on success, and it cannot tell those apart.
	Issued bool

	// NotAfter is when the issued certificate expires. The issuer renews well
	// before then; a date that has passed means renewal has been failing.
	NotAfter time.Time

	// Trusted is true when the certificate chains to an authority browsers
	// trust. Let's Encrypt's staging environment — the installer's default —
	// issues certificates that do not, and a visitor gets the same warning as
	// for no certificate at all.
	Trusted bool
}

type CertificateReader interface {
	Certificate(ctx context.Context, ref Ref, host string) (Certificate, error)
}

type ClusterInspector interface {
	// ClusterSummary returns headline capacity and utilisation.
	ClusterSummary(ctx context.Context) (ClusterSummary, error)

	// Nodes lists the machines backing the runtime.
	Nodes(ctx context.Context) ([]NodeInfo, error)

	// Pods lists running pods.
	Pods(ctx context.Context, opts PodListOptions) ([]PodInfo, error)

	// Events lists recent cluster events, newest first, capped at limit.
	Events(ctx context.Context, limit int) ([]EventInfo, error)

	// Logs reads a container's output.
	//
	// On the read-only seam because it is a read. The scoping that matters is
	// not here: the namespace and pod arrive already resolved from an app the
	// caller looked up by owner, because a pod name on its own is enough to
	// read another tenant's logs.
	Logs(ctx context.Context, opts LogOptions) ([]LogLine, error)

	// LogStream follows a container's output until ctx is done.
	//
	// Separate from Logs rather than a flag on LogOptions: the batch call
	// returns a complete slice, and a flag that makes it never return would
	// leave that signature honest for one value of one field and false for the
	// other.
	//
	// The iterator holds a connection open for as long as it is read, so a
	// caller must either drain it or cancel ctx. Scoping is the caller's job
	// here exactly as it is for Logs — the namespace and pod arrive already
	// resolved from an app looked up by owner.
	LogStream(ctx context.Context, opts LogOptions) (iter.Seq2[LogLine, error], error)

	// Volumes lists an owner's persistent volume claims.
	//
	// Scoped rather than cluster-wide: a claim names the workload it belongs to,
	// and one team reading another's is a disclosure. A claim the engine did not
	// create carries no owner and belongs to whoever runs the cluster, so it is
	// shown to nobody here.
	Volumes(ctx context.Context, owner OwnerID) ([]VolumeInfo, error)
}

type ClusterSummary struct {
	Nodes      int
	NodesReady int

	Pods        int
	PodCapacity int

	CPUUsedMillis     int64
	CPUCapacityMillis int64
	MemUsedBytes      int64
	MemCapacityBytes  int64

	Volumes    int
	UsageKnown bool
}

type EventInfo struct {
	Namespace string
	Type      string // Normal | Warning
	Reason    string
	Message   string
	Object    string // e.g. "Pod/web-7d9f4b6c85-2xk9p"
	Count     int32
	LastSeen  time.Time
}

type HTTPLogLine struct {
	At       time.Time
	Host     string
	Method   string
	Path     string
	Protocol string
	Status   int
	Bytes    int64
	Client   string
	Duration time.Duration
}

type HTTPLogOptions struct {
	// Hosts is the tenancy boundary. One controller logs every tenant's
	// traffic, so the caller resolves which hosts belong to the app from an
	// owner-scoped query and this layer never decides it.
	Hosts []string
}

type HTTPLogger interface {
	HTTPLogs(ctx context.Context, opts HTTPLogOptions) (HTTPLogs, error)

	// HTTPLogHint is the configuration that switches the access log on, for
	// the page to show when Yacht cannot apply it.
	HTTPLogHint() string

	// EnableHTTPLogs applies it, where this cluster's controller is one Yacht
	// can reconfigure. Called once at startup rather than from a page: it
	// restarts a controller every workload routes through, which is a
	// cluster-wide cost and so never one app's decision to make.
	EnableHTTPLogs(ctx context.Context) error

	// HTTPLogsEnabled reports whether the running controller is writing one.
	HTTPLogsEnabled(ctx context.Context) bool
}

type HTTPLogs struct {
	Lines []HTTPLogLine

	// Reason explains an empty result that is not simply "no traffic".
	Reason string
}

type LogLine struct {
	At   time.Time
	Text string
}

type LogOptions struct {
	// Namespace and Pod name the container. Both come from an app the caller
	// has already resolved by owner — never from a request — because a pod
	// name is enough to read any tenant's output.
	Namespace string
	Pod       string

	// Tail caps how many lines come back. A pod that has been up for a month
	// has more output than anyone wants to render, and no cap means the whole
	// lot crosses the wire before anything is shown.
	Tail int64

	// Previous reads the container that died rather than the one running now.
	// It is the only way to see why something crash-looped: the running
	// container started after the interesting part.
	Previous bool
}

type NamespaceSpec struct {
	Owner OwnerID
	Name  string

	// Limits become a default LimitRange in the namespace, so a workload that
	// specifies no resources of its own still cannot run unbounded. Zero value
	// means DefaultLimits is used; it is deliberately not possible to create a
	// namespace with no limits at all.
	Limits ResourceLimits
}

type NodeInfo struct {
	Name    string
	Ready   bool
	Roles   []string
	Pool    string // scheduling pool, from the yacht/pool label
	Address string

	Version      string // kubelet version
	OS           string
	Architecture string

	CPUCapacityMillis int64
	CPUUsedMillis     int64
	MemCapacityBytes  int64
	MemUsedBytes      int64

	Pods          int
	PodCapacity   int
	CreatedAt     time.Time
	UsageKnown    bool // false when no metrics source is available
	Unschedulable bool

	// Reason and Message are why the node is not Ready, taken from its own
	// conditions.
	//
	// The same argument PodInfo.Reason makes, for the same reason. Ready is one
	// bit, and a machine that has registered and is starting its container
	// runtime draws exactly like one that registered an hour ago and never came
	// up — which are the two situations somebody watching a join has to tell
	// apart. Kubernetes explains itself in the conditions; this carries that
	// across without a Kubernetes type crossing the seam.
	//
	// Empty while the node is Ready.
	Reason  string
	Message string
}

type NodeManager interface {
	// Cordon stops or resumes scheduling onto a node. It does not move
	// anything already running there.
	Cordon(ctx context.Context, node string, unschedulable bool) error

	// Drain evicts the pods a node is running and reports how many it asked
	// to leave.
	//
	// Eviction is a request, not a deletion: it respects disruption budgets,
	// so a pod whose budget would be violated stays and is reported rather
	// than being taken down anyway. It returns once the evictions are
	// requested, not once they have finished — the caller watches the node
	// empty rather than holding a request open for however long that takes.
	Drain(ctx context.Context, node string) (requested int, err error)

	// DeleteNode removes the node object. The machine itself is not touched:
	// it stops being part of the cluster, and shutting it down is a separate
	// act somebody performs where the machine is.
	DeleteNode(ctx context.Context, node string) error
}

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

type Orchestrator interface {
	// EnsureNamespace creates or updates an owner's namespace, including the
	// security posture and default limits that go with it.
	EnsureNamespace(ctx context.Context, spec NamespaceSpec) error

	// DeleteNamespace removes a namespace and everything in it. It returns nil
	// if the namespace is already gone.
	DeleteNamespace(ctx context.Context, name string) error

	// ApplyApp converges a workload to the given spec.
	ApplyApp(ctx context.Context, spec AppSpec) error

	// DeleteApp removes a workload. It returns nil if already gone.
	DeleteApp(ctx context.Context, ref Ref) error

	// AppStatus reports observed state. It returns ErrNotFound if the workload
	// does not exist.
	AppStatus(ctx context.Context, ref Ref) (AppStatus, error)

	// Ping verifies the runtime is reachable. Used by health checks and at
	// startup, so a misconfigured cluster fails loudly instead of at first
	// deploy.
	Ping(ctx context.Context) error

	ClusterInspector
}

type OwnerID string

type Phase string

type PodInfo struct {
	Name      string
	Namespace string
	Phase     string
	Node      string
	Ready     int32
	Total     int32
	Restarts  int32
	CreatedAt time.Time

	// App is the workload this pod belongs to, empty for pods the engine
	// does not manage.
	App   string
	Owner OwnerID

	// Reason and Message are why a container is not running, taken from the
	// container's own waiting state.
	//
	// Kubernetes explains itself here the way it does in events, and the phase
	// alone does not: "Pending" and "CreateContainerConfigError" are the same
	// picture to somebody watching a deploy, and only one of them says the
	// image runs as root and the cluster refuses it. Empty while the container
	// is running or has never been asked to start.
	Reason  string
	Message string

	// DrainMoves reports whether draining this pod's node would move it.
	//
	// Decided where the drain is implemented rather than by a caller reading
	// fields and re-deriving the rule. A page that counted differently from
	// the drain would call a node empty while the drain still had work, and
	// the two would drift the first time either changed.
	DrainMoves bool
}

type PodListOptions struct {
	// Namespace limits results. Empty means every namespace.
	Namespace string

	// ManagedOnly restricts results to workloads the engine created.
	ManagedOnly bool

	// Node limits results to pods scheduled on one machine. Empty means every
	// node.
	Node string

	// Owner limits results to one principal's workloads.
	//
	// Empty means every owner, which is right for an operator view and wrong
	// for anything a member can reach. These pages were written when the engine
	// had one owner and everything in the cluster belonged to whoever was
	// looking; teams made that false, and a cluster page is the easiest place
	// to forget it.
	Owner OwnerID
}

type Ref struct {
	Owner     OwnerID
	Namespace string
	Name      string
}

type ResourceLimits struct {
	DefaultCPU    string // applied to containers that request nothing
	DefaultMemory string
	MaxCPU        string // ceiling any single container may request
	MaxMemory     string
}

type VolumeInfo struct {
	Name          string
	Namespace     string
	Phase         string // Pending | Bound | Lost
	StorageClass  string
	CapacityBytes int64
	RequestBytes  int64
	AccessModes   []string
	App           string
	Owner         OwnerID
	CreatedAt     time.Time
}

type VolumeSpec struct {
	Name      string
	MountPath string
	SizeBytes int64

	// Class is the StorageClass. Empty means the cluster default.
	Class string
}