manualops

package
v0.4.4 Latest Latest
Warning

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

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

Documentation

Overview

Package manualops implements the business logic for manual subtitle search and download operations. The HTTP handler glue remains in the parent server package; this package owns validation, query parsing, result building, and the background download pipeline.

Index

Constants

View Source
const DownloadTimeout = 5 * time.Minute

DownloadTimeout is the context timeout for manual downloads.

View Source
const MaxResults = 50

MaxResults caps the number of results returned by manual search.

Variables

View Source
var (
	ErrMissingRequired = errors.New("provider, subtitle_id, media_id, and language are required")
	// ErrInvalidLangCode is returned for a code outside subflux's internal
	// code space (ISO 639-1 plus "pb"). The code becomes a dot segment of the
	// subtitle filename written next to the media file, so this boundary gates
	// on the same closed vocabulary the automated path uses rather than on a
	// list of characters to bar: a vocabulary cannot be widened by an input.
	ErrInvalidLangCode  = errors.New("invalid language code")
	ErrInvalidMediaType = errors.New("invalid media_type")
	ErrMissingEpisode   = errors.New("season and episode are required for episode downloads")
)

Validation errors returned by ValidateDownloadRequest.

Functions

func LookupEpisodeMediaID

func LookupEpisodeMediaID(ctx context.Context, ls *LiveState, seriesID, season, episode int) string

LookupEpisodeMediaID finds the tvdb-based media ID for a Sonarr episode.

func LookupMediaTitle

func LookupMediaTitle(ctx context.Context, ls *LiveState, mediaType subflux.MediaType, arrID int) string

LookupMediaTitle resolves the title for a media item from the arr client.

func LookupMovieMediaID

func LookupMovieMediaID(ctx context.Context, ls *LiveState, arrID int) string

LookupMovieMediaID finds the tmdb-based media ID for a Radarr movie.

func NotifyError

func NotifyError(deps *SearchDeps, n ErrorNotice)

NotifyError publishes an error notification and records an alert.

func ParseSearchQuery

func ParseSearchQuery(r *http.Request) (req subflux.SearchRequest, lang string, mediaType subflux.MediaType, arrID int)

ParseSearchQuery extracts search parameters from the request URL. The optional media_id parameter is the ARR internal ID (Radarr movie ID / Sonarr series ID): with season/episode it forms the MediaRef the handler resolves server-side for hash computation — the former client-supplied ?file= path parameter is gone (S7).

func PostDownloadUpdate

func PostDownloadUpdate(ctx context.Context, ls *LiveState, db DownloadStore,
	req *DownloadRequest, mediaType subflux.MediaType, coverageMediaID, subPath string, variant subflux.Variant,
)

PostDownloadUpdate updates coverage DB and refreshes the arr after a successful manual download.

func QueryInt

func QueryInt(q interface{ Get(string) string }, key string) int

QueryInt parses a URL query parameter as a non-negative integer, returning 0 on missing, invalid, or negative values.

func ResolveMediaIDs

func ResolveMediaIDs(ctx context.Context, ls *LiveState,
	mediaType subflux.MediaType, arrID, season, episode int,
) (coverageID, historyID string)

ResolveMediaIDs determines the coverage and history media IDs for a manual download.

func RunDownload

func RunDownload(ctx context.Context, deps *SearchDeps, ls *LiveState, db DownloadStore,
	prov provider.Provider, req *DownloadRequest, actID string,
) bool

