docker

type BootError struct {
	Phase   string
	Err     error
	LogTail string
}

type BootRequest struct {
	// Allowed is the caller's current permission check, repeated before effects.
	Allowed func(context.Context) error
	// Log reports phase entry. It receives no environment values or command output.
	// Nil disables progress reporting without changing boot behavior.
	Log          deploy.Logf
	Slug         string  // the application's current display address; not routing identity
	ExactOrigins *string // nil retains captured route context; non-nil is the owner's exact browser origin (empty means none).
	ServingLabel string  // immutable label for a standing host route; separate from secret scope
	DataClass    string  // what a standing deployment holds; "" or "synthetic" lets a moved service be recreated
	Name         string  // the public app container: apptown-preview-change-7, <prefix>env-<slug>-main
	StackID      string  // owner of its stack (services, init, network): pvsnap-change-7, pv<step>, env-<slug>-<env>
	Workspace    string  // the tree to boot: a worktree, a run workspace, the project checkout
	// HostPort pins a standing deployment's stable port; 0 lets docker pick
	// (previews).
	HostPort int
	// Persistent marks a standing deployment: its needs are reused when
	// already running (data survives releases), everything restarts with the
	// host, and the labels say class=env — never reaped. Previews are the
	// opposite on every count.
	Persistent bool
	// Deployment names which deployment's secret bindings apply
	//: "preview" for every preview, the standing
	// deployment's name for a deploy or rebuild. Empty means preview.
	Deployment string
	// Services overrides the contract's sidecars (a workflow's services:
	// declaration); empty means the contract's own.
	Services []deploy.ServiceSpec
	Probe    time.Duration
	// Docker is which daemon the stack boots on: AppTown's own by default,
	// an attached host's for a standing deployment bound there.
	Docker Scope
	// PageCheck is the gate's extra question about the page a visitor
	// opens: a client-only site's page answers (below 400), and a
	// server app's root is not refused (check.PageRefusal). Gates ask it;
	// the try-it button and the rebuild do not.
	PageCheck bool
	// VisitorHost is the host name a visitor's request carries through the
	// front door (change-7.preview.example, shop.apps.example.com); the page
	// check sends it, so a host allow-list is judged as a visitor meets it.
	// "" sends the probe address's own.
	VisitorHost  string
	ReleaseImage string // Recorded public artifact for a historical release preview.
	// Incarnation names what the boot serves, for a preview: its source and
	// the digest of its prepared public values. It is labelled on the app
	// container (apptown.incarnation), and a reuse matches it. "" is none.
	Incarnation string
	// Scratch is the boot's own folder, where a prepared boot keeps its
	// Docker configuration; its owner sweeps it (SweepBootConfigs). A
	// prepared boot without one is refused.
	Scratch  string
	Identity *deploy.DockerIdentity // Standing execution from a selected source; previews have no deployment identity.
	// Recorded is a release's images: IDs already on this daemon, or images
	// by digest it pulls. The boot runs them and builds nothing
	// (PrepareImages), for a standing deployment or a release's preview.
	// nil prepares each image from the source.
	Recorded *RecordedImages
	// Revision is the committed revision a standing deployment serves. A
	// public static part is told its release identity
	// (appcontract.Contract.PublicRelease), answers it at ReleasePath, and
	// the boot witnesses that answer. "" (a preview of a worktree) tells it
	// nothing and witnesses nothing.
	Revision string
	// Record records what a standing deployment's boot creates (its
	// containers, a network it made, data volumes, the images it pulled or
	// built), as each is created: its take-down deletes exactly that. nil
	// records nothing (previews and runs have their own cleanup). A
	// creation that cannot be recorded fails the boot.
	Record         func(deploy.Owned) error
	Storage        deploy.StorageBindings
	RestoreStorage deploy.StorageRestore
	// Owned is the deployment's list before this boot (Ownership.Recorded).
	Owned []deploy.Owned
	// Sealed boots a restore rehearsal: no address outside its host, its
	// own network, its needs filled before any init step, and only the
	// public part (Sealed). nil boots as before.
	Sealed *Sealed
	// Fill puts a deployment's data back after its needs are up and before
	// any init step, part or the public app runs, on the stack's network
	// ("" when it has none), so nothing of the app writes into, or answers
	// from, the new and empty data first: a rebuild after AppTown was
	// restored. A failing fill ends the boot (PhaseFill) with nothing of the
	// app started. nil fills nothing.
	Fill func(network string) error
	// contains filtered or unexported fields
}

