deployarchive

type AbandonResult struct {
	Removed []string
	// Kept names a path the journal recorded but that no longer holds what this
	// restore put there, so it was left alone.
	Kept []string
	// Restored names a ledger a recover had moved aside and this put back. It is
	// the operator's own capacity record, so an abandon that did not return it
	// would leave the deployment with none.
	Restored []string
}

type Action struct {
	// Entry is the archive entry this action installs, and it is the action's
	// IDENTITY: exactly one action exists per entry, and it is never empty. The
	// ledger's sidecars are not actions — they are removed by name at execution
	// time, because what the planner saw is stale by then. actionsDiffer keys on
	// this, so a duplicate or an empty one would let a changed action hide.
	Entry string
	// Path is where it lands.
	Path string
	// What names the item in the words an operator uses.
	What        string
	Disposition Disposition
}

type Archive struct {
	Dir      string
	Manifest Manifest
	// contains filtered or unexported fields
}

type AuthorityFacts struct {
	// Fingerprint is the issuing authority's public-key fingerprint, in the
	// shape `billet ca show` prints so an operator can compare the two by eye.
	Fingerprint string `json:"fingerprint"`
	NotAfter    string `json:"not_after"`

	// Rotating says a rotation was running when this was taken, which means the
	// previous authority's key travels in the archive too — it is what signs
	// what the control plane PRESENTS until the fleet has renewed.
	Rotating               bool     `json:"rotating"`
	PreviousFingerprint    string   `json:"previous_fingerprint,omitempty"`
	PreviousNotAfter       string   `json:"previous_not_after,omitempty"`
	UnexpectedFilesPresent []string `json:"unexpected_files_present,omitempty"`
}

type BackupRequest struct {
	// Dest is the directory to create. Must be absolute.
	Dest string
	// StateDir is the control plane's state directory.
	StateDir string
	// ConfigPath is where the deployment's billet.yaml lives.
	ConfigPath string
	// DeploymentID is what state.PeekDeploymentID answered. Required: a state
	// directory with no identity is not a deployment to back up.
	DeploymentID string
	// GitHub is the DEFAULT target's App identity from the config.
	GitHub GitHubIdentity
	// AppKeyPEM is the default target's App private key, already validated by
	// the caller.
	AppKeyPEM []byte
	// Targets are the further targets the deployment serves, each with its key.
	//
	// ALL OR NONE, like every other piece: a backup that captured one target's
	// key and not another's restores a control plane that serves half its
	// owners, and the half it does not serve fails hours later with a bare 401.
	Targets []TargetKey
	// ConfigBody is the billet.yaml as it stands. Copied for REFERENCE; restore
	// never installs it, because these paths are the source host's.
	ConfigBody []byte
	// Snapshot writes a consistent ledger copy to the absolute path it is given.
	// Nil exactly when ExternalLedger is set.
	Snapshot func(ctx context.Context, dest string) error
	// ExternalLedger says the ledger is not billet's to copy, and describes the
	// one this identity belongs to. Set exactly when Snapshot is nil.
	ExternalLedger *ExternalLedger
	// Now is the clock, so a test can pin the manifest's timestamp.
	Now func() time.Time
	// Hostname is recorded in the manifest as provenance.
	Hostname string
}

type Disposition int

type ExternalLedger struct {
	// Backend names the engine, e.g. "postgres". Required: an external ledger
	// nothing can name is a claim with no content.
	Backend string
	// DSNEnv is the environment variable holding the connection string. The
	// NAME, never the value.
	DSNEnv string
	// Migrations is what the live ledger had applied when this ran.
	Migrations []state.AppliedMigration
}

type FileRecord struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

type GitHubIdentity struct {
	// Org is the organization, or Repository the owner/name, exactly one of
	// them: a target is one or the other.
	Org            string `json:"org,omitempty"`
	Repository     string `json:"repository,omitempty"`
	AppID          int64  `json:"app_id"`
	ClientID       string `json:"client_id,omitempty"`
	InstallationID int64  `json:"installation_id"`
}

type Intent int

type LedgerFacts struct {
	// External says the ledger is not in this archive and never was.
	//
	// NOT DERIVED FROM THE ABSENCE OF THE ENTRY, which would make a truncated
	// archive and a deliberate one the same thing — and the truncated one would
	// then restore an identity paired with nothing, which is precisely the
	// half-deployment this package exists to refuse.
	External bool `json:"external,omitempty"`

	// Backend names the engine the external ledger lives in, e.g. "postgres".
	// Empty on a schema-1 archive and on any archive carrying its own ledger.
	Backend string `json:"backend,omitempty"`

	// DSNEnv is the ENVIRONMENT VARIABLE the source config named for the
	// connection string, and it is the variable's name rather than its value.
	// A DSN carries a password; recording one here would put it in a file that
	// travels off-site, which is the rule PostgresStateConfig already follows.
	//
	// INFORMATIONAL. A restore reports it and does not require the target to
	// agree: naming the variable differently on a replacement host is ordinary,
	// and refusing that would be refusing a correct restore over a label.
	DSNEnv string `json:"dsn_env,omitempty"`

	Migrations []state.AppliedMigration `json:"migrations"`
}

