jellytau/docs/specs/jellyfin-server-version-compatibility.md

Spec: Jellyfin server version compatibility

Status: Partially implemented Requirements: UR-085 → IR-035, JA-037, DR-279 … DR-288 (DR-287 and DR-288 were added once research established what actually breaks).

What is left

Everything below shipped on 2026-09-08 except:

• DR-283 is partially done. supports_manifest_container_direct_play and image_endpoint_upscales are resolved and tested, but nothing consumes them yet — and that may be correct rather than an omission: on 12.0 the server enforces both (it refuses direct play for manifest containers itself, and simply returns the smaller image), so the client learns the answer from the PlaybackInfo response without needing to predict it. Decide whether to consume them or delete them once a running 12.x server can be observed. Do not leave them unread indefinitely: an unconsumed flag is a branch waiting to be wired wrongly.
• honours_directplay_audio_codec is unresolved for 12.x. A source-level diff could not establish whether the behaviour changed. The override stays on for both generations. Flip it only against a running 12.x server — keeping it costs an unnecessary transcode, removing it wrongly costs silent playback.
• The user-scoped route migration (DR-282) was not performed. It is not needed: the whole family still works on 12.0. Both route shapes are built and tested, so switching is a one-line change whenever it is wanted.
• Nothing was tested against a real server of either generation. Every cross-generation assertion runs against a mock built from a source-level diff.

What research established

The framing this spec was written under was wrong in a way worth recording.

Jellyfin 11.0 does not exist and never did. With 12.0 the project dropped the leading 10 from its version scheme: what would have been 10.12.0 shipped as 12.0, and the server reports Version: "12.0.0". So "two generations" means 10.11.x and 12.x, one release-branch step apart, not two majors. 12.0 became stable on 2026-09-08 — the same day this work was done — so real-world 12.x installs are currently near zero and rising.

The delta is far smaller than this spec assumed, and almost none of it is a branch:

Finding	Consequence
X-Emby-Authorization and the api_key query parameter are disabled by default in 12.0, including on upgraded servers via a migration	The one genuinely breaking change. Fixed by a rename — Authorization + ApiKey are ungated on both — not a flag (DR-287)
GetItems now defaults recursive to true for a library parent with IncludeItemTypes	The same request returns a different result set. Fixed by stating Recursive explicitly (DR-288)
The /Users/{userId}/… family survives in 12.0	No migration needed. Six routes were removed in total; none are ones this client calls
BaseItemDto is purely additive; DeviceProfile, PlaybackInfo, PublicSystemInfo byte-identical	No DTO work at all
Manifest-container sources are no longer direct-play eligible; image endpoints no longer upscale	The only two genuine either/or differences — and both are server-enforced

The lesson for the layer rule: most of a version delta is fixed by writing the request correctly for both generations, not by branching on the version. Flags are for genuine either/or behaviour, because each one is a silent branch that outlives the reason it was added.

The full report, with a source URL per claim, is jellyfin-12-api-delta.md. UX spec: n/a for the bulk of it. One new user-visible state — "this server is a version JellyTau does not know" — needs a home in the connect flow; see DR-286. Supersedes / revises: nothing. Touches backend-owned-stream-selection.md at the StreamSelection boundary and should land after it where they overlap, but neither blocks the other.

Destination on completion: 01-rust-backend.md — a new "Server capability negotiation" section beside "Domain Vocabulary Owned by Rust", which is where the litmus test this feature exists to satisfy already lives; and a paragraph in 07-connectivity.md noting that the /System/Info/Public probe now has a second consumer. The durable half is the capability model and why it is flags rather than version comparisons; phases, ticket boundaries and acceptance criteria are disposable.

Summary

Let one build of JellyTau talk to more than one generation of Jellyfin server. The app already asks the server what version it is, at connect, before login — and then throws the answer away. Instead it resolves that version into a ServerCapabilities value once per connection, and every decision that depends on the server generation reads a named flag from it.

Nothing about the app changes for a user whose server matches what the code targets today. What changes is that the release which follows the server forward stops silently abandoning everyone who has not upgraded, and that a server the app does not recognise produces a sentence rather than a cascade of parse failures.

Motivation

The server and its clients are upgraded by different people on different schedules. A family server can sit a major version behind for a year while the phone updates itself weekly. Today the code has no way to express that.