type BootResult struct {
	HostPort int
	Network  string
	Stack    ResolvedStack
	// Page is what the front-page check saw, passed or refused; nil when
	// the boot did not ask (no PageCheck, or it stopped before).
	Page *PageWitness
}

type Booter interface {
	Boot(ctx context.Context, req BootRequest, c *appcontract.Contract) (BootResult, error)
}

type CLI struct{ Binary string }

type Client interface {
	Run(context.Context, string, Command) ([]byte, error)
}

type Command struct {
	Args    []string
	Stdin   io.Reader
	Stdout  io.Writer     // nil captures combined output; non-nil streams stdout only
	Stderr  io.Writer     // optional separate stream, e.g. the build log
	Timeout time.Duration // bounded observations retain the process-tree runner
	// Env adds NAME=value pairs to the docker CLI's own environment, so a
	// secret reaches a container by `-e NAME` and never appears in an
	// argument list another process can read.
	Env []string
}

type ContainerEvent struct {
	Container string    // the container's name
	Action    string    // "oom", "die" or "kill"
	At        time.Time // the daemon's time for it
	ExitCode  *int      // a die's exit code; nil otherwise
	// Deployment and Generation are the container's AppTown identity labels,
	// as the event carried them: "" for a container that has none (a
	// deployment's needs and other parts outlive its generations).
	Deployment, Generation string
}

type ContainerLimit struct {
	Name        string
	MemoryBytes int64   // 0: no limit
	CPUs        float64 // 0: no limit
	// CPUUnread says a CPU constraint was set that AppTown could not
	// read as a number of CPUs: never counted as no limit.
	CPUUnread bool
	// AppTown says AppTown started it (it carries a class label); Class
	// and Owner are those labels, "" where absent, so a reader can say
	// whose it is: a deployment's, a preview's, agent work, AppTown's own.
	AppTown bool
	Class   string
	Owner   string
}

type ContainerState struct {
	Status       string    `json:"status"`
	ExitCode     int       `json:"exitCode"`
	OOMKilled    bool      `json:"oomKilled"`
	RestartCount int       `json:"restartCount"`
	StartedAt    time.Time `json:"startedAt"`
	FinishedAt   time.Time `json:"finishedAt"`
	Health       string    `json:"health"`
}

type Contributions interface {
	EnvFor(context.Context) ([]string, error)
	BrowserEnv(context.Context) (string, error)
}

type DataMount struct {
	Volume, Bind string
	Found        bool
}

type Delivery struct {
	Env      func(consumer string) map[string]string
	Receipts []SecretReceipt
	Profile  string
}

type Dependencies struct {
	Secrets      SecretResolver
	Needs        NeedCatalog
	Registry     RegistryLogin
	Integrations Contributions
	Routes       Routes
	Probe        Prober // nil is the default probe
	// The images a boot runs for itself, from the tool versions snapshot its
	// caller's unit of work took: the file server for static parts, an image
	// with chown for handing a volume to the app's user ("" skips it), and
	// the df a new boot's disk admission runs.
	StaticServer string
	ChownImage   string
	DFImage      string
}

