pyfect-dev 0.1.0__py3-none-any.whl

pyfect/http_api/_client_response.py

@@ -0,0 +1,377 @@
+"""How a derived client reads a response (Effect's ``HttpApiClient``
+response decoders): a decoder for each declared status, choosing among
+content types, and the streaming success decoders."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, NotRequired, TypedDict, cast
+
+from pyfect import schema as S
+from pyfect._core import Effect
+from pyfect._json_text import PARSE_ERRORS, parse
+from pyfect.cause import Cause
+from pyfect.cause import fail as cause_fail
+from pyfect.cause import merge as cause_merge
+from pyfect.effect import context, fail, fail_cause, succeed, suspend
+from pyfect.encoding import ndjson, sse
+from pyfect.http import url_params
+from pyfect.http.error import DecodeError, HttpClientError, StatusCodeError
+from pyfect.http.response import HttpClientResponse
+from pyfect.http_api import _media_type as media_type
+from pyfect.http_api import schema as api_schema
+from pyfect.http_api._client_method import SseOptions
+from pyfect.option import Some
+from pyfect.schema import ParseOptions, SchemaError, Top
+from pyfect.schema import issue as I
+from pyfect.schema import transformation as T
+from pyfect.stream import Stream, transform_pull
+from pyfect.stream import provide_context as stream_provide_context
+
+type ResponseDecoder = Callable[[HttpClientResponse, SseOptions | None], Effect[Any, Any, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class _Alternative:
+    content_type: str
+    decode: ResponseDecoder
+
+
+def decoders(
+    errors: Mapping[int, tuple[Top, ...]],
+    successes: Mapping[int, tuple[Top, ...]],
+    streams: Sequence[tuple[Top, api_schema.StreamSchema]],
+    options: Any,
+) -> Mapping[int, ResponseDecoder]:
+    """The decoder of each declared status; ``options`` are the slot
+    parse options. A declared error is decoded then failed with."""
+    result: dict[int, ResponseDecoder] = {}
+    for status, alternatives in _alternatives(errors, options.error, options.headers).items():
+        result[status] = _fail_with(_choose(alternatives))
+    success = _alternatives(successes, options.success, options.headers)
+    for schema, body in streams:
+        status = api_schema.get_status_success_schema(schema)
+        success.setdefault(status, []).append(
+            _Alternative(
+                media_type.normalize(body.content_type),
+                _stream_response(schema, body, options.success, options.headers),
+            )
+        )
+    for status, alternatives in success.items():
+        result[status] = _choose(alternatives)
+    return result
+
+
+def _alternatives(
+    schemas: Mapping[int, tuple[Top, ...]], options: ParseOptions, headers_options: ParseOptions
+) -> dict[int, list[_Alternative]]:
+    result: dict[int, list[_Alternative]] = {}
+    for status, by_status in schemas.items():
+        for content_type, grouped in _by_content_type(by_status).items():
+            result.setdefault(status, []).append(
+                _Alternative(content_type, _schemas_response(grouped, options, headers_options))
+            )
+    return result
+
+
+def _by_content_type(schemas: tuple[Top, ...]) -> dict[str, list[Top]]:
+    grouped: dict[str, list[Top]] = {}
+    for schema in schemas:
+        body = api_schema.body_of(schema)
+        content_type = (
+            ""
+            if api_schema.is_no_content(body.__codec__().ast)
+            else media_type.normalize(api_schema.get_response_encoding_schema(schema).content_type)
+        )
+        grouped.setdefault(content_type, []).append(schema)
+    return grouped
+
+
+def _fail_with(decode: ResponseDecoder) -> ResponseDecoder:
+    def decode_error(
+        response: HttpClientResponse, sse_options: SseOptions | None
+    ) -> Effect[Any, Any, Any]:
+        status_error = HttpClientError(StatusCodeError(response.request, response))
+
+        def on_cause(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+            return fail_cause(cause_merge(cause_fail(status_error), cause))
+
+        return decode(response, sse_options).catch_cause(on_cause).flat_map(fail)
+
+    return decode_error
+
+
+def _choose(alternatives: list[_Alternative]) -> ResponseDecoder:
+    if len(alternatives) == 1:
+        return alternatives[0].decode
+
+    def decode(response: HttpClientResponse, sse_options: SseOptions | None) -> Any:
+        content_type = media_type.normalize(response.headers.get("content-type") or "")
+        for alternative in alternatives:
+            if alternative.content_type == content_type:
+                return alternative.decode(response, sse_options)
+        expected = ", ".join(dict.fromkeys(a.content_type for a in alternatives))
+        return fail(
+            decode_error(
+                response,
+                f"Unsupported response content-type for status {response.status}: "
+                f"{content_type or '<missing>'}. Expected one of: {expected}",
+            )
+        )
+
+    return decode
+
+
+def decode_error(response: HttpClientResponse, description: str) -> HttpClientError:
+    return HttpClientError(DecodeError(response.request, response, description=description))
+
+
+def undeclared_status(response: HttpClientResponse, _: SseOptions | None) -> Effect[Any, Any]:
+    return fail(decode_error(response, "undeclared status code"))
+
+
+# --- buffered bodies -------------------------------------------------------------------
+
+
+def _forbidden_decode(input: object, options: ParseOptions) -> Effect[Any, I.Issue]:
+    del options
+    return fail(I.Forbidden({"message": "Decode only schema"}, Some(input)))
+
+
+def _forbidden_encode(input: object, options: ParseOptions) -> Effect[Any, I.Issue]:
+    del options
+    return fail(I.Forbidden({"message": "Encode only schema"}, Some(input)))
+
+
+def _text(data: bytes) -> str:
+    return data.decode("utf-8", "replace")
+
+
+def _json(data: object, options: ParseOptions) -> Effect[object, I.Issue]:
+    del options
+    text = _text(cast("bytes", data))
+    if text == "":
+        return succeed(None)
+    try:
+        return succeed(parse(text))
+    except PARSE_ERRORS as error:
+        return fail(I.InvalidValue({"message": str(error)}, Some(text)))
+
+
+def _from_bytes(
+    decode: Callable[[object, ParseOptions], Effect[object, I.Issue]],
+) -> S.Bottom[object, Any]:
+    return S.Bytes.pipe(
+        S.decode_to(S.Unknown, T.transform_effect(decode=decode, encode=_forbidden_encode))
+    )
+
+
+def _sync(
+    f: Callable[[bytes], object],
+) -> Callable[[object, ParseOptions], Effect[object, I.Issue]]:
+    return lambda data, _options: succeed(f(data))  # pyright: ignore[reportArgumentType]
+
+
+_BODIES: Mapping[str, S.Bottom[object, Any]] = {
+    "Json": _from_bytes(_json),
+    "Text": _from_bytes(_sync(_text)),
+    "Uint8Array": _from_bytes(_sync(lambda data: data)),
+    "FormUrlEncoded": _from_bytes(_sync(lambda data: url_params.parse(_text(data)).to_record())),
+}
+
+
+def _from_body(schema: Top) -> Top:
+    """``schema``'s values from the bytes of a response body."""
+    body = _BODIES[api_schema.get_response_encoding(schema.__codec__().ast).tag]
+    return body.pipe(S.decode_to(schema))
+
+
+def _schemas_response(
+    schemas: list[Top], options: ParseOptions, headers_options: ParseOptions
+) -> ResponseDecoder:
+    with_headers = any(
+        api_schema.is_with_headers(s)
+        or api_schema.get_with_headers_annotation(s.__codec__().ast) is not None
+        for s in schemas
+    )
+    if not with_headers:
+        decode = S.decode_unknown_effect(S.Union(*(_from_body(s) for s in schemas)), **options)
+        return lambda response, _: response.bytes_.flat_map(decode)
+    codec = S.Union(*(_with_headers_body(s, options, headers_options) for s in schemas))
+    decode_pair = S.decode_unknown_effect(codec, **options)
+    return lambda response, _: response.bytes_.flat_map(
+        lambda data: decode_pair({"body": data, "headers": response.headers})
+    )
+
+
+class _Pair(TypedDict):
+    body: object
+    headers: object
+
+
+_PAIR = S.Struct(_Pair)
+
+
+def _with_headers_body(schema: Top, options: ParseOptions, headers_options: ParseOptions) -> Top:
+    """A ``{"body", "headers"}`` pair decoded into ``schema``'s value: the
+    body with ``options`` and the headers with ``headers_options``."""
+    annotation = api_schema.get_with_headers_annotation(schema.__codec__().ast)
+    if annotation is not None:
+        body, headers = annotation.body_codec, annotation.headers_codec
+        to_value: Callable[[Mapping[str, Any]], object] = annotation.decode
+    elif api_schema.is_with_headers(schema):
+        body, headers = schema.schema, schema.headers
+        to_value = lambda pair: api_schema.with_headers(pair["body"], pair["headers"])  # noqa: E731
+    else:
+        body, headers = schema, S.Unknown
+        to_value = lambda pair: pair["body"]  # noqa: E731
+    decode_body = S.decode_unknown_effect(_from_body(body), **options)
+    decode_headers = S.decode_unknown_effect(headers, **headers_options)
+
+    def decode(pair: Mapping[str, Any], _options: ParseOptions) -> Effect[object, I.Issue, Any]:
+        both = decode_body(pair["body"]).zip(decode_headers(pair["headers"]))
+        return both.map(lambda parts: to_value({"body": parts[0], "headers": parts[1]})).map_error(
+            lambda error: error.issue
+        )
+
+    target = schema if api_schema.is_with_headers(schema) else S.to_type(schema)
+    return _PAIR.pipe(
+        S.decode_to(target, T.transform_effect(decode=decode, encode=_forbidden_decode))
+    )
+
+
+# --- streams ---------------------------------------------------------------------------
+
+
+def _stream_response(
+    schema: Top,
+    body: api_schema.StreamSchema,
+    options: ParseOptions,
+    headers_options: ParseOptions,
+) -> ResponseDecoder:
+    decode_body = _stream_body(body, options)
+
+    def to_stream(
+        response: HttpClientResponse, sse_options: SseOptions | None
+    ) -> Effect[Stream[Any, Any, Any]]:
+        return context().map(
+            lambda services: decode_body(response, sse_options).pipe(
+                stream_provide_context(services)
+            )
+        )
+
+    if not api_schema.is_with_headers(schema):
+        return to_stream
+    decode_headers = S.decode_unknown_effect(schema.headers, **headers_options)
+    return lambda response, sse_options: decode_headers(response.headers).flat_map(
+        lambda headers: to_stream(response, sse_options).map(
+            lambda stream: api_schema.with_headers(stream, headers)
+        )
+    )
+
+
+type _BodyDecoder = Callable[[HttpClientResponse, SseOptions | None], Stream[Any, Any, Any]]
+
+
+def _stream_body(schema: api_schema.StreamSchema, options: ParseOptions) -> _BodyDecoder:
+    if isinstance(schema, api_schema.StreamUint8ArraySchema):
+        return lambda response, _: response.stream
+    if isinstance(schema, api_schema.StreamNdjsonSchema):
+        return _ndjson_body(schema, options)
+    return _sse_body(schema, options)
+
+
+def _ndjson_body(schema: api_schema.StreamNdjsonSchema[Any], options: ParseOptions) -> _BodyDecoder:
+    decode_element = S.decode_unknown_effect(S.to_codec_json(schema.schema), **options)
+    max_element_bytes = int(schema.max_element_bytes)
+
+    def decode(response: HttpClientResponse, _: SseOptions | None) -> Stream[Any, Any, Any]:
+        def to_error(error: object) -> object:
+            if not isinstance(error, ndjson.NdjsonError):
+                return error
+            if error.reason != "LineTooLarge":
+                return ndjson_schema_error(error)
+            return decode_error(
+                response, f"NDJSON line exceeds maxElementBytes of {max_element_bytes} bytes"
+            )
+
+        return (
+            response.stream.pipe_through_channel(
+                ndjson.decode(ignore_empty_lines=True, max_line_bytes=max_element_bytes)
+            )
+            .map_error(to_error)
+            .map_effect(decode_element)
+        )
+
+    return decode
+
+
+def ndjson_schema_error(error: ndjson.NdjsonError) -> SchemaError:
+    if error.reason == "InvalidUtf8":
+        message = "Expected valid UTF-8"
+    elif error.unterminated:
+        message = "Expected a valid JSON line, got an unterminated final line"
+    else:
+        message = "Expected a valid JSON line"
+    return SchemaError(I.InvalidValue({"message": message}))
+
+
+class _FailureEvent(TypedDict):
+    event: str
+    data: object
+    id: NotRequired[str]
+
+
+def _sse_body(schema: api_schema.StreamSseSchema[Any, Any], options: ParseOptions) -> _BodyDecoder:
+    cause = S.from_json_string(S.to_codec_json(S.Cause(schema.error, S.Defect())))
+    failure = S.Struct(
+        _FailureEvent, event=S.Literal(api_schema.RESERVED_STREAM_FAILURE_EVENT), data=cause
+    )
+    event = S.Union(failure, schema.events)
+    data_mode = schema.sse_mode == "data"
+
+    def decode(
+        response: HttpClientResponse, sse_options: SseOptions | None
+    ) -> Stream[Any, Any, Any]:
+        max_event_size = (sse_options or {}).get("max_event_size", sse.DEFAULT_MAX_EVENT_SIZE)
+        decoder: Any = sse.decode_schema(event, max_event_size=max_event_size, **options)
+        events = transform_pull(
+            response.stream.decode_text().pipe_through_channel(decoder), _until_failure
+        )
+        return events.map(lambda e: e["data"]) if data_mode else events
+
+    return decode
+
+
+def _until_failure(pull: Effect[tuple[Any, ...], Any], _scope: object) -> Effect[Any]:
+    """The events up to a reserved failure event, then its cause."""
+    pending: list[Cause[Any]] = []
+
+    def next_events() -> Effect[tuple[Any, ...], Any]:
+        if pending:
+            return fail_cause(pending[0])
+        return pull.flat_map(split)
+
+    def split(events: tuple[Any, ...]) -> Effect[tuple[Any, ...], Any]:
+        for index, event in enumerate(cast("tuple[Mapping[str, object], ...]", events)):
+            data = event.get("data")
+            is_failure = event.get("event") == api_schema.RESERVED_STREAM_FAILURE_EVENT
+            if is_failure and isinstance(data, Cause):
+                data = cast("Cause[Any]", data)
+                if index == 0:
+                    return fail_cause(data)
+                pending.append(data)
+                return succeed(events[:index])
+        return succeed(events)
+
+    return succeed(suspend(next_events))
+
+
+__all__ = [
+    "ResponseDecoder",
+    "decode_error",
+    "decoders",
+    "ndjson_schema_error",
+    "undeclared_status",
+]

