hayate 0.3.0__py3-none-any.whl

hayate/__init__.py

@@ -0,0 +1,46 @@
+"""hayate — a web-standards-first Python web framework, inspired by Hono."""
+
+from .abort import AbortError, AbortSignal
+from .app import ErrorHandler, Handler, Hayate, Middleware
+from .body import BodyInit
+from .context import Context, ExecutionContext, Next
+from .exceptions import HTTPException, problem
+from .formdata import File, FormData
+from .headers import Headers
+from .request import HayateRequest, Request
+from .response import Response
+from .url import URL, URLSearchParams
+from .urlpattern import URLPattern, URLPatternResult
+from .validator import validator
+from .websocket import WebSocket, WebSocketClosed
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "URL",
+    "AbortError",
+    "AbortSignal",
+    "BodyInit",
+    "Context",
+    "ErrorHandler",
+    "ExecutionContext",
+    "File",
+    "FormData",
+    "HTTPException",
+    "Handler",
+    "Hayate",
+    "HayateRequest",
+    "Headers",
+    "Middleware",
+    "Next",
+    "Request",
+    "Response",
+    "URLPattern",
+    "URLPatternResult",
+    "URLSearchParams",
+    "WebSocket",
+    "WebSocketClosed",
+    "__version__",
+    "problem",
+    "validator",
+]

hayate/abort.py

@@ -0,0 +1,62 @@
+"""Minimal ``AbortSignal``, mirroring the DOM surface a server needs.
+
+``request.signal`` lets handlers observe client disconnects. By default
+hayate does not cancel handlers on abort (same safe default as Hono);
+cancellation is opt-in via middleware.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+_logger = logging.getLogger("hayate")
+
+
+class AbortError(Exception):
+    """Raised by ``AbortSignal.raise_if_aborted()`` (DOMException "AbortError")."""
+
+
+class AbortSignal:
+    __slots__ = ("_aborted", "_callbacks", "_reason")
+
+    def __init__(self) -> None:
+        self._aborted = False
+        self._reason: Any = None
+        self._callbacks: list[Callable[[], None]] = []
+
+    @property
+    def aborted(self) -> bool:
+        return self._aborted
+
+    @property
+    def reason(self) -> Any:
+        return self._reason
+
+    def add_listener(self, callback: Callable[[], None]) -> None:
+        """Register an abort callback (fires immediately if already aborted)."""
+        if self._aborted:
+            callback()
+            return
+        self._callbacks.append(callback)
+
+    def raise_if_aborted(self) -> None:
+        """Fetch ``throwIfAborted()``."""
+        if self._aborted:
+            raise AbortError(self._reason if self._reason is not None else "aborted")
+
+    def _abort(self, reason: Any = None) -> None:
+        if self._aborted:
+            return
+        self._aborted = True
+        self._reason = reason
+        callbacks, self._callbacks = self._callbacks, []
+        for callback in callbacks:
+            try:
+                callback()
+            except Exception:
+                _logger.exception("abort listener raised")
+
+    def __repr__(self) -> str:
+        return f"AbortSignal(aborted={self._aborted!r})"

hayate/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Runtime adapters. The core never imports these at module level."""
+
+from .asgi import ASGIAdapter
+
+__all__ = ["ASGIAdapter"]

hayate/adapters/asgi.py

