mediasource

package
v0.10.0-dev.71 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

Documentation

Overview

Package mediasource is what subflux learns from its media sources (Sonarr, Radarr): the facts a source reports about its series and movies, its change cursor, and the errors every source call answers with.

Index

Constants

This section is empty.

Variables

View Source
var ErrAiredOrderUnavailable = errors.New("aired order unavailable")

ErrAiredOrderUnavailable wraps a join for a series in another order whose list agrees with no SkyHook reading; the Set reports its root unread, so nothing under it is retired or written.

View Source
var ErrRescanOutcomeUnknown = errors.New("rescan outcome unknown")

ErrRescanOutcomeUnknown wraps a Rescan the source may have run; the caller never sends it again.

View Source
var ScheduleSchema = formschema.Schema{Fields: []formschema.Field{
	{
		Key: "change_interval", Label: "Change check interval", Help: "How often subflux checks each source for imports, renames and deletes.",
		Kind: formschema.DurationMs, Default: "30s", Min: (10 * time.Second).Milliseconds(), Max: time.Hour.Milliseconds(),
	},
	{
		Key: "whole_interval", Label: "Full scan interval", Help: "Time between the end of one full library scan and the start of the next.",
		Kind: formschema.DurationMs, Default: "24h", Min: time.Hour.Milliseconds(), Max: (30 * 24 * time.Hour).Milliseconds(),
	},
}}

ScheduleSchema is the scan section's form; its defaults and minima are the poll_interval and search.scan_interval settings it replaces.

Functions

func CheckSaved

func CheckSaved(ctx context.Context, kinds []AdapterKind, deps Deps, prev, next []Config) []formschema.FieldError

CheckSaved is the sources half of the Save check: it pings each entry of next that prev lacks, whose Type differs from prev's entry with its ID, or whose value differs in a field its kind's schema marks Required or Secret, so the adapter's own schema decides which fields name the connection. The entries are pinged in parallel, so a Save waits at most one budget; each failure is a field error at sources[Index].

func PingEntry

func PingEntry(ctx context.Context, kinds []AdapterKind, deps Deps, cfg Config) error

PingEntry builds cfg's adapter with its kind's New and calls Ping under pingBudget, its answer mapped as a Set call's is; it builds no Set, so the save check and the connection test need nothing else a Set holds. An unknown type or a failing New is a plain error.

Types

type Adapter

type Adapter interface {
	Capabilities() Capabilities
	// Items returns its yield's or unread's error unchanged and stops. It
	// calls unread for a root it lists but cannot read and goes on; a failed
	// list read fails the call.
	Items(ctx context.Context, yield func(Root, []Item) error, unread Unread) error
	Root(context.Context, NativeRef) (Root, []Item, bool, error)
	Changes(context.Context, Cursor) ([]Change, Cursor, error)
	Tags(context.Context) (map[TagRef]string, error)
	RootFolders(context.Context) ([]string, error)
	Ping(context.Context) error
	Rescan(context.Context, NativeRef) error
	Poster(context.Context, NativeRef) (io.ReadCloser, string, bool, error)
}

Adapter answers for one configured source. New makes no request and starts no goroutine; every failure is a *SourceError; a zero Cursor passed to Changes takes the head; it is safe for concurrent use.

type AdapterKind

type AdapterKind struct {
	New    func(Config, Deps) (Adapter, error)
	Type   string
	Schema formschema.Schema
}

AdapterKind registers one source type.

type AiredOrderError

type AiredOrderError struct {
	Err   error
	Title string
}

AiredOrderError is a series root whose aired order cannot be read; Err is the join's error, which wraps ErrAiredOrderUnavailable and whose text is the reason.

func (*AiredOrderError) Error

func (e *AiredOrderError) Error() string

func (*AiredOrderError) Unwrap

func (e *AiredOrderError) Unwrap() error

Unwrap returns Err, so errors.Is sees ErrAiredOrderUnavailable.

type AliasedPathError

type AliasedPathError struct{ Path, To string }

AliasedPathError is a reported path that lies under a mapping's To while matching no From, so serving it would alias a mapped path. Its text follows the path it names.

