Skip to content

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.

fix: misc host protocol fixes (#11222)

Kiran Gadhavecc8628f390e9
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index 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.py
index 059dded3a4..ddad41f112 100644
--- a/marimo/_core/stream.py
+++ b/marimo/_core/stream.py
@@ -14,7 +14,7 @@ from contextlib import contextmanager
from copy import deepcopy
from dataclasses import dataclass
from datetime import datetime, timezone
-from typing import TypeAlias
+from typing import TypeAlias, get_args
import msgspec
from msgspec import UNSET
@@ -23,23 +23,6 @@ from marimo._core import protocol
LOGGER = 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.py
index b278f6dd5b..f191dfcd86 100644
--- a/marimo/_server/host/api.py
+++ b/marimo/_server/host/api.py
@@ -9,7 +9,7 @@ import threading
from collections.abc import Awaitable, Callable
from functools import wraps
from pathlib import Path
-from typing import TYPE_CHECKING, TypeAlias, TypeVar
+from typing import TYPE_CHECKING, TypeAlias, TypeVar, get_args
from urllib.parse import quote
import msgspec
@@ -31,7 +31,6 @@ if TYPE_CHECKING:
from collections.abc import AsyncIterator
from starlette.requests import Request
- from starlette.types import ASGIApp
from marimo._core.notebook import Notebook
from 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 types
run_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 types
def _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.index
target = None
if body.path is not msgspec.UNSET:
diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.py
index 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:
yield
finally:
maintenance.cancel()
with contextlib.suppress(asyncio.CancelledError):
await maintenance
- record.remove()
+ if record is not None:
+ record.remove()
bridge.close()
app.state.host_context = None
diff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.py
index 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 annotations
import hmac
+import re
from ipaddress import IPv6Address, ip_address
from typing import TYPE_CHECKING
+from starlette.exceptions import HTTPException
from starlette.requests import Request
+from starlette.routing import Match, Route
from marimo import _loggers
from marimo._server.host import HOST_API_PATH
from marimo._server.host.api import build_app, problem
if 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, Send
LOGGER = _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.
+ raise
LOGGER.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 True
try:
address = ip_address(host)
@@ -90,16 +144,18 @@ def _host_header_ok(header: str | None, port: int) -> bool:
if header is None:
return False
if header.startswith("["):
- name, _, after = header.partition("]")
+ name, closed, after = header.partition("]")
+ if not closed or (after and not after.startswith(":")):
+ return False
name = name[1:]
- given = after[1:] if after.startswith(":") else ""
+ given = after[1:]
else:
name, _, given = header.partition(":")
if not _is_loopback(name):
return False
if given == "":
return port == 80
- return given.isdigit() and int(given) == port
+ return _PORT.fullmatch(given) is not None and int(given) == port
def _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.py
index f8bcd31fed..db0414aa12 100644
--- a/marimo/_server/host/record.py
+++ b/marimo/_server/host/record.py
@@ -7,6 +7,7 @@ import atexit
import os
import tempfile
from datetime import datetime, timezone
+from ipaddress import IPv6Address, ip_address
from uuid import uuid4
import msgspec
@@ -19,9 +20,31 @@ from marimo._utils.xdg import marimo_state_dir
LOGGER = _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 None
return f"http://{loopback}:{port}{base_url}{HOST_API_PATH}"
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index 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 this
protocol defines all start with `tag:marimo.io,2026:host/` and
end 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-found
title:
type: string
diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.py
index 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 msgspec
import pytest
from marimo._core import backend as be, protocol
from marimo._core.host import Host
from 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 None
assert 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 None
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 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, urlsplit
import msgspec
import pytest
+from starlette.routing import Route
from marimo._core import backend as be, protocol
from 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.py
index 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])