dbbackup

type BackupOptions struct {
	// Key is the CLOOP_SECRET_KEY the sidecar is sealed under; "" writes an
	// unsealed sidecar, which a restore then refuses without --allow-unsealed.
	Key string
}

type BackupReport struct {
	Source        string
	Output        string
	MetadataPath  string
	SizeBytes     int64
	Duration      time.Duration
	SHA256        string
	WALCheckpoint string // "PASSED" or human-readable diagnostic
	SchemaVersion int

	// Keys and Chain are what the manifest records.
	Keys  []ManifestKey
	Chain *ManifestChain
	// KeyFingerprint names the key the sidecar is sealed under; "" when it
	// is unsealed, because there was no CLOOP_SECRET_KEY.
	KeyFingerprint string
}

type KeyVerdict struct {
	ManifestKey
	// Opens: the key derives it (passes its check value; for the legacy
	// key, opens a sample of what it sealed).
	Opens bool `json:"opens"`
	// Lost: rows sealed under it would be unreadable after the restore, and
	// it is the key's fault — a restore would make them unreadable.
	Lost bool `json:"lost,omitempty"`
	// Why says why it does not open, when it does not.
	Why string `json:"why,omitempty"`
	// KMS names the KMS the key is held by (Task 20433); "" for a key
	// derived from a passphrase. Read from the backup's own registry.
	KMS string `json:"kms,omitempty"`
}

type ManifestChain struct {
	LastID          int64  `json:"last_id"`
	LastRowHash     string `json:"last_row_hash,omitempty"`
	LastTime        string `json:"last_time,omitempty"`
	FirstID         int64  `json:"first_id,omitempty"`
	Rows            int64  `json:"rows"`
	AnchorID        int64  `json:"anchor_id,omitempty"`
	AnchorThroughID int64  `json:"anchor_through_id,omitempty"`
	AnchorHash      string `json:"anchor_hash,omitempty"`
}

type ManifestKey struct {
	ID    string `json:"id"`
	State string `json:"state"`
	// Rows counts the rows sealed under it, by sealed set.
	Rows map[string]int `json:"rows,omitempty"`
}

type Metadata struct {
	Source        string    `json:"source"`
	Backup        string    `json:"backup"`
	CreatedAt     time.Time `json:"created_at"`
	SizeBytes     int64     `json:"size_bytes"`
	SHA256        string    `json:"sha256"`
	DurationMS    int64     `json:"duration_ms"`
	SchemaVersion int       `json:"schema_version"`
	CloopVersion  string    `json:"cloop_version,omitempty"`

	// Manifest is the manifest format, ManifestVersion.
	Manifest int `json:"manifest,omitempty"`
	// Keys are the sealing keys the backup's sealed rows depend on.
	Keys []ManifestKey `json:"keys,omitempty"`
	// Chain is where the backup's audit chain ends.
	Chain *ManifestChain `json:"chain,omitempty"`
	// KeyFingerprint names the CLOOP_SECRET_KEY the sidecar is sealed under,
	// and Seal is the seal; both empty on an unsealed sidecar.
	KeyFingerprint string `json:"key_fingerprint,omitempty"`
	Seal           string `json:"seal,omitempty"`
}

type Preflight struct {
	Backup    string
	SizeBytes int64
	// SHA256 is the backup file's digest, computed here.
	SHA256 string
	// Meta is the sidecar; nil when there is none.
	Meta    *Metadata
	Sidecar SidecarState
	// Seal is what the sidecar's seal says, when it was checked.
	Seal SealState
	// SchemaVersion is the highest migration the backup records.
	SchemaVersion int
	// Chain is where the backup's audit chain ends.
	Chain statedb.AuditHead
	// Keys are the sealing keys the backup depends on, by id.
	Keys []KeyVerdict
	// KeyFingerprint names the key checked against; "" when there was none.
	// PreviousKeyFingerprint names the previous root also checked against,
	// during a change of root.
	KeyFingerprint         string
	PreviousKeyFingerprint string

	// Refusals say why the restore is refused; none when it may go ahead.
	Refusals []Refusal
	// Notes are what a restore gives up, or cannot check, without being
	// refused for it.
	Notes []string
}

