contract

type BackupDirective struct {
	// BackupID is echoed back on the status report.
	BackupID string `json:"backupId"`
	// Action is "capture", "restore", "upload", "store", "fetch" or "delete".
	Action string `json:"action"`
	// Engine is the database engine ("postgres").
	Engine string `json:"engine"`
	// Ref is a file path: the snapshot to restore/upload/fetch, or where to write a
	// downloaded snapshot in the Vault volume (store).
	Ref string `json:"ref,omitempty"`
	// Retention, for a capture, is how many newest snapshots to keep on the host
	// (older ones are pruned after this capture).
	Retention int `json:"retention,omitempty"`
	// PutURL, for upload/fetch, is where to PUT the snapshot bytes (control-plane
	// staging, authenticated with the host token).
	PutURL string `json:"putUrl,omitempty"`
	// GetURL, for store and restore-from-vault, is where to GET the snapshot bytes.
	GetURL string `json:"getUrl,omitempty"`
	// Checksum, for store, is the sha256 to verify the downloaded snapshot against.
	Checksum string `json:"checksum,omitempty"`
}

type BackupReport struct {
	// BackupID is the backup this report is for (from the backup directive).
	BackupID string `json:"backupId"`
	// Action is which directive action this report is for ("capture", "restore",
	// "upload", "store", "fetch"), so the control plane can tell them apart for the
	// same BackupID.
	Action string `json:"action,omitempty"`
	// Status is the backup phase: "running", "done" or "failed".
	Status string `json:"status"`
	// Ref, on a capture "done", is the durable host file the snapshot was written to;
	// on a store "done", the file path written inside the Vault volume.
	Ref string `json:"ref,omitempty"`
	// SizeBytes is the snapshot size on a capture "done".
	SizeBytes int64 `json:"sizeBytes,omitempty"`
	// Checksum is the snapshot sha256 on a capture "done".
	Checksum string `json:"checksum,omitempty"`
	// Log is incremental, redacted output since the last report (may be empty).
	Log string `json:"log,omitempty"`
}

type BuildDirective struct {
	// DeploymentID is echoed back on the status report so the control plane can move
	// the right Deployment through building -> live/failed.
	DeploymentID string `json:"deploymentId"`
	// RepoURL is the https git repository to clone.
	RepoURL string `json:"repoUrl"`
	// Branch to build.
	Branch string `json:"branch"`
	// GitSha is a short revision label; a change rolls the build.
	GitSha string `json:"gitSha"`
	// RootDirectory is the subdirectory to build from, for a monorepo. Empty = root.
	RootDirectory string `json:"rootDirectory,omitempty"`
	// StartCommand overrides the start command baked into the image (Nixpacks).
	StartCommand string `json:"startCommand,omitempty"`
	// BuildEnvKeys are the build-time env var KEYS; values come from EnvValues.
	BuildEnvKeys []string `json:"buildEnvKeys,omitempty"`
	// ImageTag is the local tag the agent must produce (and, for BYO, then run).
	ImageTag string `json:"imageTag"`
	// PushTo, when set, makes this a BUILD-ONLY job on a dedicated build host: the
	// agent builds ImageTag, tags it to PushTo, pushes it to the private registry,
	// and does NOT run a container. Empty = bring-your-own-host (build and run
	// locally, nothing pushed).
	PushTo string `json:"pushTo,omitempty"`
	// Private is true when the repo needs a clone token (delivered via BuildToken).
	Private bool `json:"private,omitempty"`
}

type BuildReport struct {
	// DeploymentID is the deployment this build produces (from the build directive).
	DeploymentID string `json:"deploymentId"`
	// Status is the build phase: "building", "built" or "failed".
	Status string `json:"status"`
	// Log is incremental, redacted build output since the last report (may be empty).
	Log string `json:"log,omitempty"`
}

type CgroupUsage struct {
	// MemoryBytes is current memory usage in bytes (cgroup memory.current).
	MemoryBytes int64 `json:"memoryBytes"`
	// CpuUsage is CPU usage as a fraction of one core (for example 0.25),
	// derived from cpu.stat.
	CpuUsage float64 `json:"cpuUsage"`
	// EgressBytes is observed egress in bytes. Reported for insight only, never
	// metered.
	EgressBytes int64 `json:"egressBytes"`
}

