Refactor: standardize adapters across media servers and trackers (#194)

* Refactor: standardize provider metadata, user-agent setup, and write skip handling

* Change: align scoped state writes with capture-mode safe behavior

* Change: standardize resolve, cache merge, and write logging semantics

* Refactor: standardize module write/index logging and provider result reporting

* Refactor: centralize scoped state, snapshot, restore, and unresolved helpers

* Refactor: move shared state handling into common helpers and standardize logging

* Refactor: reuse common state helpers and normalize ratings persistence flow

* Refactor: centralize snapshot and restore handling through common utilities

* Refactor: standardize module metadata, user-agent headers, and read-only write handling

* Change: standardize index and read-only write logging semantics

* Change: align scoped state writes with capture-mode safe behavior

* Refactor: standardize module metadata, user-agent handling, and provider write logging

* Change: align scoped state writes with capture-mode safe behavior

* Change: standardize index and write logging for ratings sync

* Change: standardize index and write logging for watchlist sync

* Refactor: standardize provider capabilities logging and shared module wiring

* Change: centralize shared logging, provider index, and resolver helpers

* Change: switch to common logger helpers and normalize history event logging

* Change: reuse common logging/time helpers and standardize write result events

* Change: reuse common logger helpers and standardize progress sync events

* Change: align helper behavior with updated shared provider conventions

* Change: move to shared logger helpers and normalize watchlist write logging

* Refactor: standardize provider internals logging and capability metadata

* Change: centralize shared logging, provider index, and resolver helpers

* Change: move to common logger helpers and normalize history sync logging

* Change: reuse common logger helpers and standardize progress sync logging

* Change: reuse common logging/time helpers and standardize write result event

* Change: align helper behavior with updated shared provider conventions

* Change: switch to shared logger helpers and normalize watchlist sync events

* Refactor: centralize provider behavior and normalize capability reporting

* Change: centralize shared logging, token, guid, and resolver helpers

* Refactor: move shared guid, cache, and write helpers into common utilities

* Refactor: reuse shared resolver and token helpers and normalize write result logging

* Refactor: switch to shared token, config, and logging helpers

* Refactor: align progress sync with shared logger and resolver helpers

* Change: align utility headers and helper behavior with shared plex common settings

---------

Co-authored-by: Pazzie van den Berg <[email protected]>

Author: cenodude

providers/sync/_mod_ANILIST.py

@@ -54,7 +54,9 @@ def _confirmed_keys(key_of, items: Iterable[Mapping[str, Any]], unresolved: Any)
         seen.add(k)
     return out
 
-__VERSION__ = "1.0.0"
+__VERSION__ = "1.0"
+os.environ.setdefault("CW_ANILIST_VERSION", __VERSION__)
+os.environ.setdefault("CW_ANILIST_UA", f"CrossWatch/{__VERSION__} (AniList)")
 __all__ = ["get_manifest", "ANILISTModule", "OPS"]
 
 def _health(status: str, ok: bool, latency_ms: int) -> None:
@@ -86,7 +88,7 @@ def emit(self, *args: Any, **kwargs: Any) -> None:
 
 
 GQL_URL = "https://graphql.anilist.co"
-UA = "CrossWatch/1.0"
+UA = os.environ.get("CW_ANILIST_UA") or os.environ.get("CW_UA") or f"CrossWatch/{__VERSION__} (AniList)"
 
 
 class ANILISTError(RuntimeError):
@@ -378,6 +380,7 @@ def feature_names(self) -> tuple[str, ...]:
 
     def build_index(self, feature: str, **kwargs: Any) -> dict[str, dict[str, Any]]:
         if feature != "watchlist" or not feat_watchlist:
+            _info("index_skipped", feature=feature, reason="disabled_or_missing")
             return {}
         return feat_watchlist.build_index(self)
 
@@ -394,6 +397,7 @@ def add(
         if dry_run:
             return {"ok": True, "count": len(lst), "dry_run": True}
         if feature != "watchlist" or not feat_watchlist:
+            _info("write_skipped", op="add", feature=feature, reason="disabled_or_missing")
             return {"ok": True, "count": 0, "unresolved": []}
         if hasattr(feat_watchlist, "add_detailed"):
             res = feat_watchlist.add_detailed(self, lst)  # type: ignore[attr-defined]
@@ -425,6 +429,7 @@ def remove(
         if dry_run:
             return {"ok": True, "count": len(lst), "dry_run": True}
         if feature != "watchlist" or not feat_watchlist:
+            _info("write_skipped", op="remove", feature=feature, reason="disabled_or_missing")
             return {"ok": True, "count": 0, "unresolved": []}
         count, unresolved = feat_watchlist.remove(self, lst)
         confirmed_keys = _confirmed_keys(self.key_of, lst, unresolved)

providers/sync/_mod_CROSSWATCH.py

@@ -92,7 +92,7 @@ def cw_log(provider: str, feature: str, level: str, msg: str, **fields: Any) ->
 except Exception:
     make_snapshot_progress = None  # type: ignore[assignment]
 
-__VERSION__ = "1.0.0"
+__VERSION__ = "1.0"
 __all__ = ["get_manifest", "CROSSWATCHModule", "OPS"]
 
 _FEATURES: dict[str, Any] = {}
@@ -261,7 +261,7 @@ def build_index(self, feature: str, **kwargs: Any) -> dict[str, dict[str, Any]]:
             return {}
         mod = _FEATURES.get(feature)
         if not mod:
-            _warn(feature, "index_skipped", reason="module_missing")
+            _info(feature, "index_skipped", reason="module_missing")
             return {}
         started = time.perf_counter()
         out = mod.build_index(self, **kwargs)
@@ -285,12 +285,12 @@ def add(
             return {"ok": True, "count": len(lst), "dry_run": True}
         mod = _FEATURES.get(feature)
         if not mod:
-            _warn(feature, "write_skipped", op="add", reason="module_missing")
+            _info(feature, "write_skipped", op="add", reason="module_missing")
             return {"ok": True, "count": 0, "unresolved": []}
         try:
             started = time.perf_counter()
             cnt, unresolved = mod.add(self, lst)
-            _info(feature, "write_done", op="add", count=int(cnt), unresolved=len(unresolved), dur_ms=int((time.perf_counter() - started) * 1000))
+            _info(feature, "write_done", op="add", ok=len(unresolved) == 0, applied=int(cnt), unresolved=len(unresolved), dur_ms=int((time.perf_counter() - started) * 1000))
             confirmed_keys = _confirmed_keys(_crosswatch_key_of, lst, unresolved)
             return {"ok": True, "count": int(cnt), "unresolved": unresolved, "confirmed_keys": confirmed_keys}
         except Exception as e:
@@ -314,12 +314,12 @@ def remove(
             return {"ok": True, "count": len(lst), "dry_run": True}
         mod = _FEATURES.get(feature)
         if not mod:
-            _warn(feature, "write_skipped", op="remove", reason="module_missing")
+            _info(feature, "write_skipped", op="remove", reason="module_missing")
             return {"ok": True, "count": 0, "unresolved": []}
         try:
             started = time.perf_counter()
             cnt, unresolved = mod.remove(self, lst)
-            _info(feature, "write_done", op="remove", count=int(cnt), unresolved=len(unresolved), dur_ms=int((time.perf_counter() - started) * 1000))
+            _info(feature, "write_done", op="remove", ok=len(unresolved) == 0, applied=int(cnt), unresolved=len(unresolved), dur_ms=int((time.perf_counter() - started) * 1000))
             confirmed_keys = _confirmed_keys(_crosswatch_key_of, lst, unresolved)
             return {"ok": True, "count": int(cnt), "unresolved": unresolved, "confirmed_keys": confirmed_keys}
         except Exception as e:

providers/sync/_mod_EMBY.py

@@ -16,7 +16,7 @@
 from ._log import log as cw_log
 
 from .emby._common import normalize as emby_normalize, key_of as emby_key_of
-from .emby._common import _pair_scope as _emby_pair_scope, state_file as _emby_state_file
+from .emby._common import _pair_scope as _emby_pair_scope, state_file as _emby_state_file, _is_capture_mode as _emby_capture_mode
 from .emby import _watchlist as feat_watchlist
 from .emby import _history as feat_history
 from .emby import _ratings as feat_ratings
@@ -76,10 +76,12 @@ def _confirmed_keys(key_of, items: Iterable[Mapping[str, Any]], unresolved: Any)
 except Exception:
     ctx = None  # type: ignore[assignment]
 
-__VERSION__ = "3.3.0"
+__VERSION__ = "1.0"
+os.environ.setdefault("CW_EMBY_VERSION", __VERSION__)
+os.environ.setdefault("CW_EMBY_UA", f"CrossWatch/{__VERSION__} (Emby)")
 __all__ = ["get_manifest", "EMBYModule", "OPS"]
 
-_DEF_UA = os.environ.get("CW_UA", f"CrossWatch/{__VERSION__} (Emby)")
+_DEF_UA = os.environ.get("CW_EMBY_UA") or os.environ.get("CW_UA") or f"CrossWatch/{__VERSION__} (Emby)"
 
 
 def _pick_instance_id(provider: str) -> str:
@@ -149,7 +151,7 @@ def _present_flags() -> dict[str, bool]:
 
 
 def _save_health_shadow(payload: Mapping[str, Any]) -> None:
-    if _emby_pair_scope() is None:
+    if _emby_pair_scope() is None or _emby_capture_mode():
         return
     try:
         path = _emby_state_file(_HEALTH_SHADOW_NAME)
@@ -172,7 +174,7 @@ def get_manifest() -> Mapping[str, Any]:
         "features": {
             "watchlist": True,
             "history": True,
-            "ratings": False,
+            "ratings": True,
             "playlists": False,
             "progress": True,
         },
@@ -399,7 +401,7 @@ def manifest(self) -> Mapping[str, Any]:
 
     @staticmethod
     def supported_features() -> dict[str, bool]:
-        toggles = {"watchlist": True, "history": True, "ratings": False, "playlists": False, "progress": True}
+        toggles = {"watchlist": True, "history": True, "ratings": True, "playlists": False, "progress": True}
         present = _present_flags()
         return {k: bool(toggles.get(k, False) and present.get(k, False)) for k in toggles.keys()}
 
@@ -545,7 +547,7 @@ def feature_names(self) -> tuple[str, ...]:
     def build_index(self, feature: str, **kwargs: Any) -> Mapping[str, dict[str, Any]]:
         f = (feature or "watchlist").lower()
         if not self._is_enabled(f):
-            _dbg("feature_disabled", op="build_index", feature=f)
+            _info("index_skipped", feature=f, reason="feature_disabled")
             return {}
         mod = _FEATURES.get(f)
         if not mod:
@@ -565,7 +567,7 @@ def add(
     ) -> Mapping[str, Any]:
         f = (feature or "watchlist").lower()
         if not self._is_enabled(f):
-            _dbg("feature_disabled", op="add", feature=f)
+            _info("write_skipped", op="add", feature=f, reason="feature_disabled")
             return {"ok": True, "count": 0, "unresolved": []}
         if dry_run:
             return self._dry_result(items)
@@ -592,7 +594,7 @@ def remove(
     ) -> Mapping[str, Any]:
         f = (feature or "watchlist").lower()
         if not self._is_enabled(f):
-            _dbg("feature_disabled", op="remove", feature=f)
+            _info("write_skipped", op="remove", feature=f, reason="feature_disabled")
             return {"ok": True, "count": 0, "unresolved": []}
         if dry_run:
             return self._dry_result(items)
@@ -676,4 +678,4 @@ def remove(
     def health(self, cfg: Mapping[str, Any]) -> Mapping[str, Any]:
         return self._adapter(cfg).health()
 
-OPS = _EmbyOPS()
+OPS = _EmbyOPS()

providers/sync/_mod_JELLYFIN.py

@@ -15,7 +15,7 @@
 
 from ._log import log as cw_log
 
-from .jellyfin._common import normalize as jelly_normalize, key_of as jelly_key_of, _pair_scope as _jf_pair_scope, state_file as _jf_state_file
+from .jellyfin._common import normalize as jelly_normalize, key_of as jelly_key_of, _pair_scope as _jf_pair_scope, state_file as _jf_state_file, _is_capture_mode as _jf_capture_mode
 from .jellyfin import _watchlist as feat_watchlist
 from .jellyfin import _history as feat_history
 from .jellyfin import _ratings as feat_ratings
@@ -74,10 +74,12 @@ def _confirmed_keys(key_of, items: Iterable[Mapping[str, Any]], unresolved: Any)
 except Exception:
     ctx = None  # type: ignore[assignment]
 
-__VERSION__ = "3.3.0"
+__VERSION__ = "1.0"
+os.environ.setdefault("CW_JELLYFIN_VERSION", __VERSION__)
+os.environ.setdefault("CW_JELLYFIN_UA", f"CrossWatch/{__VERSION__} (Jellyfin)")
 __all__ = ["get_manifest", "JELLYFINModule", "OPS"]
 
-_DEF_UA = os.environ.get("CW_UA", f"CrossWatch/{__VERSION__} (Jellyfin)")
+_DEF_UA = os.environ.get("CW_JELLYFIN_UA") or os.environ.get("CW_UA") or f"CrossWatch/{__VERSION__} (Jellyfin)"
 
 
 def _pick_instance_id(provider: str) -> str:
@@ -140,7 +142,7 @@ def _error(feature: str, msg: str, **fields: Any) -> None:
 
 
 def _save_health_shadow(payload: Mapping[str, Any]) -> None:
-    if _jf_pair_scope() is None:
+    if _jf_pair_scope() is None or _jf_capture_mode():
         return
     try:
         path = str(_jf_state_file(_HEALTH_SHADOW_NAME))
@@ -167,7 +169,7 @@ def get_manifest() -> Mapping[str, Any]:
         "features": {
             "watchlist": True,
             "history": True,
-            "ratings": False,
+            "ratings": True,
             "playlists": False,
             "progress": True,
         },
@@ -366,7 +368,7 @@ def manifest(self) -> Mapping[str, Any]:
 
     @staticmethod
     def supported_features() -> dict[str, bool]:
-        toggles = {"watchlist": True, "history": True, "ratings": False, "playlists": False, "progress": True}
+        toggles = {"watchlist": True, "history": True, "ratings": True, "playlists": False, "progress": True}
         present = _present_flags()
         return {k: bool(toggles.get(k, False) and present.get(k, False)) for k in toggles.keys()}
 
@@ -511,7 +513,7 @@ def feature_names(self) -> tuple[str, ...]:
     def build_index(self, feature: str, **kwargs: Any) -> Mapping[str, dict[str, Any]]:
         f = (feature or "watchlist").lower()
         if not self._is_enabled(f):
-            _dbg(f, "build index skipped", reason="feature disabled")
+            _info(f, "index_skipped", reason="feature_disabled")
             return {}
         mod = _FEATURES.get(f)
         if not mod:
@@ -531,7 +533,7 @@ def add(
     ) -> Mapping[str, Any]:
         f = (feature or "watchlist").lower()
         if not self._is_enabled(f):
-            _dbg(f, "add skipped", reason="feature disabled")
+            _info(f, "write_skipped", op="add", reason="feature_disabled")
             return {"ok": True, "count": 0, "unresolved": []}
         if dry_run:
             return self._dry_result(items)
@@ -558,7 +560,7 @@ def remove(
     ) -> Mapping[str, Any]:
         f = (feature or "watchlist").lower()
         if not self._is_enabled(f):
-            _dbg(f, "remove skipped", reason="feature disabled")
+            _info(f, "write_skipped", op="remove", reason="feature_disabled")
             return {"ok": True, "count": 0, "unresolved": []}
         if dry_run:
             return self._dry_result(items)
@@ -644,4 +646,4 @@ def remove(
     def health(self, cfg: Mapping[str, Any]) -> Mapping[str, Any]:
         return self._adapter(cfg).health()
 
-OPS = _JellyfinOPS()
+OPS = _JellyfinOPS()

providers/sync/_mod_PLEX.py

@@ -35,7 +35,9 @@ def _error(event: str, **fields: Any) -> None:
 def _log(msg: str) -> None:
     _dbg(msg)
 
-__VERSION__ = "5.2.1"
+__VERSION__ = "1.0"
+os.environ.setdefault("CW_PLEX_VERSION", __VERSION__)
+os.environ.setdefault("CW_PLEX_UA", f"CrossWatch/{__VERSION__} (Plex)")
 __all__ = ["get_manifest", "PLEXModule", "PLEXClient", "PLEXError", "PLEXAuthError", "PLEXNotFound", "OPS"]
 
 try:
@@ -1047,7 +1049,7 @@ def feature_names(self) -> tuple[str, ...]:
 
     def build_index(self, feature: str, **kwargs) -> dict[str, dict[str, Any]]:
         if not self._is_enabled(feature) or feature not in _FEATURES:
-            _info("feature_skipped", op="build_index", feature=feature, reason="disabled_or_missing")
+            _info("index_skipped", feature=feature, reason="disabled_or_missing")
             return {}
         mod = _FEATURES.get(feature)
         return mod.build_index(self, **kwargs) if mod else {}
@@ -1063,13 +1065,13 @@ def add(
         if not lst:
             return {"ok": True, "count": 0}
         if not self._is_enabled(feature) or feature not in _FEATURES:
-            _info("feature_skipped", op="add", feature=feature, reason="disabled_or_missing")
+            _info("write_skipped", op="add", feature=feature, reason="disabled_or_missing")
             return {"ok": True, "count": 0, "unresolved": []}
         if dry_run:
             return {"ok": True, "count": len(lst), "dry_run": True}
         mod = _FEATURES.get(feature)
         if not mod:
-            _warn("feature_missing", op="add", feature=feature)
+            _warn("write_skipped", op="add", feature=feature, reason="missing_feature")
             return {"ok": True, "count": 0, "unresolved": []}
         try:
             cnt, unresolved = mod.add(self, lst)
@@ -1115,13 +1117,13 @@ def remove(
         if not lst:
             return {"ok": True, "count": 0}
         if not self._is_enabled(feature) or feature not in _FEATURES:
-            _info("feature_skipped", op="remove", feature=feature, reason="disabled_or_missing")
+            _info("write_skipped", op="remove", feature=feature, reason="disabled_or_missing")
             return {"ok": True, "count": 0, "unresolved": []}
         if dry_run:
             return {"ok": True, "count": len(lst), "dry_run": True}
         mod = _FEATURES.get(feature)
         if not mod:
-            _warn("feature_missing", op="remove", feature=feature)
+            _warn("write_skipped", op="remove", feature=feature, reason="missing_feature")
             return {"ok": True, "count": 0, "unresolved": []}
         try:
             cnt, unresolved = mod.remove(self, lst)

providers/sync/_mod_TAUTULLI.py

@@ -6,6 +6,7 @@
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from typing import Any
+import os
 import time
 
 from ._log import log as cw_log
@@ -16,7 +17,9 @@
 except Exception:
     ctx = None  # type: ignore[assignment]
 
-__VERSION__ = "1.0.0"
+__VERSION__ = "1.0"
+os.environ.setdefault("CW_TAUTULLI_VERSION", __VERSION__)
+os.environ.setdefault("CW_TAUTULLI_UA", f"CrossWatch/{__VERSION__} (Tautulli)")
 __all__ = ["get_manifest", "OPS"]
 
 def _health(status: str, ok: bool, latency_ms: int) -> None:
@@ -106,6 +109,11 @@ def __init__(self, cfg: TAUTULLIConfig, raw_cfg: Mapping[str, Any]):
         self.cfg = cfg
         self.raw_cfg = raw_cfg
         self.session = build_session("TAUTULLI", ctx, feature_label=_label)
+        try:
+            self.session.headers.setdefault("User-Agent", os.environ.get("CW_TAUTULLI_UA") or f"CrossWatch/{__VERSION__} (Tautulli)")
+            self.session.headers.setdefault("Accept", "application/json")
+        except Exception:
+            pass
 
     def _url(self) -> str:
         return f"{self.cfg.server_url}/api/v2"
@@ -130,12 +138,12 @@ def call(self, cmd: str, **params: Any) -> Any:
         if isinstance(resp, dict):
             if str(resp.get("result") or "").lower() != "success":
                 msg = str(resp.get("message") or "unknown error")
-                _warn("api result not success", cmd=cmd, message=msg)
+                _warn("http_failed", op=cmd, message=msg)
                 raise RuntimeError(msg)
             return resp.get("data")
 
         if r.status_code >= 400:
-            _warn("http non ok", cmd=cmd, status=r.status_code)
+            _warn("http_failed", op=cmd, status=r.status_code)
             raise RuntimeError(f"HTTP {r.status_code}")
         return j
 
@@ -185,24 +193,28 @@ def activities(self) -> Mapping[str, Any]:
                 ts = rows[0].get("date") or rows[0].get("started")
             return {"history": str(ts or "0"), "updated_at": str(ts or "0")}
         except Exception as e:
-            _dbg("activities failed", error=str(e))
+            _dbg("activities_failed", error=str(e))
             return {"updated_at": "0"}
 
     def build_index(self, feature: str) -> Mapping[str, dict[str, Any]]:
         if feature != "history":
-            _dbg("unsupported feature", requested=feature)
+            _info("index_skipped", feature=feature, reason="disabled_or_missing")
             return {}
         from .tautulli import _history
 
         adapter = _HistoryAdapter(cfg=self.client.raw_cfg, client=self.client)
         return _history.build_index(adapter)
 
     def add(self, feature: str, items: Iterable[Mapping[str, Any]], *, dry_run: bool = False) -> dict[str, Any]:
+        if feature != "history":
+            return {"ok": True, "count": 0, "unresolved": [], "reason": "disabled_or_missing"}
         from .tautulli import _history
 
         return _history.add(self, items, dry_run=dry_run)
 
     def remove(self, feature: str, items: Iterable[Mapping[str, Any]], *, dry_run: bool = False) -> dict[str, Any]:
+        if feature != "history":
+            return {"ok": True, "count": 0, "unresolved": [], "reason": "disabled_or_missing"}
         from .tautulli import _history
 
         return _history.remove(self, items, dry_run=dry_run)