dest

type Destination interface {
	// VerifyWorm probes the destination's immutability configuration. The pipeline
	// calls this before writing: if immutability isn't confirmed (WormStatus.Locked)
	// it warns and proceeds, unless worm.require is set, in which case it fails closed.
	VerifyWorm(ctx context.Context) (WormStatus, error)

	// PutImmutable creates an object at key with object-lock retention applied. It is
	// create-only: implementations MUST refuse to overwrite an existing key
	// (fail-closed) and MUST never delete. size is the exact content length; r is
	// streamed to storage.
	PutImmutable(ctx context.Context, key string, r io.Reader, size int64, ret Retention) (PutResult, error)

	// List returns objects under prefix. Read-only; used by restore/verify.
	List(ctx context.Context, prefix string) ([]Object, error)

	// Get opens an object for reading. Read-only; used by restore/verify. The caller
	// closes the returned reader.
	Get(ctx context.Context, key string) (io.ReadCloser, error)
}

type Object struct {
	Key  string
	Size int64
	// LastModified is when the store says the object was written, by the store's clock: S3's
	// LastModified, GCS's creation time, Azure's creation time. Zero when the store did not say.
	// The objects gitdr writes are never written twice, so for them it is the time of the one
	// write.
	LastModified time.Time
}

type PageLister interface {
	// ListPage lists at most limit objects under prefix from the first page of a listing and says
	// whether the store reported more after them. It does not walk the listing: S3 and Azure send
	// one request, and the Cloud Storage library asks again only past a page that came back empty
	// with a continuation, which is a client loop this code cannot stop.
	ListPage(ctx context.Context, prefix string, limit int) (objs []Object, more bool, err error)
}

type PutResult struct {
	Key         string    `json:"key"`
	ETag        string    `json:"etag,omitempty"`
	VersionID   string    `json:"versionId,omitempty"`
	Size        int64     `json:"size"`
	SHA256      string    `json:"sha256,omitempty"`
	RetainUntil time.Time `json:"retainUntil"`
	// RetainMode is the lock mode RetainUntil holds under, on a store that has modes (S3 Object
	// Lock). Empty when there is no RetainUntil.
	RetainMode RetentionMode `json:"retainMode,omitempty"`
}

type Retention struct {
	Mode  RetentionMode // COMPLIANCE (default) or GOVERNANCE
	Until time.Time     // retain-until timestamp (UTC)
}

type RetentionMode string

type RetentionObservation string

type RetentionObserver interface {
	// ObserveRetention asks the store what retention is on key. It is read-only, and it must
	// distinguish "the store said none" from "the store would not say": an error the caller
	// cannot classify is RetentionNotChecked, never RetentionAbsent.
	ObserveRetention(ctx context.Context, key string) (RetentionObservation, time.Time, error)
}

type WormStatus struct {
	// Period is how long the store's own policy holds every object, when the store said: a GCS
	// bucket's retention period, or an Azure container's immutability period as Resource Manager
	// reports it. Zero when it did not say, and always on S3, where gitdr locks each object itself
	// for the configured days. A skip never relies on a copy past a third of the shorter of the two.
	//
	// It comes first, with Verdict's comment below it, so gofmt aligns it with no other field and
	// a change to the fields below cannot realign it.
	Period time.Duration
	// Verdict replaces the Enabled/Locked pair. Two booleans that had to agree could express
	// a state neither of them meant, and nothing outside a test ever read Enabled.
	Verdict WormVerdict
	Mode    string // observed default mode, if any (e.g. "COMPLIANCE")
	// Details is a sentence for logs, the manifest and `gitdr doctor`. gitdr writes it: a token
	// the store sent, such as an error code, goes in only through ShapedCode.
	Details string
	// Refusal is the error the store answered with when it declined the question, the one behind
	// an unknown verdict, and nil otherwise. It carries the store's own words, so it goes to a log
	// and never into a manifest or onto stdout. `gitdr doctor` reads its error code from it.
	Refusal error
}

type WormVerdict string