search

package
v0.10.0-dev.74 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: 39 Imported by: 0

Documentation

Overview

Package search is subflux's search engine: it plans each run of C4's work queue, asks the enabled providers through the call funnel, checks and ranks their candidates, fetches the best through timing-sync's aligner and delivers one subtitle per wanted (item, target, variant). Its settings are the search section here and the providers section, provider.ParseConfigs; both parsers run every check a user's values can fail, so New, after a clean parse, fails only on a registry fault.

Index

Constants

View Source
const (
	RefusalDifferentCut      = "different_cut"
	RefusalFormatUnsupported = "format_unsupported"
	// RefusalDifferentEpisode: Align refused a pack member chosen by its
	// number, so the guard measured another episode (8.11).
	RefusalDifferentEpisode = "different_episode"
	// RefusalEpisodeCount and RefusalOrderUndetermined: an automatic run
	// refused a pack by 8.11's count rule, or for an order no title or
	// reference settles.
	RefusalEpisodeCount      = "episode_count"
	RefusalOrderUndetermined = "order_undetermined"
	// RefusalFetchGone: a NotFound or Permanent fetch failure.
	RefusalFetchGone = "fetch_gone"
	// RefusalFetchFailed: a Transient, RateLimited or Auth fetch failure,
	// or an admitted attempt that ended before its payload was judged.
	RefusalFetchFailed = "fetch_failed"
	// RefusalWriteFailed: the writer refused the attempt it was to deliver
	// (mediawrite and statedb write it).
	RefusalWriteFailed = "write_failed"
)

The attempt-row spellings (CR-SE-10). Each holds its candidate in the attempt memory but RefusalFetchFailed and RefusalWriteFailed.

Variables

View Source
var (
	// ErrInstanceUnknown is an instance the store does not hold, or one
	// with no item.
	ErrInstanceUnknown = errors.New("search: instance unknown")
	// ErrTargetUnconfigured is a tag none of the instance's items targets.
	ErrTargetUnconfigured = errors.New("search: target not configured for this item")
)
View Source
var (
	// ErrSearchCapacity is a search whose handles would pass maxHandles.
	ErrSearchCapacity = errors.New("search: too many search results held")
	// ErrCandidateUnknown is a handle unknown, expired, another owner's or
	// already taken.
	ErrCandidateUnknown = errors.New("search: candidate unknown")
)
View Source
var Codes = slices.Concat([]struct {
	Err  error
	Code string
}{
	{ErrVariantUnserved, "variant_unserved"},
	{ErrCandidateUnknown, "candidate_unknown"},
	{ErrSearchCapacity, "search_capacity"},
	{ErrInstanceUnknown, "instance_unknown"},
	{ErrTargetUnconfigured, "target_unconfigured"},
}, status.StartCodes)

Codes pairs every sentinel Candidates, Download and SearchNow return with the code api answers for it: search's own, then status's StartCodes, the only status errors Keyed and Begin return.

View Source
var DownloadCauses = []string{
	RefusalFormatUnsupported, RefusalDifferentCut, RefusalDifferentEpisode, causeProviderFailed,
	causeSettingsChanged, causeMediaRootUnavailable, causeOutsideRoot, causeWriteFailed,
}

DownloadCauses is every cause a Download job ends with, in its wire spelling.

View Source
var ErrVariantUnserved = errors.New("search: variant not served by this candidate")

ErrVariantUnserved is a variant the handle's target does not list or its candidate's flags do not serve.

View Source
var Schema = formschema.Schema{Fields: []formschema.Field{
	{
		Key: keyMinFit, Label: "Minimum fit", Kind: formschema.Enum, Enum: fitChoices, Default: "other",
		Help: "The least a subtitle must match the video's release to be downloaded automatically: other, same source, same release or exact.",
	},
	{
		Key: keyUpgradeWindow, Label: "Upgrade window (days)", Kind: formschema.Int, Min: 0, Max: maxUpgradeWindowDays, Default: "7",
		Help: "For how many days after a download a better fitting subtitle replaces it. 0 turns these upgrades off.",
	},
	{
		Key: keyScanDelay, Label: "Scan delay", Kind: formschema.DurationMs,
		Min: minScanDelay.Milliseconds(), Max: maxScanDelay.Milliseconds(), Default: "5s",
		Help: "The least time between two automatic searches on one provider.",
	},
}}

Schema is the section's flat fields; min_fit_by_target, a mapping from target tag to fit, is walked and marked plain by ParseConfig itself.

Functions

func Test

