avalon 0.2.0__py3-none-any.whl

avalon/__init__.py

@@ -0,0 +1,32 @@
+"""Avalon: a small, dependency-free real-time web framework for asyncio.
+
+HTTP routes, WebSockets and broadcast channels in one tiny package.
+"""
+
+from .app import Avalon, to_response
+from .channels import Hub
+from .client import HandshakeError, connect
+from .http import HTMLResponse, HTTPError, JSONResponse, Request, Response
+from .routing import Route, Router
+from .websocket import Opcode, WebSocket, WebSocketClosed
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Avalon",
+    "HTMLResponse",
+    "HTTPError",
+    "HandshakeError",
+    "Hub",
+    "JSONResponse",
+    "Opcode",
+    "Request",
+    "Response",
+    "Route",
+    "Router",
+    "WebSocket",
+    "WebSocketClosed",
+    "connect",
+    "to_response",
+    "__version__",
+]

avalon/app.py

@@ -0,0 +1,220 @@
+"""The :class:`Avalon` application: routing, dispatch and the asyncio server."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from typing import Any, Awaitable, Callable, TypeVar
+
+from .channels import Hub
+from .http import HTTPError, JSONResponse, Request, Response, read_request
+from .routing import Router
+from .websocket import WebSocket, WebSocketClosed, accept_key
+
+__all__ = ["Avalon"]
+
+logger = logging.getLogger("avalon")
+
+F = TypeVar("F", bound=Callable[..., Any])
+HTTPHandler = Callable[[Request], Any]
+WebSocketHandler = Callable[[WebSocket], Awaitable[None]]
+
+
+def to_response(result: Any) -> Response:
+    """Coerce a handler's return value into a :class:`Response`.
+
+    ``Response`` is passed through; ``dict``/``list`` become JSON; ``str`` is
+    ``text/plain``; ``bytes`` is ``application/octet-stream``; ``None`` is an
+    empty ``204 No Content``.
+    """
+    if isinstance(result, Response):
+        return result
+    if isinstance(result, (dict, list)):
+        return JSONResponse(result)
+    if isinstance(result, str):
+        return Response(result)
+    if isinstance(result, (bytes, bytearray)):
+        return Response(bytes(result), media_type="application/octet-stream")
+    if result is None:
+        return Response(status=204)
+    raise TypeError(f"cannot convert {type(result).__name__} to a Response")
+
+
+class Avalon:
+    """A real-time web application.
+
+    Register HTTP handlers with :meth:`route` (or :meth:`get`/:meth:`post`)
+    and WebSocket handlers with :meth:`websocket`, then call :meth:`run`.
+    Handlers may be plain functions or coroutines. Use :attr:`hub` to
+    broadcast messages to groups of connected sockets.
+
+    Example::
+
+        app = Avalon()
+
+        @app.get("/hello/{name}")
+        def hello(request):
+            return {"hello": request.params["name"]}
+
+        @app.websocket("/ws/{room}")
+        async def room(ws):
+            app.hub.join(ws.params["room"], ws)
+            async for msg in ws:
+                await app.hub.broadcast(ws.params["room"], msg)
+    """
+
+    def __init__(self, *, keep_alive_timeout: float = 15.0) -> None:
+        self.router = Router()
+        self.hub = Hub()
+        self.sockets: set[WebSocket] = set()
+        """WebSocket connections currently being served."""
+        self.keep_alive_timeout = keep_alive_timeout
+
+    # -- registration ----------------------------------------------------
+
+    def route(self, path: str, methods: tuple[str, ...] | list[str] = ("GET",)) -> Callable[[F], F]:
+        """Decorator registering an HTTP handler for ``path`` and ``methods``."""
+
+        def decorator(func: F) -> F:
+            self.router.add(path, func, methods, kind="http")
+            return func
+
+        return decorator
+
+    def get(self, path: str) -> Callable[[F], F]:
+        """Shorthand for ``route(path, methods=["GET"])``."""
+        return self.route(path, ("GET",))
+
+    def post(self, path: str) -> Callable[[F], F]:
+        """Shorthand for ``route(path, methods=["POST"])``."""
+        return self.route(path, ("POST",))
+
+    def websocket(self, path: str) -> Callable[[F], F]:
+        """Decorator registering an ``async def handler(ws)`` for ``path``."""
+
+        def decorator(func: F) -> F:
+            if not inspect.iscoroutinefunction(func):
+                raise TypeError("WebSocket handlers must be async functions")
+            self.router.add(path, func, kind="websocket")
+            return func
+
+        return decorator
+
+    # -- dispatch --------------------------------------------------------
+
+    async def dispatch(self, request: Request) -> Response:
+        """Route ``request`` to its handler and return the response.
+
+        Never raises: ``HTTPError`` becomes a JSON error response and any
+        other exception becomes ``500 Internal Server Error``.
+        """
+        try:
+            route, request.params = self.router.resolve(request.path, request.method)
+            result = route.handler(request)
+            if inspect.isawaitable(result):
+                result = await result
+            return to_response(result)
+        except HTTPError as exc:
+            return JSONResponse({"error": exc.detail}, status=exc.status)
+        except Exception:
+            logger.exception("unhandled error in %s %s", request.method, request.path)
+            return JSONResponse({"error": "Internal Server Error"}, status=500)
+
+    async def _serve_websocket(
+        self, request: Request, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            route, params = self.router.resolve(request.path, kind="websocket")
+            key = request.headers.get("sec-websocket-key")
+            if not key or request.headers.get("sec-websocket-version") != "13":
+                raise HTTPError(400, "invalid WebSocket handshake")
+        except HTTPError as exc:
+            writer.write(JSONResponse({"error": exc.detail}, status=exc.status).encode())
+            await writer.drain()
+            return
+
+        writer.write(
+            (
+                "HTTP/1.1 101 Switching Protocols\r\n"
+                "Upgrade: websocket\r\n"
+                "Connection: Upgrade\r\n"
+                f"Sec-WebSocket-Accept: {accept_key(key)}\r\n\r\n"
+            ).encode("latin-1")
+        )
+        await writer.drain()
+
+        ws = WebSocket(reader, writer, path=request.path, params=params, headers=request.headers)
+        self.sockets.add(ws)
+        try:
+            await route.handler(ws)
+        except WebSocketClosed:
+            pass
+        except Exception:
+            logger.exception("unhandled error in WebSocket handler %s", request.path)
+            await ws.close(1011, "internal error")
+        finally:
+            self.sockets.discard(ws)
+            self.hub.leave_all(ws)
+            await ws.close()
+
+    async def handle_connection(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        """Serve one TCP connection (HTTP keep-alive or a WebSocket upgrade)."""
+        try:
+            while True:
+                try:
+                    request = await asyncio.wait_for(read_request(reader), self.keep_alive_timeout)
+                except asyncio.TimeoutError:
+                    break
+                except HTTPError as exc:
+                    writer.write(JSONResponse({"error": exc.detail}, status=exc.status).encode())
+                    await writer.drain()
+                    break
+                if request is None:
+                    break
+                if request.is_websocket:
+                    await self._serve_websocket(request, reader, writer)
+                    return
+                response = await self.dispatch(request)
+                keep_alive = request.keep_alive
+                data = response.encode(keep_alive)
+                if request.method == "HEAD" and response.body:
+                    data = data[: -len(response.body)]
+                writer.write(data)
+                await writer.drain()
+                if not keep_alive:
+                    break
+        except (ConnectionError, asyncio.IncompleteReadError):
+            pass
+        finally:
+            if not writer.is_closing():
+                writer.close()
+            try:
+                await writer.wait_closed()
+            except (ConnectionError, RuntimeError):
+                pass
+
+    # -- serving ---------------------------------------------------------
+
+    async def serve(self, host: str = "127.0.0.1", port: int = 8000) -> asyncio.Server:
+        """Start listening and return the running :class:`asyncio.Server`.
+
+        Pass ``port=0`` to pick a free port; read it back from
+        ``server.sockets[0].getsockname()[1]``.
+        """
+        return await asyncio.start_server(self.handle_connection, host, port)
+
+    def run(self, host: str = "127.0.0.1", port: int = 8000) -> None:
+        """Serve forever (blocking) until interrupted with Ctrl+C."""
+
+        async def main() -> None:
+            server = await self.serve(host, port)
+            addr = server.sockets[0].getsockname()
+            print(f"Avalon running on http://{addr[0]}:{addr[1]} (Ctrl+C to quit)")
+            async with server:
+                await server.serve_forever()
+
+        try:
+            asyncio.run(main())
+        except KeyboardInterrupt:
+            pass

avalon/channels.py

@@ -0,0 +1,75 @@
+"""Named broadcast channels (pub/sub) over WebSocket connections."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from .websocket import WebSocket, WebSocketClosed
+
+__all__ = ["Hub"]
+
+
+class Hub:
+    """Tracks which WebSockets are subscribed to which channels.
+
+    Every :class:`~avalon.Avalon` app owns a hub at ``app.hub``; sockets are
+    removed from all channels automatically when their handler returns.
+    """
+
+    def __init__(self) -> None:
+        self._channels: dict[str, set[WebSocket]] = {}
+
+    def join(self, channel: str, ws: WebSocket) -> None:
+        """Subscribe ``ws`` to ``channel``."""
+        self._channels.setdefault(channel, set()).add(ws)
+
+    def leave(self, channel: str, ws: WebSocket) -> None:
+        """Unsubscribe ``ws`` from ``channel`` (no-op if not subscribed)."""
+        members = self._channels.get(channel)
+        if members is None:
+            return
+        members.discard(ws)
+        if not members:
+            del self._channels[channel]
+
+    def leave_all(self, ws: WebSocket) -> None:
+        """Unsubscribe ``ws`` from every channel."""
+        for channel in list(self._channels):
+            self.leave(channel, ws)
+
+    def members(self, channel: str) -> set[WebSocket]:
+        """Return a copy of the set of sockets subscribed to ``channel``."""
+        return set(self._channels.get(channel, ()))
+
+    def channels(self) -> list[str]:
+        """Return the names of all channels with at least one member."""
+        return sorted(self._channels)
+
+    async def broadcast(
+        self,
+        channel: str,
+        message: Any,
+        *,
+        exclude: WebSocket | None = None,
+    ) -> int:
+        """Send ``message`` to every member of ``channel`` concurrently.
+
+        ``str``/``bytes`` are sent as-is; anything else is JSON-encoded.
+        Sockets that fail to receive are dropped from the hub. Returns the
+        number of sockets the message was delivered to.
+        """
+        if not isinstance(message, (str, bytes)):
+            message = json.dumps(message, separators=(",", ":"))
+        targets = [ws for ws in self.members(channel) if ws is not exclude]
+        results = await asyncio.gather(*(ws.send(message) for ws in targets), return_exceptions=True)
+        delivered = 0
+        for ws, result in zip(targets, results):
+            if isinstance(result, WebSocketClosed):
+                self.leave_all(ws)
+            elif isinstance(result, BaseException):
+                raise result
+            else:
+                delivered += 1
+        return delivered

