composeui 0.1.0__py3-none-any.whl

composeui/webcore/headers.py

@@ -0,0 +1,57 @@
+"""The headers every response carries, whatever route or middleware answers it.
+
+- Scripts: the page runs only the app's own script files, so text that ever got past
+  the escaping (`Markup`) can't run as a script, inline or evaluated. Inline style
+  attributes stay allowed: the renderers lay out with them, and they run nothing.
+- Clickjacking: another site could show the app in a hidden frame, so the user's clicks
+  reach it from the app's own page, which the origin check (`origin.py`) lets through. So
+  no page of the app may be shown in a frame.
+- No MIME sniffing: a browser keeps to the content type each response says it is, so an
+  uploaded or served file can't run as a script or a page it doesn't say it is.
+- Referrer: the app's addresses aren't sent to other sites, and its own requests still
+  carry them, which the origin check falls back to.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from starlette.datastructures import MutableHeaders
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+
+#: scripts stay local; maps alone fetch raster tiles from OSM, without credentials
+POLICY = (
+    "default-src 'self'; script-src 'self'; style-src 'self';"
+    " style-src-attr 'unsafe-inline'; img-src 'self' data:; object-src 'none';"
+    " connect-src 'self' https://tile.openstreetmap.org;"
+    " base-uri 'none'; form-action 'self'; frame-ancestors 'none'"
+)
+
+
+class SecurityHeadersMiddleware:
+    """Add the content, framing, sniffing and referrer headers to every response."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def send_with_headers(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                headers = MutableHeaders(scope=message)
+                # beside a route's own (an icon's), which can then only be stricter
+                headers.append("Content-Security-Policy", POLICY)
+                # the older framing header, for browsers without `frame-ancestors`
+                headers["X-Frame-Options"] = "DENY"
+                # kept when a route sets them (e.g. an icon's)
+                headers.setdefault("X-Content-Type-Options", "nosniff")
+                headers.setdefault("Referrer-Policy", "same-origin")
+            await send(message)
+
+        await self.app(scope, receive, send_with_headers)

composeui/webcore/icons.py

@@ -0,0 +1,58 @@
+"""The image files the views name as icons, served at an address naming their content.
+
+Only a file a renderer has asked an address for is served: the views name them, from
+the app's code (`ActionView.icon` is never loaded from a study), so a request can't
+name a file of its own. One registry for the process: every session runs the same code.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+from pathlib import Path
+from typing import NamedTuple
+
+#: the file types served, by suffix: images a browser shows in an `<img>` or a mask
+_IMAGE_SUFFIXES = frozenset({".svg", ".png", ".gif", ".jpg", ".jpeg", ".webp", ".ico"})
+
+
+class _IconFile(NamedTuple):
+    mtime_ns: int
+    #: its name in its address: its content's digest, then its suffix
+    name: str
+
+
+_lock = threading.Lock()
+_by_path: dict[Path, _IconFile] = {}
+_by_name: dict[str, Path] = {}
+
+
+def icon_url(icon: str) -> str | None:
+    """Get the address serving the image file at `icon`; None if it isn't one.
+
+    A relative path is from the current directory, as Qt reads it. The address changes
+    with the file's content, so a browser can keep it as long as it likes.
+    """
+    path = Path(icon).resolve()
+    if path.suffix.lower() not in _IMAGE_SUFFIXES:
+        return None
+    try:
+        mtime_ns = path.stat().st_mtime_ns
+        with _lock:
+            known = _by_path.get(path)
+            if known is None or known.mtime_ns != mtime_ns:
+                digest = hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+                if known is not None:
+                    _by_name.pop(known.name, None)
+                known = _IconFile(mtime_ns, f"{digest}{path.suffix.lower()}")
+                _by_path[path] = known
+                _by_name[known.name] = path
+    except OSError:  # no such file: no icon, as on Qt
+        return None
+    return f"/icon/{known.name}"
+
+
+def icon_path(name: str) -> Path | None:
+    """Get the file served as `name` (see `icon_url`); None unless a view named it."""
+    with _lock:
+        return _by_name.get(name)

composeui/webcore/limits.py

@@ -0,0 +1,55 @@
+"""Refuse a request body larger than any upload the app accepts, before it is all read.
+
+The routes check an upload's size once they have it (`MAX_STATE_SIZE`, `MAX_FILE_SIZE`),
+but Starlette parses a whole multipart body first, spooling its files to temporary files
+with no limit: an upload of many gigabytes would fill the disk before that check runs.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from starlette.datastructures import Headers
+from starlette.exceptions import HTTPException
+from starlette.responses import PlainTextResponse
+
+from composeui.webcore.session import MAX_FILE_SIZE, MAX_STATE_SIZE
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+#: largest request body accepted, in bytes: the largest upload, and room around it for the
+#: form's other fields, so a file just too large still gets the route's own message
+MAX_BODY_SIZE = max(MAX_STATE_SIZE, MAX_FILE_SIZE) + 1024 * 1024
+
+
+class BodySizeLimitMiddleware:
+    """Answer 413 to a request whose body is larger than `max_size` bytes."""
+
+    def __init__(self, app: ASGIApp, max_size: int = MAX_BODY_SIZE) -> None:
+        self.app = app
+        self.max_size = max_size
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        length = Headers(scope=scope).get("content-length")
+        if length is not None and length.isdigit() and int(length) > self.max_size:
+            response = PlainTextResponse("Request body too large", status_code=413)
+            await response(scope, receive, send)
+            return
+        received = 0
+
+        async def limited_receive() -> Message:
+            # a body without a length (chunked), or longer than it said
+            nonlocal received
+            message = await receive()
+            if message["type"] == "http.request":
+                received += len(message.get("body", b""))
+                if received > self.max_size:
+                    # raised in the route reading the body: Starlette answers it
+                    raise HTTPException(413, "Request body too large")
+            return message
+
+        await self.app(scope, limited_receive, send)

