spec

type AppSpec struct {
	SchemaVersion int       `json:"schema_version"`
	AppID         string    `json:"app_id"`
	Revision      int       `json:"revision"`
	CreatedAt     time.Time `json:"created_at"`
	CreatedBy     string    `json:"created_by"`
	Origin        Origin    `json:"origin"`

	Source    Source     `json:"source"`
	Build     Build      `json:"build"`
	Workloads []Workload `json:"workloads"`
	Volumes   []Volume   `json:"volumes"`
	Slots     []Slot     `json:"slots"`
	Routing   Routing    `json:"routing"`
	Runtime   RuntimeRef `json:"runtime"`
	Deploy    Deploy     `json:"deploy"`
	Health    Health     `json:"health"`
	Resources Resources  `json:"resources"`
	Egress    Egress     `json:"egress"`
	Retention Retention  `json:"retention"`

	// Availability is how the app is kept running when its host is lost
	// (R-419, R-422). Left out of an app that says nothing, which is most.
	Availability Availability `json:"availability,omitzero"`

	// Warnings are carried, not resolved. A warning is never a blocker —
	// blockers are PLAN_* errors.
	Warnings []Warning `json:"warnings,omitempty"`
}

type AutoDeploy struct {
	Enabled bool              `json:"enabled"`
	Trigger AutoDeployTrigger `json:"trigger,omitempty"`

	// Branch is what the branch trigger follows. Empty follows Source.Ref,
	// the ref the app was deployed from.
	Branch string `json:"branch,omitempty"`

	// TagPattern is what the release trigger counts as a release: a glob
	// matched against tag names (`release-*`). Empty means a stable semantic
	// version, v1.2.3 (O-58).
	TagPattern string `json:"tag_pattern,omitempty"`
}

type AutoDeployTrigger string

type Availability struct {
	// Standby overrides host policy's standby for this app (R-419). How an
	// app runs is the spec's (R-020), so the override is here rather than a
	// setting beside it.
	Standby StandbyMode `json:"standby,omitempty"`

	// Priority orders the apps a host starts at failover when host policy
	// allow_failover_oversubscription let their standbys be placed past what
	// it keeps free: higher first, then by app. 0 by default; negative is
	// allowed, for an app that should start last (R-422).
	Priority int `json:"priority,omitempty"`
}

type Build struct {
	Strategy   BuildStrategy `json:"strategy"`
	AdapterRef string        `json:"adapter_ref"`

	Dockerfile  string `json:"dockerfile,omitempty"`
	Context     string `json:"context,omitempty"`
	Target      string `json:"target,omitempty"`
	ComposeFile string `json:"compose_file,omitempty"`
	StaticDir   string `json:"static_dir,omitempty"`

	// GeneratedFiles are build inputs Pando produced rather than found, keyed
	// by path relative to the build context. Written into the checkout before
	// the build and never into anybody's repository.
	//
	// Opaque to core, which stores and replays them and interprets nothing:
	// only the builder that produced them knows what they mean (R-251). Today
	// that is a Railpack plan, or a Dockerfile Pando wrote and the files it
	// references; a spec stored before issue #172 carries a nixpacks plan.
	//
	// They live in the spec because R-020 makes the state store the sole record
	// of how an app runs, and a plan regenerated at each build is not a record:
	// the same commit would build differently after the planner was upgraded.
	// Storing them pins the build to what somebody reviewed, and makes it
	// something they can edit without putting deployment files in their repo —
	// which is the other half of R-020.
	//
	// Append-only like the rest of the spec (R-152), so an edit is a revision
	// that can be diffed and rolled back.
	GeneratedFiles map[string]string `json:"generated_files,omitempty"`

	// Args are build arguments and are stored in the clear. Anything sensitive
	// is a slot — this is why there is no secret-bearing build arg.
	Args []KV `json:"args,omitempty"`

	// IsolationFloor is deliberately separate from Runtime.IsolationFloor
	// (R-114): how isolated a build must be is a different question from how
	// isolated the running app must be.
	IsolationFloor IsolationClass `json:"isolation_floor"`

	TimeoutSeconds int        `json:"timeout_seconds"`
	EgressMode     EgressMode `json:"egress_mode"`
	EgressAllow    []string   `json:"egress_allow,omitempty"`
}

