millwork-solver 0.1.0__py3-none-any.whl

millwork_solver/_core/clients.py

@@ -0,0 +1,264 @@
+"""Repository-internal sync and async clients over the shared wire policy."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import Any, Awaitable, Callable
+
+from ..types import Page
+from .catalog import _OperationCatalog
+from .errors import _ClientClosedError, _ProtocolResponseError
+from .transport import _AsyncTransport, _SyncTransport, _TransportPolicy, _prepare_request
+
+
+def _page_from_response(response: Any, item_field: str) -> Page:
+    if not isinstance(response, dict):
+        raise _ProtocolResponseError("paginated response must be an object")
+    items = response.get(item_field)
+    cursor = response.get("next_cursor")
+    if not isinstance(items, list) or (cursor is not None and not isinstance(cursor, str)):
+        raise _ProtocolResponseError("paginated response has the wrong shape")
+    return Page(tuple(items), cursor)
+
+
+def _events_from_response(response: Any) -> tuple[Mapping[str, Any], ...]:
+    if not isinstance(response, dict) or not isinstance(response.get("events"), list):
+        raise _ProtocolResponseError("events response has the wrong shape")
+    events = response["events"]
+    if any(not isinstance(event, dict) for event in events):
+        raise _ProtocolResponseError("event entries must be objects")
+    return tuple(events)
+
+
+def _is_terminal_event(event: Mapping[str, Any]) -> bool:
+    return (
+        event.get("type") == "lifecycle"
+        and event.get("slice_id") is None
+        and event.get("state") in {"completed", "failed", "cancelled", "expired"}
+    )
+
+
+class _SyncClient:
+    def __init__(
+        self,
+        catalog: _OperationCatalog,
+        policy: _TransportPolicy,
+        transport: _SyncTransport,
+        *,
+        close_transport: Callable[[], None],
+        sleep: Callable[[float], None],
+    ) -> None:
+        self._catalog = catalog
+        self._policy = policy
+        self._transport = transport
+        self._close_transport = close_transport
+        self._sleep = sleep
+        self._closed = False
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise _ClientClosedError("client is closed")
+
+    def _resolve_fixture_request(self, method: str, path: str) -> tuple[str, Mapping[str, str]]:
+        return self._catalog.match_fixture_request(method, path)
+
+    def request(
+        self,
+        operation_id: str,
+        *,
+        path_parameters: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+        body: object | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        self._ensure_open()
+        operation = self._catalog.operation(operation_id)
+        prepared = _prepare_request(
+            operation_id=operation.operation_id,
+            method=operation.method,
+            path=operation.bind_path(path_parameters),
+            query=query,
+            body=body,
+            idempotency_key=idempotency_key,
+            policy=self._policy,
+        )
+        return self._transport.execute(prepared)
+
+    def pages(
+        self,
+        operation_id: str,
+        *,
+        item_field: str,
+        path_parameters: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+    ) -> Iterator[Page]:
+        cursor: str | None = None
+        while True:
+            page_query = dict(query or {})
+            if cursor is not None:
+                page_query["cursor"] = cursor
+            page = _page_from_response(
+                self.request(
+                    operation_id,
+                    path_parameters=path_parameters,
+                    query=page_query,
+                ),
+                item_field,
+            )
+            yield page
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    def events(
+        self,
+        *,
+        path_parameters: Mapping[str, object],
+        poll_interval_seconds: float = 1.0,
+    ) -> Iterator[Mapping[str, Any]]:
+        if poll_interval_seconds < 0:
+            raise ValueError("poll_interval_seconds must not be negative")
+        after: str | None = None
+        while True:
+            events = _events_from_response(
+                self.request(
+                    self._catalog.event_operation_id,
+                    path_parameters=path_parameters,
+                    query={"after": after},
+                )
+            )
+            if not events:
+                self._sleep(poll_interval_seconds)
+            for event in events:
+                yield event
+                event_id = event.get("event_id")
+                if not isinstance(event_id, str):
+                    raise _ProtocolResponseError("event_id must be a string")
+                after = event_id
+                if _is_terminal_event(event):
+                    return
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            self._close_transport()
+
+    def __enter__(self) -> "_SyncClient":
+        self._ensure_open()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class _AsyncClient:
+    def __init__(
+        self,
+        catalog: _OperationCatalog,
+        policy: _TransportPolicy,
+        transport: _AsyncTransport,
+        *,
+        close_transport: Callable[[], Awaitable[None]],
+        sleep: Callable[[float], Awaitable[None]],
+    ) -> None:
+        self._catalog = catalog
+        self._policy = policy
+        self._transport = transport
+        self._close_transport = close_transport
+        self._sleep = sleep
+        self._closed = False
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise _ClientClosedError("client is closed")
+
+    def _resolve_fixture_request(self, method: str, path: str) -> tuple[str, Mapping[str, str]]:
+        return self._catalog.match_fixture_request(method, path)
+
+    async def request(
+        self,
+        operation_id: str,
+        *,
+        path_parameters: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+        body: object | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        self._ensure_open()
+        operation = self._catalog.operation(operation_id)
+        prepared = _prepare_request(
+            operation_id=operation.operation_id,
+            method=operation.method,
+            path=operation.bind_path(path_parameters),
+            query=query,
+            body=body,
+            idempotency_key=idempotency_key,
+            policy=self._policy,
+        )
+        return await self._transport.execute(prepared)
+
+    async def pages(
+        self,
+        operation_id: str,
+        *,
+        item_field: str,
+        path_parameters: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+    ) -> AsyncIterator[Page]:
+        cursor: str | None = None
+        while True:
+            page_query = dict(query or {})
+            if cursor is not None:
+                page_query["cursor"] = cursor
+            page = _page_from_response(
+                await self.request(
+                    operation_id,
+                    path_parameters=path_parameters,
+                    query=page_query,
+                ),
+                item_field,
+            )
+            yield page
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    async def events(
+        self,
+        *,
+        path_parameters: Mapping[str, object],
+        poll_interval_seconds: float = 1.0,
+    ) -> AsyncIterator[Mapping[str, Any]]:
+        if poll_interval_seconds < 0:
+            raise ValueError("poll_interval_seconds must not be negative")
+        after: str | None = None
+        while True:
+            events = _events_from_response(
+                await self.request(
+                    self._catalog.event_operation_id,
+                    path_parameters=path_parameters,
+                    query={"after": after},
+                )
+            )
+            if not events:
+                await self._sleep(poll_interval_seconds)
+            for event in events:
+                yield event
+                event_id = event.get("event_id")
+                if not isinstance(event_id, str):
+                    raise _ProtocolResponseError("event_id must be a string")
+                after = event_id
+                if _is_terminal_event(event):
+                    return
+
+    async def aclose(self) -> None:
+        if not self._closed:
+            self._closed = True
+            await self._close_transport()
+
+    async def __aenter__(self) -> "_AsyncClient":
+        self._ensure_open()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()

millwork_solver/_core/errors.py

@@ -0,0 +1,11 @@
+"""Private compatibility names bound to the stable public error classes."""
+
+from ..errors import (
+    ClientClosedError as _ClientClosedError,
+    NetworkError as _NetworkTransportError,
+    OperationBoundaryError as _OperationBoundaryError,
+    ProblemError as _ProblemResponseError,
+    ProtocolError as _ProtocolResponseError,
+)
+
+__all__: tuple[str, ...] = ()

millwork_solver/_core/transport.py

@@ -0,0 +1,274 @@
+"""Shared safe-transport policy with distinct sync and async HTTPX execution."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Mapping
+
+import httpx
+
+from .errors import _NetworkTransportError, _ProblemResponseError, _ProtocolResponseError
+
+
+class _RetryBoundary(Enum):
+    SAFE_READ = "safe_read"
+    SAME_KEY_MUTATION = "same_key_mutation"
+    SINGLE_ATTEMPT_MUTATION = "single_attempt_mutation"
+
+
+@dataclass(frozen=True)
+class _TransportPolicy:
+    safe_methods: frozenset[str]
+    maximum_retries: int
+    backoff_seconds: float
+
+    @classmethod
+    def from_repository(
+        cls,
+        repository_root: Path,
+        *,
+        backoff_seconds: float,
+        maximum_retries: int | None = None,
+    ) -> "_TransportPolicy":
+        fixture_path = repository_root / "contracts/developer-experience/fixtures/retry-error-idempotency.json"
+        with fixture_path.open("r", encoding="utf-8") as file:
+            fixture = json.load(file)
+        policy = fixture.get("policy", {})
+        if policy.get("safe_methods") != ["GET", "HEAD"]:
+            raise _ProtocolResponseError("F1 safe-method policy drifted")
+        if policy.get("retryable_failures") != ["network_error", "http_5xx"]:
+            raise _ProtocolResponseError("F1 retryable-failure policy drifted")
+        fixture_maximum_retries = policy.get("maximum_retries")
+        if not isinstance(fixture_maximum_retries, int) or fixture_maximum_retries < 0:
+            raise _ProtocolResponseError("F1 maximum-retries policy drifted")
+        selected_maximum_retries = (
+            fixture_maximum_retries if maximum_retries is None else maximum_retries
+        )
+        if not isinstance(selected_maximum_retries, int) or selected_maximum_retries < 0:
+            raise ValueError("maximum_retries must be a non-negative integer")
+        if backoff_seconds < 0:
+            raise ValueError("backoff_seconds must not be negative")
+        return cls(frozenset(policy["safe_methods"]), selected_maximum_retries, backoff_seconds)
+
+    @classmethod
+    def from_snapshot(
+        cls,
+        snapshot_path: Path,
+        *,
+        backoff_seconds: float,
+        maximum_retries: int | None = None,
+    ) -> "_TransportPolicy":
+        with snapshot_path.open("r", encoding="utf-8") as file:
+            snapshot = json.load(file)
+        policy = snapshot.get("retry_policy", {})
+        if policy.get("safe_methods") != ["GET", "HEAD"]:
+            raise _ProtocolResponseError("installed F1 safe-method policy drifted")
+        if policy.get("retryable_failures") != ["network_error", "http_5xx"]:
+            raise _ProtocolResponseError("installed F1 retryable-failure policy drifted")
+        default_maximum_retries = policy.get("maximum_retries")
+        if not isinstance(default_maximum_retries, int) or default_maximum_retries < 0:
+            raise _ProtocolResponseError("installed F1 maximum-retries policy drifted")
+        selected_maximum_retries = (
+            default_maximum_retries if maximum_retries is None else maximum_retries
+        )
+        if not isinstance(selected_maximum_retries, int) or selected_maximum_retries < 0:
+            raise ValueError("maximum_retries must be a non-negative integer")
+        if backoff_seconds < 0:
+            raise ValueError("backoff_seconds must not be negative")
+        return cls(frozenset(policy["safe_methods"]), selected_maximum_retries, backoff_seconds)
+
+    def classify(self, method: str, idempotency_key: str | None) -> _RetryBoundary:
+        if method in self.safe_methods:
+            return _RetryBoundary.SAFE_READ
+        if idempotency_key is not None and idempotency_key.strip():
+            return _RetryBoundary.SAME_KEY_MUTATION
+        return _RetryBoundary.SINGLE_ATTEMPT_MUTATION
+
+
+@dataclass(frozen=True)
+class _PreparedRequest:
+    operation_id: str
+    method: str
+    path: str
+    query_items: tuple[tuple[str, str], ...]
+    header_items: tuple[tuple[str, str], ...]
+    body_bytes: bytes | None
+    retry_boundary: _RetryBoundary
+
+
+def _encode_query_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        try:
+            return json.dumps(value, allow_nan=False)
+        except ValueError as error:
+            raise TypeError("query numbers must be finite JSON scalars") from error
+    raise TypeError("query values must be string, number, boolean, or None")
+
+
+def _prepare_request(
+    *,
+    operation_id: str,
+    method: str,
+    path: str,
+    query: Mapping[str, object] | None,
+    body: object | None,
+    idempotency_key: str | None,
+    policy: _TransportPolicy,
+) -> _PreparedRequest:
+    body_bytes = None
+    if body is not None:
+        body_bytes = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    headers = {"accept": "application/json"}
+    if body_bytes is not None:
+        headers["content-type"] = "application/json"
+    if idempotency_key is not None:
+        headers["idempotency-key"] = idempotency_key
+    query_items = tuple(
+        (name, _encode_query_value(value))
+        for name, value in (query or {}).items()
+        if value is not None
+    )
+    return _PreparedRequest(
+        operation_id=operation_id,
+        method=method,
+        path=path,
+        query_items=query_items,
+        header_items=tuple(headers.items()),
+        body_bytes=body_bytes,
+        retry_boundary=policy.classify(method, idempotency_key),
+    )
+
+
+def _decode_response(response: httpx.Response, method: str) -> Any:
+    if 200 <= response.status_code < 300:
+        if response.status_code == 204 or method == "HEAD":
+            return None
+        try:
+            return response.json()
+        except (json.JSONDecodeError, UnicodeDecodeError) as error:
+            raise _ProtocolResponseError("success response is not valid JSON") from error
+
+    content_type = response.headers.get("content-type", "").split(";", 1)[0].strip().lower()
+    if content_type != "application/problem+json":
+        raise _ProtocolResponseError("error response is not application/problem+json")
+    try:
+        problem = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        raise _ProtocolResponseError("Problem response is not valid JSON") from error
+    if not isinstance(problem, dict):
+        raise _ProtocolResponseError("Problem response must be an object")
+    required_types = {
+        "type": str,
+        "title": str,
+        "status": int,
+        "instance": str,
+    }
+    for field, expected_type in required_types.items():
+        if not isinstance(problem.get(field), expected_type):
+            raise _ProtocolResponseError(f"Problem field {field} has the wrong type")
+    if problem["status"] != response.status_code:
+        raise _ProtocolResponseError("Problem status differs from HTTP status")
+    if "retry_after_s" in problem and not isinstance(problem["retry_after_s"], int):
+        raise _ProtocolResponseError("Problem retry_after_s has the wrong type")
+    if "errors" in problem:
+        errors = problem["errors"]
+        if not isinstance(errors, list) or any(
+            not isinstance(item, dict)
+            or not isinstance(item.get("field"), str)
+            or not isinstance(item.get("message"), str)
+            for item in errors
+        ):
+            raise _ProtocolResponseError("Problem errors have the wrong shape")
+    raise _ProblemResponseError(problem)
+
+
+def _can_retry(prepared: _PreparedRequest, retries_used: int, policy: _TransportPolicy) -> bool:
+    return (
+        prepared.retry_boundary is not _RetryBoundary.SINGLE_ATTEMPT_MUTATION
+        and retries_used < policy.maximum_retries
+    )
+
+
+class _SyncTransport:
+    def __init__(
+        self,
+        client: httpx.Client,
+        policy: _TransportPolicy,
+        sleep: Callable[[float], None],
+    ) -> None:
+        self._client = client
+        self._policy = policy
+        self._sleep = sleep
+
+    def execute(self, prepared: _PreparedRequest) -> Any:
+        retries_used = 0
+        while True:
+            try:
+                response = self._client.request(
+                    prepared.method,
+                    prepared.path,
+                    params=prepared.query_items,
+                    headers=dict(prepared.header_items),
+                    content=prepared.body_bytes,
+                )
+            except httpx.TransportError as error:
+                if _can_retry(prepared, retries_used, self._policy):
+                    self._sleep(self._policy.backoff_seconds * (2 ** retries_used))
+                    retries_used += 1
+                    continue
+                raise _NetworkTransportError(
+                    f"{prepared.operation_id} failed after {retries_used + 1} attempt(s)",
+                    cause=error,
+                ) from error
+            if response.status_code >= 500 and _can_retry(prepared, retries_used, self._policy):
+                self._sleep(self._policy.backoff_seconds * (2 ** retries_used))
+                retries_used += 1
+                continue
+            return _decode_response(response, prepared.method)
+
+
+class _AsyncTransport:
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        policy: _TransportPolicy,
+        sleep: Callable[[float], Awaitable[None]],
+    ) -> None:
+        self._client = client
+        self._policy = policy
+        self._sleep = sleep
+
+    async def execute(self, prepared: _PreparedRequest) -> Any:
+        retries_used = 0
+        while True:
+            try:
+                response = await self._client.request(
+                    prepared.method,
+                    prepared.path,
+                    params=prepared.query_items,
+                    headers=dict(prepared.header_items),
+                    content=prepared.body_bytes,
+                )
+            except httpx.TransportError as error:
+                if _can_retry(prepared, retries_used, self._policy):
+                    await self._sleep(self._policy.backoff_seconds * (2 ** retries_used))
+                    retries_used += 1
+                    continue
+                raise _NetworkTransportError(
+                    f"{prepared.operation_id} failed after {retries_used + 1} attempt(s)",
+                    cause=error,
+                ) from error
+            if response.status_code >= 500 and _can_retry(prepared, retries_used, self._policy):
+                await self._sleep(self._policy.backoff_seconds * (2 ** retries_used))
+                retries_used += 1
+                continue
+            return _decode_response(response, prepared.method)