func Test(ctx context.Context, f *providercalls.Funnel, e provider.Entry, cfg provider.Config) (ok bool, message string, err error)

Test checks cfg's credential for e's provider through f.Probe, never touching a live engine: ok with a message for the user, err only for subflux's own failure, such as a credential record or Verify error.

Types

type Aligner

type Aligner interface {
	Align(ctx context.Context, inst statedb.InstanceID, payload []byte, tag language.Tag, d timing.Decision) (syncsched.Aligned, error)
}

Aligner is the one timing-sync operation the engine consumes; *syncsched.Aligner implements it, and the engine tests script it (searchtest.Aligner).

type Annotated

type Annotated struct {
	Handle            Handle
	Provider          provider.ProviderID
	Release           string
	Covers            []media.Numbering
	Lang              language.Tag
	Grade             language.Grade
	Facts             rank.Facts
	Flags             language.Flags
	MatchedBy         rank.MatchedBy
	Fit               rank.Fit
	WhyNot            WhyNot
	Automatic         bool
	MachineTranslated bool
}

Annotated is one candidate of a manual search: Automatic when automation would take it for one of the target's variants, else WhyNot says why not.

type Answer

type Answer uint8

Answer is how a provider answered a manual search.

const (
	Answered Answer = iota
	// Paused: a rate pause, a health cooldown or an auth cooldown.
	Paused
	// Disabled: its credential is disabled.
	Disabled
	Failed
	// NotAsked: it lacks what it searches by, or a tag for the target.
	NotAsked
)

The answers.

func (Answer) MarshalText

func (a Answer) MarshalText() ([]byte, error)

MarshalText is the answer's wire spelling, refusing any other value.

func (*Answer) UnmarshalText

func (a *Answer) UnmarshalText(b []byte) error

UnmarshalText reads an answer's wire spelling and refuses every other one.

type Config

type Config struct {
	// TargetMinFit replaces MinFit for its target.
	TargetMinFit map[language.Tag]rank.Fit
	// ScanDelay spaces each provider's Automatic calls.
	ScanDelay time.Duration
	// UpgradeWindowDays is how long after a delivery a better fit replaces
	// it; 0 turns fit upgrades off.
	UpgradeWindowDays int
	MinFit            rank.Fit
}

Config is the search section. TargetMinFit keys are configured target tags; neither level is rank.Conflict.

func ParseConfig

func ParseConfig(n *yaml.Node, p language.Policy) (Config, []formschema.FieldError)

ParseConfig reads the search section, n being its node or nil when absent, against the parsed languages policy p, reporting every refusal at once at its absolute path: Schema's, and in min_fit_by_target a key that is no configured target, a key set twice, or a value that is no fit or is conflict. Every scalar it reads is marked plain: the section holds no secret.

type Deps

type Deps struct {
	Starts   *Starts
	Store    *statedb.Store
	Funnel   *providercalls.Funnel
	Writer   *mediawrite.Writer
	Prober   *embedded.Prober
	Aligner  Aligner
	Evidence Evidence
	Status   *status.Store
	// Logger, nil for slog.Default().
	Logger *slog.Logger
}

Deps are the engine's collaborators; every field but Logger is required.

type Engine

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

Engine is one configuration's search engine.

func New

func New(deps Deps, entries []provider.Entry, cfgs []provider.Config, p language.Policy, cfg Config, tc timing.Config) (*Engine, error)

New checks every entry's Summary and repeats ParseConfig's and provider.ParseConfigs' checks, then binds each enabled provider to deps.Funnel, its Automatic calls spaced by cfg.ScanDelay, and registers each enabled entry's Data with a report reconciling status.ProviderDataAlert of that provider. A refusal binds and registers nothing.

func (*Engine) Candidates

func (e *Engine) Candidates(ctx context.Context, owner int64, inst statedb.InstanceID, target language.Tag) (Results, error)

Candidates is a manual search of one configured target of inst: every enabled provider asked Interactive with the target's ManualQuery tags, 8.3's language, identity and coverage checks, at most maxCandidates in rank order, each under a fresh handle owner may download. Its refusals are ErrInstanceUnknown, ErrTargetUnconfigured and ErrSearchCapacity, the last also when the answer would pass the bound at insertion.

func (*Engine) Download added in v0.6.6

func (e *Engine) Download(ctx context.Context, owner int64, h Handle, v language.Variant, idem *status.JobKey) (status.Job, error)

Download starts a Download job fetching h's candidate for variant. With idem set, under Starts' lock on (owner, idem), the job started under that key is returned and h left alone; otherwise h is taken, and given back when the variant is not served or the job cannot be recorded. The job runs under the engine, never ctx, in the Item group under the instance's gate, and on a drained engine it ends Interrupted at once.