type BuildStrategy string

type Change struct {
	Class Class  `json:"class"`
	Path  string `json:"path"`

	// Summary is written for the person confirming the change, not for a log.
	Summary string `json:"summary"`

	From any `json:"from,omitempty"`
	To   any `json:"to,omitempty"`
}

type Class string

type Defaults struct {
	// Adapters. Empty means the install has none of that category configured,
	// and the planner's PLAN_ADAPTER_NOT_CONFIGURED says so far better than
	// anything this could invent.
	RoutingAdapter string
	RuntimeAdapter string
	BuilderAdapter string

	// RoutingMode is the routing adapter's declared default (R-162): adding an
	// app uses it without asking.
	RoutingMode RoutingMode

	// BaseDomain is what a subdomain is carved out of. Only consulted in
	// subdomain mode.
	BaseDomain string

	// Isolation floors from host policy (R-024, R-114).
	BuildIsolation   IsolationClass
	RuntimeIsolation IsolationClass

	BuildTimeoutSeconds int

	// Resources are the host defaults every new app inherits (R-240).
	Resources Resources

	Retention Retention
}

type Deploy struct {
	Strategy   DeployStrategy `json:"strategy"`
	AutoDeploy AutoDeploy     `json:"auto_deploy"`

	// AutoRollback is off by default (R-147), because an app with no health
	// signal is running rather than unhealthy, and rolling back on a signal
	// that does not exist would be worse than leaving it alone.
	AutoRollback bool `json:"auto_rollback"`

	// RequireApproval is the app asking for a second pair of eyes on its own
	// deploys (R-154). Read from the running spec as well as the one being
	// deployed, so switching it off is itself approved. Host policy can require
	// the same of an app without its owner being able to turn it off.
	RequireApproval bool `json:"require_approval,omitempty"`
}

type DeployStrategy string

type Diff struct {
	Changes []Change `json:"changes"`
}

type Egress struct {
	Mode EgressMode `json:"mode"`
	List []string   `json:"list,omitempty"`

	Add    []string `json:"add,omitempty"`
	Remove []string `json:"remove,omitempty"`

	BlockPrivate *bool `json:"block_private,omitempty"`

	// Allowlist is the field Mode allowlist used before issue #79, when an
	// app's list replaced the install's instead of narrowing it. Read as List
	// by Normalize and never written.
	Allowlist []string `json:"allowlist,omitempty"`
}

type EgressMode string

type EnvEntry struct {
	Key       string  `json:"key"`
	Value     *string `json:"value,omitempty"`
	SlotRef   *string `json:"slot_ref,omitempty"`
	SecretRef *string `json:"secret_ref,omitempty"`

	// SlotPart takes one piece of the slot's connection string rather than
	// all of it, for an app that is configured the way libpq, Laravel and most
	// official images are: PGHOST, PGUSER and PGPASSWORD, or DB_HOST and
	// DB_PASSWORD, each its own variable. One slot fills them all, so a
	// provisioned database is one answer however many variables it takes.
	// Empty is the whole connection string. Set only with SlotRef.
	SlotPart SlotPart `json:"slot_part,omitempty"`

	// Source records where this entry came from, the way Port.Source and
	// Volume.Declared already do.
	//
	// It decides what survives a re-detection. Detection proposes a whole spec,
	// and accepting one used to replace the pinned spec entirely — so a
	// variable somebody typed was gone the moment they re-detected after adding
	// a Dockerfile, with the app still running and no sign anything had been
	// dropped. Provenance is what lets the two be merged instead: an entry a
	// person set outlives anything Pando worked out for itself.
	Source EnvSource `json:"source,omitempty"`
}

type EnvSource string

type File struct {
	Path string `json:"path"`

	// Content is stored in the clear and appears in an exported spec. It comes
	// out of the repository, so it is already as public as the repository —
	// anything sensitive belongs in a secret or a slot, not in a config file
	// somebody committed.
	Content string `json:"content"`

	// Mode is the file's permission bits, defaulting to 0644. Set for the
	// entrypoint script somebody mounts and expects to be executable.
	Mode int `json:"mode,omitempty"`
}

