Source code for jitxlib.jlcpcb.parts.client

"""
The HTTP plumbing both part sources need
========================================

`JSONClient` is the only place in this package that speaks HTTP. Both the LCSC
and the JLCPCB list APIs are unauthenticated JSON POST endpoints that report
failure in the response body rather than the status line, so the two clients
differ in their base URL, their paths and how the body wraps a result, and in
nothing else.

Every failure, including a transport error, a failure code in the body and
malformed JSON, is raised as `ProviderUnavailable`. That is what lets a design
with a populated lockfile build on a box with no network: the chain reports
itself unreachable and the lock answers instead.
"""

from __future__ import annotations

import json
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any

from jitxlib.parts.error import ProviderUnavailable

# LCSC's list endpoints sit behind a WAF that answers an unadorned request with
# an Akamai error page; a browser user agent and the site's own origin are
# enough, and no cookie or token is involved. JLCPCB needs none of this and
# answers a bare request, but sending it costs nothing and keeps one client.
HEADERS: dict[str, str] = {
    "User-Agent": (
        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
        "(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
    ),
    "Content-Type": "application/json;charset=UTF-8",
    "Accept": "application/json, text/plain, */*",
    "Accept-Language": "en-US,en;q=0.9",
}


[docs] @dataclass(frozen=True) class JSONClient(ABC): """POSTs JSON to one host and unwraps whatever envelope it answers with. Args: base_url: API host, for pointing at a mirror or a recording proxy. timeout: per-request timeout in seconds. attempts: how many times a request is tried before giving up. """ base_url: str timeout: float = 20.0 attempts: int = 2 _session: dict[str, Any] = field( default_factory=dict, init=False, repr=False, compare=False ) @property @abstractmethod def label(self) -> str: """How this client names itself in a `ProviderUnavailable` message.""" @property def origin(self) -> dict[str, str]: """Extra headers this host wants, such as an `Origin` and a `Referer`.""" return {}
[docs] @abstractmethod def unwrap(self, path: str, payload: Any) -> dict[str, Any]: """The result object inside a decoded response body. Raises `ProviderUnavailable` when the body says the request failed, which is where the two APIs' envelopes differ: LCSC answers `{"code": 200, "result": ...}` and JLCPCB `{"code": 200, "data": ...}`, both reporting failure with a non-200 `code` and HTTP 200. """
[docs] def post(self, path: str, body: dict[str, Any]) -> dict[str, Any]: """The result of one request, or `ProviderUnavailable` naming why not.""" import httpx client = self._client() last: Exception | None = None for _ in range(max(1, self.attempts)): try: response = client.post(path, content=json.dumps(body).encode("utf-8")) except httpx.HTTPError as exc: # Transport level: a timeout or a refused connection is worth one # more try, since the alternative is failing a build on a blip. last = exc continue return self._decode(path, response) raise ProviderUnavailable(f"{self.label}: {path} could not be reached: {last}")
[docs] def unavailable(self, message: str) -> ProviderUnavailable: """A `ProviderUnavailable` naming this client, for `unwrap` to raise.""" return ProviderUnavailable(f"{self.label}: {message}")
def _client(self) -> Any: """One httpx client, kept alive so requests share a connection. httpx is imported here rather than at module scope: it arrives with jitx, but a failure to import it should be reported as this provider being unavailable rather than as the package failing to load. """ existing = self._session.get("client") if existing is not None: return existing try: import httpx except ImportError as exc: # pragma: no cover - httpx ships with jitx raise self.unavailable(f"httpx is not installed: {exc}") from exc client = httpx.Client( base_url=self.base_url, headers={**HEADERS, **self.origin}, timeout=self.timeout, ) self._session["client"] = client return client def _decode(self, path: str, response: Any) -> dict[str, Any]: if response.status_code != 200: raise self.unavailable(f"{path} answered HTTP {response.status_code}") try: payload = response.json() except ValueError as exc: # A WAF challenge is served as HTML with a 200, so this branch is the # usual shape of being blocked rather than a rare parser accident. raise self.unavailable( f"{path} answered with something that is not JSON" ) from exc return self.unwrap(path, payload)