type ContainerHealth struct {
	// WorkloadID is the workload this container belongs to.
	WorkloadID string `json:"workloadId"`
	// BlobID is the internal Blob identity of the Egg.
	BlobID string `json:"blobId"`
	// State is the runtime container state.
	State ContainerState `json:"state"`
	// Healthy reports whether the workload is currently passing its health check.
	Healthy bool `json:"healthy"`
	// RestartCount is the number of times the container has been restarted.
	RestartCount int `json:"restartCount"`
	// Usage is the measured cgroup usage.
	Usage CgroupUsage `json:"usage"`
	// DiskBytes is the on-disk usage of the Egg's persistent volume in bytes, for a
	// stateful (database) Egg. Zero/omitted for a stateless web Egg (no volume), and
	// omitted on reports where it was not measured this cycle (measured on a slower
	// cadence than the poll to keep du off the hot path).
	DiskBytes int64 `json:"diskBytes,omitempty"`
	// Logs are the container output lines produced since the last report
	// (incremental, may be empty).
	Logs []LogLine `json:"logs"`
	// Build, when set, reports host-side build progress for a bring-your-own-host Egg
	// the agent is building locally, so the control plane can move the Deployment
	// through building -> live/failed and show the build output in the Build tab. Nil
	// for a normal (non host-built) workload.
	Build *BuildReport `json:"build,omitempty"`
	// Import, when set, reports data-import progress for a database Egg the agent is
	// importing into, so the control plane can move the Import through
	// importing -> done/failed and show progress. Nil when there is no active import.
	Import *ImportReport `json:"import,omitempty"`
	// Backup, when set, reports backup capture/restore progress for a database Egg.
	// Nil when there is no active backup. See BackupReport.
	Backup *BackupReport `json:"backup,omitempty"`
}

type ContainerState string

type DesiredState struct {
	// HostID is the host this desired state is for.
	HostID string `json:"hostId"`
	// Version is an opaque content hash of this desired state. The agent compares
	// it against the last applied version to decide whether to reconcile.
	Version string `json:"version"`
	// Workloads are the workloads that should be running on this host.
	Workloads []WorkloadSpec `json:"workloads"`
	// RebootRequestedAt is an admin-requested reboot, as an RFC3339 instant. The
	// agent reboots when this is after the box's own boot time, and skips it once
	// the box has booted since (so it is idempotent across polls). Empty = none.
	// Deliberately outside the version hash: a reboot must not roll workloads.
	RebootRequestedAt string `json:"rebootRequestedAt,omitempty"`
	// CancelledDeploymentIDs are deployments whose in-flight build on this host
	// should be stopped (cancelled by a customer/admin, or superseded by a newer
	// deploy). The agent SIGTERMs the matching build if still running; unknown ids
	// are ignored. Outside the version hash: cancelling never rolls workloads.
	CancelledDeploymentIDs []string `json:"cancelledDeploymentIds,omitempty"`
}

type EggLifecycleState string

type EggTier string

type EggTierSpec struct {
	ID EggTier `json:"id"`
	// Label is the human-readable tier name.
	Label string `json:"label"`
	// PricePerMonthGbp is the flat price per Egg per month, in whole GBP.
	PricePerMonthGbp int `json:"pricePerMonthGbp"`
	// MemoryMb is the hard memory allowance in megabytes.
	MemoryMb int `json:"memoryMb"`
	// Vcpu is the human-readable vCPU allowance.
	Vcpu string `json:"vcpu"`
	// UnmeteredEgress is always true. Egress is unmetered on every tier.
	UnmeteredEgress bool `json:"unmeteredEgress"`
	// MostPopular flags the tier we highlight in the dashboard.
	MostPopular bool `json:"mostPopular,omitempty"`
}

