pyfect-dev 0.1.0__py3-none-any.whl

pyfect/graphql/_http.py

@@ -0,0 +1,309 @@
+"""GraphQL over HTTP (Effect's ``GraphQLProtocol.makeHttp``): queries and
+mutations POSTed as JSON (or queries as GET URL params), subscriptions over
+graphql-sse in distinct connections mode."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, Never, cast
+
+from pyfect import _json_text, stream
+from pyfect import effect as fx
+from pyfect.clock import ClockService, clock_with, now_millis_unsafe
+from pyfect.context import Context
+from pyfect.duration import Seconds, to_seconds
+from pyfect.effect import Effect
+from pyfect.encoding import sse
+from pyfect.graphql._types import (
+    Answer,
+    BatchUrl,
+    ForcePost,
+    GraphQLProtocolService,
+    GraphQLRequest,
+    Kind,
+    ResolvedUrl,
+    request_body,
+)
+from pyfect.graphql.client_error import TransportError
+from pyfect.http import error as http_error
+from pyfect.http import request as http_request
+from pyfect.http import url_params as _url_params
+from pyfect.http.client import HttpClient
+from pyfect.http.headers import Headers
+from pyfect.http.request import HttpClientRequest
+from pyfect.http.response import HttpClientResponse, filter_status_ok
+from pyfect.stream import Stream
+
+_GRAPHQL_RESPONSE = "application/graphql-response+json"
+_JSON = "application/json"
+_EVENT_STREAM = "text/event-stream"
+_GET_PARAMS = frozenset({"query", "operationName", "variables", "extensions"})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UrlOptions:
+    """What a URL function gets: the caller's services and the operation."""
+
+    context: Context[Never]
+    kind: Kind
+    operation_name: str
+
+
+type Url = str | Effect[str] | Callable[[UrlOptions], str]
+"""An endpoint: fixed, resolved by an effect in each call's context, or
+chosen per call from the caller's services and the operation."""
+
+type QueryMethod = Literal["GET", "POST"]
+
+
+def url_resolver(url: Url) -> Callable[[Kind, str], Effect[str]]:
+    """``url`` as a function of the operation, run in the caller's context."""
+    if isinstance(url, str):
+        fixed: Effect[str] = fx.succeed(url)
+        return lambda _kind, _name: fixed
+    if isinstance(url, Effect):
+        resolved = cast("Effect[str]", url)
+        return lambda _kind, _name: resolved
+    choose = url
+
+    def chosen(kind: Kind, name: str) -> Effect[str]:
+        options: Effect[Context[Never]] = fx.context()
+        return options.map(
+            lambda context: choose(UrlOptions(context=context, kind=kind, operation_name=name))
+        )
+
+    return chosen
+
+
+def _is_object(value: object) -> bool:
+    return isinstance(value, Mapping)
+
+
+def _is_graphql_body(body: object) -> bool:
+    if not isinstance(body, Mapping):
+        return False
+    fields = cast("Mapping[str, object]", body)
+    if "data" not in fields and "errors" not in fields:
+        return False
+    if "errors" in fields and not isinstance(fields["errors"], list):
+        return False
+    return "data" not in fields or fields["data"] is None or _is_object(fields["data"])
+
+
+def _post(url: str, request: GraphQLRequest, accept: str) -> HttpClientRequest:
+    return (
+        http_request.post(url)
+        .set_headers(request.headers)
+        .set_header("accept", accept)
+        .append_url_params(request.url_params)
+        .body_json_unsafe(request_body(request))
+    )
+
+
+def _get(url: str, request: GraphQLRequest, accept: str) -> HttpClientRequest:
+    base, hash_mark, fragment = url.partition("#")
+    path, _, query = base.partition("?")
+    kept = [
+        (key, value)
+        for key, value in (*_url_params.parse(query).params, *request.url_params.params)
+        if key not in _GET_PARAMS
+    ]
+    params: dict[str, str] = {"query": request.query, "operationName": request.operation_name}
+    if request.variables is not None:
+        params["variables"] = _json_text.js_stringify(request.variables)
+    if request.extensions is not None:
+        params["extensions"] = _json_text.js_stringify(request.extensions)
+    return (
+        http_request.get(path + hash_mark + fragment)
+        .set_headers(request.headers)
+        .set_header("accept", accept)
+        .append_url_params(kept)
+        .set_url_params(params)
+    )
+
+
+def _content_type(response: HttpClientResponse) -> str:
+    return response.headers.get("content-type", "").lower()
+
+
+def _read_body(
+    response: HttpClientResponse,
+) -> Effect[object, TransportError | http_error.HttpClientError]:
+    content_type = _content_type(response)
+    if _GRAPHQL_RESPONSE in content_type:
+        return response.json
+    if _JSON in content_type:
+
+        def checked(body: object) -> Effect[object, http_error.HttpClientError]:
+            if _is_graphql_body(body):
+                return fx.succeed(body)
+            return filter_status_ok(response).as_(body)
+
+        return response.json.flat_map(checked)
+    received = "no Content-Type" if content_type == "" else f"Content-Type {content_type}"
+    not_graphql = TransportError(
+        description=f"Expected a GraphQL response, received {received}",
+        status=response.status,
+        headers=response.headers,
+    )
+    return filter_status_ok(response).flat_map(lambda _: fx.fail(not_graphql))
+
+
+def _read_answer(
+    response: HttpClientResponse,
+) -> Effect[Answer, TransportError | http_error.HttpClientError]:
+    return _read_body(response).map(
+        lambda body: Answer(body=body, status=response.status, headers=response.headers)
+    )
+
+
+def _transport_error(clock: ClockService) -> Callable[[object], TransportError]:
+    def convert(error: object) -> TransportError:
+        if isinstance(error, http_error.HttpClientError):
+            return TransportError.from_http_client_error(error, now_millis=now_millis_unsafe(clock))
+        return cast("TransportError", error)
+
+    return convert
+
+
+def _sse_answers(response: HttpClientResponse) -> Stream[Answer, TransportError]:
+    """The ``next`` events of a graphql-sse body until ``complete``; a body
+    ending without one fails, with the last ``retry:`` as ``retry_after``."""
+
+    def build() -> Stream[Answer, TransportError]:
+        headers: Headers = response.headers
+        state: dict[str, Any] = {"retry_after": None, "complete": False}
+        pending: list[sse.Event] = []
+
+        def on_parse(event: sse.AnyEvent) -> None:
+            if isinstance(event, sse.Retry):
+                state["retry_after"] = to_seconds(event.duration)
+            else:
+                pending.append(event)
+
+        parser = sse.make_parser(on_parse, dispatch_empty_named_events=True)
+
+        def feed(text: str) -> Effect[list[sse.Event], TransportError]:
+            error = parser.feed(text)
+            if error is not None:
+                return fx.fail(TransportError(description=error.message, cause=error))
+            batch = list(pending)
+            pending.clear()
+            return fx.succeed(batch)
+
+        def until_complete(event: sse.Event) -> bool:
+            if event.event == "complete":
+                state["complete"] = True
+            return not state["complete"]
+
+        def answer(event: sse.Event) -> Effect[Answer, TransportError]:
+            try:
+                body: object = _json_text.parse(event.data)
+            except ValueError as cause:
+                return fx.fail(
+                    TransportError(
+                        description=f"Invalid graphql-sse next event: {cause}", cause=cause
+                    )
+                )
+            return fx.succeed(Answer(body=body, headers=headers))
+
+        def stream_failed(cause: http_error.HttpClientError) -> TransportError:
+            retry_after: Seconds | None = state["retry_after"]
+            return TransportError(
+                description=f"The graphql-sse stream failed: {cause.message}",
+                retry_after=retry_after,
+                cause=cause,
+            )
+
+        def ended() -> Stream[Never, TransportError]:
+            if state["complete"]:
+                return stream.make()
+            retry_after: Seconds | None = state["retry_after"]
+            return stream.fail(
+                TransportError(
+                    description="The graphql-sse stream ended without a complete event",
+                    retry_after=retry_after,
+                )
+            )
+
+        events: Stream[sse.Event, TransportError] = (
+            response.stream.decode_text()
+            .map_error(stream_failed)
+            .map_effect(feed)
+            .flatten_iterable()
+        )
+        return (
+            events.take_while(until_complete)
+            .filter(lambda event: event.event == "next")
+            .map_effect(answer)
+            .concat(stream.suspend(ended))
+        )
+
+    return stream.suspend(build)
+
+
+def make_http_sse(
+    *, url: Url, query_method: QueryMethod = "POST"
+) -> Effect[GraphQLProtocolService, Never, HttpClient]:
+    """A transport POSTing queries and mutations as JSON to ``url``
+    (queries as GET URL params with ``query_method="GET"``, unless a
+    resolver batch forces POST), and running subscriptions over
+    graphql-sse. A non-GraphQL response is a ``TransportError`` with its
+    status, headers and ``Retry-After``."""
+    resolve = url_resolver(url)
+    accept = f"{_GRAPHQL_RESPONSE}, {_JSON}"
+
+    def url_of(request: GraphQLRequest) -> Effect[str]:
+        # A resolver batch carries the URL it was grouped by.
+        def chosen(batch: BatchUrl | None) -> Effect[str]:
+            if batch is not None and batch.resolve is resolve:
+                return fx.succeed(batch.url)
+            return resolve(request.kind, request.operation_name)
+
+        return ResolvedUrl().flat_map(chosen)
+
+    def build(clock: ClockService) -> Effect[GraphQLProtocolService, Never, HttpClient]:
+        convert = _transport_error(clock)
+
+        def with_client(client: Any) -> GraphQLProtocolService:
+            def execute(request: GraphQLRequest) -> Effect[Answer, TransportError]:
+                def send(force_post: bool, endpoint: str) -> Effect[Answer, TransportError]:
+                    by_get = query_method == "GET" and request.kind == "query" and not force_post
+                    to_request = _get if by_get else _post
+                    answer: Effect[Answer, Any] = client.execute(
+                        to_request(endpoint, request, accept)
+                    ).flat_map(_read_answer)
+                    return answer.map_error(convert)
+
+                return ForcePost().flat_map(
+                    lambda force_post: url_of(request).flat_map(
+                        lambda endpoint: send(force_post, endpoint)
+                    )
+                )
+
+            def subscribe(request: GraphQLRequest) -> Stream[Answer, TransportError]:
+                def opened(
+                    response: HttpClientResponse,
+                ) -> Effect[Stream[Answer, TransportError], Any]:
+                    is_ok = 200 <= response.status < 300
+                    if _EVENT_STREAM in _content_type(response) and is_ok:
+                        return fx.succeed(_sse_answers(response))
+                    return _read_answer(response).map(stream.succeed)
+
+                def send(endpoint: str) -> Effect[Stream[Answer, TransportError], TransportError]:
+                    opening: Effect[Stream[Answer, TransportError], Any] = client.execute(
+                        _post(endpoint, request, _EVENT_STREAM)
+                    ).flat_map(opened)
+                    return opening.map_error(convert)
+
+                answers: Stream[Stream[Answer, TransportError], TransportError] = (
+                    stream.from_effect(url_of(request).flat_map(send))
+                )
+                return answers.flat_map(lambda inner: inner)
+
+            return GraphQLProtocolService(execute=execute, subscribe=subscribe, url=resolve)
+
+        return HttpClient().map(with_client)
+
+    return clock_with(build)

