spec

type Backup struct {
	Schedule string `yaml:"schedule"`
	Retain   int    `yaml:"retain,omitempty"`
}

type Build struct {
	Type string `yaml:"type"`
	Path string `yaml:"path,omitempty"`
	// BaseDirectory scopes the build context to a subdirectory of the
	// repo, e.g. "apps/web" in a monorepo. Empty means the repo root.
	// Meaningful for dockerfile, railpack, and static; not meaningful
	// for image (nothing gets built) or compose (the compose file's own
	// context: field already scopes each service).
	BaseDirectory string `yaml:"baseDirectory,omitempty"`
	// Image is a full registry reference (e.g.
	// "ghcr.io/org/app:v1.2.3"), only meaningful for build.type: image:
	// a CI pipeline (or anything else) already built and pushed this
	// exact image, so there is nothing for this control plane to build,
	// only to deploy as-is. See internal/deploy's deployImage.
	Image string `yaml:"image,omitempty"`
	// RegistryCredential names a store.RegistryCredential (by its Name,
	// not ID: app.yaml is hand-written, an opaque ID would be hostile
	// to author) to authenticate with when pulling Image from a private
	// registry. Empty means an unauthenticated (public) pull.
	RegistryCredential string `yaml:"registryCredential,omitempty"`
	// Args are Dockerfile build-time ARG values (e.g. a base image
	// version, a build-time feature flag), passed through as
	// --build-arg equivalents to BuildKit. Only meaningful for
	// build.type: dockerfile.
	Args map[string]string `yaml:"args,omitempty"`
}

type Database struct {
	Engine  string  `yaml:"engine"`
	Version string  `yaml:"version,omitempty"`
	Backup  *Backup `yaml:"backup,omitempty"`
	// EphemeralInPreviews opts this database into a disposable,
	// preview-scoped instance of its own (a full container, its own
	// volume, its own credentials) rather than sharing whatever this
	// database resolves to in production: one per pull request, created
	// alongside the preview and destroyed with it, with no restore path
	// once torn down. Off by default, like every other opt-in toggle in
	// this codebase; only meaningful for a database attached to an app
	// with preview environments enabled (store.GitSource.PreviewEnabled).
	EphemeralInPreviews bool `yaml:"ephemeralInPreviews,omitempty"`
	// IsolatedInPreviews opts this database into an isolated credential
	// per preview, created on this same existing database (no new
	// container, no new volume) rather than the whole disposable
	// instance EphemeralInPreviews creates: a Postgres role, or a Redis
	// ACL user scoped to its own key prefix. Ignored when
	// EphemeralInPreviews is also set, since an ephemeral instance
	// already has its own credentials. Postgres and Redis only today.
	// Off by default.
	IsolatedInPreviews bool `yaml:"isolatedInPreviews,omitempty"`
}

type Egress struct {
	Mode  string        `yaml:"mode"`
	Allow []EgressAllow `yaml:"allow,omitempty"`
}

type EgressAllow struct {
	Host string `yaml:"host"`
	Port int    `yaml:"port"`
}

type EnvVar struct {
	// Value is a literal value, set when the YAML node was a plain
	// string scalar rather than a mapping.
	Value string
	// From references another resource's computed value, e.g.
	// "postgres.main.url". Mutually exclusive with Value, Secret, and
	// Vault.
	From string
	// Secret means the operator provides this at deploy time via
	// the platform's own envelope-encrypted secret storage, never
	// written to app.yaml or the git repo. Mutually exclusive with
	// Vault: a given env var resolves its value from exactly one of
	// the two secret sources, never both.
	Secret bool
	// Required, only meaningful alongside Secret: fail the deploy if no
	// value has been provided, rather than starting the container with
	// the variable unset.
	Required bool
	// Vault means this value is resolved live from an external
	// HashiCorp Vault instance at container-create time
	// (internal/reconcile/application's resolveEnv), never stored by
	// this platform at all: the alternative to Secret above, not a
	// variant of it. nil means not vault-backed.
	Vault *VaultRef
}

type ExecCommand []string

type GPU struct {
	Count   int      `yaml:"count,omitempty" json:"count,omitempty"`
	Devices []string `yaml:"devices,omitempty" json:"devices,omitempty"`
}