type Driver struct {
	Now func() time.Time // completion time of a current readiness sample
	// Allowed rechecks the caller before boot phases; nil is an unguarded caller.
	Allowed      func(context.Context) error
	ServingLabel string                                                          // immutable owner-supplied routing label, independent of source.Slug
	Scope        func(context.Context) (Scope, error)                            // which daemon: AppTown's own, or an attached host's
	Boot         Booter                                                          // the stack boot
	URL          func(servingLabel, deployment string, port int) (string, error) // the address a deployment is reached at
	AfterRelease func(p deploy.Placement)                                        // what follows a release (a backup)
	// Registry is the credential a release's images by digest are pulled
	// with, and Scratch the folder each pull's own Docker configuration is
	// written under (RecordedImages). A credential that cannot be read is
	// an error, never an anonymous pull.
	Registry func() (*RegistryCredential, error)
	Scratch  string
	// Owner records what the deployment's boot creates on the host; nil
	// records nothing, and then a take-down deletes only the container.
	Owner          deploy.Owner
	Storage        deploy.StorageBindings
	RestoreStorage deploy.StorageRestore
	// Owned reads the deployment's list, so a boot resets only what the
	// AppTown recorded making; nil reads nothing.
	Owned func(context.Context) ([]deploy.Owned, error)
	// DataClass is what the deployment declares it holds; only
	// "synthetic" lets a standing service be replaced when its declared
	// parameters move. "" is unknown, and protected.
	DataClass string
	// Fill, when set, puts the deployment's data back in this boot, after
	// its needs and before anything of the app starts (BootRequest.Fill):
	// a rebuild after AppTown was restored.
	Fill func(network string) error
}

type HealthController struct {
	// contains filtered or unexported fields
}

type HealthDependencies struct {
	Watch      func(context.Context) []Watched                                           // the standing deployments the apptown runs on hosts it talks to
	PublicPart func(context.Context, Watched) *appcontract.Part                          // the running release's public part, nil when unreadable
	FrontDoor  func() map[string]string                                                  // the front-door signal a probe sends
	Record     func(ctx context.Context, w Watched, kind string, payload map[string]any) // the receipt of a restart or a hold
	Now        func() time.Time                                                          // the clock; nil means time.Now
	// AfterSweep runs once at the end of each sweep: the owner's reading of
	// what the daemons reported since the last (limit events). nil: none.
	AfterSweep func(context.Context)
}

type Host struct {
	// contains filtered or unexported fields
}

type HostInfo struct {
	MemoryBytes int64
	CPUs        int
	DataRoot    string
}

type InstalledBrowser struct {
	ID     string
	Values map[string]string
}

type Inventory struct {
	Scope func(context.Context) (Scope, error)
	Also  []string // containers the host also reports by name (the caller's own database on its built-in host)
	// Images is the image references the deployments on the target
	// recorded (deploy.Owned of kind image), each asked for exactly.
	Images func(context.Context) ([]string, error)
}

type Names struct {
	// contains filtered or unexported fields
}

type NeedCatalog interface {
	// Fulfil refuses a need it cannot fulfil as declared with the sentence
	// the release and preview show (an unknown need, a withdrawn
	// declaration).
	Fulfil(ctx context.Context, needs []string, params map[string]map[string]string) (services []deploy.ServiceSpec, env map[string]string, err error)
	Data(ctx context.Context, capability string) (string, error)
}

type Ownership struct {
	// Storage records engine identity separately from deletion ownership.
	Storage        deploy.StorageBindings
	RestoreStorage deploy.StorageRestore
	Record         func(deploy.Owned) error
	Needs          map[string]string
	// Recorded is the deployment's list as it stood before this boot: what
	// AppTown may delete (a synthetic need's volume, when its parameters
	// moved). Nothing else is ever deleted.
	Recorded []deploy.Owned
	// Persistent is a standing deployment's stack: its parts live with it
	// (class env, restarted with the host), never idle-reaped.
	Persistent bool
	// Info is the informational labels a standing deployment's things carry
	// for people (dockerlabel.Informational); nil for previews and runs.
	Info []string
}

type PageWitness struct {
	Path   string `json:"path"`
	Host   string `json:"host,omitempty"`
	Status int    `json:"status,omitempty"` // 0: no answer
	Passed bool   `json:"passed"`
	// Verdict says what the answer means for a visitor, in a sentence.
	Verdict string `json:"verdict"`
}

type Prefix string