composeui/webcore/origin.py

@@ -0,0 +1,63 @@
+"""Refuse requests that change a session from another origin (cross-site request forgery).
+
+The session cookie is `SameSite=Lax`, but "same site"
+ignores the port and spans sibling subdomains: a page on `localhost:9000` still sends it
+to an app on `localhost:8000`. So every unsafe request must prove it comes from the app's
+own pages, as OWASP's Fetch Metadata defense asks: `Sec-Fetch-Site`, else `Origin`, else
+`Referer`, else refused.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+from starlette.datastructures import URL, Headers
+from starlette.responses import PlainTextResponse
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp, Receive, Scope, Send
+
+#: methods that only read: every request changing a session uses another one
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+def is_same_origin(scope: Scope) -> bool:
+    """Tell whether the browser says the request comes from a page of this origin.
+
+    A browser sets these headers itself: no page can forge them. A request without any
+    is refused: it isn't evidence of a same-origin one (an old browser, or a proxy
+    stripping them).
+    """
+    headers = Headers(scope=scope)
+    site = headers.get("sec-fetch-site")
+    if site is not None:
+        return site == "same-origin"
+    url = URL(scope=scope)
+    own = f"{url.scheme}://{url.netloc}"
+    origin = headers.get("origin")
+    if origin is not None:
+        return origin == own  # "null" (e.g. a sandboxed frame) is never ours
+    referer = headers.get("referer")
+    if referer is not None:
+        parts = urlsplit(referer)
+        return f"{parts.scheme}://{parts.netloc}" == own
+    return False
+
+
+class SameOriginMiddleware:
+    """Answer 403 to an unsafe request (e.g. a POST) that another origin sent."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] == "http"
+            and scope["method"] not in SAFE_METHODS
+            and not is_same_origin(scope)
+        ):
+            response = PlainTextResponse("Cross-origin request refused", status_code=403)
+            await response(scope, receive, send)
+            return
+        await self.app(scope, receive, send)