type PreflightOptions struct {
	// Key is the CLOOP_SECRET_KEY the restored hub will run with.
	Key string
	// Previous is the CLOOP_SECRET_KEY_PREVIOUS it will run with while a
	// change of root is in progress (Task 20425): a backup taken before the
	// change holds keys only the previous root derives, and a sidecar sealed
	// under it. Both are as good as the current root's, because the restored
	// hub opens them.
	Previous string
	// KMS are the key-management services the restored hub will run with
	// (Task 20433): secrets.kms and, during a change of root,
	// secrets.kms_previous. A backup's KMS-held keys open through one of
	// them and nothing else — no key file, no escrow — so restoring a backup
	// of a hub on a KMS needs access to that KMS key.
	KMS []secretbroker.KMS
	// SkipChecksum, AllowUnsealed and AcceptSecretLoss are RestoreOptions'.
	SkipChecksum     bool
	AllowUnsealed    bool
	AcceptSecretLoss bool
}

type Recording struct {
	// RestoredHead is where the restored chain ended before the restore
	// appended to it: the newest row the backup holds.
	RestoredHead statedb.AuditHead
	// Superseded is the newest checkpoint the restore superseded; nil when
	// none saw history past the restored head, or none could be read.
	Superseded *auditcheckpoint.Located
	// Row is the audit.restored row; zero when it could not be appended.
	Row statedb.AuditEvent
	// Record is the restore record; Sealed whether it carries a seal, and
	// Sinks where it was written ("file", "stderr").
	Record auditcheckpoint.Record
	Sealed bool
	Sinks  []string
	// RetiredKeys are the sealing keys retired under --accept-secret-loss.
	RetiredKeys []string
	// Notes say what could not be done, and why.
	Notes []string
}

type Refusal struct {
	// Err is the sentinel; Message says it to an operator.
	Err     error
	Message string
	// Override is the flag that proceeds anyway; "" when none does.
	Override string
}

type RefusedError struct {
	Backup   string
	Refusals []Refusal
}

type RestoreOptions struct {
	// Force allows overwriting an existing destination database. Without
	// this flag, Restore refuses to overwrite if the destination file or
	// any of its WAL/SHM sidecars exist (heuristic for "active database").
	Force bool

	// Key is the CLOOP_SECRET_KEY the restored hub will run with. The
	// backup's sealing keys must derive from it, and its sidecar must carry
	// its seal; the restore record is sealed under it. Restore never reads
	// the environment itself: the caller says which key it means.
	Key string
	// Previous is the CLOOP_SECRET_KEY_PREVIOUS the restored hub will run
	// with during a change of root (Task 20425): the backup's keys and its
	// sidecar may derive from it instead, and checkpoints sealed under it are
	// read as the hub's own. Nothing is sealed under it.
	Previous string
	// KMS are the key-management services the restored hub will run with
	// (Task 20433); the backup's KMS-held keys must open through one of them.
	KMS []secretbroker.KMS

	// SkipChecksum restores without checking the sidecar at all — no digest,
	// no seal. For a backup whose sidecar was lost; nothing then vouches that
	// the backup was not edited, and the restore records that it was skipped.
	SkipChecksum bool

	// AllowUnsealed accepts a sidecar whose seal cannot be checked here:
	// written unsealed (before Task 20410, or by a hub with no
	// CLOOP_SECRET_KEY), sealed under another key, or with no Key to check
	// it. The digest is still checked.
	AllowUnsealed bool

	// AcceptSecretLoss restores a backup whose sealing keys Key cannot
	// derive, and retires those keys in the restored database so the hub can
	// start and mint a fresh one; what they sealed is reported lost. The
	// backup file keeps them. Recorded on the audit.restored row and the
	// restore record.
	AcceptSecretLoss bool

	// Reason says why; it is recorded and required. Actor is who.
	Reason string
	Actor  string

	// CheckpointFile is the audit checkpoint file (audit.checkpoints.file):
	// where the restore looks for the newest checkpoint it supersedes, and
	// where it appends its restore record. "" reads and writes no file.
	// CheckpointStderr receives the record's stderr copy; nil writes none.
	CheckpointFile   string
	CheckpointStderr io.Writer
	// Chain is the role the restore record names, auditcheckpoint.Chain*;
	// "" takes the role the newest checkpoint for this database names, or
	// project when there is none.
	Chain string

	// Now is the clock; nil means time.Now.
	Now func() time.Time
}

type RestoreReport struct {
	Backup       string
	Destination  string
	SizeBytes    int64
	Duration     time.Duration
	BackedUpPath string // pre-restore copy of the destination, if any

	// Preflight is what the backup was found to be before the swap.
	Preflight *Preflight
	// Recorded says how the restore was recorded; see Recording.
	Recorded Recording
}

type SealState string

type SidecarState string

type UnrecordedError struct {
	Problems []string
}