avalon/client.py

@@ -0,0 +1,68 @@
+"""A minimal asyncio WebSocket client, handy for tests and scripts."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import os
+from urllib.parse import urlsplit
+
+from .websocket import WebSocket, accept_key
+
+__all__ = ["HandshakeError", "connect"]
+
+
+class HandshakeError(Exception):
+    """Raised when the server rejects or botches the WebSocket handshake."""
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        super().__init__(message)
+
+
+async def connect(url: str, *, headers: dict[str, str] | None = None) -> WebSocket:
+    """Open a client WebSocket to ``url`` (``ws://host[:port]/path``).
+
+    Returns a :class:`WebSocket` that masks outgoing frames as RFC 6455
+    requires of clients. Only plain ``ws://`` is supported.
+    """
+    parts = urlsplit(url)
+    if parts.scheme != "ws":
+        raise ValueError(f"unsupported URL scheme {parts.scheme!r}; use ws://")
+    host = parts.hostname or "127.0.0.1"
+    port = parts.port or 80
+    target = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+
+    reader, writer = await asyncio.open_connection(host, port)
+    key = base64.b64encode(os.urandom(16)).decode("ascii")
+    request_headers = {
+        "Host": f"{host}:{port}",
+        "Upgrade": "websocket",
+        "Connection": "Upgrade",
+        "Sec-WebSocket-Key": key,
+        "Sec-WebSocket-Version": "13",
+        **(headers or {}),
+    }
+    head = f"GET {target} HTTP/1.1\r\n" + "".join(f"{k}: {v}\r\n" for k, v in request_headers.items())
+    writer.write((head + "\r\n").encode("latin-1"))
+    await writer.drain()
+
+    try:
+        raw = await reader.readuntil(b"\r\n\r\n")
+    except asyncio.IncompleteReadError:
+        writer.close()
+        raise HandshakeError(0, "connection closed during handshake") from None
+    lines = raw.decode("latin-1").split("\r\n")
+    status = int(lines[0].split(" ", 2)[1])
+    resp_headers = {}
+    for line in lines[1:]:
+        name, sep, value = line.partition(":")
+        if sep:
+            resp_headers[name.strip().lower()] = value.strip()
+    if status != 101:
+        writer.close()
+        raise HandshakeError(status, f"server responded {lines[0]!r}")
+    if resp_headers.get("sec-websocket-accept") != accept_key(key):
+        writer.close()
+        raise HandshakeError(status, "bad Sec-WebSocket-Accept")
+    return WebSocket(reader, writer, client=True, path=parts.path or "/", headers=resp_headers)

avalon/http.py

@@ -0,0 +1,191 @@
+"""HTTP/1.1 primitives: request parsing, responses and errors."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import parse_qsl, unquote, urlsplit
+
+__all__ = [
+    "HTTPError",
+    "HTMLResponse",
+    "JSONResponse",
+    "Request",
+    "Response",
+    "read_request",
+]
+
+MAX_HEADER_BYTES = 64 * 1024
+MAX_BODY_BYTES = 8 * 1024 * 1024
+
+
+class HTTPError(Exception):
+    """Raise from a handler to abort with an HTTP error status.
+
+    The error is rendered as a JSON body ``{"error": detail}``.
+    """
+
+    def __init__(self, status: int, detail: str | None = None) -> None:
+        self.status = int(status)
+        self.detail = detail if detail is not None else HTTPStatus(self.status).phrase
+        super().__init__(f"{self.status}: {self.detail}")
+
+
+@dataclass
+class Request:
+    """An incoming HTTP request.
+
+    Header names are stored lower-cased. ``query`` keeps the last value of
+    each query-string key; ``params`` holds values captured from the route
+    path (already converted, e.g. ``{id:int}`` yields an ``int``).
+    """
+
+    method: str
+    path: str
+    query: dict[str, str] = field(default_factory=dict)
+    headers: dict[str, str] = field(default_factory=dict)
+    body: bytes = b""
+    params: dict[str, Any] = field(default_factory=dict)
+    version: str = "HTTP/1.1"
+
+    def text(self, encoding: str = "utf-8") -> str:
+        """Return the body decoded as text."""
+        return self.body.decode(encoding)
+
+    def json(self) -> Any:
+        """Return the body parsed as JSON; raises ``HTTPError(400)`` if invalid."""
+        try:
+            return json.loads(self.body or b"null")
+        except ValueError as exc:
+            raise HTTPError(400, f"invalid JSON body: {exc}") from None
+
+    @property
+    def keep_alive(self) -> bool:
+        """Whether the client asked to keep the connection open."""
+        conn = self.headers.get("connection", "").lower()
+        if self.version == "HTTP/1.0":
+            return conn == "keep-alive"
+        return conn != "close"
+
+    @property
+    def is_websocket(self) -> bool:
+        """Whether this request is a WebSocket upgrade handshake."""
+        return (
+            self.headers.get("upgrade", "").lower() == "websocket"
+            and "upgrade" in self.headers.get("connection", "").lower()
+        )
+
+
+class Response:
+    """An outgoing HTTP response with a fully buffered body."""
+
+    media_type = "text/plain; charset=utf-8"
+
+    def __init__(
+        self,
+        body: str | bytes = b"",
+        status: int = 200,
+        headers: dict[str, str] | None = None,
+        media_type: str | None = None,
+    ) -> None:
+        self.body = self.render(body)
+        self.status = int(status)
+        self.headers: dict[str, str] = dict(headers or {})
+        if media_type is not None:
+            self.media_type = media_type
+
+    def render(self, content: Any) -> bytes:
+        """Convert ``content`` into body bytes."""
+        if isinstance(content, bytes):
+            return content
+        return str(content).encode("utf-8")
+
+    def encode(self, keep_alive: bool = False) -> bytes:
+        """Serialize status line, headers and body to wire format."""
+        phrase = HTTPStatus(self.status).phrase if self.status in HTTPStatus._value2member_map_ else ""
+        headers = {"Content-Type": self.media_type, **self.headers}
+        headers["Content-Length"] = str(len(self.body))
+        headers["Connection"] = "keep-alive" if keep_alive else "close"
+        lines = [f"HTTP/1.1 {self.status} {phrase}"]
+        lines += [f"{k}: {v}" for k, v in headers.items()]
+        return ("\r\n".join(lines) + "\r\n\r\n").encode("latin-1") + self.body
+
+
+class JSONResponse(Response):
+    """A response whose body is ``content`` serialized as JSON."""
+
+    media_type = "application/json"
+
+    def render(self, content: Any) -> bytes:
+        return json.dumps(content, separators=(",", ":")).encode("utf-8")
+
+
+class HTMLResponse(Response):
+    """A ``text/html`` response."""
+
+    media_type = "text/html; charset=utf-8"
+
+
+async def read_request(reader: asyncio.StreamReader) -> Request | None:
+    """Read one HTTP request from ``reader``.
+
+    Returns ``None`` if the peer closed the connection before sending a
+    request. Raises ``HTTPError`` for malformed or oversized requests.
+    """
+    try:
+        head = await reader.readuntil(b"\r\n\r\n")
+    except asyncio.IncompleteReadError as exc:
+        if not exc.partial.strip():
+            return None
+        raise HTTPError(400, "incomplete request head") from None
+    except asyncio.LimitOverrunError:
+        raise HTTPError(431) from None
+    if len(head) > MAX_HEADER_BYTES:
+        raise HTTPError(431)
+
+    lines = head.decode("latin-1").split("\r\n")
+    try:
+        method, target, version = lines[0].split(" ", 2)
+    except ValueError:
+        raise HTTPError(400, "malformed request line") from None
+
+    headers: dict[str, str] = {}
+    for line in lines[1:]:
+        if not line:
+            continue
+        name, sep, value = line.partition(":")
+        if not sep:
+            raise HTTPError(400, "malformed header")
+        headers[name.strip().lower()] = value.strip()
+
+    if "transfer-encoding" in headers:
+        raise HTTPError(501, "Transfer-Encoding request bodies are not supported")
+
+    body = b""
+    length = headers.get("content-length")
+    if length is not None:
+        try:
+            n = int(length)
+        except ValueError:
+            raise HTTPError(400, "invalid Content-Length") from None
+        if n < 0:
+            raise HTTPError(400, "invalid Content-Length")
+        if n > MAX_BODY_BYTES:
+            raise HTTPError(413)
+        try:
+            body = await reader.readexactly(n)
+        except asyncio.IncompleteReadError:
+            raise HTTPError(400, "incomplete body") from None
+
+    url = urlsplit(target)
+    return Request(
+        method=method.upper(),
+        path=unquote(url.path) or "/",
+        query=dict(parse_qsl(url.query, keep_blank_values=True)),
+        headers=headers,
+        body=body,
+        version=version.strip(),
+    )

avalon/routing.py

@@ -0,0 +1,108 @@
+"""Path-pattern routing with typed parameters."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .http import HTTPError
+
+__all__ = ["Route", "Router"]
+
+_PARAM = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)(?::(str|int|float|path))?\}")
+
+_CONVERTERS: dict[str, tuple[str, Callable[[str], Any]]] = {
+    "str": (r"[^/]+", str),
+    "int": (r"-?\d+", int),
+    "float": (r"-?\d+(?:\.\d+)?", float),
+    "path": (r".+", str),
+}
+
+
+def compile_path(path: str) -> tuple[re.Pattern[str], dict[str, Callable[[str], Any]]]:
+    """Compile a route path such as ``/users/{id:int}`` into a regex.
+
+    Supported converters: ``str`` (default), ``int``, ``float`` and ``path``
+    (which may contain slashes).
+    """
+    if not path.startswith("/"):
+        raise ValueError(f"route path must start with '/': {path!r}")
+    pattern, converters, pos = "^", {}, 0
+    for m in _PARAM.finditer(path):
+        name, kind = m.group(1), m.group(2) or "str"
+        if name in converters:
+            raise ValueError(f"duplicate parameter {name!r} in {path!r}")
+        regex, conv = _CONVERTERS[kind]
+        pattern += re.escape(path[pos : m.start()]) + f"(?P<{name}>{regex})"
+        converters[name] = conv
+        pos = m.end()
+    pattern += re.escape(path[pos:]) + "$"
+    return re.compile(pattern), converters
+
+
+@dataclass
+class Route:
+    """A single registered route.
+
+    ``kind`` is ``"http"`` or ``"websocket"``; ``methods`` is only meaningful
+    for HTTP routes.
+    """
+
+    path: str
+    handler: Callable[..., Any]
+    methods: frozenset[str] = frozenset({"GET"})
+    kind: str = "http"
+    pattern: re.Pattern[str] = field(init=False, repr=False)
+    converters: dict[str, Callable[[str], Any]] = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self.pattern, self.converters = compile_path(self.path)
+
+    def match(self, path: str) -> dict[str, Any] | None:
+        """Return converted path params if ``path`` matches, else ``None``."""
+        m = self.pattern.match(path)
+        if m is None:
+            return None
+        return {k: self.converters[k](v) for k, v in m.groupdict().items()}
+
+
+class Router:
+    """An ordered collection of routes; first match wins."""
+
+    def __init__(self) -> None:
+        self.routes: list[Route] = []
+
+    def add(
+        self,
+        path: str,
+        handler: Callable[..., Any],
+        methods: tuple[str, ...] | list[str] = ("GET",),
+        kind: str = "http",
+    ) -> Route:
+        """Register ``handler`` for ``path`` and return the new ``Route``."""
+        if kind not in ("http", "websocket"):
+            raise ValueError(f"unknown route kind {kind!r}")
+        route = Route(path, handler, frozenset(m.upper() for m in methods), kind)
+        self.routes.append(route)
+        return route
+
+    def resolve(self, path: str, method: str = "GET", kind: str = "http") -> tuple[Route, dict[str, Any]]:
+        """Find the route for ``path``.
+
+        Raises ``HTTPError(404)`` if nothing matches and ``HTTPError(405)`` if
+        a path matches but not with the given method.
+        """
+        method_mismatch = False
+        for route in self.routes:
+            if route.kind != kind:
+                continue
+            params = route.match(path)
+            if params is None:
+                continue
+            if kind == "http" and method.upper() not in route.methods:
+                if not (method.upper() == "HEAD" and "GET" in route.methods):
+                    method_mismatch = True
+                    continue
+            return route, params
+        raise HTTPError(405 if method_mismatch else 404)

avalon/websocket.py

@@ -0,0 +1,230 @@
+"""RFC 6455 WebSocket protocol: handshake helpers and a connection object."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import json
+import os
+import struct
+from enum import IntEnum
+from typing import Any, AsyncIterator
+
+__all__ = ["Opcode", "WebSocket", "WebSocketClosed", "accept_key"]
+
+_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+
+def accept_key(key: str) -> str:
+    """Compute the ``Sec-WebSocket-Accept`` value for a client ``key``."""
+    digest = hashlib.sha1((key + _GUID).encode("ascii")).digest()
+    return base64.b64encode(digest).decode("ascii")
+
+
+class Opcode(IntEnum):
+    """WebSocket frame opcodes."""
+
+    CONTINUATION = 0x0
+    TEXT = 0x1
+    BINARY = 0x2
+    CLOSE = 0x8
+    PING = 0x9
+    PONG = 0xA
+
+
+class WebSocketClosed(Exception):
+    """Raised when receiving from or sending to a closed WebSocket."""
+
+    def __init__(self, code: int = 1006, reason: str = "") -> None:
+        self.code = code
+        self.reason = reason
+        super().__init__(f"WebSocket closed ({code}) {reason}".rstrip())
+
+
+def _apply_mask(data: bytes, mask: bytes) -> bytes:
+    """XOR ``data`` with the 4-byte ``mask`` (masking is its own inverse)."""
+    if not data:
+        return data
+    repeated = (mask * (len(data) // 4 + 1))[: len(data)]
+    return (int.from_bytes(data, "big") ^ int.from_bytes(repeated, "big")).to_bytes(len(data), "big")
+
+
+def encode_frame(opcode: int, payload: bytes, *, mask: bool = False, fin: bool = True) -> bytes:
+    """Encode a single WebSocket frame."""
+    header = bytearray([(0x80 if fin else 0) | opcode])
+    mask_bit = 0x80 if mask else 0
+    n = len(payload)
+    if n < 126:
+        header.append(mask_bit | n)
+    elif n < 1 << 16:
+        header.append(mask_bit | 126)
+        header += struct.pack("!H", n)
+    else:
+        header.append(mask_bit | 127)
+        header += struct.pack("!Q", n)
+    if mask:
+        key = os.urandom(4)
+        return bytes(header) + key + _apply_mask(payload, key)
+    return bytes(header) + payload
+
+
+class WebSocket:
+    """One end of an established WebSocket connection.
+
+    Server-side sockets are handed to ``@app.websocket`` handlers; client-side
+    sockets come from :func:`avalon.connect`. Control frames are handled
+    transparently: pings are answered with pongs and a close frame from the
+    peer is echoed before :class:`WebSocketClosed` is raised.
+
+    Iterating with ``async for msg in ws`` yields messages until the peer
+    closes the connection.
+    """
+
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        *,
+        client: bool = False,
+        path: str = "/",
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        max_size: int = 1 << 20,
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._client = client
+        self._send_lock = asyncio.Lock()
+        self._closed = False
+        self.path = path
+        self.params: dict[str, Any] = dict(params or {})
+        self.headers: dict[str, str] = dict(headers or {})
+        self.max_size = max_size
+        self.close_code: int | None = None
+        self.state: dict[str, Any] = {}
+        """Free-form per-connection storage for application data."""
+
+    @property
+    def closed(self) -> bool:
+        """Whether the connection has been closed (by either side)."""
+        return self._closed
+
+    # -- sending ---------------------------------------------------------
+
+    async def _send_frame(self, opcode: int, payload: bytes) -> None:
+        if self._closed:
+            raise WebSocketClosed(self.close_code or 1006, "connection is closed")
+        async with self._send_lock:
+            try:
+                self._writer.write(encode_frame(opcode, payload, mask=self._client))
+                await self._writer.drain()
+            except (ConnectionError, RuntimeError) as exc:
+                self._closed = True
+                raise WebSocketClosed(1006, str(exc)) from None
+
+    async def send(self, data: str | bytes) -> None:
+        """Send a text (``str``) or binary (``bytes``) message."""
+        if isinstance(data, str):
+            await self._send_frame(Opcode.TEXT, data.encode("utf-8"))
+        else:
+            await self._send_frame(Opcode.BINARY, bytes(data))
+
+    async def send_json(self, obj: Any) -> None:
+        """Serialize ``obj`` as JSON and send it as a text message."""
+        await self.send(json.dumps(obj, separators=(",", ":")))
+
+    async def ping(self, data: bytes = b"") -> None:
+        """Send a ping control frame."""
+        await self._send_frame(Opcode.PING, data)
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        """Send a close frame (if still open) and shut down the transport."""
+        if not self._closed:
+            payload = struct.pack("!H", code) + reason.encode("utf-8")[:123]
+            try:
+                await self._send_frame(Opcode.CLOSE, payload)
+            except WebSocketClosed:
+                pass
+            self._closed = True
+            self.close_code = code
+        self._writer.close()
+        try:
+            await self._writer.wait_closed()
+        except (ConnectionError, RuntimeError):
+            pass
+
+    # -- receiving -------------------------------------------------------
+
+    async def _read_frame(self) -> tuple[bool, int, bytes]:
+        try:
+            b1, b2 = await self._reader.readexactly(2)
+            fin, opcode = bool(b1 & 0x80), b1 & 0x0F
+            masked, n = bool(b2 & 0x80), b2 & 0x7F
+            if n == 126:
+                (n,) = struct.unpack("!H", await self._reader.readexactly(2))
+            elif n == 127:
+                (n,) = struct.unpack("!Q", await self._reader.readexactly(8))
+            if n > self.max_size:
+                await self.close(1009, "message too big")
+                raise WebSocketClosed(1009, "message too big")
+            key = await self._reader.readexactly(4) if masked else b""
+            payload = await self._reader.readexactly(n)
+        except (asyncio.IncompleteReadError, ConnectionError):
+            self._closed = True
+            raise WebSocketClosed(1006, "connection lost") from None
+        if masked:
+            payload = _apply_mask(payload, key)
+        return fin, opcode, payload
+
+    async def receive(self) -> str | bytes:
+        """Wait for the next data message (``str`` for text, ``bytes`` for binary).
+
+        Raises :class:`WebSocketClosed` once the connection is closed.
+        """
+        if self._closed:
+            raise WebSocketClosed(self.close_code or 1006, "connection is closed")
+        msg_opcode: int | None = None
+        chunks: list[bytes] = []
+        while True:
+            fin, opcode, payload = await self._read_frame()
+            if opcode == Opcode.PING:
+                await self._send_frame(Opcode.PONG, payload)
+                continue
+            if opcode == Opcode.PONG:
+                continue
+            if opcode == Opcode.CLOSE:
+                code = struct.unpack("!H", payload[:2])[0] if len(payload) >= 2 else 1005
+                reason = payload[2:].decode("utf-8", "replace")
+                await self.close(code if code != 1005 else 1000)
+                self.close_code = code
+                raise WebSocketClosed(code, reason)
+            if opcode in (Opcode.TEXT, Opcode.BINARY):
+                if msg_opcode is not None:
+                    await self.close(1002, "expected continuation frame")
+                    raise WebSocketClosed(1002, "expected continuation frame")
+                msg_opcode = opcode
+            elif opcode != Opcode.CONTINUATION or msg_opcode is None:
+                await self.close(1002, "protocol error")
+                raise WebSocketClosed(1002, "protocol error")
+            chunks.append(payload)
+            if sum(map(len, chunks)) > self.max_size:
+                await self.close(1009, "message too big")
+                raise WebSocketClosed(1009, "message too big")
+            if fin:
+                data = b"".join(chunks)
+                return data.decode("utf-8") if msg_opcode == Opcode.TEXT else data
+
+    async def receive_json(self) -> Any:
+        """Receive a message and parse it as JSON."""
+        return json.loads(await self.receive())
+
+    def __aiter__(self) -> AsyncIterator[str | bytes]:
+        return self._iter()
+
+    async def _iter(self) -> AsyncIterator[str | bytes]:
+        while True:
+            try:
+                yield await self.receive()
+            except WebSocketClosed:
+                return

avalon-0.2.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: avalon
+Version: 0.2.0
+Summary: Real-time web framework: HTTP routes, WebSockets and broadcast channels on pure asyncio
+Author: nehz
+License: MIT
+Keywords: web,framework,websocket,real-time,asyncio,pubsub
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# avalon
+
+**Real-time web framework.** HTTP routes, WebSockets and broadcast channels in one
+small, dependency-free package built on `asyncio`.
+
+Avalon is for apps where the server pushes data to clients as it happens, such
+as chat, live dashboards, multiplayer cursors and notifications. You don't have to
+wire an HTTP framework, a WebSocket library and a pub/sub layer together
+yourself. Everything is plain standard-library Python you can read in one sitting.
+
+## Features
+
+- **Zero dependencies**: pure standard library (`asyncio`, `hashlib`, `json`, ...), Python 3.10+.
+- **Decorator routing** with typed path parameters: `{id:int}`, `{x:float}`, `{rest:path}`.
+- **Sync or async handlers**: return a `Response`, a `dict`/`list` (JSON), `str`, `bytes` or `None`.
+- **WebSockets built in** (RFC 6455): text/binary messages, fragmentation, automatic ping/pong,
+  close handshake, size limits and `async for msg in ws` iteration.
+- **Broadcast channels**: `app.hub.join(room, ws)` and `await app.hub.broadcast(room, msg)`.
+  Disconnected sockets are cleaned up automatically.
+- **HTTP/1.1 keep-alive**, `HEAD` support and JSON error responses (`HTTPError`).
+- **WebSocket client** (`avalon.connect`) for tests, scripts and service-to-service links.
+- Fully type-hinted (`py.typed`).
+
+## Install
+
+```bash
+pip install avalon
+# or, from a checkout:
+pip install .
+```
+
+## Quickstart
+
+```python
+from avalon import Avalon
+
+app = Avalon()
+
+@app.get("/hello/{name}")
+def hello(request):
+    return {"hello": request.params["name"]}
+
+@app.websocket("/ws/{room}")
+async def room(ws):
+    name = ws.params["room"]
+    app.hub.join(name, ws)
+    async for message in ws:
+        await app.hub.broadcast(name, {"room": name, "text": message})
+
+if __name__ == "__main__":
+    app.run("127.0.0.1", 8000)
+```
+
+Talk to it from Python:
+
+```python
+import asyncio
+from avalon import connect
+
+async def main():
+    ws = await connect("ws://127.0.0.1:8000/ws/lobby")
+    await ws.send("hi!")
+    print(await ws.receive_json())   # {'room': 'lobby', 'text': 'hi!'}
+    await ws.close()
+
+asyncio.run(main())
+```
+
+A complete multi-room chat with a browser UI lives in `examples/chat.py`:
+
+```bash
+PYTHONPATH=src python3 examples/chat.py          # http://127.0.0.1:8000
+PYTHONPATH=src python3 examples/chat.py --demo   # scripted two-client demo, then exit
+```
+
+## API overview
+
+Everything below is importable from the top-level `avalon` package.
+
+### `Avalon(*, keep_alive_timeout=15.0)`
+
+| Member | Description |
+| --- | --- |
+| `@app.route(path, methods=("GET",))` | Register an HTTP handler `handler(request)`; may be sync or async. |
+| `@app.get(path)` / `@app.post(path)` | Shorthands for `route` with one method. |
+| `@app.websocket(path)` | Register an `async def handler(ws)`. Non-async functions raise `TypeError`. |
+| `app.hub` | The app's `Hub` (broadcast channels). |
+| `app.sockets` | `set[WebSocket]` of connections currently being served. |
+| `app.router` | The underlying `Router`. |
+| `await app.dispatch(request)` | Route a `Request` and return a `Response` (never raises). |
+| `await app.handle_connection(reader, writer)` | Serve one TCP connection (for custom servers). |
+| `await app.serve(host="127.0.0.1", port=8000)` | Start listening and return an `asyncio.Server` (`port=0` picks a free port). |
+| `app.run(host="127.0.0.1", port=8000)` | Blocking: serve forever until Ctrl+C. |
+
+`GET` routes also answer `HEAD`. Unknown paths return `404`, a known path with the wrong
+method returns `405`, and an unhandled exception returns `500` (logged on the `avalon` logger).
+All error bodies are JSON: `{"error": "..."}`.
+
+### Handler return values: `to_response(value)`
+
+| Return | Response |
+| --- | --- |
+| `Response` (or subclass) | sent as-is |
+| `dict` / `list` | `JSONResponse` (`application/json`) |
+| `str` | `text/plain; charset=utf-8` |
+| `bytes` | `application/octet-stream` |
+| `None` | `204 No Content` |
+
+Anything else raises `TypeError`, which the app turns into a 500.
+
+### HTTP
+
+- `Request`: `method`, `path` (URL-decoded), `query: dict[str, str]`, `headers: dict[str, str]`
+  (lower-case names), `body: bytes`, `params: dict` (converted path params), `version`;
+  methods `text()` and `json()` (raises `HTTPError(400)` on invalid JSON); properties
+  `keep_alive` and `is_websocket`.
+- `Response(body=b"", status=200, headers=None, media_type=None)`: the default media type is
+  `text/plain; charset=utf-8`. `encode(keep_alive=False)` returns the wire bytes.
+- `JSONResponse(body, status=200, headers=None)`: serializes any JSON-compatible `body` with `json.dumps`.
+- `HTMLResponse(body, status=200, headers=None)`: `text/html; charset=utf-8`.
+- `HTTPError(status, detail=None)`: raise it in a handler to return `{"error": detail}` with
+  that status. `detail` defaults to the standard reason phrase.
+
+### WebSockets
+
+- `WebSocket`: `path`, `params`, `headers`, `state` (a free-form dict), `closed`, `close_code`, `max_size`
+  - `await ws.send(str | bytes)` sends a text or binary message. `await ws.send_json(obj)` sends JSON as text.
+  - `await ws.receive() -> str | bytes` and `await ws.receive_json()`.
+  - `async for msg in ws:` yields messages until the peer closes.
+  - `await ws.ping(data=b"")` and `await ws.close(code=1000, reason="")`.
+- `WebSocketClosed(code, reason)`: raised by `receive`/`send` once the connection is closed.
+  Inside a handler you can let it propagate, because the app treats it as a normal disconnect. An
+  unhandled exception in a handler closes the socket with code `1011`.
+- `Opcode`: frame opcode enum (`TEXT`, `BINARY`, `CLOSE`, `PING`, `PONG`, `CONTINUATION`).
+- `await connect(url, *, headers=None) -> WebSocket`: client for `ws://` URLs. It raises
+  `HandshakeError` (with `.status`) if the server rejects the upgrade.
+
+### Channels: `Hub`
+
+| Method | Description |
+| --- | --- |
+| `join(channel, ws)` / `leave(channel, ws)` | Subscribe or unsubscribe a socket. |
+| `leave_all(ws)` | Remove a socket from every channel (done automatically on disconnect). |
+| `members(channel) -> set[WebSocket]` | Snapshot of a channel's sockets. |
+| `channels() -> list[str]` | Sorted names of non-empty channels. |
+| `await broadcast(channel, message, *, exclude=None) -> int` | Send to all members concurrently. Non-`str`/`bytes` messages are JSON-encoded. Dead sockets are dropped. Returns the delivery count. |
+
+### Routing
+
+- `Router()`: `add(path, handler, methods=("GET",), kind="http" | "websocket") -> Route` and
+  `resolve(path, method="GET", kind="http") -> (Route, params)`, which raises `HTTPError(404/405)`.
+- `Route`: `path`, `handler`, `methods`, `kind`, `match(path) -> dict | None`.
+- Path converters: `{name}` / `{name:str}` (one segment), `{name:int}`, `{name:float}`,
+  `{name:path}` (may contain `/`). The first registered match wins.
+
+## Limitations
+
+Avalon is deliberately small. It has no TLS (put it behind a reverse proxy), no
+WebSocket extensions or subprotocol negotiation, no chunked request bodies (they are rejected with `501`), and
+hubs are in-process only, so they don't fan out across multiple workers.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+# or, with pytest installed:
+python3 -m pytest
+```
+
+## License
+
+MIT

avalon-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+avalon/__init__.py,sha256=Oa0W94oWdvmaH2y8YPR1qYkWB3eo2uMR_pIoE42bnVg,729
+avalon/app.py,sha256=HpZFor6O6yni2YXOIJMeo7gKPCAMEM6UKaR36h1-yI0,8361
+avalon/channels.py,sha256=-B9c_MKerDEmMSq7VYdqtgs9vNSy17y0Shf0ppHyV4E,2598
+avalon/client.py,sha256=PV8LMk-oRObqnePODal530puCa16sIxuw9FRQP-4v9o,2453
+avalon/http.py,sha256=kJyITRIZqtSVly5KkM56nrz3lxGRnPmUzxoxBndlcqE,6191
+avalon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+avalon/routing.py,sha256=IhUj1v7no-DTvhZMetamJGfJMTjUjO3qs14LZ5kGsj0,3681
+avalon/websocket.py,sha256=RLQgDXNJdO-MusJS94cFUok-gvMAb-h0cz38WEmt3Mw,8614
+avalon-0.2.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+avalon-0.2.0.dist-info/METADATA,sha256=-5sVTTPkc-Q_H4W-uFbcdt-l_cy_qwr_ZbHxJhpfmMQ,8309
+avalon-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+avalon-0.2.0.dist-info/top_level.txt,sha256=EwZXVOkUJp6PYD0VdJG2tmGsYN_zGk4goHK7-8PcA8c,7
+avalon-0.2.0.dist-info/RECORD,,

avalon-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

avalon-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

avalon-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+avalon