Documentation
¶
Overview ¶
Package providergate decides whether a subtitle provider may be called for one operation right now. It owns what the transient health tracker does not: a credential disable reached through a persisted ladder (a rejected credential is retried once after 5 minutes and once after 30, and a third rejection disables the provider), a per-operation rate-limit pause held in memory, and rejected optional settings.
Every engine holds a Binding, the gate's view for the provider settings it was built from. A binding whose settings for a provider are not the live ones is refused and its observations are ignored, so an engine that outlives a settings save can neither reuse the old credentials nor charge their failures to the new ones. A disable survives restart and ends only when the settings change, a credential test passes for the recorded settings, or ResetAll runs. A mutation's records are written before its call returns and ahead of its metric calls, logs and events.
Index ¶
- Constants
- type Binding
- func (b *Binding) Admit(id subflux.ProviderID, op Op) (ok bool, reason string)
- func (b *Binding) GoString() string
- func (b *Binding) Observe(ctx context.Context, id subflux.ProviderID, op Op, err error)
- func (b *Binding) ObserveSetting(id subflux.ProviderID, sr SettingReporter)
- func (b *Binding) PrepareSetting(id subflux.ProviderID, sr SettingReporter)
- func (b *Binding) ResetAll(ctx context.Context)
- func (b *Binding) Status() map[subflux.ProviderID]Status
- func (b *Binding) String() string
- type ClearResult
- type Config
- type Event
- type Gate
- func (g *Gate) Activate(b *Binding)
- func (g *Gate) Bind(settings map[subflux.ProviderID]map[string]any) *Binding
- func (g *Gate) ClearIfMatches(ctx context.Context, id subflux.ProviderID, settings map[string]any) ClearResult
- func (g *Gate) Reconcile(ctx context.Context)
- func (g *Gate) SetOnChange(fn func(Event))
- func (g *Gate) Status() map[subflux.ProviderID]Status
- type Kind
- type Metrics
- type Op
- type SettingReporter
- type Status
- type Store
Constants ¶
const MaxAuthFailures = 3
MaxAuthFailures is the credential rejection that disables a provider; each earlier rejection n waits authCooldowns[n-1] before one probe call.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Binding ¶
type Binding struct {
// contains filtered or unexported fields
}
Binding is the gate's view for one set of provider settings. Engines hold one; the zero Binding is not usable, use Gate.Bind.
func (*Binding) Admit ¶
Admit reports whether id may be called for op now and, when not, why, in words that never carry a credential. Admitting a provider with a recorded failure claims its one probe slot until Observe reports the call.
func (*Binding) Observe ¶
Observe classifies the outcome of one provider call the engine made for op: a *subflux.AuthError advances the ladder, a *subflux.RateLimitError pauses op, success from an operation that failed before clears the record, and any other error only frees the probe slot. A stale binding's observation is ignored, and so is any observation once the provider is disabled.
func (*Binding) ObserveSetting ¶
func (b *Binding) ObserveSetting(id subflux.ProviderID, sr SettingReporter)
ObserveSetting records, after a call, what sr, id's instance under b, says its upstream answered about an optional setting while the provider itself kept working. A refusal under the live settings marks the setting rejected; an acceptance clears the rejection. Either change makes every other instance of id forget its answer before its next call, an answer sr held from before the last change is forgotten rather than applied, and a stale binding's is ignored.
func (*Binding) PrepareSetting ¶
func (b *Binding) PrepareSetting(id subflux.ProviderID, sr SettingReporter)
PrepareSetting runs before a call to sr, id's instance under b: when the gate's verdict on id's optional settings changed since sr last caught up, sr forgets its upstream's answer, so the call asks the upstream again.
type ClearResult ¶
type ClearResult int
ClearResult is ClearIfMatches' answer.
const ( // Cleared: the recorded state matched the tested settings and was cleared. Cleared ClearResult // Mismatch: a record exists for settings other than the tested ones. Mismatch )
ClearIfMatches results.
type Config ¶
Config configures Open. Metrics is required; Hasher is required when Store is set. A nil Store keeps every record in memory only; a nil Now uses time.Now.
type Event ¶
type Event struct {
Provider subflux.ProviderID
Kind Kind
Reason string
Setting string
}
Event is one state transition, delivered to the SetOnChange hook. Reason is the provider's sanitized error text and never carries a credential.
type Gate ¶
type Gate struct {
// contains filtered or unexported fields
}
Gate is the process-wide provider gate. Its methods are safe for concurrent use.
func Open ¶
Open builds the gate and, with a Store, loads its records. It fails only for an invalid Config; a store read failure is logged and the gate starts with no records.
func (*Gate) Activate ¶
Activate makes b the live binding. Call Reconcile afterwards: until it runs, a record whose provider's settings changed is refused rather than trusted.
func (*Gate) Bind ¶
Bind returns a binding for the given per-provider settings, which the caller has already normalized. A provider absent from settings is absent from the binding: it is admitted only while it is absent from the live binding too.
func (*Gate) ClearIfMatches ¶
func (g *Gate) ClearIfMatches(ctx context.Context, id subflux.ProviderID, settings map[string]any) ClearResult
ClearIfMatches clears the recorded state of id when the settings (already normalized by the caller) are the ones it was recorded against. It compares against the record itself, not the live binding, so it also works with no live binding. A rejected optional setting is cleared when the tested settings are the live ones.
func (*Gate) Reconcile ¶
Reconcile brings the gate in line with the live binding: a record whose settings no longer match is deleted, a surviving disable is re-announced (persistent alerts and gauges live in memory, so this is what restores them after a restart), a record of a provider absent from the binding goes inactive but is kept, and pauses and rejected settings recorded under other settings are dropped. Call it after every Activate.
func (*Gate) SetOnChange ¶
SetOnChange installs the hook every Event is delivered to. The hook runs after the gate's locks are released, so it may call Status.
type Metrics ¶
type Metrics interface {
SetProviderDisabled(id subflux.ProviderID, disabled bool)
DeleteProviderDisabled(id subflux.ProviderID)
IncProviderAuthFailure(id subflux.ProviderID)
IncProviderRateLimited(id subflux.ProviderID, op Op)
// SetProviderSettingRejected with rejected false deletes the series.
SetProviderSettingRejected(id subflux.ProviderID, setting string, rejected bool)
}
Metrics records the gate's state. *obs.Metrics satisfies it.
type SettingReporter ¶
type SettingReporter interface {
// SettingVerdict names the setting the upstream answered about and its
// refusal, nil for an acceptance; setting is "" until the upstream answers.
SettingVerdict() (setting string, refusal error)
// ForgetSettingVerdict drops the answer, so the next call asks the
// upstream again.
ForgetSettingVerdict()
}
SettingReporter is a provider instance that remembers what its upstream answered about one of its optional settings. The gate calls both methods under its lock, so neither may call back into the gate.
type Status ¶
type Status struct {
DisabledReason string
RejectedSettings []string
PausedFor time.Duration
AuthFailures int
Disabled bool
}
Status is the gate's view of one live provider.
type Store ¶
type Store interface {
ProviderAuthRecords(ctx context.Context) ([]subflux.ProviderAuthRecord, error)
PutProviderAuthRecord(ctx context.Context, rec *subflux.ProviderAuthRecord) error
DeleteProviderAuthRecord(ctx context.Context, id subflux.ProviderID) error
}
Store persists credential-failure records. *boltstore.DB satisfies it.