providergate

package
v0.9.0-dev.21 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

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

View Source
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

func (b *Binding) Admit(id subflux.ProviderID, op Op) (ok bool, reason string)

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

func (b *Binding) GoString() string

GoString is String, so %#v cannot print a setting either.

func (*Binding) Observe

func (b *Binding) Observe(ctx context.Context, id subflux.ProviderID, op Op, err error)

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.

func (*Binding) ResetAll

func (b *Binding) ResetAll(ctx context.Context)

ResetAll is Gate.ResetAll.

func (*Binding) Status

func (b *Binding) Status() map[subflux.ProviderID]Status

Status is Gate.Status.

func (*Binding) String

func (b *Binding) String() string

String reports the provider count only, never a setting.

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

type Config struct {
	Store   Store
	Hasher  *auth.Hasher
	Metrics Metrics
	Now     func() time.Time
}

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

func Open(ctx context.Context, cfg Config) (*Gate, error)

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

func (g *Gate) Activate(b *Binding)

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

func (g *Gate) Bind(settings map[subflux.ProviderID]map[string]any) *Binding

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

func (g *Gate) Reconcile(ctx context.Context)

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

func (g *Gate) SetOnChange(fn func(Event))

SetOnChange installs the hook every Event is delivered to. The hook runs after the gate's locks are released, so it may call Status.

func (*Gate) Status

func (g *Gate) Status() map[subflux.ProviderID]Status

Status reports every live provider the gate has something to say about.

type Kind

type Kind string

Kind classifies an Event.

const (
	Disabled        Kind = "disabled"
	Enabled         Kind = "enabled"
	Inactive        Kind = "inactive"
	SettingRejected Kind = "setting_rejected"
	SettingCleared  Kind = "setting_cleared"
	Paused          Kind = "paused"
)

Event kinds.

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 Op

type Op string

Op is the provider operation a decision is about.

const (
	OpSearch   Op = "search"
	OpDownload Op = "download"
)

The two operations the engine performs against a provider.

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.

Jump to

Keyboard shortcuts

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