Home /Modules/synchro/http2.py

http2.py

synchro/synchro/http2.py · 204 line(s) · py

"""HTTP/2 client with a metered (rate-paced) sending path.

The "metered method" is a token-bucket rate limiter that paces outbound
requests to a configurable requests-per-second ceiling with a bounded burst.
This is the honest reading of "metered": deliberately throttled, predictable
egress — useful for large or international dataset transfers where you want to
avoid overrunning a peer or a shared link, and where HTTP/2 multiplexing lets
many streams share one connection.

Every request is timestamped; per-host timing is fed into the same LatencyStats
used by the UDP path, so HTTP results are reported with the same measured
min/p50/p95/p99/jitter/loss semantics — no guarantees, only observations.

Requires the optional ``httpx[http2]`` dependency for live requests. The module
imports without it; the pacing logic (RateMeter) is dependency-free and unit
testable on its own.
"""

from __future__ import annotations

import threading
import time
from dataclasses import dataclass
from typing import Dict, Iterable, List, Optional, Tuple

from .stats import LatencyStats, Sample

try:  # optional dependency
    import httpx  # type: ignore

    _HAVE_HTTPX = True
except Exception:  # pragma: no cover - env without httpx
    httpx = None  # type: ignore
    _HAVE_HTTPX = False


class RateMeter:
    """A thread-safe token-bucket for metered egress.

    Parameters
    ----------
    rate_per_s:
        Sustained requests per second (token refill rate).
    burst:
        Maximum tokens that can accumulate (burst allowance). Defaults to
        ``max(1, rate_per_s)``.
    """

    def __init__(self, rate_per_s: float, *, burst: Optional[float] = None) -> None:
        if rate_per_s <= 0:
            raise ValueError("rate_per_s must be positive")
        self.rate = float(rate_per_s)
        self.capacity = float(burst) if burst is not None else max(1.0, self.rate)
        self._tokens = self.capacity
        self._last = time.monotonic()
        self._lock = threading.Lock()

    def _refill(self) -> None:
        now = time.monotonic()
        elapsed = now - self._last
        self._last = now
        self._tokens = min(self.capacity, self._tokens + elapsed * self.rate)

    def acquire(self, tokens: float = 1.0) -> float:
        """Block until ``tokens`` are available. Returns seconds spent waiting."""
        waited = 0.0
        while True:
            with self._lock:
                self._refill()
                if self._tokens >= tokens:
                    self._tokens -= tokens
                    return waited
                deficit = tokens - self._tokens
                sleep_for = deficit / self.rate
            time.sleep(sleep_for)
            waited += sleep_for


@dataclass
class Http2Response:
    url: str
    status: Optional[int]
    elapsed_ms: float
    error: Optional[str] = None
    wait_ms: float = 0.0

    @property
    def ok(self) -> bool:
        return self.error is None and self.status is not None and 200 <= self.status < 400


class MeteredHttp2Client:
    """HTTP/2 client that paces requests through a RateMeter.

    Parameters
    ----------
    rate_per_s:
        Metered egress ceiling (requests/second).
    burst:
        Token-bucket burst allowance.
    timeout_s:
        Per-request timeout.
    window:
        Retained latency sample window per host.
    """

    def __init__(
        self,
        *,
        rate_per_s: float = 10.0,
        burst: Optional[float] = None,
        timeout_s: float = 10.0,
        window: int = 1024,
    ) -> None:
        self.meter = RateMeter(rate_per_s, burst=burst)
        self.timeout_s = timeout_s
        self.window = window
        self.stats: Dict[str, LatencyStats] = {}
        self._client = None
        self._seq = 0

    # backend protocol -----------------------------------------------------
    def open(self) -> "MeteredHttp2Client":
        if not _HAVE_HTTPX:
            raise RuntimeError(
                "MeteredHttp2Client requires the optional dependency "
                "'httpx[http2]'. Install it to perform live HTTP/2 requests; "
                "RateMeter can be used and tested without it."
            )
        if self._client is None:
            self._client = httpx.Client(  # type: ignore[attr-defined]
                http2=True, timeout=self.timeout_s
            )
        return self

    def close(self) -> None:
        if self._client is not None:
            self._client.close()
            self._client = None

    def __enter__(self):
        return self.open()

    def __exit__(self, *exc):
        self.close()

    def _host_key(self, url: str) -> str:
        try:
            from urllib.parse import urlparse

            p = urlparse(url)
            return p.netloc or url
        except Exception:
            return url

    def _stats_for(self, key: str) -> LatencyStats:
        if key not in self.stats:
            self.stats[key] = LatencyStats(key, window=self.window)
        return self.stats[key]

    def send(self, dest: str, payload: bytes = b"", *, method: str = "GET", **opts):
        """Backend-protocol entry point: one metered request to ``dest`` (a URL)."""
        return self.get(dest, method=method, **opts)

    def get(self, url: str, *, method: str = "GET", **kwargs) -> Http2Response:
        self.open()
        key = self._host_key(url)
        st = self._stats_for(key)
        self._seq += 1
        seq = self._seq

        wait_s = self.meter.acquire(1.0)  # metered pacing happens here
        sent = time.monotonic_ns()
        try:
            resp = self._client.request(method, url, **kwargs)  # type: ignore[union-attr]
            elapsed_ms = (time.monotonic_ns() - sent) / 1e6
            st.record(Sample(key, elapsed_ms, sent / 1e9, seq))
            return Http2Response(
                url=url,
                status=resp.status_code,
                elapsed_ms=elapsed_ms,
                wait_ms=wait_s * 1e3,
            )
        except Exception as exc:  # network error => record as loss
            elapsed_ms = (time.monotonic_ns() - sent) / 1e6
            st.record(Sample(key, None, sent / 1e9, seq))
            return Http2Response(
                url=url,
                status=None,
                elapsed_ms=elapsed_ms,
                error=str(exc),
                wait_ms=wait_s * 1e3,
            )

    def run(self, urls: Iterable[str], *, method: str = "GET") -> List[Http2Response]:
        """Send a metered sequence of requests and return per-request results."""
        results: List[Http2Response] = []
        try:
            for u in urls:
                results.append(self.get(u, method=method))
        finally:
            self.close()
        return results