ifaces

type ContentWriter interface {
	io.Writer

	// Commit finalizes the entry. Fails if the streamed bytes did not hash
	// to the declared digest.
	Commit(ctx context.Context) error

	// Abort discards staged bytes. Idempotent.
	Abort(ctx context.Context) error
}

type Coordinator interface {
	PullIntentQuery(ctx context.Context, peer NodeID, d digest.Digest) (PullIntent, error)
	PleasePull(ctx context.Context, peer NodeID, registry, repository string, kind OriginRefKind, digests []digest.Digest) ([]PleasePullOutcome, error)
}

type DHT interface {
	// FindProviders returns providers of d. Returning an empty slice and a
	// nil error is the "DHT-empty" case (the design doc): the caller MUST NOT treat
	// it as ground truth and SHOULD fall through to the HRW top-K probe.
	FindProviders(ctx context.Context, d digest.Digest) ([]Provider, error)

	// Provide advertises that this node holds d. Idempotent at the DHT
	// level; refreshing is the implementation's responsibility (libp2p
	// default 12 h refresh, 24 h TTL - the design doc).
	Provide(ctx context.Context, d digest.Digest) error

	// Withdraw is a soft "stop advertising" hint sent by the advertiser
	// when the digest is no longer present in the local content store
	// (e.g. containerd GC'd it). libp2p has no protocol-level withdraw
	// - existing provider records expire at the 24 h TTL - so this is
	// implementation-defined cooperation: at minimum the local agent
	// MUST stop re-Providing the digest on the next refresh cycle so
	// the stale record drains naturally. Returning a non-nil error
	// signals the advertiser to retry; nil means "acknowledged, do not
	// re-announce".
	Withdraw(ctx context.Context, d digest.Digest) error

	// Health returns the current DHT health score in [0,1] as defined by
	// the design doc (geometric mean of routing-table coverage, lookup-latency
	// score, and self-test success rate).
	Health() float64
}

type ErrNotFound struct {
	Digest digest.Digest
}

type ErrPeerHTTPStatus struct {
	PeerAddr   string
	StatusCode int
}

type ErrUnavailable struct {
	Op    string
	Cause error
}

type FailureClass string

type LocalContentStore interface {
	// Has reports whether the digest is present in the local store.
	Has(ctx context.Context, d digest.Digest) (bool, error)

	// Open returns a reader for the stored bytes plus the content
	// length. Returns ErrNotFound if absent.
	Open(ctx context.Context, d digest.Digest) (io.ReadCloser, int64, error)

	// Writer returns a digest-verifying writer for d. Bytes written
	// are staged; the entry becomes visible to subsequent Has/Open
	// calls only after Commit. Abort discards the staging area.
	Writer(ctx context.Context, d digest.Digest) (ContentWriter, error)
}

type LocalIntentProvider interface {
	LocalPullIntent(ctx context.Context, d digest.Digest) PullIntent
}

type LocalPullStarter interface {
	StartLocalPull(ctx context.Context, registry, repository string, kind OriginRefKind, digests []digest.Digest) ([]PleasePullOutcome, error)
}

type Members interface {
	// Self returns this agent's own NodeID.
	Self() NodeID

	// Snapshot returns the current node list. The returned slice is owned
	// by the caller; implementations MUST copy if they retain it.
	Snapshot() []Node

	// WaitForSync blocks until the underlying informer has completed its
	// initial list-and-watch sync. Used by readiness probes.
	WaitForSync(ctx context.Context) error
}

