Documentation
¶
Overview ¶
Package fleet owns the pacing primitives that keep many Starmap instances from hitting one source together.
The package holds four pure rules. A stable phase spreads periodic work across a full interval. A startup spread admits cold work across a shorter window. A decorrelated retry policy bounds transient failure. A hard not-before honors a `Retry-After` header or a rate-limit reset time.
Every rule is deterministic for a given identity and random source. The runtime and every source share these rules, so one instance keeps its phase across a restart and two instances rarely share one.
Index ¶
Constants ¶
const ( // DefaultStartupSpread is the admission window for cold automatic work. DefaultStartupSpread = 15 * time.Minute // MinRetryDelay is the first transient retry delay. MinRetryDelay = time.Second // MaxRetryDelay caps the decorrelated retry delay. MaxRetryDelay = 15 * time.Minute // MaxTransientRetries is the transient retry budget of one cycle. This // budget stops one automatic cycle from multiplying requests. MaxTransientRetries = 3 // MaxNotBeforeJitter is the largest delay added after a hard not-before // boundary. It stops a fleet from retrying at the same instant. MaxNotBeforeJitter = 5 * time.Minute )
Variables ¶
This section is empty.
Functions ¶
func NotBefore ¶
NotBefore returns the earliest time a client may retry after a server boundary. The boundary is a hard floor, and the result adds up to MaxNotBeforeJitter after it, so a fleet does not retry at one instant.
A boundary at or before now still adds the jitter, because a fleet that reads an expired boundary would otherwise retry together.
func StablePhase ¶
StablePhase returns the offset of one controller inside its interval. The offset is `hash(instance + controller + source) mod interval`, so a restart on the same host keeps its phase and two hosts rarely share one.
Types ¶
type Identity ¶
type Identity struct {
// Instance is the stable identity of this process.
Instance string
// Controller names the periodic worker, such as "source" or "acquisition".
Controller string
// Source is the safe identity of the configured source.
Source string
}
Identity names the inputs of one stable phase. The instance identity lives outside the catalog store. The source identity is a safe name, never a URL, a token, or the host of a custom source.
type Random ¶
type Random func() float64
Random returns a value in the half-open range from zero to one. Tests supply a deterministic implementation.
type RetryPolicy ¶
type RetryPolicy struct {
// MinDelay is the first delay and the lower bound of every later delay.
MinDelay time.Duration
// MaxDelay caps every delay.
MaxDelay time.Duration
// MaxAttempts is the transient retry budget of one cycle.
MaxAttempts int
}
RetryPolicy paces transient retries with decorrelated jitter.
func DefaultRetryPolicy ¶
func DefaultRetryPolicy() RetryPolicy
DefaultRetryPolicy returns the transient retry policy of one cycle.
func (RetryPolicy) Allows ¶
func (p RetryPolicy) Allows(retries int) bool
Allows reports whether one more transient retry stays inside the budget. The count is the number of transient retries this cycle already spent.
func (RetryPolicy) Next ¶
Next returns the delay that follows previous. A zero previous delay returns the minimum delay. Later delays draw from the decorrelated jitter range between the minimum delay and three times the previous delay.
func (RetryPolicy) Validate ¶
func (p RetryPolicy) Validate() error
Validate reports whether the policy is usable.
Source Files