millwork 0.1.0__py3-none-any.whl

millwork/protocol.py

@@ -0,0 +1,238 @@
+"""The wire protocol between a session on the server and a tab in the browser.
+
+Every message is JSON inside an envelope ``{"seq": n, "msg": {...}}``. The
+server numbers what it sends so a reconnecting tab can say how far it got;
+the client numbers its own messages the same way for logging. ``msg.type``
+discriminates the payload.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+PROTOCOL_VERSION = 3
+
+
+class Wire(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Node(Wire):
+    """One node of a page. Children are ids, so a page is a flat table."""
+
+    id: str
+    type: str
+    props: dict[str, Any] = Field(default_factory=dict)
+    children: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------- server -> client
+
+
+class Mount(Wire):
+    type: Literal["mount"] = "mount"
+    root: str
+    nodes: dict[str, Node]
+    title: str | None = None
+
+
+class SetOp(Wire):
+    op: Literal["set"] = "set"
+    id: str
+    props: dict[str, Any]
+
+
+class UnsetOp(Wire):
+    op: Literal["unset"] = "unset"
+    id: str
+    keys: list[str]
+
+
+class ChildrenOp(Wire):
+    op: Literal["children"] = "children"
+    id: str
+    children: list[str]
+
+
+class AddOp(Wire):
+    op: Literal["add"] = "add"
+    node: Node
+
+
+class RemoveOp(Wire):
+    op: Literal["remove"] = "remove"
+    id: str
+
+
+PatchOp = Annotated[SetOp | UnsetOp | ChildrenOp | AddOp | RemoveOp, Field(discriminator="op")]
+
+
+class Patch(Wire):
+    type: Literal["patch"] = "patch"
+    ops: list[PatchOp]
+
+
+class Stream(Wire):
+    """A chunk of the chat stream addressed to a Chat node. Never touches the tree."""
+
+    type: Literal["stream"] = "stream"
+    node: str
+    chunk: dict[str, Any]
+
+
+class Command(Wire):
+    type: Literal["command"] = "command"
+    name: str
+    args: dict[str, Any] = Field(default_factory=dict)
+
+
+class SessionInfo(Wire):
+    type: Literal["session"] = "session"
+    id: str
+    resume: str
+    protocol: int = PROTOCOL_VERSION
+    # Custom component versions, so a tab that outlived a deploy fetches fresh sources.
+    components: dict[str, str] = Field(default_factory=dict)
+
+
+class Ask(Wire):
+    type: Literal["ask"] = "ask"
+    request: str
+    node: str
+    timeout: float | None = None
+
+
+class ServerError(Wire):
+    type: Literal["error"] = "error"
+    message: str
+    fatal: bool = False
+
+
+class Head(Wire):
+    """A byte stream for a request starts: its metadata. Binary frames follow, then
+    the ``reply``."""
+
+    type: Literal["head"] = "head"
+    request: str
+    payload: Any = None
+
+
+class Reply(Wire):
+    """The end of a request: what it produced, or why it failed. Unnumbered: a
+    request lives within one socket connection and is never replayed."""
+
+    type: Literal["reply"] = "reply"
+    request: str
+    payload: Any = None
+    error: str | None = None
+
+
+ServerMessage = Annotated[
+    Mount | Patch | Stream | Command | SessionInfo | Ask | ServerError | Head | Reply,
+    Field(discriminator="type"),
+]
+
+
+# ---------------------------------------------------------------- client -> server
+
+
+class Hello(Wire):
+    type: Literal["hello"] = "hello"
+    path: str
+    session: str | None = None
+    resume: str | None = None
+    seq: int = 0
+    protocol: int = PROTOCOL_VERSION
+
+
+class Event(Wire):
+    type: Literal["event"] = "event"
+    node: str
+    name: str
+    payload: Any = None
+
+
+class Answer(Wire):
+    type: Literal["answer"] = "answer"
+    request: str
+    payload: Any = None
+
+
+class Navigate(Wire):
+    type: Literal["navigate"] = "navigate"
+    path: str
+
+
+# Printable ASCII, short: it goes into every binary frame's header as is.
+RequestId = Annotated[str, Field(min_length=1, max_length=32, pattern=r"^[\x21-\x7e]+$")]
+
+
+class Request(Wire):
+    """Something the session answers over the socket without a render: a handler's
+    return value (a Combobox ``search``), a file (``file``), or an upload (``upload``,
+    where ``size`` bytes follow as binary frames). The ``reply`` carries ``request``."""
+
+    type: Literal["request"] = "request"
+    node: str
+    name: str
+    request: RequestId
+    payload: Any = None
+    size: int | None = Field(default=None, ge=0)
+
+
+class Cancel(Wire):
+    type: Literal["cancel"] = "cancel"
+    request: RequestId
+
+
+ClientMessage = Annotated[
+    Hello | Event | Answer | Navigate | Request | Cancel, Field(discriminator="type")
+]
+
+
+class Envelope(Wire):
+    seq: int
+    msg: ServerMessage | ClientMessage
+
+
+server_message = TypeAdapter(ServerMessage)
+client_message = TypeAdapter(ClientMessage)
+
+
+def pack(seq: int, msg: BaseModel) -> str:
+    """Serialise one message for the wire."""
+    return Envelope(seq=seq, msg=msg).model_dump_json()  # type: ignore[arg-type]
+
+
+def unpack_client(text: str) -> tuple[int, Hello | Event | Answer | Navigate | Request | Cancel]:
+    """Parse one message from the browser. Raises ``pydantic.ValidationError``."""
+    env = Envelope.model_validate_json(text)
+    msg = client_message.validate_python(env.msg.model_dump())
+    return env.seq, msg
+
+
+# ---------------------------------------------------------------- binary frames
+
+# A chunk of a request's byte stream, either direction: one byte with the length
+# of the request id, the id in ASCII, then the bytes. Ids are short and ASCII by
+# construction (the tab makes them), so the header is at most 33 bytes.
+MAX_REQUEST_ID = 32
+
+
+def pack_frame(request: str, data: bytes) -> bytes:
+    rid = request.encode("ascii")
+    if not 0 < len(rid) <= MAX_REQUEST_ID:
+        raise ValueError("request id must be 1 to 32 ASCII characters")
+    return bytes([len(rid)]) + rid + data
+
+
+def unpack_frame(frame: bytes) -> tuple[str, bytes]:
+    """Raises ``ValueError`` for a frame that is not ours."""
+    if not frame:
+        raise ValueError("empty frame")
+    n = frame[0]
+    if not 0 < n <= MAX_REQUEST_ID or len(frame) < 1 + n:
+        raise ValueError("bad frame header")
+    return frame[1 : 1 + n].decode("ascii"), bytes(frame[1 + n :])

millwork/proxy.py

@@ -0,0 +1,122 @@
+"""A reverse proxy in front of the app.
+
+With ``App(proxied=True)``, or ``millwork run --proxied``, the process is
+behind a reverse proxy and believes what that proxy says: the visitor's
+address and scheme from ``X-Forwarded-For`` and ``X-Forwarded-Proto``, and
+the visitor's identity from the headers an ``auth.Headers`` provider names.
+Whoever can reach the process can then send those headers, so a proxied
+app listens where only its proxy connects: a unix socket, a loopback port,
+a container network.
+
+Without the switch the headers are ignored, which suits a process that
+browsers reach directly, as in development. The middleware records the
+switch in the scope as ``millwork.proxied`` for the auth layer.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any
+
+log = logging.getLogger("millwork.proxy")
+
+Scope = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[Any]]
+Send = Callable[[Any], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+class Proxied:
+    """ASGI middleware: see through the proxy when the app says there is one.
+
+    ``proxied`` is read on every connection, so the switch can be set after
+    the app was built, as the CLI does."""
+
+    def __init__(self, app: ASGIApp, proxied: Callable[[], bool]) -> None:
+        self.app = app
+        self.proxied = proxied
+        self._bad_root: str | None = None
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] in ("http", "websocket"):
+            if not self._root_ok(scope):
+                await _refuse(scope, send)
+                return
+            trusted = bool(self.proxied())
+            scope["millwork.proxied"] = trusted
+            if trusted:
+                _see_through(scope)
+        await self.app(scope, receive, send)
+
+    def _root_ok(self, scope: Scope) -> bool:
+        """The prefix the server was given must be plain path segments; one that
+        is not would fail inside every handler, the error page included."""
+        from millwork.shell import check_prefix
+
+        root = scope.get("root_path", "")
+        if root == self._bad_root:
+            return False
+        try:
+            check_prefix(root)
+        except ValueError as exc:
+            self._bad_root = root
+            log.error("every request refused: %s", exc)
+            return False
+        return True
+
+
+def _see_through(scope: Scope) -> None:
+    """The scheme and the visitor's address as the proxy forwarded them. A proxy
+    appends the address it saw to ``X-Forwarded-For``, so the last one is the
+    proxy's word and anything before it is whatever the browser sent."""
+    proto: bytes | None = None
+    forwarded: list[bytes] = []
+    for name, value in scope["headers"]:
+        if name == b"x-forwarded-proto":
+            proto = value
+        elif name == b"x-forwarded-for":
+            forwarded.append(value)
+    if proto is not None:
+        scheme = proto.decode("latin-1").strip().lower()
+        if scheme in ("http", "https", "ws", "wss"):
+            if scope["type"] == "websocket":
+                scheme = scheme.replace("http", "ws")
+            scope["scheme"] = scheme
+    if forwarded:
+        last = b", ".join(forwarded).decode("latin-1").split(",")[-1].strip()
+        host, port = _host_port(last)
+        if host:
+            scope["client"] = (host, port)
+
+
+def _host_port(value: str) -> tuple[str, int]:
+    """``host``, ``host:port`` or ``[v6]:port``; anything else is kept as given."""
+    if value.startswith("["):
+        end = value.find("]")
+        if end == -1:
+            return value, 0
+        rest = value[end + 1 :]
+        if rest[:1] == ":" and rest[1:].isdigit():
+            return value[1:end], int(rest[1:])
+        return value[1:end], 0
+    if value.count(":") == 1:
+        host, port = value.rsplit(":", 1)
+        if port.isdigit():
+            return host, int(port)
+    return value, 0
+
+
+async def _refuse(scope: Scope, send: Send) -> None:
+    if scope["type"] == "websocket":
+        await send({"type": "websocket.close", "code": 1011})
+        return
+    body = b"millwork: the server's root path is not a valid prefix; see the log"
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 500,
+            "headers": [(b"content-type", b"text/plain; charset=utf-8")],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})