deploy

type Artifact struct {
	Kind string // compose | do-app-spec | docker-source | ...
	Body []byte
	Hash string
	// Source is the selected software the artifact was rendered from, for
	// drivers that build from source on the host (the built-in Docker
	// host). Never serialized: the receipt carries Body and Hash, and a
	// staged workspace belongs to one execution.
	Source *Source
}

type BucketData interface {
	BucketConnection(ctx context.Context, bucket string) (Connection, error)
	TearDownStorage(ctx context.Context, p Placement, td TakeDown) TakenDown
}

type Checkpoint func(map[string]any) error

type Connection struct {
	Host     string
	Port     int
	Database string
	User     string
	Password string
	SSLMode  string
}

type ConsumerSecrets interface {
	EnvFor(consumer string) map[string]string
}

type Controls struct {
	Liveness bool
	Rollout  bool
}

type DockerIdentity struct {
	Deployment HostLabel `json:"deployment"`
	Generation int64     `json:"generation"`
	Artifact   string    `json:"artifact"`
}

type Driver interface {
	// Reconcile brings the deployment to the artifact as the given
	// generation. The same idempotency key is the same attempt; checkpoint
	// records the provider's identifiers on the attempt as soon as they
	// exist, so recovery can use them.
	Reconcile(ctx context.Context, p Placement, generation int64, art Artifact, key string, log Logf, checkpoint Checkpoint) (Observation, error)
	// Resume picks up an attempt AppTown was interrupted in: given what
	// was noted, find out what the target did and finish the attempt,
	// active, failed, or honestly unknown.
	Resume(ctx context.Context, p Placement, generation int64, noted map[string]any, log Logf) (Observation, error)
	Observe(ctx context.Context, p Placement) (Observation, error)
	// Teardown removes exactly the recorded generation's deployment and
	// deletes what AppTown recorded creating for it (td.Owned): data
	// only when td.BackedUp says a final backup covers it. It never
	// deletes what is not on the list. An error means the serving thing
	// (container, app, stack, bucket) may still stand; anything else it
	// could not delete, and data it keeps, it reports as Left.
	Teardown(ctx context.Context, p Placement, generation int64, td TakeDown) (TakenDown, error)
	Controls() Controls
}

type FleetObserver interface {
	ObserveAll(ctx context.Context, ps []Placement) ([]Observation, error)
}

type Gate struct {
	// Image is the gate's image by digest, published for AppTown.
	Image string
	// Secret is this deployment's gate secret: the probe token and the
	// gate's credential when it redeems a ticket. It is held only in
	// memory while AppTown starts the deployment, and is delivered as the
	// provider's encrypted secret to the gate alone. Empty when AppTown
	// only observes or takes the deployment down, which needs no secret.
	Secret string
	// AppTown is AppTown's public origin, where the gate redeems tickets.
	AppTown string
	// Marker is this deployment's own random mark, recorded by AppTown
	// before anything is made and rendered into the gate's environment. It
	// is what proves an app found on the account by its name is this
	// deployment's and not another's of the same name: a take-down deletes
	// an app it did not record only when the app carries this mark.
	Marker string
}

type HostLabel string

type Ingress struct {
	Hosts             []string `json:"hosts"`
	URL               string   `json:"url"`
	CertificateDomain string   `json:"certificateDomain"`
}

type Inspector interface {
	Inspect(ctx context.Context, p Placement) (running bool, err error)
}

type IntranetNeed struct {
	Name    string
	Image   string
	Command []string
	// Entrypoint replaces the image's entrypoint (a need's start script).
	Entrypoint []string
	Env        map[string]string
	Health     string // a shell healthcheck (exit 0 = healthy); "" = none
	Data       string // the emulator's data directory; "" = ephemeral
	// Resources is the most the need's service may use; nothing declared
	// is no limit.
	Resources appcontract.Resources
}

