feat: download ETA on the press bar from measured Soulseek throughput

Show a live "~Xm left" countdown on the download progress bar. The slskd download
loop already polls byte transfer every 3s; measure the actual throughput (EWMA-
smoothed bytes/sec), compute seconds-remaining from the album's total bytes, and
surface it. New nullable Job.downloadEtaSeconds (migration; web entrypoint runs
prisma migrate deploy), threaded through the on_progress callback (optional 2nd arg,
so other adapters/callers are unaffected — they report no ETA). API exposes it;
queue.tsx renders etaLabel() after the track count. Null when unknown (no sample yet
or a source that doesn't report bytes). Worker 330 tests, web 214 tests, both green;
verified live-rendered as "42% · 6/14 tracks · ~4m left".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

worker/lyra_worker/adapters/_slskd.py

@@ -29,6 +29,14 @@ def _dirname(path: str) -> str:
     return ""
 
 
+def _eta_seconds(total_bytes: int, bytes_now: int, speed_bps: float) -> int | None:
+    """Seconds until the transfer finishes at the current measured rate, or None when it can't be
+    estimated (no throughput sample yet, unknown total, or already complete). Pure — unit-tested."""
+    if speed_bps <= 0 or total_bytes <= 0 or bytes_now >= total_bytes:
+        return None
+    return int((total_bytes - bytes_now) / speed_bps)
+
+
 def _norm(s: str) -> str:
     """Lowercase, strip diacritics, and reduce to alphanumeric tokens, so 'Beyoncé' matches a
     peer's 'Beyonce' folder and punctuation ('I Am… Sasha Fierce') doesn't defeat the match."""
@@ -206,9 +214,13 @@ class SlskdClient:
         on_progress(0.0)
 
         total = len(files)
+        total_bytes = sum(int(f.get("size") or 0) for f in files)
         completed = False
         last_bytes = -1
         stall = 0
+        speed = 0.0  # bytes/sec, EWMA-smoothed so the ETA doesn't jitter poll to poll
+        prev_bytes = 0
+        prev_t = time.monotonic()
         for _ in range(_MAX_XFER_POLLS):
             time.sleep(_POLL_SECONDS)
             data = self._get(f"/api/v0/transfers/downloads/{username}")
@@ -224,8 +236,14 @@ class SlskdClient:
             if states:
                 if any(bad in s for s in states for bad in ("Errored", "Rejected", "Cancelled")):
                     raise RuntimeError("soulseek transfer failed")
+                now = time.monotonic()
+                dt = now - prev_t
+                if dt > 0 and bytes_now >= prev_bytes:
+                    inst = (bytes_now - prev_bytes) / dt
+                    speed = inst if speed == 0.0 else 0.6 * speed + 0.4 * inst
+                prev_bytes, prev_t = bytes_now, now
                 done = sum(1 for s in states if "Completed" in s)
-                on_progress(min(1.0, done / max(total, 1)))
+                on_progress(min(1.0, done / max(total, 1)), _eta_seconds(total_bytes, bytes_now, speed))
                 if done >= total:
                     completed = True
                     break

worker/lyra_worker/pipeline.py

@@ -159,29 +159,35 @@ def _set_state(conn: psycopg.Connection, job_id: str, state: str, stage: str) ->
     conn.commit()
 
 
-def _set_download_progress(conn: psycopg.Connection, job_id: str, frac: float) -> None:
+def _set_download_progress(
+    conn: psycopg.Connection, job_id: str, frac: float, eta_seconds: int | None = None
+) -> None:
     with conn.cursor() as cur:
-        cur.execute('UPDATE "Job" SET "downloadProgress" = %s WHERE id = %s', (frac, job_id))
+        cur.execute(
+            'UPDATE "Job" SET "downloadProgress" = %s, "downloadEtaSeconds" = %s WHERE id = %s',
+            (frac, eta_seconds, job_id),
+        )
     conn.commit()
 
 
 def _make_on_progress(conn: psycopg.Connection, job_id: str, reports: "threading.Event"):
-    """Build the on_progress(pct) callback threaded into adapter.download. It marks the
-    adapter as reporting real byte-level progress (so the file-count poller yields) and
-    throttle-writes Job.downloadProgress. Called synchronously from adapter.download on the
-    pipeline's own thread, so it safely reuses `conn`."""
+    """Build the on_progress(pct, eta_seconds=None) callback threaded into adapter.download. It
+    marks the adapter as reporting real byte-level progress (so the file-count poller yields) and
+    throttle-writes Job.downloadProgress (+ the download ETA when the adapter measures one — slskd
+    does; others pass None). Called synchronously from adapter.download on the pipeline's own
+    thread, so it safely reuses `conn`."""
     state = {"frac": -1.0, "t": 0.0}
 
-    def on_progress(pct: float) -> None:
+    def on_progress(pct: float, eta_seconds: int | None = None) -> None:
         reports.set()
         frac = 0.0 if pct < 0 else 1.0 if pct > 1 else float(pct)
         now = time.monotonic()
-        # throttle DB writes: on a >=1% move or every 0.5s, not once per received byte
-        if frac - state["frac"] >= 0.01 or (now - state["t"]) >= 0.5:
+        # throttle DB writes: on a >=1% move, a new ETA, or every 0.5s — not once per received byte
+        if frac - state["frac"] >= 0.01 or eta_seconds is not None or (now - state["t"]) >= 0.5:
             state["frac"] = frac
             state["t"] = now
             try:
-                _set_download_progress(conn, job_id, frac)
+                _set_download_progress(conn, job_id, frac, eta_seconds)
             except Exception as e:  # a progress write must never fail the download
                 print(f"pipeline: on_progress write failed: {e}", flush=True)
 

worker/tests/test_slskd_cancel.py

@@ -6,7 +6,7 @@ import json
 import pytest
 
 import lyra_worker.adapters._slskd as slskd_mod
-from lyra_worker.adapters._slskd import SlskdClient, _parse_search_responses
+from lyra_worker.adapters._slskd import SlskdClient, _eta_seconds, _parse_search_responses
 
 
 class _Resp:
@@ -63,7 +63,7 @@ def test_stalled_peer_is_abandoned_and_cancelled(tmp_path, monkeypatch):
     fake = slskd_mod.requests
 
     with pytest.raises(TimeoutError):
-        _client(tmp_path).download(_REF, str(tmp_path / "dest"), lambda _p: None)
+        _client(tmp_path).download(_REF, str(tmp_path / "dest"), lambda *_a: None)
     assert any(u.endswith("/api/v0/transfers/downloads/peerA/t1") for u in fake.deleted)
 
 
@@ -72,7 +72,7 @@ def test_error_state_is_cancelled(tmp_path, monkeypatch):
     monkeypatch.setattr(slskd_mod.time, "sleep", lambda _s: None)
     fake = slskd_mod.requests
     with pytest.raises(RuntimeError):
-        _client(tmp_path).download(_REF, str(tmp_path / "dest"), lambda _p: None)
+        _client(tmp_path).download(_REF, str(tmp_path / "dest"), lambda *_a: None)
     assert any(u.endswith("/peerA/t1") for u in fake.deleted)
 
 
@@ -92,7 +92,7 @@ def test_slow_but_progressing_peer_is_not_abandoned(tmp_path, monkeypatch):
     monkeypatch.setattr(slskd_mod.time, "sleep", lambda _s: None)
     monkeypatch.setattr(slskd_mod, "_STALL_POLLS", 2)  # would fire early if progress were ignored
 
-    out = _client(tmp_path).download(ref, str(tmp_path / "dest"), lambda _p: None)
+    out = _client(tmp_path).download(ref, str(tmp_path / "dest"), lambda *_a: None)
     assert out["track_count"] == 1
     assert slskd_mod.requests.deleted == []  # completed cleanly → nothing cancelled
 
@@ -108,3 +108,39 @@ def test_parse_ranks_free_and_fast_peers_first():
     ]
     peers = [json.loads(c["source_ref"])["username"] for c in _parse_search_responses(responses)]
     assert peers == ["fast", "slow", "queued"]  # free+fast first; no-slot peer last despite speed
