Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

6.6 KB
Raw Blame
"""A deliberately thin HTTP client.

The suite tests a server, so it must not paper over anything a server does. This client therefore
does no retrying, no redirect chasing, and no error raising — every check sees the exact status,
headers and body the server sent, including the malformed ones.
"""
from __future__ import annotations

import json
import time
import urllib.error
import urllib.request
from dataclasses import dataclass, field


@dataclass
class Result:
    status: int
    headers: dict
    body: bytes
    elapsed_s: float
    url: str
    method: str

    @property
    def json(self):
        """Parsed body, or None when it is not JSON. Never raises: a server returning HTML where
        JSON was promised is a finding to report, not an exception to crash the run."""
        try:
            return json.loads(self.body.decode("utf-8"))
        except Exception:  # noqa: BLE001
            return None

    @property
    def text(self) -> str:
        """The body as text, for a failure message that quotes what the server said. Never raises,
        for the same reason `json` does not: this string is built inside an assert's message, so an
        exception here would surface as ERROR — a bug in the suite — and bury the server's defect."""
        return self.body.decode("utf-8", "replace")

    def header(self, name: str) -> str:
        return self.headers.get(name.lower(), "")


@dataclass
class Client:
    base_url: str
    api_key: str = ""
    timeout: float = 300.0
    calls: list = field(default_factory=list)
    # Sent on every request, before the per-call headers. For targets that need something a
    # stock UHP client never sends, such as a bring-your-own-key host that wants the caller's
    # model key in a header of its own: the suite measures the protocol, the header pays for it.
    headers: dict = field(default_factory=dict)

    def _url(self, path: str) -> str:
        return f"{self.base_url.rstrip('/')}{path}"

    def request(self, method: str, path: str, *, body=None, headers=None,
                auth: bool = True, raw: bytes | None = None, content_type: str | None = None) -> Result:
        url = self._url(path)
        h = {"accept": "application/json"}
        if auth and self.api_key:
            h["authorization"] = f"Bearer {self.api_key}"
        if body is not None:
            raw = json.dumps(body).encode()
            h["content-type"] = "application/json"
        if content_type:
            h["content-type"] = content_type
        h.update({k.lower(): v for k, v in self.headers.items()})
        h.update({k.lower(): v for k, v in (headers or {}).items()})

        req = urllib.request.Request(url, data=raw, method=method, headers=h)
        t0 = time.time()
        try:
            with urllib.request.urlopen(req, timeout=self.timeout) as r:
                res = Result(r.status, {k.lower(): v for k, v in r.headers.items()},
                             r.read(), time.time() - t0, url, method)
        except urllib.error.HTTPError as e:
            res = Result(e.code, {k.lower(): v for k, v in (e.headers or {}).items()},
                         e.read(), time.time() - t0, url, method)
        except Exception as e:  # noqa: BLE001 — a transport failure is a result, not a crash
            res = Result(0, {}, str(e).encode(), time.time() - t0, url, method)
        self.calls.append(res)
        return res

    def get(self, path, **kw):
        return self.request("GET", path, **kw)

    def post(self, path, **kw):
        return self.request("POST", path, **kw)

    def put(self, path, **kw):
        return self.request("PUT", path, **kw)

    def delete(self, path, **kw):
        return self.request("DELETE", path, **kw)

    def stream(self, path: str, body: dict, *, headers=None, max_seconds: float = 300.0) -> list[dict]:
        """POST and read Server-Sent Events, returning the parsed `data:` objects in arrival order.

        Reads incrementally rather than buffering the whole body, so a server that only flushes at
        the end is measurable (see the streaming-progressiveness check) instead of indistinguishable
        from a fast one.
        """
        url = self._url(path)
        h = {"accept": "text/event-stream", "content-type": "application/json"}
        if self.api_key:
            h["authorization"] = f"Bearer {self.api_key}"
        h.update({k.lower(): v for k, v in self.headers.items()})
        h.update({k.lower(): v for k, v in (headers or {}).items()})
        req = urllib.request.Request(url, data=json.dumps(body).encode(), method="POST", headers=h)

        events: list[dict] = []
        t0 = time.time()
        try:
            with urllib.request.urlopen(req, timeout=max_seconds) as r:
                self.stream_headers = {k.lower(): v for k, v in r.headers.items()}
                self.stream_status = r.status
                buf = b""
                for chunk in r:
                    buf = _drain_sse(buf + chunk, events, t0)
                    if time.time() - t0 > max_seconds:
                        break
                else:
                    _drain_sse(buf, events, t0, final=True)
        except urllib.error.HTTPError as e:
            self.stream_status = e.code
            self.stream_headers = {k.lower(): v for k, v in (e.headers or {}).items()}
            self.stream_error = e.read().decode("utf-8", "replace")[:500]
        except Exception as e:  # noqa: BLE001
            self.stream_status = 0
            self.stream_headers = {}
            self.stream_error = str(e)[:500]
        return events


def _drain_sse(buf: bytes, events: list[dict], t0: float, *, final: bool = False) -> bytes:
    """Append every complete Server-Sent Event in `buf` to `events`; return the unparsed rest.

    Lines may end in CRLF, LF or CR (WHATWG HTML, "Parsing an event stream"); sse-starlette, for
    one, frames with CRLF by default. A trailing CR is held back unless `final`, since it may be
    the first half of a CRLF split across reads. An event's data is its `data:` lines joined by LF.
    """
    held = b""
    if buf.endswith(b"\r") and not final:
        buf, held = buf[:-1], b"\r"
    buf = buf.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
    while b"\n\n" in buf:
        raw, _, buf = buf.partition(b"\n\n")
        data = [ln[5:].removeprefix(b" ") for ln in raw.split(b"\n") if ln.startswith(b"data:")]
        if not data:
            continue
        try:
            ev = json.loads(b"\n".join(data).decode("utf-8"))
        except Exception:  # noqa: BLE001
            continue
        if isinstance(ev, dict):
            ev["__t"] = time.time() - t0     # arrival time, for progressiveness
            events.append(ev)
    return buf + held