func (*AliasedPathError) Error

func (e *AliasedPathError) Error() string

type Capabilities

type Capabilities struct {
	Kinds                          []media.Kind
	Changes, Rescan, Tags, Posters bool
}

Capabilities are what a source can do beyond listing its library.

type Catalogue

type Catalogue struct {
	// Fetched is when SkyHook answered this reading's order requests.
	Fetched time.Time
	// Orders lists every order but the aired one and "absolute".
	Orders []CatalogueOrder
	// Episodes are the aired order, SkyHook's "official" answer.
	Episodes []CatalogueEpisode
	TVDB     uint64
}

Catalogue is one SkyHook reading of a TVDB series' episode orders. Places and air dates are the same in every language, so it holds no title.

func (Catalogue) Reordered

func (c Catalogue) Reordered() bool

Reordered is the order index of a catalogue Validate accepts: some order moves a regular episode. Whether an order is listed says nothing; most DVD orders move none.

type CatalogueEpisode

type CatalogueEpisode struct {
	// AirDate is YYYY-MM-DD, or "" when SkyHook lists none.
	AirDate string
	// ID is the TVDB episode id, SkyHook's tvdbId, distinct in a catalogue.
	ID uint64
	// Season, Episode and Absolute are aired; Absolute is 0 when none.
	Season, Episode, Absolute int
}

CatalogueEpisode is one episode of the aired order.

type CatalogueOrder

type CatalogueOrder struct {
	Type, Name string
	// Places is parallel to Catalogue.Episodes.
	Places []Place
	// Extra are the order's places Places cannot hold, an episode the aired
	// list lacks or an aired episode's second place, ascending by season and
	// episode.
	Extra []ExtraPlace
}

CatalogueOrder is one order's places for the catalogue's episodes.

type Cause

type Cause uint8

Cause is why a source call failed.

const (
	Unreachable Cause = iota + 1
	Unauthorized
	NotFound
	Protocol
	Unsupported
	UnknownSource
	// Expired is a cursor the source no longer serves; a whole pass replaces it.
	Expired
)

The causes; the zero Cause is unset.

func (Cause) String

func (c Cause) String() string

String is the snake_case value name, the spelling api's error codes and the source alert's text use; an undefined value is cause(<n>).

type Change

type Change struct{ Root NativeRef }

Change names a root whose items may have changed, a deletion included.

type Config

type Config struct {
	Values       formschema.Values
	ID           media.SourceID
	Type         string
	PathMappings []PathMapping
	ExcludeTags  []string
	Index        int
}

Config is one parsed sources entry. Index is its position in the section, enabled: false entries counted, so a field error about it names sources[Index].

func ParseConfigs

func ParseConfigs(n *yaml.Node, kinds []AdapterKind) ([]Config, []formschema.FieldError)

ParseConfigs reads the sources section, n being its node or nil when absent, and reports every refusal at once at its absolute path. Adapter keys go to the kind's Schema.Decode and the whole entry to the kind's New with a zero Deps. An entry with enabled: false is validated and left out of the result. Every envelope scalar is marked plain. The settings loader refuses anchors, aliases and tags before any section parses, so n holds none.

type Cursor

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

Cursor is a source's change position, opaque to all but the adapter that wrote it, which reads its own format version from the bytes and answers Expired for a version it cannot read. The zero Cursor asks for the head.

func (Cursor) IsZero

func (c Cursor) IsZero() bool

IsZero reports whether c is the zero Cursor, which names no position.

func (Cursor) MarshalBinary

func (c Cursor) MarshalBinary() ([]byte, error)

MarshalBinary returns a copy of the cursor's bytes, none for the zero Cursor.

func (*Cursor) UnmarshalBinary

func (c *Cursor) UnmarshalBinary(b []byte) error

UnmarshalBinary keeps a copy of b, refusing nothing, so a stored cursor in an unreadable format reaches the adapter's Expired rather than failing every read of it. Empty b is the zero Cursor.

type Deps

type Deps struct {
	HTTP   *http.Client
	Logger *slog.Logger
}