type HostStatus struct {
	// HostID is the host this report is for.
	HostID string `json:"hostId"`
	// AgentVersion is the version string of the reporting agent.
	AgentVersion string `json:"agentVersion"`
	// AppliedVersion is the desired-state version the agent has applied, if any.
	AppliedVersion string `json:"appliedVersion,omitempty"`
	// CpuCores is the real CPU cores of the physical box (fractional allowed),
	// detected on the host and reported on every heartbeat so a resized VPS is
	// picked up automatically. omitempty: a zero (detection miss) is not sent, so
	// it can never overwrite a known-good Host value (version-skew safety).
	CpuCores float64 `json:"cpuCores,omitempty"`
	// TotalRamMb is total host RAM in MB, agent-detected. Same omitempty rule.
	TotalRamMb int `json:"totalRamMb,omitempty"`
	// DiskTotalGb and DiskFreeGb are the total and available space of the host's
	// tenant-data filesystem in GB, agent-detected each heartbeat. The control plane
	// budgets placement against these. Same omitempty (0 = miss, keep known value).
	DiskTotalGb int `json:"diskTotalGb,omitempty"`
	DiskFreeGb  int `json:"diskFreeGb,omitempty"`
	// OSName and OSVersion identify the host operating system (for example "Ubuntu"
	// and "22.04"), for the operator fleet view. Omitted when not detected.
	OSName    string `json:"osName,omitempty"`
	OSVersion string `json:"osVersion,omitempty"`
	// Kernel is the running kernel release (uname -r), for spotting an unpatched box.
	Kernel string `json:"kernel,omitempty"`
	// SecurityUpdates is the count of pending OS security updates. A pointer so nil
	// (not determined) stays distinct from 0 (checked and patched); omitempty drops
	// only the nil, so a real 0 is still sent and clears a stale count.
	SecurityUpdates *int `json:"securityUpdates,omitempty"`
	// RebootRequired is true when the OS has flagged that a reboot is needed to
	// finish applying updates. Sent even when false (no omitempty), so the control
	// plane can clear a stale flag after the box has been rebooted.
	RebootRequired bool `json:"rebootRequired"`
	// UptimeSeconds is how long the host has been up (from /proc/uptime). Lets the
	// control plane tell when a box has rebooted (uptime resets), so an admin reboot
	// request self-clears once the host reports a boot after the request. omitempty:
	// a host that cannot determine it (0) omits it rather than claiming a fresh boot.
	UptimeSeconds int64 `json:"uptimeSeconds,omitempty"`
	// RolledBack lists agent versions this node fetched, failed to run, and rolled
	// back from (quarantined). Always sent (even empty, no omitempty) so the control
	// plane can clear the alert once the node's quarantine is cleared.
	RolledBack []string `json:"rolledBack"`
	// Containers is the health of every container the agent is currently running.
	Containers []ContainerHealth `json:"containers"`
	// AgentLogs is the agent's OWN recent log output (a rolling window, not
	// incremental), so an operator can stream a node's agent logs from the console
	// without shell access. May be empty. Never contains secrets.
	AgentLogs []LogLine `json:"agentLogs,omitempty"`
}

type ImportDirective struct {
	// ImportID is echoed back on the status report so the control plane can move the
	// right Import through importing -> done/failed.
	ImportID string `json:"importId"`
	// Engine is the database engine ("postgres"), so the agent picks the right tool.
	Engine string `json:"engine"`
}

type ImportReport struct {
	// ImportID is the import this report is for (from the import directive).
	ImportID string `json:"importId"`
	// Status is the import phase: "importing", "done" or "failed".
	Status string `json:"status"`
	// Log is incremental, redacted import output since the last report (may be empty).
	Log string `json:"log,omitempty"`
}

type LogLine struct {
	// Ts is the runtime timestamp of the line (RFC3339).
	Ts string `json:"ts"`
	// Stream is which stream the line came from: "stdout" or "stderr".
	Stream string `json:"stream"`
	// Text is the log text, stripped of the runtime timestamp prefix.
	Text string `json:"text"`
}

type MigrationCounts struct {
	Tables int `json:"tables,omitempty"`
	Rows   int `json:"rows,omitempty"`
	Keys   int `json:"keys,omitempty"`
}

type MigrationDirective struct {
	// ID is the migration id, the idempotency key for every step.
	ID string `json:"id"`
	// Role is this host's part: "source" or "target".
	Role string `json:"role"`
	// Phase is which snapshot this directive is for: "base" or "delta".
	Phase string `json:"phase"`
	// Engine is the database engine: "postgres" or "redis".
	Engine string `json:"engine"`
	// VolumeName is the Egg's persistent volume name, identical on both hosts.
	VolumeName string `json:"volumeName"`
	// PutURL / GetURL are where to move the snapshot bytes. Empty means use the
	// control-plane relay endpoint (authenticated with the host token); a production
	// deploy supplies presigned object-storage URLs instead.
	PutURL string `json:"putUrl,omitempty"`
	GetURL string `json:"getUrl,omitempty"`
	// Checksum is the sha256 the target verifies against the downloaded snapshot.
	Checksum string `json:"checksum,omitempty"`
	// Quiesce (source only) means stop serving writes before the delta snapshot.
	Quiesce bool `json:"quiesce,omitempty"`
}

