contract

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"`
	// Logs are the container output lines produced since the last report
	// (incremental, may be empty).
	Logs []LogLine `json:"logs"`
}

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"`
}

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"`
	// 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"`
	// 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 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 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"`
}

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. Zero (omitted) in production, where the
	// ingress tier routes traffic and the agent publishes nothing.
	PublishPort int `json:"publishPort,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.
	HealthCheckPath string `json:"healthCheckPath"`
	// 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"`
	// 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:"-"`
}