backup

type AppCreateRequest struct {
	AppID string

	// Kind is rolling or on_delete. An on_delete backup is kept until somebody
	// discards it (R-204), so it carries no retention at all.
	Kind string

	// Spec is the app's pinned spec, stored beside the data. Without it a
	// restore has bytes and no idea what ran them.
	Spec json.RawMessage

	// Volumes are the app's volumes, resolved to their runtime and handle.
	Volumes []VolumeRef

	DestinationRef string
	RetainFor      time.Duration
}

type AppRestoreRequest struct {
	AppID      string
	AdapterRef string
	ObjectName string

	// Volumes are the app's volumes as they exist now, to restore into.
	Volumes []VolumeRef

	// Confirm is required. Restoring replaces the app's data with what was in
	// the backup, and anything written since is gone.
	Confirm bool
}

type AppRestoreResult struct {
	Manifest       Manifest
	VolumesApplied int
}

type CreateRequest struct {
	// Passphrase is supplied at backup time and never stored (R-213). Losing it
	// makes the bundle unusable (R-214), which is an accepted cost and one the
	// console states at creation rather than in documentation.
	Passphrase secret.Value

	// DestinationRef names the backup adapter to write to. Empty uses the
	// configured default.
	DestinationRef string

	// RetainFor is how long to keep it. Zero means keep until discarded.
	RetainFor time.Duration
}

type Created struct {
	ObjectName  string
	AdapterRef  string
	SizeBytes   int64
	Manifest    Manifest
	RetainUntil *time.Time
}

type Entry struct {
	Name   string `json:"name"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

type Manifest struct {
	Version   int       `json:"version"`
	Kind      string    `json:"kind"`
	CreatedAt time.Time `json:"created_at"`

	// PandoVersion and SchemaVersion are what restore checks compatibility
	// against. The schema version is the migration number: a bundle from a
	// newer schema cannot be restored into an older binary, because the
	// migrations that would make sense of it do not exist here yet.
	PandoVersion  string `json:"pando_version"`
	SchemaVersion uint   `json:"schema_version"`

	// Entries is every file in the bundle with its size and checksum. Restore
	// compares against this before applying, and the comparison is what makes
	// "incomplete" a detectable state rather than a surprise.
	Entries []Entry `json:"entries"`

	// Counts are object counts from the state store — apps, users, grants,
	// specs, volumes. Checksums prove the bytes arrived; counts prove the
	// bytes describe the install someone thinks they are restoring. An
	// operator staring at a restore prompt needs the second one.
	Counts map[string]int `json:"counts"`
}

type RestoreRequest struct {
	AdapterRef string
	ObjectName string
	Passphrase secret.Value

	// Confirm is Sequence D step 3. Restoring replaces the install — every app,
	// every user, every secret — and a caller that has not said so explicitly
	// is a caller who meant to verify.
	Confirm bool
}

type RestoreResult struct {
	Manifest       Manifest
	VolumesApplied int

	// EdgeVolumesApplied counts the edge's storage put back — Traefik's
	// certificates (EdgesPrefix).
	EdgeVolumesApplied int

	// UploadsApplied counts uploaded source archives put back (O-37).
	UploadsApplied int
}

type Service struct {
	Registry *api.Registry

	// DatabaseURL is dumped and restored. Held as a secret.Value because it
	// carries the password and would otherwise reach a log line the first time
	// someone logged the config (R-194).
	DatabaseURL secret.Value

	// SecretsKeyPath is the local secrets adapter's key file. Without it in the
	// bundle, a restored install has every app's ciphertext and nothing to
	// decrypt it with — which looks like a successful restore until an app
	// starts (R-212).
	SecretsKeyPath string

	// TokenKeyPath is core's API token key file (core/tokenkey). API tokens
	// are stored as HMAC-SHA-256 under it, so a restore without it holds every
	// token's digest and can check none of them (R-063, R-212). Empty leaves it
	// out, which only a test does: every install has one.
	TokenKeyPath string

	// UploadDir is where uploaded source archives are kept
	// (source.DefaultUploadDir). Each goes into the bundle and is put back by
	// a restore (O-37). Empty leaves them out, which only a test does.
	UploadDir string

	// State supplies everything the bundle records about the install.
	State StateSource

	// Version and SchemaVersion go into the manifest so a restore can refuse a
	// bundle it cannot make sense of, rather than half-applying it.
	Version       string
	SchemaVersion uint

	// WorkDir is where the bundle is assembled before being encrypted and
	// streamed out. A DR bundle does not fit in memory.
	WorkDir string

	// Regrant re-applies the database's grant policy after a restore. Nil
	// skips it. pg_restore recreates every table and function with the
	// owner's default privileges, which hand the application role UPDATE
	// and DELETE on every month of the audit log until something revokes
	// them (R-027).
	Regrant func(ctx context.Context) error
}

type ServiceRef struct {
	ServiceID  string
	AppID      string
	AdapterRef string
	Handle     string
}

type StateSource interface {
	// Counts are object counts for the manifest: apps, users, grants, specs,
	// volumes. Checksums prove the bytes arrived; counts prove the bytes
	// describe the install the operator thinks they are restoring.
	Counts(ctx context.Context) (map[string]int, error)

	// AdapterConfigs and HostPolicy are exported verbatim.
	AdapterConfigs(ctx context.Context) ([]byte, error)
	HostPolicy(ctx context.Context) ([]byte, error)

	// VolumesToSnapshot lists every live volume with the runtime that holds it.
	VolumesToSnapshot(ctx context.Context) ([]VolumeRef, error)

	// ServicesToSnapshot lists every provisioned service with the adapter that
	// holds it (R-131).
	ServicesToSnapshot(ctx context.Context) ([]ServiceRef, error)
}

type Verified struct {
	Manifest Manifest

	// Found is every entry actually present, by name.
	Found map[string]Entry
}

type VolumeRef struct {
	// AppID names the app the volume belongs to. A volume ID is unique only
	// within its app — two apps may both keep one called "data" — so a
	// bundle holding every app's volumes names each entry by both.
	AppID      string
	VolumeID   string
	AdapterRef string
	Handle     string
}

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