type MigrationReport struct {
	MigrationID string           `json:"migrationId"`
	Role        string           `json:"role"`
	Phase       string           `json:"phase,omitempty"`
	State       string           `json:"state"`
	Counts      *MigrationCounts `json:"counts,omitempty"`
	Checksum    string           `json:"checksum,omitempty"`
	SizeBytes   int64            `json:"sizeBytes,omitempty"`
	Error       string           `json:"error,omitempty"`
}

type NetworkAttachment struct {
	// Name is the pair network, identical for both peered Eggs.
	Name string `json:"name"`
	// Alias is this Egg's stable DNS name on that network.
	Alias string `json:"alias"`
}

type Region string

type RegionAvailability string

type RegionInfo struct {
	ID           Region             `json:"id"`
	Label        string             `json:"label"`
	Centre       string             `json:"centre"`
	Availability RegionAvailability `json:"availability"`
}

type ResourceLimits struct {
	// MemoryMb is the hard memory limit in megabytes (cgroup memory.max).
	MemoryMb int `json:"memoryMb"`
	// CpuFloor is the guaranteed vCPU share under contention, in fractional cores
	// (for example 0.5). Enforced as cgroup cpu.weight, proportional to this floor.
	CpuFloor float64 `json:"cpuFloor"`
	// CpuBurst is the burst ceiling when the host is idle, in fractional cores
	// (for example 2.0). Enforced as cgroup cpu.max. Always >= CpuFloor.
	CpuBurst float64 `json:"cpuBurst"`
	// PidsLimit is the maximum number of process IDs allowed (cgroup pids.max).
	PidsLimit int `json:"pidsLimit"`
	// ReadOnlyRootfs mounts the root filesystem read only. Defaults to true.
	ReadOnlyRootfs bool `json:"readOnlyRootfs"`
	// DroppedCaps lists the Linux capabilities to drop. Defaults to ["ALL"].
	DroppedCaps []string `json:"droppedCaps"`
}

type SecretsResponse struct {
	HostID    string            `json:"hostId"`
	Workloads []WorkloadSecrets `json:"workloads"`
}

type VolumeMount struct {
	// Name is the stable Docker volume name for this Egg's data.
	Name string `json:"name"`
	// Path is the absolute mount point inside the container (the engine's data dir).
	Path string `json:"path"`
	// SizeGb is the billed allocation. Advisory to the agent for now (the local
	// volume driver does not hard-enforce a quota).
	SizeGb int `json:"sizeGb,omitempty"`
}

type WorkloadSecrets struct {
	WorkloadID string            `json:"workloadId"`
	Env        map[string]string `json:"env"`
	// BuildToken is a short-lived git clone token for a private host-built repo. Used
	// only to clone the source for the build, then discarded; never injected into the
	// running container. Empty for public repos and non host-built workloads.
	BuildToken string `json:"buildToken,omitempty"`
	// ImportSourceURL is the external Postgres source connection string for an
	// in-progress data import. Used only to dump the source; never injected into the
	// running container's env. Empty when there is no active import.
	ImportSourceURL string `json:"importSourceUrl,omitempty"`
}

