withcache 0.4.3__tar.gz → 0.5.0__tar.gz

{withcache-0.4.3 → withcache-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.4.3
+Version: 0.5.0
 Summary: Operator-curated, URL-keyed artifact cache for a small lab (CUDA/ROCm/DOCA/firmware)
 Project-URL: Homepage, https://github.com/safl/withcache
 Author-email: "Simon A. F. Lund" <safl@safl.dk>

{withcache-0.4.3 → withcache-0.5.0}/shim/build.zig.zon

@@ -2,7 +2,7 @@
     .name = .withcache_shim,
     // Zig requires a literal here; keep it in lockstep with the project's
     // single source (src/withcache/__init__.py) via `make bump` / `make version-check`.
-    .version = "0.4.3",
+    .version = "0.5.0",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.4.3 → withcache-0.5.0}/src/withcache/__init__.py

@@ -12,6 +12,6 @@ All modules are stdlib-only and self-contained.
 
 from .client import blob_url, cache_base, is_cached, serve_url
 
-__version__ = "0.4.3"
+__version__ = "0.5.0"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "serve_url"]

{withcache-0.4.3 → withcache-0.5.0}/src/withcache/server.py

@@ -64,6 +64,18 @@ def now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+def _age_human(started_at: float, *, now: float | None = None) -> str:
+    """Render seconds-since as a compact ``Ns`` / ``Nm`` / ``Nh`` string for
+    the streams table. ``now`` is injectable so tests don't need
+    monkeypatching ``time.time`` to assert formatting."""
+    elapsed = int(max(0.0, (now if now is not None else time.time()) - started_at))
+    if elapsed < 60:
+        return f"{elapsed}s"
+    if elapsed < 3600:
+        return f"{elapsed // 60}m{elapsed % 60:02d}s"
+    return f"{elapsed // 3600}h{(elapsed % 3600) // 60:02d}m"
+
+
 def human_size(n: int) -> str:
     f = float(n)
     for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