RunDownload performs the actual download, post-processing, and save. actID is the download's activity entry: on a successful save the entry's detail is updated with the saved subtitle path, which is how activity consumers (the remote CLI's poll loop) learn where the file landed. Returns true on success.

func TryComputeHash

func TryComputeHash(ctx context.Context, ls *LiveState, req *subflux.SearchRequest, filePath string)

TryComputeHash attempts to compute the video hash for the search request. Logs warnings on validation or hash failures; updates req in place on success.

func ValidateDownloadRequest

func ValidateDownloadRequest(req *DownloadRequest) error

ValidateDownloadRequest checks that the download request has all required fields and valid values. It normalises MediaType to "movie" when empty. Returns nil on success.

Types

type ActivityTracker

type ActivityTracker interface {
	Start(action, detail string, source activity.Source) string
	End(id string)
	Fail(id string)
	Progress(id string, current, total int, detail string)
}

ActivityTracker manages activity lifecycle. Progress doubles as the detail mutator: download completion writes the saved subtitle path into the entry detail so activity consumers (the remote CLI's poll loop) can report it.

type BGTracker

type BGTracker interface {
	Go(f func())
}

BGTracker registers a background goroutine with the server's WaitGroup for graceful-shutdown tracking. One method, because sync.WaitGroup.Go (Go 1.25) launches and counts in one call: an Add/Done pair can leak a counter (an early return or a panic before the defer is installed leaves the drain hung), and a one-method surface makes that unrepresentable.

type DownloadAccepted added in v0.1.148

type DownloadAccepted struct {
	ActivityID string `json:"activity_id"`
	Status     string `json:"status"`
}

DownloadAccepted is the typed 202 Accepted response for manual downloads.

type DownloadRequest

type DownloadRequest struct {
	Provider    subflux.ProviderID `json:"provider"`
	SubtitleID  string             `json:"subtitle_id"`
	Language    string             `json:"language"`
	ReleaseName string             `json:"release_name,omitempty"`
	MediaType   subflux.MediaType  `json:"media_type,omitempty"`

	Score      int  `json:"score,omitempty"`
	Season     int  `json:"season,omitempty"`
	Episode    int  `json:"episode,omitempty"`
	ArrID      int  `json:"media_id,omitempty"`
	TopPick    bool `json:"top_pick,omitempty"`
	HearingImp bool `json:"hearing_impaired,omitempty"`
	Forced     bool `json:"forced,omitempty"`
	// contains filtered or unexported fields
}

DownloadRequest holds the parsed fields for a manual download. The video is addressed by MediaRef only (media_type + media_id [arr ID] + season/episode); the server resolves the video file path from the arr — the wire carries no file path (S7). videoPath is the server-resolved value, set by the handler after resolution, never decoded from JSON.

func (*DownloadRequest) SetVideoPath added in v0.1.148

func (req *DownloadRequest) SetVideoPath(path string)

SetVideoPath records the server-resolved video path on the request. Called by the HTTP handler after MediaRef resolution (and by tests); the download pipeline reads it via VideoPath.

func (*DownloadRequest) VideoPath added in v0.1.148

func (req *DownloadRequest) VideoPath() string

VideoPath returns the server-resolved video file path.

type DownloadStore

type DownloadStore interface {
	Store
	NextManualNumber(ctx context.Context, key subflux.ManualLockKey) int
	UpsertSubtitleFile(ctx context.Context, mediaType subflux.MediaType, mediaID string, sf *subflux.SubtitleFile) error
	SetSyncOffset(ctx context.Context, path string, offsetMs int64) error
	SaveDownload(ctx context.Context, rec *subflux.DownloadRecord) error
}

DownloadStore is what saving a manual download writes: the next ordinal for the numbered file, the coverage row, the timing offset, and the download record — plus Store, because a download re-reads what the search leg read. 6 of the 36 methods the store offers, composed by embedding so the two legs cannot disagree about the read half.

type ErrorNotice added in v0.4.0

type ErrorNotice struct {
	// Source attributes the alert to a subsystem.
	Source string
	// Alert is the operator-facing text; it lands in the alert log.
	Alert string
	// UI is the user-facing text; it lands on the notify bus.
	UI string
}

ErrorNotice is one error's two audiences: the operator reading the alert log and the user watching the UI.

Named rather than positional because Alert and UI are both human-readable text of the same type, so a transposition compiles and reads plausibly at the call site while putting the internal diagnosis in front of the user and the user-facing summary in the operator's alert log. Two of the three call sites pass DIFFERENT strings for the two, which is exactly where such a swap leaves no trace — the one that passes the same string twice would not even change behaviour, so the reviewer gets no signal from the sites either.

type EventPublisher

type EventPublisher interface {
	PublishNotify(level events.NotifyLevel, text string)
	PublishCoverageUpdate(ev *events.CoverageEvent)
}

EventPublisher publishes events to SSE clients. *events.EventBus satisfies it structurally.

type Handler

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

Handler provides HTTP handlers for manual search and download endpoints.

func NewHandler

func NewHandler(deps HandlerDeps) *Handler

NewHandler creates a manual ops Handler with the given dependencies.

func (*Handler) HandleClearLock

func (h *Handler) HandleClearLock(w http.ResponseWriter, r *http.Request)

HandleClearLock handles POST /api/search/clear-lock.

func (*Handler) HandleManualDownload

func (h *Handler) HandleManualDownload(w http.ResponseWriter, r *http.Request)

HandleManualDownload handles POST /api/search/download.

func (*Handler) HandleManualSearch

func (h *Handler) HandleManualSearch(w http.ResponseWriter, r *http.Request)

HandleManualSearch handles GET /api/search?imdb=tt1234567&lang=fr&type=movie

func (*Handler) HandleSearchResolve added in v0.1.148

func (h *Handler) HandleSearchResolve(w http.ResponseWriter, r *http.Request)

HandleSearchResolve handles GET /api/search/resolve.

type HandlerDeps

type HandlerDeps struct {
	DBFunc     func() DownloadStore
	Activity   ActivityTracker
	Alerts     WarnRecorder
	Events     EventPublisher
	StateFunc  func() *LiveState
	BGTracker  BGTracker
	ServerCtx  func() context.Context
	Resolve    *resolve.Resolver
	DecodeJSON func(w http.ResponseWriter, r *http.Request, v any, maxSize int64) bool
}

HandlerDeps holds the dependencies for the manual search/download HTTP handlers. Resolve is the S7 typed-reference resolver: the download verb and the manual-search hash computation address the video by MediaRef and the server resolves the file path from the arr — no client-supplied paths.

type LiveState

type LiveState struct {
	Cfg       pathValidator
	Engine    manualEngine
	Scorer    tierLabeller
	Sonarr    ManualSonarrClient
	Radarr    ManualRadarrClient
	SonarrLib ResolveSonarrClient
	RadarrLib ResolveRadarrClient
	Providers []provider.Provider
}

LiveState holds the runtime state needed for a manual search pass. Sonarr/Radarr are the narrow by-ID surfaces manual downloads use; SonarrLib/RadarrLib are the library-listing surfaces the resolve endpoint uses (all nil when the corresponding arr is not configured).

type ManualRadarrClient added in v0.1.106

type ManualRadarrClient interface {
	MovieByID(ctx context.Context, movieID int) (arrapi.Movie, error)
	RescanMovie(ctx context.Context, movieID int) error
}

ManualRadarrClient is the Radarr surface manual downloads use.

type ManualSearchResponse

type ManualSearchResponse struct {
	Results []SearchResult `json:"results"`
}

ManualSearchResponse is the typed response from RunSearch. It deliberately carries no lock state: manual locks are invisible infrastructure ("a manual pick is never overwritten"), not a user-facing concept, so the popup has nothing to display about them.

func RunSearch

func RunSearch(ctx context.Context, deps *SearchDeps, ls *LiveState,
	req *subflux.SearchRequest, lang string, mediaType subflux.MediaType, filePath string,
) ManualSearchResponse

RunSearch executes the manual search against all providers and returns the JSON-ready response payload.

type ManualSonarrClient added in v0.1.106

type ManualSonarrClient interface {
	SeriesByID(ctx context.Context, seriesID int) (arrapi.Series, error)
	RescanSeries(ctx context.Context, seriesID int) error
}

ManualSonarrClient is the Sonarr surface manual downloads use: series lookup (for media-ID and title resolution) and a post-download rescan.

type ResolveCandidate added in v0.1.148

type ResolveCandidate struct {
	MediaType subflux.MediaType `json:"media_type"`
	Title     string            `json:"title"`
	MediaID   int               `json:"media_id"`
	Year      int               `json:"year,omitempty"`
}

ResolveCandidate is one ambiguity candidate; Year disambiguates equal titles.

type ResolveQueryParams added in v0.1.148

type ResolveQueryParams struct {
	Season  *int
	Episode *int
	Title   string
	Imdb    string
	Type    string // "", "series", or "movie"
	Tmdb    int
}

ResolveQueryParams is the validated query surface of the resolve endpoint. Season and Episode carry PRESENCE, not just value: nil means the parameter was absent, while a non-nil zero is an explicit season=0 (specials) or episode=0 — an explicit zero narrows the expansion and marks the query episodic exactly like any other supplied value.

type ResolveRadarrClient added in v0.1.148

type ResolveRadarrClient interface {
	Movies(ctx context.Context) ([]arrapi.Movie, error)
}

ResolveRadarrClient is the Radarr surface query resolution uses.

type ResolveResponse added in v0.1.148

type ResolveResponse struct {
	Items      []ResolvedItem     `json:"items,omitempty"`
	Candidates []ResolveCandidate `json:"candidates,omitempty"`
	Resolved   bool               `json:"resolved"`
}

ResolveResponse is the typed result of GET /api/search/resolve. Exactly one of the following holds: Resolved with Items (success), Candidates (ambiguous — the client disambiguates), or all empty (no match).

func ResolveQuery added in v0.1.148

func ResolveQuery(ctx context.Context, ls *LiveState, p *ResolveQueryParams) (ResolveResponse, error)

ResolveQuery maps the validated query onto arr media items. With an explicit type only that arm runs (an unconfigured arr is then an error); with no type the deleted local resolver's fallback is preserved: series first, movies only when the series arm found nothing and no season/episode narrowing was requested — EXCEPT when a TMDB id was supplied, which is a movie-only criterion and therefore resolves the movie identity first (a supplied stable ID always outranks a title match). A conflict short-circuits; an arm failure surfaces only when the healthy arm could not satisfy the query (partial-arr rule).

type ResolveSearchIDs added in v0.1.148

type ResolveSearchIDs struct {
	Imdb string `json:"imdb,omitempty"`
	Tvdb int    `json:"tvdb,omitempty"`
	Tmdb int    `json:"tmdb,omitempty"`
}

ResolveSearchIDs carries the stable identifiers of a resolved item for the follow-up search call.

type ResolveSonarrClient added in v0.1.148

type ResolveSonarrClient interface {
	Series(ctx context.Context) ([]arrapi.Series, error)
	Episodes(ctx context.Context, seriesID int) ([]arrapi.Episode, error)
}

ResolveSonarrClient is the Sonarr surface query resolution uses: the full series list for matching and per-series episodes for expansion.

type ResolvedItem added in v0.1.148

type ResolvedItem struct {
	MediaType subflux.MediaType `json:"media_type"`
	Title     string            `json:"title"`
	SearchIDs ResolveSearchIDs  `json:"search_ids"`
	MediaID   int               `json:"media_id"`
	Year      int               `json:"year,omitempty"`
	Season    int               `json:"season,omitempty"`
	Episode   int               `json:"episode,omitempty"`
}

ResolvedItem is one searchable media item: an episode of the matched series (file-bearing only) or the matched movie. MediaID is the arr ID (Sonarr series ID / Radarr movie ID) — the same identity the search and download endpoints consume.

type SearchDeps

type SearchDeps struct {
	DB       Store
	Activity ActivityTracker
	Alerts   WarnRecorder
	Events   EventPublisher
}

SearchDeps holds the narrow dependencies for manual search execution.

type SearchResult

type SearchResult struct {
	Matches     map[string]int     `json:"matches,omitempty"`
	Provider    subflux.ProviderID `json:"provider"`
	Language    string             `json:"language"`
	ReleaseName string             `json:"release_name"`
	MatchedBy   string             `json:"matched_by"`
	SubtitleID  string             `json:"subtitle_id"`
	// Tier is the score's quality-tier label, computed server-side by the
	// scorer (same table as /api/score): the remote CLI renders it and has
	// no scorer of its own.
	Tier       subflux.ScoreTier `json:"tier"`
	Score      int               `json:"score"`
	HearingImp bool              `json:"hearing_impaired"`
	Forced     bool              `json:"forced"`
	OnDisk     bool              `json:"on_disk"`
}

SearchResult is a single result returned by the manual search API.

func BuildSearchResults

func BuildSearchResults(scored []subflux.ScoredResult, refs []subflux.DownloadedRef, sc tierLabeller) []SearchResult

BuildSearchResults converts scored results to API response format. sc supplies the server-computed tier label per score (a nil scorer — only possible before the first successful wire — leaves tiers empty).

type Store added in v0.4.0

type Store interface {
	DownloadedRefs(ctx context.Context, mediaType subflux.MediaType, mediaID, language string) ([]subflux.DownloadedRef, error)
	ClearManualLock(ctx context.Context, key subflux.ManualLockKey) error
}

Store is the two rows a manual search touches: what is already on disk for the language (the popup's "downloaded" markers) and releasing a lock. 2 of the 36 methods the store offers. The lock key's empty variant means "all variants of the language" (see subflux.ManualLockKey).

type WarnRecorder added in v0.4.0

type WarnRecorder interface {
	RecordWarn(source, msg string)
}

WarnRecorder records an actionable warning for the UI's alert list. activity.AlertLog satisfies it structurally.

Jump to

Keyboard shortcuts

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