type Health struct {
	Readiness *Probe `yaml:"readiness,omitempty"`
	Liveness  *Probe `yaml:"liveness,omitempty"`
	// ReadyTimeout overrides how long a fresh deploy waits for Readiness
	// to pass before the deploy is marked ReadinessFailed (internal/
	// reconcile/application.defaultReadyBudget, 60s, when unset). A slow
	// cold start (a JVM app, a big migration, a slow external connection)
	// can legitimately take longer than 60s without ever being unhealthy.
	ReadyTimeout string `yaml:"readyTimeout,omitempty"`
}

type Hooks struct {
	PreDeploy  string `yaml:"preDeploy,omitempty"`
	PostDeploy string `yaml:"postDeploy,omitempty"`
}

type Issue struct {
	Path    string `json:"path"`
	Line    int    `json:"line"`
	Message string `json:"message"`
}

type Job struct {
	Name     string   `yaml:"name"`
	Schedule string   `yaml:"schedule"`
	Command  []string `yaml:"command"`
	Timezone string   `yaml:"timezone,omitempty"`
	// Mode is "fresh" (default, a new container from the service's image
	// and spec) or "exec" (inside the running container).
	Mode string `yaml:"mode,omitempty"`
	// Concurrency is "allow", "forbid" (default) or "replace".
	Concurrency     string  `yaml:"concurrency,omitempty"`
	Timeout         string  `yaml:"timeout,omitempty"`
	Retries         int     `yaml:"retries,omitempty"`
	RetryBackoff    string  `yaml:"retryBackoff,omitempty"`
	CatchUp         string  `yaml:"catchUp,omitempty"`
	CatchUpLookback string  `yaml:"catchUpLookback,omitempty"`
	CPU             float64 `yaml:"cpu,omitempty"`
	Memory          string  `yaml:"memory,omitempty"`
	WarnAfter       string  `yaml:"warnAfter,omitempty"`
	// Enabled defaults to true when omitted.
	Enabled *bool `yaml:"enabled,omitempty"`
}

type Probe struct {
	Path            string      `yaml:"path,omitempty"`
	Scheme          string      `yaml:"scheme,omitempty" json:"scheme,omitempty"`
	Host            string      `yaml:"host,omitempty" json:"host,omitempty"`
	TLSSkipVerify   bool        `yaml:"tls_skip_verify,omitempty" json:"tls_skip_verify,omitempty"`
	FollowRedirects *bool       `yaml:"follow_redirects,omitempty" json:"follow_redirects,omitempty"`
	ExpectedStatus  StatusCodes `yaml:"expected_status,omitempty" json:"expected_status,omitempty"`
	Exec            ExecCommand `yaml:"exec,omitempty" json:"exec,omitempty"`
	Interval        string      `yaml:"interval,omitempty"`
	Timeout         string      `yaml:"timeout,omitempty"`
	Failures        int         `yaml:"failures,omitempty"`
}

type Resources struct {
	Memory string  `yaml:"memory,omitempty"`
	CPU    float64 `yaml:"cpu,omitempty"`
	// SwapMemory caps memory plus swap combined, the same "512Mi"/"1Gi"
	// shape as Memory (Docker's own MemorySwap semantics); only
	// meaningful alongside Memory, see Validate.
	SwapMemory string `yaml:"swapMemory,omitempty"`
	// CPUSet pins the container to specific host CPUs, Docker's own
	// cpuset-cpus format (e.g. "0-3" or "0,2").
	CPUSet string `yaml:"cpuSet,omitempty"`
	// GPU requests NVIDIA GPUs; the service is placed only on a node
	// with a usable GPU. nil means no GPU.
	GPU *GPU `yaml:"gpu,omitempty"`
}

