timbro-protocol 0.10.0__py3-none-any.whl

timbro_protocol/_core.py

@@ -0,0 +1,565 @@
+"""Request building, response decoding, error mapping, and retry decisions.
+
+Nothing here performs I/O, so the sync and async executors share every rule.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import hashlib
+import json
+import logging
+import re
+import sys
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+from urllib.parse import quote, unquote, urlsplit
+
+import httpx
+
+from ._errors import (
+    RETRYABLE_STATUSES,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    ProblemDetail,
+    TimbroError,
+    UnexpectedResponseError,
+    api_error_class,
+)
+from ._operation import RAW_REQUEST, Operation
+
+DEFAULT_BASE_URL = "https://api.timbro.do"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRY_DELAY_SECONDS = 2.0
+
+LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+PATH_PARAMETER = re.compile(r"\{([^{}]+)\}")
+# Matched whole, with ASCII digits only, as the JavaScript SDKs do.
+PRINTABLE_ASCII = re.compile(r"[\x20-\x7e]+")
+DELTA_SECONDS = re.compile(r"[0-9]+")
+UUID = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
+IN_PROGRESS_CODE = "idempotency_request_in_progress"
+MAX_IDEMPOTENCY_KEY_LENGTH = 255
+MAX_RESPONSE_BYTES = 10 * 1024 * 1024
+JSON_MEDIA_TYPE = "application/json"
+
+# Failures raised before any request byte left this process.
+NOT_SENT_ERRORS = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.PoolTimeout,
+    httpx.ProxyError,
+    httpx.UnsupportedProtocol,
+    httpx.LocalProtocolError,
+)
+
+logger = logging.getLogger("timbro_protocol")
+
+TimeoutTypes = float | httpx.Timeout
+
+
+@dataclass(frozen=True)
+class FileResponse:
+    """The bytes of a successful download, before any check of its declared metadata.
+
+    `media_type` is the `Content-Type` without parameters, and `headers` holds every
+    response header under its lowercase name.
+    """
+
+    content: bytes = field(repr=False)
+    media_type: str
+    headers: Mapping[str, str] = field(repr=False)
+    request_id: str | None
+    operation: Operation
+
+
+@dataclass(frozen=True)
+class ClientSettings:
+    """Validated client configuration shared by the sync and async executors."""
+
+    api_key: str = field(repr=False)
+    base_url: str
+    timeout: httpx.Timeout
+    max_retries: int
+    user_agent: str
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: TimeoutTypes,
+        max_retries: int,
+        user_agent: str,
+    ) -> ClientSettings:
+        require_bearer_credential(api_key, "api_key")
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+            raise ValueError("max_retries must be a non-negative integer.")
+        return cls(
+            api_key=api_key,
+            base_url=normalize_base_url(base_url),
+            timeout=as_timeout(timeout),
+            max_retries=max_retries,
+            user_agent=user_agent,
+        )
+
+
+def require_bearer_credential(value: object, name: str) -> str:
+    if not isinstance(value, str) or value.strip() == "":
+        raise ValueError(f"{name} is required.")
+    # A credential that cannot be a header value would otherwise surface in an httpx error.
+    if not PRINTABLE_ASCII.fullmatch(value) or " " in value:
+        raise ValueError(f"{name} must be printable ASCII without spaces.")
+    return value
+
+
+def normalize_base_url(base_url: str) -> str:
+    """Returns the origin Timbro is reached at, refusing anything but an HTTPS origin.
+
+    Plain HTTP is allowed only for a loopback host, for local development.
+    """
+    try:
+        parts = urlsplit(base_url)
+        port = parts.port
+    except ValueError as error:
+        raise ValueError("base_url must be an absolute https origin.") from error
+    host = parts.hostname
+    if (
+        host is None
+        or parts.username is not None
+        or parts.password is not None
+        or parts.path not in ("", "/")
+        or parts.query != ""
+        or parts.fragment != ""
+        or base_url.endswith(("?", "#"))
+    ):
+        raise ValueError(
+            "base_url must be an origin with no path, query, fragment, or credentials."
+        )
+    if parts.scheme == "https" or (parts.scheme == "http" and host in LOCAL_HOSTS):
+        authority = f"[{host}]" if ":" in host else host
+        return f"{parts.scheme}://{authority}" + ("" if port is None else f":{port}")
+    raise ValueError("base_url must use https; http is allowed only for localhost.")
+
+
+def as_timeout(timeout: TimeoutTypes) -> httpx.Timeout:
+    if isinstance(timeout, httpx.Timeout):
+        return timeout
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+        raise ValueError("timeout must be a positive number of seconds or an httpx.Timeout.")
+    return httpx.Timeout(float(timeout))
+
+
+KeyMode = Literal["test", "live"] | None
+
+
+def key_mode(api_key: str) -> KeyMode:
+    """The mode a `sk_test_` or `sk_live_` key works in, or None for any other key form."""
+    if api_key.startswith("sk_test_"):
+        return "test"
+    if api_key.startswith("sk_live_"):
+        return "live"
+    return None
+
+
+def build_user_agent(package: str, version: str, application: str | None = None) -> str:
+    """Returns `timbro-<package>-python/<version> python/<x.y> httpx/<version> [application]`."""
+    python = f"{sys.version_info.major}.{sys.version_info.minor}"
+    agent = f"timbro-{package}-python/{version} python/{python} httpx/{httpx.__version__}"
+    if application is None:
+        return agent
+    if not PRINTABLE_ASCII.fullmatch(application) or application.strip() != application:
+        raise ValueError("application must be printable ASCII without surrounding spaces.")
+    return f"{agent} {application}"
+
+
+def build_request(
+    settings: ClientSettings,
+    operation: Operation,
+    *,
+    path_params: Mapping[str, str],
+    query: Mapping[str, object] | None,
+    body: Mapping[str, Any] | None,
+    idempotency_key: str | None,
+    timeout: httpx.Timeout | None,
+    access_token: str | None = None,
+    accept: str = JSON_MEDIA_TYPE,
+) -> httpx.Request:
+    """Builds the request; `timeout` is attached only when given, so a caller's client keeps its own.
+
+    `access_token` replaces the API key for an operation authorized by a grant.
+    """
+    credential = (
+        settings.api_key
+        if access_token is None
+        else require_bearer_credential(access_token, "access_token")
+    )
+    headers = {
+        "Authorization": f"Bearer {credential}",
+        "Accept": accept,
+        "User-Agent": settings.user_agent,
+    }
+    content: bytes | None = None
+    if body is not None:
+        headers["Content-Type"] = JSON_MEDIA_TYPE
+        content = json.dumps(
+            body, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+        ).encode("utf-8")
+    if idempotency_key is not None:
+        headers["Idempotency-Key"] = require_idempotency_key(idempotency_key)
+    params = [
+        (name, query_value(item))
+        for name, value in (query or {}).items()
+        if value is not None
+        for item in (value if isinstance(value, (list, tuple)) else [value])
+    ]
+    return httpx.Request(
+        operation.method,
+        settings.base_url + expand_path(operation.path, path_params),
+        params=tuple(params),
+        headers=headers,
+        content=content,
+        extensions={} if timeout is None else {"timeout": timeout.as_dict()},
+    )
+
+
+RAW_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
+# A /v1/ path of URL path characters only: no scheme, host, query, fragment, or template.
+RAW_PATH = re.compile(r"/v1/[A-Za-z0-9._~!$&'()*+,;=:@%/-]+")
+
+
+def raw_operation(method: str, path: str) -> Operation:
+    """The operation for a request to a route outside the published contract.
+
+    A `GET` is retried like any read; another method is retried only with an
+    idempotency key.
+    """
+    verb = method.upper() if isinstance(method, str) else ""
+    if verb not in RAW_METHODS:
+        raise ValueError(f"method must be one of {', '.join(sorted(RAW_METHODS))}.")
+    segments = path.split("/")[2:] if isinstance(path, str) else []
+    if (
+        not isinstance(path, str)
+        or RAW_PATH.fullmatch(path) is None
+        or any(unquote(segment) in ("", ".", "..") for segment in segments)
+    ):
+        raise ValueError("path must be a /v1/ path without a query, fragment, or empty segment.")
+    return Operation(
+        operation_id=f"{verb} {path}",
+        method=verb,
+        path=path,
+        retry="safe_to_retry" if verb == "GET" else "retry_with_same_idempotency_key",
+        idempotency="optional",
+        recovery=None,
+        name=RAW_REQUEST,
+    )
+
+
+def expand_path(template: str, path_params: Mapping[str, str]) -> str:
+    def replace(match: re.Match[str]) -> str:
+        value = path_params.get(match.group(1))
+        # "." and ".." survive percent-encoding and would address a different path.
+        if not isinstance(value, str) or value in ("", ".", ".."):
+            raise ValueError(f"{match.group(1)} must be a non-empty identifier.")
+        return quote(value, safe="")
+
+    return PATH_PARAMETER.sub(replace, template)
+
+
+def query_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (str, int, float)):
+        return str(value)
+    raise TypeError(f"Unsupported query parameter value of type {type(value).__name__}.")
+
+
+def require_idempotency_key(idempotency_key: str) -> str:
+    if (
+        not isinstance(idempotency_key, str)
+        or len(idempotency_key) > MAX_IDEMPOTENCY_KEY_LENGTH
+        or not PRINTABLE_ASCII.fullmatch(idempotency_key)
+        or idempotency_key.strip() == ""
+    ):
+        raise ValueError("idempotency_key must be 1 to 255 printable ASCII characters.")
+    return idempotency_key
+
+
+def derive_idempotency_key(command: str, identity: str) -> str:
+    """Returns `<command>_<hex sha256 of command, NUL, identity>`, as every Timbro SDK does."""
+    digest = hashlib.sha256(f"{command}\0{identity}".encode()).hexdigest()
+    return f"{command}_{digest}"
+
+
+def may_retry(operation: Operation, request: httpx.Request) -> bool:
+    """Retries a safe operation always, a keyed one only with its key, and nothing else."""
+    if operation.retry == "safe_to_retry":
+        return True
+    if operation.retry == "retry_with_same_idempotency_key":
+        return "Idempotency-Key" in request.headers
+    return False
+
+
+def retry_delay_after_response(
+    operation: Operation,
+    request: httpx.Request,
+    response: httpx.Response,
+    retry: int,
+    max_retries: int,
+) -> float | None:
+    """Seconds to wait before retrying, or None when the response is final."""
+    if (
+        retry >= max_retries
+        or response.status_code not in RETRYABLE_STATUSES
+        or not may_retry(operation, request)
+    ):
+        return None
+    retry_after = retry_after_seconds(response.headers.get("Retry-After"))
+    if retry_after is None:
+        return backoff_delay(retry)
+    return float(retry_after) if retry_after <= MAX_RETRY_DELAY_SECONDS else None
+
+
+def retry_delay_after_transport_error(
+    operation: Operation, request: httpx.Request, retry: int, max_retries: int
+) -> float | None:
+    if retry >= max_retries or not may_retry(operation, request):
+        return None
+    return backoff_delay(retry)
+
+
+def backoff_delay(retry: int) -> float:
+    return float(min(0.1 * 2**retry, MAX_RETRY_DELAY_SECONDS))
+
+
+def retry_after_seconds(header: str | None, now: float | None = None) -> int | None:
+    """Reads `Retry-After` as delta-seconds or an IMF-fixdate; None when absent or unusable."""
+    if header is None:
+        return None
+    value = header.strip()
+    if DELTA_SECONDS.fullmatch(value):
+        return int(value)
+    try:
+        at = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if at.tzinfo is None:
+        return None
+    remaining = at.timestamp() - (time.time() if now is None else now)
+    return max(0, -int(-remaining // 1))
+
+
+def transport_error(operation: Operation, error: httpx.TransportError) -> APIConnectionError:
+    """The error for a failed attempt; `settle` marks it `outcome_unknown` when it may have run."""
+    never_sent = isinstance(error, NOT_SENT_ERRORS)
+    if isinstance(error, httpx.TimeoutException):
+        return APITimeoutError(
+            "The request to Timbro timed out",
+            code="connection_failed" if never_sent else "request_timed_out",
+            operation=operation,
+        )
+    return APIConnectionError("Timbro could not be reached", operation=operation)
+
+
+def may_have_arrived(error: httpx.TransportError) -> bool:
+    return not isinstance(error, NOT_SENT_ERRORS)
+
+
+def settle(
+    operation: Operation, request: httpx.Request, error: TimbroError, reached: bool
+) -> TimbroError:
+    """Marks the final error of a call whose state change may have happened anyway.
+
+    `reached` is true when any attempt may have arrived at Timbro. A write is then
+    uncertain when the last attempt got no answer, a server failure, or word that the
+    first attempt is still running.
+    """
+    status = getattr(error, "status", None)
+    uncertain = (
+        isinstance(error, APIConnectionError)
+        or (isinstance(status, int) and status >= 500)
+        or error.code == IN_PROGRESS_CODE
+    )
+    error.outcome_unknown = reached and uncertain and not operation.is_read
+    if error.outcome_unknown and isinstance(error, APIConnectionError):
+        error.code = "outcome_unknown"
+    error._idempotency_key_sent = "Idempotency-Key" in request.headers
+    return error
+
+
+def log_response(operation: Operation, response: httpx.Response, attempt: int) -> None:
+    logger.debug(
+        "%s %s -> %s request_id=%s attempt=%d",
+        operation.method,
+        operation.path,
+        response.status_code,
+        response.headers.get("request-id"),
+        attempt,
+    )
+
+
+def decode_response(
+    operation: Operation,
+    response: httpx.Response,
+    content: bytes,
+    expect: Mapping[str, str] | None = None,
+) -> dict[str, Any] | None:
+    """Returns the JSON object of a success, None for 204, or raises the mapped error.
+
+    Each `expect` member names the identifier the answer must carry, so an answer
+    about another resource is refused.
+    """
+    status = response.status_code
+    if not 200 <= status < 300:
+        raise failure(operation, response, content)
+    require_bounded(operation, response, content)
+    if status == 204:
+        return None
+    body = parse_json_object(content)
+    if body is None:
+        raise unexpected(operation, response, "Timbro returned a success without a JSON object")
+    for member, identifier in (expect or {}).items():
+        if not same_identifier(body.get(member), identifier):
+            raise unexpected(
+                operation,
+                response,
+                f"Timbro answered with another {member} than the one requested",
+                code="response_identity_mismatch",
+            )
+    if operation.page:
+        require_page(operation, response, body)
+    return body
+
+
+def require_page(operation: Operation, response: httpx.Response, body: dict[str, Any]) -> None:
+    """Refuses a list page that is malformed or promises more rows without a cursor."""
+    cursor = body.get("nextCursor")
+    if (
+        body.get("object") != "list"
+        or not isinstance(body.get("data"), list)
+        or not isinstance(body.get("hasMore"), bool)
+        or not (cursor is None or isinstance(cursor, str))
+    ):
+        raise unexpected(operation, response, "Timbro returned a malformed list page")
+    if body["hasMore"] and (cursor is None or cursor == ""):
+        raise unexpected(
+            operation,
+            response,
+            "Timbro returned a page that promised more rows without a cursor",
+            code="collection_page_not_advancing",
+        )
+
+
+def decode_file(operation: Operation, response: httpx.Response, content: bytes) -> FileResponse:
+    """Returns the bytes of a successful download, or raises the mapped error."""
+    if not 200 <= response.status_code < 300:
+        raise failure(operation, response, content)
+    require_bounded(operation, response, content)
+    media_type = response.headers.get("content-type", "").split(";", 1)[0].strip().lower()
+    return FileResponse(
+        content=content,
+        media_type=media_type,
+        headers={name.lower(): value for name, value in response.headers.items()},
+        request_id=response.headers.get("request-id"),
+        operation=operation,
+    )
+
+
+def failure(operation: Operation, response: httpx.Response, content: bytes) -> TimbroError:
+    status = response.status_code
+    if 300 <= status < 400:
+        return unexpected(operation, response, "Timbro answered with a redirect, which is refused")
+    body = parse_json_object(content)
+    if body is None or not isinstance(body.get("code"), str):
+        return unexpected(operation, response, f"Timbro returned HTTP {status} without a Problem")
+    return problem_error(operation, response, body)
+
+
+def declares_too_much(response: httpx.Response) -> bool:
+    """True when `Content-Length` already exceeds the response limit."""
+    length = response.headers.get("content-length", "")
+    return length.isdigit() and int(length) > MAX_RESPONSE_BYTES
+
+
+def require_bounded(operation: Operation, response: httpx.Response, content: bytes) -> None:
+    if len(content) > MAX_RESPONSE_BYTES or declares_too_much(response):
+        raise unexpected(
+            operation,
+            response,
+            f"Timbro returned more than {MAX_RESPONSE_BYTES // (1024 * 1024)} MiB",
+            code="response_too_large",
+        )
+
+
+def same_identifier(actual: object, expected: str) -> bool:
+    """Compares canonical UUIDs without regard to letter case, and anything else exactly."""
+    if not isinstance(actual, str):
+        return False
+    if UUID.fullmatch(actual) and UUID.fullmatch(expected):
+        return actual.lower() == expected.lower()
+    return actual == expected
+
+
+def problem_error(operation: Operation, response: httpx.Response, body: dict[str, Any]) -> APIError:
+    status = response.status_code
+    title = body.get("title")
+    title = title if isinstance(title, str) and title != "" else f"HTTP {status}"
+    detail = body.get("detail")
+    message = detail if isinstance(detail, str) and detail != "" else title
+    request_id = body.get("requestId")
+    return api_error_class(status)(
+        message,
+        code=body["code"],
+        status=status,
+        title=title,
+        problems=problem_details(body.get("problems")),
+        retry_after_seconds=retry_after_seconds(response.headers.get("Retry-After")),
+        body=body,
+        request_id=request_id
+        if isinstance(request_id, str) and request_id != ""
+        else response.headers.get("request-id"),
+        operation=operation,
+    )
+
+
+def problem_details(problems: object) -> tuple[ProblemDetail, ...]:
+    if not isinstance(problems, list):
+        return ()
+    return tuple(
+        ProblemDetail(path=entry["path"], code=entry["code"], message=entry["message"])
+        for entry in problems
+        if isinstance(entry, dict)
+        and all(isinstance(entry.get(key), str) for key in ("path", "code", "message"))
+    )
+
+
+def parse_json_object(content: bytes) -> dict[str, Any] | None:
+    try:
+        value = json.loads(content)
+    except ValueError:
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def unexpected(
+    operation: Operation,
+    response: httpx.Response,
+    message: str,
+    *,
+    code: str = "unexpected_http_error",
+) -> UnexpectedResponseError:
+    status = response.status_code
+    return UnexpectedResponseError(
+        message,
+        code=code,
+        status=status,
+        retryable=status in RETRYABLE_STATUSES
+        or retry_after_seconds(response.headers.get("Retry-After")) is not None,
+        request_id=response.headers.get("request-id"),
+        operation=operation,
+    )