1. One server generation is hard-coded, unconditionally. The current target is 10.11.5 and it is written into the code as fact, not as a branch — device_profile.rs:336, online.rs:966, online.rs:2271, and most pointedly online.rs:4667, which is documented as "the override that exists because Jellyfin 10.11.5 ignores…". Every one of those is correct for one server and wrong for another, and there is nowhere to say which.

2. Endpoints are 57 inline string literals, not a route table. They are built with format! at the point of use, query string and all — online.rs:1957 is representative. Supporting a second route shape without a table means 57 conditionals rather than one.

3. The legacy user-scoped routes are load-bearing. Roughly twelve sites use /Users/{uid}/Items, /Users/{uid}/Items/Resume, /Users/{uid}/Views, /Users/{uid}/FavoriteItems/{id} and /Users/{uid}/PlayedItems/{id}. These are precisely the routes upstream has been moving away from in favour of /Items?userId=. Whichever release drops them takes the app with it.

4. There is no way to test any of this. src-tauri/ contains no HTTP mocking at all — no wiremock, no mockito, no httpmock. Every test of the online repository asserts on a constructed URL string; not one exercises a response. So there is currently no mechanism by which "works against both generations" could be demonstrated, and this is the single largest item in the work. It is also worth doing on its own merits: a 4,797-line adapter with no response-level tests is under-covered regardless of how many server versions it supports.

5. A Jellyfin route is being built in the frontend. imageCache.ts:64 constructs ${serverUrl}/Items/${itemId}/Images/${imageType} in Svelte. By the litmus test in this project's own spec template — would this have to change if Jellyfin changed its API? — that is domain logic in the presentation layer. It is the only one left, and this is the feature that makes it actively wrong rather than merely misplaced.

What this is not. It is not multi-server support. Profiles are users on one server (profiles/store.rs), and that does not change here. "Both versions at the same time" means one binary that adapts to whichever server it is pointed at, not two servers connected at once.

Layer assignment

Logic / responsibility	Layer	Why it belongs there
Server version string → capability flags	Rust	Domain vocabulary in the strictest sense: it changes when and only when Jellyfin's API changes. The template's litmus test answers this in one word.
Which route shape to use for a given call	Rust	Wire format. The frontend must not know that a route exists, let alone that there are two.
Image URL construction (moving out of imageCache.ts)	Rust	A Jellyfin route, therefore it changes with Jellyfin's API. Currently in the frontend; this feature is what turns that from untidy into broken.
Device-profile / PlaybackInfo override selection	Rust	Already Rust and staying there. Only the gating is new — the overrides stop being unconditional.
Whether a cache written against one server generation is still valid	Rust	A storage invariant. The frontend cannot see the server version and must not learn to.
Deciding a server is too old / too new to use	Rust	A domain judgement about an API, expressed as an opaque state on the wire.
How the "unsupported server" state is worded and where it appears in the connect flow	Frontend	Pure presentation. It changes if the UI is redesigned and not otherwise. The frontend renders an opaque state; it never compares a version.

Borderline: none. The one row that could be argued is the last, and it splits cleanly — Rust decides that the server is unsupported, the frontend decides what that looks like. The frontend never receives a version number to reason about, for the same reason it never receives an item-type list.

Design

ServerCapabilities

Resolved once, at connect, from a version the app already has. AuthManager::connect_to_server (auth/mod.rs:147) already parses PublicSystemInfo.version and returns it in ServerInfo, and the servers table already has a version TEXT column (schema.rs:42) that is written on insert. Detection therefore costs nothing new; the value is simply discarded today.

The resolved value hangs on OnlineRepository and is passed to the route table. OfflineRepository has no server and no capabilities; HybridRepository delegates. No MediaRepository method signature changes, so no caller above repository/ is touched.

Flags, not comparisons. Every capability is named for the behaviour it governs — user_scoped_item_routes, honours_directplay_container, playback_info_respects_container — and the version → flags mapping lives in exactly one function. A version < 11 scattered through call sites is the same mistake as a taxonomy in the frontend: it re-derives a domain fact at the point of use, and it is unreadable at the second occurrence. Flags also survive the case the comparison cannot express, which is a backport.

Route table

