pyfect-dev 0.1.0__py3-none-any.whl

pyfect/http/_httpx_options.py

@@ -0,0 +1,120 @@
+"""The ``httpx.AsyncClient`` options that would add to every request
+(``headers``, ``params``, ``cookies``, ``auth``), taken out of httpx's hands.
+
+httpx merges them into each request it sends, after pyfect's request
+transformations (``follow_redirects`` stripping credentials on a hop to
+another origin among them) have run. Parsed here once into a
+``RequestDefaults`` that the pyfect client applies as a request
+preprocessing step instead, so the request pyfect sees is the request sent.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Final
+
+from pyfect._extras import missing_extra
+from pyfect.http.request import HttpClientRequest
+
+REQUEST_DEFAULT_OPTIONS: Final = frozenset(("headers", "params", "cookies", "auth"))
+"""The ``httpx.AsyncClient`` parameters httpx merges into every request."""
+
+
+@dataclass(frozen=True, slots=True)
+class RequestDefaults:
+    """What each request gets unless it sets the same name itself."""
+
+    headers: tuple[tuple[str, str], ...] = ()
+    params: tuple[tuple[str, str], ...] = ()
+    basic_auth: tuple[str, str] | None = None
+
+    def is_empty(self) -> bool:
+        return not self.headers and not self.params and self.basic_auth is None
+
+    def apply(self, request: HttpClientRequest) -> HttpClientRequest:
+        if self.basic_auth is not None and "authorization" not in request.headers:
+            request = request.basic_auth(*self.basic_auth)
+        missing = [(name, value) for name, value in self.headers if name not in request.headers]
+        if missing:
+            request = request.update_headers(lambda headers: headers.set_all(missing))
+        params = request.url_params
+        added = [(name, value) for name, value in self.params if not params.get_all(name)]
+        if added:
+            request = request.set_url_params(params.append_all(added))
+        return request
+
+
+def _text(value: str | bytes) -> str:
+    return value.decode("latin-1") if isinstance(value, bytes) else value
+
+
+def _basic_auth(auth: object) -> tuple[str, str] | None:
+    match auth:
+        case None:
+            return None
+        case (str() | bytes() as username, str() | bytes() as password):
+            return _text(username), _text(password)
+        case _:
+            raise TypeError(
+                "httpx_client: auth must be a (username, password) pair; set any other "
+                "credential per request (client.map_request(lambda r: r.bearer_token(...))) "
+                "so follow_redirects can drop it on a hop to another origin"
+            )
+
+
+def _cookie_header(cookies: object) -> tuple[tuple[str, str], ...]:
+    match cookies:
+        case None:
+            return ()
+        case Mapping():
+            pairs = [(str(name), str(value)) for name, value in cookies.items()]  # pyright: ignore[reportUnknownVariableType, reportUnknownArgumentType]
+            return (
+                (("cookie", "; ".join(f"{name}={value}" for name, value in pairs)),)
+                if pairs
+                else ()
+            )
+        case _:
+            raise TypeError(
+                "httpx_client: cookies must be a mapping of names to values; "
+                "use HttpClientService.with_cookies_ref for a cookie jar"
+            )
+
+
+def import_httpx():  # the inferred return type is the httpx module
+    """The ``httpx`` module, imported when a client is made, so that
+    ``pyfect.http`` imports without the ``httpx`` extra."""
+    try:
+        import httpx
+    except ImportError as error:
+        raise missing_extra("pyfect.http.httpx_client", "httpx") from error
+    return httpx
+
+
+def _header_pairs(headers: Any) -> tuple[tuple[str, str], ...]:
+    if headers is None:
+        return ()
+    return tuple(
+        (name.lower(), value) for name, value in import_httpx().Headers(headers).multi_items()
+    )
+
+
+def _param_pairs(params: Any) -> tuple[tuple[str, str], ...]:
+    if params is None:
+        return ()
+    return tuple(import_httpx().QueryParams(params).multi_items())
+
+
+def split_options(options: Mapping[str, Any]) -> tuple[RequestDefaults, dict[str, Any]]:
+    """``options`` split into the request defaults and the rest (passed to
+    ``httpx.AsyncClient``). Raises ``TypeError`` for a default pyfect could
+    not keep from following a redirect to another origin."""
+    transport = {
+        name: value for name, value in options.items() if name not in REQUEST_DEFAULT_OPTIONS
+    }
+    defaults = RequestDefaults(
+        headers=_header_pairs(options.get("headers")) + _cookie_header(options.get("cookies")),
+        params=_param_pairs(options.get("params")),
+        basic_auth=_basic_auth(options.get("auth")),
+    )
+    return defaults, transport

pyfect/http/_in_memory.py

@@ -0,0 +1,76 @@
+"""An ``HttpClientService`` answered by an app in the same process (the
+client Effect's ``HttpApiTest.groups`` builds).
+
+Each request runs the app on the requesting fiber, in its own scope forked
+from the client's. A streamed response body is not buffered: the client
+reads it as the app writes it, one chunk per pull, and the request's scope
+closes when the body ends or the reader stops (or with the client's scope,
+for a body never read).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Never
+
+from pyfect._core import Effect
+from pyfect.effect import gen, provide_service, succeed
+from pyfect.exit import Exit, Success
+from pyfect.http._request_state import CurrentRequestState, RequestState
+from pyfect.http.client import HttpClientService
+from pyfect.http.client import make as make_http_client
+from pyfect.http.error import HttpClientError
+from pyfect.http.http_effect import scope_transfer_to_stream
+from pyfect.http.request import HttpClientRequest
+from pyfect.http.server_request import HttpServerRequest, from_client_request
+from pyfect.http.server_response import HttpServerResponse, to_client_response
+from pyfect.scope import CloseableScope, Scope
+
+
+def client(
+    app: Effect[HttpServerResponse, Any, Any], scope: CloseableScope
+) -> HttpClientService[HttpClientError, Any]:
+    """A client whose requests ``app`` answers; ``app`` 's failures are
+    defects of the request. Bodies left open close with ``scope``."""
+    return make_http_client(lambda request, _url, _signal, _fiber: _handle(app, scope, request))
+
+
+def _handle(
+    app: Effect[HttpServerResponse, Any, Any],
+    scope: CloseableScope,
+    request: HttpClientRequest,
+) -> Effect[Any, Never, Any]:
+    def run() -> Any:
+        request_scope: CloseableScope = yield from scope.fork()
+        server_request = from_client_request(request)
+        state = RequestState()
+        transferred = False
+
+        def pre_response(response: HttpServerResponse) -> Effect[HttpServerResponse, Any, Any]:
+            pre = state.pre_response_handler
+            return succeed(response) if pre is None else pre(server_request, response)
+
+        def to_client(response: HttpServerResponse) -> Any:
+            nonlocal transferred
+            transfer = scope_transfer_to_stream(response)
+            transferred = transfer is not response
+            return to_client_response(transfer, request=request)
+
+        def on_exit(exit_: Exit[Any, Any]) -> Effect[None]:
+            if transferred and isinstance(exit_, Success):
+                return succeed(None)
+            return request_scope.close(exit_)
+
+        return (
+            yield from app.flat_map(pre_response)
+            .map(to_client)
+            .pipe(provide_service(HttpServerRequest, server_request))
+            .pipe(provide_service(CurrentRequestState, state))
+            .pipe(provide_service(Scope, request_scope))
+            .or_die()
+            .on_exit(on_exit)
+        )
+
+    return gen(run)
+
+
+__all__ = ["client"]

pyfect/http/_request_state.py

@@ -0,0 +1,59 @@
+"""What a request being handled keeps besides its context: the handlers
+run on its response before it is sent, whether the logger is off, and
+whether its scope closes with the handler or with the response stream."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from pyfect._core import Effect
+from pyfect.context import Context, Tag
+
+if TYPE_CHECKING:
+    from pyfect.http.server_error import HttpServerError
+    from pyfect.http.server_request import ServerRequest
+    from pyfect.http.server_response import HttpServerResponse
+
+type PreResponseHandler = Callable[
+    [ServerRequest, HttpServerResponse], Effect[HttpServerResponse, HttpServerError]
+]
+"""Runs on a response before it is sent, and may replace it."""
+
+
+class RequestState:
+    __slots__ = ("handled", "logger_disabled", "pre_response_handler", "scope_ejected")
+
+    def __init__(self) -> None:
+        self.pre_response_handler: PreResponseHandler | None = None
+        self.logger_disabled = False
+        self.handled = False
+        self.scope_ejected = False
+
+
+class CurrentRequestState(Tag[RequestState], key="effect/http/HttpEffect/CurrentRequestState"):
+    """The state of the request being handled."""
+
+
+def get(context: Context[Any]) -> RequestState | None:
+    found, state = context.lookup(CurrentRequestState)
+    return state if found else None
+
+
+def append_pre_response_handler_unsafe(context: Context[Any], handler: PreResponseHandler) -> None:
+    """Run ``handler`` after the handlers already added (outside a request
+    being handled, nothing)."""
+    state = get(context)
+    if state is None:
+        return
+    previous = state.pre_response_handler
+    if previous is None:
+        state.pre_response_handler = handler
+        return
+
+    def both(
+        request: ServerRequest, response: HttpServerResponse
+    ) -> Effect[HttpServerResponse, HttpServerError]:
+        return previous(request, response).flat_map(lambda changed: handler(request, changed))
+
+    state.pre_response_handler = both

pyfect/http/_vary.py

@@ -0,0 +1,14 @@
+"""The ``Vary`` header a middleware extends."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+def vary_with(headers: Mapping[str, str], dimension: str) -> str:
+    """``Vary`` with ``dimension`` added, unless it (or ``*``) is there."""
+    vary = headers.get("vary")
+    if vary is None:
+        return dimension
+    members = [member.strip().lower() for member in vary.split(",")]
+    return vary if "*" in members or dimension.lower() in members else f"{vary}, {dimension}"

pyfect/http/abort.py

@@ -0,0 +1,65 @@
+"""Aborting a request in flight (the ``AbortController`` / ``AbortSignal``
+pair Effect's clients use).
+
+A client backend gets the request's ``AbortSignal`` and listens on it: the
+signal fires when the request is interrupted, when an unread response is
+garbage collected, when its stream ends or when its ``with_scope`` scope
+closes. Listeners run once, on the thread that aborts.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import final
+
+
+def _noop() -> None:
+    return None
+
+
+@final
+class AbortSignal:
+    __slots__ = ("_listeners", "_lock", "aborted")
+
+    def __init__(self) -> None:
+        self.aborted = False
+        self._listeners: list[Callable[[], object]] = []
+        self._lock = threading.Lock()
+
+    def add_listener(self, listener: Callable[[], object]) -> Callable[[], object]:
+        """Run ``listener`` on abort (now, if aborted already); returns a
+        function that removes it."""
+        with self._lock:
+            if not self.aborted:
+                self._listeners.append(listener)
+                return lambda: self._remove(listener)
+        listener()
+        return _noop
+
+    def _remove(self, listener: Callable[[], object]) -> None:
+        with self._lock:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+
+@final
+class AbortController:
+    __slots__ = ("signal",)
+
+    def __init__(self) -> None:
+        self.signal = AbortSignal()
+
+    def abort(self) -> None:
+        """Fire the signal; later calls do nothing."""
+        signal = self.signal
+        with signal._lock:  # pyright: ignore[reportPrivateUsage]
+            if signal.aborted:
+                return
+            signal.aborted = True
+            listeners, signal._listeners = signal._listeners, []  # pyright: ignore[reportPrivateUsage]
+        for listener in listeners:
+            listener()
+
+
+__all__ = ["AbortController", "AbortSignal"]

pyfect/http/asgi/__init__.py

@@ -0,0 +1,59 @@
+"""ASGI: HTTP apps on any ASGI 3 server, and ASGI applications inside
+apps.
+
+``to_asgi(app, layer)`` is an ASGI application for uvicorn, hypercorn,
+granian or a host framework (FastAPI's ``app.mount``). Its ``lifespan``
+scope builds the layer in a ``ManagedRuntime`` and releases it at
+shutdown; each request runs on its own fiber on the server's loop::
+
+    app = router.to_http_effect(routes)
+    asgi_app = asgi.to_asgi(app, services)  # uvicorn module:asgi_app
+
+Request bodies are streams that wait for the client; streamed responses
+are sent chunk by chunk; a client disconnect interrupts the request (a
+client abort, 499) and stops its body. A ``websocket`` scope is a ``GET``
+request whose ``upgrade`` is a WebSocket ``Socket`` (``request.upgrade``
+accepts it); an app that does not upgrade answers with its response.
+Under a host framework's ``Mount``, ``root_path`` is removed from the
+request's URL. Host frameworks send no lifespan to mounted apps: pass
+``asgi_app.lifespan()`` to the host's own (``FastAPI(lifespan=lambda _:
+asgi_app.lifespan())``).
+
+``router.to_asgi(routes)`` serves a router's routes the same way.
+
+The other way round, ``from_asgi(fastapi_app)`` is an app answering with
+another framework's application, mountable under a router prefix
+(``root_path`` is the prefix), and ``lifespan(fastapi_app)`` runs its
+startup and shutdown in a scope. ``pyfect.http.uvicorn_server`` serves an
+app on a port with uvicorn (extra ``pyfect-dev[server]``).
+"""
+
+from pyfect._public import publish
+from pyfect.http.asgi._app import AsgiApp, to_asgi, to_asgi_with
+from pyfect.http.asgi._http import HIGH_WATER_MARK, ClientDisconnectedError
+from pyfect.http.asgi._mount import AsgiLifespanError, AsgiNoResponseError, from_asgi, lifespan
+from pyfect.http.asgi._serve import AsgiHandler, UnsupportedScopeError
+from pyfect.http.asgi._types import AsgiApplication, Message, Receive, Scope, Send
+from pyfect.http.asgi._web_socket import AsgiWebSocket
+
+__all__ = [
+    "HIGH_WATER_MARK",
+    "AsgiApp",
+    "AsgiApplication",
+    "AsgiHandler",
+    "AsgiLifespanError",
+    "AsgiNoResponseError",
+    "AsgiWebSocket",
+    "ClientDisconnectedError",
+    "Message",
+    "Receive",
+    "Scope",
+    "Send",
+    "UnsupportedScopeError",
+    "from_asgi",
+    "lifespan",
+    "to_asgi",
+    "to_asgi_with",
+]
+
+publish(globals())

pyfect/http/asgi/_app.py

@@ -0,0 +1,155 @@
+"""``to_asgi``: an app as an ASGI 3 application whose services a layer
+builds, in a ``ManagedRuntime`` that lives as long as the server's
+lifespan."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from typing import Any, Never, overload
+
+from pyfect._context_effects import provide_context
+from pyfect._core import Effect, _WithFiber
+from pyfect._effect_args import require_effect
+from pyfect._fiber import Fiber
+from pyfect._layer_core import MemoMap, require_layer
+from pyfect.context import Context, Tag
+from pyfect.effect import succeed
+from pyfect.http.asgi._serve import AsgiHandler
+from pyfect.http.asgi._types import Receive, Scope, Send
+from pyfect.http.http_effect import HttpMiddleware
+from pyfect.http.server_request import HttpServerRequest
+from pyfect.http.server_response import HttpServerResponse
+from pyfect.layer import Layer, provide_merge
+from pyfect.layer import effect as layer_effect
+from pyfect.layer import empty as empty_layer
+from pyfect.managed_runtime import ManagedRuntime
+from pyfect.scope import Scope as ScopeTag
+
+
+class AsgiApp:
+    """An ASGI 3 application (``await app(scope, receive, send)``) serving
+    an HTTP app.
+
+    ``runtime`` holds the layer's services: built by the ``lifespan``
+    scope's startup, or by the first request when the server sends none,
+    and released at its shutdown, which interrupts requests in flight
+    (a plain app is uninterruptible, as in Effect, so it is awaited; router
+    routes are interruptible). Each request runs on its own fiber, on the
+    server's loop."""
+
+    __slots__ = ("_handler", "runtime")
+
+    def __init__(
+        self,
+        app: Effect[HttpServerResponse, Any, Any],
+        runtime: ManagedRuntime[Any, Any],
+        middleware: HttpMiddleware | None,
+    ) -> None:
+        self.runtime = runtime
+        self._handler = AsgiHandler(app, middleware, Context.empty(), self._fork)
+
+    def _fork(self, handled: Effect[None, Never, Any], context: Context[Any]) -> Fiber[None, Never]:
+        return self.runtime.run_fork(handled.pipe(provide_context(context)))
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            await self._lifespan(receive, send)
+        else:
+            await self._handler(scope, receive, send)
+
+    async def _lifespan(self, receive: Receive, send: Send) -> None:
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                try:
+                    await self.runtime.context()
+                except Exception as error:
+                    await send({"type": "lifespan.startup.failed", "message": str(error)})
+                    return
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                await self.runtime.dispose_async()
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncGenerator[None]:
+        """Build the services on enter and release them on exit: the
+        lifespan of a host app this one is mounted in (``FastAPI(lifespan=
+        lambda _: app.lifespan())``), whose server sends no lifespan to
+        mounted apps."""
+        await self.runtime.context()
+        try:
+            yield
+        finally:
+            await self.runtime.dispose_async()
+
+
+type _Served = HttpServerRequest | ScopeTag
+
+
+@overload
+def to_asgi[E](
+    app: Effect[HttpServerResponse, E, _Served],
+    /,
+    *,
+    middleware: HttpMiddleware | None = None,
+) -> AsgiApp: ...
+@overload
+def to_asgi[E, R, LE](
+    app: Effect[HttpServerResponse, E, R | _Served],
+    layer: Layer[R, LE],
+    /,
+    *,
+    middleware: HttpMiddleware | None = None,
+    memo_map: MemoMap | None = None,
+) -> AsgiApp: ...
+def to_asgi(
+    app: Effect[HttpServerResponse, Any, Any],
+    layer: Layer[Any, Any] | None = None,
+    /,
+    *,
+    middleware: HttpMiddleware | None = None,
+    memo_map: MemoMap | None = None,
+) -> AsgiApp:
+    """``app`` (through ``middleware``) as an ASGI 3 application for
+    uvicorn, hypercorn, granian or a host framework, with the services of
+    ``layer``. ``HEAD`` responses have no body; request bodies are
+    streams; streamed responses are sent as they are produced; a client
+    disconnect interrupts the request; WebSocket requests are upgraded
+    through ``request.upgrade``."""
+    require_effect(app, "app")
+    if layer is not None:
+        require_layer(layer, "layer")
+    runtime = ManagedRuntime.make(empty_layer if layer is None else layer, memo_map=memo_map)
+    return AsgiApp(app, runtime, middleware)
+
+
+class _ServedApp(Tag[Effect[HttpServerResponse, Any, Any]], key="pyfect/http/asgi/ServedApp"):
+    """The app ``to_asgi_with`` made of the layer's services."""
+
+
+def _served(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, Any, Any]:
+    return fiber._context.get_unsafe(_ServedApp)
+
+
+def to_asgi_with[LE](
+    layer: Layer[Any, LE],
+    to_app: Callable[[Context[Any]], Effect[HttpServerResponse, Any, Any]],
+    *,
+    middleware: HttpMiddleware | None = None,
+    memo_map: MemoMap | None = None,
+) -> AsgiApp:
+    """``to_asgi`` for the app ``to_app`` makes of ``layer``'s services once
+    they are built (what ``router.to_asgi`` serves routes with)."""
+    require_layer(layer, "layer")
+
+    def make(fiber: Fiber[Any, Any]) -> Effect[Effect[HttpServerResponse, Any, Any]]:
+        return succeed(to_app(fiber._context))
+
+    served = layer_effect(_ServedApp, _WithFiber(make)).pipe(provide_merge(layer))
+    runtime = ManagedRuntime.make(served, memo_map=memo_map)
+    app: Effect[HttpServerResponse, Any, Any] = _WithFiber(_served)
+    return AsgiApp(app, runtime, middleware)