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
- Variables
- func Test(ctx context.Context, f *providercalls.Funnel, e provider.Entry, ...) (ok bool, message string, err error)
- type Aligner
- type Annotated
- type Answer
- type Config
- type Deps
- type Engine
- func (e *Engine) Candidates(ctx context.Context, owner int64, inst statedb.InstanceID, target language.Tag) (Results, error)
- func (e *Engine) Download(ctx context.Context, owner int64, h Handle, v language.Variant, ...) (status.Job, error)
- func (e *Engine) Drain(ctx context.Context) error
- func (e *Engine) SearchNow(ctx context.Context, owner int64, inst statedb.InstanceID, idem *status.JobKey) (status.Job, error)
- func (e *Engine) Upload(ctx context.Context, owner int64, inst statedb.InstanceID, f UploadFile, ...) (status.Job, error)
- type Evidence
- type Handle
- type ProviderAnswer
- type Results
- type Starts
- type UploadFile
- type WhyNot
Constants ¶
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 ¶
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") )
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") )
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.
var DownloadCauses = []string{ RefusalFormatUnsupported, RefusalDifferentCut, RefusalDifferentEpisode, causeProviderFailed, causeSettingsChanged, causeMediaRootUnavailable, causeOutsideRoot, causeWriteFailed, }
DownloadCauses is every cause a Download job ends with, in its wire spelling.
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.
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 ¶
MarshalText is the answer's wire spelling, refusing any other value.
func (*Answer) UnmarshalText ¶
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 ¶
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.
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 ¶
MarshalText is the reason's wire spelling, refusing any other value.
func (*WhyNot) UnmarshalText ¶
UnmarshalText reads a reason's wire spelling and refuses every other one.
Source Files
¶
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. |