func (*Engine) Drain

func (e *Engine) Drain(ctx context.Context) error

Drain is the one drainer of the work queue and owns every goroutine the engine starts until ctx ends; it then waits for them, releases the engine's bindings and returns ctx's error. A second call returns an error at once.

func (*Engine) SearchNow

func (e *Engine) SearchNow(ctx context.Context, owner int64, inst statedb.InstanceID, idem *status.JobKey) (status.Job, error)

SearchNow starts an ItemScan job settled by the first Item run of inst starting after it: Succeeded, Partial with the skips' reasons in Cause, Failed on a run error or instance_unknown. With idem, under Starts' lock, the job started under that key is returned whatever inst's state; else an instance not held or itemless is ErrInstanceUnknown before any job. Cancelling settles it Cancelled and cancels a run no other job waits on; on a drained engine the work is enqueued and the job settles Interrupted.

func (*Engine) Upload

func (e *Engine) Upload(ctx context.Context, owner int64, inst statedb.InstanceID, f UploadFile, idem *status.JobKey) (status.Job, error)

Upload starts a Download job delivering f for inst, numbered, locked and Uploaded with no provider (8.7). With idem set, under Starts' lock on (owner, idem), the job started under that key is returned. Before any job it refuses ErrInstanceUnknown for an unknown inst or an Item not in it, ErrTargetUnconfigured and ErrVariantUnserved for a pair the Item's coverage does not list. The job ends as a Download job does, never provider_failed, and a refused file writes nothing.

type Evidence

type Evidence interface {
	Evidence(ctx context.Context, src media.SourceID, root mediasource.NativeRef) (mediasource.SeriesEvidence, bool, error)
}

Evidence is a series root's bound reading as its source's join stored it; *seriesorder.Service implements it. False is no reading.

type Handle

type Handle string

Handle names one candidate of one manual search, for its owner only.

type ProviderAnswer

type ProviderAnswer struct {
	Until    time.Time
	Provider provider.ProviderID
	Cause    string
	Count    int
	Answer   Answer
}

ProviderAnswer is one enabled provider's outcome: Count when Answered (a Failed one keeps the candidates it read before failing), Until when Paused, Cause, one redacted line, when Failed or NotAsked.

type Results

type Results struct {
	Candidates []Annotated
	Providers  []ProviderAnswer
}

Results is Candidates' answer: the candidates in rank order and one answer per enabled provider, so an empty list can say who did not answer.

type Starts

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

Starts is the process-wide download-start coordinator: app makes one and every engine shares it, so a same-key Download resend that crosses an engine swap waits for its original and finds its job.

func NewStarts

func NewStarts() *Starts

NewStarts makes the coordinator app passes every engine.

type UploadFile

type UploadFile struct {
	Bytes   []byte
	Name    string
	Target  language.Tag
	Item    media.Key
	Variant language.Variant
}

UploadFile is a subtitle file or archive a user brings for Item, to serve Target's Variant. Upload keeps Bytes until its job ends, so the caller must not change them.

type WhyNot

type WhyNot uint8

WhyNot is why a candidate is not taken automatically, or why a pair was skipped; None is a candidate automation would take.

const (
	None WhyNot = iota
	NoCandidate
	BelowMinFit
	DifferentCut
	PreRelease
	LanguageManualOnly
	PartialCoverage
	FormatUnsupported
	// IdentityUnconfirmed: a candidate its adapter could not place on the
	// item, or a title-matched movie whose year is unknown on either side.
	IdentityUnconfirmed
	// DifferentEpisode, EpisodeCount and OrderUndetermined: an automatic
	// run within attemptMemory refused the candidate's pack member chosen
	// by number, the pack's count, or its undetermined order (8.11).
	DifferentEpisode
	EpisodeCount
	OrderUndetermined
)

The reasons.

func (WhyNot) MarshalText

func (w WhyNot) MarshalText() ([]byte, error)

MarshalText is the reason's wire spelling, refusing any other value.

func (*WhyNot) UnmarshalText

func (w *WhyNot) UnmarshalText(b []byte) error

UnmarshalText reads a reason's wire spelling and refuses every other one.

Directories

Path Synopsis
Package searchtest is test support for the search engine: a scripted timing-sync aligner the engine tests pass as search.Deps.Aligner.
Package searchtest is test support for the search engine: a scripted timing-sync aligner the engine tests pass as search.Deps.Aligner.

Jump to

Keyboard shortcuts

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