feat(debug): add comprehensive debug logging for downloaders and muxing

unshackle/core/downloaders/curl_impersonate.py

@@ -11,7 +11,7 @@ from rich import filesize
 
 from unshackle.core.config import config
 from unshackle.core.constants import DOWNLOAD_CANCELLED
-from unshackle.core.utilities import get_extension
+from unshackle.core.utilities import get_debug_logger, get_extension
 
 MAX_ATTEMPTS = 5
 RETRY_WAIT = 2
@@ -189,6 +189,8 @@ def curl_impersonate(
     if not isinstance(max_workers, (int, type(None))):
         raise TypeError(f"Expected max_workers to be {int}, not {type(max_workers)}")
 
+    debug_logger = get_debug_logger()
+
     if not isinstance(urls, list):
         urls = [urls]
 
@@ -209,6 +211,24 @@ def curl_impersonate(
     if proxy:
         session.proxies.update({"all": proxy})
 
+    if debug_logger:
+        first_url = urls[0].get("url", "") if urls else ""
+        url_display = first_url[:200] + "..." if len(first_url) > 200 else first_url
+        debug_logger.log(
+            level="DEBUG",
+            operation="downloader_curl_impersonate_start",
+            message="Starting curl_impersonate download",
+            context={
+                "url_count": len(urls),
+                "first_url": url_display,
+                "output_dir": str(output_dir),
+                "filename": filename,
+                "max_workers": max_workers,
+                "browser": BROWSER,
+                "has_proxy": bool(proxy),
+            },
+        )
+
     yield dict(total=len(urls))
 
     download_sizes = []
@@ -235,11 +255,23 @@ def curl_impersonate(
                 # tell dl that it was cancelled
                 # the pool is already shut down, so exiting loop is fine
                 raise
-            except Exception:
+            except Exception as e:
                 DOWNLOAD_CANCELLED.set()  # skip pending track downloads
                 yield dict(downloaded="[red]FAILING")
                 pool.shutdown(wait=True, cancel_futures=True)
                 yield dict(downloaded="[red]FAILED")
+                if debug_logger:
+                    debug_logger.log(
+                        level="ERROR",
+                        operation="downloader_curl_impersonate_failed",
+                        message=f"curl_impersonate download failed: {e}",
+                        error=e,
+                        context={
+                            "url_count": len(urls),
+                            "output_dir": str(output_dir),
+                            "browser": BROWSER,
+                        },
+                    )
                 # tell dl that it failed
                 # the pool is already shut down, so exiting loop is fine
                 raise
@@ -260,5 +292,17 @@ def curl_impersonate(
                     last_speed_refresh = now
                     download_sizes.clear()
 
+    if debug_logger:
+        debug_logger.log(
+            level="DEBUG",
+            operation="downloader_curl_impersonate_complete",
+            message="curl_impersonate download completed successfully",
+            context={
+                "url_count": len(urls),
+                "output_dir": str(output_dir),
+                "filename": filename,
+            },
+        )
+
 
 __all__ = ("curl_impersonate",)