type Manifest struct {
	Schema int    `json:"schema"`
	Kind   string `json:"kind"`

	CreatedAt     string `json:"created_at"`
	BilletVersion string `json:"billet_version"`

	// DeploymentID is the identity every other piece belongs to. It is repeated
	// here rather than only stored in identity/deployment-id so that a mismatch
	// between the manifest and the file is itself detectable.
	DeploymentID string `json:"deployment_id"`

	Source Source `json:"source"`
	// GitHub is the DEFAULT target's App identity, the one the `github:` block
	// declares, whose key travels as EntryAppKey.
	GitHub GitHubIdentity `json:"github"`
	// Targets are the FURTHER targets the deployment serves, each with its own
	// App and its key under EntryAppKeyFor. Schema 3; empty on every archive of
	// a single-target deployment, which is what keeps such an archive readable
	// by the billet that wrote it.
	Targets   []TargetIdentity `json:"targets,omitempty"`
	Authority AuthorityFacts   `json:"authority"`
	Ledger    LedgerFacts      `json:"ledger"`

	Files []FileRecord `json:"files"`
}

type ObjectStore interface {
	Put(ctx context.Context, key string, body []byte) error
	Get(ctx context.Context, key string) ([]byte, error)
}

type Plan struct {
	Archive *Archive
	Target  Target
	// Intent is which operation this plan is for. The executor re-plans with it
	// rather than assuming a restore.
	Intent Intent

	Actions  []Action
	Refusals []lifeops.Refusal

	// Superseded is where a replaced ledger is renamed to. Set only under
	// ReplaceLedger, and reported so an operator knows where the record of the
	// jobs they accepted losing has gone.
	Superseded string

	// LedgerSidecars are the -wal and -shm files that must go with a replaced
	// ledger. Orphaning a -wal beside a restored billet.db would corrupt it.
	LedgerSidecars []string
}

type Progress struct {
	// Present says a journal is there. A journal billet could not read counts as
	// present and comes back with an error: "could not tell" is never "there is
	// nothing here".
	Present bool
	// ArchiveDir is where the interrupted run read its archive from, which is
	// what a diagnostic names.
	ArchiveDir string
	// ManifestSHA identifies that archive.
	ManifestSHA string
	// Intent is which operation wrote it, in Intent.String()'s words. Recorded
	// rather than inferred from the fence, which can be gone while the journal
	// is still here.
	Intent string
	// Phase is how far it got. See phasePublishing and its neighbours.
	Phase string
}

type RestoreRequest struct {
	Plan Plan

	// InstallAppKey publishes the App private key at a path that must not
	// already exist, creating it exactly once and never replacing anything.
	//
	// INJECTED RATHER THAN WRITTEN HERE. `billet github-app create` already owns
	// that publication — a sibling reservation, an os.Link that fails rather
	// than replaces, and a recovery path that never declares a credential lost
	// while its bytes are still in memory — and four review rounds went into it.
	// A restore installing the same kind of file must use the same code, not a
	// second implementation of the same idea.
	InstallAppKey func(path string, pem []byte) error

	// Now is the clock, so a test can pin the journal.
	Now func() time.Time
	// Actor is who ran this, recorded in the journal for whoever finds it.
	Actor string
}

type Result struct {
	Installed []Action
	Skipped   []Action
	Removed   []string
	// Resumed says a journal from an earlier interrupted run was picked up.
	Resumed bool
	// Strays are staging files a publication could not remove. NOT a failure —
	// the destination is installed and correct — but never swallowed either: a
	// second copy of a restored ledger that nothing mentions is one nobody
	// finds, which is the rule the App-key installer already follows.
	Strays []string
	// Superseded names what a recover moved aside. It is the only surviving
	// record of the work that operation failed, so it is reported rather than
	// left for somebody to notice.
	Superseded []string
	// Unfinished says the publication succeeded and the directory is STILL
	// fenced, with its journal in place, because the caller has something left to
	// do behind that fence. Only a recovery reaches it; call Finish afterwards.
	Unfinished bool
}

type Source struct {
	Host       string `json:"host"`
	ConfigPath string `json:"config_path"`
	StateDir   string `json:"state_dir"`
}

type Target struct {
	ConfigPath string
	StateDir   string
	// AppKeyPath and GitHub are the DEFAULT target's key path and identity,
	// from the `github:` block.
	AppKeyPath string
	GitHub     GitHubIdentity
	// Targets are the further targets the config declares, each with the path
	// its key goes to. Every one the archive carries must be here with the same
	// identity, and every one here must be in the archive.
	Targets []TargetPath

	// LedgerBackend is what THIS host's config says its ledger is — "sqlite",
	// "postgres", or empty for a config that names none (which is sqlite).
	//
	// COMPARED AGAINST THE ARCHIVE'S, because the halves have to be paired and
	// this is the half billet can actually check. An identity-only archive
	// restored onto a host whose config says the ledger is local produces a
	// control plane that mints a FRESH empty ledger beside a restored identity —
	// which is the same lost fleet as restoring an identity with no ledger at
	// all, arriving through a config mistake instead of a missing file.
	LedgerBackend string

	// ExternalLedgerAttached is the operator asserting that the ledger this
	// archive's identity belongs to is back and reachable.
	//
	// REQUIRED FOR AN IDENTITY-ONLY ARCHIVE, and it is a flag rather than a check
	// because there is nothing here to check: the database is on the other end of
	// a DSN this process has not been given, and its restore is pg_dump or the
	// provider's snapshot — the operator's to run. Billet verifies what it can
	// (the backend the config names) and asks about exactly the part it cannot.
	//
	// A ledger that is NOT back produces a control plane that starts against an
	// empty database holding a restored identity: it advertises capacity for a
	// fleet it has no record of, and reaps as orphans the compute the old one
	// launched.
	ExternalLedgerAttached bool
}

type TargetIdentity struct {
	Name string `json:"name"`
	GitHubIdentity
}

type TargetKey struct {
	Name      string
	GitHub    GitHubIdentity
	AppKeyPEM []byte
}

type TargetPath struct {
	Name       string
	AppKeyPath string
	GitHub     GitHubIdentity
}