type IntranetStack struct {
	// Prefix and Base begin the stack's name, router and volume keys
	// (portainer.StackNames): apptown- and dep-<key>.
	Prefix string
	Base   string
	Hosts  []string
	Domain string
	Image  string // the selected public release image
	// Command is the app's command; empty runs the image's own.
	Command []string
	Port    int
	// Resources is the public part's; each non-public part carries its own.
	Resources appcontract.Resources
	Env       map[string]string // the public part's prepared environment
	// Integrations are the project's attached integrations' values for the
	// public part, as a Docker host gives them: under its environment and
	// secrets.
	Integrations map[string]string
	// BrowserEnv is a static public part's browser values, the JSON its
	// file server answers at /_apptown/env.js ("{}" for none); "" for a
	// server app, which is not given them.
	BrowserEnv string
	Secrets    ConsumerSecrets
	// PublicPart names the public part, the consumer the app service is.
	PublicPart string
	DataDir    string
	Origins    string // APPTOWN_ORIGINS: the tiers a browser reaches the app at
	// Release is the public part's release identity
	// (appcontract.Contract.PublicRelease), APPTOWN_RELEASE, which its file
	// server answers at ReleasePath; "" when the public part is not static.
	Release string
	// Trust is the installer with the extra certificates the app's own
	// containers are given (internal/trust: APPTOWN_TRUST, which they run);
	// "" for none.
	Trust string
	Needs []IntranetNeed
	Init  []appcontract.InitContainer
	Parts []appcontract.Part // non-public app parts only
}

type Inventorier interface {
	Inventory(ctx context.Context) ([]Resource, error)
}

type Left struct {
	What   string
	Handle map[string]any
	Data   bool
	Why    string
}

type Logf = func(string, ...any)

type ManagedData interface {
	AppConnection(ctx context.Context, instance, database, user string) (Connection, error)
	Databases(ctx context.Context, instance string) ([]string, error)
	NewDatabase(ctx context.Context, instance, name, owner string) error
	DropDatabase(ctx context.Context, instance, name string) error
	Backups(ctx context.Context, instance string) ([]NativeBackup, error)
	DeleteInstance(ctx context.Context, instance string) error
}

type NativeBackup struct {
	CreatedAt time.Time
	SizeGB    float64
}

type NeedBinding struct {
	Env map[string]string // variables the app reads (DATABASE_URL, PG*)
	// Secret are variables the app reads whose values are credentials (an
	// object store's key secret): delivered as the target's secrets, never
	// in a receipt.
	Secret map[string]string
	Native map[string]any // target-native reference (an App Platform database component)
}

type NeedBindings map[string]NeedBinding

type NeedFulfiller interface {
	FulfilNeed(ctx context.Context, p Placement, need string, params map[string]string, log Logf) (NeedBinding, map[string]any, error)
}

type NeedRecorder interface {
	// Recorded is the need's recorded handle (its identity once
	// established, else what an earlier fulfilment asked for under
	// "requested"); nil when nothing is recorded.
	Recorded(ctx context.Context, placementID ids.ID, need string) (map[string]any, error)
	RecordIntent(ctx context.Context, placementID ids.ID, need string, requested map[string]any) error
	RecordIdentity(ctx context.Context, placementID ids.ID, need string, requested map[string]any, id, name string) error
}

type Observation struct {
	// RuntimeToken is an ephemeral probe incarnation (container ID and start
	// time, or provider deployment ID). It is never restored from a receipt.
	RuntimeToken string `json:"-"`
	// ReadinessPolicy comes from the admitted artifact, never a saved observation.
	ReadinessPolicy *appcontract.HealthPolicy `json:"-"`
	// HealthObservedAt and ArtifactHash identify a fresh exact-release health
	// witness. Zero/empty means the provider has supplied no such evidence.
	HealthObservedAt time.Time `json:"healthObservedAt,omitempty"`
	ArtifactHash     string    `json:"artifactHash,omitempty"`
	ImageDigest      string    `json:"imageDigest,omitempty"` // Actual image when execution built it from admitted source.
	Generation       int64     `json:"generation"`
	Rollout          string    `json:"rollout"` // pending | rolling | active | failed | absent
	Health           string    `json:"health"`  // healthy | unhealthy | unknown
	URL              string    `json:"url"`
	Handle           any       `json:"handle,omitempty"`
	Orphans          []string  `json:"orphans,omitempty"`
	// Running is the provider's own name for what runs, read from the same
	// answer as the rest: App Platform's active deployment id, a Portainer
	// stack's app image. Empty when the provider named none (nothing
	// deployed yet, or the app is gone). After a restore it says whether the
	// deployment still runs what AppTown recorded.
	Running string `json:"running,omitempty"`
}