@@ -460,6 +472,65 @@ class TruncatedDownload(Exception):
     """
 
 
+@dataclass
+class Stream:
+    """One in-flight blob serve. Lives in memory only for the duration of
+    the response: registered before the first byte goes out, deregistered
+    in a finally block. Operator visibility into "what is the cache
+    currently uploading, and to whom" without touching the kernel's
+    /proc/net/tcp or the access log.
+    """
+
+    id: int
+    url: str
+    client: str  # ``ip:port`` of the consumer
+    started_at: float
+    bytes_sent: int = 0
+    total: int | None = None  # known up front from the blob row
+
+
+class StreamRegistry:
+    """Thread-safe registry of in-flight blob serves. Reads (snapshot for
+    the operator dash) and writes (start / progress / finish from
+    request handler threads) all serialised on a single lock; the
+    contention window is the few microseconds of a dict mutation, and
+    progress updates are batched at one per chunk (see PROGRESS_STRIDE)
+    so a 4 GiB stream is ~64k updates, not millions.
+    """
+
+    PROGRESS_STRIDE = 16  # update bytes_sent every N chunks (~1 MiB at CHUNK=64K)
+
+    def __init__(self) -> None:
+        self._ids = itertools.count(1)
+        self._lock = threading.Lock()
+        self._active: dict[int, Stream] = {}
+
+    def start(self, url: str, client: str, total: int | None) -> Stream:
+        with self._lock:
+            s = Stream(
+                id=next(self._ids), url=url, client=client, started_at=time.time(), total=total
+            )
+            self._active[s.id] = s
+            return s
+
+    def bump(self, stream_id: int, bytes_sent: int) -> None:
+        # Caller already gates by PROGRESS_STRIDE so this is cheap; the
+        # write itself only takes the lock long enough to mutate the int.
+        with self._lock:
+            s = self._active.get(stream_id)
+            if s is not None:
+                s.bytes_sent = bytes_sent
+
+    def finish(self, stream_id: int) -> None:
+        with self._lock:
+            self._active.pop(stream_id, None)
+
+    def snapshot(self) -> list[Stream]:
+        with self._lock:
+            # Stable order: oldest first (matches the queue mental model).
+            return sorted(self._active.values(), key=lambda s: s.started_at)
+
+
 @dataclass
 class Job:
     id: int
@@ -587,6 +658,10 @@ class Handler(http.server.BaseHTTPRequestHandler):
     def auto_fetch(self) -> bool:
         return self.server.auto_fetch  # type: ignore[attr-defined]
 
+    @property
+    def streams(self) -> StreamRegistry:
+        return self.server.streams  # type: ignore[attr-defined]
+
     def log_message(self, format, *args):  # quieter, single-line
         print(f"{self.address_string()} - {format % args}", flush=True)
 
@@ -779,17 +854,39 @@ class Handler(http.server.BaseHTTPRequestHandler):
         self.send_header("X-Withcache-Sha256", row["sha256"])
         self.end_headers()
         if head_only:
-            return  # the shim's HEAD probe — not a served download, so don't count it
+            return  # the shim's HEAD probe (not a served download, so don't count it)
         self.store.record_hit(row["key"])
+        # Register the stream BEFORE we open the file so an operator
+        # watching the dash sees the serve immediately (even if the
+        # disk read stalls). The handler runs on a worker thread per
+        # the ThreadingHTTPServer mixin, so the registry sees
+        # concurrent calls; StreamRegistry serialises on its own lock.
+        client = f"{self.client_address[0]}:{self.client_address[1]}"
+        stream = self.streams.start(url=url, client=client, total=row["size"])
         try:
             with open(path, "rb") as f:
+                sent = 0
+                ticks = 0
                 while True:
                     chunk = f.read(CHUNK)
                     if not chunk:
                         break
                     self.wfile.write(chunk)
+                    sent += len(chunk)
+                    ticks += 1
+                    # Batched progress update: every 16 chunks (~1 MiB
+                    # at CHUNK=64K) is plenty for a 1 Hz dashboard and
+                    # keeps lock-contention sane on a busy box.
+                    if ticks % StreamRegistry.PROGRESS_STRIDE == 0:
+                        self.streams.bump(stream.id, sent)
+                # Final position so the dash's last frame shows the
+                # serve completing at the declared total, not at
+                # whatever the last batched update happened to be.
+                self.streams.bump(stream.id, sent)
         except (BrokenPipeError, ConnectionResetError):
             pass  # client went away mid-stream
+        finally:
+            self.streams.finish(stream.id)
 
     # -- helpers -----------------------------------------------------------
     def read_form(self) -> dict:
@@ -903,7 +1000,15 @@ class Handler(http.server.BaseHTTPRequestHandler):
     </fieldset>
   </form>
 
-  <div id="dash" hx-get="/admin/dash" hx-trigger="load, every 1s" hx-swap="innerHTML">
+  <!-- The hx-trigger gates polling on the user NOT having an active
+       text selection, so highlight-and-copy a URL out of a table cell
+       isn't wiped by the 1 Hz refresh. ``isCollapsed`` is true when
+       there's no selection or the caret is a zero-width point; once
+       the operator releases / clears the selection polling resumes
+       on the next 1 s tick. -->
+  <div id="dash" hx-get="/admin/dash"
+       hx-trigger="load, every 1s [document.getSelection().isCollapsed]"
+       hx-swap="innerHTML">
     {self.render_dash()}
   </div>
 </main></body></html>"""
@@ -913,11 +1018,62 @@ class Handler(http.server.BaseHTTPRequestHandler):
         jobs = self.mgr.list()
         misses = self.store.list_misses()
         blobs = self.store.list_blobs()
+        streams = self.streams.snapshot()
         used = human_size(self.store.total_size())
         if self.store.max_bytes:
             used += f" / {human_size(self.store.max_bytes)}"
         full = "" if self.store.has_capacity() else " &middot; <strong>cache full</strong>"
 
