A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
fix: misc host protocol fixes (#11222)
Kiran Gadhavecc8628f390e9
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex 6430914edd..a9bd562811 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -1418,7 +1418,7 @@ class Problem(Struct, frozen=True):type: Annotated[str,Meta(- description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `not-acceptable` (406),\n`conflict` (409), `no-runtime` (409), `decision-required`\n(409), `internal` (500), or `unsupported-operation` (501). A\nclient that sees a kind it does not recognize falls back to\n`status`.\n"+ description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `method-not-allowed`\n(405), `not-acceptable` (406), `conflict` (409), `no-runtime`\n(409), `decision-required` (409), `internal` (500), or\n`unsupported-operation` (501). A client that sees a kind it\ndoes not recognize falls back to `status`.\n"),]decisions: (diff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex 059dded3a4..ddad41f112 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -14,7 +14,7 @@ from contextlib import contextmanagerfrom copy import deepcopyfrom dataclasses import dataclassfrom datetime import datetime, timezone-from typing import TypeAlias+from typing import TypeAlias, get_argsimport msgspecfrom msgspec import UNSET@@ -23,23 +23,6 @@ from marimo._core import protocolLOGGER = logging.getLogger(__name__)-CATALOG_KINDS = frozenset(- {"host", "project", "notebook", "runtime", "attachment"}-)-NOTEBOOK_KINDS = frozenset(- {- "notebook",- "runtime",- "attachment",- "run",- "execution",- "console",- "display",- "custom",- }-)--Body: TypeAlias = (protocol.Host| protocol.Project@@ -52,24 +35,30 @@ Body: TypeAlias = (| protocol.Display| protocol.Custom)+"""Every object a stream carries. The wrapper map and the notebook kinds+derive from it; the catalog kinds are a chosen subset."""-_WRAPPERS: dict[str, type[msgspec.Struct]] = {- "host": protocol.HostMessage,- "project": protocol.ProjectMessage,- "notebook": protocol.NotebookMessage,- "runtime": protocol.RuntimeMessage,- "attachment": protocol.AttachmentMessage,- "run": protocol.RunMessage,- "execution": protocol.ExecutionMessage,- "console": protocol.ConsoleMessage,- "display": protocol.DisplayMessage,- "custom": protocol.CustomMessage,-}++def _kind(body_type: type[msgspec.Struct]) -> str:+ return body_type.__name__.lower()def kind_of(body: Body) -> str:"""Return the object's event kind, used by the `types` filter."""- return type(body).__name__.lower()+ return _kind(type(body))+++_WRAPPERS: dict[str, type[msgspec.Struct]] = {+ _kind(body_type): getattr(protocol, f"{body_type.__name__}Message")+ for body_type in get_args(Body)+}++CATALOG_KINDS = frozenset(+ {"host", "project", "notebook", "runtime", "attachment"}+)+# Host and project describe the whole host, so they never belong to one+# notebook's stream. Every other kind does.+NOTEBOOK_KINDS = frozenset(_WRAPPERS) - {"host", "project"}def message(diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex b278f6dd5b..f191dfcd86 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -9,7 +9,7 @@ import threadingfrom collections.abc import Awaitable, Callablefrom functools import wrapsfrom pathlib import Path-from typing import TYPE_CHECKING, TypeAlias, TypeVar+from typing import TYPE_CHECKING, TypeAlias, TypeVar, get_argsfrom urllib.parse import quoteimport msgspec@@ -31,7 +31,6 @@ if TYPE_CHECKING:from collections.abc import AsyncIteratorfrom starlette.requests import Request- from starlette.types import ASGIAppfrom marimo._core.notebook import Notebookfrom marimo._core.stream import Event@@ -59,11 +58,15 @@ _ATTACHMENT_HEADERS = {PING = b": ping\n\n"PING_SECONDS = 15.0+OBJECT_TYPES = frozenset(get_args(get_args(protocol.ObjectType)[0]))+"""Values the `types` stream filter accepts."""+_TITLES = {"invalid-request": "Invalid request","unauthorized": "Unauthorized","forbidden": "Forbidden","not-found": "Not found",+ "method-not-allowed": "Method not allowed","conflict": "Conflict","no-runtime": "No runtime","unsupported-operation": "Unsupported operation",@@ -71,8 +74,28 @@ _TITLES = {}-def problem(status: int, kind: str, detail: str | None = None) -> Response:- """Return a protocol error as an HTTP problem response."""+_HTTP_KINDS = {+ 400: "invalid-request",+ 404: "not-found",+ 405: "method-not-allowed",+ 409: "conflict",+}+++def problem(+ status: int, kind: str | None = None, detail: str | None = None+) -> Response:+ """Return a protocol error as an HTTP problem response.++ Without a kind, the status picks one. A status this protocol does+ not name is a server bug, so it becomes a 500 rather than a problem+ of an unknown kind.+ """+ kind = _HTTP_KINDS.get(status) if kind is None else kind++ if kind is None:+ LOGGER.error("The host API raised an unmapped status %s", status)+ status, kind, detail = 500, "internal", "The host failed"body = protocol.Problem(type=PROBLEM_TYPE_PREFIX + kind,title=_TITLES[kind],@@ -86,33 +109,39 @@ def problem(status: int, kind: str, detail: str | None = None) -> Response:)-def build_app() -> ASGIApp:+def build_app() -> Router:"""Build the host API router."""+ routes = [+ Route("/events", _events, methods=["GET"]),+ Route("/notebooks", _create_notebook, methods=["POST"]),+ Route("/notebooks/{id}", _update_notebook, methods=["PATCH"]),+ Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),+ Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),+ Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),+ Route("/notebooks/{id}/runtime", _start_runtime, methods=["PUT"]),+ Route("/notebooks/{id}/runtime", _stop_runtime, methods=["DELETE"]),+ Route(+ "/notebooks/{id}/runtime/restart",+ _restart_runtime,+ methods=["POST"],+ ),+ Route("/notebooks/{id}/runtime/runs", _run, methods=["POST"]),+ Route(+ "/notebooks/{id}/runtime/runs/{run_id}",+ _interrupt,+ methods=["DELETE"],+ ),+ ]+ for route in routes:+ # Starlette implies HEAD for every GET route, but a HEAD here would+ # open a real stream and attach a client nobody can see.+ if route.methods == {"GET", "HEAD"}:+ route.methods = {"GET"}return Router(- routes=[- Route("/events", _events, methods=["GET"]),- Route("/notebooks", _create_notebook, methods=["POST"]),- Route("/notebooks/{id}", _update_notebook, methods=["PATCH"]),- Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),- Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),- Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),- Route("/notebooks/{id}/runtime", _start_runtime, methods=["PUT"]),- Route(- "/notebooks/{id}/runtime", _stop_runtime, methods=["DELETE"]- ),- Route(- "/notebooks/{id}/runtime/restart",- _restart_runtime,- methods=["POST"],- ),- Route("/notebooks/{id}/runtime/runs", _run, methods=["POST"]),- Route(- "/notebooks/{id}/runtime/runs/{run_id}",- _interrupt,- methods=["DELETE"],- ),- ],+ routes=routes,default=_not_found,+ # Clients never follow redirects, so a trailing slash is a miss.+ redirect_slashes=False,)@@ -316,12 +345,7 @@ async def _execute_mutation(endpoint: _Endpoint, request: Request) -> Response:except msgspec.DecodeError as e:return problem(400, "invalid-request", str(e))except HTTPException as e:- kind = {- 400: "invalid-request",- 404: "not-found",- 409: "conflict",- }[e.status_code]- return problem(e.status_code, kind, e.detail)+ return problem(e.status_code, detail=e.detail)def _reply(status: int, body: msgspec.Struct | None = None) -> Response:@@ -348,9 +372,12 @@ async def _events(request: Request) -> Response:cursor = _cursor(request)if isinstance(cursor, Response):return cursor+ types = _types(request)+ if isinstance(types, Response):+ return types# Refresh on connection because the catalog has no directory watcher.await context.bridge.refresh()- return _stream(context, cursor, _types(request), notebook_id=None)+ return _stream(context, cursor, types, notebook_id=None)async def _notebook_events(request: Request) -> Response:@@ -363,6 +390,9 @@ async def _notebook_events(request: Request) -> Response:cursor = _cursor(request)if isinstance(cursor, Response):return cursor+ types = _types(request)+ if isinstance(types, Response):+ return typesrun_id = request.query_params.get("run_id")if run_id == "":return problem(400, "invalid-request", "run_id must not be empty")@@ -377,7 +407,7 @@ async def _notebook_events(request: Request) -> Response:return _stream(context,cursor,- _types(request),+ types,notebook_id=notebook.id,run_id=run_id,on_close=lambda: notebook.detach(attachment.id),@@ -388,16 +418,28 @@ def _cursor(request: Request) -> int | Response | None:raw = request.headers.get("Last-Event-ID")if raw is None:return None- if not raw.isdigit():+ # Header text is latin-1, where superscripts count as digits.+ if not (raw.isascii() and raw.isdigit()):return problem(400, "invalid-request", "Last-Event-ID must be an id")- return int(raw)+ try:+ return int(raw)+ except ValueError:+ return problem(400, "invalid-request", "Last-Event-ID is too long")-def _types(request: Request) -> set[str] | None:+def _types(request: Request) -> set[str] | Response | None:asked = request.query_params.get("types")if not asked:return None- return {kind for kind in asked.split(",") if kind}+ types = {kind for kind in asked.split(",") if kind}+ unknown = types - OBJECT_TYPES+ if unknown:+ return problem(+ 400,+ "invalid-request",+ f"types has no kind named {', '.join(sorted(unknown))}",+ )+ return typesdef _attachment_problem(error: msgspec.ValidationError) -> str:@@ -471,6 +513,8 @@ def _frame(event: Event) -> bytes:def _inside_project(path: str) -> Path:+ if "\x00" in path:+ raise HTTPException(400, "path must not contain NUL")relative = Path(path)if relative.is_absolute() or ".." in relative.parts:raise HTTPException(400, "path must stay in the project")@@ -507,6 +551,8 @@ async def _update_notebook(request: Request) -> Response:record = _record(request)body = await _decode(request, protocol.UpdateNotebookRequest)+ if body.path is msgspec.UNSET and body.name is msgspec.UNSET:+ raise HTTPException(400, "path or name is required")index = context.bridge.indextarget = Noneif body.path is not msgspec.UNSET:diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.pyindex b73894c5f4..008667ba3a 100644--- a/marimo/_server/host/lifespan.py+++ b/marimo/_server/host/lifespan.py@@ -45,17 +45,22 @@ async def host(app: Starlette) -> AsyncIterator[None]:context.expire()maintenance = asyncio.create_task(maintain(), name="host.retention")- record = HostRecordFile(url=url, token=token)- try:- record.write()- except Exception as e:- LOGGER.warning("Could not write the host record: %s", e)+ record = None+ if url is None:+ LOGGER.warning("No host record: loopback cannot reach %s", server.host)+ else:+ record = HostRecordFile(url=url, token=token)+ try:+ record.write()+ except Exception as e:+ LOGGER.warning("Could not write the host record: %s", e)try:yieldfinally:maintenance.cancel()with contextlib.suppress(asyncio.CancelledError):await maintenance- record.remove()+ if record is not None:+ record.remove()bridge.close()app.state.host_context = Nonediff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.pyindex 5fc706f745..c057d463cb 100644--- a/marimo/_server/host/middleware.py+++ b/marimo/_server/host/middleware.py@@ -8,20 +8,29 @@ server's port. The bearer token comes from the host discovery record.from __future__ import annotationsimport hmac+import refrom ipaddress import IPv6Address, ip_addressfrom typing import TYPE_CHECKING+from starlette.exceptions import HTTPExceptionfrom starlette.requests import Request+from starlette.routing import Match, Routefrom marimo import _loggersfrom marimo._server.host import HOST_API_PATHfrom marimo._server.host.api import build_app, problemif TYPE_CHECKING:- from starlette.types import ASGIApp, Receive, Scope, Send+ from collections.abc import Sequence++ from starlette.responses import Response+ from starlette.routing import BaseRoute+ from starlette.types import ASGIApp, Message, Receive, Scope, SendLOGGER = _loggers.marimo_logger()+_PORT = re.compile(r"[0-9]{1,5}")+class HostApiMiddleware:"""Authenticate and route host API requests."""@@ -58,11 +67,30 @@ class HostApiMiddleware:response = problem(401, "unauthorized", "Send the host record's token as a bearer")+ response.headers["WWW-Authenticate"] = "Bearer"else:scope = {**scope, "root_path": self.prefix}+ started = False++ async def guarded(message: Message) -> None:+ nonlocal started+ if message["type"] == "http.response.start":+ started = True+ await send(message)+try:- await self.host_app(scope, receive, send)+ await self.host_app(scope, receive, guarded)+ except HTTPException as exc:+ if started:+ raise+ # The bare router has no exception middleware, so a known+ # path with an unsupported method surfaces here as a 405.+ response = _router_problem(exc, scope, self.host_app.routes)+ await response(scope, receive, send)except Exception:+ if started:+ # The server logs the failure once it ends the stream.+ raiseLOGGER.exception("The host API failed on %s", scope["path"])response = problem(500, "internal", "The host failed")await response(scope, receive, send)@@ -73,8 +101,34 @@ class HostApiMiddleware:return path == self.prefix or path.startswith(self.prefix + "/")+def _router_problem(+ exc: HTTPException, scope: Scope, routes: Sequence[BaseRoute]+) -> Response:+ response = problem(exc.status_code, detail=exc.detail)+ if exc.status_code == 405:+ # The router names only the first route that matched the path, but+ # a path can be declared once per method.+ response.headers["Allow"] = ", ".join(+ sorted(_methods_declared_for(scope, routes))+ )+ return response+++def _methods_declared_for(+ scope: Scope, routes: Sequence[BaseRoute]+) -> set[str]:+ methods: set[str] = set()+ for route in routes:+ if (+ isinstance(route, Route)+ and route.matches(scope)[0] is not Match.NONE+ ):+ methods.update(route.methods or ())+ return methods++def _is_loopback(host: str) -> bool:- if host == "localhost":+ if host.lower() == "localhost":return Truetry:address = ip_address(host)@@ -90,16 +144,18 @@ def _host_header_ok(header: str | None, port: int) -> bool:if header is None:return Falseif header.startswith("["):- name, _, after = header.partition("]")+ name, closed, after = header.partition("]")+ if not closed or (after and not after.startswith(":")):+ return Falsename = name[1:]- given = after[1:] if after.startswith(":") else ""+ given = after[1:]else:name, _, given = header.partition(":")if not _is_loopback(name):return Falseif given == "":return port == 80- return given.isdigit() and int(given) == port+ return _PORT.fullmatch(given) is not None and int(given) == portdef _bearer_matches(authorization: str | None, token: str) -> bool:@@ -108,4 +164,7 @@ def _bearer_matches(authorization: str | None, token: str) -> bool:scheme, _, credentials = authorization.partition(" ")if scheme.lower() != "bearer":return False- return hmac.compare_digest(credentials.strip(), token)+ # Header text is latin-1, and compare_digest rejects non-ASCII str.+ return hmac.compare_digest(+ credentials.strip().encode("latin-1"), token.encode()+ )diff --git a/marimo/_server/host/record.py b/marimo/_server/host/record.pyindex f8bcd31fed..db0414aa12 100644--- a/marimo/_server/host/record.py+++ b/marimo/_server/host/record.py@@ -7,6 +7,7 @@ import atexitimport osimport tempfilefrom datetime import datetime, timezone+from ipaddress import IPv6Address, ip_addressfrom uuid import uuid4import msgspec@@ -19,9 +20,31 @@ from marimo._utils.xdg import marimo_state_dirLOGGER = _loggers.marimo_logger()-def host_url(host: str, port: int, base_url: str) -> str:- """Build a loopback URL for the host API."""- loopback = "[::1]" if host.strip("[]") == "::1" else "127.0.0.1"+def host_url(host: str, port: int, base_url: str) -> str | None:+ """Build the loopback URL for the host API.++ Returns None when the server binds an address that loopback cannot+ reach, because a record would then name a URL nobody can open.+ """+ name = host.strip("[]")+ if name.lower() == "localhost":+ loopback = "127.0.0.1"+ else:+ try:+ address = ip_address(name)+ except ValueError:+ return None+ if isinstance(address, IPv6Address) and address.ipv4_mapped:+ # Only Python 3.13 treats a mapped loopback as loopback.+ address = address.ipv4_mapped+ if address.is_unspecified:+ # A wildcard IPv6 bind is v6-only, so its loopback is ::1.+ loopback = "[::1]" if address.version == 6 else "127.0.0.1"+ elif address.is_loopback:+ # A socket bound to one loopback address refuses the others.+ loopback = f"[{address}]" if address.version == 6 else str(address)+ else:+ return Nonereturn f"http://{loopback}:{port}{base_url}{HOST_API_PATH}"diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex e27cb379cb..d19c2e47db 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -88,6 +88,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'500': { $ref: '#/components/responses/Internal' }/notebooks:post:@@ -120,6 +121,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -151,6 +153,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -170,6 +173,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -260,6 +264,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'500': { $ref: '#/components/responses/Internal' }/notebooks/{notebook_id}/edits:post:@@ -310,6 +315,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -353,6 +359,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -380,6 +387,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -424,6 +432,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -451,6 +460,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -480,6 +490,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -532,6 +543,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -561,6 +573,7 @@ paths:'401': { $ref: '#/components/responses/Unauthorized' }'403': { $ref: '#/components/responses/Forbidden' }'404': { $ref: '#/components/responses/NotFound' }+ '405': { $ref: '#/components/responses/MethodNotAllowed' }'409': { $ref: '#/components/responses/Conflict' }'500': { $ref: '#/components/responses/Internal' }'501': { $ref: '#/components/responses/UnsupportedOperation' }@@ -696,6 +709,15 @@ components:content:application/problem+json:schema: { $ref: '#/components/schemas/Problem' }+ MethodNotAllowed:+ description: The route exists but not for this method. `Allow` lists the methods it accepts.+ headers:+ Allow:+ schema: { type: string }+ description: The methods this route accepts, comma separated.+ content:+ application/problem+json:+ schema: { $ref: '#/components/schemas/Problem' }NotAcceptable:description: No representation the host produces satisfies `Accept`.content:@@ -1488,11 +1510,11 @@ components:What kind of problem this is, as a URI. The kinds thisprotocol defines all start with `tag:marimo.io,2026:host/` andend with one of `invalid-request` (400), `unauthorized` (401),- `forbidden` (403), `not-found` (404), `not-acceptable` (406),- `conflict` (409), `no-runtime` (409), `decision-required`- (409), `internal` (500), or `unsupported-operation` (501). A- client that sees a kind it does not recognize falls back to- `status`.+ `forbidden` (403), `not-found` (404), `method-not-allowed`+ (405), `not-acceptable` (406), `conflict` (409), `no-runtime`+ (409), `decision-required` (409), `internal` (500), or+ `unsupported-operation` (501). A client that sees a kind it+ does not recognize falls back to `status`.example: tag:marimo.io,2026:host/not-foundtitle:type: stringdiff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.pyindex c0d15b0e97..cacd3ad324 100644--- a/tests/_core/test_stream.py+++ b/tests/_core/test_stream.py@@ -3,12 +3,23 @@from __future__ import annotations+from typing import get_args++import msgspecimport pytestfrom marimo._core import backend as be, protocolfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook-from marimo._core.stream import Event, Stream, kind_of+from marimo._core.stream import (+ CATALOG_KINDS,+ NOTEBOOK_KINDS,+ Body,+ Event,+ Stream,+ kind_of,+ message,+)from tests._core.conftest import ScriptedBackend, names, project@@ -183,3 +194,44 @@ def test_custom_events_are_on_the_notebook_stream_only(replayed = host._stream.since(cursor)assert replayed is not Noneassert names(replayed) == ["custom"]+++def test_every_body_has_a_kind_a_stream_and_a_message() -> None:+ kinds = {body_type.__name__.lower() for body_type in get_args(Body)}+ assert kinds == CATALOG_KINDS | NOTEBOOK_KINDS+ assert CATALOG_KINDS - NOTEBOOK_KINDS == {"host", "project"}+ for body_type in get_args(Body):+ kind = body_type.__name__.lower()+ wrapper = type(message(_blank(body_type)))+ assert wrapper.__name__ == f"{body_type.__name__}Message"+ assert kind in {+ field.name for field in msgspec.structs.fields(wrapper)+ }+ assert kind_of(_blank(body_type)) == kind+++def _blank(body_type: type[msgspec.Struct]) -> msgspec.Struct:+ """Build a body with placeholder values, enough to wrap it."""+ values = {}+ for field in msgspec.structs.fields(body_type):+ if field.required:+ values[field.name] = _placeholder(field.type)+ return body_type(**values)+++def _placeholder(annotation: object) -> object:+ origin = getattr(annotation, "__origin__", None)+ args = getattr(annotation, "__args__", ())+ if origin is not None and args:+ return _placeholder(args[0])+ if annotation is str:+ return "x"+ if annotation is int:+ return 0+ if annotation is bool:+ return False+ if annotation is float:+ return 0.0+ if isinstance(annotation, type) and issubclass(annotation, msgspec.Struct):+ return _blank(annotation)+ return Nonediff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 6100ba7f89..1d0ea9c921 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -12,6 +12,7 @@ from urllib.parse import parse_qs, urlsplitimport msgspecimport pytest+from starlette.routing import Routefrom marimo._core import backend as be, protocolfrom marimo._core.execution_state import RetentionPolicy@@ -159,14 +160,67 @@ async def test_unknown_routes_are_problems(harness: Harness) -> None:assert response.headers["content-type"] == "application/problem+json"+async def test_a_wrong_method_on_a_known_route_is_a_405_problem(+ harness: Harness,+) -> None:+ response = await finished(harness.app, "GET", "/notebooks", headers=AUTH)+ assert response.status == 405+ assert response.headers["content-type"] == "application/problem+json"+ assert response.json()["type"].endswith("/method-not-allowed")+ assert "POST" in response.headers["allow"]+++def _declared_routes() -> dict[str, set[str]]:+ methods: dict[str, set[str]] = {}+ for route in api_module.build_app().routes:+ assert isinstance(route, Route)+ path = route.path.replace("{id}", "nb-x").replace("{run_id}", "run-x")+ methods.setdefault(path, set()).update(route.methods or set())+ return methods+++_DECLARED = _declared_routes()+_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]+_UNKNOWN = [+ "/nothing",+ "/notebooks/nb-x/nothing",+ "/events/",+ "/notebooks/",+ "/notebooks/nb-x/runtime/runs/run-x/",+]+_SWEEP = [+ (path, method) for path in [*_DECLARED, *_UNKNOWN] for method in _METHODS+]++[email protected](("path", "method"), _SWEEP)+async def test_every_method_on_every_route_is_a_response_not_a_500(+ harness: Harness, path: str, method: str+) -> None:+ response, _, disconnect = request(harness.app, method, path, headers=AUTH)+ await wait_for(response, lambda r: r.status != 0)+ disconnect()+ assert response.status != 500+ if not 200 <= response.status < 300:+ assert response.headers["content-type"] == "application/problem+json"+ if response.status == 405:+ allowed = {m.strip() for m in response.headers["allow"].split(",")}+ assert allowed == _DECLARED[path]++@pytest.mark.parametrize(("host", "status"),[("127.attacker.example:1234", 403),("127.1.2.3:1234", 202),("localhost:1234", 202),+ ("LOCALHOST:1234", 202),("[::1]:1234", 202),("[::ffff:127.0.0.1]:1234", 202),+ ("[::1]junk:1234", 403),+ ("[::1", 403),+ ("[::1:1234", 403),+ ("127.0.0.1:" + "1" * 5000, 403),],)async def test_only_loopback_names_are_admitted(@@ -183,6 +237,136 @@ async def test_only_loopback_names_are_admitted(assert response.status == status+ "port",+ ["\xb2", "1234\xb2", "\xb9\xb2\xb3"],+)+def test_latin1_superscripts_are_not_a_port(port: str) -> None:+ from marimo._server.host.middleware import _host_header_ok++ assert port.isdigit()+ assert _host_header_ok(f"127.0.0.1:{port}", PORT) is False+++ ("authorization", "status"),+ [+ ("Bearer \xe9", 401),+ ("Bearer", 401),+ ("Bearer ", 401),+ ("Basic record-token", 401),+ ("bearer record-token ", 202),+ ],+)+async def test_malformed_bearers_are_401_problems(+ harness: Harness, authorization: str, status: int+) -> None:+ response = await finished(+ harness.app,+ "PUT",+ f"/notebooks/{harness.notebook_id}/runtime",+ headers={"Authorization": authorization, "Idempotency-Key": "start"},+ body=b"{}",+ )+ assert response.status == status+ if status != 202:+ assert response.headers["content-type"] == "application/problem+json"++[email protected]("cursor", ["x", "-1", "1" * 5000, "1 "])+async def test_a_malformed_cursor_is_a_400_problem(+ harness: Harness, cursor: str+) -> None:+ response = await finished(+ harness.app,+ "GET",+ "/events",+ headers={**AUTH, "Last-Event-ID": cursor},+ )+ assert response.status == 400+ assert response.json()["type"].endswith("/invalid-request")+++async def test_a_nul_byte_in_a_path_is_a_400_problem(harness: Harness) -> None:+ response = await finished(+ harness.app,+ "POST",+ "/notebooks",+ headers=key("nul"),+ body=json.dumps(+ {+ "project_id": harness.bridge.index.project_id,+ "path": "a\u0000b.py",+ }+ ).encode(),+ )+ assert response.status == 400+ assert response.json()["type"].endswith("/invalid-request")+++async def test_a_401_names_the_bearer_scheme(harness: Harness) -> None:+ response = await finished(harness.app, "GET", "/events")+ assert response.status == 401+ assert response.headers["www-authenticate"] == "Bearer"++[email protected]("path", ["/events", "/notebooks/{id}/events"])[email protected]("types", ["bogus", "notebook,bogus", "Notebook"])+async def test_an_unknown_type_filter_is_a_400_problem(+ harness: Harness, path: str, types: str+) -> None:+ response = await finished(+ harness.app,+ "GET",+ path.replace("{id}", harness.notebook_id),+ headers=AUTH,+ query=f"types={types}",+ )+ assert response.status == 400+ assert "bogus" in response.json()["detail"] or types == "Notebook"+++async def test_an_empty_update_is_a_400_problem(harness: Harness) -> None:+ response = await finished(+ harness.app,+ "PATCH",+ f"/notebooks/{harness.notebook_id}",+ headers=key("empty"),+ body=b"{}",+ )+ assert response.status == 400+ assert response.json()["type"].endswith("/invalid-request")+++async def test_head_on_a_stream_is_a_405_and_attaches_nothing(+ harness: Harness,+) -> None:+ notebook = harness.host.notebook(harness.notebook_id)+ before = len(notebook._attachments)+ response = await finished(+ harness.app, "HEAD", f"/notebooks/{notebook.id}/events", headers=AUTH+ )+ assert response.status == 405+ assert response.headers["allow"] == "GET"+ assert len(notebook._attachments) == before+++async def test_a_failure_inside_a_stream_does_not_restart_the_response(+ harness: Harness, monkeypatch: pytest.MonkeyPatch+) -> None:+ def broken(_event: object) -> bytes:+ raise RuntimeError("frame failed")++ monkeypatch.setattr(api_module, "_frame", broken)+ response, task, _ = request(harness.app, "GET", "/events", headers=AUTH)+ # Older Starlette raises the body's error inside an ExceptionGroup.+ with pytest.raises(Exception) as caught:+ await asyncio.wait_for(task, 5)+ assert "frame failed" in repr(caught.value)+ assert response.status == 200+ assert response.body == b""++async def test_the_catalog_stream_sends_a_snapshot_then_changes(harness: Harness,) -> None:diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.pyindex 5e60a84e32..2b67e2bed2 100644--- a/tests/_server/host/test_host_record.py+++ b/tests/_server/host/test_host_record.py@@ -32,15 +32,50 @@ if TYPE_CHECKING:from pathlib import Path-def test_the_url_always_names_a_loopback_address() -> None:- assert (- host_url("0.0.0.0", 2718, "")- == f"http://127.0.0.1:2718{HOST_API_PATH}"+ ("host", "loopback"),+ [+ ("0.0.0.0", "127.0.0.1"),+ ("127.0.0.1", "127.0.0.1"),+ ("127.1.2.3", "127.1.2.3"),+ ("localhost", "127.0.0.1"),+ ("LOCALHOST", "127.0.0.1"),+ ("::ffff:127.0.0.1", "127.0.0.1"),+ ("::1", "[::1]"),+ ("[::1]", "[::1]"),+ ("::", "[::1]"),+ ("[::]", "[::1]"),+ ],+)+def test_the_url_names_the_loopback_that_reaches_the_bind(+ host: str, loopback: str+) -> None:+ assert host_url(host, 2718, "/marimo") == (+ f"http://{loopback}:2718/marimo{HOST_API_PATH}")- assert host_url("::1", 2718, "/marimo") == (- f"http://[::1]:2718/marimo{HOST_API_PATH}"++[email protected]("host", ["192.168.1.5", "10.0.0.1", "fe80::1", "x"])+def test_an_unreachable_bind_has_no_url(host: str) -> None:+ assert host_url(host, 2718, "") is None+++async def test_an_unreachable_bind_writes_no_record(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ monkeypatch.setattr(record_module, "marimo_state_dir", lambda: tmp_path)+ app = create_starlette_app(+ base_url="", enable_auth=True, lifespan=Lifespans([host_lifespan])+ )+ state = get_starlette_server_state_init()+ state.apply(app.state)+ app.state.server = uvicorn.Server(+ uvicorn.Config(app, host="192.168.1.5", port=1234))- assert host_url("[::1]", 2718, "") == f"http://[::1]:2718{HOST_API_PATH}"++ async with app.router.lifespan_context(app):+ assert list((tmp_path / "hosts-v1").glob("*.json")) == []+ assert app.state.host_context is not None@pytest.mark.parametrize("external_port", [1234, 8443])