Files
silo-server/internal/metadata/nfo/provider_test.go
91e1164090 feat(metadata): local NFO metadata and sidecar artwork (builtin chain provider) (#390)
* feat(metadata): register builtin NFO provider and broaden parsing

Phases A and B of the #216 local-NFO work, implemented test-first.

Registration & hint-first identity (Phase A):
- Migration seeds a reserved kind='builtin' silo.builtin installation
  and an 'nfo' metadata capability (default_enabled=false, priority 1
  for movie/series) with a partial unique index and documented Down.
- In-process builtin provider registry (internal/metadata/builtin.go);
  buildProviders returns the registered provider for builtin rows.
- Guard rails keep the reserved row out of every plugin surface (user
  plugin-settings, installations list, image resolvers, preload,
  auto-update, store Delete, mutation handlers -> 409); silo.builtin is
  a reserved manifest id.
- Startup sync materializes legacy content_level='' chains per level,
  then appends builtin capabilities disabled via
  AppendProviderToAllChains (idempotent); resolveEnabledProvidersBy
  priority now respects default_enabled=false.
- NFO uniqueids seed the trusted-hint machinery via IdentityHintProvider
  with per-mode conflict policy (stored IDs win on scheduled refresh,
  NFO wins on manual refresh, Identify skips NFO); ID-less candidates
  are excluded from provider-priority tie-breaks and nfo never counts
  as corroboration.
- Web chain-editor empty-state gate is now server-derived so builtin
  providers are reachable on plugin-less servers.

Parser breadth & sidecar hardening (Phase B):
- Parser covers the practical Kodi/Jellyfin field set for <movie> and
  <tvshow>: original title, tagline, runtime, dates, content rating,
  genres/studios/countries/tags, multi-source ratings with scale
  normalization, cast with roles/order, director/credits. Empty
  collections stay nil so merge early-returns apply.
- findNFO parses candidates and falls through on read/parse failure or
  root-type mismatch, so a stray movie.nfo cannot shadow tvshow.nfo;
  GetMetadata gains the same ContentType guard Search has.
- New FieldReleaseDates lock gates Year/ReleaseDate/First+LastAirDate
  in merge (Go) and the edit-metadata dialog (web), closing the gap
  where a manual refresh re-applied NFO dates over admin corrections.
- Merge-contract tests pin NFO fill semantics, genres whole-list
  first-provider-wins, and NFO edits propagating on manual refresh only.
- Docs: new admin wiki page (supported fields, merge semantics,
  naming-supplies-structure contract), index bullet, sidecar wording
  revision, v1-scope feature-detection note.

Zero behavior change while the provider is disabled (default); pinned
by CI-mode and DB-gated test suites.

Part of #216

AI-use disclosure: implemented with Claude Code (Fable 5) via
spec-driven TDD and agent-assisted implementation.

* feat(metadata): ingest local sidecar artwork and read series-depth NFO

Phases C and D of the #216 local-NFO work, implemented test-first, plus
the mixed-library use-case pins. Together these deliver the headline
case: a series absent from every remote database (e.g. a fitness
library) scans into a fully presented show -> named seasons -> titled
episodes tree from NFO files and sidecar art alone.

Local sidecar artwork through the S3 image cache (Phase C):
- The NFO provider implements ImageProvider: poster/backdrop/logo
  sidecar discovery with a fixed precedence map, symlink/non-regular
  rejection, an 8 MiB cap, and file:// source URLs at rating 0. Generic
  filenames apply only via the sidecar search paths, so a shared
  folder.jpg in a flat multi-movie directory applies to none.
- file:// becomes a live local source scheme: routed into *_source_path
  (never *_path), accepted by every image enqueue gate, attributed as
  provider "local", excluded from cached-path detection.
- The image-cache processor caches local files with lexical-on-logical
  confinement to the library roots, open-handle reads with re-checks,
  the same variant widths as remote art, and stable (7-day) failure
  classification. Keys land under
  local/{contentType}/{contentID}/{hash8}/{imageType}; superseded
  prefixes are cleaned on re-cache and item deletion.
- applyIfBetter gains a local exemption so rating-0 local art can fill
  matched items without being stickily displaced; ImageRequest carries
  additive sidecar path context.

Series depth (Phase D):
- SeasonsRequest/EpisodesRequest carry additive local path context
  (series roots, per-season directories, per-episode file paths),
  derived from naming at match time and reconstructed on refresh.
- season.nfo supplies season name/plot; NFO season numbers are advisory
  (directory-derived number wins with a Warn - naming owns structure).
  <episodedetails> gains aired/runtime/ratings; <basename>.nfo titles
  episodes and <basename>-thumb.ext supplies thumbs; filename SxxEyy
  wins over NFO numbers.
- Episode NFOs work without a season.nfo (provider seasons unioned with
  on-disk seasons); SynthesizeFallbackEpisodes always runs after persist
  so NFO-less episodes keep synthesized rows. Season/episode file:// art
  rides the Phase C pipeline unchanged.
- Migration adds season:1/episode:1 to the builtin NFO capability's
  default_priority (still default_enabled=false).

Mixed sports-library use case (tests only, no product change):
- Pins the classification contract for one library holding movie-shaped
  and show-shaped content (WWE PPV events as movies next to a "WWE
  SmackDown" show, NASCAR/F1/FIFA with partial TVDB/TMDB data): naming
  decides movie-vs-series per file before any provider runs; the NFO
  supplies metadata/identity but never flips type (ContentType guard);
  the per-root Type override is the correction path.
- NFO-driven type classification at scan time is recorded as an explicit
  deferred open question.

Part of #216

AI-use disclosure: implemented with Claude Code (Fable 5) via
spec-driven TDD and agent-assisted implementation.

* docs(metadata): document local NFO metadata architecture

Add a single as-built architecture page
(docs/architecture/local-nfo-metadata.md) for the #216 local-NFO
feature: the builtin registration model, hint-first identity semantics,
the file:// -> S3 artwork pipeline and its deployment constraint, series
depth, the mixed-library classification contract, and known limitations.

This replaces the working implementation plan, the per-phase specs, and
the narrow sidecar-artwork note, which were planning drafts and are left
untracked; admin-facing behavior remains in the wiki.

Part of #216

AI-use disclosure: planned, drafted, and consolidated with Claude Code
(Fable 5) using multi-agent exploration and adversarial review.

* fix(metadata): address PR review findings on NFO builtin provider

Fold in the valid, low-risk fixes surfaced by automated review on #390:

- imagecache: extract validateCacheRequest so CacheBytes (the local
  sidecar season/episode path) enforces the same episode-requires-season
  guard as Cache, preventing distinct episodes' art from colliding under
  one S3 key.
- image_cache_processor: close the sidecar symlink-swap window by
  rejecting the opened handle unless os.SameFile matches the Lstat'd
  file, so a leaf swapped to a symlink can't pull an out-of-root target
  into the public cache.
- plugins: guard the reserved builtin installation row in the store's
  Update, matching Delete, so its version/enabled/capabilities can never
  be rewritten even if a mutation slips past the HTTP layer.
- cmd/silo: bound SyncBuiltinProviderChains with a 30s timeout so a stuck
  DB round-trip fails fast at startup instead of hanging.
- metadata: panic instead of silently no-op'ing on an invalid
  RegisterBuiltinProvider call (init-time programmer error).
- docs: correct the media-folder-and-naming NFO paragraph to state
  season/episode NFOs and sidecar artwork are actively read.

---------

Co-authored-by: Quick104 <31828688+Quick104@users.noreply.github.com>
2026-07-16 17:55:36 -04:00

305 lines
10 KiB
Go

package nfo
import (
"context"
"os"
"path/filepath"
"slices"
"testing"
"github.com/Silo-Server/silo-server/internal/metadata"
)
func TestFindNFO_FilePathFallsBackToDirectoryLevelSidecar(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Blade Runner (1982).mkv")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "movie.nfo"), []byte("<movie><title>Dir</title></movie>"), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
want := filepath.Join(dir, "movie.nfo")
if got, _ := findNFO([]string{filePath}, ""); got != want {
t.Fatalf("findNFO(file path) = %q, want %q", got, want)
}
}
func TestFindNFO_DirectoryPathUsesDirectoryLevelSidecar(t *testing.T) {
t.Parallel()
dir := t.TempDir()
want := filepath.Join(dir, "movie.nfo")
if err := os.WriteFile(want, []byte("<movie><title>Dir</title></movie>"), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
if got, _ := findNFO([]string{dir}, ""); got != want {
t.Fatalf("findNFO(directory path) = %q, want %q", got, want)
}
}
func TestFindNFO_FilePathUsesBasenameMatchedNFO(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Blade Runner (1982).mkv")
want := filepath.Join(dir, "Blade Runner (1982).nfo")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(want, []byte("<movie><title>File</title></movie>"), 0o644); err != nil {
t.Fatalf("WriteFile(file.nfo) error = %v", err)
}
if got, _ := findNFO([]string{filePath}, ""); got != want {
t.Fatalf("findNFO(file path) = %q, want %q", got, want)
}
}
func TestFindNFO_ExtensionlessFilePathUsesDirectoryLevelSidecar(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Blade Runner (1982)")
want := filepath.Join(dir, "movie.nfo")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(want, []byte("<movie><title>Dir</title></movie>"), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
if got, _ := findNFO([]string{filePath}, ""); got != want {
t.Fatalf("findNFO(extensionless file path) = %q, want %q", got, want)
}
}
func TestFindNFO_ExtensionlessFilePathUsesBasenameMatchedNFO(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Blade Runner (1982)")
want := filepath.Join(dir, "Blade Runner (1982).nfo")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(want, []byte("<movie><title>File</title></movie>"), 0o644); err != nil {
t.Fatalf("WriteFile(file.nfo) error = %v", err)
}
if got, _ := findNFO([]string{filePath}, ""); got != want {
t.Fatalf("findNFO(extensionless file path) = %q, want %q", got, want)
}
}
func TestNFOCandidatesForMissingDottedDirectoryPathIncludeDirectoryLevelSidecars(t *testing.T) {
t.Parallel()
path := filepath.Join("/media/shows", "Mr. Robot")
got := nfoCandidatesForPath(path)
wantMovie := filepath.Join(path, "movie.nfo")
wantTV := filepath.Join(path, "tvshow.nfo")
if !slices.Contains(got, wantMovie) {
t.Fatalf("nfoCandidatesForPath(%q) missing %q in %#v", path, wantMovie, got)
}
if !slices.Contains(got, wantTV) {
t.Fatalf("nfoCandidatesForPath(%q) missing %q in %#v", path, wantTV, got)
}
}
// A tvshow.nfo sitting next to a movie file must not inject series data into
// a movie item at top priority: GetMetadata carries the same ContentType
// guard Search has.
func TestGetMetadata_TVShowNFOBesideMovieFileDoesNotInject(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Home Movie (2021).mkv")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
nfoXML := `<tvshow><title>Some Series</title><uniqueid type="tvdb">123</uniqueid></tvshow>`
if err := os.WriteFile(filepath.Join(dir, "tvshow.nfo"), []byte(nfoXML), 0o644); err != nil {
t.Fatalf("WriteFile(tvshow.nfo) error = %v", err)
}
p := NewProvider()
result, err := p.GetMetadata(context.Background(), metadata.MetadataRequest{
ContentType: "movie",
FilePath: filePath,
})
if err != nil {
t.Fatalf("GetMetadata() error = %v", err)
}
if result.HasMetadata {
t.Fatalf("GetMetadata() = %#v, want no metadata (series NFO must not inject into a movie)", result)
}
}
// A stray movie.nfo in a series root must not shadow tvshow.nfo: findNFO
// falls through to the next candidate on type mismatch.
func TestFindNFO_StrayMovieNFOInSeriesRootFallsThroughToTVShow(t *testing.T) {
t.Parallel()
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "movie.nfo"), []byte(`<movie><title>Stray</title></movie>`), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
want := filepath.Join(dir, "tvshow.nfo")
if err := os.WriteFile(want, []byte(`<tvshow><title>The Show</title></tvshow>`), 0o644); err != nil {
t.Fatalf("WriteFile(tvshow.nfo) error = %v", err)
}
got, parsed := findNFO([]string{dir}, "series")
if got != want {
t.Fatalf("findNFO(series root) = %q, want %q", got, want)
}
if parsed == nil || parsed.Title != "The Show" {
t.Fatalf("parsed = %#v, want tvshow content", parsed)
}
}
// A candidate that exists but fails to parse falls through to the next
// candidate instead of masking a valid sidecar.
func TestFindNFO_ParseFailureFallsThroughToNextCandidate(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Blade Runner (1982).mkv")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "movie.nfo"), []byte("not xml at all"), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
want := filepath.Join(dir, "Blade Runner (1982).nfo")
if err := os.WriteFile(want, []byte(`<movie><title>Blade Runner</title></movie>`), 0o644); err != nil {
t.Fatalf("WriteFile(basename nfo) error = %v", err)
}
got, parsed := findNFO([]string{filePath}, "movie")
if got != want {
t.Fatalf("findNFO(parse-failure fallthrough) = %q, want %q", got, want)
}
if parsed == nil || parsed.Title != "Blade Runner" {
t.Fatalf("parsed = %#v, want valid movie content", parsed)
}
}
// GetMetadata surfaces the full Phase-B field set from a curated movie NFO.
func TestGetMetadata_FullMovieFieldSet(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Blade Runner (1982).mkv")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "movie.nfo"), []byte(fullMovieNFO), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
p := NewProvider()
result, err := p.GetMetadata(context.Background(), metadata.MetadataRequest{
ContentType: "movie",
FilePath: filePath,
})
if err != nil {
t.Fatalf("GetMetadata() error = %v", err)
}
if !result.HasMetadata {
t.Fatal("HasMetadata = false, want true")
}
if result.OriginalTitle != "Blade Runner: The Original" {
t.Errorf("OriginalTitle = %q", result.OriginalTitle)
}
if result.Tagline != "Man has made his match" {
t.Errorf("Tagline = %q", result.Tagline)
}
if result.Runtime != 117 {
t.Errorf("Runtime = %d", result.Runtime)
}
if result.ReleaseDate != "1982-06-25" {
t.Errorf("ReleaseDate = %q", result.ReleaseDate)
}
if result.ContentRating != "R" {
t.Errorf("ContentRating = %q", result.ContentRating)
}
if len(result.Genres) != 2 || len(result.Studios) != 2 || len(result.Countries) != 2 || len(result.Keywords) != 2 {
t.Errorf("collections = genres %d studios %d countries %d keywords %d, want 2 each",
len(result.Genres), len(result.Studios), len(result.Countries), len(result.Keywords))
}
if result.Ratings.IMDB != 8.1 || result.Ratings.TMDB != 7.9 || result.Ratings.RTCritic != 89 || result.Ratings.RTAudience != 91 {
t.Errorf("Ratings = %#v", result.Ratings)
}
if len(result.People) != 5 {
t.Errorf("People len = %d, want 5", len(result.People))
}
if result.FirstAirDate != "" {
t.Errorf("FirstAirDate = %q, want empty for a movie", result.FirstAirDate)
}
}
// A minimal NFO must not emit placeholder collections: empty slices stay nil
// so MergeFillEmpty's early-return lets remote providers fill them.
func TestGetMetadata_MinimalNFOEmitsNoPlaceholders(t *testing.T) {
t.Parallel()
dir := t.TempDir()
filePath := filepath.Join(dir, "Home Movie (2021).mkv")
if err := os.WriteFile(filePath, []byte("video"), 0o644); err != nil {
t.Fatalf("WriteFile(file) error = %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "movie.nfo"), []byte(`<movie><title>Home Movie</title></movie>`), 0o644); err != nil {
t.Fatalf("WriteFile(movie.nfo) error = %v", err)
}
p := NewProvider()
result, err := p.GetMetadata(context.Background(), metadata.MetadataRequest{
ContentType: "movie",
FilePath: filePath,
})
if err != nil {
t.Fatalf("GetMetadata() error = %v", err)
}
if result.Genres != nil || result.Studios != nil || result.Countries != nil || result.Keywords != nil || result.People != nil {
t.Errorf("placeholder collections emitted: %#v", result)
}
if result.Runtime != 0 || result.ReleaseDate != "" || result.ContentRating != "" {
t.Errorf("placeholder scalars emitted: %#v", result)
}
}
// The series GetMetadata path maps aired/premiered onto FirstAirDate.
func TestGetMetadata_SeriesFirstAirDate(t *testing.T) {
t.Parallel()
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "tvshow.nfo"), []byte(fullTVShowNFO), 0o644); err != nil {
t.Fatalf("WriteFile(tvshow.nfo) error = %v", err)
}
p := NewProvider()
result, err := p.GetMetadata(context.Background(), metadata.MetadataRequest{
ContentType: "series",
PrimarySidecarSearchPaths: []string{dir},
})
if err != nil {
t.Fatalf("GetMetadata() error = %v", err)
}
if !result.HasMetadata {
t.Fatal("HasMetadata = false, want true")
}
if result.FirstAirDate != "2015-06-24" {
t.Errorf("FirstAirDate = %q, want 2015-06-24", result.FirstAirDate)
}
if result.ReleaseDate != "" {
t.Errorf("ReleaseDate = %q, want empty for a series", result.ReleaseDate)
}
}