Deps is what an adapter's New may copy; a nil field takes the adapter's default.

type EntryEdit

type EntryEdit uint8

EntryEdit is how a sources entry differs from its earlier form with the same ID.

const (
	// EntrySame is no field changed; Index is the entry's position in the
	// section, not its configuration, so a moved entry is the same.
	EntrySame EntryEdit = iota
	// EntryRekeyed is only fields the kind's schema marks Secret changed: a
	// credential names no other instance.
	EntryRekeyed
	// EntryChanged is the type or any other field changed.
	EntryChanged
)

func CompareEntry

func CompareEntry(kinds []AdapterKind, prev, cur *Config) EntryEdit

CompareEntry answers how cur differs from prev, the earlier entry with its ID; kinds supplies the schema marking the Secret fields, and a type kinds lacks is EntryChanged.

type EpisodeTitle

type EpisodeTitle struct {
	Title string
	ID    uint64
}

EpisodeTitle is one episode's title in a TitleSet's language.

type ExtraPlace

type ExtraPlace struct {
	// AirDate is YYYY-MM-DD, or "" when SkyHook lists none.
	AirDate         string
	Season, Episode int
}

ExtraPlace is an order's place for an episode the aired list lacks; such an episode can agree with a source's list but has no aired key.

type Item

type Item struct {
	// AudioLangs are the file's audio tracks, in track order.
	AudioLangs []language.Tag
	Tags       []TagRef
	Native     NativeID
	Title      string
	// AirDate is YYYY-MM-DD as the source lists it; "" while unaired.
	AirDate              string
	VideoPath, SceneName string
	OriginalLang         language.Tag
	External             media.ExternalIDs
	// Numbering is the episode's place in TVDB's aired order, the one its key
	// is chosen by; the Set sets it from the aired join, overwriting any
	// adapter's value.
	Numbering media.Numbering
	// SeriesNumbering is the episode's place in Root.Order, as the source
	// lists and names it; it equals Numbering under the aired order.
	SeriesNumbering media.Numbering
	// Absolute is the aired absolute number, 0 when none: the source's own
	// under the aired order, the join's under any other.
	Absolute int
	// Excluded is set by the Set alone, from the source's exclude tags.
	Excluded bool
}

Item is one episode or movie of a Root, whose kind it shares.

type JoinQuery

type JoinQuery struct {
	// Episodes are in the series' order.
	Episodes []Listed
	// Source and Root name the root whose stored evidence the join reads.
	Source   media.SourceID
	Root     NativeRef
	Language language.Tag
	Order    Order
	TVDB     uint64
}

JoinQuery is one series as a source lists it, for the Set's aired join.

type Joined

type Joined struct {
	Season, Episode, Absolute int
	OK                        bool
}

Joined is a listed episode's aired place; OK false leaves it unidentified.

type Listed

type Listed struct {
	AirDate, Title            string
	Season, Episode, Absolute int
}

Listed is an episode as its source lists it, in its series' order.

type NativeID

type NativeID string

NativeID is a source's own id for a root or item: 1 to 64 bytes of [A-Za-z0-9._:-], canonical decimal on Sonarr and Radarr. It is never identity; media.Key is.

type NativeRef

type NativeRef struct {
	ID   NativeID
	Kind media.Kind
}

NativeRef names a root in its source.

type Order

type Order struct {
	Type, Name string
	Aired      bool
}

Order is a series' episode order as its source names it; a movie's is zero. Name is "" while the source names none, and Aired means the order's numbers are TVDB's aired order.

type OrderJoin

type OrderJoin interface {
	Join(ctx context.Context, q JoinQuery) ([]Joined, *RootEvidence, error)
}

OrderJoin is the aired join the Set keys every episode root through (design 3.6): one Joined per listed episode, in order, with the evidence the yielded root carries; or an error wrapping ErrAiredOrderUnavailable, a passed deadline's included, or the store's error, which fails the call. It is a NewSet argument, not a Deps field, so no adapter or media server gets it.

type PathMapping

type PathMapping struct{ From, To string }