composeui/webcore/page.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from string import Template
+
+from markupsafe import Markup, escape
+
+_STATIC = Path(__file__).parent / "static"
+
+
+def _static_url(name: str) -> str:
+    """Get the address of a static file, naming its content.
+
+    A new version of the file has a new address, so a browser never keeps using a copy it
+    cached of an older one (e.g. a stylesheet without the classes a new page uses).
+    """
+    digest = hashlib.sha256((_STATIC / name).read_bytes()).hexdigest()[:16]
+    return f"/static/{name}?v={digest}"
+
+
+# no `data-theme`: daisyUI then follows the browser's light/dark preference
+_PAGE = Template("""<!DOCTYPE html>
+<html lang="$language">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>$title</title>
+$icon_link
+<!-- no copies of past pages: going back or forward reloads the page from the server,
+     whose state they would contradict, at the address of a page of the app. Nothing
+     htmx would run or style inline, which the page's policy refuses (`headers.py`). -->
+<meta name="htmx-config" content='{"historyCacheSize": 0, "refreshOnHistoryMiss": true,
+  "allowEval": false, "allowScriptTags": false, "includeIndicatorStyles": false}' />
+<script src="$htmx_url"></script>
+<!-- built from css/app.css by `make css`: no CDN, so the page works offline -->
+<link href="$css_url" rel="stylesheet" type="text/css" />
+<script src="$page_url" data-uplot="$uplot_url" data-cally="$cally_url"
+  data-deckgl="$deckgl_url"></script>
+</head>
+
+<body class="bg-base-200 min-h-screen">
+<div id="app">
+$content
+</div>
+$page_marker
+$pollers
+<form id="$save_form" method="post" action="/state/download" hidden></form>
+</body>
+
+</html>
+""")
+
+
+#: read once: the files only change with a new version of the package
+_STATIC_URLS = {
+    # htmx 2.0.10 (https://github.com/bigskysoftware/htmx); `make web-deps` updates these files
+    "htmx_url": _static_url("htmx.min.js"),
+    # Tailwind and daisyUI 5.7.47 classes, daisyUI's license in daisyui.LICENSE
+    "css_url": _static_url("app.css"),
+    # a file, not inline: a policy can then allow the page's own scripts by address
+    "page_url": _static_url("page.js"),
+    # uPlot 1.6.32 (https://github.com/leeoniya/uPlot), its stylesheet in css/uPlot.min.css,
+    # its license in uPlot.LICENSE
+    "uplot_url": _static_url("uPlot.iife.min.js"),
+    # Cally 0.9.2 (https://github.com/WickyNilliams/cally), styled by daisyUI's `cally`
+    "cally_url": _static_url("cally.js"),
+    # deck.gl 9.2.6 (https://github.com/visgl/deck.gl), its license in deckgl.LICENSE
+    "deckgl_url": _static_url("deckgl.min.js"),
+}
+
+
+def page_marker(language: str, title: str, *, oob: bool = False) -> Markup:
+    """Get the element telling the page's script its `<html lang>` and `<title>`."""
+    swap = Markup(' hx-swap-oob="true"') if oob else Markup()
+    return Markup('<div id="cui-page" data-language="{}" data-title="{}"{} hidden></div>').format(
+        language, title, swap
+    )
+
+
+#: id of the form Save and Save As post, their button naming the action (`trigger`)
+SAVE_FORM_ID = "cui-save"
+
+
+#: milliseconds the page waits, while jobs run, before asking for what they changed
+JOBS_POLL_MS = 300
+
+
+def jobs_poller(*, is_running: bool, oob: bool = False) -> Markup:
+    """Get the element asking the server for what the jobs changed, while they run.
+
+    No response carries what a job's result changes (see `RenderTarget.pending`): while
+    the main view's jobs run, this element fetches itself every `JOBS_POLL_MS`, which
+    brings the changes along, until it comes back without a fetch once they are over.
+    """
+    swap = Markup(' hx-swap-oob="true"') if oob else Markup()
+    poll = (
+        Markup(' hx-get="/jobs" hx-trigger="load delay:{}ms" hx-swap="outerHTML"').format(
+            JOBS_POLL_MS
+        )
+        if is_running
+        else Markup()
+    )
+    return Markup('<div id="cui-jobs"{}{} hidden></div>').format(poll, swap)
+
+
+#: milliseconds between two asks, in a page of a ``--reload`` server, whether it restarted
+RELOAD_POLL_MS = 1000
+
+
+def reload_poller(instance: str | None) -> Markup:
+    """Get the element asking a ``--reload`` server whether it restarted; none without.
+
+    It asks every `RELOAD_POLL_MS`, naming `instance`, the server's process that served
+    the page. Another process answers with ``HX-Refresh``: the page reloads, with the
+    changed code and its session restored. An ask that fails while the server restarts is
+    asked again.
+    """
+    if instance is None:
+        return Markup()
+    return Markup(
+        '<div id="cui-reload" hx-get="/reload?instance={}" hx-trigger="every {}ms"'
+        ' hx-swap="none" hidden></div>'
+    ).format(instance, RELOAD_POLL_MS)
+
+
+def get_page(
+    title: str, content: Markup, language: str, *, pollers: Markup, icon: str | None = None
+) -> str:
+    """Get the app's page showing `content`, with the browser tab's `icon` at its address.
+
+    `pollers` are the elements asking the server for news: `jobs_poller`'s, and
+    `reload_poller`'s.
+    """
+    return _PAGE.substitute(
+        {
+            "title": escape(title),
+            "icon_link": Markup('<link rel="icon" href="{}" />').format(icon) if icon else "",
+            "content": content,
+            "language": escape(language),
+            "page_marker": page_marker(language, title),
+            "pollers": pollers,
+            "save_form": SAVE_FORM_ID,
+            **_STATIC_URLS,
+        }
+    )

