pyfect-dev 0.1.0__py3-none-any.whl

pyfect/http/asgi/_http.py

@@ -0,0 +1,201 @@
+"""An HTTP request over ASGI: the scope and ``http.request`` messages as a
+``WebRequest``, the handler's ``WebResponse`` as ``http.response.*``
+messages.
+
+One task reads ``receive`` for the whole request. It buffers body chunks
+until ``HIGH_WATER_MARK`` bytes wait unread, and an ``http.disconnect``
+before the response is complete fires the request's signal, which
+interrupts the app (a client abort) and stops a streamed body. While the
+buffer is full nothing is read, so a disconnect is seen once the app reads
+on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import AsyncIterator
+from typing import Any
+
+from pyfect.http._field import is_field_value, is_token
+from pyfect.http.abort import AbortController
+from pyfect.http.asgi import _scope
+from pyfect.http.asgi._types import Message, Receive, Scope, Send
+from pyfect.http.web import WebRequest, WebResponse
+from pyfect.http.web_handler import WebHandler
+
+HIGH_WATER_MARK = 64 * 1024
+
+
+class ClientDisconnectedError(ConnectionError):
+    """The client went away before the request body ended."""
+
+
+class _Inbound:
+    __slots__ = (
+        "_changed",
+        "_chunks",
+        "_controller",
+        "_ended",
+        "_receive",
+        "_room",
+        "_size",
+        "_task",
+        "disconnected",
+        "responded",
+    )
+
+    def __init__(self, receive: Receive, controller: AbortController) -> None:
+        self._receive = receive
+        self._controller = controller
+        self._chunks: deque[bytes] = deque()
+        self._size = 0
+        self._ended = False
+        self._changed = asyncio.Event()
+        self._room = asyncio.Event()
+        self._room.set()
+        self.disconnected = False
+        self.responded = False
+        self._task = asyncio.get_running_loop().create_task(self._pump())
+
+    async def _pump(self) -> None:
+        while True:
+            await self._room.wait()
+            message = await self._receive()
+            if message["type"] == "http.disconnect":
+                self.disconnected = True
+                self._changed.set()
+                if not self.responded:
+                    self._controller.abort()
+                return
+            if message["type"] != "http.request" or self._ended:
+                continue
+            chunk: bytes = message.get("body", b"")
+            if chunk:
+                self._chunks.append(chunk)
+                self._size += len(chunk)
+                if self._size >= HIGH_WATER_MARK:
+                    self._room.clear()
+            if not message.get("more_body", False):
+                self._ended = True
+            self._changed.set()
+
+    async def chunks(self) -> AsyncIterator[bytes]:
+        while True:
+            if self._chunks:
+                chunk = self._chunks.popleft()
+                self._size -= len(chunk)
+                if self._size < HIGH_WATER_MARK:
+                    self._room.set()
+                yield chunk
+            elif self._ended:
+                return
+            elif self.disconnected:
+                raise ClientDisconnectedError("the client disconnected")
+            else:
+                self._changed.clear()
+                await self._changed.wait()
+
+    def close(self) -> None:
+        self._task.cancel()
+
+
+def request_of(
+    scope: Scope, body: AsyncIterator[bytes] | None, controller: AbortController
+) -> WebRequest | None:
+    """The request, or ``None`` when its target is not origin-form."""
+    lines = _scope.header_lines(scope)
+    url = _scope.url(scope, lines)
+    if url is None:
+        return None
+    return WebRequest(
+        url,
+        method=scope.get("method", "GET"),
+        headers=lines,
+        body=body if _scope.has_body(scope, lines) else None,
+        signal=controller.signal,
+        remote_address=_scope.remote_address(scope),
+    )
+
+
+class InvalidResponseHeaderError(ValueError):
+    """A response header that cannot be sent (Node's ``writeHead`` throws)."""
+
+
+def encode_headers(lines: tuple[tuple[str, str], ...]) -> list[tuple[bytes, bytes]]:
+    """The header lines as ASGI sends them; an invalid one raises
+    ``InvalidResponseHeaderError``."""
+    encoded: list[tuple[bytes, bytes]] = []
+    for name, value in lines:
+        if not is_token(name) or not is_field_value(value):
+            raise InvalidResponseHeaderError(f"Invalid response header: {name}")
+        try:
+            encoded.append((name.encode("latin-1"), value.encode("latin-1")))
+        except UnicodeEncodeError as cause:
+            raise InvalidResponseHeaderError(f"Invalid response header: {name}") from cause
+    return encoded
+
+
+async def _aclose(chunks: AsyncIterator[bytes]) -> None:
+    close: Any = getattr(chunks, "aclose", None)
+    if close is not None:
+        await close()
+
+
+async def send_response(send: Send, response: WebResponse, inbound: _Inbound) -> None:
+    try:
+        headers = encode_headers(response.header_lines)
+    except InvalidResponseHeaderError:
+        # Answered with a 500, then reported by the server.
+        await send({"type": "http.response.start", "status": 500, "headers": []})
+        inbound.responded = True
+        await send({"type": "http.response.body", "body": b""})
+        await _aclose(response.chunks())
+        raise
+    start: Message = {"type": "http.response.start", "status": response.status, "headers": headers}
+    body = response.body
+    if body is None or isinstance(body, bytes):
+        await send(start)
+        inbound.responded = True
+        await send({"type": "http.response.body", "body": body or b""})
+        return
+    chunks = response.chunks()
+    try:
+        await send(start)
+        async for chunk in chunks:
+            if inbound.disconnected:
+                return
+            if chunk:
+                await send({"type": "http.response.body", "body": chunk, "more_body": True})
+        inbound.responded = True
+        await send({"type": "http.response.body", "body": b""})
+    finally:
+        await _aclose(chunks)
+
+
+async def serve_http(
+    handler: WebHandler,
+    scope: Scope,
+    receive: Receive,
+    send: Send,
+    controller: AbortController,
+) -> None:
+    """Answer one ``http`` scope with ``handler``. ``controller`` aborts the
+    request: it interrupts the app and ends a streamed body."""
+    inbound = _Inbound(receive, controller)
+    try:
+        request = request_of(scope, inbound.chunks(), controller)
+        response = await handler(request) if request is not None else WebResponse(status=400)
+        await send_response(send, response, inbound)
+    except asyncio.CancelledError:
+        controller.abort()
+        raise
+    except OSError:
+        # The server could not send: the client is gone.
+        controller.abort()
+    except Exception:
+        # A body stopped because the client went away ends quietly.
+        if not controller.signal.aborted:
+            raise
+    finally:
+        inbound.close()

pyfect/http/asgi/_mount.py

@@ -0,0 +1,263 @@
+"""Another framework's ASGI application (FastAPI, Starlette...) as an HTTP
+app: ``from_asgi`` answers each request with it, and ``lifespan`` runs its
+startup and shutdown with a scope. Both await the application on the
+fiber's asyncio loop, so they need an asyncio run (``run_main``,
+``run_async``, the ASGI and uvicorn servers)."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+from pyfect._core import Effect, _WithFiber
+from pyfect._fiber import Fiber
+from pyfect.effect import fail, from_async, try_async
+from pyfect.errors import TaggedError
+from pyfect.http._foreign_path import decode_path
+from pyfect.http.abort import AbortController
+from pyfect.http.asgi._types import AsgiApplication, Message
+from pyfect.http.server_error import HttpServerError, InternalError
+from pyfect.http.server_request import HttpServerRequest, ServerRequest, to_url
+from pyfect.http.server_response import HttpServerResponse
+from pyfect.http.web import WebResponse
+from pyfect.http.web_handler import request_to_web, response_from_web
+from pyfect.result import Err, Ok
+from pyfect.scope import Scope, acquire_release
+
+_ASGI = {"version": "3.0", "spec_version": "2.4"}
+_QUEUED_CHUNKS = 16
+
+
+class AsgiNoResponseError(RuntimeError):
+    """The application returned without starting a response."""
+
+
+def _root_path(request: ServerRequest) -> tuple[str, str]:
+    """The original path, and the part of it a router's prefix removed."""
+    original = urlsplit(request.original_url).path or "/"
+    path = request.url.split("?", 1)[0] or "/"
+    if path == "/":
+        return original, original.removesuffix("/")
+    if original.endswith(path):
+        return original, original[: len(original) - len(path)]
+    return original, ""
+
+
+def _scope(request: ServerRequest, state: Mapping[str, Any] | None) -> dict[str, Any]:
+    original, root = _root_path(request)
+    query = request.url.split("?", 1)[1] if "?" in request.url else ""
+    url = to_url(request)
+    scheme = url.scheme if url is not None else "http"
+    server = (
+        None
+        if url is None or url.hostname is None
+        else (url.hostname, url.port or (443 if scheme == "https" else 80))
+    )
+    remote = request.remote_address
+    scope: dict[str, Any] = {
+        "type": "http",
+        "asgi": _ASGI,
+        "http_version": "1.1",
+        "method": request.method,
+        "scheme": scheme,
+        "path": decode_path(original),
+        "raw_path": original.encode("latin-1", "replace"),
+        "root_path": decode_path(root),
+        "query_string": query.encode("latin-1", "replace"),
+        "headers": [
+            (name.encode("latin-1"), value.encode("latin-1"))
+            for name, value in request.headers.items()
+        ],
+        "client": None if remote is None else (remote, 0),
+        "server": server,
+        "extensions": {},
+    }
+    if state is not None:
+        scope["state"] = dict(state)
+    return scope
+
+
+class _Exchange:
+    """One call of the application: ``receive`` reads the request body,
+    ``send`` hands the response over."""
+
+    def __init__(self, body: AsyncIterator[bytes] | None) -> None:
+        loop = asyncio.get_running_loop()
+        self._body = body
+        self._body_done = False
+        self.finished = asyncio.Event()
+        self.started: asyncio.Future[tuple[int, list[tuple[str, str]]]] = loop.create_future()
+        self.chunks: asyncio.Queue[bytes | None] = asyncio.Queue(_QUEUED_CHUNKS)
+
+    async def receive(self) -> Message:
+        if not self._body_done:
+            if self._body is not None:
+                try:
+                    chunk = await anext(self._body)
+                except StopAsyncIteration:
+                    pass
+                else:
+                    return {"type": "http.request", "body": chunk, "more_body": True}
+            self._body_done = True
+            return {"type": "http.request", "body": b"", "more_body": False}
+        await self.finished.wait()
+        return {"type": "http.disconnect"}
+
+    async def send(self, message: Message) -> None:
+        if message["type"] == "http.response.start" and not self.started.done():
+            headers: list[tuple[bytes, bytes]] = message.get("headers", [])
+            self.started.set_result(
+                (
+                    message["status"],
+                    [(name.decode("latin-1"), value.decode("latin-1")) for name, value in headers],
+                )
+            )
+        elif message["type"] == "http.response.body" and not self.finished.is_set():
+            chunk: bytes = message.get("body", b"")
+            if chunk:
+                await self.chunks.put(chunk)
+            if not message.get("more_body", False):
+                self.finished.set()
+                await self.chunks.put(None)
+
+
+async def _body(exchange: _Exchange, task: asyncio.Task[None]) -> AsyncIterator[bytes]:
+    try:
+        while True:
+            getting = asyncio.ensure_future(exchange.chunks.get())
+            await asyncio.wait((getting, task), return_when=asyncio.FIRST_COMPLETED)
+            if not getting.done():
+                getting.cancel()
+                # The application ended (or raised) before ending the body.
+                task.result()
+                raise AsgiNoResponseError("the ASGI application did not end the response")
+            chunk = getting.result()
+            if chunk is None:
+                return
+            yield chunk
+    finally:
+        exchange.finished.set()
+        if not task.done():
+            task.cancel()
+
+
+async def _call(
+    app: AsgiApplication, scope: dict[str, Any], body: AsyncIterator[bytes] | None
+) -> WebResponse:
+    exchange = _Exchange(body)
+    task = asyncio.ensure_future(app(scope, exchange.receive, exchange.send))
+    try:
+        await asyncio.wait((exchange.started, task), return_when=asyncio.FIRST_COMPLETED)
+    except asyncio.CancelledError:
+        exchange.finished.set()
+        task.cancel()
+        raise
+    if not exchange.started.done():
+        task.result()
+        raise AsgiNoResponseError("the ASGI application returned without a response")
+    status, headers = exchange.started.result()
+    return WebResponse(_body(exchange, task), status=status, headers=headers)
+
+
+def from_asgi(
+    app: AsgiApplication, *, state: Mapping[str, Any] | None = None
+) -> Effect[HttpServerResponse, HttpServerError, HttpServerRequest]:
+    """An app answering with the ASGI application ``app`` (Effect's
+    ``fromWebHandler`` for ASGI). Mounted under a router prefix
+    (``router.prefix_route``), the prefix is the scope's ``root_path``;
+    ``state`` is the scope's ``state`` (what ``lifespan`` gives).
+    Interrupting the app cancels the call."""
+
+    def run(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, HttpServerError]:
+        request = fiber._context.get_unsafe(HttpServerRequest)
+        controller = AbortController()
+        match request_to_web(request, signal=controller.signal, context=fiber._context):
+            case Err(reason):
+                return fail(HttpServerError(reason))
+            case Ok(web):
+                pass
+        scope = _scope(request, state)
+        body = None if web.body is None else web.chunks()
+
+        async def call() -> WebResponse:
+            try:
+                return await _call(app, scope, body)
+            except asyncio.CancelledError:
+                controller.abort()
+                raise
+
+        def on_error(cause: Exception) -> HttpServerError:
+            return HttpServerError(InternalError(request, "HttpApp.fromAsgi: Error in app", cause))
+
+        return try_async(call, on_error).map(response_from_web)
+
+    return _WithFiber(run)
+
+
+@dataclass(frozen=True)
+class AsgiLifespanError(TaggedError):
+    """The application's lifespan startup failed."""
+
+    message: str
+
+
+class _Lifespan:
+    """A running ``lifespan`` scope."""
+
+    def __init__(self, app: AsgiApplication) -> None:
+        self.state: dict[str, Any] = {}
+        self._inbox: asyncio.Queue[Message] = asyncio.Queue()
+        self._outbox: asyncio.Queue[Message] = asyncio.Queue()
+        scope = {"type": "lifespan", "asgi": _ASGI, "state": self.state}
+        self._task = asyncio.ensure_future(app(scope, self._inbox.get, self._outbox.put))
+        self._supported = True
+
+    async def _reply(self) -> Message | None:
+        """The application's next message; ``None`` once it has ended."""
+        replying = asyncio.ensure_future(self._outbox.get())
+        await asyncio.wait((replying, self._task), return_when=asyncio.FIRST_COMPLETED)
+        if replying.done():
+            return replying.result()
+        replying.cancel()
+        return None
+
+    async def startup(self) -> None:
+        await self._inbox.put({"type": "lifespan.startup"})
+        reply = await self._reply()
+        if reply is None:
+            # An application without lifespan support raises or returns.
+            self._supported = False
+            if not self._task.cancelled():
+                self._task.exception()
+            return
+        if reply["type"] == "lifespan.startup.failed":
+            raise AsgiLifespanError(reply.get("message", ""))
+
+    async def shutdown(self) -> None:
+        if self._supported and not self._task.done():
+            await self._inbox.put({"type": "lifespan.shutdown"})
+            await self._reply()
+        if not self._task.done():
+            self._task.cancel()
+
+
+def lifespan(app: AsgiApplication) -> Effect[dict[str, Any], AsgiLifespanError, Scope]:
+    """Start ``app``'s lifespan (its startup handlers) and shut it down when
+    the scope closes; succeeds with the lifespan ``state`` to pass to
+    ``from_asgi``. An application without lifespan support starts at once."""
+
+    async def start() -> _Lifespan:
+        running = _Lifespan(app)
+        await running.startup()
+        return running
+
+    def on_error(cause: Exception) -> AsgiLifespanError:
+        return cause if isinstance(cause, AsgiLifespanError) else AsgiLifespanError(str(cause))
+
+    return acquire_release(
+        try_async(start, on_error), lambda running, _exit: from_async(running.shutdown)
+    ).map(lambda running: running.state)

pyfect/http/asgi/_scope.py

@@ -0,0 +1,86 @@
+"""What a request's ASGI scope says: its target relative to the mount
+point (``root_path``), absolute URL, headers and peer."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from pyfect.http._authority import (
+    LOCALHOST,
+    Authority,
+    OriginForm,
+    absolute_url,
+    parse_authority,
+    parse_origin_form,
+)
+from pyfect.http.asgi._types import Scope
+
+# What ``quote`` keeps of a path: RFC 3986 ``pchar``s and ``/``.
+_PATH_SAFE = "/:@!$&'()*+,;=-._~%"
+
+
+def _strip_prefix(path: str, prefix: str) -> str:
+    if prefix and path.startswith(prefix) and path[len(prefix) : len(prefix) + 1] in ("", "/"):
+        return path[len(prefix) :] or "/"
+    return path
+
+
+def target(scope: Scope) -> OriginForm | None:
+    """The path and query, without the ``root_path`` the app is mounted at
+    (servers and Starlette's ``Mount`` keep it in ``path``); ``None`` when
+    the path has no leading ``/`` (a server may hand on a raw target)."""
+    root = quote(scope.get("root_path", ""), safe=_PATH_SAFE)
+    raw: bytes | None = scope.get("raw_path")
+    path = raw.decode("latin-1") if raw else quote(scope["path"], safe=_PATH_SAFE)
+    path = _strip_prefix(path.split("?", 1)[0], root) or "/"
+    query: bytes = scope.get("query_string", b"")
+    return parse_origin_form(f"{path}?{query.decode('latin-1')}" if query else path)
+
+
+def header_lines(scope: Scope) -> list[tuple[str, str]]:
+    pairs: list[tuple[bytes, bytes]] = scope.get("headers", [])
+    return [(name.decode("latin-1").lower(), value.decode("latin-1")) for name, value in pairs]
+
+
+def _host(scope: Scope, lines: list[tuple[str, str]]) -> Authority:
+    """The ``host`` header, or the server's address when there is none or
+    it is no authority (the routed path comes from the scope alone)."""
+    for name, value in lines:
+        if name == "host":
+            authority = parse_authority(value)
+            if authority is not None:
+                return authority
+            break
+    server: tuple[str, int | None] | None = scope.get("server")
+    if server is None:
+        return LOCALHOST
+    host, port = server
+    host = f"[{host}]" if ":" in host else host
+    return parse_authority(host if port is None else f"{host}:{port}") or LOCALHOST
+
+
+def url(scope: Scope, lines: list[tuple[str, str]]) -> str | None:
+    """The absolute URL: ``http`` or ``https`` (``ws`` and ``wss`` too);
+    ``None`` when the target is not origin-form (answered with 400)."""
+    scheme = "https" if scope.get("scheme") in ("https", "wss") else "http"
+    origin = target(scope)
+    return None if origin is None else absolute_url(scheme, _host(scope, lines), origin)
+
+
+def remote_address(scope: Scope) -> str | None:
+    client: tuple[str, int] | None = scope.get("client")
+    return None if client is None else client[0]
+
+
+def has_body(scope: Scope, lines: list[tuple[str, str]]) -> bool:
+    """Whether the request has a body: framed by its headers over HTTP/1,
+    possible on any request with content over HTTP/2 and 3."""
+    for name, value in lines:
+        if name == "transfer-encoding":
+            return True
+        if name == "content-length":
+            return value.strip() != "0"
+    return scope.get("http_version", "1.1") not in ("1.0", "1.1") and scope.get("method") not in (
+        "GET",
+        "HEAD",
+    )

pyfect/http/asgi/_serve.py

@@ -0,0 +1,72 @@
+"""Requests of an ASGI connection (``http`` and ``websocket`` scopes)
+answered by an app, each on its own fiber."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyfect._core import Effect
+from pyfect.context import Context
+from pyfect.http.abort import AbortController
+from pyfect.http.asgi._http import serve_http
+from pyfect.http.asgi._types import Receive, Scope, Send
+from pyfect.http.asgi._web_socket import serve_websocket
+from pyfect.http.http_effect import HttpMiddleware
+from pyfect.http.server_response import HttpServerResponse
+from pyfect.http.web_handler import Fork, to_web_handler_with
+
+
+class UnsupportedScopeError(RuntimeError):
+    """An ASGI scope type the app does not serve."""
+
+
+class AsgiHandler:
+    """An ASGI app answering ``http`` and ``websocket`` scopes with
+    ``app``: ``fork`` starts each request's fiber with ``context`` and the
+    request."""
+
+    __slots__ = ("_app", "_context", "_fork", "_middleware", "_open", "_web")
+
+    def __init__(
+        self,
+        app: Effect[HttpServerResponse, Any, Any],
+        middleware: HttpMiddleware | None,
+        context: Context[Any],
+        fork: Fork,
+    ) -> None:
+        self._app = app
+        self._middleware = middleware
+        self._context = context
+        self._fork = fork
+        self._web = to_web_handler_with(context, fork=fork)(app, middleware)
+        self._open: set[AbortController] = set()
+
+    def end_responses(self) -> None:
+        """Abort every ``http`` request in flight, on the server's loop: a
+        handler still running is interrupted, and a streamed body ends where
+        it is. A server calls it once ``graceful_shutdown_timeout`` has
+        passed, so an endless body (SSE) cannot hold its shutdown open."""
+        for controller in tuple(self._open):
+            controller.abort()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        match scope["type"]:
+            case "http":
+                controller = AbortController()
+                self._open.add(controller)
+                try:
+                    await serve_http(self._web, scope, receive, send, controller)
+                finally:
+                    self._open.discard(controller)
+            case "websocket":
+                await serve_websocket(
+                    scope,
+                    receive,
+                    send,
+                    app=self._app,
+                    middleware=self._middleware,
+                    context=self._context,
+                    fork=self._fork,
+                )
+            case other:
+                raise UnsupportedScopeError(f"unsupported ASGI scope type: {other!r}")

pyfect/http/asgi/_types.py

@@ -0,0 +1,13 @@
+"""The ASGI 3 interface (asgiref's ``Scope``, ``Receive``, ``Send`` and
+``ASGI3Application``), loosely typed as servers send it."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any
+
+type Scope = MutableMapping[str, Any]
+type Message = MutableMapping[str, Any]
+type Receive = Callable[[], Awaitable[Message]]
+type Send = Callable[[Message], Awaitable[None]]
+type AsgiApplication = Callable[[Scope, Receive, Send], Awaitable[None]]