without-asgi 0.0.1__tar.gz

without_asgi-0.0.1/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: without-asgi
+Version: 0.0.1
+Summary: without adapters that turn an ASGI app's receive/send into typed event streams and back.
+Author: Josh Karpel
+Author-email: Josh Karpel <josh.karpel@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: without-core==0.0.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# without-asgi
+
+`without` adapters that turn an [ASGI](https://asgi.readthedocs.io/) application's
+`receive`/`send` into typed event streams and back. This package is *only* the
+boundary: it parses raw ASGI
+event dicts into typed values, encodes typed values back into the dicts a server
+expects, and exposes `receive` as a `Stream` and `send` as a `Sink`. Routing,
+middleware, and handlers are left to the application. The one piece of protocol
+the adapter does drive is lifespan, because that is boundary work, not app policy.
+
+An ASGI app is `async def app(scope, receive, send)`. The adapters let the body
+of that callable read as plain `without` wiring:
+
+```python
+from without_asgi import http_inbound, http_outbound, parse_http_scope
+
+async def app(scope, receive, send):
+    head = parse_http_scope(scope)
+    handler = select(head)                          # your routing, your processor
+    outbound = handler(http_inbound(receive))       # Stream[Inbound] -> Stream[Outbound]
+    await http_outbound(send)(outbound)             # drive ASGI send
+```
+
+`make_asgi_app(lifespan, http=..., websocket=...)` builds the ASGI app, driving
+the lifespan protocol and wiring each connection's `receive`/`send` around the
+`Processor` a router selects. The same typed vocabulary parses and encodes in
+*both* directions, so a transport that owns the wire (like
+[`without-http`](../without-http)) can talk ASGI to any app in typed values; and
+the optional `without_asgi.routing` submodule ships the unopinionated
+`Middleware` / `stack` / `wrap` / `buffered` tools you assemble a router from.
+
+For a full, opinionated router you don't have to hand-roll, the sibling
+[`without-web`](../without-web) package snaps onto this boundary through nothing
+but the `HttpRouter` type.
+
+See the
+[`without-asgi` guide](https://without.help/guides/without-asgi/)
+(with the [API reference](https://without.help/reference/without_asgi/))
+for the full surface, including the codec's server direction and the middleware
+body shapes.

without_asgi-0.0.1/README.md

@@ -0,0 +1,40 @@
+# without-asgi
+
+`without` adapters that turn an [ASGI](https://asgi.readthedocs.io/) application's
+`receive`/`send` into typed event streams and back. This package is *only* the
+boundary: it parses raw ASGI
+event dicts into typed values, encodes typed values back into the dicts a server
+expects, and exposes `receive` as a `Stream` and `send` as a `Sink`. Routing,
+middleware, and handlers are left to the application. The one piece of protocol
+the adapter does drive is lifespan, because that is boundary work, not app policy.
+
+An ASGI app is `async def app(scope, receive, send)`. The adapters let the body
+of that callable read as plain `without` wiring:
+
+```python
+from without_asgi import http_inbound, http_outbound, parse_http_scope
+
+async def app(scope, receive, send):
+    head = parse_http_scope(scope)
+    handler = select(head)                          # your routing, your processor
+    outbound = handler(http_inbound(receive))       # Stream[Inbound] -> Stream[Outbound]
+    await http_outbound(send)(outbound)             # drive ASGI send
+```
+
+`make_asgi_app(lifespan, http=..., websocket=...)` builds the ASGI app, driving
+the lifespan protocol and wiring each connection's `receive`/`send` around the
+`Processor` a router selects. The same typed vocabulary parses and encodes in
+*both* directions, so a transport that owns the wire (like
+[`without-http`](../without-http)) can talk ASGI to any app in typed values; and
+the optional `without_asgi.routing` submodule ships the unopinionated
+`Middleware` / `stack` / `wrap` / `buffered` tools you assemble a router from.
+
+For a full, opinionated router you don't have to hand-roll, the sibling
+[`without-web`](../without-web) package snaps onto this boundary through nothing
+but the `HttpRouter` type.
+
+See the
+[`without-asgi` guide](https://without.help/guides/without-asgi/)
+(with the [API reference](https://without.help/reference/without_asgi/))
+for the full surface, including the codec's server direction and the middleware
+body shapes.

without_asgi-0.0.1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "without-asgi"
+version = "0.0.1"
+description = "without adapters that turn an ASGI app's receive/send into typed event streams and back."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Josh Karpel", email = "josh.karpel@gmail.com" },
+]
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "without-core==0.0.1",
+]
+
+[tool.uv.sources]
+without-core = { workspace = true }

without_asgi-0.0.1/src/without_asgi/__init__.py

@@ -0,0 +1,173 @@
+from without_asgi.app import HttpHandler
+from without_asgi.app import HttpRouter
+from without_asgi.app import Lifespan
+from without_asgi.app import WebsocketHandler
+from without_asgi.app import WebsocketRouter
+from without_asgi.app import make_asgi_app
+from without_asgi.app import refuse_http
+from without_asgi.app import refuse_websocket
+from without_asgi.inbound import Disconnect
+from without_asgi.inbound import Inbound
+from without_asgi.inbound import LifespanEvent
+from without_asgi.inbound import RequestBody
+from without_asgi.inbound import Shutdown
+from without_asgi.inbound import Startup
+from without_asgi.inbound import WebsocketConnect
+from without_asgi.inbound import WebsocketDisconnect
+from without_asgi.inbound import WebsocketInbound
+from without_asgi.inbound import WebsocketReceive
+from without_asgi.inbound import encode_inbound
+from without_asgi.inbound import encode_lifespan_event
+from without_asgi.inbound import encode_websocket_inbound
+from without_asgi.inbound import parse_inbound
+from without_asgi.inbound import parse_lifespan_event
+from without_asgi.inbound import parse_websocket_inbound
+from without_asgi.outbound import EarlyHint
+from without_asgi.outbound import LifespanReply
+from without_asgi.outbound import Outbound
+from without_asgi.outbound import PathSend
+from without_asgi.outbound import Response
+from without_asgi.outbound import ResponseBody
+from without_asgi.outbound import ResponseDebug
+from without_asgi.outbound import ResponseStart
+from without_asgi.outbound import ResponseTrailers
+from without_asgi.outbound import ServerPush
+from without_asgi.outbound import ShutdownComplete
+from without_asgi.outbound import ShutdownFailed
+from without_asgi.outbound import StartupComplete
+from without_asgi.outbound import StartupFailed
+from without_asgi.outbound import SupportsFileno
+from without_asgi.outbound import WebsocketAccept
+from without_asgi.outbound import WebsocketClose
+from without_asgi.outbound import WebsocketOutbound
+from without_asgi.outbound import WebsocketResponseBody
+from without_asgi.outbound import WebsocketResponseStart
+from without_asgi.outbound import WebsocketSend
+from without_asgi.outbound import ZeroCopySend
+from without_asgi.outbound import encode_lifespan_reply
+from without_asgi.outbound import encode_outbound
+from without_asgi.outbound import encode_response
+from without_asgi.outbound import encode_websocket_outbound
+from without_asgi.outbound import parse_lifespan_reply
+from without_asgi.outbound import parse_outbound
+from without_asgi.outbound import parse_websocket_outbound
+from without_asgi.scope import Asgi
+from without_asgi.scope import ConnectionScope
+from without_asgi.scope import HttpScope
+from without_asgi.scope import LifespanScope
+from without_asgi.scope import Scope
+from without_asgi.scope import Tls
+from without_asgi.scope import WebsocketScope
+from without_asgi.scope import encode_http_scope
+from without_asgi.scope import encode_scope
+from without_asgi.scope import encode_websocket_scope
+from without_asgi.scope import extension
+from without_asgi.scope import parse_http_scope
+from without_asgi.scope import parse_scope
+from without_asgi.scope import parse_tls
+from without_asgi.scope import parse_websocket_scope
+from without_asgi.shell import ClientDisconnect
+from without_asgi.shell import http_inbound
+from without_asgi.shell import http_outbound
+from without_asgi.shell import lifespan_inbound
+from without_asgi.shell import lifespan_outbound
+from without_asgi.shell import read_body
+from without_asgi.shell import websocket_inbound
+from without_asgi.shell import websocket_outbound
+from without_asgi.types import ASGIApp
+from without_asgi.types import RawHeaders
+from without_asgi.types import RawMessage
+from without_asgi.types import RawScope
+from without_asgi.types import Receive
+from without_asgi.types import Send
+from without_asgi.types import WebsocketBinary
+from without_asgi.types import WebsocketData
+from without_asgi.types import WebsocketText
+
+__all__ = [
+    "ASGIApp",
+    "Asgi",
+    "ClientDisconnect",
+    "ConnectionScope",
+    "Disconnect",
+    "EarlyHint",
+    "HttpHandler",
+    "HttpRouter",
+    "HttpScope",
+    "Inbound",
+    "Lifespan",
+    "LifespanEvent",
+    "LifespanReply",
+    "LifespanScope",
+    "Outbound",
+    "PathSend",
+    "RawHeaders",
+    "RawMessage",
+    "RawScope",
+    "Receive",
+    "RequestBody",
+    "Response",
+    "ResponseBody",
+    "ResponseDebug",
+    "ResponseStart",
+    "ResponseTrailers",
+    "Scope",
+    "Send",
+    "ServerPush",
+    "Shutdown",
+    "ShutdownComplete",
+    "ShutdownFailed",
+    "Startup",
+    "StartupComplete",
+    "StartupFailed",
+    "SupportsFileno",
+    "Tls",
+    "WebsocketAccept",
+    "WebsocketBinary",
+    "WebsocketClose",
+    "WebsocketConnect",
+    "WebsocketData",
+    "WebsocketDisconnect",
+    "WebsocketHandler",
+    "WebsocketInbound",
+    "WebsocketOutbound",
+    "WebsocketReceive",
+    "WebsocketResponseBody",
+    "WebsocketResponseStart",
+    "WebsocketRouter",
+    "WebsocketScope",
+    "WebsocketSend",
+    "WebsocketText",
+    "ZeroCopySend",
+    "encode_http_scope",
+    "encode_inbound",
+    "encode_lifespan_event",
+    "encode_lifespan_reply",
+    "encode_outbound",
+    "encode_response",
+    "encode_scope",
+    "encode_websocket_inbound",
+    "encode_websocket_outbound",
+    "encode_websocket_scope",
+    "extension",
+    "http_inbound",
+    "http_outbound",
+    "lifespan_inbound",
+    "lifespan_outbound",
+    "make_asgi_app",
+    "parse_http_scope",
+    "parse_inbound",
+    "parse_lifespan_event",
+    "parse_lifespan_reply",
+    "parse_outbound",
+    "parse_scope",
+    "parse_tls",
+    "parse_websocket_inbound",
+    "parse_websocket_outbound",
+    "parse_websocket_scope",
+    "read_body",
+    "refuse_http",
+    "refuse_websocket",
+    "websocket_inbound",
+    "websocket_outbound",
+]

without_asgi-0.0.1/src/without_asgi/app.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+from typing import assert_never
+
+from without import Processor
+from without import Stream
+from without import stream_from_iterable
+
+from without_asgi.inbound import Inbound
+from without_asgi.inbound import Shutdown
+from without_asgi.inbound import Startup
+from without_asgi.inbound import WebsocketInbound
+from without_asgi.outbound import Outbound
+from without_asgi.outbound import Response
+from without_asgi.outbound import ShutdownComplete
+from without_asgi.outbound import ShutdownFailed
+from without_asgi.outbound import StartupComplete
+from without_asgi.outbound import StartupFailed
+from without_asgi.outbound import WebsocketClose
+from without_asgi.outbound import WebsocketOutbound
+from without_asgi.outbound import encode_lifespan_reply
+from without_asgi.outbound import encode_response
+from without_asgi.scope import HttpScope
+from without_asgi.scope import LifespanScope
+from without_asgi.scope import WebsocketScope
+from without_asgi.scope import parse_scope
+from without_asgi.shell import http_inbound
+from without_asgi.shell import http_outbound
+from without_asgi.shell import lifespan_inbound
+from without_asgi.shell import websocket_inbound
+from without_asgi.shell import websocket_outbound
+from without_asgi.types import ASGIApp
+from without_asgi.types import RawScope
+from without_asgi.types import Receive
+from without_asgi.types import Send
+
+# A `Lifespan` is a plain async context manager that sets up some state `T`,
+# yields it for the server's lifetime, and tears it down. It names no ASGI types
+# on purpose: the same value drives any shell (an ASGI server here, a queue
+# processor or a test elsewhere). Interdependent resources compose *inside* it
+# with nested `async with`, which also gives reverse-order teardown for free.
+type Lifespan[T] = Callable[[], AbstractAsyncContextManager[T]]
+
+# A `*Handler` is the `Processor` that serves one connection: it maps that
+# connection's inbound event stream to its outbound one, the same `Processor`
+# shape as every other `without` node, and is the only thing an app writes per
+# connection. A `*Router` selects the handler for a connection from the lifespan
+# state and the parsed scope: `make_asgi_app` calls it once per connection, then
+# owns the receive/send wiring around the returned handler (parsing inbound,
+# encoding outbound), so neither the router nor the handler touches the raw ASGI
+# callables. "Router" is the role even when it always returns the same handler (a
+# constant router that never dispatches on path is still one). The state is
+# threaded in per call rather than captured, so it stays a value the router is
+# handed, not a place it reaches into. HTTP and WebSocket have separate
+# router/handler pairs because their event types differ, which keeps an HTTP
+# handler from emitting a WebSocket event (and vice versa) by construction.
+type HttpHandler = Processor[Inbound, Outbound]
+type HttpRouter[T] = Callable[[T, HttpScope], HttpHandler]
+type WebsocketHandler = Processor[WebsocketInbound, WebsocketOutbound]
+type WebsocketRouter[T] = Callable[[T, WebsocketScope], WebsocketHandler]
+
+
+class _Unset:
+    pass
+
+
+_UNSET = _Unset()
+
+
+@dataclass(slots=True)
+class _Cell[T]:
+    # The one shared reference the ASGI process model forces: lifespan startup
+    # and each request are separate `app()` calls, so the state set up by the
+    # former must reach the latter through a place in the wrapper's closure. ASGI
+    # guarantees startup completes before any request, so `require` is never
+    # reached before `value` is set; the guard turns the can't-happen case into a
+    # loud failure rather than a silent `None`.
+    value: T | _Unset = _UNSET
+
+    def require(self) -> T:
+        if isinstance(self.value, _Unset):
+            raise RuntimeError("lifespan startup has not completed")
+        return self.value
+
+
+async def _drive[T](lifespan: Lifespan[T], cell: _Cell[T], receive: Receive, send: Send) -> None:
+    # The stack outlives the `startup` branch: it is entered when startup arrives
+    # and closed when shutdown arrives, two separate server messages with the
+    # `await receive()` for shutdown in between. A plain `async with` cannot
+    # straddle that gap, which is exactly why the lifespan protocol exists. The
+    # enclosing `async with` also guarantees teardown if the lifespan task is
+    # cancelled before shutdown is ever sent.
+    async with AsyncExitStack() as stack:
+        async for event in lifespan_inbound(receive):
+            match event:
+                case Startup():
+                    try:
+                        cell.value = await stack.enter_async_context(lifespan())
+                    except Exception as exc:  # noqa: BLE001 - ASGI lifespan reports any startup failure as StartupFailed
+                        await send(encode_lifespan_reply(StartupFailed(message=str(exc))))
+                        return
+                    await send(encode_lifespan_reply(StartupComplete()))
+                case Shutdown():
+                    try:
+                        await stack.aclose()
+                    except Exception as exc:  # noqa: BLE001 - ASGI lifespan reports any shutdown failure as ShutdownFailed
+                        await send(encode_lifespan_reply(ShutdownFailed(message=str(exc))))
+                        return
+                    await send(encode_lifespan_reply(ShutdownComplete()))
+                case _ as unreachable:
+                    assert_never(unreachable)
+
+
+# What the default routers refuse a connection with. An `http` scope gets `501
+# Not Implemented` (the HTTP status for "the server has no handler for this", as
+# opposed to `500` for an unexpected failure); a `websocket` scope is closed
+# before `accept`, which the ASGI server is required to turn into a `403`.
+_HTTP_UNSUPPORTED = Response(
+    status=501,
+    headers=((b"content-type", b"text/plain; charset=utf-8"),),
+    body=b"this application does not serve http\n",
+)
+_WEBSOCKET_UNSUPPORTED = WebsocketClose()
+
+
+# The default routers each `make_asgi_app` protocol falls back to, so an app
+# serves a protocol only by passing its own router to override the default. They
+# ignore the threaded state, hence `object`, which keeps them assignable as the
+# default for any `make_asgi_app[T]`.
+def refuse_http(state: object, head: HttpScope) -> HttpHandler:
+    """An `HttpRouter` that refuses every request with `501 Not Implemented`."""
+
+    def handler(inputs: Stream[Inbound]) -> Stream[Outbound]:
+        return stream_from_iterable(encode_response(_HTTP_UNSUPPORTED))
+
+    return handler
+
+
+def refuse_websocket(state: object, head: WebsocketScope) -> WebsocketHandler:
+    """A `WebsocketRouter` that refuses every connection by closing before `accept` (a `403`)."""
+
+    def handler(inputs: Stream[WebsocketInbound]) -> Stream[WebsocketOutbound]:
+        return stream_from_iterable((_WEBSOCKET_UNSUPPORTED,))
+
+    return handler
+
+
+def make_asgi_app[T](
+    lifespan: Lifespan[T],
+    http: HttpRouter[T] = refuse_http,
+    websocket: WebsocketRouter[T] = refuse_websocket,
+) -> ASGIApp:
+    """
+    Build the ASGI app that drives `lifespan` and runs a per-connection
+    `Processor` over each connection's event stream.
+
+    This is the ASGI entrypoint: it parses each raw scope into its typed value
+    and owns all the receive/send wiring. The `lifespan` scope is set up once on
+    `startup` and torn down on `shutdown`, with boot failures reported as
+    `lifespan.startup.failed` / `lifespan.shutdown.failed`. For a connection
+    scope it calls the matching handler with the state threaded in, wraps
+    `receive` into the inbound event stream, runs the returned `Processor`, and
+    drains its outbound stream into `send`: the handler only ever sees streams.
+
+    Each protocol's router defaults to one that refuses the connection, so an app
+    serves a protocol only by passing its own router (an HTTP-only app passes
+    `http`, a WebSocket-only app passes `websocket`). The default refusal never
+    reaches app code: an HTTP scope gets a `501 Not Implemented` response, a
+    WebSocket scope is closed before `accept` (which the server turns into a
+    `403`). Drilling under this driver, e.g. to build a handler that needs the raw
+    `receive`/`send`, is `parse_scope` plus the `http_inbound` / `http_outbound`
+    (and websocket) shell functions this wires together.
+    """
+    cell: _Cell[T] = _Cell()
+
+    async def app(scope: RawScope, receive: Receive, send: Send) -> None:
+        match parse_scope(scope):
+            case LifespanScope():
+                await _drive(lifespan, cell, receive, send)
+            case HttpScope() as head:
+                await http_outbound(send)(http(cell.require(), head)(http_inbound(receive)))
+            case WebsocketScope() as head:
+                await websocket_outbound(send)(websocket(cell.require(), head)(websocket_inbound(receive)))
+            case _ as unreachable:
+                assert_never(unreachable)
+
+    return app

without_asgi-0.0.1/src/without_asgi/inbound.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import assert_never
+
+from without_asgi.narrow import narrow_to_bytes
+from without_asgi.narrow import narrow_to_int
+from without_asgi.narrow import narrow_to_str
+from without_asgi.types import RawMessage
+from without_asgi.types import WebsocketData
+from without_asgi.types import decode_websocket_data
+from without_asgi.types import encode_websocket_data
+
+
+@dataclass(frozen=True, slots=True)
+class RequestBody:
+    body: bytes
+    more_body: bool
+
+
+@dataclass(frozen=True, slots=True)
+class Disconnect:
+    """The client went away before the request finished."""
+
+
+type Inbound = RequestBody | Disconnect
+
+
+@dataclass(frozen=True, slots=True)
+class WebsocketConnect:
+    """The client is opening a websocket and awaiting an accept or a close."""
+
+
+@dataclass(frozen=True, slots=True)
+class WebsocketReceive:
+    data: WebsocketData
+
+
+@dataclass(frozen=True, slots=True)
+class WebsocketDisconnect:
+    code: int
+    reason: str
+
+
+type WebsocketInbound = WebsocketConnect | WebsocketReceive | WebsocketDisconnect
+
+
+@dataclass(frozen=True, slots=True)
+class Startup:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Shutdown:
+    pass
+
+
+type LifespanEvent = Startup | Shutdown
+
+
+def _as_reason(value: object) -> str:
+    return "" if value is None else narrow_to_str(value)
+
+
+def parse_inbound(message: RawMessage) -> Inbound:
+    """Classify one inbound `http` event. An unknown event is a protocol fault, so it raises."""
+    match message.get("type"):
+        case "http.request":
+            return RequestBody(
+                body=narrow_to_bytes(message.get("body", b"")),
+                more_body=bool(message.get("more_body", False)),
+            )
+        case "http.disconnect":
+            return Disconnect()
+        case other:
+            raise ValueError(f"unexpected http event type: {other!r}")
+
+
+def parse_websocket_inbound(message: RawMessage) -> WebsocketInbound:
+    """Classify one inbound `websocket` event. An unknown event is a protocol fault, so it raises."""
+    match message.get("type"):
+        case "websocket.connect":
+            return WebsocketConnect()
+        case "websocket.receive":
+            return WebsocketReceive(data=decode_websocket_data(message))
+        case "websocket.disconnect":
+            return WebsocketDisconnect(
+                code=narrow_to_int(message.get("code", 1005)),
+                reason=_as_reason(message.get("reason")),
+            )
+        case other:
+            raise ValueError(f"unexpected websocket event type: {other!r}")
+
+
+def parse_lifespan_event(message: RawMessage) -> LifespanEvent:
+    """Classify one `lifespan` event. An unknown event is a protocol fault, so it raises."""
+    match message.get("type"):
+        case "lifespan.startup":
+            return Startup()
+        case "lifespan.shutdown":
+            return Shutdown()
+        case other:
+            raise ValueError(f"unexpected lifespan event type: {other!r}")
+
+
+def encode_inbound(event: Inbound) -> RawMessage:
+    """
+    Render one inbound `http` event as the raw dict an ASGI `receive` returns.
+
+    The server-direction dual of `parse_inbound`: a transport that owns the wire
+    (without-http) builds typed `Inbound` events and hands them to the app as the
+    dicts ASGI `receive` yields.
+    """
+    match event:
+        case RequestBody(body, more_body):
+            return {"type": "http.request", "body": body, "more_body": more_body}
+        case Disconnect():
+            return {"type": "http.disconnect"}
+        case _ as unreachable:
+            assert_never(unreachable)
+
+
+def encode_websocket_inbound(event: WebsocketInbound) -> RawMessage:
+    """Render one inbound `websocket` event as the raw dict an ASGI `receive` returns."""
+    match event:
+        case WebsocketConnect():
+            return {"type": "websocket.connect"}
+        case WebsocketReceive(data):
+            return {"type": "websocket.receive", **encode_websocket_data(data)}
+        case WebsocketDisconnect(code, reason):
+            return {"type": "websocket.disconnect", "code": code, "reason": reason}
+        case _ as unreachable:
+            assert_never(unreachable)
+
+
+def encode_lifespan_event(event: LifespanEvent) -> RawMessage:
+    """Render one `lifespan` event as the raw dict an ASGI `receive` returns."""
+    match event:
+        case Startup():
+            return {"type": "lifespan.startup"}
+        case Shutdown():
+            return {"type": "lifespan.shutdown"}
+        case _ as unreachable:
+            assert_never(unreachable)

without_asgi-0.0.1/src/without_asgi/narrow.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+
+def narrow[T](value: object, expected: type[T]) -> T:
+    """
+    Return `value` typed as `expected`, raising `TypeError` if it isn't.
+
+    The boundary reads ASGI scopes and messages as `Mapping[str, object]`, so
+    every field arrives as an untyped `object`. `narrow` turns one such value
+    into the concrete type the caller expects, failing loudly on a mismatch
+    rather than letting a wrong type flow inward.
+    """
+    if isinstance(value, expected):
+        return value
+    raise TypeError(f"expected {expected.__name__}, got {type(value).__name__}")
+
+
+def narrow_to_str(value: object) -> str:
+    return narrow(value, str)
+
+
+def narrow_to_bytes(value: object) -> bytes:
+    return narrow(value, bytes)
+
+
+def narrow_to_int(value: object) -> int:
+    return narrow(value, int)