@@ -0,0 +1,220 @@
+"""ASGI adapter: translates ASGI ``http`` / ``lifespan`` events to ``app.fetch()``.
+
+Users never see ``scope`` / ``receive`` / ``send`` — the ``Hayate`` app is
+itself an ASGI callable that delegates here, so ``uvicorn main:app`` works
+out of the box.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from ..abort import AbortSignal
+from ..context import Context
+from ..headers import Headers
+from ..request import HayateRequest, Request
+from ..router import WEBSOCKET_METHOD
+from ..url import URL
+from ..websocket import WebSocket, WebSocketClosed
+
+if TYPE_CHECKING:
+    from ..app import Hayate
+    from ..response import Response
+
+_logger = logging.getLogger("hayate.asgi")
+
+type Receive = Callable[[], Awaitable[dict[str, Any]]]
+type Send = Callable[[dict[str, Any]], Awaitable[None]]
+
+_DEFAULT_SCHEME_PORTS = {"http": "80", "https": "443", "ws": "80", "wss": "443"}
+# pchar set — keep valid path characters intact when re-encoding a decoded path.
+_PATH_SAFE = "/:@!$&'()*+,;=~-._"
+
+
+async def _request_body(receive: Receive, signal: AbortSignal) -> AsyncIterator[bytes]:
+    while True:
+        message = await receive()
+        if message["type"] == "http.request":
+            chunk = message.get("body", b"")
+            if chunk:
+                yield chunk
+            if not message.get("more_body", False):
+                return
+        elif message["type"] == "http.disconnect":
+            signal._abort("client disconnected")
+            return
+
+
+async def _call_hook(hook: Callable[[], Any]) -> None:
+    result = hook()
+    if inspect.isawaitable(result):
+        await result
+
+
+class ASGIAdapter:
+    __slots__ = ("_app",)
+
+    def __init__(self, app: Hayate) -> None:
+        self._app = app
+
+    async def __call__(self, scope: dict[str, Any], receive: Receive, send: Send) -> None:
+        kind = scope["type"]
+        if kind == "http":
+            await self._http(scope, receive, send)
+        elif kind == "websocket":
+            await self._websocket(scope, receive, send)
+        elif kind == "lifespan":
+            await self._lifespan(receive, send)
+        else:
+            raise RuntimeError(f"unsupported ASGI scope type: {kind!r}")
+
+    # -- http -----------------------------------------------------------------
+
+    async def _http(self, scope: dict[str, Any], receive: Receive, send: Send) -> None:
+        raw_headers: list[tuple[bytes, bytes]] = scope.get("headers", [])
+        host: bytes | None = None
+        expects_body = False
+        for name, value in raw_headers:
+            if name == b"host":
+                if host is None:
+                    host = value
+            elif name == b"content-length":
+                expects_body = value not in (b"", b"0")
+            elif name == b"transfer-encoding":
+                expects_body = True
+        if expects_body:
+            signal: AbortSignal | None = AbortSignal()
+            body: Any = _request_body(receive, signal)
+        else:
+            # No content-length / transfer-encoding means no request body
+            # (RFC 9112) — a null body per Fetch; skip stream and signal.
+            signal = None
+            body = None
+        request = Request(
+            _build_url(scope, host),
+            method=scope["method"],
+            headers=Headers._from_wire(raw_headers, guard="immutable"),
+            body=body,
+            signal=signal,
+        )
+        response = await self._app.fetch(request)
+        try:
+            await _send_response(scope, send, response)
+        finally:
+            background = response._background
+            if background is not None:
+                await background._drain()
+
+    # -- websocket ---------------------------------------------------------------
+
+    async def _websocket(self, scope: dict[str, Any], receive: Receive, send: Send) -> None:
+        raw_path = scope.get("raw_path")
+        if raw_path:
+            path = raw_path.decode("latin-1")
+        else:
+            path = quote(scope.get("path", "/"), safe=_PATH_SAFE)
+        matched = self._app._router.match(WEBSOCKET_METHOD, path)
+        if matched is None:
+            await receive()  # websocket.connect
+            await send({"type": "websocket.close", "code": 4404, "reason": "not found"})
+            return
+        route, params = matched
+        raw_headers: list[tuple[bytes, bytes]] = scope.get("headers", [])
+        host: bytes | None = None
+        for name, value in raw_headers:
+            if name == b"host":
+                host = value
+                break
+        request = Request(
+            _build_url(scope, host),
+            headers=Headers._from_wire(raw_headers, guard="immutable"),
+        )
+        hayate_request = HayateRequest(request)
+        hayate_request._params = params
+        c = Context(hayate_request, self._app._env, None)
+        ws = WebSocket(receive, send)
+        await ws.accept()
+        try:
+            await route.handler(c, ws)
+        except WebSocketClosed:
+            pass
+        except Exception:
+            _logger.exception("websocket handler failed on %s", path)
+            await ws.close(1011, "internal error")
+            return
+        await ws.close()
+
+    # -- lifespan ----------------------------------------------------------------
+
+    async def _lifespan(self, receive: Receive, send: Send) -> None:
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                try:
+                    for hook in self._app._on_start:
+                        await _call_hook(hook)
+                except Exception as exc:
+                    await send({"type": "lifespan.startup.failed", "message": str(exc)})
+                    return
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                try:
+                    for hook in self._app._on_stop:
+                        await _call_hook(hook)
+                except Exception as exc:
+                    await send({"type": "lifespan.shutdown.failed", "message": str(exc)})
+                    return
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+
+def _build_url(scope: dict[str, Any], host_header: bytes | None) -> URL:
+    scheme = scope.get("scheme", "http")
+    if host_header:
+        host = host_header.decode("latin-1")
+    else:
+        server = scope.get("server")
+        if server:
+            host = server[0]
+            port = server[1]
+            if port is not None and str(port) != _DEFAULT_SCHEME_PORTS.get(scheme):
+                host = f"{host}:{port}"
+        else:
+            host = "localhost"
+    raw_path = scope.get("raw_path")
+    if raw_path:
+        path = raw_path.decode("latin-1")
+    else:
+        path = quote(scope.get("path", "/"), safe=_PATH_SAFE)
+    query = scope.get("query_string", b"").decode("latin-1")
+    return URL._from_server(scheme, host, path, query)
+
+
+async def _send_response(scope: dict[str, Any], send: Send, response: Response) -> None:
+    status = response.status
+    body = response.body
+    headers = [
+        (name.encode("latin-1"), value.encode("latin-1")) for name, value in response.headers.raw()
+    ]
+    body_allowed = status >= 200 and status not in (204, 304)
+    if body_allowed and not response.headers.has("content-length"):
+        if isinstance(body, bytes):
+            headers.append((b"content-length", str(len(body)).encode("latin-1")))
+        elif body is None:
+            headers.append((b"content-length", b"0"))
+        # Stream bodies get no content-length; the server frames them.
+    await send({"type": "http.response.start", "status": status, "headers": headers})
+    suppress_body = scope["method"] == "HEAD" or not body_allowed
+    if suppress_body or body is None:
+        await send({"type": "http.response.body", "body": b"", "more_body": False})
+        return
+    if isinstance(body, bytes):
+        await send({"type": "http.response.body", "body": body, "more_body": False})
+        return
+    async for chunk in body:
+        await send({"type": "http.response.body", "body": bytes(chunk), "more_body": True})
+    await send({"type": "http.response.body", "body": b"", "more_body": False})

hayate/adapters/aws.py

@@ -0,0 +1,116 @@
+"""AWS Lambda adapter (Function URLs / API Gateway HTTP API, payload v2.0).
+
+    from hayate.adapters.aws import to_lambda
+    from app import app
+
+    handler = to_lambda(app)
+
+Each invocation runs the app on a fresh event loop — the standard
+pattern for sync Lambda handlers. Response bodies are emitted as text
+when the content-type is textual and there is no content-encoding;
+otherwise they are base64-encoded. ``Set-Cookie`` values map to the
+payload's ``cookies`` list so they are never comma-joined.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from typing import TYPE_CHECKING, Any
+
+from ..headers import Headers
+from ..request import Request
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ..app import Hayate
+
+_TEXT_EXACT = {
+    "application/json",
+    "application/javascript",
+    "application/xml",
+    "application/manifest+json",
+    "image/svg+xml",
+}
+
+
+def _is_textual(content_type: str) -> bool:
+    base = content_type.partition(";")[0].strip().lower()
+    return (
+        base.startswith("text/")
+        or base in _TEXT_EXACT
+        or base.endswith("+json")
+        or base.endswith("+xml")
+    )
+
+
+async def _handle(app: Hayate, event: dict[str, Any]) -> dict[str, Any]:
+    http = event["requestContext"]["http"]
+    method = http.get("method", "GET")
+    path = event.get("rawPath") or "/"
+    query = event.get("rawQueryString") or ""
+    header_map: dict[str, str] = event.get("headers") or {}
+    pairs = list(header_map.items())
+    request_cookies = event.get("cookies")
+    if request_cookies:
+        pairs.append(("cookie", "; ".join(request_cookies)))
+
+    host = header_map.get("host") or event["requestContext"].get("domainName", "lambda")
+    target = f"https://{host}{path}"
+    if query:
+        target += f"?{query}"
+
+    raw_body = event.get("body")
+    body: bytes | str | None
+    if raw_body is None:
+        body = None
+    elif event.get("isBase64Encoded"):
+        body = base64.b64decode(raw_body)
+    else:
+        body = raw_body
+
+    request = Request(target, method=method, headers=Headers(pairs, guard="immutable"), body=body)
+    response = await app.fetch(request)
+    background = response._background
+    if background is not None:
+        await background._drain()
+
+    payload = response.body
+    if payload is not None and not isinstance(payload, bytes):
+        payload = await response.bytes()
+
+    headers: dict[str, str] = {}
+    set_cookies: list[str] = []
+    for name, value in response.headers.raw():
+        if name == "set-cookie":
+            set_cookies.append(value)
+        elif name in headers:
+            headers[name] = f"{headers[name]}, {value}"
+        else:
+            headers[name] = value
+
+    result: dict[str, Any] = {"statusCode": response.status, "headers": headers}
+    if set_cookies:
+        result["cookies"] = set_cookies
+    if payload is None:
+        result["body"] = ""
+        result["isBase64Encoded"] = False
+    else:
+        content_type = response.headers.get("content-type") or ""
+        if response.headers.has("content-encoding") or not _is_textual(content_type):
+            result["body"] = base64.b64encode(payload).decode("ascii")
+            result["isBase64Encoded"] = True
+        else:
+            result["body"] = payload.decode("utf-8")
+            result["isBase64Encoded"] = False
+    return result
+
+
+def to_lambda(app: Hayate) -> Callable[[dict[str, Any], Any], dict[str, Any]]:
+    """Build a synchronous Lambda handler: ``handler = to_lambda(app)``."""
+
+    def handler(event: dict[str, Any], context: Any) -> dict[str, Any]:
+        return asyncio.run(_handle(app, event))
+
+    return handler