type Owned struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	Data bool   `json:"data,omitempty"`
	Need string `json:"need,omitempty"`
}

type Owner interface {
	Created(ctx context.Context, o Owned) error
}

type Placement struct {
	ID         ids.ID         // the deployment's record identity: need records; opaque to the driver
	Label      HostLabel      // the deployment's name on its host: container labels, boot proofs
	Name       string         // the deployment's name (main, cloud, preview-12)
	Generation int64          // the generation last observed
	URL        string         // where it was last reached
	Handle     map[string]any // the provider's own identifiers
	Container  string         // the built-in host's container, when it has one
	HostPort   int            // the built-in host's port, when it has one
	// Gate, when set, puts the deployment behind AppTown's access gate
	// (design/subsystems/deployment.md, "Restored copies"): it holds production data
	// that only people AppTown admits may reach.
	Gate *Gate
}

type Preflighter interface {
	Preflight(ctx context.Context, p Placement, src Source, secrets ConsumerSecrets, log Logf) error
}

type PreviewSource struct {
	Worktree  string
	History   SelectedSource
	Snapshots string
}

type Renderer interface {
	Render(ctx context.Context, p Placement, src Source, bindings NeedBindings, secrets ConsumerSecrets, log Logf) (Artifact, error)
}

type Resource struct {
	// ObservedDaemonID belongs to this exact Docker or Portainer inventory snapshot, including cached observations.
	ObservedDaemonID string   `json:"-"`
	Kind             string   `json:"kind"` // app | database | registry | container | volume | network | image | stack | bucket
	Name             string   `json:"name"`
	ID               string   `json:"id,omitempty"`
	Status           string   `json:"status,omitempty"`
	Region           string   `json:"region,omitempty"`
	Size             string   `json:"size,omitempty"`
	Version          string   `json:"version,omitempty"` // engine + version for a database
	URL              string   `json:"url,omitempty"`
	Detail           string   `json:"detail,omitempty"`
	Tags             []string `json:"tags,omitempty"`
	// What the caller knows about it.
	Record   string         `json:"record"`             // RecordRecorded | RecordUnrecorded | RecordMissing
	Owner    string         `json:"owner,omitempty"`    // AppTown.owner label: which stack made it
	Stack    string         `json:"stack,omitempty"`    // the compose project label: which stack it belongs to
	Hosts    []ResourceHost `json:"hosts,omitempty"`    // the deployments running on / using it
	Retained *RetainedNote  `json:"retained,omitempty"` // left behind by a torn-down deployment
}

type ResourceFitter interface {
	FitResources(ctx context.Context, c *appcontract.Contract) (map[string]string, error)
}

type ResourceHost struct {
	ProjectID    ids.ID `json:"projectId,omitzero"`
	DeploymentID ids.ID `json:"deploymentId,omitzero"`
	Project      string `json:"project"`
	Deployment   string `json:"deployment"`
	Generation   int64  `json:"generation,omitempty"`
	Need         string `json:"need,omitempty"` // for a database: which need it fulfils
}

type RetainedNote struct {
	ID         ids.ID     `json:"id"`
	Project    string     `json:"project"`
	Deployment string     `json:"deployment"`
	RetainedBy string     `json:"retainedBy"`
	RetainedAt stamp.Time `json:"retainedAt"`
	// Reason, when the note comes from a label rather than the retained
	// ledger: why the deployment no longer records the resource.
	Reason string `json:"reason,omitempty"`
}

type RunningRecord interface {
	RecordedRunning(p Placement, released string) string
	AdoptRunning(running string) map[string]any
}

type SelectedSource struct{ Repository, Revision string }

