Documentation
¶
Overview ¶
Package advertise reconciles the local containerd content store against the set of digests this node is advertising on the DHT.
Contract :
- The local containerd content store is the source of truth for "what we can serve to peers". - The DHT is a hint layer: provider records say "this node might have this digest", subject to ≤24 h TTL and eventual consistency. - This package owns the local "announced set" - the digests we currently believe are present-and-advertised - and reconciles it against an inventory source (typically containerdstore.Inventory) plus an event stream (cdsub.ImageEvent).
Reconciliation passes call inventory.Inventory(ctx), diff against the announced set, and for each delta:
- present-but-not-announced -> DHT.Provide + add to announced set. - announced-but-absent -> DHT.Withdraw + remove from announced set.
Withdraw is a soft hint per libp2p has no protocol-level withdraw and the existing record will drain via TTL. The advertiser simply stops calling Provide for the digest so refresh ticks no longer keep it alive.
The announced set is local rebuildable state - it is NOT persisted across process restarts. On startup the first reconcile pass re-Provides every present digest, which is the same operation libp2p performs internally on its 12 h refresh schedule, so the extra cost is bounded by inventory size.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Advertiser ¶
type Advertiser struct {
// contains filtered or unexported fields
}
Advertiser keeps DHT provider records in sync with the local content store. Methods are safe for concurrent use.
func New ¶
func New(inv Inventory, dht ifaces.DHT, opts ...Option) *Advertiser
New constructs an Advertiser. inv supplies the current local content inventory; dht is the announce target.
func (*Advertiser) AnnouncedSize ¶
func (a *Advertiser) AnnouncedSize() int
AnnouncedSize returns the current size of the announced set. Used by readiness/observability probes; not by the reconcile path itself.
func (*Advertiser) IsAnnounced ¶
func (a *Advertiser) IsAnnounced(d digest.Digest) bool
IsAnnounced reports whether d is currently in the announced set. Helper for tests and observability probes.
func (*Advertiser) Notify ¶
Notify is a fast-path hook for the cdsub event loop: a single digest event ("we just observed an image/content change for d") translates to either Provide (present=true) or Withdraw (present=false). Used to react to image-lifecycle events between reconcile ticks without waiting for the next full inventory pass.
func (*Advertiser) Reconcile ¶
func (a *Advertiser) Reconcile(ctx context.Context) error
Reconcile performs a single pass: snapshot the current inventory, Provide digests that newly appeared, Withdraw digests that disappeared. Returns the Inventory error if the snapshot itself fails (Provide/Withdraw failures are logged but do not abort the pass - partial progress is better than no progress).
type Inventory ¶
Inventory is the interface the advertiser uses to discover what digests are currently present in the local content store. The canonical implementation is containerdstore.Store.Inventory.
type MetricsHooks ¶
type MetricsHooks struct {
// OnReconcileStart fires when a reconcile pass begins.
OnReconcileStart func()
// OnReconcileEnd fires after each reconcile pass with the elapsed
// duration, the total inventory size, and the count of digests
// added/removed from the announced set.
OnReconcileEnd func(dur time.Duration, inventorySize, added, removed int)
// OnReconcileError fires when a reconcile pass aborts on Inventory error.
OnReconcileError func(err error)
// because the inventory backend (containerd) is unavailable.
// Distinct from OnReconcileError so dashboards can separate
// "real error" from "backend hiccup that we deliberately
// tolerated by preserving the announced set". Per plan
// "containerd unavailable pauses advertise/reconcile
// rather than treating everything as absent".
OnReconcileUnavailable func()
// OnProvide fires after each successful DHT.Provide call.
OnProvide func()
// OnProvideError fires after each failed DHT.Provide call.
OnProvideError func()
// OnWithdraw fires after each successful DHT.Withdraw call.
OnWithdraw func()
// OnWithdrawError fires after each failed DHT.Withdraw call.
OnWithdrawError func()
}
MetricsHooks are optional Prometheus shims. Any callback may be nil.
type Openable ¶
type Openable interface {
Open(ctx context.Context, d digest.Digest) (io.ReadCloser, int64, error)
}
Openable is implemented by stores that can prove a digest is locally serveable. The containerdstore.Store implements this through Open.
type Option ¶
type Option func(*Advertiser)
Option configures an Advertiser.
func WithMetrics ¶
func WithMetrics(h MetricsHooks) Option
WithMetrics registers metric callbacks. The Hooks struct is copied by value so subsequent mutations by the caller do not affect the running advertiser.
func WithProvideTimeout ¶
WithProvideTimeout caps the per-Provide RPC budget. Zero or negative leaves the default (30 seconds).
func WithReconcileInterval ¶
WithReconcileInterval sets the cadence between full reconcile passes. Zero or negative leaves the default (5 minutes).
func WithWithdrawTimeout ¶
WithWithdrawTimeout caps the per-Withdraw RPC budget. Zero or negative leaves the default (10 seconds).