type Prepared struct {
	Version int `json:"version"`
	// Contract is the selected contract the values were prepared for: the
	// boot runs it, and nothing else may use them (preparedSecrets).
	Contract *appcontract.Contract `json:"contract"`
	// Services replace the contract's sidecars (a workflow's services:).
	Services []deploy.ServiceSpec         `json:"services,omitempty"`
	Secrets  map[string]map[string]string `json:"secrets,omitempty"` // per consumer
	Receipts []SecretReceipt              `json:"receipts,omitempty"`
	Profile  string                       `json:"profile,omitempty"`
	Needs    []deploy.ServiceSpec         `json:"needs,omitempty"`
	NeedEnv  map[string]string            `json:"needEnv,omitempty"`
	NeedData map[string]string            `json:"needData,omitempty"`
	// Env is the attached integrations' server environment: it may hold
	// secrets, and is never public.
	Env []string `json:"env,omitempty"`
	// SecretsFingerprint identifies Secrets and Env without revealing them:
	// a keyed digest the caller that holds the key sets ("" when both are
	// empty). A secret's version does not always change with its value (an
	// Infisical value, a built-in one set again), so the values themselves
	// are what a changed secret or integration value changes, and with it
	// the preview's identity.
	SecretsFingerprint string              `json:"secretsFingerprint,omitempty"`
	BrowserEnv         string              `json:"browserEnv"`
	FrontDoor          map[string]string   `json:"frontDoor,omitempty"`
	Origins            string              `json:"origins,omitempty"`
	Registry           *RegistryCredential `json:"registry,omitempty"`
}

type Probe struct{ Settle time.Duration } // Settle 0 is the three-second production default

type Prober interface {
	Check(ctx context.Context, dk Scope, container, url string, timeout time.Duration, probe RenderedProbe) (bool, string)
}

type PublicPrepared struct {
	Version            int                   `json:"version"`
	Contract           *appcontract.Contract `json:"contract"`
	Services           []deploy.ServiceSpec  `json:"services,omitempty"`
	Receipts           []SecretReceipt       `json:"receipts,omitempty"`
	Profile            string                `json:"profile,omitempty"`
	SecretsFingerprint string                `json:"secretsFingerprint,omitempty"`
	Needs              []deploy.ServiceSpec  `json:"needs,omitempty"`
	NeedEnv            map[string]string     `json:"needEnv,omitempty"`
	NeedData           map[string]string     `json:"needData,omitempty"`
	BrowserEnv         string                `json:"browserEnv"`
	FrontDoor          map[string]string     `json:"frontDoor,omitempty"`
	Origins            string                `json:"origins,omitempty"`
}

type ReadinessSample struct {
	Placement       deploy.Placement
	Artifact, Image string
	Part            *appcontract.Part
	Timeout         time.Duration
}

type RecentLog struct {
	Text      string
	Truncated bool
}

type RecordedImages struct {
	Parts, Init map[string]string
	// Login is the registry credential images by digest are pulled with,
	// written into a Docker configuration of the pull's own under Scratch
	// (WithBootConfig), never logged in where another command could find
	// it. nil pulls anonymously.
	Login   *RegistryCredential
	Scratch string
}

type Refusing struct{ Attached Client }

type RegistryCredential struct {
	Host, Username, Token string
}

type RegistryLogin interface {
	Login(ctx context.Context, dk Scope, imageRef string) error
}

type RenderedProbe struct {
	Policy      *appcontract.HealthPolicy
	PolicyError error
	Path        string            // HTTP path to hit (default "/")
	Headers     map[string]string // front-door shaping (ingress.go), nil = probe naked
	Expect      int               // required HTTP status; 0 = below 400 (appcontract.Ready)
	Release     string            // a release identity the answer must serve (appcontract.ServesRelease); "" = none
	Grace       time.Duration     // startupGrace floor — extends the probe deadline
	// The controller's liveness variants (probeApp/cold-boot uses only the HTTP
	// fields above): a TCP connect, or a command run inside the container.
	TCP  bool     // dial the port instead of an HTTP GET
	Exec []string // `docker exec` this command; exit 0 = healthy
}

type ResolvedNeed struct {
	deploy.ServiceSpec
	Data string
}

type ResolvedStack struct {
	// Plan owns the resolved execution values for each consumer.
	Plan *appcontract.Plan
	// NeedNames retain only the output names, for scoped-secret admission.
	NeedNames []string
	// Services are the sidecars (the contract's, or a workflow override)
	// followed by the needs' emulators — the stack, in start order.
	Services []deploy.ServiceSpec
	// Needs are the fulfilled needs (the tail of Services) with where each
	// emulator keeps its data; the intranet gives each a named volume.
	Needs []ResolvedNeed
	// Secrets is the broker's delivery for this boot: per consumer, the
	// values to inject; and the receipts (names, stores, versions — never
	// values) the boot records.
	Secrets Delivery
}