+        # Tabs are pure-CSS via :target. The URL hash names the active
+        # section; htmx innerHTML-replacement of #dash leaves the hash
+        # alone, so the operator's tab choice survives every refresh.
+        # ``body:not(:has(section:target))`` selects the default tab
+        # when no hash is present; :has() lands cleanly on Chrome 105+,
+        # Firefox 121+, Safari 15.4+, which is the whole modern web by
+        # the time this ships in 2026.
+        tab_style = """
+<style>
+  nav.tabs { margin: 1rem 0 .25rem; border-bottom: 1px solid var(--pico-muted-border-color); }
+  nav.tabs ul { display: flex; gap: 0; padding: 0; margin: 0; list-style: none; }
+  nav.tabs li { margin: 0; }
+  nav.tabs a {
+    display: inline-block; padding: .45rem .9rem; text-decoration: none;
+    color: var(--pico-muted-color); border-bottom: 2px solid transparent;
+    margin-bottom: -1px; font-size: .9rem;
+  }
+  nav.tabs a:hover { color: var(--pico-color); }
+  section.tab { display: none; padding-top: .75rem; }
+  section.tab:target { display: block; }
+  body:not(:has(section.tab:target)) section.tab#tab-streams { display: block; }
+  body:has(#tab-streams:target)  nav.tabs a[href="#tab-streams"],
+  body:has(#tab-downloads:target) nav.tabs a[href="#tab-downloads"],
+  body:has(#tab-misses:target)    nav.tabs a[href="#tab-misses"],
+  body:has(#tab-cached:target)    nav.tabs a[href="#tab-cached"] {
+    color: var(--pico-color);
+    border-bottom-color: var(--pico-primary, #0172ad);
+    font-weight: 600;
+  }
+  body:not(:has(section.tab:target)) nav.tabs a[href="#tab-streams"] {
+    color: var(--pico-color);
+    border-bottom-color: var(--pico-primary, #0172ad);
+    font-weight: 600;
+  }
+</style>
+"""
+
+        stream_rows = (
+            "".join(
+                f"""<tr>
+                <td class="url">{html.escape(s.url)}</td>
+                <td class="mono"><small>{html.escape(s.client)}</small></td>
+                <td>{self._stream_progress_cell(s)}</td>
+                <td><small>{_age_human(s.started_at)}</small></td>
+            </tr>"""
+                for s in streams
+            )
+            or '<tr><td colspan="4"><em>No active streams.</em></td></tr>'
+        )
+
         job_rows = (
             "".join(self._job_row(j) for j in jobs)
             or '<tr><td colspan="4"><em>No downloads yet.</em></td></tr>'
@@ -968,35 +1124,76 @@ class Handler(http.server.BaseHTTPRequestHandler):
             or '<tr><td colspan="7"><em>Cache is empty.</em></td></tr>'
         )
 