type Health struct {
	Source          HealthSource `json:"source"`
	Path            string       `json:"path,omitempty"`
	Port            int          `json:"port,omitempty"`
	IntervalSeconds int          `json:"interval_seconds"`
	TimeoutSeconds  int          `json:"timeout_seconds"`
	Retries         int          `json:"retries"`
}

type HealthSource string

type Healthcheck struct {
	Command         []string `json:"command,omitempty"`
	Path            string   `json:"path,omitempty"`
	Port            int      `json:"port,omitempty"`
	IntervalSeconds int      `json:"interval_seconds,omitempty"`
	TimeoutSeconds  int      `json:"timeout_seconds,omitempty"`
	Retries         int      `json:"retries,omitempty"`
}

type IsolationClass int

type KV struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type ModeSource string

type Mount struct {
	VolumeID string `json:"volume_id"`
	Path     string `json:"path"`
	ReadOnly bool   `json:"read_only"`
}

type Origin string

type Port struct {
	Number   int        `json:"number"`
	Protocol string     `json:"protocol"`
	Source   PortSource `json:"source"`
}

type PortSource string

type Resolution struct {
	Mode       ResolutionMode `json:"mode"`
	ServiceRef string         `json:"service_ref,omitempty"`
	Target     string         `json:"target,omitempty"`

	// SecretRef holds a literal value. A literal is stored as a secret rather
	// than inline, which keeps "export is safe to hand to someone" true without
	// a special case.
	SecretRef string `json:"secret_ref,omitempty"`
}

type ResolutionMode string

type ResourceLimits struct {
	CPUMillis   int   `json:"cpu_millis,omitempty"`
	MemoryBytes int64 `json:"memory_bytes,omitempty"`
}

type Resources struct {
	CPUMillis   int   `json:"cpu_millis"`
	MemoryBytes int64 `json:"memory_bytes"`
	DiskBytes   int64 `json:"disk_bytes"`

	// Overridden requires app.resources.override (R-241).
	Overridden bool `json:"overridden"`
}

type Retention struct {
	LogBytes         int64 `json:"log_bytes"`
	BackupDailyCount int   `json:"backup_daily_count"`
	SpecRevisions    int   `json:"spec_revisions"`
}

type Routing struct {
	AdapterRef string      `json:"adapter_ref"`
	Mode       RoutingMode `json:"mode"`
	ModeSource ModeSource  `json:"mode_source"`
	Hostname   string      `json:"hostname,omitempty"`
	PathPrefix string      `json:"path_prefix,omitempty"`
	Port       int         `json:"port,omitempty"`
}

type RoutingMode string

type RuntimeRef struct {
	AdapterRef     string         `json:"adapter_ref"`
	IsolationFloor IsolationClass `json:"isolation_floor"`
}

type SecretFormat string

type Slot struct {
	Key      string   `json:"key"`
	Type     SlotType `json:"type"`
	Required bool     `json:"required"`
	Evidence []string `json:"evidence,omitempty"`

	// Format is the shape the value must take, for a value the app checks:
	// a Laravel APP_KEY, a Rails SECRET_KEY_BASE. What "generate a value"
	// produces and what a literal is checked against (SecretFormat). Empty
	// for a slot whose value Pando knows nothing about.
	Format SecretFormat `json:"format,omitempty"`

	// Resolution nil means unfilled. A required unfilled slot blocks deploy
	// (R-132) at plan time, not at deploy time.
	Resolution *Resolution `json:"resolution,omitempty"`

	// Aliases are names a provisioned service also answers to on the app's
	// network: the compose service it replaced. The URL is rewired to the new
	// instance, but an app may reach the old name another way — a
	// `while ! </dev/tcp/db/5432` wait in its start command never finished
	// once `db` resolved to nothing (issue #90).
	Aliases []string `json:"aliases,omitempty"`

	// Scheme is how the app spells a provisioned service's URL: postgres or
	// postgresql for a Postgres slot, empty for the default. Drivers disagree
	// and each refuses the other's spelling — readflow's "unsupported database:
	// postgresql", SQLAlchemy 2's "Can't load plugin: sqlalchemy.dialects:
	// postgres" (issue #90) — so the spelling the app's own configuration used
	// is the one it is given, and recorded here because nothing is read from
	// the repository at deploy time (R-020).
	Scheme string `json:"scheme,omitempty"`
}

