SpotiFLAC 4.2.2__tar.gz → 4.2.3__tar.gz

{spotiflac-4.2.2/SpotiFLAC.egg-info → spotiflac-4.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SpotiFLAC
-Version: 4.2.2
+Version: 4.2.3
 Summary: Fetch Spotify track metadata and retrieve matching lossless audio through configurable Tidal, Qobuz & Amazon Music provider backends.
 Author:  BartolomeoRusso9
 License: MIT

spotiflac-4.2.3/SpotiFLAC/core/provider_cooldown.py

@@ -0,0 +1,226 @@
+"""core/provider_cooldown.py — a provider that asked for a break gets one.
+
+tidal-py tries the Community (signed-desktop) gateway first on every track.
+That gateway has enforced pauses — the SpotiFLAC desktop logic it comes from
+blocks downloads for a while — and during one it answers 503 with how long
+the pause lasts: "Please try again in about 51 minute(s)". The extension logs
+that, falls back to public mirrors that time out, and fails; on the next
+track it does all of it again. Roughly 25 seconds per track went to a
+provider that had said, in words, when it would work again.
+
+This reads that answer out of the extension's log and keeps the provider out
+of the rotation until then. The provider is not removed: once the pause is
+over it is tried first again, in the order the user configured. The pause is
+kept in the cache directory, so a restart does not forget it and start the
+25-second detour over.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from .atomic_io import write_json_atomic
+from .paths import cache_path
+
+logger = logging.getLogger(__name__)
+
+_CACHE_FILE_NAME = "provider_cooldowns.json"
+
+#: Module (and so logger) prefix of the Python `.sflx` extensions — see
+#: extensions/python_provider._module_name.
+_PLUGIN_PREFIX = "SpotiFLAC.extensions_plugins."
+
+#: Logger prefix of the JS `.sflx` extensions. They have no module of their
+#: own — the bridge relays their log lines from Node — so JSRuntime sends
+#: them out under a child logger named for the extension, which is what
+#: makes one extension's 503 tellable from another's.
+_JS_LOG_PREFIX = "SpotiFLAC.extensions.runtime."
+
+#: How a JS extension provider is named in PROVIDER_REGISTRY — see
+#: extensions/provider.JSExtensionProvider.
+_EXT_NAME_PREFIX = "ext:"
+
+_UNAVAILABLE = re.compile(r"\b503\b")
+_WAIT = re.compile(r"try again in (?:about )?(\d+)\s*(minute|min|hour|h)", re.I)
+
+#: A pause longer than a day is read as a misparse, not as a promise.
+_MAX_PAUSE_S = 24 * 3600
+
+_lock = threading.Lock()
+
+
+def _cache_file() -> Path:
+    return cache_path(_CACHE_FILE_NAME)
+
+
+def _load() -> dict[str, dict]:
+    try:
+        data = json.loads(_cache_file().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _save(data: dict[str, dict]) -> None:
+    try:
+        write_json_atomic(_cache_file(), data)
+    except OSError:
+        logger.debug("[cooldown] could not write %s", _cache_file(), exc_info=True)
+
+
+def pause_seconds(message: str) -> int:
+    """Seconds a 503 asks to wait before trying again, or 0 if it names none."""
+    if not _UNAVAILABLE.search(message):
+        return 0
+    match = _WAIT.search(message)
+    if not match:
+        return 0
+    amount = int(match.group(1))
+    unit = match.group(2).lower()
+    seconds = amount * 3600 if unit.startswith("h") else amount * 60
+    return min(seconds, _MAX_PAUSE_S)
+
+
+def extension_key(logger_name: str) -> str:
+    """The pause key of the extension that logger belongs to; "" for the host.
+
+    Both kinds of extension are keyed by the name they are installed under:
+
+      "SpotiFLAC.extensions_plugins.tidal_py"  → "tidal-py"   (Python)
+      "SpotiFLAC.extensions.runtime.tidal-web" → "tidal-web"  (JS)
+
+    A Python extension is a module, so its underscores are the ones a module
+    name is obliged to have; a JS extension's logger is named for the
+    extension directly and is left alone.
+    """
+    if logger_name.startswith(_PLUGIN_PREFIX):
+        return logger_name[len(_PLUGIN_PREFIX) :].split(".", 1)[0].replace("_", "-")
+    if logger_name.startswith(_JS_LOG_PREFIX):
+        return logger_name[len(_JS_LOG_PREFIX) :].split(".", 1)[0]
+    return ""
+
+
+def provider_key(provider: Any) -> str:
+    """The pause key of a provider object, or "" if it is not an extension.
+
+    Two ways to the same key, because the two kinds of extension carry their
+    identity in different places. PythonExtensionProvider returns the
+    extension's own provider instance, so the class's module is the
+    extension module whose logger reported the 503. A JS extension is a
+    JSExtensionProvider whatever the extension is, so its module says
+    nothing about which one — its registry name does: "ext:tidal-web" is the
+    extension "tidal-web", the key its log lines already arrive under.
+
+    Keying both from the installed name is what lets pause() and
+    usable_providers() agree: a pause started from a JS extension's log has
+    to name the provider object that gets skipped for it.
+    """
+    key = extension_key(type(provider).__module__)
+    if key:
+        return key
+    name = str(getattr(provider, "name", "") or "")
+    if name.startswith(_EXT_NAME_PREFIX):
+        return name[len(_EXT_NAME_PREFIX) :]
+    return ""
+
+
+def pause(key: str, seconds: float, reason: str = "", now: float | None = None) -> None:
+    """Keeps `key` out of the rotation for `seconds`. A shorter pause never
+    cuts a longer one short."""
+    if not key or seconds <= 0:
+        return
+    now = time.time() if now is None else now
+    until = now + seconds
+    with _lock:
+        data = _load()
+        try:
+            current = float((data.get(key) or {}).get("until", 0))
+        except (TypeError, ValueError):
+            current = 0.0
+        if current >= until:
+            return
+        data[key] = {"until": until, "reason": reason[:300]}
+        _save(data)
+    logger.warning(
+        "[cooldown] %s paused for %d min (until %s): the service asked to try again later",
+        key,
+        max(1, round(seconds / 60)),
+        time.strftime("%H:%M", time.localtime(until)),
+    )
+
+
+def remaining(key: str, now: float | None = None) -> float:
+    """Seconds left on `key`'s pause; 0 when it has none."""
+    if not key:
+        return 0.0
+    now = time.time() if now is None else now
+    try:
+        until = float((_load().get(key) or {}).get("until", 0))
+    except (TypeError, ValueError):
+        return 0.0
+    return max(0.0, until - now)
+
+
+def usable_providers(providers: list) -> list:
+    """`providers` without the ones on a pause, in the same order.
+
+    All of them when every one is paused: a track with nothing left to try
+    would fail without an attempt, and a pause is an estimate, not a ban.
+    """
+    active: list = []
+    paused: list[tuple[Any, float]] = []
+    for provider in providers:
+        left = remaining(provider_key(provider))
+        if left > 0:
+            paused.append((provider, left))
+        else:
+            active.append(provider)
+    if not paused or not active:
+        return list(providers)
+    for provider, left in paused:
+        logger.info(
+            "[cooldown] Skipping %s: paused for another %d min",
+            provider_key(provider),
+            max(1, round(left / 60)),
+        )
+    return active
+
+
+class _PauseWatcher(logging.Handler):
+    """Turns an extension's "503 … try again in about N minute(s)" into a pause."""
+
+    def __init__(self) -> None:
+        super().__init__(level=logging.WARNING)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        key = extension_key(record.name)
+        if not key:
+            return
+        try:
+            message = record.getMessage()
+        except Exception:
+            return
+        seconds = pause_seconds(message)
+        if seconds:
+            pause(key, seconds, message)
+
+
+_watcher = _PauseWatcher()
+
+
+def watch_extension_logs() -> None:
+    """Attaches the watcher to the root logger, again if it was removed.
+
+    Cheap enough to call once per track, which it is: the GUI and --web
+    reconfigure logging with basicConfig(force=True) when the log level
+    changes, and that drops every handler on the root logger.
+    """
+    root = logging.getLogger()
+    if _watcher not in root.handlers:
+        root.addHandler(_watcher)

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/core/signed_session_desktop.py

@@ -18,9 +18,30 @@ from http.server import BaseHTTPRequestHandler, HTTPServer
 import requests
 
 from SpotiFLAC.core import get_community_url
+from SpotiFLAC.core.signed_session_errors import (
+    parse_session_error,
+    retry_after_header_seconds,
+)
 
 logger = logging.getLogger(__name__)
 
+
+def _refusal_message(what: str, resp) -> str:
+    """ "<what> returned HTTP <code>", with the wait the service asked for.
+
+    The exception raised from it is all a caller ever sees of the response,
+    and a bare "returned HTTP 429" dropped the one thing that says how long
+    the address is limited for. Read from the Retry-After header, else from
+    the gateway's error envelope (see signed_session_errors).
+    """
+    msg = f"{what} returned HTTP {resp.status_code}"
+    wait = retry_after_header_seconds(resp.headers.get("Retry-After"))
+    if not wait:
+        with contextlib.suppress(Exception):
+            wait = parse_session_error(resp.content).retry_after_seconds
+    return f"{msg}, retry after {wait}s" if wait else msg
+
+
 # Costanti
 COMMUNITY_SESSION_SKEW = timedelta(minutes=5)
 # The callback grant is consumed by ``run_community_verification()`` from a
@@ -309,7 +330,7 @@ def run_community_verification(record: CommunitySessionRecord) -> str:
 
         resp = requests.get(bootstrap_url, params=params, timeout=15)
         if resp.status_code != 200:
-            msg = f"verification bootstrap returned HTTP {resp.status_code}"
+            msg = _refusal_message("verification bootstrap", resp)
             raise Exception(msg)
 
         result = resp.json()
@@ -515,7 +536,7 @@ def exchange_community_grant(
     resp = requests.post(url, json=payload, timeout=15)
 
     if resp.status_code != 200:
-        msg = f"session exchange returned HTTP {resp.status_code}"
+        msg = _refusal_message("session exchange", resp)
         raise Exception(msg)
 
     data = resp.json()

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/core/signed_session_errors.py

@@ -23,7 +23,10 @@ whose contract is what the gateway actually emits.
 from __future__ import annotations
 
 import json
+import math
 from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
 from typing import Any
 
 #: The session is gone and can be re-established without the user.
@@ -59,6 +62,32 @@ class SessionError:
         return self.origin == "provider"
 
 
+def retry_after_header_seconds(raw: Any) -> int:
+    """Seconds a Retry-After header asks for, or 0. Never raises.
+
+    RFC 9110 allows two forms, a count of seconds and an HTTP date, and the
+    bridge's retryAfterSeconds() (extensions/_bridge.js) has always read
+    both. The Python readers accepted only digits, so a gateway answering
+    with the date form read here as "no Retry-After" and the wait fell
+    through to the error envelope — or to nothing. A date already in the
+    past is 0: the wait is over.
+    """
+    text = str(raw or "").strip()
+    if text.isdigit():
+        return int(text)
+    try:
+        when = parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return 0
+    if when is None:
+        return 0
+    # An HTTP date is UTC by definition, but parsedate_to_datetime returns a
+    # naive datetime for the obsolete formats that carry no offset.
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0, math.ceil((when - datetime.now(timezone.utc)).total_seconds()))
+
+
 def parse_session_error(body: Any) -> SessionError:
     """Reads the envelope out of a response body. Never raises.
 

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/core/signed_session_mobile.py

@@ -23,7 +23,11 @@ from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
 
 import httpx
 
-from .signed_session_errors import parse_session_error, should_clear_session
+from .signed_session_errors import (
+    parse_session_error,
+    retry_after_header_seconds,
+    should_clear_session,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -1187,9 +1191,9 @@ def _retry_after_from(exc: BaseException) -> int:
     response = getattr(exc, "response", None)
     if response is None:
         return 0
-    raw = (response.headers.get("Retry-After") or "").strip()
-    if raw.isdigit():
-        return int(raw)
+    wait = retry_after_header_seconds(response.headers.get("Retry-After"))
+    if wait:
+        return wait
     with contextlib.suppress(Exception):
         return parse_session_error(response.content).retry_after_seconds
     return 0
@@ -1329,6 +1333,18 @@ async def perform_signed_fetch(
         resp = await client.request(method, path, json_body=body, extra_headers=headers)
         elapsed = time.monotonic() - started
 
+        # How long a refusal says to wait: the Retry-After header first, else
+        # the gateway's error envelope. Worked out before the log lines below,
+        # because a 429 is logged with it: the extensions retry a rate limit
+        # on their own and say nothing, so the log held no record of how long
+        # an address had been limited for.
+        ok = 200 <= resp.status_code < 300
+        retry_after = retry_after_header_seconds(resp.headers.get("Retry-After"))
+        # Parsed only for a refusal: a success body is the provider's payload,
+        # sometimes a large manifest, and never an envelope.
+        err = None if ok else parse_session_error(getattr(resp, "content", b""))
+        wait = retry_after or (err.retry_after_seconds if err else 0)
+
         if is_ticket:
             granted = False
             if 200 <= resp.status_code < 300:
@@ -1364,6 +1380,15 @@ async def perform_signed_fetch(
                 elapsed,
             )
 
+        if resp.status_code == 429:
+            logger.warning(
+                "[signed_session:%s] HTTP 429 for %s %s — %s",
+                client.namespace,
+                method,
+                path,
+                f"retry after {wait}s" if wait else "no Retry-After",
+            )
+
         # Same distinction as in request(): re-bootstrapping and demanding
         # verification are session decisions, and a provider's refusal is
         # not grounds for either.
@@ -1374,12 +1399,6 @@ async def perform_signed_fetch(
             if isinstance(retry_auth_url, str) and retry_auth_url:
                 return {"needsVerification": True, "auth_url": retry_auth_url}
 
-        retry_after = 0
-        raw_retry_after = resp.headers.get("Retry-After", "").strip()
-        if raw_retry_after.isdigit():
-            retry_after = max(0, int(raw_retry_after))
-
-        ok = 200 <= resp.status_code < 300
         result = {
             "statusCode": resp.status_code,
             "status": resp.status_code,
@@ -1405,8 +1424,7 @@ async def perform_signed_fetch(
         # hand the gateway a switch to end a download early, and whether it
         # sets them that precisely on transient failures is not something
         # this side can verify.
-        if not ok:
-            err = parse_session_error(getattr(resp, "content", b""))
+        if err is not None:
             if err.retry_mode:
                 result["retryMode"] = err.retry_mode
             if not retry_after and err.retry_after_seconds:

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/downloader.py

@@ -1043,10 +1043,15 @@ async def _download_one_pass_async(
     download_one_async(), when a Hi-Res file turns out to be upsampled and
     is fetched again at LOSSLESS.
     """
+    from .core import provider_cooldown
+
     stop_event = asyncio.Event()
     DownloadManager()
     errors: dict[str, str] = {}
     started_at = time.monotonic()
+    # A provider that answered "503 … try again in about N minutes" is kept
+    # out of the rotation until then (see core/provider_cooldown.py).
+    provider_cooldown.watch_extension_logs()
 
     # What was asked for, before any provider gets to write its own findings
     # onto the shared TrackMetadata. Taken once for the whole track, not once
@@ -1095,7 +1100,9 @@ async def _download_one_pass_async(
             await asyncio.sleep(wait)
             errors.clear()
 
-        for idx, provider in enumerate(providers):
+        # Per attempt, not per track: a pause that starts on the first
+        # attempt already applies to the retries.
+        for idx, provider in enumerate(provider_cooldown.usable_providers(providers)):
             if idx > 0:
                 is_ext = provider.name.startswith("ext:")
                 target_type = "extension" if is_ext else "provider"

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/extensions/_bridge.js

@@ -634,6 +634,32 @@ async function handleBridgeRequest() {
   Atomics.notify(STATE, 0, 1);
 }
 
+/** Seconds a Retry-After header asks for — a number of seconds or an HTTP
+ *  date — or 0 when there is none. */
+function retryAfterSeconds(headers) {
+  const raw = String((headers && headers['retry-after']) || '').trim();
+  if (/^\d+$/.test(raw)) return Number(raw);
+  const when = Date.parse(raw);
+  return Number.isNaN(when) ? 0 : Math.max(0, Math.ceil((when - Date.now()) / 1000));
+}
+
+/** Logs a rate limit at warning level, with the wait it asked for.
+ *  The extensions retry a 429 on their own and seldom say so, which left the
+ *  host with no record of how long an address had been limited. Sent to
+ *  Python as a log message on stdout rather than written to stderr, which
+ *  Python only reads at debug level. */
+function logRateLimited(what, rawUrl, headers) {
+  let host = String(rawUrl);
+  try { host = new URL(rawUrl).host; } catch (_) { /* keep the raw string */ }
+  const seconds = retryAfterSeconds(headers);
+  const wait = seconds > 0 ? `retry after ${seconds}s` : 'no Retry-After';
+  process.stdout.write(JSON.stringify({
+    type: 'log',
+    level: 'warning',
+    msg: `[http] HTTP 429 from ${host} (${what}) — ${wait}`,
+  }) + '\n');
+}
+
 /** The User-Agent a request gets when the extension names none. The mobile
  *  app's Go client always sends one of its own; Node sends nothing, and
  *  some sites refuse a request without it outright. */
@@ -699,13 +725,16 @@ function nodeHttpRequest(method, rawUrl, body, headers, _depth = 0) {
       }
       res.setEncoding('utf8');
       res.on('data', (d) => { data += d; });
-      res.on('end', () => resolve({
-        statusCode: res.statusCode,
-        body:       data,
-        headers:    res.headers,
-        url:        rawUrl,
-        error:      null,
-      }));
+      res.on('end', () => {
+        if (res.statusCode === 429) logRateLimited(method, rawUrl, res.headers);
+        resolve({
+          statusCode: res.statusCode,
+          body:       data,
+          headers:    res.headers,
+          url:        rawUrl,
+          error:      null,
+        });
+      });
     });
     req.on('error', (e) => resolve({ statusCode: 0, body: '', error: e.message, url: rawUrl }));
     req.setTimeout(30_000, () => { req.destroy(); resolve({ statusCode: 0, body: '', error: 'timeout' }); });