+
+
+def test_eta_seconds_from_measured_rate():
+    assert _eta_seconds(1000, 250, 250.0) == 3  # 750 bytes left / 250 B/s
+    assert _eta_seconds(1000, 0, 100.0) == 10
+
+
+def test_eta_seconds_unknown_cases():
+    assert _eta_seconds(1000, 250, 0.0) is None      # no speed sample yet
+    assert _eta_seconds(0, 0, 100.0) is None          # unknown total size
+    assert _eta_seconds(1000, 1000, 100.0) is None    # already complete
+
+
+def test_download_reports_shrinking_eta(tmp_path, monkeypatch):
+    # A 900-byte file arriving 300 bytes per 3s poll → measured speed 100 B/s → ETA counts down
+    # (6s, 3s) then None on completion. on_progress gets (fraction, eta_seconds).
+    (tmp_path / "01.flac").write_bytes(b"x" * 900)  # so _retrieve finds the finished file
+    ref = json.dumps({"username": "peerA", "files": [{"filename": r"d\Album\01.flac", "size": 900}]})
+    polls = [
+        {"directories": [{"files": [{"filename": r"d\Album\01.flac", "size": 900,
+                                     "state": "InProgress", "bytesTransferred": b, "id": "t1"}]}]}
+        for b in (300, 600)
+    ] + [
+        {"directories": [{"files": [{"filename": r"d\Album\01.flac", "size": 900,
+                                     "state": "Completed, Succeeded", "bytesTransferred": 900, "id": "t1"}]}]}
+    ]
+    monkeypatch.setattr(slskd_mod, "requests", _SeqRequests(polls))
+    monkeypatch.setattr(slskd_mod.time, "sleep", lambda _s: None)
+    clock = iter(float(i) * 3 for i in range(100))  # 0,3,6,… deterministic monotonic time
+    monkeypatch.setattr(slskd_mod.time, "monotonic", lambda: next(clock))
+
+    calls: list = []
+    _client(tmp_path).download(ref, str(tmp_path / "dest"), lambda *a: calls.append(a))
+
+    etas = [a[1] for a in calls if len(a) > 1]
+    assert etas == [6, 3, None]  # counts down at 100 B/s, then None once complete