"""
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)