@@ -785,6 +814,7 @@ function nodeFileDownload(rawUrl, outputPath, opts, callId) {
     const stream = fs.createWriteStream(outputPath);
     const req = lib.request(reqOpts, (res) => {
       if (res.statusCode >= 400) {
+        if (res.statusCode === 429) logRateLimited('file download', rawUrl, res.headers);
         res.resume();
         stream.close();
         fs.unlink(outputPath, () => {});
@@ -929,6 +959,7 @@ function nodeFileDownloadSegments(urls, outputPath, opts, callId) {
           return;
         }
         if (status >= 400) {
+          if (status === 429) logRateLimited('segment', rawUrl, res.headers);
           res.resume();
           // 403/410 is how every signed CDN says "this URL has aged out".
           const expired = status === 403 || status === 410;
@@ -936,7 +967,7 @@ function nodeFileDownloadSegments(urls, outputPath, opts, callId) {
             ok: false,
             error: `HTTP ${status}`,
             error_type: expired ? 'expired_stream' : 'download_error',
-            retry_after_seconds: Number(res.headers['retry-after'] || 0) || 0,
+            retry_after_seconds: retryAfterSeconds(res.headers),
           });
           return;
         }

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/extensions/provider.py

@@ -216,6 +216,7 @@ class JSExtensionProvider(BaseProvider):
                 else None
             ),
             cancelled_probe=self._stop_requested,
+            ext_name=self._ext.name,
         )
         rt.start()
         return rt

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC/extensions/runtime.py

@@ -88,6 +88,7 @@ class JSRuntime:
         startup_timeout: float = 20.0,
         session_handler: Callable[[str, str, Any, dict], Awaitable[dict]] | None = None,
         cancelled_probe: Callable[[], bool] | None = None,
+        ext_name: str = "",
     ) -> None:
         self.ext_path = Path(ext_path)
         self.settings = settings or {}
