hyperfluid 0.1.0__py3-none-any.whl

hyperfluid/api/common.py

@@ -0,0 +1,845 @@
+# this file is @generated by Perseid; edit the shared runtime template.
+"""Shared HTTP plumbing for the generated API resources.
+
+Authentication, an automatic ``idempotency-key`` on POST when the API deduplicates
+by it, retries with jittered exponential backoff, per-request timeouts and headers,
+and typed errors.
+
+Retries: a request is retried on connection errors, timeouts, 408, 429 and 5xx
+responses, honouring ``Retry-After`` (or ``retry-after-ms``) up to a minute,
+but only when replaying it is safe: for GET, HEAD, OPTIONS, TRACE, PUT and DELETE, and
+for any request carrying an ``idempotency-key``, which every POST gets
+automatically when the API deduplicates by it. A timed-out request can therefore take up to
+``timeout * (1 + max_retries)`` plus the backoff delays before
+:class:`APITimeoutError` is raised.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import datetime as _datetime
+import email.utils
+import enum
+import json
+import random
+import time
+import typing as t
+import urllib.parse
+import uuid
+from decimal import Decimal
+
+import httpx
+
+from .._exceptions import APIResponseValidationError, connection_error
+from .._version import __version__
+from ..serialization import (
+    UNSET,
+    JSONValue,
+    Unset,
+    format_datetime,
+    format_decimal,
+    from_json_value,
+    to_json_value,
+)
+from ._auth import (
+    OAuthTokens,
+    Security,
+    SecurityScheme,
+    TokenProvider,
+    apply_auth,
+    async_token,
+    chosen_schemes,
+    needs_token_provider,
+    oauth_scheme,
+    sync_token,
+    token_url,
+)
+from ._errors import error_class
+from ._response import capture_response
+from ._streaming import (
+    MultipartField,
+    UploadContent,
+    is_event_stream,
+    multipart_files,
+    not_an_event_stream,
+    replayable,
+)
+from .middleware import AsyncMiddleware, SyncMiddleware, chain_async, chain_sync
+
+__all__ = [
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_TIMEOUT",
+    "INITIAL_RETRY_DELAY",
+    "MAX_RETRY_DELAY",
+    "ApiBase",
+    "ApiBaseAsync",
+    "ApiBaseSync",
+    "ApiRequest",
+    "Configuration",
+    "EncodedPathParam",
+    "ErrorTypes",
+    "QueryParams",
+    "Timeout",
+    "decode_optional_response",
+    "decode_response",
+    "encode_path_param",
+    "json_header",
+    "serialize_form_body",
+    "serialize_query_params",
+]
+
+DEFAULT_TIMEOUT: float = 60
+DEFAULT_MAX_RETRIES = 2
+AUTO_IDEMPOTENCY_KEY: bool = json.loads("false")
+"""Whether the API deduplicates POSTs by ``idempotency-key``, so that each gets one to be retried."""
+INITIAL_RETRY_DELAY = 0.5
+"""Seconds before the first retry, doubling for each next one up to :data:`MAX_RETRY_DELAY`."""
+MAX_RETRY_DELAY = 8.0
+_MAX_RETRY_AFTER = 60.0
+_REPLAYABLE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "TRACE", "PUT", "DELETE"})
+
+QueryParams: t.TypeAlias = "list[tuple[str, str]]"
+Timeout: t.TypeAlias = "float | httpx.Timeout | None"
+"""Seconds, an ``httpx.Timeout`` for finer control, or ``None`` to wait forever."""
+
+_T = t.TypeVar("_T")
+
+
+def _serialize_scalar(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, enum.Enum):
+        return _serialize_scalar(value.value)
+    if isinstance(value, _datetime.datetime):
+        return format_datetime(value)
+    if isinstance(value, _datetime.date):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return format_decimal(value)
+    return str(value)
+
+
+def serialize_query_params(
+    params: t.Mapping[str, object],
+    comma_joined: t.Collection[str] = (),
+    structured: t.Collection[str] = (),
+    deep_object: t.Collection[str] = (),
+    delimited: t.Mapping[str, str] | None = None,
+    json_params: t.Collection[str] = (),
+) -> QueryParams:
+    """Render query parameters, dropping the ones left unset.
+
+    List values are exploded into repeated parameters (OpenAPI ``explode=true``)
+    unless their name is listed in ``comma_joined``. ``structured`` ones are sent
+    from their JSON value, objects as ``name[key]=value``, and ``deep_object``
+    lists as ``name[]=item``. ``delimited`` lists are joined by their delimiter
+    (``pipeDelimited``, ``spaceDelimited``) and ``json_params`` are sent as
+    compact JSON text (``content: application/json``).
+    """
+    out: QueryParams = []
+    for key, value in params.items():
+        if value is None or value is UNSET:
+            continue
+        if key in json_params:
+            out.append((key, _compact_json(to_json_value(value))))
+        elif delimited and key in delimited:
+            items = [
+                _serialize_scalar(v) for v in to_json_value(value) if v is not None
+            ]
+            if items:
+                out.append((key, delimited[key].join(items)))
+        elif key in structured:
+            explode = key not in comma_joined
+            encode_param(key, to_json_value(value), key in deep_object, explode, out)
+        elif isinstance(value, (list, tuple, set, frozenset)):
+            items = [_serialize_scalar(v) for v in t.cast("t.Iterable[object]", value)]
+            if key in comma_joined:
+                out.append((key, ",".join(items)))
+            else:
+                out.extend((key, item) for item in items)
+        else:
+            out.append((key, _serialize_scalar(value)))
+    return out
+
+
+def _compact_json(value: t.Any) -> str:
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def header_value(value: object) -> str | None:
+    """A header or cookie value as text: a list comma-separated, ``None`` for none."""
+    if value is None or value is UNSET:
+        return None
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return ",".join(_serialize_scalar(item) for item in value)
+    return _serialize_scalar(value)
+
+
+def json_header(value: t.Any) -> str | None:
+    """A ``content: application/json`` header value as compact JSON text."""
+    if value is None or value is UNSET:
+        return None
+    return _compact_json(to_json_value(value))
+
+
+class EncodedPathParam(str):
+    """A path parameter serialized and percent-encoded by its OpenAPI style."""
+
+
+def _quote_unreserved(text: str) -> str:
+    quoted = urllib.parse.quote(text, safe="")
+    # A `.` or `..` segment would be resolved away by the URL, leaving the resource path.
+    return quoted.replace(".", "%2E") if quoted in (".", "..") else quoted
+
+
+def _path_text(value: t.Any) -> str:
+    if value is None:
+        return ""
+    if _nested(value):
+        return _compact_json(value)
+    return _serialize_scalar(value)
+
+
+def encode_path_param(
+    name: str, value: t.Any, style: str, explode: bool
+) -> EncodedPathParam:
+    """A path parameter in its OpenAPI ``style`` (``simple``, ``label``, ``matrix``).
+
+    ``json`` is for ``content: application/json`` values. Every part is
+    percent-encoded, so that ``,`` ``.`` ``;`` and ``=`` are structural.
+    """
+    value = to_json_value(value)
+    if style == "json":
+        return EncodedPathParam(_quote_unreserved(_compact_json(value)))
+    result = _encode_styled_path_param(name, value, style, explode)
+    # A whole segment of dots, plain or percent-encoded, would be resolved away by the URL.
+    dots = result.replace("%2E", ".")
+    return EncodedPathParam("%2E" * len(dots) if dots in (".", "..") else result)
+
+
+def _encode_styled_path_param(
+    name: str, value: t.Any, style: str, explode: bool
+) -> str:
+    def quote(item: t.Any) -> str:
+        return _quote_unreserved(_path_text(item))
+
+    head, separator = {"label": (".", "."), "matrix": (";", ";")}.get(style, ("", ","))
+    key = _quote_unreserved(name)
+    if isinstance(value, list):
+        values = [quote(item) for item in value]
+        if style == "matrix":
+            if explode:
+                return "".join(f";{key}={item}" for item in values)
+            return f";{key}=" + ",".join(values)
+        return head + (separator if explode else ",").join(values)
+    if isinstance(value, dict):
+        pairs = [
+            (_quote_unreserved(field), quote(item)) for field, item in value.items()
+        ]
+        flat = ",".join(part for pair in pairs for part in pair)
+        if style == "matrix":
+            if explode:
+                return "".join(f";{field}={item}" for field, item in pairs)
+            return f";{key}={flat}"
+        if explode:
+            return head + separator.join(f"{f}={i}" for f, i in pairs)
+        return head + flat
+    text = quote(value)
+    if style == "label":
+        return f".{text}"
+    if style == "matrix":
+        return f";{key}" if text == "" else f";{key}={text}"
+    return text
+
+
+def serialize_form_body(
+    body: t.Mapping[str, JSONValue] | None,
+    deep_object: t.Collection[str] = (),
+    unexploded: t.Collection[str] = (),
+) -> QueryParams | None:
+    """The pairs of an ``application/x-www-form-urlencoded`` body, nested values as in queries."""
+    if body is None:
+        return None
+    out: QueryParams = []
+    for key, value in body.items():
+        encode_param(key, value, key in deep_object, key not in unexploded, out)
+    return out
+
+
+def _nested(value: object) -> bool:
+    return isinstance(value, (dict, list))
+
+
+def encode_param(
+    name: str, value: JSONValue, deep_object: bool, explode: bool, out: QueryParams
+) -> None:
+    """One JSON value as pairs, the way Stripe-style APIs read nested values.
+
+    Objects are sent as ``name[key]=value``, lists of scalars in them as
+    ``name[]=item`` and lists of objects as ``name[0][key]=value``. A top-level
+    list of scalars repeats ``name`` unless ``deep_object`` or not ``explode``.
+    """
+    if isinstance(value, list) and not deep_object and not any(map(_nested, value)):
+        items = [_serialize_scalar(v) for v in value if v is not None]
+        if explode:
+            out.extend((name, item) for item in items)
+        elif items:
+            out.append((name, ",".join(items)))
+        return
+    _flatten_param(name, value, out)
+
+
+def _flatten_param(prefix: str, value: JSONValue, out: QueryParams) -> None:
+    if value is None:
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            _flatten_param(f"{prefix}[{key}]", item, out)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _flatten_param(
+                f"{prefix}[{index}]" if _nested(item) else f"{prefix}[]", item, out
+            )
+    else:
+        out.append((prefix, _serialize_scalar(value)))
+
+
+@dataclasses.dataclass
+class Configuration:
+    """Resolved client configuration, shared by every resource."""
+
+    base_path: str
+    bearer_access_token: str | None = None
+    token_provider: TokenProvider | None = None
+    basic_auth: tuple[str, str] | None = None
+    oauth: OAuthTokens | None = None
+    api_keys: t.Mapping[str, str] = dataclasses.field(default_factory=dict[str, str])
+    security_schemes: t.Mapping[str, SecurityScheme] = dataclasses.field(
+        default_factory=dict[str, SecurityScheme]
+    )
+    security: Security = ()
+    user_agent: str = f"hyperfluid-python/{__version__}"
+    timeout: Timeout = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    default_headers: t.Mapping[str, str] = dataclasses.field(
+        default_factory=dict[str, str]
+    )
+    middleware: list[SyncMiddleware] = dataclasses.field(
+        default_factory=list[SyncMiddleware]
+    )
+    async_middleware: list[AsyncMiddleware] = dataclasses.field(
+        default_factory=list[AsyncMiddleware]
+    )
+
+    def headers(self) -> httpx.Headers:
+        headers = httpx.Headers(
+            {"user-agent": self.user_agent, "accept": "application/json"}
+        )
+        headers.update(self.default_headers)
+        return headers
+
+
+ErrorTypes: t.TypeAlias = "t.Mapping[str, object]"
+"""The schema of each error response by status: ``"404"``, ``"4XX"`` or ``"default"``."""
+
+
+@dataclasses.dataclass(frozen=True)
+class ApiRequest:
+    """One operation call, as the generated methods describe it."""
+
+    method: str
+    path: str
+    path_params: t.Mapping[str, str] | None = None
+    query_params: QueryParams | None = None
+    header_params: t.Mapping[str, str | None] | None = None
+    cookie_params: t.Mapping[str, str | None] | None = None
+    json_body: object = None
+    form_body: QueryParams | None = None
+    upload_body: UploadContent | None = None
+    upload_content_type: str = "application/octet-stream"
+    multipart: t.Sequence[MultipartField] | None = None
+    security: Security | None = None
+    error_types: ErrorTypes | None = None
+    extra_headers: t.Mapping[str, str] | None = None
+    extra_query: t.Mapping[str, object] | None = None
+    extra_body: t.Mapping[str, object] | None = None
+    timeout: Timeout | Unset = UNSET
+    max_retries: int | None = None
+    stream: bool = False
+    replayable: bool = False
+    """Whether a POST is safe to retry without an ``idempotency-key``."""
+
+
+def _with_extra_body(
+    spec: ApiRequest,
+) -> tuple[object, QueryParams | None, t.Sequence[MultipartField] | None]:
+    """The JSON, form and multipart bodies of ``spec``, with its ``extra_body`` properties."""
+    if not spec.extra_body:
+        return spec.json_body, spec.form_body, spec.multipart
+    extra: dict[str, JSONValue] = {
+        str(key): to_json_value(value) for key, value in spec.extra_body.items()
+    }
+    if spec.form_body is not None:
+        form = [*spec.form_body]
+        for key, value in extra.items():
+            encode_param(key, value, False, True, form)
+        return None, form, None
+    if spec.multipart is not None:
+        return (
+            None,
+            None,
+            [
+                *spec.multipart,
+                *((key, value, False, None) for key, value in extra.items()),
+            ],
+        )
+    if spec.upload_body is not None:
+        raise TypeError("extra_body needs a JSON, form or multipart request body")
+    if spec.json_body is None:
+        return extra, None, None
+    if not isinstance(spec.json_body, dict):
+        raise TypeError("extra_body needs a JSON object request body")
+    return {**t.cast("dict[str, JSONValue]", spec.json_body), **extra}, None, None
+
+
+def _raise_for_status(response: httpx.Response, error_types: ErrorTypes | None) -> None:
+    if response.is_success:
+        return
+    # Any other status -- 4xx, 5xx, or a 3xx left unfollowed -- is an error.
+    raise error_class(response.status_code)(
+        response, _error_body(response, error_types)
+    )
+
+
+def _error_body(response: httpx.Response, error_types: ErrorTypes | None) -> object:
+    """The error response as its declared schema, else its JSON, else ``None``."""
+    try:
+        data = response.json()
+    except ValueError:
+        return None
+    status = response.status_code
+    for key in (str(status), f"{status // 100}XX", "default"):
+        if error_types is not None and key in error_types:
+            try:
+                return from_json_value(error_types[key], data)
+            except (ValueError, TypeError):
+                break
+    return t.cast(object, data)
+
+
+@t.overload
+def decode_response(response: httpx.Response, type_: type[_T]) -> _T: ...
+
+
+@t.overload
+def decode_response(response: httpx.Response, type_: object) -> t.Any: ...
+
+
+def decode_response(response: httpx.Response, type_: object) -> object:
+    """Decode a 2xx JSON body into ``type_``.
+
+    Any failure -- invalid JSON or UTF-8, or a body that does not match the
+    type -- raises :class:`APIResponseValidationError`, so a client call only
+    ever raises :class:`HyperfluidError` subclasses.
+    """
+    try:
+        return t.cast(object, from_json_value(type_, response.json()))
+    # `json.JSONDecodeError`, `UnicodeDecodeError` and `ModelParseError` are
+    # `ValueError`s; `TypeError` covers a JSON shape the model code trips on.
+    except (ValueError, TypeError) as exc:
+        raise APIResponseValidationError(response, str(exc)) from exc
+
+
+@t.overload
+def decode_optional_response(
+    response: httpx.Response, type_: type[_T]
+) -> _T | None: ...
+
+
+@t.overload
+def decode_optional_response(response: httpx.Response, type_: object) -> t.Any: ...
+
+
+def decode_optional_response(response: httpx.Response, type_: object) -> object:
+    """Like :func:`decode_response`, but ``None`` for a 2xx without a body, such as a 204,
+    or with a JSON ``null`` body."""
+    if response.status_code in (204, 205) or response.content.strip() in (b"", b"null"):
+        return None
+    return decode_response(response, type_)
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    """The delay a response asks for before a retry, in seconds, if any."""
+    header = response.headers.get("retry-after-ms")
+    if header is not None:
+        try:
+            return float(header) / 1000
+        except ValueError:
+            pass
+    header = response.headers.get("retry-after")
+    if header is None:
+        return None
+    try:
+        return float(header)
+    except ValueError:
+        pass
+    try:
+        date: _datetime.datetime = email.utils.parsedate_to_datetime(header)
+    except (TypeError, ValueError):
+        return None
+    return (date - _datetime.datetime.now(_datetime.timezone.utc)).total_seconds()
+
+
+def _retryable_status(status: int) -> bool:
+    return status in (408, 429) or status >= 500
+
+
+class ApiBase:
+    """Turns one operation into ``httpx`` requests and decides on retries."""
+
+    _cfg: Configuration
+
+    def __init__(self, cfg: Configuration) -> None:
+        self._cfg = cfg
+
+    def _build(
+        self,
+        client: httpx.Client | httpx.AsyncClient,
+        spec: ApiRequest,
+        token: str | None,
+    ) -> tuple[httpx.Request, bool]:
+        """The ``httpx`` request of ``spec``, and whether it is safe to send again."""
+        path = spec.path
+        if spec.path_params:
+            path = path.format(
+                **{
+                    key: value
+                    if isinstance(value, EncodedPathParam)
+                    else _quote_unreserved(str(value))
+                    for key, value in spec.path_params.items()
+                }
+            )
+
+        headers = self._cfg.headers()
+        headers["hyperfluid-req-id"] = str(random.getrandbits(32))
+        for key, value in (spec.header_params or {}).items():
+            if value is not None:
+                headers[key] = value
+        headers.update(spec.extra_headers or {})
+        # Cookie parameters share one `Cookie` header with the cookie of a call's own headers
+        # and, once authenticated, with the API key cookie.
+        cookies = [
+            f"{key}={urllib.parse.quote(value, safe='')}"
+            for key, value in (spec.cookie_params or {}).items()
+            if value is not None
+        ]
+        if cookies:
+            previous = headers.get("cookie")
+            if previous is not None:
+                cookies.append(previous)
+            headers["cookie"] = "; ".join(cookies)
+        method = spec.method.upper()
+        if (
+            AUTO_IDEMPOTENCY_KEY
+            and method == "POST"
+            and "idempotency-key" not in headers
+        ):
+            headers["idempotency-key"] = f"auto_{uuid.uuid4()}"
+        if spec.stream:
+            headers["accept"] = "text/event-stream"
+
+        # `httpx` replaces the query of the URL by `params`, so a path's own query goes first.
+        path, _, own_query = path.partition("?")
+        params = urllib.parse.parse_qsl(own_query, keep_blank_values=True)
+        extra_query = spec.extra_query or {}
+        params.extend(
+            (key, value)
+            for key, value in spec.query_params or []
+            if key.partition("[")[0] not in extra_query
+        )
+        params.extend(serialize_query_params(extra_query))
+
+        content: str | UploadContent | None = None
+        json_body, form_body, multipart = _with_extra_body(spec)
+        files = multipart_files(multipart) if multipart is not None else []
+        if form_body is not None:
+            content = urllib.parse.urlencode(form_body)
+            headers["content-type"] = "application/x-www-form-urlencoded"
+        elif spec.upload_body is not None:
+            content = spec.upload_body
+            headers["content-type"] = spec.upload_content_type
+
+        schemes = chosen_schemes(
+            self._cfg, self._cfg.security if spec.security is None else spec.security
+        )
+        credentials = httpx.Headers()
+        apply_auth(self._cfg, schemes, token, credentials, params)
+        for key, value in credentials.items():
+            # Headers of the client or of the call win over its credentials.
+            if key == "cookie" and key in headers:
+                headers[key] = f"{headers[key]}; {value}"
+            elif key not in headers:
+                headers[key] = value
+
+        # Passed per request, so it also applies to a caller-supplied `httpx` client.
+        timeout = self._cfg.timeout if isinstance(spec.timeout, Unset) else spec.timeout
+        if spec.stream and timeout is not None:
+            # The timeout only covers opening an event stream, not reading it.
+            limits = httpx.Timeout(timeout)
+            timeout = httpx.Timeout(
+                connect=limits.connect, read=None, write=limits.write, pool=limits.pool
+            )
+        request = client.build_request(
+            method,
+            path if "://" in path else f"{self._cfg.base_path}{path}",
+            params=tuple(params) or None,
+            headers=headers,
+            content=content,
+            json=json_body,
+            files=files or None,
+            timeout=timeout,
+        )
+        safe = (
+            spec.replayable
+            or method in _REPLAYABLE_METHODS
+            or "idempotency-key" in headers
+        )
+        return request, safe and replayable(content, files)
+
+    def _needs_token(self, spec: ApiRequest) -> bool:
+        security = self._cfg.security if spec.security is None else spec.security
+        return needs_token_provider(self._cfg, chosen_schemes(self._cfg, security))
+
+    def _oauth_scheme(self, spec: ApiRequest) -> SecurityScheme | None:
+        """The OAuth2 scheme whose access token this client fetches for ``spec``, if any."""
+        security = self._cfg.security if spec.security is None else spec.security
+        return oauth_scheme(self._cfg, chosen_schemes(self._cfg, security))
+
+    def _token_request(self, scheme: SecurityScheme) -> tuple[str, ApiRequest]:
+        """The URL of the token endpoint of ``scheme`` and the client credentials request to it."""
+        oauth = self._cfg.oauth
+        assert oauth is not None
+        url = token_url(self._cfg.base_path, scheme.token_url)
+        form, headers = oauth.request_parts(scheme.scope)
+        # Another token is as good as the first: the request is safe to retry.
+        return url, ApiRequest(
+            "POST",
+            url,
+            form_body=form,
+            security=(),
+            extra_headers=headers,
+            replayable=True,
+        )
+
+    def _rejected_token(
+        self,
+        response: httpx.Response,
+        request: httpx.Request,
+        used: tuple[str, str] | None,
+        renewed: bool,
+        replayable: bool,
+    ) -> bool:
+        """Whether ``response`` rejects the OAuth2 access token ``used`` (its cache key and
+        value) that the request carried, which is then forgotten."""
+        oauth = self._cfg.oauth
+        if (
+            oauth is None
+            or used is None
+            or renewed
+            or not replayable
+            or response.status_code != 401
+            or request.headers.get("authorization") != f"Bearer {used[1]}"
+        ):
+            return False
+        oauth.invalidate(*used)
+        return True
+
+    @staticmethod
+    def _parse_token(response: httpx.Response) -> tuple[str, float | None]:
+        """The access token and its lifetime in seconds of a token endpoint response."""
+        try:
+            body = response.json()
+            token = body["access_token"]
+            if not isinstance(token, str) or not token:
+                raise ValueError("access_token is not a string")
+            expires = body.get("expires_in")
+            return token, None if expires is None else float(expires)
+        except (ValueError, TypeError, KeyError, AttributeError) as exc:
+            raise APIResponseValidationError(
+                response,
+                f"the token endpoint response has no usable access_token: {exc}",
+            ) from exc
+
+    def _retry_delay(
+        self,
+        spec: ApiRequest,
+        attempt: int,
+        replayable: bool,
+        response: httpx.Response | None,
+    ) -> float | None:
+        """Seconds to wait before retrying, or ``None`` to give up."""
+        max_retries = (
+            self._cfg.max_retries if spec.max_retries is None else spec.max_retries
+        )
+        if attempt >= max_retries or not replayable:
+            return None
+        if response is not None:
+            if not _retryable_status(response.status_code):
+                return None
+            retry_after = _retry_after(response)
+            if retry_after is not None and 0 <= retry_after <= _MAX_RETRY_AFTER:
+                return retry_after
+        backoff = min(INITIAL_RETRY_DELAY * 2.0**attempt, MAX_RETRY_DELAY)
+        return backoff * (1 - 0.25 * random.random())
+
+    @staticmethod
+    def _finish(response: httpx.Response, spec: ApiRequest) -> None:
+        _raise_for_status(response, spec.error_types)
+        if spec.stream and not is_event_stream(response):
+            raise not_an_event_stream(response)
+        capture_response(response)
+
+
+class ApiBaseSync(ApiBase):
+    _httpx_client: httpx.Client
+
+    def __init__(self, cfg: Configuration, httpx_client: httpx.Client) -> None:
+        super().__init__(cfg)
+        self._httpx_client = httpx_client
+
+    def _send(self, request: httpx.Request, stream: bool) -> httpx.Response:
+        send = chain_sync(
+            lambda request: self._httpx_client.send(request, stream=stream),
+            self._cfg.middleware,
+        )
+        response = send(request)
+        if stream and not response.is_success:
+            response.read()
+        return response
+
+    def _oauth_token(self, scheme: SecurityScheme) -> tuple[str, str]:
+        """The access token of ``scheme`` with its cache key (token URL and scope): the cached one, else a new one.
+        Concurrent callers share one token request."""
+        oauth = self._cfg.oauth
+        assert oauth is not None
+        url, spec = self._token_request(scheme)
+        key = f"{url}\n{scheme.scope}"
+        with oauth.lock:
+            token = oauth.cached(key)
+            if token is None:
+                token = oauth.store(key, *self._parse_token(self._request(spec)))
+        return key, token
+
+    def _request(self, spec: ApiRequest) -> httpx.Response:
+        token = sync_token(self._cfg) if self._needs_token(spec) else None
+        scheme = self._oauth_scheme(spec)
+        used: tuple[str, str] | None = None
+        if scheme is not None:
+            used = self._oauth_token(scheme)
+            token = used[1]
+        request, replayable = self._build(self._httpx_client, spec, token)
+        attempt = 0
+        renewed = False
+        while True:
+            try:
+                response = self._send(request, spec.stream)
+            except httpx.RequestError as exc:
+                delay = self._retry_delay(spec, attempt, replayable, None)
+                if delay is None:
+                    raise connection_error(exc) from exc
+            else:
+                if scheme is not None and self._rejected_token(
+                    response, request, used, renewed, replayable
+                ):
+                    # The API rejected the access token: one request with a new one, which
+                    # does not use up a retry.
+                    renewed = True
+                    response.close()
+                    used = self._oauth_token(scheme)
+                    request.headers["authorization"] = f"Bearer {used[1]}"
+                    continue
+                delay = self._retry_delay(spec, attempt, replayable, response)
+                if delay is None:
+                    try:
+                        self._finish(response, spec)
+                    except BaseException:
+                        response.close()
+                        raise
+                    return response
+                response.close()
+            time.sleep(delay)
+            attempt += 1
+            request.headers["hyperfluid-retry-count"] = str(attempt)
+
+
+class ApiBaseAsync(ApiBase):
+    _httpx_client: httpx.AsyncClient
+
+    def __init__(self, cfg: Configuration, httpx_client: httpx.AsyncClient) -> None:
+        super().__init__(cfg)
+        self._httpx_client = httpx_client
+
+    async def _send(self, request: httpx.Request, stream: bool) -> httpx.Response:
+        send = chain_async(
+            lambda request: self._httpx_client.send(request, stream=stream),
+            self._cfg.async_middleware,
+        )
+        response = await send(request)
+        if stream and not response.is_success:
+            await response.aread()
+        return response
+
+    async def _oauth_token(self, scheme: SecurityScheme) -> tuple[str, str]:
+        """The access token of ``scheme`` with its cache key (token URL and scope): the cached one, else a new one.
+        Concurrent callers share one token request."""
+        oauth = self._cfg.oauth
+        assert oauth is not None
+        url, spec = self._token_request(scheme)
+        key = f"{url}\n{scheme.scope}"
+        async with oauth.async_lock():
+            token = oauth.cached(key)
+            if token is None:
+                token = oauth.store(key, *self._parse_token(await self._request(spec)))
+        return key, token
+
+    async def _request(self, spec: ApiRequest) -> httpx.Response:
+        token = await async_token(self._cfg) if self._needs_token(spec) else None
+        scheme = self._oauth_scheme(spec)
+        used: tuple[str, str] | None = None
+        if scheme is not None:
+            used = await self._oauth_token(scheme)
+            token = used[1]
+        request, replayable = self._build(self._httpx_client, spec, token)
+        attempt = 0
+        renewed = False
+        while True:
+            try:
+                response = await self._send(request, spec.stream)
+            except httpx.RequestError as exc:
+                delay = self._retry_delay(spec, attempt, replayable, None)
+                if delay is None:
+                    raise connection_error(exc) from exc
+            else:
+                if scheme is not None and self._rejected_token(
+                    response, request, used, renewed, replayable
+                ):
+                    # The API rejected the access token: one request with a new one, which
+                    # does not use up a retry.
+                    renewed = True
+                    await response.aclose()
+                    used = await self._oauth_token(scheme)
+                    request.headers["authorization"] = f"Bearer {used[1]}"
+                    continue
+                delay = self._retry_delay(spec, attempt, replayable, response)
+                if delay is None:
+                    try:
+                        self._finish(response, spec)
+                    except BaseException:
+                        await response.aclose()
+                        raise
+                    return response
+                await response.aclose()
+            await asyncio.sleep(delay)
+            attempt += 1
+            request.headers["hyperfluid-retry-count"] = str(attempt)