type ServiceSpec struct {
	Name  string            `json:"name"`
	Image string            `json:"image"`
	Env   map[string]string `json:"env"`
	// Command overrides the image's default (a dependency emulator like MinIO
	// needs `server /data`). Sidecars from a contract leave it empty.
	Command []string `json:"command,omitempty"`
	// Entrypoint replaces the image's entrypoint, when set: a need's start
	// script (the s3 emulator's makes its bucket and account first). Docker
	// takes one executable for it; the rest go before Command (RunArgs).
	Entrypoint []string `json:"entrypoint,omitempty"`
	// ConfigAtStart says the service keeps none of what it is started with
	// in its data: everything it is configured with is set again at every
	// start. A standing one whose image, entrypoint, command or environment
	// changed is remade on its own volume, whatever its data class, as a
	// lifted size limit is.
	ConfigAtStart bool `json:"configAtStart,omitempty"`
	// KeepsImage says the service's data is in its image's own format: a
	// standing one whose image moved is not remade under ConfigAtStart but
	// refused unless its data is synthetic, as any data service is. A
	// Postgres of another major version cannot read the old files.
	KeepsImage bool `json:"keepsImage,omitempty"`
	// Health is a shell healthcheck command (exit 0 = healthy). When set, the
	// runtime applies it as docker --health-cmd and can gate startup on it.
	Health string `json:"health,omitempty"`
	// AppPart says the service is one of the app's own parts, not a need's:
	// it is given the extra certificates the app's containers trust
	// (internal/trust); a database or cache beside it calls out to nothing.
	AppPart bool `json:"appPart,omitempty"`
	// Public/host-port handling is caller-driven; these mark a non-public app
	// part started on the stack (Port for its PORT env, not a host mapping).
	Port int `json:"port,omitempty"`
	// Resources is the most a non-public app part or a need's service may
	// use; nothing declared is no limit.
	Resources appcontract.Resources `json:"resources,omitzero"`
	// Data is where a need's emulator keeps its data (its catalogue kind's
	// local data path), empty for a sidecar or an app part. A throwaway
	// start mounts a disposable volume there: an emulator whose image does
	// not make that folder itself (S3's) exits at once without it.
	Data string `json:"data,omitempty"`
	// Credentials are the values AppTown generated for this service (a
	// deployment's or a preview's need credentials), in its Env and in what
	// the app is given: a boot redacts them from every failure it returns
	// (docker.Host.Boot). Carried with a prepared boot to where it runs.
	Credentials []string `json:"credentials,omitempty"`
}

type SizePricer interface {
	SizePrices(ctx context.Context) (map[string]float64, error)
}

type Source struct {
	// Ingress is selected at admission, never recomputed from current names.
	Ingress *Ingress
	// Services is a replay of supplied sidecars after applying the generation
	// record; nil uses the original artifact inputs. It never changes Body/Hash.
	Services  []ServiceSpec
	Workspace string // a staged, self-contained checkout of Revision
	Revision  string // the committed tree the source is
	Slug      string // the application's slug, for naming on hosts
	Contract  *appcontract.Contract
	Images    map[string]string // part -> image id, or image by digest, when the parts were built earlier
	Init      map[string]string // init step -> image id, likewise
	// Published: Images and Init are images by digest in a registry, built
	// for Platform; false is image IDs that live only on the host that
	// built them.
	Published bool
	Platform  string
}

type SourceTree struct{ Directory, Revision string }

type StorageBinding struct {
	Need          string    `json:"need"`
	Volume        string    `json:"volume"`
	DataPath      string    `json:"dataPath"`
	DeclaredImage string    `json:"declaredImage"`
	ImageID       string    `json:"imageID"`
	RepoDigest    string    `json:"repoDigest,omitempty"`
	VolumeCreated time.Time `json:"volumeCreated"`
	VolumeDriver  string    `json:"volumeDriver"`
	Origin        string    `json:"origin"`
}

type StorageBindings interface {
	Get(context.Context, string, string) (StorageBinding, bool, error)
	Establish(context.Context, StorageBinding) error
	Retire(context.Context, string, string) error
}

type StorageCopy struct {
	Volume        string
	Physical      bool
	EngineImageID string
}

type StorageRestore interface {
	Image(need, declared string, source *StorageBinding) (image string, exact bool, err error)
	Restore(context.Context, *StorageBinding, StorageBinding) error
}

type TakeDown struct {
	Owned    []Owned
	BackedUp bool
	LastUser bool
	// Synthetic says the deployment's data is synthetic and nothing will
	// restore it (an eval copy's): Data entries are deleted with no final
	// backup. It still deletes only what Owned names.
	Synthetic bool
}

type TakenDown struct {
	Deleted []string
	Left    []Left
}