[FEATURE] STRM dead-link refresh scaffolding #21
Description
Summary
Add scaffolding to persist STRM-to-resolved-URL mappings so AniBridge can later refresh expired provider URLs without changing current runtime behavior.
Further Information
See the spec notes for context: specs/004-strm-file-support/refresh-boilerplate.md
Problem
STRM files currently store resolved provider URLs that can expire (tokens/TTL/geo constraints). When they expire, playback fails until a new STRM is generated. There is no persisted mapping to support a future refresh endpoint or automation.
Proposal (Scaffolding Only)
Introduce a new SQLModel table (not yet wired into runtime or migrations) to store:
strm_pathresolved_urlresolved_at- Episode identity:
slug,season,episode,language,site - Optional:
provider_used
Suggested model (do NOT wire into app/db/models.py yet unless also handling migrations/runtime table creation):
StrmUrlMappingwith a dedicatedidPKresolved_atdefaults to UTC now
Suggested Future Write Points (Not Implemented)
- When STRM job finishes writing
.strm, insert/update mapping row forstrm_path+ episode identity. - If a future refresh endpoint exists, re-resolve URL, rewrite
.strm, update mapping row.
Potential Future Triggers (Not Implemented)
There are lots of possible triggers for refresh:
- A Web UI with a per-episode/per-anime “Refresh STRM” button.
- A CLI command that refreshes a specific episode/season/series.
- An HTTP API endpoint that can be called by automation.
- Some “refresh all” or “refresh stale” action tied to UI or CLI.
Suggested Future “Dead Link” Detection (Not Implemented)
- Simple: HEAD/GET and mark dead on 4xx/5xx/timeouts.
- Better: retry window; treat 403/451/429 differently.
- Consider proxy/VPN: failures may be geo/rate-limit, not expiry.
Notes (Sonarr Sorting Context)
- Sonarr ranks releases using size/quality/profiles, not STRM semantics.
- STRM entries currently use the same enclosure length heuristic as non-STRM to avoid rejection by minimum size rules.
- Titles keep quality tags and add
[STRM].
Acceptance Criteria
- Document the proposed
StrmUrlMappingtable and fields in the relevant spec or developer docs. - No runtime behavior changes; no migrations or DB writes added yet.
SQLite / Migrations Reality Check
Right now we have no DB migrations. The database is effectively ephemeral and gets deleted in /docker/entrypoint.sh. Adding a new table means we need a migration story, but SQLite is painful here:
- There’s no “easy” migrations tool out of the box for SQLModel + FastAPI + SQLite (no Flyway-like experience; no Drizzle/Prisma style tooling).
- An approach could be “Add Alembic migrations for database schema management with SQLModel” (like PR Add Alembic migrations for database schema management with SQLModel #14 ) but it’s been open for 2+ months and the current state doesn’t work.
- Django has
sqlmigrate, but we’re not on Django. - There’s a third-party tool: https://github.com/simonw/sqlite-migrate — but it’s “early alpha” with no commits in ~2 years, so it may not be safe.
Basically: if we introduce a new table for STRM refresh mapping, we also need to solve migrations (or at least decide how to handle schema changes) or this will be brittle.
Out of Scope (for this issue)
- Implementing refresh endpoints/CLI
- Automatic refresh on playback
- Live dead-link probing or retries
- Sonarr behavior changes