pyfect/graphql/_schemas.py

@@ -0,0 +1,39 @@
+"""Schemas the GraphQL errors and results share: ``HEADERS`` (a string
+record decoded into ``Headers``) and ``SECONDS_FROM_MILLIS`` (Effect's
+``Schema.DurationFromMillis`` over ``Seconds``)."""
+
+from __future__ import annotations
+
+from typing import TypeIs
+
+from pyfect import schema as S
+from pyfect.duration import Seconds, to_millis
+from pyfect.http.headers import Headers, from_input
+from pyfect.schema import transformation as T
+
+
+def _is_seconds(value: object) -> TypeIs[Seconds]:
+    return isinstance(value, Seconds)
+
+
+def _is_headers(value: object) -> TypeIs[Headers]:
+    return isinstance(value, Headers)
+
+
+def _plain(headers: Headers) -> dict[str, str]:
+    return dict(headers)
+
+
+SECONDS_FROM_MILLIS = S.Finite.pipe(
+    S.decode_to(
+        S.declare(_is_seconds, expected="Seconds"),
+        T.transform(decode=lambda millis: Seconds(millis / 1000), encode=to_millis),
+    )
+)
+
+HEADERS = S.Record(S.String, S.String).pipe(
+    S.decode_to(
+        S.declare(_is_headers, expected="Headers"),
+        T.transform(decode=from_input, encode=_plain),
+    )
+)