pyfect/http_api/_handlers.py

@@ -0,0 +1,282 @@
+"""The handlers of a group's endpoints (Effect's ``HttpApiBuilder``
+``Handlers``)::
+
+    handlers.handle(Users.get_user)(get_user).handle(Users.list_users)(list_users)
+
+``handle(endpoint)`` gives the slot of one endpoint; calling it with the
+handler gives the handlers with that one added. The two steps let the
+handler's types be checked against the endpoint's: its request is the
+endpoint's, its success and errors must be declared, and the services its
+middleware provides are not required of the group layer
+(``research/typing/httpapi_2_middleware.py``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, Never, TypeVar, overload
+
+from pyfect._core import Effect
+from pyfect.http.router import Provided
+from pyfect.http.server_request import ServerRequest
+from pyfect.http.server_response import HttpServerResponse
+from pyfect.http_api.endpoint import AnyEndpoint, HttpApiEndpoint
+from pyfect.http_api.error import HttpApiPayloadTooLarge, HttpApiSchemaError
+from pyfect.http_api.group import AnyGroup, HttpApiGroup
+from pyfect.http_api.middleware import HttpApiMiddleware
+
+if TYPE_CHECKING:
+    from pyfect.socket import SocketService
+
+P_co = TypeVar("P_co", covariant=True)
+Q_co = TypeVar("Q_co", covariant=True)
+B_co = TypeVar("B_co", covariant=True)
+H_co = TypeVar("H_co", covariant=True)
+X_co = TypeVar("X_co", covariant=True)
+S = TypeVar("S")
+E = TypeVar("E")
+MP_co = TypeVar("MP_co", covariant=True)
+GP = TypeVar("GP")
+GE = TypeVar("GE")
+R_co = TypeVar("R_co", covariant=True)
+
+type PayloadErrors = HttpApiSchemaError | HttpApiPayloadTooLarge
+"""What reading a streamed payload may fail with; any handler may fail
+with them (they become defects)."""
+
+
+@dataclass(frozen=True, slots=True)
+class HttpApiRequest(Generic[P_co, Q_co, B_co, H_co]):
+    """What a handler gets: the decoded ``params``, ``query``, ``payload``
+    and ``headers`` (``None`` for a part the endpoint does not declare),
+    the ``request``, its ``endpoint`` and ``group``."""
+
+    params: P_co
+    query: Q_co
+    payload: B_co
+    headers: H_co
+    request: ServerRequest
+    endpoint: AnyEndpoint
+    group: AnyGroup
+    upgrader: Callable[[object], Effect[SocketService]] | None = field(default=None, repr=False)
+
+    def upgrade(self, headers: object = None) -> Effect[SocketService]:
+        """The upgraded connection of an ``Upgrade`` endpoint, answering the
+        ``101`` with ``headers`` (encoded by the upgrade's headers schema).
+        Return it from the handler."""
+        if self.upgrader is None:
+            raise TypeError(f"Endpoint {self.endpoint.identifier!r} declares no Upgrade")
+        return self.upgrader(headers)
+
+
+type Handler = Callable[[HttpApiRequest[Any, Any, Any, Any]], Effect[Any, Any, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class HandlerEntry:
+    """A registered handler (Effect's ``HandlerRuntime``)."""
+
+    endpoint: AnyEndpoint
+    handler: Handler
+    is_raw: bool
+    uninterruptible: bool
+
+
+@dataclass(frozen=True, slots=True)
+class Handlers(Generic[GP, GE, R_co]):
+    """The handlers of ``group`` so far, needing ``R``. ``GP`` and ``GE``
+    are what the group's middleware provides and fails with."""
+
+    group: AnyGroup
+    entries: Mapping[str, HandlerEntry] = field(default_factory=dict[str, HandlerEntry])
+
+    @overload
+    def handle[P, Q, B, CB, H, S1, CS, E1](
+        self,
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, Never],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, B, H], S1, E1 | GE, GP, GP, GE, R_co]: ...
+    @overload
+    def handle[P, Q, B, CB, H, S1, CS, E1, MP, ME, MR, MT](
+        self,
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, HttpApiMiddleware[MP, ME, MR], MT],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, B, H], S1, E1 | ME | GE, MP | GP, GP, GE, R_co | MT | MR]: ...
+    def handle(self, endpoint: AnyEndpoint, /, *, uninterruptible: bool = False) -> Any:
+        """The slot of ``endpoint``'s handler; ``uninterruptible`` runs it
+        uninterruptibly."""
+        return Bound[Any, Any, Any, Any, Any, Any, Any](self, endpoint, False, uninterruptible)
+
+    @overload
+    def handle_raw[P, Q, B, CB, H, S1, CS, E1](
+        self,
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, Never],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, None, H], S1, E1 | GE, GP, GP, GE, R_co]: ...
+    @overload
+    def handle_raw[P, Q, B, CB, H, S1, CS, E1, MP, ME, MR, MT](
+        self,
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, HttpApiMiddleware[MP, ME, MR], MT],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[
+        HttpApiRequest[P, Q, None, H], S1, E1 | ME | GE, MP | GP, GP, GE, R_co | MT | MR
+    ]: ...
+    def handle_raw(self, endpoint: AnyEndpoint, /, *, uninterruptible: bool = False) -> Any:
+        """``handle`` without reading the payload: the handler reads the
+        request's body itself."""
+        return Bound[Any, Any, Any, Any, Any, Any, Any](self, endpoint, True, uninterruptible)
+
+    def _register(self, entry: HandlerEntry) -> Handlers[Any, Any, Any]:
+        identifier = entry.endpoint.identifier
+        group = self.group
+        if identifier not in group.endpoints:
+            raise ValueError(
+                f'HttpApiEndpoint "{identifier}" not found in HttpApiGroup "{group.identifier}"'
+            )
+        if identifier in self.entries:
+            raise ValueError(
+                f'Handler for HttpApiEndpoint "{identifier}" is already registered in '
+                f'HttpApiGroup "{group.identifier}"'
+            )
+        canonical = HandlerEntry(
+            group.endpoints[identifier], entry.handler, entry.is_raw, entry.uninterruptible
+        )
+        return Handlers(group, {**self.entries, identifier: canonical})
+
+
+@dataclass(frozen=True, slots=True)
+class Bound(Generic[X_co, S, E, MP_co, GP, GE, R_co]):
+    """The handler slot of one endpoint: its request ``X``, success ``S``,
+    errors ``E`` and the services its middleware provides ``MP``; ``R``
+    holds the group layer's requirements so far and the endpoint's
+    middleware. Both are computed in ``handle``: in one call the
+    middleware's services would be solved from the handler too, and a
+    union of two class TypeVars that are both ``Never`` is ``Unknown``."""
+
+    handlers: Handlers[Any, Any, Any]
+    endpoint: AnyEndpoint
+    is_raw: bool
+    uninterruptible: bool
+
+    @overload
+    def __call__(
+        self,
+        handler: Callable[
+            [X_co], Effect[S | HttpServerResponse, E | PayloadErrors, MP_co | Provided]
+        ],
+        /,
+    ) -> Handlers[GP, GE, R_co]: ...
+    @overload
+    def __call__[R1](
+        self,
+        handler: Callable[
+            [X_co], Effect[S | HttpServerResponse, E | PayloadErrors, R1 | MP_co | Provided]
+        ],
+        /,
+    ) -> Handlers[GP, GE, R_co | R1]: ...
+    def __call__(self, handler: Any, /) -> Any:
+        return self.handlers._register(  # pyright: ignore[reportPrivateUsage]
+            HandlerEntry(self.endpoint, handler, self.is_raw, self.uninterruptible)
+        )
+
+
+G_co = TypeVar("G_co", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class GroupHandlers(Generic[G_co]):
+    """The handlers of the group ``G`` before the first one: ``handle``
+    reads what the group's middleware provides and fails with from ``G``
+    (``Handlers`` carries them on)."""
+
+    group: AnyGroup
+
+    @overload
+    def handle[P, Q, B, CB, H, S1, CS, E1](
+        self: GroupHandlers[HttpApiGroup[Never, Never]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, Never],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, B, H], S1, E1, Never, Never, Never, Never]: ...
+    @overload
+    def handle[P, Q, B, CB, H, S1, CS, E1, MP, ME, MR, MT](
+        self: GroupHandlers[HttpApiGroup[Never, Never]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, HttpApiMiddleware[MP, ME, MR], MT],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, B, H], S1, E1 | ME, MP, Never, Never, MT | MR]: ...
+    @overload
+    def handle[P, Q, B, CB, H, S1, CS, E1, GP1, GE1, GR1, GT1](
+        self: GroupHandlers[HttpApiGroup[HttpApiMiddleware[GP1, GE1, GR1], GT1]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, Never],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, B, H], S1, E1 | GE1, GP1, GP1, GE1, GT1 | GR1]: ...
+    @overload
+    def handle[P, Q, B, CB, H, S1, CS, E1, MP, ME, MR, MT, GP1, GE1, GR1, GT1](
+        self: GroupHandlers[HttpApiGroup[HttpApiMiddleware[GP1, GE1, GR1], GT1]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, HttpApiMiddleware[MP, ME, MR], MT],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[
+        HttpApiRequest[P, Q, B, H], S1, E1 | ME | GE1, MP | GP1, GP1, GE1, MT | MR | GT1 | GR1
+    ]: ...
+    def handle(self, endpoint: AnyEndpoint, /, *, uninterruptible: bool = False) -> Any:
+        """The slot of ``endpoint``'s handler (see ``Handlers.handle``)."""
+        return Handlers[Any, Any, Any](self.group).handle(endpoint, uninterruptible=uninterruptible)
+
+    @overload
+    def handle_raw[P, Q, B, CB, H, S1, CS, E1](
+        self: GroupHandlers[HttpApiGroup[Never, Never]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, Never],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, None, H], S1, E1, Never, Never, Never, Never]: ...
+    @overload
+    def handle_raw[P, Q, B, CB, H, S1, CS, E1, MP, ME, MR, MT](
+        self: GroupHandlers[HttpApiGroup[Never, Never]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, HttpApiMiddleware[MP, ME, MR], MT],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, None, H], S1, E1 | ME, MP, Never, Never, MT | MR]: ...
+    @overload
+    def handle_raw[P, Q, B, CB, H, S1, CS, E1, GP1, GE1, GR1, GT1](
+        self: GroupHandlers[HttpApiGroup[HttpApiMiddleware[GP1, GE1, GR1], GT1]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, Never],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[HttpApiRequest[P, Q, None, H], S1, E1 | GE1, GP1, GP1, GE1, GT1 | GR1]: ...
+    @overload
+    def handle_raw[P, Q, B, CB, H, S1, CS, E1, MP, ME, MR, MT, GP1, GE1, GR1, GT1](
+        self: GroupHandlers[HttpApiGroup[HttpApiMiddleware[GP1, GE1, GR1], GT1]],
+        endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E1, HttpApiMiddleware[MP, ME, MR], MT],
+        /,
+        *,
+        uninterruptible: bool = False,
+    ) -> Bound[
+        HttpApiRequest[P, Q, None, H], S1, E1 | ME | GE1, MP | GP1, GP1, GE1, MT | MR | GT1 | GR1
+    ]: ...
+    def handle_raw(self, endpoint: AnyEndpoint, /, *, uninterruptible: bool = False) -> Any:
+        """``Handlers.handle_raw``."""
+        return Handlers[Any, Any, Any](self.group).handle_raw(
+            endpoint, uninterruptible=uninterruptible
+        )
+
+
+__all__ = ["Bound", "GroupHandlers", "HandlerEntry", "Handlers", "HttpApiRequest", "PayloadErrors"]

pyfect/http_api/_html.py

@@ -0,0 +1,38 @@
+"""Escaping for the documentation pages (Effect's ``internal/html``)."""
+
+from collections.abc import Callable
+from importlib import resources
+
+from pyfect import _json_text
+
+
+def escape_json(value: object) -> str:
+    """``value`` as JSON safe inside a ``<script>`` element."""
+    text = _json_text.stringify(value)
+    return text.replace("<", "\\u003c").replace("\u2028", "\\u2028").replace("\u2029", "\\u2029")
+
+
+def escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def escape_attribute(text: str) -> str:
+    return escape(text).replace('"', "&quot;").replace("'", "&#39;")
+
+
+def memoize_success[A](make: Callable[[], A]) -> Callable[[], A]:
+    """``make()``, made once it succeeds: a raise is retried on the next
+    call (Effect's ``Function.memoize`` of a function that throws)."""
+    done: list[A] = []
+
+    def get() -> A:
+        if not done:
+            done.append(make())
+        return done[0]
+
+    return get
+
+
+def asset(name: str) -> str:
+    """A bundled documentation asset (``_assets/<name>``)."""
+    return resources.files("pyfect.http_api").joinpath("_assets", name).read_text("utf-8")