Invidious: interface, media paths and operational responsibility
Reading Invidious search code: URL detection is a dispatch gate, not the sanitizer
Follow Query initialization, filter precedence and URL normalization, with sixteen explicitly independent offline teaching-model cases.
What you will learn
- Initialization decides what kind of search exists
- The URL gate answers a narrow routing question
- Follow the next call before drawing a security conclusion
Before you start
- Basic HTTP and container concepts
- Ability to distinguish application state from media traffic
Explain the dependency and trust boundaries, prepare a verifiable trial and interpret source/model evidence without overclaiming.
Key takeaways
- Mode and filter precedence are part of the query semantics.
- Passing a URL heuristic is not the same as validating or playing a video.
- The route invokes a separate sanitizer after classification.
Initialization decides what kind of search exists
Search::Query reads q and, for regular searches, can fall back to search_query. It strips surrounding whitespace and removes a leading backslash while setting a smart-feature inhibitor. It then parses page information and handles regular, channel, subscription and playlist modes differently. Do not infer the complete behavior from a single regular-expression match near the end of the file.
The inspected branch gives the sp parameter a YouTube-compatible parsing path. Otherwise it reads Invidious URL filters and only considers legacy query-string filters when the parsed filters remain at defaults and the text has the relevant syntax. The upstream specs contain precedence examples; they were read as source evidence, not executed. A modern filter can keep a legacy-looking token as ordinary query text.
The URL gate answers a narrow routing question
Query.url? rejects inhibited smart features, non-regular modes and nondefault filters before applying a YouTube-domain prefix heuristic. In the independent JavaScript model, a normal watch URL, a short link and a scheme-less path pass; an uppercase spelling, missing slash, leading text, nondefault filters or a leading backslash do not. Sixteen model cases passed with no network activity.
The model also accepts the YouTube root URL with a trailing slash. That result means only that this narrow gate classifies the string as URL-like; it does not prove a valid video, a successful redirect or a playable asset. The model uses explicit mode/filter flags and ASCII fixtures. It does not execute Crystal, parse every filter or establish equivalence across Unicode and URI edge cases.
Follow the next call before drawing a security conclusion
The search route calls UrlSanitizer.process before redirecting a URL-like query. The sanitizer constructs a new relative URI, filters path components and copies query parameters according to the target path category. Its duplicate-parameter loop takes the last allowed value. These later transformations are separate from the gate and were inspected, not exercised by our model.
A useful extension is a source-language regression suite that verifies the final redirect destination for conflicting parameters, unusual paths and each query mode. That suite is proposed, not shipped or run here. The evidence supports an explanation of control flow and specific model outputs; it does not support announcing a vulnerability, a complete security audit or an end-to-end search test.
Implementation steps
- 1
Read initialization before Query.url?.
- 2
Inspect the route that consumes a positive classification.
- 3
Run the sixteen independent teaching-model cases with their stated limits.
- 4
Design separate Crystal tests for final normalized destinations.
Copy-ready example
{
"modelCases": 16,
"rootUrlWithSlash": true,
"leadingBackslash": false,
"nondefaultFilters": false,
"upstreamCrystalExecuted": false,
"sanitizerExecuted": false,
"playbackVerified": false
}Frequently asked questions
Do the sixteen cases execute the Invidious application?
No. They execute an independent JavaScript teaching model of the inspected gate. Crystal, complete filter parsing, the sanitizer and playback remain unexecuted.
Does the gate accepting a URL prove it is safe or playable?
No. Normalization, routing, upstream availability and actual playback are different stages with different checks.
Sources
- invidious/src/invidious/search/query.crSource checked 2026-09-08
- invidious/spec/invidious/search/query_spec.crSource checked 2026-09-08
- invidious/src/invidious/routes/search.crSource checked 2026-09-08
- invidious/src/invidious/yt_backend/url_sanitizer.crSource checked 2026-09-08