composeui/webcore/routes.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from starlette.concurrency import run_in_threadpool
+from starlette.datastructures import UploadFile
+from starlette.responses import (
+    FileResponse,
+    HTMLResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    Response,
+    StreamingResponse,
+)
+
+from composeui.core import chartimage
+from composeui.webcore.icons import icon_path
+from composeui.webcore.session import MAX_FILE_SIZE, MAX_STATE_SIZE
+from composeui.webcore.webrenderer import UnsupportedEventError
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from composeui.webcore.session import SessionStore, WebSession
+
+#: Every page and fragment reflects live server state: a browser reusing a cached copy
+#: (or restoring the fields of one) would show values the server no longer has, e.g.
+#: after a server restart.
+_NO_STORE = {"Cache-Control": "no-store"}
+#: Answer to a widget request whose session is gone (expired, or the server restarted):
+#: htmx reloads the page, which starts a fresh session, instead of the request failing.
+_RELOAD = {**_NO_STORE, "HX-Refresh": "true"}
+#: An icon's address names its content (see `icons.py`), so it never changes; an SVG
+#: opened on its own runs no script and loads nothing.
+_ICON_HEADERS = {
+    "Cache-Control": "public, max-age=31536000, immutable",
+    "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
+    "X-Content-Type-Options": "nosniff",
+}
+#: key of the session id in Starlette's signed session cookie
+SESSION_KEY = "composeui_session"
+
+
+def _store(request: Request) -> SessionStore:
+    store: SessionStore = request.app.state.sessions
+    return store
+
+
+def _session(request: Request) -> WebSession | None:
+    return _store(request).get(request.session.get(SESSION_KEY))
+
+
+def _session_or_new(request: Request) -> WebSession | None:
+    """Get the request's session, or a new one; None while the server has too many."""
+    session = _session(request)
+    if session is None:
+        created = _store(request).create()
+        if created is None:
+            return None
+        session_id, session = created
+        request.session[SESSION_KEY] = session_id
+    return session
+
+
+def _reload_instance(request: Request) -> str | None:
+    """Get the id of this process of a ``--reload`` server; None for another server."""
+    instance: str | None = request.app.state.reload_instance
+    return instance
+
+
+def _too_many_sessions() -> Response:
+    return PlainTextResponse(
+        "Too many sessions are open: try again later.", status_code=503, headers=_NO_STORE
+    )
+
+
+def homepage(request: Request) -> Response:
+    """Show the app; one with pages is sent to its first page's address."""
+    session = _session_or_new(request)
+    if session is None:
+        return _too_many_sessions()
+    path = session.home_path()
+    if path is not None:
+        return RedirectResponse(path, status_code=303, headers=_NO_STORE)
+    return HTMLResponse(session.page_html(_reload_instance(request)), headers=_NO_STORE)
+
+
+def page(request: Request) -> Response:
+    """Show the app on the page of the address's route (`/<route>`).
+
+    An address no page has is not found, rather than sent to a page: a browser asks
+    for addresses of its own (e.g. `/favicon.ico`), which must not navigate.
+    """
+    session = _session_or_new(request)
+    if session is None:
+        return _too_many_sessions()
+    if not session.open_route(request.path_params["route"]):
+        return PlainTextResponse("Not Found", status_code=404, headers=_NO_STORE)
+    return HTMLResponse(session.page_html(_reload_instance(request)), headers=_NO_STORE)
+
+
+def reload_poll(request: Request) -> Response:
+    """Tell a page of a ``--reload`` server whether another process of it served the page.
+
+    Then its answer reloads the page (``HX-Refresh``), which runs the changed code. Only
+    a read: the next request restores the session (`SessionStore`). A server without
+    ``--reload`` reloads the page too: a tab a ``--reload`` server served, left open on
+    its address, would else ask it every second, for ever.
+    """
+    instance = _reload_instance(request)
+    if instance is not None and request.query_params.get("instance") == instance:
+        return Response(status_code=204, headers=_NO_STORE)
+    return Response(headers=_RELOAD)
+
+
+async def widget_event(request: Request) -> Response:
+    """Dispatch a browser event to a widget; respond with every fragment it changed."""
+    session = _session(request)
+    if session is None:
+        return Response(headers=_RELOAD)
+    form = await request.form()
+    fields = {name: value for name, value in form.items() if isinstance(value, str)}
+    event = fields.pop("event", "")
+    widget_id = request.path_params["widget_id"]
+    try:
+        # view callbacks are plain sync code: keep them off the event loop
+        result = await run_in_threadpool(session.handle_event, widget_id, event, fields)
+    except UnsupportedEventError as e:
+        return PlainTextResponse(str(e), status_code=400)
+    if result is None:
+        return PlainTextResponse("Unknown widget", status_code=404)
+    return _widget_response(request, session, *result)
+
+
+def _widget_response(
+    request: Request, session: WebSession, body: str, path: str | None
+) -> Response:
+    """Answer a widget request with the fragments it changed, `body`, and its page."""
+    if session.closed:
+        # e.g. Exit: end the session; the page it lands on starts a fresh one
+        _store(request).drop(request.session.get(SESSION_KEY))
+        return Response(headers={**_NO_STORE, "HX-Redirect": "/"})
+    # a navigation puts the new page's address in the browser's history
+    headers = _NO_STORE if path is None else {**_NO_STORE, "HX-Push-Url": path}
+    return HTMLResponse(body, headers=headers)
+
+
+async def widget_file(request: Request) -> Response:
+    """Hand an uploaded file to a `PickFileAction`; respond as `widget_event` does."""
+    session = _session(request)
+    if session is None:
+        return Response(headers=_RELOAD)
+    form = await request.form(max_files=1)
+    upload = form.get("file")
+    if not isinstance(upload, UploadFile):
+        return PlainTextResponse("No file uploaded", status_code=400)
+    # one byte over the limit is enough to know the file is too large
+    content = await upload.read(MAX_FILE_SIZE + 1)
+    widget_id = request.path_params["widget_id"]
+    try:
+        result = await run_in_threadpool(
+            session.pick_file, widget_id, upload.filename or "", content
+        )
+    except UnsupportedEventError as e:
+        return PlainTextResponse(str(e), status_code=400)
+    if result is None:
+        return PlainTextResponse("Unknown widget", status_code=404)
+    return _widget_response(request, session, *result)
+
+
+def widget_fragment(request: Request) -> Response:
+    """Return a widget's current fragment (e.g. a status bar whose message timed out)."""
+    session = _session(request)
+    if session is None:
+        return Response(headers=_RELOAD)
+    body = session.fragment(request.path_params["widget_id"])
+    if body is None:
+        return PlainTextResponse("Unknown widget", status_code=404)
+    return HTMLResponse(body, headers=_NO_STORE)
+
+
+async def chart_image(request: Request) -> Response:
+    """Download a chart's image as a report's figure, drawn by matplotlib at its zoom.
+
+    A plain link, like the state's download. Without matplotlib (the `report` extra), not
+    found: the page draws its PNG itself.
+    """
+    session = _session(request)
+    if session is None:
+        return RedirectResponse("/", status_code=303)
+    if not chartimage.is_available():
+        return PlainTextResponse("Not Found", status_code=404)
+    query = dict(request.query_params)
+    image_format = query.pop("format", "pdf").lower()
+    widget_id = request.path_params["widget_id"]
+    try:
+        # matplotlib takes a while: off the event loop
+        result = await run_in_threadpool(session.chart_image, widget_id, image_format, query)
+    except ValueError as error:
+        return PlainTextResponse(str(error), status_code=400)
+    if result is None:
+        return PlainTextResponse("Unknown widget", status_code=404)
+    filename, body = result
+    headers = {**_NO_STORE, "Content-Disposition": _attachment(filename)}
+    return Response(body, media_type=chartimage.MEDIA_TYPES[image_format], headers=headers)
+
+
+def _attachment(filename: str) -> str:
+    """Get the `Content-Disposition` of a download named `filename`."""
+    # the name's own letters, which a header's latin-1 may not have, and a fallback
+    ascii_name = filename.encode("ascii", "replace").decode().replace("?", "_")
+    return f"attachment; filename=\"{ascii_name}\"; filename*=UTF-8''{quote(filename)}"
+
+
+def table_csv(request: Request) -> Response:
+    """Download a large table's rows shown as CSV, streamed a window of rows at a time.
+
+    A plain link, like a chart's image: it only reads.
+    """
+    session = _session(request)
+    if session is None:
+        return RedirectResponse("/", status_code=303)
+    result = session.table_csv(request.path_params["widget_id"])
+    if result is None:
+        return PlainTextResponse("Unknown widget", status_code=404)
+    filename, chunks = result
+    headers = {**_NO_STORE, "Content-Disposition": _attachment(filename)}
+    return StreamingResponse(chunks, media_type="text/csv; charset=utf-8", headers=headers)
+
+
+def jobs_poll(request: Request) -> Response:
+    """Return the jobs' poller and what they changed, which it fetches while they run."""
+    session = _session(request)
+    if session is None:
+        return Response(headers=_RELOAD)
+    return HTMLResponse(session.poll_jobs(), headers=_NO_STORE)
+
+
+def state_download(request: Request) -> Response:
+    """Download the session's state as a file, the web side of `MainView.save_state`.
+
+    A plain link, not htmx (htmx can't start downloads); without a session, the
+    browser is sent to the page, which starts one.
+    """
+    session = _session(request)
+    if session is None:
+        return RedirectResponse("/", status_code=303)
+    return _state_file(session)
+
+
+async def state_save(request: Request) -> Response:
+    """Fire Save's own `triggered`, then download the state as `state_download` does.
+
+    A form's post rather than a link: the action changes the session, which a GET must
+    not (a link from another site would fire it).
+    """
+    session = _session(request)
+    if session is None:
+        return RedirectResponse("/", status_code=303)
+    trigger = (await request.form()).get("trigger")
+    if isinstance(trigger, str):
+        await run_in_threadpool(session.trigger_action, trigger)
+    return _state_file(session)
+
+
+def _state_file(session: WebSession) -> Response:
+    filename, body, media_type = session.save_state()
+    headers = {**_NO_STORE, "Content-Disposition": f'attachment; filename="{filename}"'}
+    return Response(body, media_type=media_type, headers=headers)
+
+
+async def state_upload(request: Request) -> Response:
+    """Load an uploaded state file, the web side of `MainView.load_state`.
+
+    A load can change any part of the tree, so instead of collecting fragments the page
+    reloads; a rejected file leaves the state alone and says why in the status bar.
+    """
+    session = _session(request)
+    if session is None:
+        return Response(headers=_RELOAD)
+    form = await request.form(max_files=1)
+    upload = form.get("file")
+    if not isinstance(upload, UploadFile):
+        return PlainTextResponse("No file uploaded", status_code=400)
+    trigger = form.get("trigger")
+    if isinstance(trigger, str):
+        # e.g. Open's own `triggered`, before the file is loaded
+        await run_in_threadpool(session.trigger_action, trigger)
+    # one byte over the limit is enough to know the file is too large
+    content = await upload.read(MAX_STATE_SIZE + 1)
+    status_bar = await run_in_threadpool(session.load_state, upload.filename or "", content)
+    if status_bar is None:
+        return Response(headers=_RELOAD)
+    return HTMLResponse(status_bar, headers=_NO_STORE)
+
+
+def icon(request: Request) -> Response:
+    """Serve an icon file a view named; any other name is not found."""
+    path = icon_path(request.path_params["name"])
+    if path is None or not path.is_file():
+        return PlainTextResponse("Not Found", status_code=404)
+    return FileResponse(path, headers=_ICON_HEADERS)