pipeline

type ArtifactInfo struct {
	Kind        string    `json:"kind"` // bundle | meta | sha256
	Key         string    `json:"key"`
	Size        int64     `json:"size"`
	SHA256      string    `json:"sha256"`
	RetainUntil time.Time `json:"retainUntil"`
}

type BackupDeps struct {
	Config        *config.Config
	Source        source.Source
	Dest          dest.Destination
	Git           *gitexec.Git
	SigningKey    ed25519.PrivateKey
	EncryptionKey []byte // optional client-side envelope key; nil = off
	ToolVersion   string
	Logger        *slog.Logger
	Now           func() time.Time
	RequireWORM   bool // --require-worm / worm.require: fail closed if not immutable
}

type BackupResult struct {
	Manifest    *Manifest
	ManifestKey string
}

type DestInfo struct {
	Type          string `json:"type"`
	Bucket        string `json:"bucket"`
	WormMode      string `json:"wormMode,omitempty"`    // configured retention mode
	WormImmutable bool   `json:"wormImmutable"`         // WORM check confirmed immutable
	WormDetails   string `json:"wormDetails,omitempty"` // observed immutability detail
}

type DrillDeps struct {
	Dest          dest.Destination
	Git           *gitexec.Git
	EncryptionKey []byte
	// PublicKey verifies the manifest being drilled. Without it the drill still runs and the
	// report says the manifest's signature was not checked — a drill against an unverified
	// manifest proves the artifacts restore, not that they are the ones gitdr wrote.
	PublicKey ed25519.PublicKey
	// SigningKey signs the report. A drill report is evidence, and unsigned evidence is a
	// text file anybody can write.
	SigningKey  ed25519.PrivateKey
	ToolVersion string
	Logger      *slog.Logger
	Now         func() time.Time
}

type DrillRepo struct {
	Slug   string `json:"slug"`
	Status string `json:"status"` // success | failed
	Error  string `json:"error,omitempty"`

	// SourceRefs is how many refs the signed manifest says the source advertised. Zero for a
	// copy made by a pre-v3 gitdr, where the drill can still prove the bundle restores and
	// cannot prove it matches the source.
	SourceRefs int `json:"sourceRefs"`
	// BundleRefs is how many the bundle's own header declares.
	BundleRefs int `json:"bundleRefs"`
	// RestoredRefs is how many of those the restored repository carries at the same object.
	RestoredRefs int `json:"restoredRefs"`
	// Unreferenced names refs the bundle declares that a clone's refspec does not create.
	// Counted apart from RestoredRefs rather than folded into it.
	Unreferenced []string `json:"unreferenced,omitempty"`
	// SourceMatch says whether the bundle declares exactly what the source advertised. Null
	// when the manifest recorded no source refs, which is not the same as false.
	SourceMatch *bool `json:"sourceMatch,omitempty"`
	// Mismatches name what did not line up, in ref order, so the first one named is stable.
	Mismatches []string `json:"mismatches,omitempty"`
}

type DrillReport struct {
	Schema      string   `json:"schema"`
	DrillID     string   `json:"drillId"`
	Tool        ToolInfo `json:"tool"`
	ManifestKey string   `json:"manifestKey"`
	// ManifestSigned records whether the manifest's own signature was checked before its
	// contents were believed. False is not a failure and is not hidden: it narrows what the
	// drill proves, from "the artifacts gitdr wrote restore" to "these artifacts restore".
	ManifestSigned bool      `json:"manifestSigned"`
	StartedAt      time.Time `json:"startedAt"`
	FinishedAt     time.Time `json:"finishedAt"`
	Status         string    `json:"status"`
	// Eligible is how many repositories the manifest records a successful copy for; Drilled
	// is how many this report actually restored. They differ when Sample is set, and a reader
	// must be able to see that without reading the repo list.
	Eligible int         `json:"eligible"`
	Drilled  int         `json:"drilled"`
	Repos    []DrillRepo `json:"repos"`
}

type DrillRequest struct {
	// ManifestKey is the run to drill. Empty means the most recent manifest for Host/Owner.
	ManifestKey string
	Host        string
	Owner       string
	// Sample caps how many repositories are restored. Zero means all of them.
	//
	// A partial drill is honest about being one: the report records how many were eligible and
	// how many were tried, so nobody can read a ten-repository sample as a thousand-repository
	// guarantee. Repositories are chosen in slug order, so a sample is reproducible rather
	// than a different ten every time.
	Sample int
	// WorkDir is where repositories are restored. Each is removed as soon as it is compared;
	// a drill of a large organisation would otherwise need the whole estate on disk at once.
	WorkDir string
}

type Manifest struct {
	Schema      string      `json:"schema"`
	RunID       string      `json:"runId"`
	Tool        ToolInfo    `json:"tool"`
	Source      SourceInfo  `json:"source"`
	Destination DestInfo    `json:"destination"`
	StartedAt   time.Time   `json:"startedAt"`
	FinishedAt  time.Time   `json:"finishedAt"`
	Status      string      `json:"status"` // success | failed
	Repos       []RepoEntry `json:"repos"`
}