type WorkloadSpec struct {
	// ID is the stable identifier for this workload on the host.
	ID string `json:"id"`
	// EggID is the customer-facing Egg identifier. Safe to show in the dashboard
	// and logs.
	EggID string `json:"eggId"`
	// BlobID is the internal Blob identifier for the same unit. Never render this
	// in user-facing text.
	BlobID string `json:"blobId"`
	// ImageRef is the OCI image reference (registry/name@digest or
	// registry/name:tag).
	ImageRef string `json:"imageRef"`
	// Replicas is the desired number of running replicas.
	Replicas int `json:"replicas"`
	// Port is the container port the workload listens on.
	Port int `json:"port"`
	// PublishPort optionally publishes the container Port to this host port, for
	// local development and demos, and for a game-server Egg (which needs a real
	// public host:port). Zero (omitted) for a plain web Egg in production, where the
	// ingress tier routes traffic and the agent publishes nothing.
	PublishPort int `json:"publishPort,omitempty"`
	// PublishProtocol is the transport to publish PublishPort with: "udp" for a
	// native game server (FishNet Tugboat), else "tcp" (the default when empty).
	PublishProtocol string `json:"publishProtocol,omitempty"`
	// Hostnames this Egg serves: its platform subdomain plus any verified custom
	// domains. The agent registers ingress routes for these and answers the ask
	// endpoint for them.
	Hostnames []string `json:"hostnames,omitempty"`
	// Env lists the names of environment variables the workload expects. Only the
	// keys travel over this contract. Secret values are injected out of band and
	// are never included here, and are never logged.
	Env []string `json:"env"`
	// HealthCheckPath is the HTTP path polled for health checks (when HealthProbe
	// is "http").
	HealthCheckPath string `json:"healthCheckPath"`
	// HealthProbe is how the agent decides a container is healthy: "http" (GET the
	// health path), "tcp" (connect to the port) or "running" (healthy whenever it
	// runs, for a database or game-server Egg that speaks a wire protocol). Empty
	// keeps the agent's existing volume/port heuristic.
	HealthProbe string `json:"healthProbe,omitempty"`
	// ReleaseCommand is an optional command from the repo Procfile's release: line
	// (e.g. "bin/rails db:migrate"). The agent runs it once as a one-shot container
	// with this deployment's image, env and private networks BEFORE rolling the
	// workload, and gates the roll on its success. Empty means no release step.
	ReleaseCommand string `json:"releaseCommand,omitempty"`
	// Revision is an opaque deployment revision. It changes on redeploy, which
	// changes the desired-state version and rolls the container even when the
	// image is unchanged. The agent does not interpret it.
	Revision string `json:"revision,omitempty"`
	// EnvHash is a hash over the env set (keys plus ciphertext). It changes when a
	// value changes, rolling the container. Carries no plaintext.
	EnvHash string `json:"envHash,omitempty"`
	// Networks are the private-network peerings this Egg joins: one dedicated
	// two-party bridge per explicitly peered sibling, each with the alias this Egg
	// answers to on it. Deny-by-default: empty means fully isolated. The agent
	// joins the isolated base bridge plus one bridge per entry, so only an
	// explicitly peered sibling shares a network and can route to this Egg.
	Networks []NetworkAttachment `json:"networks,omitempty"`
	// NetworkName is the deprecated single-network form, kept for one version of
	// skew. Preferred is Networks; this is used only when Networks is empty.
	NetworkName string `json:"networkName,omitempty"`
	// InternalAlias is this Egg's alias on the deprecated NetworkName.
	InternalAlias string `json:"internalAlias,omitempty"`
	// Volumes are persistent named volumes to mount, for stateful Eggs (databases).
	// Each survives container recreation, so the data outlives a redeploy or
	// restart. Empty for stateless (web) Eggs.
	Volumes []VolumeMount `json:"volumes,omitempty"`
	// Migration, when set, is a database Egg migration in flight this host has a part
	// in (source: snapshot + upload; target: download + restore). Nil for a normal
	// workload. See MigrationDirective.
	Migration *MigrationDirective `json:"migration,omitempty"`
	// Build, when set, tells this host to build the image from source LOCALLY (bring
	// your own host) before running it, so the customer's code never leaves the box.
	// Nil for a normal, already-built or registry-pulled workload. See BuildDirective.
	Build *BuildDirective `json:"build,omitempty"`
	// Import, when set, is a one-off data import into this database Egg from an
	// external Postgres source (pg_dump piped into the Egg's own container). Nil when
	// there is no active import. See ImportDirective.
	Import *ImportDirective `json:"import,omitempty"`
	// Backup, when set, is a backup capture or restore for this database Egg (pg_dump
	// to a durable host file, or restore of one). Nil when there is no active backup.
	// See BackupDirective.
	Backup *BackupDirective `json:"backup,omitempty"`
	// Limits are the hard resource limits enforced by the agent.
	Limits ResourceLimits `json:"limits"`
	// EnvValues is the decrypted env as "KEY=VALUE" lines, populated locally by the
	// agent from the secrets endpoint. It is never on the wire (json:"-") and is
	// never logged.
	EnvValues []string `json:"-"`
	// BuildToken is a short-lived git clone token for a PRIVATE host-built repo,
	// populated locally from the secrets endpoint. Never on the wire (json:"-"),
	// never logged, and never injected into the running container.
	BuildToken string `json:"-"`
	// ImportSourceURL is the external Postgres source connection string for an
	// in-progress data import, populated locally from the secrets endpoint. Never on
	// the wire (json:"-"), never logged, passed to the import as an env var not argv.
	ImportSourceURL string `json:"-"`
}