advertise

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 7, 2026 License: MIT Imports: 9 Imported by: 0

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

func (a *Advertiser) Notify(ctx context.Context, d digest.Digest, present bool) bool

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).

func (*Advertiser) Run

func (a *Advertiser) Run(ctx context.Context) error

Run drives the reconcile loop until ctx is cancelled. Triggers one reconcile pass immediately so startup converges fast, then ticks at the configured interval with ±25% jitter to spread cluster-wide load.

type Inventory

type Inventory interface {
	Inventory(ctx context.Context) ([]digest.Digest, error)
}

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)
	// OnReconcileUnavailable fires when a reconcile pass aborts
	// 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 WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger plumbs a structured logger.

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

func WithProvideTimeout(d time.Duration) Option

WithProvideTimeout caps the per-Provide RPC budget. Zero or negative leaves the default (30 seconds).

func WithReconcileInterval

func WithReconcileInterval(d time.Duration) Option

WithReconcileInterval sets the cadence between full reconcile passes. Zero or negative leaves the default (5 minutes).

func WithWithdrawTimeout

func WithWithdrawTimeout(d time.Duration) Option

WithWithdrawTimeout caps the per-Withdraw RPC budget. Zero or negative leaves the default (10 seconds).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL