polling

Documentation

Overview

Package polling provides the history-polling subsystem for Sonarr/Radarr import events and the write-through poll timestamp cache.

Index

• type Deps
• type ImportResult
• type LiveState
• type PollCache
  • func NewPollCache(readFn func(ctx context.Context, key api.PollKey) (time.Time, error), ...) *PollCache
  • func (c *PollCache) Get(ctx context.Context, key api.PollKey) time.Time
  • func (c *PollCache) Set(ctx context.Context, key api.PollKey, t time.Time)
• type PollCacher
• type PollRadarrClient
• type PollSonarrClient
• type PollSource
• type Poller
  • func NewPoller(deps Deps, stateFunc StateFunc) *Poller
  • func (p *Poller) PollOnce(ctx context.Context) int
  • func (p *Poller) Run(ctx context.Context)
• type PollerCfg
• type PollerEvents
• type PollerMetrics
• type PollerStore
• type StateFunc
• type StatsCacheInvalidator

Types

type Deps

type Deps struct {
	PollCache  *PollCache
	Store      PollerStore
	Metrics    PollerMetrics
	Alerts     activity.WarnRecorder
	Events     PollerEvents
	StatsCache StatsCacheInvalidator
}

Deps holds all dependencies for the Poller.

type ImportResult

type ImportResult struct {
	Req       *api.SearchRequest
	Source    PollSource
	Label     string
	Targets   []api.SubtitleTarget
	RefreshID int
}

ImportResult holds the resolved search parameters for a single arr import event.

type LiveState

type LiveState struct {
	Cfg    PollerCfg
	Engine api.SearchEngine
	Sonarr PollSonarrClient
	Radarr PollRadarrClient
}

LiveState holds the hot-reloadable runtime state the poller reads each cycle.

type PollCache

type PollCache struct {
	// contains filtered or unexported fields
}

PollCache is a write-through cache for poll timestamps. It absorbs transient DB write failures: if the DB write fails, subsequent reads still return the in-memory value instead of re-reading a stale DB entry. On first read after startup, the cache is seeded from the DB via readFn. Uses sync.Map for lock-free reads on the hot path (2 keys, read-heavy).

func NewPollCache

func NewPollCache(
	readFn func(ctx context.Context, key api.PollKey) (time.Time, error),
	setFn func(ctx context.Context, key api.PollKey, t time.Time) error,
) *PollCache

NewPollCache creates a PollCache backed by the given read/set functions.

func (*PollCache) Get

func (c *PollCache) Get(ctx context.Context, key api.PollKey) time.Time

Get returns the cached timestamp for key, falling back to the DB on miss. Uses LoadOrStore to handle the race between concurrent first-reads atomically.

func (*PollCache) Set

func (c *PollCache) Set(ctx context.Context, key api.PollKey, t time.Time)

Set updates both the in-memory cache and the persistent store. The cache advances unconditionally; the DB write is best-effort and WARN-logged on failure.

type PollCacher

type PollCacher interface {
	Get(ctx context.Context, key api.PollKey) time.Time
	Set(ctx context.Context, key api.PollKey, t time.Time)
}

PollCacher is the interface for poll timestamp caching. Consumers depend on this interface rather than the concrete *PollCache, enabling test doubles and alternative implementations.

type PollRadarrClient

type PollRadarrClient interface {
	GetHistorySince(ctx context.Context, since time.Time, eventTypes ...arrapi.EventType) ([]arrapi.HistoryRecord, error)
	GetMovieByID(ctx context.Context, id int) (arrapi.Movie, error)
	ResolveExcludeTagIDs(ctx context.Context, tagNames []string, logMissing bool) map[int]struct{}
	RescanMovie(ctx context.Context, movieID int) error
}

PollRadarrClient is the Radarr surface the history poller uses.

type PollSonarrClient

type PollSonarrClient interface {
	GetHistorySince(ctx context.Context, since time.Time, eventTypes ...arrapi.EventType) ([]arrapi.HistoryRecord, error)
	GetSeriesByID(ctx context.Context, id int) (arrapi.Series, error)
	GetEpisodeByID(ctx context.Context, id int) (arrapi.Episode, error)
	ResolveExcludeTagIDs(ctx context.Context, tagNames []string, logMissing bool) map[int]struct{}
	RescanSeries(ctx context.Context, seriesID int) error
}

PollSonarrClient is the Sonarr surface the history poller uses: import-event polling, per-item lookups, exclude-tag resolution, and a post-import rescan.

type PollSource

type PollSource string

PollSource identifies the arr system that produced an import event.

const (
	PollSourceSonarr PollSource = "sonarr"
	PollSourceRadarr PollSource = "radarr"
)

Poll source constants.

type Poller

type Poller struct {
	// contains filtered or unexported fields
}

Poller polls Sonarr/Radarr history APIs for new import events and processes each through the search engine.

func NewPoller

func NewPoller(deps Deps, stateFunc StateFunc) *Poller

NewPoller creates a Poller with the given dependencies. In unconfigured mode (server.New called without WithConfig) stateFunc may return a LiveState with a nil Cfg; we fall back to a sane default TTL so construction does not panic. Run() reads the live PollInterval per cycle and the per-entry expiry is governed by the cache TTL set here, so the first poll after configuration uses the configured interval naturally; the tag cache lifetime is the only thing tied to this initial value.

func (*Poller) PollOnce

func (p *Poller) PollOnce(ctx context.Context) int

PollOnce checks both Sonarr and Radarr for new import events. Returns the number of imported-history entries observed across both arr clients (used by Run to decide whether to enter adaptive-burst mode).

func (*Poller) Run

func (p *Poller) Run(ctx context.Context)

Run polls on a timer, re-reading the interval from live config after each poll so hot-reloaded interval changes take effect immediately. When PollOnce reports activity, the next interval is shortened to burstPollInterval and stays there until burstPollWindow passes idle.

type PollerCfg

type PollerCfg interface {
	PollInterval() time.Duration
	Search() api.SearchConfig
	ValidatePath(ctx context.Context, path string) error
	ResolveTargetsWithFallback(originalLang string, audioLangs []string) []api.SubtitleTarget
	LanguageCodes() []string
}

PollerCfg is the narrow configuration interface consumed by the poller subsystem. The full api.ConfigProvider satisfies it via structural typing. Declaring it here documents the poller's actual dependency surface.

type PollerEvents

type PollerEvents interface {
	Publish(e events.Event)
}

PollerEvents is the narrow events interface consumed by the poller.

type PollerMetrics

type PollerMetrics interface {
	RecordImport(source api.PollKey)
}

PollerMetrics is the narrow metrics interface consumed by the poller.

type PollerStore

type PollerStore interface {
	DeleteStateByPaths(ctx context.Context, paths []string) (api.CleanupResult, error)
}

PollerStore is the narrow store interface consumed by poll-import processing. Only DeleteStateByPaths is needed to clean up stale entries when a video file disappears between poll cycles.

type StateFunc

type StateFunc func() *LiveState

StateFunc returns the current live state. Called each poll cycle to pick up hot-reloaded config/clients.

type StatsCacheInvalidator

type StatsCacheInvalidator interface {
	Invalidate()
}

StatsCacheInvalidator is the narrow interface for stats cache invalidation.