The ~30 distinct endpoints move into repository/endpoints.rs, each a function taking &ServerCapabilities and returning the path. Everything in online.rs already funnels through three helpers that take endpoint: &str — get_json, post_json, post_json_response (online.rs:315-459) — so the interception point exists and there are 32 call sites, not 57 literals.

This step is behaviour-preserving on its own and lands before anything depends on it.

Unknown versions

An unrecognised version resolves to the newest known capability set and is recorded, not rejected — the app should keep working against a server that is merely newer than the release. Rejection is reserved for a version below the floor, where the failure is certain rather than likely. Either way the outcome crosses the IPC boundary as an opaque state, never a version number.

Cache validity

Cached rows carry no record of which server generation wrote them. The server's version goes on the cache alongside the existing synced_at, and a change invalidates by clearing synced_at — the same move MIGRATION_018 and migration 025 already make, and for the same reason: the association was never stored, so existing rows cannot be repaired locally and must be re-fetched.

Out of scope

• Multi-server support. One server per install, as today.
• Emby, or any non-Jellyfin server. The capability model would carry it; the DTO layer would not, and nothing here should be read as a step toward it.
• The Windows/Linux/Android split. Capabilities describe the server, never the client platform. Platform differences stay in device_profile.rs.
• Raising coverage of the whole online adapter. The mock-server harness makes that possible and the version-sensitive paths get tests; a general backfill is separate work.

Acceptance criteria

• The app connects, browses, plays and reports against both target server generations, from one build, with no user-visible configuration.
• The repository suite runs against both generations' fixtures and passes.
• No format! endpoint literal remains in online.rs.
• No version comparison exists outside the single version → capabilities function.
• A server below the supported floor produces one legible message; a server newer than the release still works.
• bun run check and bun run test pass.
• cargo fmt clean, cargo clippy --all-targets -D warnings clean, bun run test:rust passes.
• bun run check:boundary passes — and note it will not catch the imageCache.ts route, which is why DR-285 is a ticket rather than a tripwire.
• New requirement-implementing code carries // TRACES: comments; bun run traces:validate passes and coverage does not fall.
• bindings.ts regenerated if Rust types changed.

Testing

The harness is the feature's precondition, not its afterthought.

Rust. Add a mock HTTP server (wiremock — a project dependency, so no CI image change; see the toolchain rule in CLAUDE.md) plus one recorded fixture set per server generation. The repository suite becomes parameterised over generations. What must be covered: route selection per capability; the device-profile overrides firing on the generation they were written for and not on the other; cache invalidation across a version change; an unknown version resolving forward rather than failing.

Frontend. imageCache.ts loses its URL construction, so its tests assert it calls the command rather than that it builds a string.

repository/online_integration_test.rs has been deleted (2026-09-08). It was never declared in repository/mod.rs and referenced a crate::api::jellyfin module that does not exist, so it had never compiled. It is worth knowing why it was not merely dead but harmful: its mock reimplemented the URL builders and then asserted against itself, and online.rs carries a comment recording that this exact arrangement once shipped a /Videos/{id}/download endpoint that 404s on real servers while the mock happily tested the correct one — silently breaking every movie and TV download. Its own test_image_url_basic asserted api_key= appears in image URLs while the mock beside it documented the opposite.

That is the anti-pattern DR-281 exists to replace: assert against a response from a mock server, never against a mock that re-derives the thing under test.

TRACES

Piece	Suggested tag
ServerCapabilities + version resolution	UR-085 | IR-035, DR-280 | UT-xxx
repository/endpoints.rs	UR-085 | DR-279
Route selection for user-scoped endpoints	UR-085 | JA-037, DR-282
Capability-gated profile overrides	UR-085 | DR-283
Cache generation stamp + invalidation	UR-085 | DR-284
Image URL command	UR-012, UR-085 | DR-285
Unsupported-server state	UR-085 | DR-286

Notes for the implementer

• The concrete API delta is not in this spec, deliberately. No route, field or behaviour difference between the two generations is asserted here, because none has been verified against an upstream changelog. The first ticket exists to establish it. Do not let a plausible-sounding difference enter the code without a citation — a wrong capability flag is worse than none, since it fires silently on the generation it was not tested against.
• The route table and the capability struct are independently useful and independently reviewable. If the feature is cut, cut from the end, not the start.
• A parallel Claude session may be active in this repo — git diff before "repairing" unexpected changes.