hayate/adapters/workers.py

@@ -0,0 +1,94 @@
+"""Cloudflare Python Workers adapter.
+
+Usage — the entry module of a Python Worker:
+
+    from hayate.adapters.workers import to_workers
+    from app import app
+
+    Default = to_workers(app)
+
+The Workers runtime modules (``workers``, ``js``) exist only inside
+Pyodide, so they are imported inside ``to_workers()``; the translation
+helpers are plain Python and unit-testable anywhere.
+
+Unlike the official FastAPI integration (JS Request -> ASGI -> Starlette
+Request), this is a single-step translation: JS Request -> hayate
+Request, same conceptual model on both sides.
+
+v0.2 scope: bodies are buffered across the FFI boundary (streaming
+bridges need on-platform verification — docs/research/cloudflare.md §5)
+and the abort signal is not yet bridged.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from ..context import ExecutionContext
+from ..headers import Headers
+from ..request import Request
+
+if TYPE_CHECKING:
+    from ..app import Hayate
+    from ..response import Response
+
+
+def _js_headers_to_pairs(js_headers: Any) -> list[tuple[str, str]]:
+    return [(str(entry[0]), str(entry[1])) for entry in js_headers.entries()]
+
+
+async def _to_hayate_request(js_request: Any) -> Request:
+    body: bytes | None = None
+    if js_request.body is not None:
+        buffer = await js_request.arrayBuffer()
+        data = buffer.to_py() if hasattr(buffer, "to_py") else buffer
+        body = bytes(data) or None
+    return Request(
+        str(js_request.url),
+        method=str(js_request.method),
+        headers=Headers(_js_headers_to_pairs(js_request.headers), guard="immutable"),
+        body=body,
+    )
+
+
+async def _to_workers_response(
+    response: Response, workers_response_cls: Any, js_headers_cls: Any
+) -> Any:
+    body = response.body
+    if body is not None and not isinstance(body, bytes):
+        body = await response.bytes()  # buffered crossing in v0.2
+    js_headers = js_headers_cls.new()
+    for name, value in response.headers.raw():
+        js_headers.append(name, value)
+    return workers_response_cls(body, status=response.status, headers=js_headers)
+
+
+class _WorkersExecutionContext(ExecutionContext):
+    """Forwards ``wait_until`` to the Workers runtime (``ctx.waitUntil``)."""
+
+    __slots__ = ("_js_ctx",)
+
+    def __init__(self, js_ctx: Any) -> None:
+        super().__init__()
+        self._js_ctx = js_ctx
+
+    def wait_until(self, awaitable: Any) -> None:
+        # Pyodide converts asyncio futures to JS promises at the boundary.
+        self._js_ctx.waitUntil(asyncio.ensure_future(awaitable))
+
+
+def to_workers(app: Hayate) -> type:
+    """Build the Workers entrypoint class: ``Default = to_workers(app)``."""
+    from js import Headers as JsHeaders
+    from workers import Response as WorkersResponse
+    from workers import WorkerEntrypoint
+
+    class Default(WorkerEntrypoint):
+        async def fetch(self, request: Any) -> Any:
+            hayate_request = await _to_hayate_request(request)
+            exec_ctx = _WorkersExecutionContext(self.ctx)
+            response = await app.fetch(hayate_request, env=self.env, ctx=exec_ctx)
+            return await _to_workers_response(response, WorkersResponse, JsHeaders)
+
+    return Default