type SlotPart string

type SlotType string

type Source struct {
	Type SourceType `json:"type"`
	URL  string     `json:"url,omitempty"`

	// Ref is what the user asked for; Commit is what runs (R-120). Auto-deploy
	// advances Commit and creates a revision. A deploy never resolves Ref
	// implicitly at runtime.
	Ref    string `json:"ref,omitempty"`
	Commit string `json:"commit,omitempty"`

	Subdir string `json:"subdir,omitempty"`
	Image  string `json:"image,omitempty"`
	Digest string `json:"digest,omitempty"`

	// UploadID names a stored upload — the app's own ID, for `pando deploy ./`
	// (design 04 §4). An upload has no commit and no ref: there is no revision
	// to resolve, and pretending otherwise would put a fabricated commit in the
	// spec, which R-120 exists to prevent.
	UploadID string `json:"upload_id,omitempty"`

	// CredentialRef names an app-owned secret (O-3). The credential belongs to
	// the app, not the person who supplied it, so an app keeps deploying after
	// its author leaves; the supplier is recorded in the audit event instead.
	CredentialRef string `json:"credential_ref,omitempty"`
}

type SourceType string

type StandbyMode string

type Volume struct {
	ID            string       `json:"id"`
	Name          string       `json:"name"`
	Declared      VolumeSource `json:"declared"`
	SizeHintBytes int64        `json:"size_hint_bytes,omitempty"`
}

type VolumeSource string

type Warning struct {
	Code        string `json:"code"`
	Message     string `json:"message"`
	Dismissed   bool   `json:"dismissed"`
	DismissedBy string `json:"dismissed_by,omitempty"`
}

type Workload struct {
	Name       string   `json:"name"`
	Image      string   `json:"image,omitempty"`
	Command    []string `json:"command,omitempty"`
	Entrypoint []string `json:"entrypoint,omitempty"`
	WorkingDir string   `json:"working_dir,omitempty"`

	Env       []EnvEntry   `json:"env,omitempty"`
	Ports     []Port       `json:"ports,omitempty"`
	Mounts    []Mount      `json:"mounts,omitempty"`
	Files     []File       `json:"files,omitempty"`
	DependsOn []string     `json:"depends_on,omitempty"`
	Health    *Healthcheck `json:"healthcheck,omitempty"`

	// Aliases are other names the workload answers to on the app's private
	// network, beside its own. A compose file's `container_name` is one: the
	// other services address it by that name — an nginx upstream, a database
	// host in a URL — and Pando, which names containers itself, made the name
	// resolve nowhere (issue #90). Reachable only inside the app, like the
	// workload's own name (R-026).
	Aliases []string `json:"aliases,omitempty"`

	// Exposed means reachable through the proxy at a sub-route (R-026).
	Exposed bool `json:"exposed"`

	// Primary is the workload the app's URL resolves to. Exactly one workload
	// has it: the app has one canonical endpoint.
	Primary bool `json:"primary"`

	Resources *ResourceLimits `json:"resources,omitempty"`

	// Build is how this workload's image is produced, when it is built rather
	// than pulled. Nil means Image names something that already exists.
	//
	// Per workload because that is how a compose file describes an app: each
	// service either names an image or says how to build one, and a file with
	// two buildable services needs two images. The app-level Build block cannot
	// say that — it is one build — which is why importing a compose file used
	// to discard the build instructions entirely.
	Build *WorkloadBuild `json:"build,omitempty"`
}

type WorkloadBuild struct {
	Context    string `json:"context,omitempty"`
	Dockerfile string `json:"dockerfile,omitempty"`
	Target     string `json:"target,omitempty"`

	// Args are this service's own build arguments, from its compose `build:
	// args:`. Stored in the clear, like the app's.
	Args []KV `json:"args,omitempty"`
}