type RefComparison struct {
	Declared int
	Matched  int
	// Unreferenced lists refs the bundle declares that `git clone` does not create.
	//
	// A clone uses the default refspec, +refs/heads/*:refs/remotes/origin/* plus tags, so a
	// bundle's refs/notes/*, refs/merge-requests/*, refs/pull/* and refs/keep-around/*
	// entries arrive as objects and get no ref. Verified: a mirror carrying notes, a merge
	// request ref and a keep-around ref bundles all five refs, and the clone from that
	// bundle has three, while `count-objects -v` shows the same six objects on both sides.
	// The data is there; nothing points at it, so a future gc can drop it.
	//
	// Not a failure, because the cause is `git clone`'s refspec and not the backup: it is
	// the same for a perfect bundle and a damaged one, so failing on it would fail every
	// restore of every GitLab project, and a check that fires on the happy path gets turned
	// off. Not silent either, because these refs genuinely are not in the restored
	// repository: they are held out of Matched and named in the summary.
	Unreferenced []string
	// Mismatches are the failures, in ref-name order, so the first one named is stable.
	Mismatches []RefMismatch
}

type RefEntry struct {
	Name   string `json:"name"`
	Commit string `json:"commit"`
}

type RefMismatch struct {
	Ref  string // the ref as the bundle declares it
	Want string // the object the bundle declares
	Got  string // what the restore has; empty when the ref is absent altogether
}

type RepoEntry struct {
	Slug   string `json:"slug"`
	Status string `json:"status"` // success | failed | skipped
	Error  string `json:"error,omitempty"`
	// Why a repository was skipped, in plain words. Additive to the manifest schema rather
	// than a new status value, because a consumer switching on `status` would break on an
	// unknown one and there is more than one reason to skip.
	Reason    string         `json:"reason,omitempty"`
	Artifacts []ArtifactInfo `json:"artifacts,omitempty"`
	// What the source advertised when this copy was made, from `git ls-remote`.
	//
	// It is recorded so the next run can ask the same question and compare, and skip a
	// repository whose refs have not moved instead of writing a byte-identical copy of its
	// entire history. Before this, every run rewrote everything, and on WORM storage the
	// customer could not delete any of it.
	//
	// A slice and not a map: Canonical() relies on struct field order for stable bytes, and
	// Go map iteration order is random, so a map here would produce a different signature
	// for the same run. Sorted by name for the same reason.
	//
	// Recorded only on a successful copy. A run that failed halfway has refs that describe a
	// repository nothing was written for, and trusting them would skip the retry.
	Refs []RefEntry `json:"refs,omitempty"`
	// When the artifacts this entry relies on were actually written.
	//
	// For a copy that was made this run it is this run's finish time. For a repository that
	// was skipped as unchanged it is carried forward from the run that made the copy, which
	// is the whole point: without it, each skip would reset the age of the copy and the
	// refresh bound in unchanged.go would never fire, so a repository that never changes
	// would be skipped past its object lock's expiry and end up with nothing.
	//
	// Found by running the backup three times in a row and watching the third copy in full.
	//
	// A pointer, because `omitempty` does nothing on a `time.Time`: a struct is never empty to
	// encoding/json, so a value field emitted `"copiedAt":"0001-01-01T00:00:00Z"` into every
	// manifest including ones re-read from v2 — which changed their canonical bytes and made
	// every already-signed manifest fail verification. Caught by the v2 round-trip test.
	CopiedAt *time.Time `json:"copiedAt,omitempty"`
}

type RestoreDeps struct {
	Dest          dest.Destination
	Git           *gitexec.Git
	EncryptionKey []byte // optional; must match the backup's key
	// PublicKey is optional. When set, restore locates the signed run-manifest for the
	// requested date, verifies its signature, and checks every artifact it downloads
	// against the checksums the manifest records. The unsigned .sha256 sidecar catches
	// corruption but not tampering; the manifest catches both. Without a key restore
	// keeps the sidecar-only check and says so in RestoreResult.Verification.
	PublicKey ed25519.PublicKey
	Logger    *slog.Logger
}

type RestoreRequest struct {
	Host   string // e.g. github.com
	Owner  string
	Name   string
	Date   string // YYYY-MM-DD
	OutDir string
}

type RestoreResult struct {
	BundleKey string `json:"bundleKey"`
	SHA256    string `json:"sha256"`
	OutDir    string `json:"outDir"`
	Verified  bool   `json:"verified"`
	// Verification says in plain words which integrity checks this restore ran, so a
	// restore that was not checked against the signed manifest announces itself
	// instead of looking identical to one that was. Deliberately kept out of the JSON:
	// the --output json shape is a versioned public contract (SPEC §11), and widening
	// it is its own change, made on purpose, not as a side effect of a read-side fix.
	Verification string `json:"-"`
	// Refs is the proof that the restore reproduced the history the bundle declares:
	// how many refs the bundle's own header carries and how many of them the restored
	// repository has at the same object. Out of the JSON for the same reason as
	// Verification — the shape is a versioned contract, and putting this on it is a
	// separate, deliberate change.
	Refs RefComparison `json:"-"`
}

type SourceInfo struct {
	Type string `json:"type"`
	Host string `json:"host"`
}

type ToolInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type VerifyDeps struct {
	Dest      dest.Destination
	PublicKey ed25519.PublicKey
	Logger    *slog.Logger
}

type VerifyResult struct {
	ManifestKey      string   `json:"manifestKey"`
	SignatureValid   bool     `json:"signatureValid"`
	ArtifactsChecked int      `json:"artifactsChecked"`
	ArtifactsOK      int      `json:"artifactsOk"`
	Failures         []string `json:"failures,omitempty"`
}