type Routes interface {
	FrontDoorHeaders() map[string]string
	PublicOrigins(ctx context.Context) string
}

type Runtime struct {
	ID      string            `json:"id"`
	Image   string            `json:"image"`
	Running bool              `json:"running"`
	Labels  map[string]string `json:"labels"`
	// MemoryLimit is the memory the container is held to, in bytes; 0 is no
	// limit.
	MemoryLimit int64 `json:"memoryLimit"`
	// State is what the daemon says of the container's process: nil when
	// the answer carried none, which is "not reported", never a clean exit.
	State *ContainerState `json:"state,omitempty"`
}

type Scope struct {
	Client   Client
	Host     string // DOCKER_HOST, "" for AppTown's own daemon
	Hostname string // the attached host's address, for probes and plain URLs
	Domain   string // the attached host's ingress domain, "" when it has none
	// Config is a Docker configuration folder of this scope's own, for one
	// boot (WithBootConfig); "" is the ambient one.
	Config string
	// Lifetime bounds every command through this scope: when it ends, each
	// command still running is stopped (a boot's lifetime, WithLifetime). nil
	// is no bound beyond each command's own.
	Lifetime context.Context
	// Now is the clock a container's apptown.created label is stamped from,
	// which the reaper judges a container's age by; nil is the real one.
	Now func() time.Time
	// NoStreams is a daemon reached through a proxy that carries plain
	// requests and answers but not attached streams (Portainer's Docker
	// proxy): a step that streams runs as a job instead (RunStep).
	NoStreams bool
	// Redact replaces the values a boot generated (its needs' credentials)
	// in what a failure keeps of a container's own output, before that is
	// cut short (Boot sets it once its needs are resolved); nil keeps the
	// text. It is never applied to what AppTown compares or acts on.
	Redact func(string) string
	// Instance is the installation id every container, volume and network
	// made through this scope is labelled with (dockerlabel.Instance): the
	// inventory reports as not accounted for only what carries it. "" labels
	// nothing, and then nothing reads as this installation's.
	Instance string
}

type Sealed struct {
	// Fill fills the stack's new, empty needs from a copy, on its own
	// network, after they are healthy and before any init step reads them.
	Fill func(network string) error
	// ProbeImage runs the in-network probe; it needs a shell, nc and awk
	// (busybox has them).
	ProbeImage string
	// Host is the host name the probe's requests carry: the deployment
	// the rehearsal stands in for, as its visitors reach it.
	Host string
}

type SecretReceipt struct {
	Name      string   `json:"name"`
	Store     string   `json:"store"`
	Version   string   `json:"version"`
	Consumers []string `json:"consumers"`
	Generated bool     `json:"generated,omitempty"`
}

type SecretResolver interface {
	Resolve(ctx context.Context, slug, deployment, ws string, c *appcontract.Contract, allowed func(context.Context) error) (Delivery, error)
}

type SourceInputs struct {
	Version  int                  `json:"version"`
	Revision string               `json:"revision"`
	Services []deploy.ServiceSpec `json:"services,omitempty"`
}

type Step struct {
	Exec    string   // the running container to run in
	Image   string   // else: a throwaway container of this image
	Options []string // docker run options for Image (--network, -v, --volumes-from)
	Env     []string
	// Command is the shell command; Argv, when set instead, runs as it is.
	Command string
	Argv    []string
	Stdin   io.Reader
	Stdout  io.Writer
	// Name names the container a job makes (a person finds a job a stopped
	// AppTown left by it, and by its labels); "" lets the daemon name it.
	Name string
}

type Watched struct {
	DeploymentID, ProjectID ids.ID                // the selected records, never resolved again by name
	Identity                deploy.DockerIdentity // the settled deployment and generation on this host
	Slug                    string                // the application
	Name                    string                // the deployment
	HostPort                int
	Container               string
	Docker                  Scope // the daemon it stands on
}