Documentation
¶
Overview ¶
Package gitpoll implements ref-advertisement polling (DESIGN §3.1, D5): the stateless, checkout-free protocol read that is both the controller's change detection and the sole source of pin values. Credentials are parsed with the very function source-controller uses, making §3.1's "credentials identical by construction" literal rather than conventional (DESIGN §7.1).
Index ¶
- Constants
- func AuthFromSecret(repoURL string, data map[string][]byte) (transport.AuthMethod, error)
- type Lister
- type Observation
- type Poller
- func (p *Poller) Configure(interval time.Duration, perHostConcurrency int)
- func (p *Poller) Observation(src types.NamespacedName) (Observation, bool)
- func (p *Poller) Observations() map[types.NamespacedName]Observation
- func (p *Poller) SetTargets(targets []Target)
- func (p *Poller) Start(ctx context.Context) error
- type Target
Constants ¶
const ( // DefaultInterval matches the Wavefront CRD default for spec.poll.interval. DefaultInterval = 90 * time.Second // DefaultPerHostConcurrency matches the CRD default for // spec.poll.perHostConcurrency. DefaultPerHostConcurrency = 4 )
Variables ¶
This section is empty.
Functions ¶
func AuthFromSecret ¶
AuthFromSecret builds a go-git transport auth method from a GitRepository's secret, using the same parser as source-controller (DESIGN §7.1). data may be nil (anonymous HTTP).
Types ¶
type Lister ¶
type Lister interface {
List(ctx context.Context, repoURL string, auth transport.AuthMethod) (map[string]string, error)
}
Lister lists advertised refs for one repository URL. Returned map: full ref name → 40-hex SHA, including peeled "<ref>^{}" entries.
func NewGoGitLister ¶
NewGoGitLister returns the production Lister (go-git Remote.List, no clone).
type Observation ¶
type Observation struct {
SHA string // "" while unobserved or on persistent failure
ObservedAt time.Time // when the last sweep touched this target
FirstObserved time.Time // when this SHA value was first seen (reset on change)
Err error // last listing error, nil on success
// URL and TrackingRef record the plumbing the SHA was observed against,
// so a consumer can reject an observation that predates a repo edit
// (DESIGN §3.1: no stale candidate survives a plumbing change).
URL string
TrackingRef string
}
Observation is the latest advertisement result for a target's tracking ref.
type Poller ¶
type Poller struct {
// contains filtered or unexported fields
}
Poller periodically sweeps all targets, batched per git host with bounded per-host concurrency (DESIGN §3.1, §4.1 poll.*). Implements manager.Runnable.
func NewPoller ¶
func NewPoller(secrets client.Reader, lister Lister, notify func(), strategy selection.Strategy, failures *prometheus.CounterVec, credentialFailures prometheus.Counter) *Poller
NewPoller returns a Poller with the CRD's default cadence, ready for Configure and SetTargets.
strategy is required: the poller consults only its Candidate method, while WavefrontReconciler.Strategy consults only TrackingRef — the two halves of one selection policy. The caller must construct a single strategy instance and share it between both, or a non-TrackRef strategy injected at one site would be silently half-applied (finding 10).
failures is wavefront_ref_list_failures_total and credentialFailures is wavefront_credential_read_failures_total (DESIGN §6), both already created and registered by the caller — internal/metrics owns every collector's registration, so the poller only ever records against handles it is given. Both may be nil, in which case nothing is recorded.
func (*Poller) Configure ¶
Configure sets the sweep cadence. Non-positive values are clamped to the CRD defaults: a typed client can send explicit zeros past CRD defaulting, and a zero interval must never tight-loop.
func (*Poller) Observation ¶
func (p *Poller) Observation(src types.NamespacedName) (Observation, bool)
Observation returns the latest observation for a source, if any.
func (*Poller) Observations ¶
func (p *Poller) Observations() map[types.NamespacedName]Observation
Observations returns a coherent point-in-time snapshot of every current observation: an independent copy of the whole store, taken under a single read lock.
Coherence across sources is the contract, not an implementation detail. A sweep publishes all of its results at once (see publish), so a snapshot always reflects exactly one sweep — never a mixture of two. Callers that compare sources against one another depend on this: under the rolling admission rule a descendant is admitted when its ancestors are *settled*, and an ancestor whose observation lagged a sweep behind would look settled when it is not, mis-sequencing co-arriving changes (DESIGN §3.3). Reading source by source with Observation cannot provide that guarantee.
func (*Poller) SetTargets ¶
SetTargets replaces the poll set (the reconciler calls this). An observation is dropped when its source is no longer targeted *or* when the target's plumbing changed: a GitRepository flipped from refs/heads/main to refs/tags/v2 (or repointed at another URL) must not present main's HEAD as a current observation, because that SHA would be pinned under the observed-SHAs-only invariant (DESIGN §3.1).
func (*Poller) Start ¶
Start blocks until ctx is done, sweeping every configured interval. It implements manager.Runnable.
Each wait is computed as a deadline from the last sweep rather than from a fixed ticker, so a Configure that shortens the interval takes effect immediately instead of after the old — possibly far longer — interval elapses. Anchoring on the last sweep is also what keeps repeated reconfiguration from starving sweeps entirely: the deadline moves only with the interval, never with the number of times it is set.
type Target ¶
type Target struct {
Source types.NamespacedName // the GitRepository
URL string // spec.url
SecretRef *types.NamespacedName // secret holding credentials, if any
TrackingRef string
}
Target is one source to poll.
Source Files