dccd 3.3.1__tar.gz → 3.4.0__tar.gz

{dccd-3.3.1 → dccd-3.4.0}/CHANGELOG.md

@@ -16,6 +16,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [3.4.0] - 2026-06-10
+
+### Added
+
+### Changed
+
+- Remote-friendly UI transport: gzip on API/page responses (`/api/inventory`
+  measured 12 450 B → 460 B, 27×; SSE excluded and flushed immediately so
+  EventSource connects without waiting for the first event), dashboard fetches
+  parallelised (3×RTT → 1×RTT), Live re-fetches the inventory only on load and
+  stream-status changes instead of every 8 s, dashboard/storage poll cadences
+  relaxed (15 s / 30 s), and runs-store SQLite reads moved off the event loop.
+  UI smoke: 27/27 steps clean. (#121)
+
+### Fixed
+
+- Order-book stream jobs with a depth the exchange doesn't support (production
+  case: Kraken `depth: 20`/`50` — WS v2 only accepts {10, 25, 100, 500, 1000})
+  were silently rejected and sat "live" forever writing nothing. Valid depths
+  are now declared per capability (verified against the live APIs), requests
+  snap to the nearest valid value with a warning, and WS subscription
+  rejections raise — surfacing in runs as `failed` with the exchange's error —
+  instead of being filtered out. (#122)
+- A live stream whose WS generator ended on its own (no stop requested) was
+  recorded `cancelled`; it is now `failed` with an explicit
+  "stream ended unexpectedly" error, so Logs/Runs no longer claim someone
+  stopped a stream nobody touched. (#121)
+- Order-book WS adapters built the full book as pydantic objects on **every**
+  delta while the stream operation kept only one frame per `snapshot_interval` —
+  97.7 % CPU on the production collector, starving the event loop and making
+  the remote UI unusable. Snapshots are now constructed only at capture time
+  (`min_interval` pushed down into the adapters; `0.0` keeps per-frame), and
+  Kraken/Bybit book state is truncated to the subscribed depth (WS truncation
+  contract). Verified live: Kraken 60 s at 10 s interval → exactly 6 snapshots,
+  ≤ 25 levels/side, never crossed; 3 live books for 2 min → **2.0 %** CPU. (#120)
+- `ParquetStore` metadata (inventory, last timestamp, gap detection) no longer
+  reads the full TS column of every file in the store — it reads parquet footer
+  statistics with a per-file mtime cache (legacy files without statistics fall
+  back to the old path), and `/api/inventory` + `/api/storage/sync` now run it
+  off the event loop. Verified value-identical on real data; 13× faster warm on
+  a small store, and the gap grows with file size (production showed 100 s for
+  a 10 KB inventory response under load). (#119)
+- Permanently failing scheduled jobs no longer hammer the exchange at full
+  cadence: the interval loop applies exponential backoff (reset on success) and
+  starts with a random jitter instead of firing every job at once on daemon
+  start. `HealthMonitor` alerts once when the failure threshold is crossed,
+  then at most hourly — instead of on every failure (a broken job used to spam
+  the webhook every ~20 s). (#118)
+
+### Deprecated
+
+### Removed
+
 ## [3.3.1] - 2026-06-10
 
 ### Fixed

{dccd-3.3.1 → dccd-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dccd
-Version: 3.3.1
+Version: 3.4.0
 Summary: Download Crypto Currency Data — hexagonal architecture, async-first.
 Author-email: Arthur Bernard <arthur.bernard.92@gmail.com>
 License: MIT

{dccd-3.3.1 → dccd-3.4.0}/dccd/application/monitor.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import time
 from collections import defaultdict
 
 from dccd.application.events import Event, EventBus, StatusEvent
@@ -12,10 +13,19 @@ __all__ = ["HealthMonitor"]
 
 logger = logging.getLogger(__name__)
 
+# Minimum seconds between repeated alerts for the same job while it keeps failing.
+_ALERT_COOLDOWN_S = 3600
+
 
 class HealthMonitor:
     """Monitors job runs and fires webhook alerts on repeated failures.
 
+    An alert fires when the consecutive-failure count first **crosses**
+    ``max_consecutive_errors``.  While the job keeps failing, a follow-up alert
+    fires at most once per ``_ALERT_COOLDOWN_S`` (1 hour) so a permanently-broken
+    job does not flood a webhook.  The count (and cooldown) reset on the first
+    success.
+
     Parameters
     ----------
     runs_store : RunsStore
@@ -36,6 +46,10 @@ class HealthMonitor:
         self._webhook = webhook_url
         self._max_errors = max_consecutive_errors
         self._consecutive: dict[str, int] = defaultdict(int)
+        # Last monotonic timestamp at which an alert was sent per job key.
+        self._last_alert_ts: dict[str, float] = {}
+        # Last monotonic timestamp at which a webhook-send failure was logged per key.
+        self._last_webhook_err_ts: dict[str, float] = {}
         event_bus.subscribe(self._on_event)
 
     def _on_event(self, event: Event) -> None:
@@ -49,14 +63,24 @@ class HealthMonitor:
         if event.state == "failed":
             self._consecutive[key] += 1
             count = self._consecutive[key]
-            if count >= self._max_errors:
+            if count == self._max_errors:
+                # First crossing: always alert.
                 self._alert(key, count)
+            elif count > self._max_errors:
+                # Still failing: re-alert only once per cooldown window.
+                last = self._last_alert_ts.get(key, 0.0)
+                if time.monotonic() - last >= _ALERT_COOLDOWN_S:
+                    self._alert(key, count)
         elif event.state == "succeeded":
             self._consecutive[key] = 0
+            # Reset cooldown so the next failure streak starts fresh.
+            self._last_alert_ts.pop(key, None)
+            self._last_webhook_err_ts.pop(key, None)
 
     def _alert(self, run_id: str, count: int) -> None:
         msg = f"dccd alert: {run_id} failed {count} times consecutively."
         logger.error(msg)
+        self._last_alert_ts[run_id] = time.monotonic()
         if self._webhook:
             try:
                 import json
@@ -70,4 +94,8 @@ class HealthMonitor:
                 with urllib.request.urlopen(req, timeout=5):
                     pass
             except Exception as exc:
-                logger.warning("Webhook alert failed: %s", exc)
+                # Log webhook-send failures at most once per cooldown window.
+                last_err = self._last_webhook_err_ts.get(run_id, 0.0)
+                if time.monotonic() - last_err >= _ALERT_COOLDOWN_S:
+                    logger.warning("Webhook alert failed: %s", exc)
+                    self._last_webhook_err_ts[run_id] = time.monotonic()

{dccd-3.3.1 → dccd-3.4.0}/dccd/application/operations.py

@@ -449,19 +449,33 @@ async def stream(
         elif target.data_type == DataType.ORDERBOOK:
             if not isinstance(adapter, OrderBookLive):
                 raise NoCapability(target.exchange, "orderbook", "live")
-            # The WS pushes the book continuously, but we only *capture* a
-            # snapshot every ``snapshot_interval`` seconds. Emit the liveness
-            # sample only when we actually save, so the liveness reflects the
-            # real capture cadence (matching the "Δ Ns" shown in the UI) instead
-            # of flickering every second on data we discard. ``last_save = 0``
-            # captures the first frame immediately.
-            last_save = 0.0
-            async for snap in adapter.stream_orderbook(target.symbol, params.depth or 50):
+            # Snap the requested depth to the channel's declared discrete values
+            # (e.g. Kraken WS v2 only accepts {10,25,100,500,1000}): an undeclared
+            # depth is silently rejected by the exchange and the "live" stream
+            # would never write anything. Prefer the smallest valid depth that
+            # still covers the request; fall back to the largest available.
+            depth = params.depth or 50
+            ob_cap = adapter.capability_for(DataType.ORDERBOOK, "ws", "live")
+            if ob_cap is not None and ob_cap.depths and depth not in ob_cap.depths:
+                snapped = min((d for d in ob_cap.depths if d >= depth),
+                              default=max(ob_cap.depths))
+                if events:
+                    events.log(
+                        f"{target.exchange} order-book channel does not accept "
+                        f"depth={depth}; using {snapped} "
+                        f"(valid: {sorted(ob_cap.depths)})",
+                        level="warning",
+                    )
+                depth = snapped
+            # The throttle is owned by the adapter: pass min_interval so that
+            # pydantic objects are only constructed for frames that will be saved.
+            # The adapter yields one snapshot per interval, so every yielded
+            # snapshot is saved immediately (no downstream throttle needed).
+            async for snap in adapter.stream_orderbook(
+                target.symbol, depth, min_interval=snapshot_interval
+            ):
                 if stop_event and stop_event.is_set():
                     break
-                if time.time() - last_save < snapshot_interval:
-                    continue
-                last_save = time.time()
                 await asyncio.to_thread(store.save, ds, [snap], Provenance(source=prov_src))
                 # Best bid = highest bid price, best ask = lowest ask price.
                 # Compute rather than trust ordering so a momentarily unsorted
@@ -481,10 +495,21 @@ async def stream(
     if batch:
         await asyncio.to_thread(store.save, ds, batch, Provenance(source=prov_src))
 
-    if events:
-        events.status("cancelled")
-    if runs_store:
-        runs_store.finish_run(run_id, "cancelled")
+    # `cancelled` only when a stop was actually requested. A WS generator that
+    # ends on its own (exhausted without stop) is a failure — recording it as
+    # `cancelled` made Logs/Runs claim someone stopped a stream nobody touched.
+    if stop_event and stop_event.is_set():
+        if events:
+            events.status("cancelled")
+        if runs_store:
+            runs_store.finish_run(run_id, "cancelled")
+    else:
+        msg = "stream ended unexpectedly"
+        if events:
+            events.log(msg, level="error")
+            events.status("failed")
+        if runs_store:
+            runs_store.finish_run(run_id, "failed", error=msg)
 
 
 def read(

{dccd-3.3.1 → dccd-3.4.0}/dccd/application/scheduler.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import random
 import time
 
 from dccd.application.events import EventBus, RunEvents
@@ -197,9 +198,13 @@ class Scheduler:
                     self._interval_of(spec),
                 )
 
+    async def _run_once_void(self, spec: JobSpec) -> None:
+        """Thin void wrapper around :meth:`_run_once` for use with ``create_task``."""
+        await self._run_once(spec)
+
     async def run_now(self, spec: JobSpec) -> None:
         """Trigger a one-shot backfill for *spec* immediately."""
-        self._track(asyncio.create_task(self._run_once(spec)))
+        self._track(asyncio.create_task(self._run_once_void(spec)))
 
     async def start(self, specs: list[JobSpec]) -> None:
         """Start all enabled specs (full daemon mode)."""
@@ -222,7 +227,7 @@ class Scheduler:
             elif spec.trigger.kind == "once":
                 # Track the task so stop() can cancel it and the event loop
                 # cannot silently GC it before it finishes.
-                self._track(asyncio.create_task(self._run_once(spec)))
+                self._track(asyncio.create_task(self._run_once_void(spec)))
 
     async def stop(self) -> None:
         """Stop all running jobs."""
@@ -303,15 +308,32 @@ class Scheduler:
 
     async def _interval_loop(self, spec: JobSpec) -> None:
         every = spec.trigger.every or spec.target.span or 3600
+        # Startup jitter: spread simultaneous daemon starts over [0, min(every, 60)].
+        jitter = random.uniform(0, min(every, 60))
+        await asyncio.sleep(jitter)
+        consecutive_failures = 0
         while self._running:
-            await self._run_once(spec)
-            await asyncio.sleep(every)
+            success = await self._run_once(spec)
+            if success:
+                consecutive_failures = 0
+                delay = every
+            else:
+                # Cap the exponent at 11 to avoid overflow (2**11 = 2048).
+                k = min(consecutive_failures, 11)
+                delay = min(every * (2 ** k), max(every, 6 * 3600))
+                consecutive_failures += 1
+                logger.warning(
+                    "Scheduled job %s failed (consecutive=%d) — backing off %ds",
+                    spec.id, consecutive_failures, int(delay),
+                )
+            await asyncio.sleep(delay)
 
-    async def _run_once(self, spec: JobSpec) -> None:
+    async def _run_once(self, spec: JobSpec) -> bool:
+        """Run *spec* once; return True on success, False on error."""
         from dccd.application.operations import backfill
         try:
             run_events = self._events.for_run(f"{spec.id}@{int(time.time())}")
-            await backfill(
+            result = await backfill(
                 spec,
                 registry=self._registry,
                 store=self._store,
@@ -319,8 +341,10 @@ class Scheduler:
                 coverage_store=self._coverage_store,
                 events=run_events,
             )
+            return not (isinstance(result, dict) and "error" in result)
         except Exception as exc:
             logger.error("Scheduled job %s failed: %s", spec.id, exc)
+            return False
 
     def start_stream(self, spec_id: str) -> bool:
         """Start one registered stream by spec id; return whether it existed."""

{dccd-3.3.1 → dccd-3.4.0}/dccd/domain/capability.py

@@ -31,6 +31,12 @@ class Capability(BaseModel, frozen=True):
         Supported OHLC spans in seconds. ``None`` = span list not constrained.
     max_depth : int or None
         Maximum order book depth.
+    depths : list[int] or None
+        Discrete order-book depths the channel accepts (e.g. Kraken WS v2:
+        ``[10, 25, 100, 500, 1000]``). ``None`` = not constrained. The stream
+        operation snaps a requested depth to the nearest declared value — an
+        undeclared depth would be silently rejected by the exchange and leave
+        a "live" stream that never writes anything.
     auth_required : bool
         Whether this capability requires authentication.
 
@@ -50,4 +56,5 @@ class Capability(BaseModel, frozen=True):
     page_direction: Literal["forward", "backward"] | None = None
     spans: list[int] | None = None
     max_depth: int | None = None
+    depths: list[int] | None = None
     auth_required: bool = False

{dccd-3.3.1 → dccd-3.4.0}/dccd/interfaces/api/app.py

@@ -32,6 +32,7 @@ from urllib.parse import parse_qs
 
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
 from fastapi.responses import JSONResponse, RedirectResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
@@ -301,6 +302,11 @@ def create_app(
     # all; allowing every origin let any website's JS drive the local API
     # (reachable on 127.0.0.1 from the user's browser). Cross-origin access is
     # opt-in via settings.ui_allow_origins.
+    # Compress API/page responses for remote (Tailscale/TLS) clients — inventory
+    # and runs JSON shrink ~10×. Starlette excludes `text/event-stream` from
+    # compression by default, so the SSE stream at /api/events is untouched.
+    app.add_middleware(GZipMiddleware, minimum_size=1024)
+
     allow_origins = list(getattr(getattr(config, "settings", None), "ui_allow_origins", []) or [])
     if allow_origins:
         app.add_middleware(
@@ -464,7 +470,9 @@ def create_app(
     @app.get("/api/inventory")
     async def get_inventory(request: Request) -> dict[str, Any]:
         """Return all stored datasets."""
-        return {"datasets": _store(request).inventory()}
+        store = _store(request)
+        datasets = await asyncio.to_thread(store.inventory)
+        return {"datasets": datasets}
 
     # -----------------------------------------------------------------------
     # Remote sync
@@ -483,7 +491,9 @@ def create_app(
         remotes = [r.remote for r in cfg.storage.remotes]
         configured = bool(remotes)
         interval = cfg.storage.sync_interval
-        runs = _runs(request).list_runs(spec_id="remote-sync", limit=1)
+        runs = await asyncio.to_thread(
+            lambda: _runs(request).list_runs(spec_id="remote-sync", limit=1)
+        )
         last = None
         next_eta = None
         if runs:
@@ -496,7 +506,9 @@ def create_app(
             }
             if configured and r["ended_at"]:
                 next_eta = r["ended_at"] + interval * NS
-        total_bytes = sum(d.get("bytes", 0) for d in _store(request).inventory())
+        store = _store(request)
+        inventory = await asyncio.to_thread(store.inventory)
+        total_bytes = sum(d.get("bytes", 0) for d in inventory)
         return {
             "configured": configured,
             "remotes": remotes,
@@ -566,7 +578,7 @@ def create_app(
     @app.get("/api/backfill/{run_id}")
     async def get_backfill_status(run_id: str, request: Request) -> dict[str, Any]:
         """Get the status of a backfill run by ``run_id``."""
-        run = _runs(request).get_run(run_id)
+        run = await asyncio.to_thread(_runs(request).get_run, run_id)
         if not run:
             raise HTTPException(404, f"Run {run_id!r} not found")
         return _parse_run(run)
@@ -583,7 +595,8 @@ def create_app(
     @app.get("/api/runs")
     async def list_runs(request: Request, limit: int = 50) -> dict[str, Any]:
         """List recent job runs."""
-        return {"runs": [_parse_run(r) for r in _runs(request).list_runs(limit=limit)]}
+        runs = await asyncio.to_thread(lambda: _runs(request).list_runs(limit=limit))
+        return {"runs": [_parse_run(r) for r in runs]}
 
     # -----------------------------------------------------------------------
     # Stream control
@@ -785,6 +798,12 @@ def create_app(
 
         async def _generator():
             try:
+                # Flush an immediate comment: GZipMiddleware (even though it
+                # excludes text/event-stream from compression) buffers the
+                # response *start* until the first body chunk — without this,
+                # EventSource sits in "connecting" until the first event or
+                # the 30 s heartbeat.
+                yield ": connected\n\n"
                 while True:
                     if await request.is_disconnected():
                         break

{dccd-3.3.1 → dccd-3.4.0}/dccd/interfaces/ui/templates/dashboard.html

@@ -45,11 +45,13 @@ function kpi(label, value) {
 }
 
 async function load() {
-  // Fetch everything we need once.
-  let runs = [], streams = [], datasets = [];
-  try { runs = (await api('GET','/api/runs?limit=50')).runs || []; } catch (_) {}
-  try { streams = (await api('GET','/api/streams')).streams || []; } catch (_) {}
-  try { datasets = (await api('GET','/api/inventory')).datasets || []; } catch (_) {}
+  // Fetch everything we need once — in parallel: serial awaits cost 3×RTT,
+  // which is what a remote (Tailscale/TLS) client actually feels.
+  const [runsR, streamsR, invR] = await Promise.allSettled([
+    api('GET','/api/runs?limit=50'), api('GET','/api/streams'), api('GET','/api/inventory')]);
+  const runs = runsR.status === 'fulfilled' ? (runsR.value.runs || []) : [];
+  const streams = streamsR.status === 'fulfilled' ? (streamsR.value.streams || []) : [];
+  const datasets = invR.status === 'fulfilled' ? (invR.value.datasets || []) : [];
 
   const liveStreams = streams.filter(s => s.running);
   const activeRuns = runs.filter(r => r.state === 'running' || r.state === 'reconnecting');
@@ -118,6 +120,6 @@ async function load() {
 }
 
 load();
-setInterval(load, 8000);
+setInterval(load, 15000);
 </script>
 {% endblock %}

{dccd-3.3.1 → dccd-3.4.0}/dccd/interfaces/ui/templates/live.html

@@ -40,17 +40,22 @@ function invFor(j) {
   return INV.find(d => d.exchange===j.exchange && d.pair===pair && d.data_type===j.data_type);
 }
 
-async function loadAll() {
+async function loadAll(withInventory) {
   try {
-    const [jr, sr, ir] = await Promise.all([
-      api('GET','/api/jobs'), api('GET','/api/streams'), api('GET','/api/inventory')]);
+    // Inventory only seeds liveness from disk — fetch it on initial load and
+    // on SSE status changes (a stream stopped/failed wrote its last point),
+    // not on every 8 s poll: it is the heaviest endpoint and live samples
+    // arrive over SSE anyway.
+    const reqs = [api('GET','/api/jobs'), api('GET','/api/streams')];
+    if (withInventory) reqs.push(api('GET','/api/inventory'));
+    const [jr, sr, ir] = await Promise.all(reqs);
     JOBS = (jr.jobs||[]).filter(j => j.operation === 'stream');
     RUNNING = {};
     for (const s of (sr.streams||[])) RUNNING[s.id] = s.running;
     // Seed liveness from what's on disk so a page refresh immediately reflects
     // the last stored data point (and its freshness) instead of "waiting…".
     // Real-time SSE samples (`live`) always win and are never overwritten here.
-    INV = ir.datasets || [];
+    if (ir) INV = ir.datasets || [];
     for (const j of JOBS) {
       if (samples[j.id] && samples[j.id].live) continue;
       const inv = invFor(j);
@@ -187,7 +192,7 @@ async function toggleStream(jobId) {
     await api('POST', running?'/api/streams/stop':'/api/streams/start', { spec_id: jobId });
     toast(running?'Stream stopped':'Stream started','ok');
     if (running) delete samples[jobId];
-    setTimeout(loadAll, 400);
+    setTimeout(() => loadAll(true), 400);
   } catch (e) { toast(e.message,'err'); btn.disabled = false; }
 }
 
@@ -290,7 +295,7 @@ function connectSSE() {
       samples[specId] = { value: ev.value, bid: ev.bid, ask: ev.ask, ts: ev.ts, live: true };
     } else if (ev.kind === 'status') {
       // a stream stopping/failing → refresh state soon
-      setTimeout(loadAll, 300);
+      setTimeout(() => loadAll(true), 300);
     }
   };
   es.onerror = () => {
@@ -300,7 +305,7 @@ function connectSSE() {
 }
 
 initTabs('#live-tabs');
-loadAll();
+loadAll(true);
 connectSSE();
 setInterval(refreshLiveness, 1000);
 setInterval(loadAll, 8000);

{dccd-3.3.1 → dccd-3.4.0}/dccd/interfaces/ui/templates/storage.html

@@ -103,6 +103,7 @@ async function loadInventory() {
 
 loadSync();
 loadInventory();
-setInterval(loadSync, 10000);
+// Status view: 30 s is plenty ("Sync now" already polls itself after a trigger).
+setInterval(loadSync, 30000);
 </script>
 {% endblock %}

{dccd-3.3.1 → dccd-3.4.0}/dccd/sources/base.py

@@ -130,6 +130,25 @@ class TradesLive(Source):
 class OrderBookLive(Source):
     """Protocol: can stream live order book snapshots/deltas via WebSocket."""
 
-    def stream_orderbook(self, symbol: Symbol, depth: int) -> AsyncIterator[OrderBookSnapshot]:
-        """Yield live order-book snapshots/deltas over WebSocket."""
+    def stream_orderbook(
+        self,
+        symbol: Symbol,
+        depth: int,
+        *,
+        min_interval: float = 0.0,
+    ) -> AsyncIterator[OrderBookSnapshot]:
+        """Yield live order-book snapshots over WebSocket.
+
+        Parameters
+        ----------
+        symbol : Symbol
+        depth : int
+            Maximum number of levels per side to include in each snapshot.
+        min_interval : float, optional
+            Minimum seconds between emitted snapshots.  ``0.0`` (default)
+            preserves the legacy per-frame behaviour — every WS frame yields a
+            snapshot.  Pass ``snapshot_interval`` from the job spec to move the
+            throttle *upstream* so pydantic objects are only constructed for
+            frames that will actually be saved.
+        """
         raise NotImplementedError

{dccd-3.3.1 → dccd-3.4.0}/dccd/sources/binance.py

@@ -87,7 +87,7 @@ class BinanceSource(
             ),
             Capability(data_type=DataType.OHLC, transport="ws", mode="live"),
             Capability(data_type=DataType.TRADES, transport="ws", mode="live"),
-            Capability(data_type=DataType.ORDERBOOK, transport="ws", mode="live", max_depth=20),
+            Capability(data_type=DataType.ORDERBOOK, transport="ws", mode="live", max_depth=20, depths=[5, 10, 20]),
         ]
 
     def render_symbol(self, s: Symbol) -> str:
@@ -205,7 +205,13 @@ class BinanceSource(
         ws = _BinanceTradeWS(pair)
         return ws.stream()
 
-    def stream_orderbook(self, symbol: Symbol, depth: int) -> AsyncIterator[OrderBookSnapshot]:
+    def stream_orderbook(
+        self,
+        symbol: Symbol,
+        depth: int,
+        *,
+        min_interval: float = 0.0,
+    ) -> AsyncIterator[OrderBookSnapshot]:
         """Stream live order-book snapshots over WebSocket.
 
         Uses Binance's *partial book depth* stream, which pushes a fully sorted
@@ -214,7 +220,7 @@ class BinanceSource(
         pair = self.render_symbol(symbol).lower()
         levels = 5 if depth <= 5 else 10 if depth <= 10 else 20
         ws = _BinanceDepthWS(pair, levels)
-        return ws.stream()
+        return ws.stream(min_interval=min_interval)
 
 
 class _BinanceKlineWS(WebSocketBase):
@@ -279,3 +285,22 @@ class _BinanceDepthWS(WebSocketBase):
             asks=asks,
             is_snapshot=True,
         )
+
+    async def stream(self, min_interval: float = 0.0) -> AsyncIterator[OrderBookSnapshot]:
+        """Yield parsed order-book snapshots, throttled to *min_interval* seconds.
+
+        The throttle check is applied on the raw frame **before** calling
+        ``parse_message`` so no pydantic objects are constructed for frames that
+        will be discarded.  ``min_interval=0.0`` preserves the legacy per-frame
+        behaviour.
+        """
+        import time as _time
+        last_emit: float = -float("inf")  # first frame always emits
+        async for raw in self.stream_raw():
+            # Fast path: do a cheap JSON sniff before committing to parse_message.
+            now = _time.monotonic()
+            if now - last_emit < min_interval:
+                continue
+            async for record in self.parse_message(raw):
+                last_emit = _time.monotonic()
+                yield record

{dccd-3.3.1 → dccd-3.4.0}/dccd/sources/bitfinex.py

@@ -219,7 +219,13 @@ class BitfinexSource(OHLCHistory, TradesHistory, OrderBookSnapshotREST, OHLCLive
         ws = _BitfinexWS(_bfx_symbol(symbol), "trades")
         return ws.stream()
 
-    def stream_orderbook(self, symbol: Symbol, depth: int) -> AsyncIterator[OrderBookSnapshot]:
+    def stream_orderbook(
+        self,
+        symbol: Symbol,
+        depth: int,
+        *,
+        min_interval: float = 0.0,
+    ) -> AsyncIterator[OrderBookSnapshot]:
         """Stream live order-book snapshots/deltas over WebSocket."""
         raise NotImplementedError("Bitfinex live order book stream is not implemented")