+        # Per-tab counts let the operator see at a glance whether each
+        # section is empty without flipping to it.
+        nstreams = len(streams)
+        njobs = len(jobs)
+
         return f"""
   <p><small>{nblobs} cached ({used}){full} &middot; {nmisses} pending miss(es)</small></p>
-
-  <div class="row">
-    <h4>Downloads</h4>
-    <form hx-post="/admin/clear" hx-target="#dash" hx-swap="innerHTML" style="margin:0">
-      <button type="submit" class="secondary outline" style="width:auto;padding:.2rem .7rem">
-        Clear finished</button>
-    </form>
-  </div>
-  <figure><table class="striped">
-    <thead><tr><th>Artifact</th><th>Progress</th><th>Status</th><th></th></tr></thead>
-    <tbody>{job_rows}</tbody>
-  </table></figure>
-
-  <h4>Misses</h4>
-  <figure><table class="striped">
-    <thead><tr><th>URL</th><th class="num">Misses</th><th>Last seen</th><th>Action</th></tr></thead>
-    <tbody>{miss_rows}</tbody>
-  </table></figure>
-
-  <h4>Cached artifacts</h4>
-  <figure><table class="striped">
-    <thead><tr>
-      <th>URL</th><th>Size</th><th class="num">Hits</th><th class="num">Misses</th>
-      <th>SHA-256</th><th>Fetched</th><th>Action</th>
-    </tr></thead>
-    <tbody>{blob_rows}</tbody>
-  </table></figure>"""
+{tab_style}
+  <nav class="tabs"><ul>
+    <li><a href="#tab-streams">Streams ({nstreams})</a></li>
+    <li><a href="#tab-downloads">Downloads ({njobs})</a></li>
+    <li><a href="#tab-misses">Misses ({nmisses})</a></li>
+    <li><a href="#tab-cached">Cached ({nblobs})</a></li>
+  </ul></nav>
+
+  <section id="tab-streams" class="tab">
+    <figure><table class="striped">
+      <thead><tr>
+        <th>URL</th><th>Client</th><th>Progress</th><th>Age</th>
+      </tr></thead>
+      <tbody>{stream_rows}</tbody>
+    </table></figure>
+  </section>
+
+  <section id="tab-downloads" class="tab">
+    <div class="row">
+      <small>Auto-fetch workers feeding the cache.</small>
+      <form hx-post="/admin/clear" hx-target="#dash" hx-swap="innerHTML" style="margin:0">
+        <button type="submit" class="secondary outline" style="width:auto;padding:.2rem .7rem">
+          Clear finished</button>
+      </form>
+    </div>
+    <figure><table class="striped">
+      <thead><tr><th>Artifact</th><th>Progress</th><th>Status</th><th></th></tr></thead>
+      <tbody>{job_rows}</tbody>
+    </table></figure>
+  </section>
+
+  <section id="tab-misses" class="tab">
+    <figure><table class="striped">
+      <thead><tr>
+        <th>URL</th><th class="num">Misses</th><th>Last seen</th><th>Action</th>
+      </tr></thead>
+      <tbody>{miss_rows}</tbody>
+    </table></figure>
+  </section>
+
+  <section id="tab-cached" class="tab">
+    <figure><table class="striped">
+      <thead><tr>
+        <th>URL</th><th>Size</th><th class="num">Hits</th><th class="num">Misses</th>
+        <th>SHA-256</th><th>Fetched</th><th>Action</th>
+      </tr></thead>
+      <tbody>{blob_rows}</tbody>
+    </table></figure>
+  </section>"""
+
+    def _stream_progress_cell(self, s: Stream) -> str:
+        """One progress cell for an active stream: a <progress> bar when the
+        total is known (always for a cached blob, since the size came off
+        the row), with a small ``sent / total`` line under it. Falls back
+        to bytes-only when total somehow went missing."""
+        if s.total is None or s.total <= 0:
+            return f'<small class="mono">{human_size(s.bytes_sent)}</small>'
+        pct = min(100, int(s.bytes_sent * 100 / s.total))
+        return (
+            f'<progress value="{s.bytes_sent}" max="{s.total}"></progress>'
+            f'<br><small class="mono">{human_size(s.bytes_sent)} / '
+            f"{human_size(s.total)} ({pct}%)</small>"
+        )
 
     def _job_row(self, j: Job) -> str:
         name = os.path.basename(urllib.parse.urlsplit(j.url).path) or j.url
@@ -1074,6 +1271,7 @@ def main():
     httpd.auth = auth  # type: ignore[attr-defined]
     httpd.mgr = mgr  # type: ignore[attr-defined]
     httpd.auto_fetch = not args.curate  # type: ignore[attr-defined]
+    httpd.streams = StreamRegistry()  # type: ignore[attr-defined]
     print(
         f"withcache cache-host on http://{args.host}:{args.port}  "
         f"(data={store.data_dir}, keep_query={args.keep_query}, workers={args.workers}, "

{withcache-0.4.3 → withcache-0.5.0}/tests/test_withcache.py

@@ -370,6 +370,113 @@ class TestRangeResumeOnTruncation(unittest.TestCase):
         self.assertTrue(any(d > half for d, _ in observed))
 
 
+# --------------------------------------------------------------------------
+# StreamRegistry: in-flight blob-serve registry powering the operator dash's
+# "Streams" tab. Validates thread-safety + snapshot ordering + lifecycle.
+# --------------------------------------------------------------------------
+class TestStreamRegistry(unittest.TestCase):
+    def test_start_assigns_unique_ids_and_records_metadata(self):
+        reg = server.StreamRegistry()
+        a = reg.start(url="http://o/x", client="10.0.0.1:5000", total=1024)
+        b = reg.start(url="http://o/y", client="10.0.0.2:5000", total=None)
+        self.assertNotEqual(a.id, b.id)
+        self.assertEqual(a.url, "http://o/x")
+        self.assertEqual(a.client, "10.0.0.1:5000")
+        self.assertEqual(a.total, 1024)
+        self.assertIsNone(b.total)
+        # both visible in snapshot, oldest-first
+        snap = reg.snapshot()
+        self.assertEqual([s.id for s in snap], [a.id, b.id])
+
+    def test_bump_updates_bytes_sent_for_known_id(self):
+        reg = server.StreamRegistry()
+        s = reg.start(url="http://o/x", client="c", total=100)
+        reg.bump(s.id, 42)
+        self.assertEqual(reg.snapshot()[0].bytes_sent, 42)
+        # later bump moves forward; the registry doesn't enforce
+        # monotonicity (the handler is the only caller and it is monotonic)
+        reg.bump(s.id, 99)
+        self.assertEqual(reg.snapshot()[0].bytes_sent, 99)
+
+    def test_bump_unknown_id_is_a_silent_noop(self):
+        """A finish() that races against a final bump() must not crash:
+        the bump arrives, finds the id gone, returns silently. The
+        handler relies on this so its tight write loop doesn't have to
+        special-case the race."""
+        reg = server.StreamRegistry()
+        reg.bump(99999, 7)
+        self.assertEqual(reg.snapshot(), [])
+
+    def test_finish_removes_from_snapshot(self):
+        reg = server.StreamRegistry()
+        s = reg.start(url="http://o/x", client="c", total=10)
+        self.assertEqual(len(reg.snapshot()), 1)
+        reg.finish(s.id)
+        self.assertEqual(reg.snapshot(), [])
+        # second finish is a no-op (handler's finally: block can fire twice)
+        reg.finish(s.id)
+        self.assertEqual(reg.snapshot(), [])
+
+    def test_snapshot_returns_a_copy_not_the_live_dict(self):
+        """Operator code iterating a snapshot must not see torn state when
+        a worker thread starts/finishes a stream mid-iteration."""
+        reg = server.StreamRegistry()
+        s = reg.start(url="http://o/x", client="c", total=10)
+        snap = reg.snapshot()
+        reg.finish(s.id)
+        reg.start(url="http://o/y", client="c", total=10)
+        # snapshot taken before the mutations stays put
+        self.assertEqual(len(snap), 1)
+        self.assertEqual(snap[0].url, "http://o/x")
+
+    def test_concurrent_start_finish_under_load(self):
+        """Hammer the lock with 500 starts + 500 finishes from 10 threads;
+        the registry must end empty with no exception leaks."""
+        reg = server.StreamRegistry()
+        errors: list[BaseException] = []
+
+        def churn():
+            try:
+                for _ in range(50):
+                    s = reg.start(url="http://o/x", client="c", total=10)
+                    reg.bump(s.id, 5)
+                    reg.finish(s.id)
+            except BaseException as e:
+                errors.append(e)
+
+        threads = [threading.Thread(target=churn) for _ in range(10)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        self.assertEqual(errors, [])
+        self.assertEqual(reg.snapshot(), [])
+
+
+class TestAgeHuman(unittest.TestCase):
+    """``_age_human`` renders elapsed seconds into the compact form the
+    Streams table cell shows. Inject ``now`` so the test doesn't have
+    to monkeypatch ``time.time``."""
+
+    def test_seconds_only(self):
+        self.assertEqual(server._age_human(100.0, now=100.0), "0s")
+        self.assertEqual(server._age_human(100.0, now=159.0), "59s")
+
+    def test_minutes_pad_seconds(self):
+        self.assertEqual(server._age_human(100.0, now=160.0), "1m00s")
+        self.assertEqual(server._age_human(100.0, now=222.0), "2m02s")
+
+    def test_hours_pad_minutes(self):
+        self.assertEqual(server._age_human(0.0, now=3600.0), "1h00m")
+        self.assertEqual(server._age_human(0.0, now=3661.0), "1h01m")
+        self.assertEqual(server._age_human(0.0, now=7320.0), "2h02m")
+
+    def test_negative_clamps_to_zero(self):
+        # Started-at in the future (clock skew, replayed snapshot) renders
+        # as 0s rather than a confusing negative.
+        self.assertEqual(server._age_human(200.0, now=100.0), "0s")
+
+
 # --------------------------------------------------------------------------
 # _shim: URL detection, rewrite, real-tool resolution, env, path-encoding
 # --------------------------------------------------------------------------
@@ -536,6 +643,7 @@ def _start_withcache(auto_fetch=False):
     httpd.auth = server.Auth(b"k", None)  # auth disabled -> read path open
     httpd.mgr = server.DownloadManager(store, workers=1)
     httpd.auto_fetch = auto_fetch
+    httpd.streams = server.StreamRegistry()
     threading.Thread(target=httpd.serve_forever, daemon=True).start()
     return httpd, store