PathMapping maps a source's From prefix to the local To prefix.

type Place

type Place struct {
	Season, Episode int
	Listed          bool
}

Place is an episode's season and episode in one order; Listed is false when the order leaves the episode out.

type Root

type Root struct {
	// Evidence is the root's SkyHook evidence from the aired join, nil when
	// none.
	Evidence  *RootEvidence
	AltTitles []string
	Title     string
	// Link is the root's page in the source's web UI, under public_url, else
	// url: an absolute http or https URL, or "".
	Link string
	// Language is the series' metadata language, zero when the source reports
	// none; the aired join asks SkyHook in it.
	Language language.Tag
	Order    Order
	Native   NativeRef
	External media.ExternalIDs
	// Year is the series' or movie's year, 0 when the source gives none.
	Year int
}

Root is a series or a movie as its source reports it.

type RootEvidence

type RootEvidence struct {
	Held  *SeriesEvidence
	Bound SeriesEvidence
}

RootEvidence is one root's evidence: Bound, the chosen reading (under any order but the aired one, the reading its stored keys came from), and Held, a later reading its source's list has not agreed with, nil when none.

func (RootEvidence) Validate

func (r RootEvidence) Validate() error

Validate refuses an invalid reading, title sets repeated or out of order by Language, a title for an id its catalogue lacks, and a Held for another TVDB id or fetched no later than Bound.

type Schedule

type Schedule struct{ Change, Whole time.Duration }

Schedule is the scan section: how often scan checks each source for changes, and how long after a whole pass ends the next is due. It lives here, not in scan, so settings can hold it without importing scan, which imports status.

func ParseSchedule

func ParseSchedule(n *yaml.Node) (Schedule, []formschema.FieldError)

ParseSchedule decodes the scan section, n being its node or nil when absent, reporting each error at scan.<key>; Decode marks both scalars plain.

type SeriesEvidence

type SeriesEvidence struct {
	Titles    []TitleSet
	Catalogue Catalogue
}

SeriesEvidence is one reading, never a mix: its catalogue and its title sets, ascending by Language, each holding the catalogue's aired episodes.

type Set

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

Set is the configured sources behind one check of every answer. It is safe for concurrent use.

func NewSet

func NewSet(kinds []AdapterKind, cfgs []Config, deps Deps, orders OrderJoin) (*Set, error)

NewSet builds each entry's adapter over deps, keying episodes through orders, refusing an unknown type, a duplicate id, a failing New or a nil orders: ParseConfigs ran each check, so any of them is a programming fault.

func (*Set) Capabilities

func (s *Set) Capabilities(id media.SourceID) (Capabilities, bool)

Capabilities answers a source's capabilities; false for an unknown id.

func (*Set) Changes

func (s *Set) Changes(ctx context.Context, id media.SourceID, cur Cursor) ([]Change, Cursor, error)

Changes answers the roots changed since cur and the cursor after them; each change root passes the identity rule, once per answer.

func (*Set) Inherit

func (s *Set) Inherit(prev *Set)

Inherit copies prev's root-folder and tag caches into each entry whose Config equals prev's entry with that ID outside the fields its kind's schema marks Secret, so an edit elsewhere, or of a key alone, keeps a source's roots while it is down. App calls it before publishing a rebuilt Set; a nil prev is a no-op.

func (*Set) Items

func (s *Set) Items(ctx context.Context, id media.SourceID, yield func(Root, []Item) error, unread Unread) error

Items walks the source's library, yielding each root after its answer check, exclusion and aired keys. A root breaking a per-root bound, or whose aired order cannot be read, goes to unread with nothing yielded, as do the adapter's own reports; an identity violation or a join's store failure fails the call. The walk ends with the error of the walkFailBudget-th consecutive unread root the source failed, or of the unread root past maxUnreadRoots. The caller's yield or unread error comes back unwrapped. unread must be non-nil.

func (*Set) LocalPath

func (s *Set) LocalPath(src media.SourceID, remote string) (string, error)

LocalPath maps a folder a source reports by the rule a video path maps by, an unmatched path passing through. A path breaking the path rule, or one aliasing a mapped path, is Protocol; an unknown source UnknownSource.

