Documentation
¶
Overview ¶
Package arrsvc composes the github.com/cplieger/arrapi Sonarr and Radarr clients with subflux's subtitle-specific operations: "wanted" iteration (which library items need a subtitle search), exclude-tag name resolution, and a fire-and-forget rescan. The raw library reads, per-item lookups, history polling, and connectivity ping are promoted from the embedded arrapi client unchanged, so this package adds only the app-level behavior arrapi deliberately does not provide.
It also holds the ONE arr-read wrapper (CachedSonarr/CachedRadarr over a shared ReadGate): the four read families — series list, movie list, episodes-by-series, exclude-tag resolution — route through its cache, plain-read coalescing, and ?recovery=1 waves.
Index ¶
- Variables
- func AudioLanguages(mi *arrapi.MediaInfo) []string
- func HasExcludeTag(tags []int, excludeIDs map[int]struct{}) bool
- func OriginalLangCode(lang *arrapi.Language) string
- func RecoveryMarked(ctx context.Context) bool
- func SeasonEpisodeFileCount(s *arrapi.Series, seasonNum int) int
- func WithRecovery(ctx context.Context) context.Context
- type APIKey
- type CachedRadarr
- func (c *CachedRadarr) Close()
- func (c *CachedRadarr) MovieByTmdbID(ctx context.Context, tmdbID int) (arrapi.Movie, bool, error)
- func (c *CachedRadarr) Movies(ctx context.Context) ([]arrapi.Movie, error)
- func (c *CachedRadarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
- func (c *CachedRadarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
- func (c *CachedRadarr) WantedMovies(ctx context.Context, excludeTagIDs map[int]struct{}, ...) error
- type CachedSonarr
- func (c *CachedSonarr) Close()
- func (c *CachedSonarr) Episodes(ctx context.Context, seriesID int) ([]arrapi.Episode, error)
- func (c *CachedSonarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
- func (c *CachedSonarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
- func (c *CachedSonarr) Series(ctx context.Context) ([]arrapi.Series, error)
- func (c *CachedSonarr) SeriesByTvdbID(ctx context.Context, tvdbID int) (arrapi.Series, bool, error)
- func (c *CachedSonarr) WantedEpisodes(ctx context.Context, excludeTagIDs map[int]struct{}, ...) error
- type Radarr
- func (r *Radarr) RescanMovie(ctx context.Context, movieID int) error
- func (r *Radarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
- func (r *Radarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
- func (r *Radarr) WantedMovies(ctx context.Context, excludeTagIDs map[int]struct{}, ...) error
- type ReadGate
- type Sonarr
- func (s *Sonarr) RescanSeries(ctx context.Context, seriesID int) error
- func (s *Sonarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
- func (s *Sonarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
- func (s *Sonarr) WantedEpisodes(ctx context.Context, excludeTagIDs map[int]struct{}, ...) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRecoveryRefused is the refusal sentinel: the admission budget // expired before the wave was admitted, or the request deadline expired // before the read settled. Handlers map it to 429 // (httpapi.TooManyRequestsC) — a refusal to keep waiting, never a 500 // through the generic InternalErrorC arm. ErrRecoveryRefused = errors.New("recovery read refused") // ErrRecoveryFailed is the execution-failure sentinel: an admitted wave // pass failed (upstream error, execution-budget expiry, or server // shutdown), fanned out to every waiter. Handlers map it to the family's // upstream-failure status (502). ErrRecoveryFailed = errors.New("recovery wave failed") // ErrUnknownSeries is the ordered membership gate's post-wave verdict: a // marked episodes read whose series id misses the fresh series list. // Handlers map it to 404; no upstream episodes call was made. ErrUnknownSeries = errors.New("series not in the sonarr library") )
Sentinel errors of the wrapper's recovery (marked) reads, exported so the coverage and media handlers can map them to the wire. The wrapper never writes HTTP itself.
Functions ¶
func AudioLanguages ¶ added in v0.4.0
AudioLanguages parses a file's MediaInfo audio-languages string into deduplicated ISO 639-1 codes. Returns nil when mi is nil or empty.
func HasExcludeTag ¶ added in v0.4.0
HasExcludeTag reports whether any of the item's tags are in the exclude set.
func OriginalLangCode ¶ added in v0.4.0
OriginalLangCode returns the ISO 639-1 code for an arr original-language reference, or "" when the reference is nil or the name is unmapped.
func RecoveryMarked ¶ added in v0.5.0
RecoveryMarked reports whether ctx carries the ?recovery=1 marker set by WithRecovery. The handler-level honoring pin reads it through fake clients: exactly the honoring endpoints interpret the query parameter, and this is what lets a test observe that from outside the package.
func SeasonEpisodeFileCount ¶ added in v0.4.0
SeasonEpisodeFileCount returns the number of episode files for a specific season, using Sonarr's per-season statistics. Returns 0 if the season is not found or statistics are unavailable.
func WithRecovery ¶ added in v0.5.0
WithRecovery marks ctx as carrying a ?recovery=1 read and arms the request deadline at the current instant. The handler calls it once at server request arrival, before the consumer-interface call; every wrapper read on the returned context selects wave admission and charges against the one deadline. An unmarked context reads plain.
Types ¶
type APIKey ¶ added in v0.4.0
APIKey is arrapi's credential type, re-exported so callers convert with arrsvc.APIKey(...) instead of importing arrapi for one cast. An alias, not a new type: it IS the library's type, and a second distinct one would add a conversion without adding a guarantee.
type CachedRadarr ¶ added in v0.5.0
type CachedRadarr struct {
*Radarr
// contains filtered or unexported fields
}
CachedRadarr is the Radarr half of the arr-read wrapper; see CachedSonarr.
func NewCachedRadarr ¶ added in v0.5.0
func NewCachedRadarr(baseURL string, apiKey APIKey, gate *ReadGate) (*CachedRadarr, error)
NewCachedRadarr builds the wrapped Radarr service; see NewCachedSonarr.
func (*CachedRadarr) Close ¶ added in v0.5.0
func (c *CachedRadarr) Close()
Close releases both clients' transports.
func (*CachedRadarr) MovieByTmdbID ¶ added in v0.5.0
MovieByTmdbID returns the cached movie row for one TMDB id; see SeriesByTvdbID.
func (*CachedRadarr) Movies ¶ added in v0.5.0
Movies returns the cached movie list. The returned slice is shared and read-only.
func (*CachedRadarr) ResolveExcludeTagIDs ¶ added in v0.5.0
func (c *CachedRadarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
ResolveExcludeTagIDs is the fail-open projection; see the CachedSonarr method.
func (*CachedRadarr) ResolveExcludeTagIDsErr ¶ added in v0.5.0
func (c *CachedRadarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
ResolveExcludeTagIDsErr is the Radarr-side error-returning exclude-tag resolution; see the CachedSonarr method.
func (*CachedRadarr) WantedMovies ¶ added in v0.5.0
func (c *CachedRadarr) WantedMovies(ctx context.Context, excludeTagIDs map[int]struct{}, fn func(arrapi.Movie) error) error
WantedMovies is the scan engine's Radarr entry point; see WantedEpisodes.
type CachedSonarr ¶ added in v0.5.0
type CachedSonarr struct {
*Sonarr
// contains filtered or unexported fields
}
CachedSonarr is the Sonarr half of the arr-read wrapper (A4): the series list, episodes-by-series and exclude-tag read families route through one cache with plain-read coalescing and recovery waves; every other method passes through to the shipped client. Plain reads fetch on the shipped 3-attempt client; admitted wave passes run single-attempt on the wrapper's own wave client. Returned slices are shared cache state: read-only.
func NewCachedSonarr ¶ added in v0.5.0
func NewCachedSonarr(baseURL string, apiKey APIKey, gate *ReadGate) (*CachedSonarr, error)
NewCachedSonarr builds the wrapped Sonarr service: the shipped client plus the wrapper's own wave client (WithMaxAttempts(1), WithTimeout at the execution budget), constructed together so activation publishes and closes them atomically. The wrapper's cache starts empty, so a reload revokes the previous instance's in-flight wave writes.
func (*CachedSonarr) Close ¶ added in v0.5.0
func (c *CachedSonarr) Close()
Close releases both clients' transports.
func (*CachedSonarr) Episodes ¶ added in v0.5.0
Episodes returns the cached episode list for one series. A MARKED read passes the ordered membership gate first: an id missing from the cached series list awaits/joins the same recovery's series-list wave and re-checks; only a post-wave miss answers ErrUnknownSeries, with no upstream episodes call. A plain read keeps today's behavior — a miss falls through to the cached upstream call.
func (*CachedSonarr) ResolveExcludeTagIDs ¶ added in v0.5.0
func (c *CachedSonarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
ResolveExcludeTagIDs is the shipped fail-open projection over ResolveExcludeTagIDsErr, kept by plain reads and the scan path.
func (*CachedSonarr) ResolveExcludeTagIDsErr ¶ added in v0.5.0
func (c *CachedSonarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
ResolveExcludeTagIDsErr is the error-returning exclude-tag resolution: cached beneath the fail-open, so only err == nil results are stored, and a marked read's wave failure or refusal PROPAGATES (a typed leg failure at the HTTP response, never a silent empty-exclusion 200).
func (*CachedSonarr) Series ¶ added in v0.5.0
Series returns the cached series list. The returned slice is shared and read-only.
func (*CachedSonarr) SeriesByTvdbID ¶ added in v0.5.0
SeriesByTvdbID returns the cached series row for one TVDB id, resolved through the tvdb→row index carried inside the entry value. Absence is a normal answer: an id the list does not hold (only positive ids are ever indexed) reports found == false with a nil error. The returned row shares cache state: read-only.
func (*CachedSonarr) WantedEpisodes ¶ added in v0.5.0
func (c *CachedSonarr) WantedEpisodes(ctx context.Context, excludeTagIDs map[int]struct{}, fn func(arrapi.Series, arrapi.Episode) error) error
WantedEpisodes is the scan engine's entry point: its fetches bypass the cache (always fresh) and register as write-through waves.
type Radarr ¶
Radarr composes arrapi.Radarr with subflux's wanted-movie iteration, exclude-tag resolution, and error-only rescan.
func NewRadarr ¶
NewRadarr builds a Radarr service for the given base URL and API key. The key is typed for the same reason NewSonarr's is.
func (*Radarr) RescanMovie ¶
RescanMovie asks Radarr to rescan the movie's folder for new or changed files. Fire-and-forget, like RescanSeries.
func (*Radarr) ResolveExcludeTagIDs ¶
func (r *Radarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
ResolveExcludeTagIDs is the Radarr-side counterpart.
func (*Radarr) ResolveExcludeTagIDsErr ¶ added in v0.5.0
func (r *Radarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
ResolveExcludeTagIDsErr is the Radarr-side error-returning form.
func (*Radarr) WantedMovies ¶ added in v0.4.0
func (r *Radarr) WantedMovies(ctx context.Context, excludeTagIDs map[int]struct{}, fn func(arrapi.Movie) error) error
WantedMovies invokes fn for every movie that needs a subtitle search. It fetches the full movie list first (closing that connection), then iterates locally, skipping movies with an excluded tag or no file.
type ReadGate ¶ added in v0.5.0
type ReadGate struct {
// contains filtered or unexported fields
}
ReadGate is the shared half of the arr-read wrapper: the global FIFO wave-admission queue — both arr sides share it, so maxConcurrentWaves is an aggregate ceiling — plus the server runtime wave passes run under. One per server, surviving config reloads; the per-instance halves (CachedSonarr, CachedRadarr) are rebuilt by every activation.
func NewReadGate ¶ added in v0.5.0
NewReadGate builds the gate. serverCtx yields the server lifetime context (shutdown cancels admitted passes; upstream calls are never derived from a waiter's request context); bg is the WaitGroup wave runners and their timers register with. Either may be nil in tests.
type Sonarr ¶
Sonarr composes arrapi.Sonarr with subflux's wanted-episode iteration, exclude-tag resolution, and error-only rescan.
func NewSonarr ¶
NewSonarr builds a Sonarr service for the given base URL and API key.
The key is typed rather than a second string: the two were adjacent and both strings, so a transposed pair compiled and dialled the API key as a URL, putting the credential in the connection error. The conversion to arrapi's type used to happen INSIDE this function — one level past the boundary a caller can actually get wrong.
func (*Sonarr) RescanSeries ¶
RescanSeries asks Sonarr to rescan the series' folder for new or changed files (subflux calls this after writing a subtitle). It is fire-and-forget: arrapi returns the queued command, which subflux does not poll, so only the error is surfaced.
func (*Sonarr) ResolveExcludeTagIDs ¶
func (s *Sonarr) ResolveExcludeTagIDs(ctx context.Context, names []string, logMissing bool) map[int]struct{}
ResolveExcludeTagIDs returns the arr tag IDs matching the given tag names. When logMissing is true, names with no matching tag are logged once at INFO (coverage passes false to avoid repeating the message on every page load).
func (*Sonarr) ResolveExcludeTagIDsErr ¶ added in v0.5.0
func (s *Sonarr) ResolveExcludeTagIDsErr(ctx context.Context, names []string, logMissing bool) (map[int]struct{}, error)
ResolveExcludeTagIDsErr is the error-returning form: a tag-fetch error PROPAGATES instead of failing open, so a recovery read can surface it as a typed leg failure.
func (*Sonarr) WantedEpisodes ¶ added in v0.4.0
func (s *Sonarr) WantedEpisodes(ctx context.Context, excludeTagIDs map[int]struct{}, fn func(arrapi.Series, arrapi.Episode) error) error
WantedEpisodes invokes fn for every episode that needs a subtitle search. It fetches the full series list first (closing that connection), then fetches each non-excluded series' episodes concurrently (bounded to 6 goroutines), then invokes fn sequentially. A series whose episode fetch keeps failing is logged and skipped rather than aborting the whole scan.