coldstart

type ChildDigest struct {
	Digest digest.Digest
	Kind   ifaces.OriginRefKind
}

type Discovery interface {
	FindProviders(ctx context.Context, d digest.Digest) ([]ifaces.Provider, error)
	Health() float64
}

type MetricsHooks struct {
	// OnRankMismatch fires once per pull_intent response whose
	// reported hrw_rank disagrees with the requester's computed
	// rank for that responder. kindLabel is "manifest", "config",
	// or "layer".
	OnRankMismatch func(kindLabel string, responder ifaces.NodeID)
	// OnDhtFalseEmpty fires when the orchestrator observes the
	// false-empty case: DHT had returned 0 providers, but a
	// pull_intent_query reports has_cached=true.
	OnDhtFalseEmpty func()
	// OnTopKProbeHit fires when any rule before rule 7 (cold-start)
	// resolves the request. Used to track how often the probe saves
	// an origin pull.
	OnTopKProbeHit func()
	// OnColdStartDuration is called once per Resolve with the total
	// elapsed time and the outcome rule that fired ("rule1".."rule7"
	// or "expanded_rule_N").
	OnColdStartDuration func(kindLabel, outcome string, d time.Duration)
	// OnDesignatedPullerTakeover fires when a pull_intent_query
	// responder reports in_flight=true but its started_at is older
	// than the per-the design doc stall threshold, so the requester excludes
	// it from rule-3 piggyback and routes via the next-ranked node
	// (rule 6 / rule 7). kindLabel is "manifest", "config", or
	// "layer". Maps to the design doc metric
	// `p2p_designated_puller_takeover_total`.
	OnDesignatedPullerTakeover func(kindLabel string)
	// OnTopKExpansion fires once per expansion pass to top-2K (or
	// top-(K × TopKExpansionFactor) when the factor is configured).
	// reason is "degraded" (rule-6 DHT-degraded expand) or
	// "all_unreachable" (rule-5 expansion). Maps to the design doc metric
	// `p2p_topk_expansion_total{reason=}`.
	OnTopKExpansion func(reason string)
	// OnPrefetchBatch fires once per PrefetchLayers call with the
	// number of distinct pullers contacted and the number of layer
	// digests grouped into those batches (after self / unreachable
	// filtering). Maps to the design doc / the design doc batched-please_pull metrics:
	// `p2p_prefetch_batches_total` (count) and
	// `p2p_prefetch_digests_batched_total` (sum).
	OnPrefetchBatch func(pullers, digests int)
}

type Options struct {
	Members   ifaces.Members
	Discovery Discovery
	Coord     ifaces.Coordinator
	Inflight  *inflight.Map
	Logger    *slog.Logger
	Metrics   MetricsHooks
	Now       func() time.Time
	HrwK      int       // default 3
	HrwScope  hrw.Scope // default ScopeCluster
	SelfZone  string    // required when HrwScope == ScopeZone

	// LocalIntent computes self's PullIntent synchronously, without
	// the libp2p coord round-trip. When non-nil, the cold-start
	// orchestrator includes self as a first-class participant in the
	// the design doc rule cascade - rule 2 (cache hit on self), rule 3 (self
	// in-flight), rule 4 (self in cooldown), and rule 7 (self picked
	// as designated puller) all behave the same as for any peer.
	//
	// Without LocalIntent, the resolver excludes self from
	// queryTargets and from `reachable`, which means a self-as-HRW-
	// rank-0 case routes please_pull to rank 1 - two nodes both
	// trying to delegate to each other can each origin-pull the same
	// digest, violating the cache-hit "one origin pull per digest"
	// invariant. New deployments MUST wire LocalIntent.
	LocalIntent ifaces.LocalIntentProvider
	// LocalPull starts an origin pull on self without the libp2p
	// please_pull RPC. Used when rule 7's lowest-rank-reachable puller
	// is self. nil + LocalIntent non-nil + rule 7 picks self ->
	// resolver falls back to Coord.PleasePull(self, ...), which will
	// either fail to dial or burn a stream slot to no benefit; tests
	// should set both together.
	LocalPull ifaces.LocalPullStarter

	// Tunables (defaults applied if zero).
	QueryTimeout         time.Duration // default 2s - step 5 wait window
	PollManifest         time.Duration // default 200ms -
	PollLayer            time.Duration // default 1s -
	TransientCooldownCap time.Duration // default 30s - rule 4
	HonorSweepInterval   time.Duration // default 1m, negative disables full sweeps

	// TopKExpansionFactor is the multiplier applied to HrwK on the
	// expansion pass under rule 5 / rule 6 (the step 5; the design doc
	// `topk_expansion_factor_degraded`). Defaults to 2 when ≤1.
	TopKExpansionFactor int

	// TrustedFailureClasses is the set of the design doc origin-error classes
	// the requester accepts as a cluster-wide 5xx-immediate signal
	// when a top-K responder reports recently_failed in rule 1.
	// Classes outside this set (notably `transient`) are honored
	// only locally by the reporting puller. Empty defaults to
	// {auth, not_found, rate_limited} per design the design doc / config
	// `origin_failure_classes_trusted_cluster_wide`.
	TrustedFailureClasses []ifaces.FailureClass
}

type Resolution struct {
	// Providers are transfer endpoints (host:port) the caller should
	// fetch from, in priority order. Non-empty on success.
	Providers []ifaces.Provider
	// Outcome names which rule fired. Useful for tests and metrics.
	Outcome string
}

type Resolver struct {
	// contains filtered or unexported fields
}