From c66849155519c45cd065325299c95242b1c96863 Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Thu, 19 Nov 2026 05:56:40 +0800
Subject: [PATCH 1/6] fix(media): read-only collections list; collection API
stores titles as a sync does
- Media Manage lists Plex collections read-only: its Create, Rename and Delete never worked (wrong payload, and the next Plex sync undoes any change).
- POST/PUT /api/media/collections check title and alternate_titles and normalize them with normalize_titles; PUT updates the row in place and answers 409 on a taken title.
- One parse_alternate_titles helper for the manual picker and the poster renamerr, so a non-string alternate title no longer crashes the picker.
---
backend/api/media_api.py | 68 ++++----
backend/modules/poster_renamerr.py | 11 +-
backend/util/asset_candidates.py | 9 +-
backend/util/database/collection_cache.py | 40 ++++-
backend/util/helper.py | 9 +
frontend/src/pages/media/MediaManagePage.jsx | 164 +-----------------
.../src/pages/media/MediaManagePage.test.jsx | 22 ++-
frontend/src/utils/api/media.js | 15 --
tests/test_helper.py | 12 ++
tests/test_media_api_queries.py | 60 +++++++
tests/test_posters_queries.py | 13 ++
11 files changed, 200 insertions(+), 223 deletions(-)
diff --git a/backend/api/media_api.py b/backend/api/media_api.py
index e534ca3fa..ded300a2c 100644
--- a/backend/api/media_api.py
+++ b/backend/api/media_api.py
@@ -33,6 +33,7 @@
from backend.util.arr_delete import ArrDeleter, ArrOutcome
from backend.util.arr_instances import instance_detail
from backend.util.config import ConfigError, load_config
+from backend.util.normalization import normalize_titles
from backend.util.public_error import failure_text
from backend.util.database import (
INCOMPLETE_METADATA_FIELDS,
@@ -746,6 +747,22 @@ def delete_collection(
)
+def _title_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
+ """The title columns ``payload`` sets, normalized as a Plex sync stores them, or why they are invalid."""
+ fields: Dict[str, Any] = {}
+ if "title" in payload:
+ title = payload["title"]
+ if not isinstance(title, str) or not title.strip():
+ return {}, "Field 'title' must be a non-empty string"
+ fields.update(title=title, normalized_title=normalize_titles(title))
+ if "alternate_titles" in payload:
+ alts = payload["alternate_titles"]
+ if not isinstance(alts, list) or not all(isinstance(t, str) and t.strip() for t in alts):
+ return {}, "Field 'alternate_titles' must be a list of non-empty strings"
+ fields.update(alternate_titles=alts, normalized_alternate_titles=[normalize_titles(t) for t in alts])
+ return fields, None
+
+
@router.post(
"/collections",
summary="Create collection",
@@ -763,7 +780,7 @@ def delete_collection(
}
},
},
- 400: {"description": "Missing 'title' or 'instance_name'"},
+ 400: {"description": "Missing 'title' or 'instance_name', or a title field of the wrong type"},
413: {"description": "Request body too large"},
},
)
@@ -801,19 +818,19 @@ async def create_collection(
status_code=400,
)
+ titles, why = _title_fields(payload)
+ if why:
+ return error(why, code="INVALID_FIELDS", status_code=400)
record = {
- "title": title,
- "normalized_title": title.lower().strip() if title else None,
"year": payload.get("year"),
"tmdb_id": payload.get("tmdb_id"),
"tvdb_id": payload.get("tvdb_id"),
"imdb_id": payload.get("imdb_id"),
"folder": payload.get("folder"),
"library_name": payload.get("library_name"),
- "alternate_titles": payload.get("alternate_titles", []),
- "normalized_alternate_titles": payload.get(
- "normalized_alternate_titles", []
- ),
+ "alternate_titles": [],
+ "normalized_alternate_titles": [],
+ **titles,
}
db.collection.upsert(record, instance_name)
@@ -852,7 +869,10 @@ async def create_collection(
}
}
},
- }
+ },
+ 400: {"description": "A title field of the wrong type"},
+ 404: {"description": "No collection with that id"},
+ 409: {"description": "Another collection in this library already has that title"},
},
)
async def update_collection(
@@ -897,31 +917,21 @@ async def update_collection(
status_code=404,
)
- # Merge updates into existing record
- updatable_fields = [
- "title",
- "year",
- "tmdb_id",
- "tvdb_id",
- "imdb_id",
- "folder",
- "library_name",
- "alternate_titles",
- "normalized_alternate_titles",
- ]
- for field in updatable_fields:
+ titles, why = _title_fields(payload)
+ if why:
+ return error(why, code="INVALID_FIELDS", status_code=400)
+ for field in ("year", "tmdb_id", "tvdb_id", "imdb_id", "folder", "library_name"):
if field in payload:
existing[field] = payload[field]
-
- # Update normalized_title if title changed
- if "title" in payload:
- existing["normalized_title"] = (
- payload["title"].lower().strip() if payload["title"] else None
+ existing.update(titles)
+ # In place by id: an upsert keyed on the new title would add a second row.
+ if not db.collection.update_row(collection_id, existing):
+ return error(
+ "Another collection in this library already has that title",
+ code="COLLECTION_EXISTS",
+ status_code=409,
)
- instance_name = existing.get("instance_name")
- db.collection.upsert(existing, instance_name)
-
# Fetch the updated record
updated = db.collection.get_by_id(collection_id)
diff --git a/backend/modules/poster_renamerr.py b/backend/modules/poster_renamerr.py
index 9e7d22c76..5fa64c7ff 100755
--- a/backend/modules/poster_renamerr.py
+++ b/backend/modules/poster_renamerr.py
@@ -27,6 +27,7 @@
)
from backend.util.helper import (
as_list,
+ parse_alternate_titles,
classify_match,
is_id_match_reason,
create_table,
@@ -529,15 +530,7 @@ def find_asset_candidate(
season_number = media.get("season_number")
expected_asset_type = "collection" if is_collection else asset_type
- alt_titles = []
- try:
- alt_titles = json.loads(media.get("alternate_titles") or "[]")
- except Exception:
- pass
- # The collections API stores these unchecked: keep only the strings.
- if not isinstance(alt_titles, list):
- alt_titles = []
- alt_titles = [t for t in alt_titles if isinstance(t, str) and t]
+ alt_titles = parse_alternate_titles(media.get("alternate_titles"))
reasons = []
candidates = []
diff --git a/backend/util/asset_candidates.py b/backend/util/asset_candidates.py
index 283e237a2..92358e41a 100644
--- a/backend/util/asset_candidates.py
+++ b/backend/util/asset_candidates.py
@@ -6,10 +6,9 @@
"""
import difflib
-import json
from typing import Any, Dict, List, Optional, Tuple
-from backend.util.helper import is_match
+from backend.util.helper import is_match, parse_alternate_titles
from backend.util.normalization import normalize_titles
@@ -22,11 +21,7 @@ def rank_candidates(
) -> List[Tuple[Dict[str, Any], bool, float, str]]:
"""Best-first (row, would_match, similarity, reason) tuples for a media row."""
season_number = row.get("season_number")
- try:
- alts = json.loads(row.get("alternate_titles") or "[]")
- except (ValueError, TypeError):
- alts = []
- search_titles = [row.get("title")] + [a for a in alts if a]
+ search_titles = [row.get("title")] + parse_alternate_titles(row.get("alternate_titles"))
row_norm = row.get("normalized_title") or normalize_titles(row.get("title") or "")
seen = set()
diff --git a/backend/util/database/collection_cache.py b/backend/util/database/collection_cache.py
index 1a869097e..e18f41a7a 100755
--- a/backend/util/database/collection_cache.py
+++ b/backend/util/database/collection_cache.py
@@ -1,4 +1,5 @@
import json
+import sqlite3
from typing import Any, List, Optional
from .db_base import DatabaseBase
@@ -10,18 +11,45 @@ class CollectionCache(DatabaseBase):
Provides CRUD and sync operations.
"""
- def upsert(self, record: dict, instance_name: str) -> None:
- """Insert or update a collection record for a given instance."""
- record["instance_name"] = instance_name
- record["asset_type"] = "collection"
-
- # Serialize list/dict fields to JSON
+ @staticmethod
+ def _store_json(record: dict) -> None:
+ """Serialize ``record``'s title lists to JSON in place; a missing list is stored empty."""
for key in ("alternate_titles", "normalized_alternate_titles"):
if isinstance(record.get(key), (list, dict)):
record[key] = json.dumps(record[key])
elif record.get(key) is None:
record[key] = json.dumps([])
+ def update_row(self, id: int, record: dict) -> bool:
+ """Write ``record``'s fields onto row ``id`` in place; False when its title is taken in that library and instance."""
+ self._store_json(record)
+ columns = (
+ "title",
+ "normalized_title",
+ "alternate_titles",
+ "normalized_alternate_titles",
+ "year",
+ "tmdb_id",
+ "tvdb_id",
+ "imdb_id",
+ "folder",
+ "library_name",
+ )
+ try:
+ self.execute_query(
+ f"UPDATE collections_cache SET {', '.join(c + '=?' for c in columns)} WHERE id=?",
+ (*(record.get(c) for c in columns), id),
+ )
+ except sqlite3.IntegrityError:
+ return False
+ return True
+
+ def upsert(self, record: dict, instance_name: str) -> None:
+ """Insert or update a collection record for a given instance."""
+ record["instance_name"] = instance_name
+ record["asset_type"] = "collection"
+ self._store_json(record)
+
self.execute_query(
"""
INSERT INTO collections_cache
diff --git a/backend/util/helper.py b/backend/util/helper.py
index a2596e600..5a5a0ca78 100755
--- a/backend/util/helper.py
+++ b/backend/util/helper.py
@@ -684,6 +684,15 @@ def classify_match(matched: bool, reason: str) -> Tuple[str, float]:
return "matched", _MATCH_CONF_EXACT
+def parse_alternate_titles(raw: Any) -> List[str]:
+ """The non-empty string titles in a row's ``alternate_titles`` JSON; [] when it is unreadable or not a list."""
+ try:
+ titles = json.loads(raw or "[]")
+ except (TypeError, ValueError):
+ return []
+ return [t for t in titles if isinstance(t, str) and t] if isinstance(titles, list) else []
+
+
def generate_title_variants(title: str) -> Dict[str, List[str]]:
"""Produce alternate title candidates plus their normalized forms.
diff --git a/frontend/src/pages/media/MediaManagePage.jsx b/frontend/src/pages/media/MediaManagePage.jsx
index aca0c99d9..fa1eeeb94 100644
--- a/frontend/src/pages/media/MediaManagePage.jsx
+++ b/frontend/src/pages/media/MediaManagePage.jsx
@@ -6,7 +6,7 @@ import { mediaAPI } from '../../utils/api/media.js';
import { nestarrAPI } from '../../utils/api/nestarr.js';
import { apiCore } from '../../utils/api/core.js';
import { Modal } from '../../components/modals/Modal';
-import { Button, LoadingButton, IconButton } from '../../components/ui/index.js';
+import { Button, LoadingButton } from '../../components/ui/index.js';
import { PageHeader } from '../../components/ui/PageHeader';
import Spinner from '../../components/ui/Spinner.jsx';
import { LibraryMaintenance } from '../../components/maintenance/LibraryMaintenance.jsx';
@@ -426,10 +426,6 @@ const MediaManagePage = () => {
const [resolveDeleteFiles, setResolveDeleteFiles] = useState(false);
const [resolveMembers, setResolveMembers] = useState(null);
const [resolveMembersLoading, setResolveMembersLoading] = useState(false);
- const [showCreateCollection, setShowCreateCollection] = useState(false);
- const [newCollectionName, setNewCollectionName] = useState('');
- const [editCollection, setEditCollection] = useState(null);
- const [editCollectionName, setEditCollectionName] = useState('');
const [nestedIssues, setNestedIssues] = useState([]);
const [lastScanTime, setLastScanTime] = useState(null);
const [unmatchedEnabled, setUnmatchedEnabled] = useState(true);
@@ -447,40 +443,11 @@ const MediaManagePage = () => {
mediaAPI.exportMedia({ format: 'json' })
);
- const { execute: createCollection, isLoading: isCreatingCollection } = useApiMutation(
- name => mediaAPI.createCollection({ name }),
- {
- successMessage: 'Collection created',
- onSuccess: () => {
- setShowCreateCollection(false);
- setNewCollectionName('');
- refreshCollections();
- },
- }
- );
-
- const { execute: updateCollectionMutation, isLoading: isUpdatingCollection } = useApiMutation(
- // execute() forwards a single arg — take one object, not (id, data).
- ({ id, data }) => mediaAPI.updateCollection(id, data),
- {
- successMessage: 'Collection updated',
- onSuccess: () => {
- setEditCollection(null);
- setEditCollectionName('');
- refreshCollections();
- },
- }
- );
-
- const { data: collectionsData, refresh: refreshCollections } = useApiData({
+ const { data: collectionsData } = useApiData({
apiFunction: mediaAPI.fetchCollections,
options: { showErrorToast: false },
});
- const { execute: deleteCollection } = useApiMutation(id => mediaAPI.deleteCollection(id), {
- successMessage: 'Collection deleted',
- });
-
const { execute: deleteItem, isLoading: isDeleting } = useApiMutation(
() => mediaAPI.deleteMediaItem(deleteTarget?.id, { deleteFiles }),
{ successMessage: 'Media item deleted' }
@@ -675,24 +642,6 @@ const MediaManagePage = () => {
}
};
- const handleCreateCollection = async () => {
- if (!newCollectionName.trim()) return;
- try {
- await createCollection(newCollectionName.trim());
- } catch {
- toast.error('Failed to create collection');
- }
- };
-
- const handleDeleteCollection = async id => {
- try {
- await deleteCollection(id);
- refreshCollections();
- } catch {
- toast.error('Failed to delete collection');
- }
- };
-
const handleDelete = async () => {
if (!deleteTarget) return;
try {
@@ -1108,20 +1057,16 @@ const MediaManagePage = () => {
title="Collections"
count={`${collections.length}`}
countClass="bg-primary/15 text-primary-hover"
- >
-
-
+ />
+
+ Your Plex collections as of the last sync. Create, rename or delete them in
+ Plex.
+
{collections.map((col, i) => (
@@ -1133,27 +1078,6 @@ const MediaManagePage = () => {
)}
-
- {
- setEditCollection(col);
- setEditCollectionName(col.title || col.name || '');
- }}
- />
- handleDeleteCollection(col.id)}
- />
-
))}
@@ -1363,78 +1287,6 @@ const MediaManagePage = () => {
- {/* Create Collection Modal */}
- {
- setShowCreateCollection(false);
- setNewCollectionName('');
- }}
- size="small"
- >
- Create Collection
-
-
- setNewCollectionName(e.target.value)}
- placeholder="My Collection"
- className="w-full p-2 bg-input border border-border rounded-md text-fg text-sm focus:border-primary focus:outline-none"
- />
-
-
-
-
-
-
- {/* Edit Collection Modal */}
- {
- setEditCollection(null);
- setEditCollectionName('');
- }}
- size="small"
- >
- Edit Collection
-
-
- setEditCollectionName(e.target.value)}
- className="w-full p-2 bg-input border border-border rounded-md text-fg text-sm focus:border-primary focus:outline-none"
- />
-
-
-
-
-
-
{/* Fix Nested Media Modal — shows preview before executing */}
{
expect(media.fetchDuplicates).toHaveBeenCalledTimes(1);
});
});
+
+describe('MediaManagePage Collections', () => {
+ beforeEach(() => {
+ media.fetchDuplicates.mockResolvedValue({ data: { duplicates: [] } });
+ media.fetchCollections.mockResolvedValue({
+ data: { collections: [{ id: 1, title: 'Marvel Cinematic Universe', year: 2008 }] },
+ });
+ });
+
+ it('lists Plex collections read-only and says where to change them', async () => {
+ render();
+ const section = (await screen.findByRole('heading', { name: 'Collections' })).closest(
+ 'section'
+ );
+
+ expect(within(section).getByText('Marvel Cinematic Universe')).toBeTruthy();
+ expect(within(section).getByText(/Create, rename or delete them in Plex/)).toBeTruthy();
+ expect(within(section).queryAllByRole('button')).toEqual([]);
+ });
+});
diff --git a/frontend/src/utils/api/media.js b/frontend/src/utils/api/media.js
index 9bcab96db..da3df216c 100755
--- a/frontend/src/utils/api/media.js
+++ b/frontend/src/utils/api/media.js
@@ -117,21 +117,6 @@ export const mediaAPI = {
});
},
- /** Create a collection from { name, description, mediaIds }. */
- createCollection: collectionData => {
- return apiCore.post('/media/collections', collectionData);
- },
-
- /** Update a collection. */
- updateCollection: (collectionId, collectionData) => {
- return apiCore.put(`/media/collections/${collectionId}`, collectionData);
- },
-
- /** Delete a collection. */
- deleteCollection: collectionId => {
- return apiCore.delete(`/media/collections/${collectionId}`);
- },
-
/** Duplicate groups and folder collisions. */
fetchDuplicates: (options = {}) => {
const params = new URLSearchParams(options);
diff --git a/tests/test_helper.py b/tests/test_helper.py
index 30df14174..60edc8a99 100644
--- a/tests/test_helper.py
+++ b/tests/test_helper.py
@@ -2,8 +2,11 @@
import os
+import pytest
+
from backend.util.helper import (
+ parse_alternate_titles,
classify_match,
compare_strings,
create_bar,
@@ -624,3 +627,12 @@ def test_is_match_both_years_present_and_differ_still_blocks():
media = {"title": "The Lovers", "year": 2023}
matched, _ = is_match(asset, media)
assert matched is False
+
+
+@pytest.mark.parametrize(
+ "raw, titles",
+ [(None, []), ("", []), ("not json", []), ('{"Duna": 1}', []), ('"Duna"', []), ('[1, "", "Duna"]', ["Duna"])],
+)
+def test_parse_alternate_titles_keeps_only_string_titles(raw, titles):
+ parsed = parse_alternate_titles(raw)
+ assert parsed == titles
diff --git a/tests/test_media_api_queries.py b/tests/test_media_api_queries.py
index 3a1de7da3..e003387fe 100644
--- a/tests/test_media_api_queries.py
+++ b/tests/test_media_api_queries.py
@@ -447,3 +447,63 @@ def test_create_collection_route_reads_back_the_created_row(db):
collection = resp.json()["data"]["collection"]
assert collection["title"] == "Marvel"
assert collection["instance_name"] == "plex1"
+
+
+def _collection_rows(db):
+ rows = db.collection.execute_query(
+ "SELECT title, normalized_title, normalized_alternate_titles FROM collections_cache ORDER BY id",
+ fetch_all=True,
+ )
+ return [(r["title"], r["normalized_title"], r["normalized_alternate_titles"]) for r in rows]
+
+
+def test_create_collection_stores_titles_normalized_as_a_sync_does(db):
+ resp = _client(db).post(
+ "/api/media/collections",
+ json={"title": "The Matrix Collection", "instance_name": "plex1", "alternate_titles": ["Matrix"]},
+ )
+ rows = _collection_rows(db)
+ assert (resp.status_code, rows) == (200, [("The Matrix Collection", "thematrixcollection", '["matrix"]')])
+
+
+@pytest.mark.parametrize(
+ "body",
+ [{"alternate_titles": "Matrix"}, {"alternate_titles": ["Matrix", 7]}, {"alternate_titles": [" "]}, {"title": 7}],
+ ids=["string", "number-in-list", "blank", "numeric-title"],
+)
+def test_create_collection_refuses_title_fields_of_the_wrong_shape(db, body):
+ resp = _client(db).post("/api/media/collections", json={"title": "Marvel", "instance_name": "plex1", **body})
+ assert (resp.status_code, resp.json()["error_code"], _collection_rows(db)) == (400, "INVALID_FIELDS", [])
+
+
+def test_update_collection_renames_in_place_and_renormalizes(db):
+ client = _client(db)
+ created = client.post("/api/media/collections", json={"title": "Matrix", "instance_name": "plex1"})
+ cid = created.json()["data"]["collection"]["id"]
+ resp = client.put(
+ f"/api/media/collections/{cid}",
+ json={"title": "The Matrix Collection", "alternate_titles": ["Matrix"]},
+ )
+ rows = _collection_rows(db)
+ assert (resp.status_code, resp.json()["data"]["collection"]["title"], rows) == (
+ 200,
+ "The Matrix Collection",
+ [("The Matrix Collection", "thematrixcollection", '["matrix"]')],
+ )
+
+
+@pytest.mark.parametrize(
+ "body, status, code",
+ [({"title": ""}, 400, "INVALID_FIELDS"), ({"title": "Marvel"}, 409, "COLLECTION_EXISTS")],
+ ids=["blank-title", "taken-title"],
+)
+def test_update_collection_refuses_a_title_it_cannot_store(db, body, status, code):
+ client = _client(db)
+ for title in ("Marvel", "Matrix"):
+ client.post(
+ "/api/media/collections", json={"title": title, "instance_name": "plex1", "library_name": "Movies"}
+ )
+ cid = db.collection.get_by_title_and_instance("Matrix", "plex1", "Movies")["id"]
+ resp = client.put(f"/api/media/collections/{cid}", json=body)
+ titles = [title for title, *_ in _collection_rows(db)]
+ assert (resp.status_code, resp.json()["error_code"], titles) == (status, code, ["Marvel", "Matrix"])
diff --git a/tests/test_posters_queries.py b/tests/test_posters_queries.py
index 48eec20f0..17511cf37 100644
--- a/tests/test_posters_queries.py
+++ b/tests/test_posters_queries.py
@@ -934,3 +934,16 @@ def _boom(*_a, **_kw):
"SELECT file FROM poster_cache", fetch_one=True
)["file"]
assert stored == str(poster) # row still points at the surviving file
+
+
+@pytest.mark.parametrize("stored", ['{"Duna": 1}', '[1, "Duna"]', "not json"])
+def test_rank_candidates_ranks_a_row_with_odd_alternate_titles(db, stored):
+ """A row stored with non-string alternate titles still ranks: only its string titles are looked up."""
+ from backend.util.asset_candidates import rank_candidates
+
+ _seed_poster(db, "Dune", file="/src/Dune (2021).jpg")
+ row = {**db.media.get_by_id(_seed_media(db, "Dune")), "alternate_titles": stored}
+
+ ranked = rank_candidates(db, row, "movie")
+
+ assert [c["title"] for c, *_ in ranked] == ["Dune"]
From 6d4bc4feb2450cc83e53910db8da439086a358f2 Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Thu, 19 Nov 2026 05:59:29 +0800
Subject: [PATCH 2/6] refactor(helper): one json_list for every
alternate_titles read
is_match's nested copy and tmdb's _json_list become helper.json_list; parse_alternate_titles builds on it.
---
backend/util/helper.py | 32 +++++++++++++++-----------------
backend/util/tmdb.py | 19 ++++---------------
tests/test_helper.py | 10 +++++++++-
3 files changed, 28 insertions(+), 33 deletions(-)
diff --git a/backend/util/helper.py b/backend/util/helper.py
index 5a5a0ca78..5ab80d01b 100755
--- a/backend/util/helper.py
+++ b/backend/util/helper.py
@@ -453,17 +453,6 @@ def is_match(
)
media["normalized_folder_title"] = normalize_titles(media["folder_title"])
- def json_list(value: Any) -> List[Any]:
- if isinstance(value, list):
- return value
- if isinstance(value, str):
- try:
- parsed = json.loads(value)
- return parsed if isinstance(parsed, list) else []
- except Exception:
- return []
- return []
-
asset_alt_titles = json_list(asset.get("alternate_titles"))
asset_norm_alt_titles = json_list(asset.get("normalized_alternate_titles"))
media_alt_titles = json_list(media.get("alternate_titles"))
@@ -684,13 +673,22 @@ def classify_match(matched: bool, reason: str) -> Tuple[str, float]:
return "matched", _MATCH_CONF_EXACT
+def json_list(value: Any) -> List[Any]:
+ """``value`` as a list: itself, or the list its JSON holds; [] for anything else."""
+ if isinstance(value, list):
+ return value
+ if isinstance(value, str):
+ try:
+ parsed = json.loads(value)
+ except ValueError:
+ return []
+ return parsed if isinstance(parsed, list) else []
+ return []
+
+
def parse_alternate_titles(raw: Any) -> List[str]:
- """The non-empty string titles in a row's ``alternate_titles`` JSON; [] when it is unreadable or not a list."""
- try:
- titles = json.loads(raw or "[]")
- except (TypeError, ValueError):
- return []
- return [t for t in titles if isinstance(t, str) and t] if isinstance(titles, list) else []
+ """The non-empty string titles in a row's ``alternate_titles`` (a list or its JSON)."""
+ return [t for t in json_list(raw) if isinstance(t, str) and t]
def generate_title_variants(title: str) -> Dict[str, List[str]]:
diff --git a/backend/util/tmdb.py b/backend/util/tmdb.py
index ce8abc951..55918b14f 100644
--- a/backend/util/tmdb.py
+++ b/backend/util/tmdb.py
@@ -23,6 +23,7 @@
from backend.util.config import TMDBConfig
from backend.util.database import ChubDB
+from backend.util.helper import json_list
from backend.util.normalization import normalize_titles
@@ -638,18 +639,6 @@ def _norm_set(values: Iterable[Optional[str]]) -> Set[str]:
return out
-def _json_list(value) -> List:
- if isinstance(value, list):
- return value
- if isinstance(value, str):
- try:
- parsed = json.loads(value)
- return parsed if isinstance(parsed, list) else []
- except (ValueError, TypeError):
- return []
- return []
-
-
def run_match_quality(
db: ChubDB,
cfg: TMDBConfig,
@@ -734,7 +723,7 @@ def _verify_and_hydrate(
)
row_titles = _norm_set(
[row.get("title"), row.get("normalized_title")]
- + _json_list(row.get("alternate_titles"))
+ + json_list(row.get("alternate_titles"))
)
# row's normalized_title is already normalized; include raw too
row_titles |= {n for n in [row.get("normalized_title")] if n}
@@ -778,8 +767,8 @@ def _flag_review(db: ChubDB, media_id: int, reason: str) -> None:
def _merge_akas(db: ChubDB, row: dict, tmdb_akas: List[str]) -> bool:
"""Union TMDB AKAs into a row's alternate_titles / normalized_alternate_titles.
Returns True if anything new was added."""
- existing = _json_list(row.get("alternate_titles"))
- existing_norm = set(_json_list(row.get("normalized_alternate_titles")))
+ existing = json_list(row.get("alternate_titles"))
+ existing_norm = set(json_list(row.get("normalized_alternate_titles")))
added = False
for aka in tmdb_akas:
n = normalize_titles(aka)
diff --git a/tests/test_helper.py b/tests/test_helper.py
index 60edc8a99..49cf68217 100644
--- a/tests/test_helper.py
+++ b/tests/test_helper.py
@@ -631,7 +631,15 @@ def test_is_match_both_years_present_and_differ_still_blocks():
@pytest.mark.parametrize(
"raw, titles",
- [(None, []), ("", []), ("not json", []), ('{"Duna": 1}', []), ('"Duna"', []), ('[1, "", "Duna"]', ["Duna"])],
+ [
+ (None, []),
+ ("", []),
+ ("not json", []),
+ ('{"Duna": 1}', []),
+ ('"Duna"', []),
+ ('[1, "", "Duna"]', ["Duna"]),
+ (["Duna", 1], ["Duna"]),
+ ],
)
def test_parse_alternate_titles_keeps_only_string_titles(raw, titles):
parsed = parse_alternate_titles(raw)
From ffbc9d2786471090516330905314904ac77dad01 Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Thu, 19 Nov 2026 06:10:31 +0800
Subject: [PATCH 3/6] fix(media): collection API derives titles with the sync's
helper and checks every field
- collection_title_fields owns the sync's title derivation (unescape, ASCII, normalize, variants); the Plex sync and the API both call it, so a rename regenerates variants.
- One _collection_fields check for POST and PUT: ids and year are positive whole numbers, text fields are strings, library_name is required on create; a PUT with nothing to set answers NO_FIELDS.
- update_row refuses a clash in one statement with IS, so a NULL library no longer slips past the UNIQUE key and a 409 logs no database error; a row removed mid-request answers 404.
- json_list also absorbs RecursionError; the poster renamerr's last raw json.loads reads through parse_alternate_titles.
---
backend/api/media_api.py | 89 +++++++-----
backend/modules/poster_renamerr.py | 4 +-
backend/util/database/collection_cache.py | 25 ++--
backend/util/helper.py | 12 +-
backend/util/plex.py | 16 +--
tests/test_helper.py | 1 +
tests/test_media_api_queries.py | 161 +++++++++++++++++-----
tests/test_poster_renamerr.py | 5 +
tests/test_posters_queries.py | 2 +-
9 files changed, 216 insertions(+), 99 deletions(-)
diff --git a/backend/api/media_api.py b/backend/api/media_api.py
index ded300a2c..a73654fc1 100644
--- a/backend/api/media_api.py
+++ b/backend/api/media_api.py
@@ -33,6 +33,7 @@
from backend.util.arr_delete import ArrDeleter, ArrOutcome
from backend.util.arr_instances import instance_detail
from backend.util.config import ConfigError, load_config
+from backend.util.helper import collection_title_fields
from backend.util.normalization import normalize_titles
from backend.util.public_error import failure_text
from backend.util.database import (
@@ -747,18 +748,38 @@ def delete_collection(
)
-def _title_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
- """The title columns ``payload`` sets, normalized as a Plex sync stores them, or why they are invalid."""
+def _is_text(value: Any) -> bool:
+ """A string with more than whitespace in it."""
+ return isinstance(value, str) and bool(value.strip())
+
+
+def _collection_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
+ """The collection columns ``payload`` sets, titles derived as a Plex sync derives them, or why one is invalid."""
fields: Dict[str, Any] = {}
+ for key in ("year", "tmdb_id", "tvdb_id"):
+ if key in payload:
+ number = None if payload[key] is None else _media_id(payload[key])
+ if payload[key] is not None and number is None:
+ return {}, f"Field '{key}' must be a positive whole number or null"
+ fields[key] = number
+ for key in ("imdb_id", "folder"):
+ if key in payload:
+ if payload[key] is not None and not isinstance(payload[key], str):
+ return {}, f"Field '{key}' must be a string or null"
+ fields[key] = payload[key]
+ if "library_name" in payload:
+ if not _is_text(payload["library_name"]):
+ return {}, "Field 'library_name' must be a non-empty string"
+ fields["library_name"] = payload["library_name"]
if "title" in payload:
- title = payload["title"]
- if not isinstance(title, str) or not title.strip():
+ if not _is_text(payload["title"]):
return {}, "Field 'title' must be a non-empty string"
- fields.update(title=title, normalized_title=normalize_titles(title))
+ fields.update(collection_title_fields(payload["title"].strip()))
if "alternate_titles" in payload:
alts = payload["alternate_titles"]
- if not isinstance(alts, list) or not all(isinstance(t, str) and t.strip() for t in alts):
+ if not isinstance(alts, list) or not all(_is_text(t) for t in alts):
return {}, "Field 'alternate_titles' must be a list of non-empty strings"
+ alts = [t.strip() for t in alts]
fields.update(alternate_titles=alts, normalized_alternate_titles=[normalize_titles(t) for t in alts])
return fields, None
@@ -780,7 +801,7 @@ def _title_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
}
},
},
- 400: {"description": "Missing 'title' or 'instance_name', or a title field of the wrong type"},
+ 400: {"description": "Missing 'title', 'instance_name' or 'library_name', or a field of the wrong type"},
413: {"description": "Request body too large"},
},
)
@@ -804,8 +825,7 @@ async def create_collection(
return body_too_large_error()
logger.debug(f"Serving POST /api/media/collections with payload: {payload}")
- title = payload.get("title")
- if not title:
+ if "title" not in payload:
return error(
"Field 'title' is required", code="MISSING_TITLE", status_code=400
)
@@ -818,26 +838,21 @@ async def create_collection(
status_code=400,
)
- titles, why = _title_fields(payload)
+ if "library_name" not in payload:
+ return error(
+ "Field 'library_name' is required",
+ code="MISSING_LIBRARY",
+ status_code=400,
+ )
+ record, why = _collection_fields(payload)
if why:
return error(why, code="INVALID_FIELDS", status_code=400)
- record = {
- "year": payload.get("year"),
- "tmdb_id": payload.get("tmdb_id"),
- "tvdb_id": payload.get("tvdb_id"),
- "imdb_id": payload.get("imdb_id"),
- "folder": payload.get("folder"),
- "library_name": payload.get("library_name"),
- "alternate_titles": [],
- "normalized_alternate_titles": [],
- **titles,
- }
db.collection.upsert(record, instance_name)
- # Fetch the created/updated record
+ # Read back by the stored title: the sync's derivation may have changed it.
created = db.collection.get_by_title_and_instance(
- title, instance_name, record["library_name"]
+ record["title"], instance_name, record["library_name"]
)
return ok("Collection created successfully", {"collection": created})
@@ -870,7 +885,7 @@ async def create_collection(
}
},
},
- 400: {"description": "A title field of the wrong type"},
+ 400: {"description": "No updatable field, or a field of the wrong type"},
404: {"description": "No collection with that id"},
409: {"description": "Another collection in this library already has that title"},
},
@@ -885,7 +900,7 @@ async def update_collection(
Update a media collection by ID.
Fetches the existing collection, merges in the provided updates,
- and upserts the result back to the database.
+ and writes the result back onto that row.
Args:
collection_id: The unique identifier of the collection to update
@@ -898,7 +913,7 @@ async def update_collection(
if payload is BODY_TOO_LARGE:
return body_too_large_error()
# An unusable body used to raise into the 500 handler; keep that
- # response — falling through would upsert the record unchanged.
+ # response — falling through would write the record unchanged.
if not isinstance(payload, dict) or not payload:
return error(
"Error updating collection",
@@ -917,24 +932,28 @@ async def update_collection(
status_code=404,
)
- titles, why = _title_fields(payload)
+ fields, why = _collection_fields(payload)
if why:
return error(why, code="INVALID_FIELDS", status_code=400)
- for field in ("year", "tmdb_id", "tvdb_id", "imdb_id", "folder", "library_name"):
- if field in payload:
- existing[field] = payload[field]
- existing.update(titles)
+ if not fields:
+ return error("No valid fields to update", code="NO_FIELDS", status_code=400)
+ existing.update(fields)
# In place by id: an upsert keyed on the new title would add a second row.
- if not db.collection.update_row(collection_id, existing):
+ written = db.collection.update_row(collection_id, existing)
+ updated = db.collection.get_by_id(collection_id)
+ if updated is None:
+ return error(
+ f"Collection {collection_id} not found",
+ code="COLLECTION_NOT_FOUND",
+ status_code=404,
+ )
+ if not written:
return error(
"Another collection in this library already has that title",
code="COLLECTION_EXISTS",
status_code=409,
)
- # Fetch the updated record
- updated = db.collection.get_by_id(collection_id)
-
return ok("Collection updated successfully", {"collection": updated})
except Exception as e:
diff --git a/backend/modules/poster_renamerr.py b/backend/modules/poster_renamerr.py
index 5fa64c7ff..4d560f63e 100755
--- a/backend/modules/poster_renamerr.py
+++ b/backend/modules/poster_renamerr.py
@@ -637,9 +637,7 @@ def _title_match_reason(
"""is_match()'s reason when a title-lookup poster belongs to ``media``, else ""."""
if cand.get("season_number") != media.get("season_number"):
return ""
- cand_alt_titles = set(
- json.loads(cand.get("normalized_alternate_titles", "[]") or "[]")
- )
+ cand_alt_titles = set(parse_alternate_titles(cand.get("normalized_alternate_titles")))
if (
cand.get("normalized_title", "") not in all_titles
and not all_titles & cand_alt_titles
diff --git a/backend/util/database/collection_cache.py b/backend/util/database/collection_cache.py
index e18f41a7a..9db4173d1 100755
--- a/backend/util/database/collection_cache.py
+++ b/backend/util/database/collection_cache.py
@@ -1,5 +1,4 @@
import json
-import sqlite3
from typing import Any, List, Optional
from .db_base import DatabaseBase
@@ -21,7 +20,7 @@ def _store_json(record: dict) -> None:
record[key] = json.dumps([])
def update_row(self, id: int, record: dict) -> bool:
- """Write ``record``'s fields onto row ``id`` in place; False when its title is taken in that library and instance."""
+ """Write ``record``'s fields onto row ``id`` in place; False when that row is gone or another holds its key."""
self._store_json(record)
columns = (
"title",
@@ -35,14 +34,20 @@ def update_row(self, id: int, record: dict) -> bool:
"folder",
"library_name",
)
- try:
- self.execute_query(
- f"UPDATE collections_cache SET {', '.join(c + '=?' for c in columns)} WHERE id=?",
- (*(record.get(c) for c in columns), id),
- )
- except sqlite3.IntegrityError:
- return False
- return True
+ # `IS`: the UNIQUE key treats NULL libraries as distinct, so it never refuses a clash there.
+ written = self.execute_query(
+ f"UPDATE collections_cache SET {', '.join(c + '=?' for c in columns)} WHERE id=? AND NOT EXISTS "
+ "(SELECT 1 FROM collections_cache WHERE title IS ? AND library_name IS ? AND instance_name IS ? AND id<>?)",
+ (
+ *(record.get(c) for c in columns),
+ id,
+ record.get("title"),
+ record.get("library_name"),
+ record.get("instance_name"),
+ id,
+ ),
+ )
+ return bool(written)
def upsert(self, record: dict, instance_name: str) -> None:
"""Insert or update a collection record for a given instance."""
diff --git a/backend/util/helper.py b/backend/util/helper.py
index 5ab80d01b..8a83f9090 100755
--- a/backend/util/helper.py
+++ b/backend/util/helper.py
@@ -1,6 +1,7 @@
# util/helper.py
import copy
+import html
import json
import os
import re
@@ -12,6 +13,7 @@
import yaml
from tqdm import tqdm
+from unidecode import unidecode
from backend.util.constants import (
folder_year_regex,
@@ -680,14 +682,14 @@ def json_list(value: Any) -> List[Any]:
if isinstance(value, str):
try:
parsed = json.loads(value)
- except ValueError:
+ except (ValueError, RecursionError):
return []
return parsed if isinstance(parsed, list) else []
return []
def parse_alternate_titles(raw: Any) -> List[str]:
- """The non-empty string titles in a row's ``alternate_titles`` (a list or its JSON)."""
+ """The non-empty strings in an alternate-titles column, raw or normalized (a list or its JSON)."""
return [t for t in json_list(raw) if isinstance(t, str) and t]
@@ -763,3 +765,9 @@ def generate_title_variants(title: str) -> Dict[str, List[str]]:
"alternate_titles": alternate_titles,
"normalized_alternate_titles": normalized_alternate_titles,
}
+
+
+def collection_title_fields(title: str) -> Dict[str, Any]:
+ """The title columns collections_cache stores for a Plex collection named ``title``."""
+ plain = unidecode(html.unescape(title))
+ return {"title": plain, "normalized_title": normalize_titles(plain), **generate_title_variants(plain)}
diff --git a/backend/util/plex.py b/backend/util/plex.py
index 69d7f1217..6ec17770a 100755
--- a/backend/util/plex.py
+++ b/backend/util/plex.py
@@ -1,4 +1,3 @@
-import html
import itertools
import os
import re
@@ -12,12 +11,11 @@
from plexapi.exceptions import NotFound
from pathvalidate import sanitize_filename
from plexapi.server import PlexServer
-from unidecode import unidecode
from backend.util.config import get_config_path
from backend.util.helper import (
YEAR_MATCH_TOLERANCE,
- generate_title_variants,
+ collection_title_fields,
progress,
)
from backend.util.normalization import normalize_titles
@@ -250,9 +248,8 @@ def get_collections(
leave=False,
) as inner:
for collection in inner:
- title_unescaped = unidecode(html.unescape(collection.title))
- normalized_title = normalize_titles(title_unescaped)
- alternate_titles = generate_title_variants(title_unescaped)
+ titles = collection_title_fields(collection.title)
+ title_unescaped = titles["title"]
# Use pathvalidate rather than the bare regex so the folder name
# is safe across Linux + Windows + Samba shares (handles
# reserved names like CON/AUX, max-length truncation, and
@@ -271,15 +268,10 @@ def get_collections(
imdb_id = None
tvdb_id = None
media_item = {
- "title": title_unescaped,
- "normalized_title": normalized_title,
+ **titles,
"location": library_name,
"year": year,
"folder": folder,
- "alternate_titles": alternate_titles["alternate_titles"],
- "normalized_alternate_titles": alternate_titles[
- "normalized_alternate_titles"
- ],
"library_name": library_name,
"asset_type": "collection",
"tmdb_id": tmdb_id,
diff --git a/tests/test_helper.py b/tests/test_helper.py
index 49cf68217..0e823760d 100644
--- a/tests/test_helper.py
+++ b/tests/test_helper.py
@@ -639,6 +639,7 @@ def test_is_match_both_years_present_and_differ_still_blocks():
('"Duna"', []),
('[1, "", "Duna"]', ["Duna"]),
(["Duna", 1], ["Duna"]),
+ pytest.param("[" * 100_000, [], id="deep-nesting"),
],
)
def test_parse_alternate_titles_keeps_only_string_titles(raw, titles):
diff --git a/tests/test_media_api_queries.py b/tests/test_media_api_queries.py
index e003387fe..48bfbee87 100644
--- a/tests/test_media_api_queries.py
+++ b/tests/test_media_api_queries.py
@@ -441,7 +441,7 @@ def test_create_collection_route_reads_back_the_created_row(db):
"""POST /collections returns the row it just upserted."""
resp = _client(db).post(
"/api/media/collections",
- json={"title": "Marvel", "instance_name": "plex1", "year": 2012},
+ json={"title": "Marvel", "instance_name": "plex1", "library_name": "Movies", "year": 2012},
)
assert resp.status_code == 200
collection = resp.json()["data"]["collection"]
@@ -457,53 +457,142 @@ def _collection_rows(db):
return [(r["title"], r["normalized_title"], r["normalized_alternate_titles"]) for r in rows]
-def test_create_collection_stores_titles_normalized_as_a_sync_does(db):
- resp = _client(db).post(
- "/api/media/collections",
- json={"title": "The Matrix Collection", "instance_name": "plex1", "alternate_titles": ["Matrix"]},
- )
- rows = _collection_rows(db)
- assert (resp.status_code, rows) == (200, [("The Matrix Collection", "thematrixcollection", '["matrix"]')])
+def _plex_sync(db, titles, library="Movies", instance="plex1"):
+ """The real PlexClient.get_collections + sync_collections_cache over fake plexapi collections."""
+ from types import SimpleNamespace
+
+ from backend.util.plex import PlexClient
+
+ found = [SimpleNamespace(title=t, smart=False, minYear=None) for t in titles]
+ section = SimpleNamespace(search=lambda libtype: found, type="movie")
+ client = PlexClient.__new__(PlexClient)
+ client.logger = _StubLog()
+ client.plex = SimpleNamespace(library=SimpleNamespace(section=lambda name: section))
+ db.collection.sync_collections_cache(instance, library, client.get_collections(library, include_smart=True))
+
+
+def _post_collection(client, **fields):
+ body = {"title": "Marvel", "instance_name": "plex1", "library_name": "Movies", **fields}
+ return client.post("/api/media/collections", json=body)
+
+
+@pytest.mark.parametrize("title", ["The Matrix Collection", "Amélie Collection", "Fast & Furious Collection"])
+def test_create_collection_stores_the_title_columns_a_sync_stores(tmp_path, title):
+ with ChubDB(_StubLog(), db_path=str(tmp_path / "api.db")) as api_db, ChubDB(
+ _StubLog(), db_path=str(tmp_path / "sync.db")
+ ) as sync_db:
+ resp = _post_collection(_client(api_db), title=f" {title} ")
+ _plex_sync(sync_db, [title])
+ assert (resp.status_code, _collection_rows(api_db)) == (200, _collection_rows(sync_db))
+
+
+@pytest.mark.parametrize(
+ "body, code",
+ [
+ ({"instance_name": "plex1", "library_name": "Movies"}, "MISSING_TITLE"),
+ ({"title": "Marvel", "instance_name": "plex1"}, "MISSING_LIBRARY"),
+ ],
+ ids=["no-title", "no-library"],
+)
+def test_create_collection_refuses_a_body_missing_a_key_field(db, body, code):
+ resp = _client(db).post("/api/media/collections", json=body)
+ assert (resp.status_code, resp.json()["error_code"], _collection_rows(db)) == (400, code, [])
@pytest.mark.parametrize(
"body",
- [{"alternate_titles": "Matrix"}, {"alternate_titles": ["Matrix", 7]}, {"alternate_titles": [" "]}, {"title": 7}],
- ids=["string", "number-in-list", "blank", "numeric-title"],
+ [
+ {"alternate_titles": "Matrix"},
+ {"alternate_titles": ["Matrix", 7]},
+ {"alternate_titles": [" "]},
+ {"title": 7},
+ {"title": " "},
+ {"library_name": ""},
+ {"year": [2008]},
+ {"year": True},
+ {"tmdb_id": 2**63},
+ {"imdb_id": 7},
+ ],
+ ids=["string", "number-in-list", "blank", "numeric-title", "blank-title", "blank-library", "list-year",
+ "bool-year", "huge-id", "numeric-imdb"],
)
-def test_create_collection_refuses_title_fields_of_the_wrong_shape(db, body):
- resp = _client(db).post("/api/media/collections", json={"title": "Marvel", "instance_name": "plex1", **body})
+def test_create_collection_refuses_fields_of_the_wrong_shape(db, body):
+ resp = _post_collection(_client(db), **body)
assert (resp.status_code, resp.json()["error_code"], _collection_rows(db)) == (400, "INVALID_FIELDS", [])
-def test_update_collection_renames_in_place_and_renormalizes(db):
- client = _client(db)
- created = client.post("/api/media/collections", json={"title": "Matrix", "instance_name": "plex1"})
- cid = created.json()["data"]["collection"]["id"]
- resp = client.put(
- f"/api/media/collections/{cid}",
- json={"title": "The Matrix Collection", "alternate_titles": ["Matrix"]},
- )
- rows = _collection_rows(db)
- assert (resp.status_code, resp.json()["data"]["collection"]["title"], rows) == (
- 200,
- "The Matrix Collection",
- [("The Matrix Collection", "thematrixcollection", '["matrix"]')],
- )
+@pytest.mark.parametrize(
+ "body, row",
+ [
+ ({"title": "Star Wars Collection"}, ("Star Wars Collection", "starwarscollection", '["starwarscollection", "starwars"]')),
+ (
+ {"title": "Star Wars Collection", "alternate_titles": ["Star Wars"]},
+ ("Star Wars Collection", "starwarscollection", '["starwars"]'),
+ ),
+ ],
+ ids=["variants-regenerated", "variants-given"],
+)
+def test_update_collection_renames_in_place_and_rederives_its_titles(db, body, row):
+ _plex_sync(db, ["The Matrix Collection"])
+ cid = db.collection.get_by_title_and_instance("The Matrix Collection", "plex1", "Movies")["id"]
+ resp = _client(db).put(f"/api/media/collections/{cid}", json=body)
+ assert (resp.status_code, resp.json()["data"]["collection"]["id"], _collection_rows(db)) == (200, cid, [row])
+
+
+class _ErrorLog(_StubLog):
+ """Keeps error() lines; every other log call is a no-op."""
+
+ def __init__(self):
+ self.errors = []
+
+ def error(self, msg, *_a, **_kw):
+ self.errors.append(str(msg))
@pytest.mark.parametrize(
"body, status, code",
- [({"title": ""}, 400, "INVALID_FIELDS"), ({"title": "Marvel"}, 409, "COLLECTION_EXISTS")],
- ids=["blank-title", "taken-title"],
+ [
+ ({"title": ""}, 400, "INVALID_FIELDS"),
+ ({"library_name": None}, 400, "INVALID_FIELDS"),
+ ({"name": "Avengers"}, 400, "NO_FIELDS"),
+ ({"title": "Marvel"}, 409, "COLLECTION_EXISTS"),
+ ],
+ ids=["blank-title", "null-library", "no-updatable-field", "taken-title"],
)
-def test_update_collection_refuses_a_title_it_cannot_store(db, body, status, code):
- client = _client(db)
- for title in ("Marvel", "Matrix"):
- client.post(
- "/api/media/collections", json={"title": title, "instance_name": "plex1", "library_name": "Movies"}
+def test_update_collection_refuses_a_change_it_cannot_store(tmp_path, body, status, code):
+ log = _ErrorLog()
+ with ChubDB(log, db_path=str(tmp_path / "chub.db")) as db:
+ _plex_sync(db, ["Marvel", "Matrix"])
+ cid = db.collection.get_by_title_and_instance("Matrix", "plex1", "Movies")["id"]
+ resp = _client(db).put(f"/api/media/collections/{cid}", json=body)
+ titles = [title for title, *_ in _collection_rows(db)]
+ assert (resp.status_code, resp.json()["error_code"], titles, log.errors) == (
+ status,
+ code,
+ ["Marvel", "Matrix"],
+ [],
)
- cid = db.collection.get_by_title_and_instance("Matrix", "plex1", "Movies")["id"]
- resp = client.put(f"/api/media/collections/{cid}", json=body)
+
+
+def test_update_collection_refuses_a_taken_title_in_no_library(db):
+ for title in ("Marvel", "Matrix"):
+ db.collection.upsert({"title": title, "normalized_title": title.lower(), "library_name": None}, "plex1")
+ cid = db.collection.get_by_title_and_instance("Matrix", "plex1", None)["id"]
+ resp = _client(db).put(f"/api/media/collections/{cid}", json={"title": "Marvel"})
+ titles = [title for title, *_ in _collection_rows(db)]
+ assert (resp.status_code, resp.json()["error_code"], titles) == (409, "COLLECTION_EXISTS", ["Marvel", "Matrix"])
+
+
+def test_update_collection_answers_404_when_a_sync_removed_the_row_first(db, monkeypatch):
+ _plex_sync(db, ["Marvel"])
+ cid = db.collection.get_by_title_and_instance("Marvel", "plex1", "Movies")["id"]
+ write = db.collection.update_row
+
+ def sync_lands_first(id, record):
+ _plex_sync(db, ["Avengers"])
+ return write(id, record)
+
+ monkeypatch.setattr(db.collection, "update_row", sync_lands_first)
+ resp = _client(db).put(f"/api/media/collections/{cid}", json={"year": 2012})
titles = [title for title, *_ in _collection_rows(db)]
- assert (resp.status_code, resp.json()["error_code"], titles) == (status, code, ["Marvel", "Matrix"])
+ assert (resp.status_code, resp.json()["error_code"], titles) == (404, "COLLECTION_NOT_FOUND", ["Avengers"])
diff --git a/tests/test_poster_renamerr.py b/tests/test_poster_renamerr.py
index 9584a72f3..67aae84b3 100644
--- a/tests/test_poster_renamerr.py
+++ b/tests/test_poster_renamerr.py
@@ -2987,3 +2987,8 @@ def _broken(*_a):
m.run()
assert m.logger.messages["warning"][-1] == "Could not log the run summary: summary bug"
+
+def test_title_match_reason_skips_a_poster_with_unreadable_alternate_titles():
+ poster = {"season_number": None, "normalized_title": "other", "normalized_alternate_titles": "matrix"}
+ reason = PosterRenamerr._title_match_reason(poster, {"season_number": None}, {"matrix"}, [])
+ assert reason == ""
diff --git a/tests/test_posters_queries.py b/tests/test_posters_queries.py
index 17511cf37..b3f0defba 100644
--- a/tests/test_posters_queries.py
+++ b/tests/test_posters_queries.py
@@ -938,7 +938,7 @@ def _boom(*_a, **_kw):
@pytest.mark.parametrize("stored", ['{"Duna": 1}', '[1, "Duna"]', "not json"])
def test_rank_candidates_ranks_a_row_with_odd_alternate_titles(db, stored):
- """A row stored with non-string alternate titles still ranks: only its string titles are looked up."""
+ """A row whose stored alternate titles are not a list of strings still ranks instead of raising."""
from backend.util.asset_candidates import rank_candidates
_seed_poster(db, "Dune", file="/src/Dune (2021).jpg")
From ae64a5faf66a9589683209f06f7959c2c9d878b1 Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Thu, 19 Nov 2026 06:14:21 +0800
Subject: [PATCH 4/6] refactor(media): split the collection field check below
the complexity line; widen its tests
_scalar_fields takes the year, ids, folder and library; the title test compares the raw alternate titles too, and a null now has a test.
---
backend/api/media_api.py | 12 ++++++++++--
tests/test_media_api_queries.py | 26 +++++++++++++++++++++-----
2 files changed, 31 insertions(+), 7 deletions(-)
diff --git a/backend/api/media_api.py b/backend/api/media_api.py
index a73654fc1..827918b81 100644
--- a/backend/api/media_api.py
+++ b/backend/api/media_api.py
@@ -753,8 +753,8 @@ def _is_text(value: Any) -> bool:
return isinstance(value, str) and bool(value.strip())
-def _collection_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
- """The collection columns ``payload`` sets, titles derived as a Plex sync derives them, or why one is invalid."""
+def _scalar_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
+ """The year, ids, folder and library ``payload`` sets, or why one is invalid."""
fields: Dict[str, Any] = {}
for key in ("year", "tmdb_id", "tvdb_id"):
if key in payload:
@@ -771,6 +771,14 @@ def _collection_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
if not _is_text(payload["library_name"]):
return {}, "Field 'library_name' must be a non-empty string"
fields["library_name"] = payload["library_name"]
+ return fields, None
+
+
+def _collection_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
+ """The collection columns ``payload`` sets (a title derived as a Plex sync derives it), or why one is invalid."""
+ fields, why = _scalar_fields(payload)
+ if why:
+ return {}, why
if "title" in payload:
if not _is_text(payload["title"]):
return {}, "Field 'title' must be a non-empty string"
diff --git a/tests/test_media_api_queries.py b/tests/test_media_api_queries.py
index 48bfbee87..89193f601 100644
--- a/tests/test_media_api_queries.py
+++ b/tests/test_media_api_queries.py
@@ -451,10 +451,10 @@ def test_create_collection_route_reads_back_the_created_row(db):
def _collection_rows(db):
rows = db.collection.execute_query(
- "SELECT title, normalized_title, normalized_alternate_titles FROM collections_cache ORDER BY id",
+ "SELECT title, normalized_title, alternate_titles, normalized_alternate_titles FROM collections_cache ORDER BY id",
fetch_all=True,
)
- return [(r["title"], r["normalized_title"], r["normalized_alternate_titles"]) for r in rows]
+ return [(r["title"], r["normalized_title"], r["alternate_titles"], r["normalized_alternate_titles"]) for r in rows]
def _plex_sync(db, titles, library="Movies", instance="plex1"):
@@ -524,10 +524,18 @@ def test_create_collection_refuses_fields_of_the_wrong_shape(db, body):
@pytest.mark.parametrize(
"body, row",
[
- ({"title": "Star Wars Collection"}, ("Star Wars Collection", "starwarscollection", '["starwarscollection", "starwars"]')),
(
- {"title": "Star Wars Collection", "alternate_titles": ["Star Wars"]},
- ("Star Wars Collection", "starwarscollection", '["starwars"]'),
+ {"title": "Star Wars Collection"},
+ (
+ "Star Wars Collection",
+ "starwarscollection",
+ '["Star Wars Collection", "Star Wars"]',
+ '["starwarscollection", "starwars"]',
+ ),
+ ),
+ (
+ {"title": "Star Wars Collection", "alternate_titles": [" Star Wars "]},
+ ("Star Wars Collection", "starwarscollection", '["Star Wars"]', '["starwars"]'),
),
],
ids=["variants-regenerated", "variants-given"],
@@ -539,6 +547,14 @@ def test_update_collection_renames_in_place_and_rederives_its_titles(db, body, r
assert (resp.status_code, resp.json()["data"]["collection"]["id"], _collection_rows(db)) == (200, cid, [row])
+def test_update_collection_clears_the_fields_it_is_sent_as_null(db):
+ created = _post_collection(_client(db), year=2012, tmdb_id=86311, folder="Marvel")
+ cid = created.json()["data"]["collection"]["id"]
+ resp = _client(db).put(f"/api/media/collections/{cid}", json={"year": None, "tmdb_id": None, "folder": None})
+ row = db.collection.get_by_id(cid)
+ assert (resp.status_code, row["year"], row["tmdb_id"], row["folder"]) == (200, None, None, None)
+
+
class _ErrorLog(_StubLog):
"""Keeps error() lines; every other log call is a no-op."""
From cda5d8f00a94343c11dccddacf3756a5e2355fc1 Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Thu, 19 Nov 2026 06:25:41 +0800
Subject: [PATCH 5/6] fix(media): refuse a collection title that decodes to
blank; an empty PUT answers NO_FIELDS
- A title like ' ' or an emoji-only one passed the blank check but stored a blank title once decoded to ASCII; the derived title is checked too.
- A supplied alternate title that normalizes to nothing is refused, so it cannot match every poster whose normalized title is empty.
- PUT {} reaches the NO_FIELDS answer; only a non-object body keeps the old 500.
---
backend/api/media_api.py | 15 ++++++++++-----
tests/test_media_api_queries.py | 23 ++++++++++++++++++++---
2 files changed, 30 insertions(+), 8 deletions(-)
diff --git a/backend/api/media_api.py b/backend/api/media_api.py
index 827918b81..6bd5a4084 100644
--- a/backend/api/media_api.py
+++ b/backend/api/media_api.py
@@ -782,13 +782,19 @@ def _collection_fields(payload: dict) -> Tuple[Dict[str, Any], Optional[str]]:
if "title" in payload:
if not _is_text(payload["title"]):
return {}, "Field 'title' must be a non-empty string"
- fields.update(collection_title_fields(payload["title"].strip()))
+ titles = collection_title_fields(payload["title"].strip())
+ if not _is_text(titles["title"]):
+ return {}, "Field 'title' is blank once decoded to ASCII"
+ fields.update(titles)
if "alternate_titles" in payload:
alts = payload["alternate_titles"]
if not isinstance(alts, list) or not all(_is_text(t) for t in alts):
return {}, "Field 'alternate_titles' must be a list of non-empty strings"
alts = [t.strip() for t in alts]
- fields.update(alternate_titles=alts, normalized_alternate_titles=[normalize_titles(t) for t in alts])
+ normalized = [normalize_titles(t) for t in alts]
+ if not all(normalized):
+ return {}, "Field 'alternate_titles' has a title that is blank once normalized"
+ fields.update(alternate_titles=alts, normalized_alternate_titles=normalized)
return fields, None
@@ -920,9 +926,8 @@ async def update_collection(
payload = await read_request_json(request)
if payload is BODY_TOO_LARGE:
return body_too_large_error()
- # An unusable body used to raise into the 500 handler; keep that
- # response — falling through would write the record unchanged.
- if not isinstance(payload, dict) or not payload:
+ # A non-object body used to raise into the 500 handler; keep that response.
+ if not isinstance(payload, dict):
return error(
"Error updating collection",
code="COLLECTION_UPDATE_ERROR",
diff --git a/tests/test_media_api_queries.py b/tests/test_media_api_queries.py
index 89193f601..1dcf641be 100644
--- a/tests/test_media_api_queries.py
+++ b/tests/test_media_api_queries.py
@@ -505,16 +505,32 @@ def test_create_collection_refuses_a_body_missing_a_key_field(db, body, code):
{"alternate_titles": "Matrix"},
{"alternate_titles": ["Matrix", 7]},
{"alternate_titles": [" "]},
+ {"alternate_titles": ["Marvel", " "]},
{"title": 7},
{"title": " "},
+ {"title": " "},
+ {"title": "\U0001F600"},
{"library_name": ""},
{"year": [2008]},
{"year": True},
{"tmdb_id": 2**63},
{"imdb_id": 7},
],
- ids=["string", "number-in-list", "blank", "numeric-title", "blank-title", "blank-library", "list-year",
- "bool-year", "huge-id", "numeric-imdb"],
+ ids=[
+ "string",
+ "number-in-list",
+ "blank",
+ "entity-blank-alternate",
+ "numeric-title",
+ "blank-title",
+ "entity-blank",
+ "emoji-only",
+ "blank-library",
+ "list-year",
+ "bool-year",
+ "huge-id",
+ "numeric-imdb",
+ ],
)
def test_create_collection_refuses_fields_of_the_wrong_shape(db, body):
resp = _post_collection(_client(db), **body)
@@ -571,9 +587,10 @@ def error(self, msg, *_a, **_kw):
({"title": ""}, 400, "INVALID_FIELDS"),
({"library_name": None}, 400, "INVALID_FIELDS"),
({"name": "Avengers"}, 400, "NO_FIELDS"),
+ ({}, 400, "NO_FIELDS"),
({"title": "Marvel"}, 409, "COLLECTION_EXISTS"),
],
- ids=["blank-title", "null-library", "no-updatable-field", "taken-title"],
+ ids=["blank-title", "null-library", "no-updatable-field", "empty-object", "taken-title"],
)
def test_update_collection_refuses_a_change_it_cannot_store(tmp_path, body, status, code):
log = _ErrorLog()
From 06193a3566fc7b5e7d954276572538fdf7d366cb Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Thu, 19 Nov 2026 07:27:20 +0800
Subject: [PATCH 6/6] fix(media): collection create checks instance_name's type
An object or blank instance_name passed the truthiness check and failed at SQLite binding with a 500; a missing key keeps MISSING_INSTANCE, a present but invalid one answers INVALID_FIELDS.
---
backend/api/media_api.py | 10 ++++++++--
tests/test_media_api_queries.py | 7 ++++++-
2 files changed, 14 insertions(+), 3 deletions(-)
diff --git a/backend/api/media_api.py b/backend/api/media_api.py
index 6bd5a4084..98ad3864c 100644
--- a/backend/api/media_api.py
+++ b/backend/api/media_api.py
@@ -844,13 +844,19 @@ async def create_collection(
"Field 'title' is required", code="MISSING_TITLE", status_code=400
)
- instance_name = payload.get("instance_name")
- if not instance_name:
+ if "instance_name" not in payload:
return error(
"Field 'instance_name' is required",
code="MISSING_INSTANCE",
status_code=400,
)
+ instance_name = payload["instance_name"]
+ if not _is_text(instance_name):
+ return error(
+ "Field 'instance_name' must be a non-empty string",
+ code="INVALID_FIELDS",
+ status_code=400,
+ )
if "library_name" not in payload:
return error(
diff --git a/tests/test_media_api_queries.py b/tests/test_media_api_queries.py
index 1dcf641be..b131e023e 100644
--- a/tests/test_media_api_queries.py
+++ b/tests/test_media_api_queries.py
@@ -491,8 +491,9 @@ def test_create_collection_stores_the_title_columns_a_sync_stores(tmp_path, titl
[
({"instance_name": "plex1", "library_name": "Movies"}, "MISSING_TITLE"),
({"title": "Marvel", "instance_name": "plex1"}, "MISSING_LIBRARY"),
+ ({"title": "Marvel", "library_name": "Movies"}, "MISSING_INSTANCE"),
],
- ids=["no-title", "no-library"],
+ ids=["no-title", "no-library", "no-instance"],
)
def test_create_collection_refuses_a_body_missing_a_key_field(db, body, code):
resp = _client(db).post("/api/media/collections", json=body)
@@ -511,6 +512,8 @@ def test_create_collection_refuses_a_body_missing_a_key_field(db, body, code):
{"title": " "},
{"title": "\U0001F600"},
{"library_name": ""},
+ {"instance_name": {"name": "plex1"}},
+ {"instance_name": " "},
{"year": [2008]},
{"year": True},
{"tmdb_id": 2**63},
@@ -526,6 +529,8 @@ def test_create_collection_refuses_a_body_missing_a_key_field(db, body, code):
"entity-blank",
"emoji-only",
"blank-library",
+ "object-instance",
+ "blank-instance",
"list-year",
"bool-year",
"huge-id",