type Service struct {
	Build Build `yaml:"build"`
	// Image is shorthand for build: {type: image, image: ...}; Parse folds it
	// into Build, so consumers only ever read Build.
	Image   string   `yaml:"image,omitempty"`
	Domains []string `yaml:"domains,omitempty"`
	Port    int      `yaml:"port,omitempty"`
	// HostPort pins the host-side port Docker binds Port to, 0 meaning
	// auto-assign (the same zero-value-means-unset convention Port
	// itself uses). Its storage home is store.DesiredService.HostPort
	// (migrations/0056_service_host_port.sql).
	HostPort int `yaml:"host_port,omitempty"`
	// BindAddress picks which network interface Port (and HostPort, if
	// pinned) binds to on the host: "private" (loopback only, the
	// default when empty), "public" (every interface, an explicit opt-
	// in), or a literal IP. See internal/bindaddr.Resolve for the exact
	// rules; EffectiveBindAddress applies the default.
	BindAddress string            `yaml:"bind_address,omitempty"`
	Health      *Health           `yaml:"health,omitempty"`
	Resources   *Resources        `yaml:"resources,omitempty"`
	Env         map[string]EnvVar `yaml:"env,omitempty"`
	Replicas    int               `yaml:"replicas,omitempty"`
	Strategy    string            `yaml:"strategy,omitempty"`
	// Labels are arbitrary operator-supplied Docker labels applied to the
	// service's container at create time, an escape hatch for tooling
	// this platform doesn't know about (a monitoring agent or log
	// shipper that keys off container labels, a homegrown script, and
	// so on). See ValidateLabels (labels.go) for what's rejected:
	// notably, any key under ReservedLabelPrefix, kept open for this
	// platform's own bookkeeping labels.
	Labels map[string]string `yaml:"labels,omitempty"`

	// Volumes are named Docker volumes or host-directory bind mounts this
	// service's container mounts (see Volume's own doc comment for how
	// the two are distinguished): named volumes were previously a
	// database-only capability, bind mounts a compose-import-only one. A
	// named volume's Name is a logical name scoped to this service, not a
	// global Docker volume name (see internal/deploy's translation into
	// store.ServiceVolume for the actual, platform-prefixed name); two
	// services can each declare a volume named "data" without colliding.
	Volumes []Volume `yaml:"volumes,omitempty"`

	// Hooks are shell commands the reconciler runs inside this service's
	// own container at defined points in a deploy (internal/reconcile/
	// application's controller). Nil means neither is configured, the
	// same "declarative, resolved before storing" shape Health/Resources
	// already follow.
	Hooks *Hooks `yaml:"hooks,omitempty"`

	// Command overrides the image's own default CMD
	// (store.DesiredService.Command), nil meaning the image's own
	// default: the app.yaml equivalent of
	// internal/compose.Service.Command, which this mirrors. A plain argv
	// list, never shell-interpreted.
	Command []string `yaml:"command,omitempty"`

	// Egress restricts this service's outbound network traffic to an
	// explicit host+port allowlist, enforced by
	// internal/reconcile/application's egress sidecar. Nil (the default,
	// and the only state every service had before this field existed)
	// means today's open-egress behavior, unchanged: this is deliberately
	// opt-in, not deny-by-default, since Levelrail runs arbitrary
	// third-party apps for existing users rather than AX's own
	// tightly-scoped agent sandboxes, and defaulting every existing app
	// to deny-all egress on upgrade would be a breaking change.
	Egress *Egress `yaml:"egress,omitempty"`

	// LoadBalancer configures balancing across this service's replicas
	// (internal/loadbalancer). Nil keeps the plain single-upstream route.
	LoadBalancer *loadbalancer.Config `yaml:"loadbalancer,omitempty"`

	// DependsOn names sibling services: keys (within this same Spec, or
	// within the same compose file for a compose-expanded service, see
	// internal/compose.ExpandBuildService) this service waits on before
	// the reconciler starts its own containers: internal/reconcile/
	// application.Controller does not create a container for this
	// service until every named dependency has at least one running
	// container. This matches real Docker Compose's own default
	// depends_on: semantic (service_started, not service_healthy): a
	// start-order guarantee, not a health-based wait. See Validate for
	// the reference and cycle checks.
	DependsOn []string `yaml:"dependsOn,omitempty"`

	// Jobs are cron-scheduled commands run for this service, each in a
	// fresh container of its image (or exec'd into the running one), kept
	// in step with this list on every deploy. Nil leaves jobs created
	// through the dashboard or CLI alone; an explicit empty list removes
	// every spec-declared job.
	Jobs []Job `yaml:"jobs,omitempty"`
}

type Spec struct {
	Version   int                 `yaml:"version"`
	Services  map[string]Service  `yaml:"services"`
	Databases map[string]Database `yaml:"databases,omitempty"`
}

type StatusCodes string

type VaultRef struct {
	Path string `yaml:"path"`
	Key  string `yaml:"key"`
}

type Volume struct {
	Name     string `yaml:"name,omitempty"`
	HostPath string `yaml:"hostPath,omitempty"`
	Path     string `yaml:"path"`
	ReadOnly bool   `yaml:"readOnly,omitempty"`
}