type Node struct {
	ID NodeID

	// Addr is the network address to reach this node's transfer
	// endpoint (HTTP/2 on the configured transfer port). When the
	// transfer port is known (production deploy), Addr is "ip:port";
	// for back-compat with older snapshots it may be a bare IP and
	// callers must append the port.
	Addr string

	// Zone is the optional topology label `topology.kubernetes.io/zone`.
	// Empty when not topology-aware (the design doc).
	Zone string

	// PeerID is the libp2p peer.ID (CID-encoded string form) the node
	// publishes via its pod annotation. Empty until the peer announces.
	// coord.Client uses this to dial via libp2p without requiring that
	// NodeID itself be a peer.ID string.
	PeerID string

	// P2PAddrs lists the node's libp2p listen multiaddrs published via
	// pod annotation. Empty until the peer announces. main.go reads
	// this on startup to seed disco.Connect for DHT bootstrap (the design doc)
	// without needing operator-supplied bootstrap_peers.
	P2PAddrs []string
}

type NodeID string

type OriginError struct {
	Ref   OriginRef
	Class FailureClass
	Err   error
}

type OriginPuller interface {
	// Pull opens a streaming read of the digest's bytes from origin. The
	// returned ReadCloser is digest-unverified; the caller is expected to
	// verify via a Cache writer or equivalent.
	//
	// On terminal failure the returned error is wrapped in an *OriginError
	// carrying the failure classification used by the design doc.
	Pull(ctx context.Context, ref OriginRef) (io.ReadCloser, int64, error)

	// Head fetches metadata for a digest without transferring the body.
	// Used by the mirror's HEAD handler to satisfy distribution-spec
	// metadata requests on a cache miss without doing a full origin pull.
	//
	// Head is deliberately NOT counted in p2p_origin_pull_total or its
	// success/failure siblings. Those counters describe byte-pull
	// attempts: metadata-only HEAD is a different operation class, and
	// folding HEAD calls into pull totals broke the per-pull arithmetic
	// (started == success + failure + in_flight) because HEAD never
	// produces bytes, never commits to cache, and therefore can fire
	// neither success nor downstream-failure. See origin.Client.Head's
	// implementation comment for why HEAD failures also stay out of
	// p2p_origin_pull_failure_total.
	//
	// The returned contentType is the upstream registry's Content-Type
	// header verbatim (may be "" if the upstream omitted it). The mirror
	// needs this so that HEAD responses to containerd carry the same
	// media type the eventual GET will. Without it containerd builds a
	// descriptor with the wrong type at HEAD time and later fails the
	// unpack with "expected manifest but found index" when the body is
	// a manifest list (see mirror.writeBlobHeadersWithPrefix).
	//
	// On terminal failure the returned error is wrapped in an
	// *OriginError carrying the failure classification used by the design doc so
	// the mirror can convert it to the right HTTP status.
	Head(ctx context.Context, ref OriginRef) (size int64, contentType string, err error)
}

type OriginRef struct {
	Registry   string // e.g. "registry.example.com"
	Repository string // e.g. "library/nginx"
	Digest     digest.Digest

	// Kind discriminates the OCI Distribution Spec URL family for this
	// reference. Manifests live at /v2/<repo>/manifests/<digest>, blobs at
	// /v2/<repo>/blobs/<digest>. Zero value (KindBlob) is the common case;
	// only the mirror's manifest-by-digest path and cold-start manifest
	// pulls set KindManifest.
	Kind OriginRefKind
}

type OriginRefKind int

type PeerDialer interface {
	// FetchFromPeer streams the digest's bytes from peerAddr's :5001
	// endpoint. The implementation MUST set `Gantry-Mirrored: 1` and MUST
	// surface a NotFound error distinctly from transport errors so the
	// caller can fail over to the next provider.
	FetchFromPeer(ctx context.Context, peerAddr string, ref OriginRef) (io.ReadCloser, int64, error)
}

type PleasePullOutcome struct {
	Digest        digest.Digest
	Outcome       PleasePullStatus
	StartedAt     time.Time
	CooldownUntil time.Time
	FailureClass  FailureClass
}

type PleasePullStatus int

type Provider struct {
	NodeID NodeID
	Addr   string
}

type PullIntent struct {
	HasCached      bool
	InFlight       bool
	StartedAt      time.Time
	RecipientRank  int32
	RecentlyFailed bool
	CooldownUntil  time.Time
	FailureClass   FailureClass
}