@@ -98,6 +99,16 @@ class JSRuntime:
         # never cached here: the point of the probe is that the answer
         # changes underneath a call that is already running.
         self.cancelled_probe = cancelled_probe
+        # The extension's own log lines go out under a logger named for the
+        # extension. A JS extension has no module of its own to be known by,
+        # and the host needs to know *which* one said "503 … try again in
+        # about 51 minute(s)" to keep that one out of the rotation until
+        # then (core/provider_cooldown.py). Unnamed — a bare JSRuntime in a
+        # test — they stay on this module's logger, as they always were.
+        self.ext_name = ext_name
+        self._ext_logger = (
+            logging.getLogger(f"{__name__}.{ext_name}") if ext_name else logger
+        )
 
         self._proc: subprocess.Popen | None = None
         self._seq = 0
@@ -410,7 +421,8 @@ class JSRuntime:
             return
         if msg.get("type") == "log":
             level = msg.get("level", "info")
-            getattr(logger, level, logger.info)("[EXT] %s", msg.get("msg", ""))
+            log = self._ext_logger
+            getattr(log, level, log.info)("[EXT] %s", msg.get("msg", ""))
             return
         if msg.get("type") == "session_signed_fetch":
             self._handle_session_signed_fetch(msg)

{spotiflac-4.2.2 → spotiflac-4.2.3/SpotiFLAC.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SpotiFLAC
-Version: 4.2.2
+Version: 4.2.3
 Summary: Fetch Spotify track metadata and retrieve matching lossless audio through configurable Tidal, Qobuz & Amazon Music provider backends.
 Author:  BartolomeoRusso9
 License: MIT

{spotiflac-4.2.2 → spotiflac-4.2.3}/SpotiFLAC.egg-info/SOURCES.txt

@@ -87,6 +87,7 @@ SpotiFLAC/core/paths.py
 SpotiFLAC/core/playlist_sync.py
 SpotiFLAC/core/profiles.py
 SpotiFLAC/core/progress.py
+SpotiFLAC/core/provider_cooldown.py
 SpotiFLAC/core/provider_stats.py
 SpotiFLAC/core/quality.py
 SpotiFLAC/core/recording_guard.py
@@ -282,7 +283,9 @@ tests/test_profiles.py
 tests/test_progress_and_csv_counters.py
 tests/test_progress_cross_loop.py
 tests/test_progress_manager_loops.py
+tests/test_provider_cooldown.py
 tests/test_quotas.py
+tests/test_rate_limit_logging.py
 tests/test_recording_guard.py
 tests/test_registry_signing_cli.py
 tests/test_release_date_hydration.py

{spotiflac-4.2.2 → spotiflac-4.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "SpotiFLAC"
-version = "4.2.2"
+version = "4.2.3"
 description = "Fetch Spotify track metadata and retrieve matching lossless audio through configurable Tidal, Qobuz & Amazon Music provider backends."
 readme = "README.md"
 # 3.10, not 3.9: core/models.py declares PEP 604 unions (`str | None`) on