pyfect/graphql/_slices.py

@@ -0,0 +1,110 @@
+"""Reading a batched response back into one result per slice, and the
+helpers resolvers use to compare keys and walk results."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any, cast
+
+from pyfect import _json_text
+from pyfect.graphql._types import ExecutionResult
+from pyfect.graphql.client_error import GraphQLError
+from pyfect.graphql.template import DocumentTemplate
+
+
+def canonical_json(value: object) -> str:
+    """JSON with object keys sorted, so equal JSON values give equal
+    strings."""
+    return _json_text.stringify(value, sort_keys=True, default=str)
+
+
+def frozen(value: object) -> Hashable:
+    """``value`` as a hashable stand-in that is equal for equal values:
+    mappings and sequences compare by content."""
+    if isinstance(value, Mapping):
+        items = cast("Mapping[object, object]", value).items()
+        return ("mapping", frozenset((frozen(k), frozen(v)) for k, v in items))
+    if isinstance(value, list | tuple):
+        return ("sequence", tuple(frozen(item) for item in cast("Sequence[object]", value)))
+    if isinstance(value, set | frozenset):
+        return ("set", frozenset(frozen(item) for item in cast("set[object]", value)))
+    return cast("Hashable", value)
+
+
+def split_slices(
+    result: ExecutionResult, template: DocumentTemplate, prefixes: Sequence[str]
+) -> list[ExecutionResult] | None:
+    """The batched ``result`` split per prefix, with the prefix removed
+    from root keys and error paths. ``None`` if an error matches no slice
+    or the data is null or missing."""
+    slice_errors: list[list[GraphQLError]] = [[] for _ in prefixes]
+    for error in result.errors:
+        path = error.get("path")
+        key = path[0] if path else None
+        # No prefix is a prefix of another, so at most one matches.
+        index = (
+            next((i for i, prefix in enumerate(prefixes) if key.startswith(prefix)), None)
+            if isinstance(key, str)
+            else None
+        )
+        if index is None or path is None or not isinstance(key, str):
+            return None
+        unprefixed: Any = {**error, "path": [key[len(prefixes[index]) :], *path[1:]]}
+        slice_errors[index].append(unprefixed)
+    data = result.data
+    if not isinstance(data, Mapping):
+        return None
+    data = cast("Mapping[str, object]", data)
+    sliced: list[ExecutionResult] = []
+    for prefix, errors in zip(prefixes, slice_errors, strict=True):
+        slice_data: dict[str, object] = {}
+        for selection in template.selections:
+            key = cast("str", selection.alias or selection.name)
+            if prefix + key in data:
+                slice_data[key] = data[prefix + key]
+        sliced.append(replace(result, data=slice_data, errors=tuple(errors)))
+    return sliced
+
+
+@dataclass(frozen=True, slots=True)
+class FoundList:
+    """The list at a resolver's path, and whether its parent's
+    ``pageInfo.hasNextPage`` says there are more."""
+
+    items: Sequence[object]
+    truncated: bool
+
+
+def _field(value: object, name: str) -> object:
+    return cast("Mapping[str, object]", value).get(name) if isinstance(value, Mapping) else None
+
+
+def find_list(data: object, path: Sequence[str]) -> FoundList | None:
+    """The list at ``path`` in ``data``, or ``None`` when a field on the
+    way is null or missing."""
+    parent = data
+    for name in path[:-1]:
+        parent = _field(parent, name)
+    items = _field(parent, path[-1])
+    if not isinstance(items, list | tuple):
+        return None
+    page_info = _field(parent, "pageInfo")
+    return FoundList(
+        items=cast("Sequence[object]", items),
+        truncated=_field(page_info, "hasNextPage") is True,
+    )
+
+
+def entry_index(error: GraphQLError, path: Sequence[str], length: int) -> int | None:
+    """The entry an error at ``[*path, i]`` belongs to, if it is one of
+    ``length`` entries."""
+    error_path = error.get("path")
+    if error_path is None or len(error_path) <= len(path):
+        return None
+    if any(error_path[i] != name for i, name in enumerate(path)):
+        return None
+    index = error_path[len(path)]
+    if not isinstance(index, int) or isinstance(index, bool):
+        return None
+    return index if 0 <= index < length else None

pyfect/graphql/_template.py

@@ -0,0 +1,111 @@
+"""Joining and slicing a ``DocumentTemplate`` without a GraphQL parser
+(Effect's ``internal/graphql`` printer): ``join_template`` gives the
+document a template was split from, and ``render_slices`` repeats it once
+per alias prefix."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from pyfect.graphql.template import DocumentTemplate, Fragment, Parts
+
+_WORD_END = re.compile(r'[\w"-]$', re.ASCII)
+_WORD_START = re.compile(r'^[\w"-]', re.ASCII)
+
+
+def _concat(left: str, right: str) -> str:
+    """Two printed pieces, with a space only where two non-punctuators
+    would touch (the generator printer's rule)."""
+    if _WORD_END.search(left) and _WORD_START.search(right):
+        return f"{left} {right}"
+    return left + right
+
+
+def _concat_all(pieces: Sequence[str]) -> str:
+    joined = ""
+    for piece in pieces:
+        joined = _concat(joined, piece)
+    return joined
+
+
+def _render_parts(parts: Parts, prefix: str) -> str:
+    return "".join(prefix + part if i % 2 == 1 else part for i, part in enumerate(parts))
+
+
+def _is_shared(fragment: Fragment) -> bool:
+    return len(fragment.body) <= 1
+
+
+def _render(kind: str, name: str, template: DocumentTemplate, prefixes: Sequence[str]) -> str:
+    variables = (
+        ""
+        if not template.variables
+        else "("
+        + _concat_all(
+            [
+                f"${prefix}{variable.name}:{variable.body}"
+                for prefix in prefixes
+                for variable in template.variables
+            ]
+        )
+        + ")"
+    )
+    selections: list[str] = []
+    for prefix in prefixes:
+        for selection in template.selections:
+            key = (
+                selection.alias if prefix == "" else f"{prefix}{selection.alias or selection.name}"
+            )
+            head = "" if key is None else f"{key}:"
+            selections.append(
+                f"{head}{selection.name or ''}{_render_parts(selection.body, prefix)}"
+            )
+    fragments = [
+        _concat_all(["fragment", prefix + fragment.name, _render_parts(fragment.body, prefix)])
+        for fragment in template.fragments
+        for prefix in ([""] if _is_shared(fragment) else prefixes)
+    ]
+    directives = "" if template.directives is None else _render_parts(template.directives, "")
+    return _concat_all(
+        [kind, name, variables, directives, "{" + _concat_all(selections) + "}", *fragments]
+    )
+
+
+def join_template(kind: str, name: str, template: DocumentTemplate) -> str:
+    """The document ``template`` was split from."""
+    return _render(kind, name, template, [""])
+
+
+def unsliceable_reason(template: DocumentTemplate) -> str | None:
+    """Why ``template`` cannot be repeated under aliases, if it cannot."""
+    if template.directives is not None and len(template.directives) > 1:
+        return "its operation directives reference variables"
+    if any(selection.name is None for selection in template.selections):
+        return "it has a fragment spread or inline fragment at the root"
+    return None
+
+
+def render_slices(kind: str, name: str, template: DocumentTemplate, prefixes: Sequence[str]) -> str:
+    """One operation repeating ``template`` once per prefix: each slice's
+    variables, root response keys and per-slice fragments are renamed with
+    its prefix; directives and shared fragments appear once. No prefix may
+    be a prefix of another. Raises ``ValueError`` for an unsliceable
+    template or a renamed fragment taking a shared fragment's name."""
+    shared = {fragment.name for fragment in template.fragments if _is_shared(fragment)}
+    collision = next(
+        (
+            prefix + fragment.name
+            for fragment in template.fragments
+            if not _is_shared(fragment)
+            for prefix in prefixes
+            if prefix + fragment.name in shared
+        ),
+        None,
+    )
+    reason = unsliceable_reason(template) or (
+        None if collision is None else f"fragment {collision} would collide with a shared fragment"
+    )
+    if reason is not None:
+        raise ValueError(f"Cannot render slices of operation {name}: {reason}")
+    return _render(kind, name, template, prefixes)

pyfect/graphql/_types.py

@@ -0,0 +1,115 @@
+"""What a GraphQL transport takes and gives: a ``GraphQLRequest`` in, an
+``Answer`` (the raw body with its HTTP status and headers) out, read by the
+client into an ``ExecutionResult``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Literal
+
+from pyfect import schema as S
+from pyfect.context import Reference, Tag
+from pyfect.effect import Effect
+from pyfect.graphql.client_error import GraphQLError, TransportError
+from pyfect.http.headers import EMPTY as EMPTY_HEADERS
+from pyfect.http.headers import Headers
+from pyfect.http.url_params import EMPTY as EMPTY_URL_PARAMS
+from pyfect.http.url_params import UrlParams
+from pyfect.stream import Stream
+
+type Kind = Literal["query", "mutation", "subscription"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GraphQLRequest:
+    """One operation to send: the document (``query``), the operation's
+    name and its encoded variables, plus per-call headers and URL params.
+    Middleware may return a changed copy (``dataclasses.replace``)."""
+
+    kind: Kind
+    query: str
+    operation_name: str
+    variables: object
+    extensions: Mapping[str, object] | None = None
+    headers: Headers = field(default=EMPTY_HEADERS)
+    url_params: UrlParams = field(default=EMPTY_URL_PARAMS)
+
+
+def request_body(request: GraphQLRequest) -> dict[str, object]:
+    """The JSON body of a POST and the payload of a graphql-ws
+    ``subscribe``; ``extensions`` is left out when unset."""
+    body: dict[str, object] = {
+        "query": request.query,
+        "operationName": request.operation_name,
+        "variables": request.variables,
+    }
+    if request.extensions is not None:
+        body["extensions"] = request.extensions
+    return body
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExecutionResult:
+    """A GraphQL response: ``data`` (``None`` when null or missing), its
+    ``errors`` and ``extensions``, and the transport's ``status`` and
+    ``headers`` (metadata, never read from the body)."""
+
+    data: object = None
+    errors: tuple[GraphQLError, ...] = ()
+    extensions: Mapping[str, S.JsonValue] | None = None
+    status: int | None = None
+    headers: Headers | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Answer:
+    """What a transport received: the parsed body, and the HTTP status and
+    headers when there were any."""
+
+    body: object
+    status: int | None = None
+    headers: Headers | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GraphQLProtocolService:
+    """A transport: ``execute`` sends a query or mutation, ``subscribe``
+    a subscription. ``url`` resolves the endpoint of an operation, when the
+    transport has one."""
+
+    execute: Callable[[GraphQLRequest], Effect[Answer, TransportError]]
+    subscribe: Callable[[GraphQLRequest], Stream[Answer, TransportError]]
+    url: Callable[[Kind, str], Effect[str]] | None = None
+
+
+class GraphQLProtocol(Tag[GraphQLProtocolService], key="effect/graphql/GraphQLProtocol"):
+    """The transport the GraphQL client sends through."""
+
+
+class ForcePost(Reference[bool], key="effect/graphql/ForcePost"):
+    """Set while a resolver batch is sent, so a transport that would send
+    queries by GET posts it (a batch may outgrow a URL)."""
+
+    @classmethod
+    def default(cls) -> bool:
+        return False
+
+
+@dataclass(frozen=True, slots=True)
+class BatchUrl:
+    """The URL a resolver batch was grouped by, and the ``url`` function
+    of the transport that resolved it."""
+
+    resolve: Callable[[Kind, str], Effect[str]]
+    url: str
+
+
+class ResolvedUrl(Reference[BatchUrl | None], key="effect/graphql/ResolvedUrl"):
+    """Carries a ``BatchUrl`` from a resolver batch to the transport, so it
+    sends there without resolving the URL again. The client clears it while
+    middleware run, so calls they make resolve their own."""
+
+    @classmethod
+    def default(cls) -> BatchUrl | None:
+        return None