backup

type Entry struct {
	Stamp     string
	Time      time.Time
	DBSize    int64 // -1 when the .db is missing
	FilesSize int64 // -1 when the .tar.gz is missing
	// AnalyticsSize is the size of <stamp>-analytics.db, -1 when absent.
	AnalyticsSize int64
	LocalState    string
	HasManifest   bool
	Remote        UploadReceipt
}

type ExternalRequirement struct {
	Kind      string `json:"kind"`
	Reference string `json:"reference"`
	State     string `json:"state"`
}

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

type Inspection struct {
	Stamp                string `json:"stamp"`
	CheckedAt            string `json:"checked_at"`
	LocalComplete        bool   `json:"local_complete"`
	IntegrityOK          bool   `json:"integrity_ok"`
	ForeignKeyViolations int    `json:"foreign_key_violations"`
	ArchiveFiles         int    `json:"archive_files"`
	RecoveryKeyArchived  bool   `json:"recovery_key_archived"`
	// Analytics reports that the backup has the optional analytics.db
	// member (restore puts it back as <destination>/analytics.db).
	Analytics            bool                  `json:"analytics_included"`
	Consistency          string                `json:"consistency"`
	Readiness            string                `json:"readiness"`
	Errors               []string              `json:"errors"`
	Warnings             []string              `json:"warnings"`
	CutoverChecklist     []string              `json:"cutover_checklist"`
	ExternalRequirements []ExternalRequirement `json:"external_requirements"`
	Remote               UploadReceipt         `json:"remote"`
}

type Manifest struct {
	FormatVersion      int        `json:"format_version"`
	Stamp              string     `json:"stamp"`
	CreatedAt          string     `json:"created_at"`
	Database           FileDigest `json:"database"`
	Archive            FileDigest `json:"archive"`
	Consistency        string     `json:"consistency"`
	RecoveryFiles      []string   `json:"recovery_files"`
	Limitations        []string   `json:"limitations"`
	EncryptedFileLimit int64      `json:"encrypted_file_limit"`
	// Analytics is the optional <stamp>-analytics.db member: absent when
	// the backup skipped analytics or there was no analytics.db.
	Analytics *FileDigest `json:"analytics,omitempty"`
	// HMAC is hex(HMAC-SHA256(site secret, domain || canonical digests)).
	// Empty on legacy manifests written before keyed integrity.
	HMAC string `json:"hmac,omitempty"`
}

type Options struct {
	// IncludeSecrets archives secret.key and gorun.toml in plain text
	// (`gorun backup --include-secrets`). Keep such archives offline and
	// encrypted; the admin never sets it.
	IncludeSecrets bool
	// SecretKey (32 bytes) HMACs the manifest so a writable backups
	// directory alone cannot forge digests. Prefer the site secret.
	SecretKey []byte
	// SkipAnalytics leaves <dataDir>/analytics.db out of the backup.
	// Callers set it from the setting named by SettingSkipAnalytics.
	SkipAnalytics bool
	// SkipAnalyticsReason, when set with SkipAnalytics, marks the skip as
	// involuntary (for example the setting could not be read): it is copied
	// to Result.AnalyticsSkipped so callers warn about it. A deliberate
	// exclusion leaves it empty.
	SkipAnalyticsReason string
}

type Result struct {
	Stamp, DB, Files string
	Manifest         string
	// Analytics is the <stamp>-analytics.db copy, or "" when the backup
	// has no analytics member (skipped, or no analytics.db to copy).
	Analytics string
	// AnalyticsSkipped is "<code>: <detail>" when analytics.db existed (or
	// may have) but was left out against the operator's choice: the copy
	// failed, the copy failed its integrity check, or the exclusion setting
	// could not be read. The core backup still succeeds without the member;
	// callers must surface this as a warning. Empty otherwise.
	AnalyticsSkipped string
	Count            int // archived files
}

type UploadFile struct {
	Name      string `json:"name"`
	State     string `json:"state"`
	ObjectKey string `json:"object_key,omitempty"`
	Code      string `json:"code,omitempty"`
	CheckedAt string `json:"checked_at"`
}

type UploadReceipt struct {
	State            string       `json:"state"`
	Files            []UploadFile `json:"files"`
	ReadBackVerified bool         `json:"read_back_verified"`
	Stamp            string       `json:"stamp,omitempty"`
	DestinationID    string       `json:"destination_id,omitempty"`
	ManifestHMAC     string       `json:"manifest_hmac,omitempty"`
	HMAC             string       `json:"hmac,omitempty"`
	DatabaseSHA256   string       `json:"database_sha256,omitempty"`
	ArchiveSHA256    string       `json:"archive_sha256,omitempty"`
	// AnalyticsSHA256 is set when the manifest has an analytics member; the
	// receipt then lists it as a third file.
	AnalyticsSHA256 string `json:"analytics_sha256,omitempty"`
}