pyfect-dev 0.1.0__py3-none-any.whl

pyfect/graphql/client_error.py

@@ -0,0 +1,285 @@
+"""The errors of a GraphQL client (Effect's ``GraphQLClientError``).
+
+Every client method fails with a ``GraphQLClientError``: the ``operation``
+that failed and a ``reason`` saying why. ``ResponseError`` is a response
+with GraphQL ``errors``; ``TransportError`` a response that never came or
+was not GraphQL; ``EncodeError`` / ``DecodeError`` variables or data that
+did not match their schemas; ``PaginationError`` cursor paging that could
+not go on. ``is_retryable`` and ``retry_after`` read the reason.
+
+Each error is a schema class, so errors round-trip through
+``S.encode_sync`` / ``S.decode_unknown_sync``; headers encode as a plain
+string record and ``retryAfter`` as milliseconds.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping, Sequence
+from typing import NotRequired
+
+from typing_extensions import TypedDict
+
+from pyfect import schema as S
+from pyfect.duration import Seconds
+from pyfect.graphql._schemas import HEADERS, SECONDS_FROM_MILLIS
+from pyfect.http import error as http_error
+from pyfect.http.headers import Headers, parse_retry_after, retry_after_delay
+from pyfect.result import Ok
+from pyfect.schema._undefined import Undefined
+
+
+class Location(TypedDict):
+    """Where in the document an error happened."""
+
+    line: float
+    column: float
+
+
+class GraphQLError(TypedDict, extra_items=S.JsonValue):
+    """One entry of a response's ``errors``, as the GraphQL specification
+    describes it. ``path[0]`` is the response key (the alias, when the
+    document used one). Other top-level keys, such as GitHub's ``type``,
+    are kept as JSON values."""
+
+    message: str
+    locations: NotRequired[Sequence[Location]]
+    path: NotRequired[Sequence[str | float]]
+    extensions: NotRequired[Mapping[str, S.JsonValue]]
+
+
+GRAPHQL_ERROR = S.Struct(
+    GraphQLError,
+    locations=S.Array(S.Struct(Location)),
+    path=S.Array(S.Union(S.String, S.Number)),
+)
+"""The schema of a ``GraphQLError``."""
+
+_JSON_OBJECT = S.Record(S.String, S.Json)
+
+_RETRYABLE_STANDARD_CLOSE_CODES = frozenset({1000, 1001, 1005, 1006, 1012, 1013, 1014})
+_FATAL_GRAPHQL_WS_CLOSE_CODES = frozenset({4400, 4401, 4403, 4406, 4409, 4429, 4500})
+
+
+def is_fatal_close_code(code: int) -> bool:
+    """A WebSocket close code that retrying cannot fix: every standard
+    ``1xxx`` code but 1000, 1001, 1005, 1006, 1012, 1013 and 1014, and the
+    graphql-ws codes 4400, 4401, 4403, 4406, 4409, 4429 and 4500."""
+    if 1000 <= code < 2000:
+        return code not in _RETRYABLE_STANDARD_CLOSE_CODES
+    return code in _FATAL_GRAPHQL_WS_CLOSE_CODES
+
+
+def _is_retryable_status(status: int) -> bool:
+    return status == 429 or 500 <= status < 600
+
+
+def parse_retry_after_header(value: str | None, now_millis: float) -> Seconds | None:
+    """A ``Retry-After`` value (whole seconds or an HTTP date) as a delay
+    from ``now_millis``; anything else is ``None``."""
+    if value is None:
+        return None
+    parsed = parse_retry_after(value)
+    return retry_after_delay(parsed.value, now_millis) if isinstance(parsed, Ok) else None
+
+
+class ResponseError(S.TaggedError, identifier="effect/graphql/GraphQLClientError/ResponseError"):
+    """The server answered with GraphQL ``errors`` (a query or mutation
+    fails on any, even with partial ``data``, which is kept raw here).
+    ``status`` and ``headers`` are what the transport reported.
+    ``retry_after`` reads the ``Retry-After`` header when the error is
+    made; ``is_retryable`` holds for status 429 or 5xx, or any valid
+    ``Retry-After``."""
+
+    errors: tuple[GraphQLError, ...] = S.field(S.NonEmptyArray(GRAPHQL_ERROR))
+    data: S.JsonValue = S.field(S.Union(S.Json, Undefined), default=None)
+    extensions: Mapping[str, S.JsonValue] | None = S.field(
+        S.Union(_JSON_OBJECT, Undefined), default=None
+    )
+    status: int | None = S.field(S.Union(S.Int, Undefined), default=None)
+    headers: Headers | None = S.field(S.Union(HEADERS, Undefined), default=None)
+
+    def __post_init__(self) -> None:
+        header = None if self.headers is None else self.headers.get("retry-after")
+        object.__setattr__(
+            self, "_retry_after", parse_retry_after_header(header, time.time_ns() // 1_000_000)
+        )
+
+    @property
+    def retry_after(self) -> Seconds | None:
+        retry_after: Seconds | None = self.__dict__["_retry_after"]
+        return retry_after
+
+    @property
+    def is_retryable(self) -> bool:
+        if self.retry_after is not None:
+            return True
+        return self.status is not None and _is_retryable_status(self.status)
+
+    @property
+    def message(self) -> str:
+        return "; ".join(error["message"] for error in self.errors)
+
+
+class TransportError(S.TaggedError, identifier="effect/graphql/GraphQLClientError/TransportError"):
+    """No GraphQL response came: a network failure, an HTTP response that
+    is not GraphQL (``status`` and ``headers`` set), or a closed WebSocket
+    (``close_code``). ``fatal`` marks a failure retrying cannot fix;
+    ``cause`` is the original error."""
+
+    description: str
+    status: int | None = S.field(S.Union(S.Int, Undefined), default=None)
+    headers: Headers | None = S.field(S.Union(HEADERS, Undefined), default=None)
+    retry_after: Seconds | None = S.field(
+        S.Union(SECONDS_FROM_MILLIS, Undefined), default=None, key="retryAfter"
+    )
+    close_code: int | None = S.field(S.Union(S.Int, Undefined), default=None, key="closeCode")
+    fatal: bool | None = S.field(S.Union(S.Boolean, Undefined), default=None)
+    cause: object = S.field(S.Union(S.Defect(), Undefined), default=None)
+
+    def __post_init__(self) -> None:
+        self.__cause__ = self.cause if isinstance(self.cause, BaseException) else None
+
+    @property
+    def is_retryable(self) -> bool:
+        """A network failure, status 429 or 5xx, a ``retry_after``, or a
+        close code that is not fatal; never when ``fatal``."""
+        if self.fatal:
+            return False
+        if self.close_code is not None and is_fatal_close_code(self.close_code):
+            return False
+        if self.retry_after is not None:
+            return True
+        return self.status is None or _is_retryable_status(self.status)
+
+    @property
+    def message(self) -> str:
+        return self.description
+
+    @staticmethod
+    def from_http_client_error(
+        error: http_error.HttpClientError, *, now_millis: float | None = None
+    ) -> TransportError:
+        """``error`` with the response's ``status``, ``headers`` and
+        ``Retry-After`` (an HTTP date measured from ``now_millis``, by
+        default the wall clock)."""
+        response = error.response
+        headers = None if response is None else response.headers
+        now = time.time_ns() // 1_000_000 if now_millis is None else now_millis
+        return TransportError(
+            description=error.message,
+            status=None if response is None else response.status,
+            headers=headers,
+            retry_after=parse_retry_after_header(
+                None if headers is None else headers.get("retry-after"), now
+            ),
+            cause=error,
+        )
+
+
+class EncodeError(S.TaggedError, identifier="effect/graphql/GraphQLClientError/EncodeError"):
+    """The variables schema rejected the input; nothing was sent."""
+
+    description: str
+
+    @property
+    def is_retryable(self) -> bool:
+        return False
+
+    @property
+    def message(self) -> str:
+        return self.description
+
+
+class DecodeError(S.TaggedError, identifier="effect/graphql/GraphQLClientError/DecodeError"):
+    """The response was not GraphQL, or its ``data`` did not match the
+    result schema (``data: null`` without ``errors`` included)."""
+
+    description: str
+
+    @property
+    def is_retryable(self) -> bool:
+        return False
+
+    @property
+    def message(self) -> str:
+        return self.description
+
+
+class PaginationError(
+    S.TaggedError, identifier="effect/graphql/GraphQLClientError/PaginationError"
+):
+    """``pages`` / ``items`` could not go on: the connection was ``null``
+    after the first page, or ``hasNextPage`` was true with a ``null`` or
+    unchanged ``endCursor``. ``cursor`` is the last one sent."""
+
+    description: str
+    cursor: str | None
+
+    @property
+    def is_retryable(self) -> bool:
+        return False
+
+    @property
+    def message(self) -> str:
+        return self.description
+
+
+type Reason = ResponseError | TransportError | EncodeError | DecodeError | PaginationError
+
+REASON = S.Union(ResponseError, TransportError, EncodeError, DecodeError, PaginationError)
+"""The schema of every reason."""
+
+
+class GraphQLClientError(S.TaggedError, identifier="~effect/graphql/GraphQLClientError"):
+    """What every client method fails with: the ``operation`` and the
+    ``reason`` (also its ``__cause__``)."""
+
+    operation: str
+    reason: Reason = S.field(REASON)
+
+    def __post_init__(self) -> None:
+        self.__cause__ = self.reason
+
+    @property
+    def is_retryable(self) -> bool:
+        return self.reason.is_retryable
+
+    @property
+    def retry_after(self) -> Seconds | None:
+        """The ``Retry-After`` hint of a response or transport reason."""
+        reason = self.reason
+        if isinstance(reason, ResponseError | TransportError):
+            return reason.retry_after
+        return None
+
+    @property
+    def status(self) -> int | None:
+        reason = self.reason
+        return reason.status if isinstance(reason, ResponseError | TransportError) else None
+
+    @property
+    def headers(self) -> Headers | None:
+        reason = self.reason
+        return reason.headers if isinstance(reason, ResponseError | TransportError) else None
+
+    @property
+    def message(self) -> str:
+        return f"{self.operation}: {type(self.reason).__name__}: {self.reason.message}"
+
+
+__all__ = [
+    "GRAPHQL_ERROR",
+    "REASON",
+    "DecodeError",
+    "EncodeError",
+    "GraphQLClientError",
+    "GraphQLError",
+    "Location",
+    "PaginationError",
+    "Reason",
+    "ResponseError",
+    "TransportError",
+    "is_fatal_close_code",
+    "parse_retry_after_header",
+]

pyfect/graphql/group.py

@@ -0,0 +1,142 @@
+"""Groups of GraphQL operations (Effect's ``GraphQLGroup``).
+
+A group is a class whose attributes are operations; ``client.make(Group)``
+gives an instance whose attributes are their methods. The type argument
+names the middleware every operation of the group runs, outermost first::
+
+    class Issues(GraphQLGroup[Auth | Logging]):
+        repo_issues = RepoIssues
+        issue_updated = IssueUpdated
+
+Read on the class, an operation carries the group's middleware, so another
+group takes it with it (Effect's ``GraphQLGroup.merge``)::
+
+    class Everything(GraphQLGroup):
+        repo_issues = Issues.repo_issues
+        viewer = Viewer
+"""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping
+from typing import Any, Generic, Never, Self, TypeVar, Union, cast, get_args, get_origin
+
+from pyfect.graphql.middleware import AnyMiddleware, GraphQLMiddleware
+from pyfect.graphql.operation import AnyOperation, Operation, OperationInfo, Subscription
+
+GM_co = TypeVar("GM_co", covariant=True, default=Never)
+OM_co = TypeVar("OM_co", covariant=True, default=Never)
+G_co = TypeVar("G_co", covariant=True)
+GT_co = TypeVar("GT_co", covariant=True)
+OT_co = TypeVar("OT_co", covariant=True)
+
+
+class GroupTypes(Generic[G_co, GT_co, OT_co]):
+    """The client type and the middleware tags of a group (run by every
+    operation, by some), for ``make``. Kept apart: a union of two class
+    TypeVars that are both ``Never`` is ``Unknown``."""
+
+
+class GraphQLGroup(Generic[GM_co, OM_co]):
+    """A group of operations; subclass it with the operations as class
+    attributes. Clients are made by ``client.make`` and
+    ``client.make_test``, not by calling the class.
+
+    ``GM`` is the middleware every operation runs; ``OM`` the middleware
+    some operations run (``op.middleware(M)``, or an operation taken from a
+    group with middleware), which ``make`` needs too. Pyright cannot gather
+    it from the class attributes, so it is declared, and a group whose
+    operations run middleware it does not declare is a ``TypeError``."""
+
+    __slots__ = ("_methods",)
+
+    def __init__(self, methods: Mapping[AnyOperation, object]) -> None:
+        self._methods = dict(methods)
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        declared = {*group_middlewares(cls), *operation_middlewares(cls)}
+        undeclared: dict[AnyMiddleware, None] = {}
+        for operation in operations_of(cls):
+            for middleware in operation.middlewares:
+                if middleware not in declared:
+                    undeclared[middleware] = None
+        if undeclared:
+            names = " | ".join(m.__qualname__ for m in undeclared)
+            raise TypeError(
+                f"{cls.__qualname__}'s operations run middleware it does not declare: {names}. "
+                f"Declare it as the second type argument (class {cls.__qualname__}"
+                f"(GraphQLGroup[..., {names}])) so that make() requires it"
+            )
+
+    @classmethod
+    def __graphql_group__(cls) -> GroupTypes[Self, GM_co, OM_co]:
+        return GroupTypes()
+
+
+def _group_arguments(owner: type) -> tuple[object, ...]:
+    """The type arguments of the ``GraphQLGroup[...]`` base nearest
+    ``owner`` in its MRO; none for a bare ``GraphQLGroup``."""
+    for cls in owner.__mro__:
+        for base in getattr(cls, "__orig_bases__", ()):
+            if get_origin(base) is GraphQLGroup:
+                return get_args(base)
+    return ()
+
+
+def group_middlewares(owner: type) -> tuple[AnyMiddleware, ...]:
+    """The middleware classes of ``class G(GraphQLGroup[M])`` (or of a
+    subclass of it), outermost first; none for any other class."""
+    arguments = _group_arguments(owner)
+    return _middleware_classes(arguments[0]) if arguments else ()
+
+
+def operation_middlewares(owner: type) -> tuple[AnyMiddleware, ...]:
+    """The middleware classes declared as ``GraphQLGroup[M, OM]``'s ``OM``."""
+    arguments = _group_arguments(owner)
+    return _middleware_classes(arguments[1]) if len(arguments) > 1 else ()
+
+
+def _middleware_classes(argument: object) -> tuple[AnyMiddleware, ...]:
+    if argument is Never:
+        return ()
+    if get_origin(argument) in (Union, types.UnionType):
+        return tuple(m for arg in get_args(argument) for m in _middleware_classes(arg))
+    if isinstance(argument, type) and issubclass(argument, GraphQLMiddleware):
+        return (cast("AnyMiddleware", argument),)
+    raise TypeError(f"GraphQLGroup[...] takes middleware classes, got {argument!r}")
+
+
+def operations_of(group: type[GraphQLGroup[Any, Any]]) -> list[AnyOperation]:
+    """The operations of ``group``'s attributes, each once; an attribute a
+    subclass overrides holds the subclass's operation. Raises
+    ``ValueError`` for two operations with one name."""
+    attributes: dict[str, object] = {}
+    for cls in reversed(group.__mro__):
+        attributes.update(vars(cls))
+    by_name: dict[str, AnyOperation] = {}
+    for value in attributes.values():
+        if not isinstance(value, Operation | Subscription):
+            continue
+        operation: AnyOperation = cast("OperationInfo", value)
+        existing = by_name.get(operation.name)
+        if existing is not None and existing is not operation:
+            raise ValueError(f'GraphQLGroup: duplicate operation name "{operation.name}"')
+        by_name[operation.name] = operation
+    return list(by_name.values())
+
+
+def method_of(instance: object, operation: AnyOperation) -> object:
+    """The method of ``operation`` on a client."""
+    return cast("GraphQLGroup[Any, Any]", instance)._methods[operation]  # pyright: ignore[reportPrivateUsage]
+
+
+__all__ = [
+    "GraphQLGroup",
+    "GroupTypes",
+    "group_middlewares",
+    "method_of",
+    "operation_middlewares",
+    "operations_of",
+]

pyfect/graphql/middleware.py

@@ -0,0 +1,98 @@
+"""Client middleware for GraphQL operations (Effect's ``GraphQLMiddleware``).
+
+A middleware is a tag class whose service is an ``Implementation``: it
+gets each request with ``next`` (the rest of the chain) and may change the
+request, the result, or fail with its own error ``E`` while needing ``R``::
+
+    class Auth(GraphQLMiddleware[TokenExpired, CurrentUser]): ...
+
+    AuthLive = layer.succeed(Auth, map_request(add_token))
+
+Attach it to an operation with ``op.middleware(Auth)`` (and declare it on
+the group, ``class Api(GraphQLGroup[Never, Auth])``, so ``make`` requires
+it) or to every operation of a group with ``class Api(GraphQLGroup[Auth]):
+...``. Group middleware runs outside operation middleware; within a level,
+in attach order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, Never, TypeVar
+
+from pyfect.context import Tag
+from pyfect.effect import Effect
+from pyfect.graphql._types import ExecutionResult, GraphQLRequest
+from pyfect.graphql.client_error import GraphQLClientError
+from pyfect.stream import Stream, from_effect
+
+if TYPE_CHECKING:
+    from pyfect.graphql.operation import AnyOperation
+
+E_co = TypeVar("E_co", covariant=True, default=Never)
+R_co = TypeVar("R_co", covariant=True, default=Never)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExecuteOptions:
+    """What a middleware's ``execute`` gets. ``next`` fails with
+    ``GraphQLClientError`` and, at runtime, with the errors of the
+    middleware further in (Effect's ``Types.unhandled``)."""
+
+    operation: AnyOperation
+    request: GraphQLRequest
+    next: Callable[[GraphQLRequest], Effect[ExecutionResult, GraphQLClientError]]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SubscribeOptions:
+    """What a middleware's ``subscribe`` gets."""
+
+    operation: AnyOperation
+    request: GraphQLRequest
+    next: Callable[[GraphQLRequest], Stream[ExecutionResult, GraphQLClientError]]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Implementation(Generic[E_co, R_co]):
+    """A middleware's service: one function around queries and mutations,
+    one around subscriptions."""
+
+    execute: Callable[[ExecuteOptions], Effect[ExecutionResult, GraphQLClientError | E_co, R_co]]
+    subscribe: Callable[
+        [SubscribeOptions], Stream[ExecutionResult, GraphQLClientError | E_co, R_co]
+    ]
+
+
+class GraphQLMiddleware(Tag[Implementation[E_co, R_co]], Generic[E_co, R_co], base=True):
+    """A middleware tag failing with ``E`` and needing ``R``. Subclass it
+    once per middleware."""
+
+
+type AnyMiddleware = type[GraphQLMiddleware[Any, Any]]
+
+
+def map_request[E = Never, R = Never](
+    f: Callable[[GraphQLRequest, AnyOperation], Effect[GraphQLRequest, E, R]],
+) -> Implementation[E, R]:
+    """A middleware that only changes the request, for every kind of
+    operation."""
+
+    def execute(options: ExecuteOptions) -> Effect[ExecutionResult, GraphQLClientError | E, R]:
+        return f(options.request, options.operation).flat_map(options.next)
+
+    def subscribe(options: SubscribeOptions) -> Stream[ExecutionResult, GraphQLClientError | E, R]:
+        return from_effect(f(options.request, options.operation)).flat_map(options.next)
+
+    return Implementation(execute=execute, subscribe=subscribe)
+
+
+__all__ = [
+    "AnyMiddleware",
+    "ExecuteOptions",
+    "GraphQLMiddleware",
+    "Implementation",
+    "SubscribeOptions",
+    "map_request",
+]