func (*Set) MediaRoots

func (s *Set) MediaRoots(ctx context.Context) []string

MediaRoots answers, deduped and sorted, each source's mapping targets, or for an unmapped source its last successful root folders. An empty cache is filled once per Set on a context no caller cancels, bounded by rootFoldersWait; each caller waits for it at most until its own deadline.

func (*Set) Ping

func (s *Set) Ping(ctx context.Context, id media.SourceID) error

Ping checks that the source answers with the configured credentials.

func (*Set) Poster

func (s *Set) Poster(ctx context.Context, id media.SourceID, ref NativeRef) (body io.ReadCloser, contentType string, found bool, err error)

Poster opens a root's poster with its content type; false when it has none. The caller closes the reader.

func (*Set) Rescan

func (s *Set) Rescan(ctx context.Context, id media.SourceID, ref NativeRef) error

Rescan asks the source to rescan one root.

func (*Set) Root

func (s *Set) Root(ctx context.Context, id media.SourceID, ref NativeRef) (Root, []Item, bool, error)

Root reads one root fresh, with its items, after the answer check and aired keys; false with no error when the source has no such root. A root whose aired order cannot be read answers that *SourceError.

func (*Set) RootFolders

func (s *Set) RootFolders(ctx context.Context, id media.SourceID) ([]string, error)

RootFolders answers the source's root folders, dropping with one WARN any that breaks the path rule; a successful answer refreshes what MediaRoots reports for an unmapped source.

func (*Set) Sources

func (s *Set) Sources() []media.SourceID

Sources lists the configured ids in entry order.

type SourceError

type SourceError struct {
	Err    error
	Source media.SourceID
	Op     string
	Cause  Cause
}

SourceError is every failure of a source call. Op is the method name.

func (*SourceError) Error

func (e *SourceError) Error() string

Error is "source <id> <op>: <cause>: <err>", leaving out an unset Source, Op or Err.

func (*SourceError) Unwrap

func (e *SourceError) Unwrap() error

Unwrap returns Err, so errors.Is and httpclient.IsTransient see the cause.

type TagRef

type TagRef NativeID

TagRef is a source's own id for one of its tags.

type TitleSet

type TitleSet struct {
	// Language is an ISO 639-2/T code.
	Language string
	// Titles ascend by ID.
	Titles []EpisodeTitle
	// Found is false when SkyHook answered 404 for Language.
	Found bool
}

TitleSet is one language's episode titles of a reading; an episode with no title in Language is absent.

type Unread

type Unread func(NativeRef, *SourceError) error

Unread is Items' report of a root the walk lists but cannot read or must refuse. The walk goes on when it returns nil; a non-nil return ends the walk with that error.

Directories

Path Synopsis
arr
Package arr is what the Sonarr and Radarr adapters share: their form, error classifier, history cursor, tags, root folders and the poster's two-zone fetch.
Package arr is what the Sonarr and Radarr adapters share: their form, error classifier, history cursor, tags, root folders and the poster's two-zone fetch.
arrtest
Package arrtest serves a Sonarr's or Radarr's recorded answers to the adapters' tests, in process or over a socket, and checks a recording directory holds no credential.
Package arrtest serves a Sonarr's or Radarr's recorded answers to the adapters' tests, in process or over a socket, and checks a recording directory holds no credential.
Package radarr is the media source over Radarr (API v3), through arrapi v3.
Package radarr is the media source over Radarr (API v3), through arrapi v3.
Package sonarr is the media source over Sonarr v4 (API v3) and v5 (API v5), through arrapi v3.
Package sonarr is the media source over Sonarr v4 (API v3) and v5 (API v5), through arrapi v3.
Package sourcetest is the contract suite every mediasource adapter passes, the fake library a harness serves, and Fake, an in-memory adapter for Set and scan tests.
Package sourcetest is the contract suite every mediasource adapter passes, the fake library a harness serves, and Fake, an in-memory adapter for Set and scan tests.

Jump to

Keyboard shortcuts

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