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

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 Health struct {
	Readiness *Probe `yaml:"readiness,omitempty"`
	Liveness  *Probe `yaml:"liveness,omitempty"`
}

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

type Probe struct {
	Path     string `yaml:"path"`
	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"`
}

type Service struct {
	Build   Build    `yaml:"build"`
	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"`
	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"`
}

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

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