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.

Move notebook operations into core (#11485)

Trevor Manz8685346ecbc9
diff --git a/marimo/_core/calls.py b/marimo/_core/calls.py
new file mode 100644
index 0000000000..24f42e997a
--- /dev/null
+++ b/marimo/_core/calls.py
@@ -0,0 +1,235 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Requests for notebook operations, each with the handler that serves it.
+
+A call has the parts of an HTTP request, as the client sends them. Its
+`params` are the path parameters, its `headers` the request headers it
+reads, and its `body` the decoded request body. A call also gives its place
+in the HTTP API, and its `handle` method does the work and declares the
+successful status and response in its return type.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Literal
+
+import msgspec
+
+from marimo._core import protocol
+from marimo._core.errors import Conflict, HostError, Invalid, NotFound
+from marimo._core.operations import Reply, problem_for
+
+if TYPE_CHECKING:
+ from marimo._core.operations import Mutations, NotebookBridge
+
+
+class NotebookParams(msgspec.Struct, frozen=True):
+ notebook_id: protocol.NotebookId
+
+
+class RunParams(NotebookParams, frozen=True):
+ run_id: protocol.RunId
+
+
+class MutationHeaders(msgspec.Struct, frozen=True):
+ idempotency_key: str = msgspec.field(name="idempotency-key", default="")
+
+
+class SaveHeaders(MutationHeaders, frozen=True):
+ if_match: str | None = msgspec.field(name="if-match", default=None)
+
+
+class _Call(msgspec.Struct, frozen=True, tag_field="operation"):
+ METHOD: ClassVar[str]
+ PATH: ClassVar[str]
+
+
+class EditCall(_Call, frozen=True, tag="notebook.edit"):
+ """Change parts of the document."""
+
+ METHOD = "POST"
+ PATH = "/notebooks/{notebook_id}/edits"
+
+ params: NotebookParams
+ headers: MutationHeaders
+ body: protocol.EditRequest
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[200], protocol.EditResponse]:
+ return 200, await bridge.edit(
+ self.params.notebook_id,
+ self.body.changes,
+ request_id=self.headers.idempotency_key,
+ )
+
+
+class SaveCall(_Call, frozen=True, tag="notebook.save"):
+ """Write the document to the host's store."""
+
+ METHOD = "POST"
+ PATH = "/notebooks/{notebook_id}/save"
+
+ params: NotebookParams
+ headers: SaveHeaders
+ body: protocol.SaveRequest
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[200], protocol.EditResponse]:
+ decisions = self.body.decisions
+ return 200, await bridge.save(
+ self.params.notebook_id,
+ if_match=_if_match(self.headers.if_match),
+ decisions={} if decisions is msgspec.UNSET else decisions,
+ request_id=self.headers.idempotency_key,
+ )
+
+
+class StartCall(_Call, frozen=True, tag="runtime.start"):
+ """Start the notebook's runtime, or find the one it has."""
+
+ METHOD = "PUT"
+ PATH = "/notebooks/{notebook_id}/runtime"
+
+ params: NotebookParams
+ headers: MutationHeaders
+ body: protocol.StartRuntimeRequest
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[200, 202], protocol.Runtime]:
+ notebook = await bridge.host.notebook(self.params.notebook_id)
+ runtime, created = notebook.start(
+ request_id=self.headers.idempotency_key
+ )
+ return (202 if created else 200), runtime
+
+
+class StopCall(_Call, frozen=True, tag="runtime.stop"):
+ """Stop the notebook's runtime."""
+
+ METHOD = "DELETE"
+ PATH = "/notebooks/{notebook_id}/runtime"
+
+ params: NotebookParams
+ headers: MutationHeaders
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[202], protocol.Runtime]:
+ notebook = await bridge.host.notebook(self.params.notebook_id)
+ return 202, notebook.stop(request_id=self.headers.idempotency_key)
+
+
+class RestartCall(_Call, frozen=True, tag="runtime.restart"):
+ """Restart the notebook's kernel."""
+
+ METHOD = "POST"
+ PATH = "/notebooks/{notebook_id}/runtime/restart"
+
+ params: NotebookParams
+ headers: MutationHeaders
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[202], protocol.Runtime]:
+ notebook = await bridge.host.notebook(self.params.notebook_id)
+ return 202, notebook.restart(request_id=self.headers.idempotency_key)
+
+
+class RunCall(_Call, frozen=True, tag="runtime.run"):
+ """Run code or cells against the notebook's runtime."""
+
+ METHOD = "POST"
+ PATH = "/notebooks/{notebook_id}/runtime/runs"
+
+ params: NotebookParams
+ headers: MutationHeaders
+ body: protocol.RunRequest
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[202], protocol.Run]:
+ notebook = await bridge.host.notebook(self.params.notebook_id)
+ key = self.headers.idempotency_key
+ code, cells = self.body.code, self.body.cells
+ if isinstance(code, str) and cells is msgspec.UNSET:
+ return 202, notebook.run(code, request_id=key)
+ if code is msgspec.UNSET and isinstance(cells, tuple):
+ return 202, notebook.run(cells=cells, request_id=key)
+ raise Invalid("A run names code or cells, not both")
+
+
+class InterruptCall(_Call, frozen=True, tag="runtime.interrupt"):
+ """Interrupt a run."""
+
+ METHOD = "DELETE"
+ PATH = "/notebooks/{notebook_id}/runtime/runs/{run_id}"
+
+ params: RunParams
+ headers: MutationHeaders
+
+ async def handle(
+ self, bridge: NotebookBridge
+ ) -> tuple[Literal[202], protocol.Run]:
+ notebook_id, run_id = self.params.notebook_id, self.params.run_id
+ notebook = await bridge.host.notebook(notebook_id)
+ try:
+ return 202, notebook.interrupt(run_id)
+ except NotFound:
+ run = bridge.host.run(notebook_id, run_id)
+ if run is not None and run.status == "completed":
+ raise Conflict(f"run {run_id} has already ended.") from None
+ raise
+
+
+OperationCall = (
+ EditCall
+ | SaveCall
+ | StartCall
+ | StopCall
+ | RestartCall
+ | RunCall
+ | InterruptCall
+)
+"""A request for any notebook operation, tagged by its operation id."""
+
+# The same members as `OperationCall`, as values to build routes from.
+# `typing.get_args` would return them untyped.
+CALLS: tuple[type[OperationCall], ...] = (
+ EditCall,
+ SaveCall,
+ StartCall,
+ StopCall,
+ RestartCall,
+ RunCall,
+ InterruptCall,
+)
+
+
+async def dispatch(
+ mutations: Mutations, bridge: NotebookBridge, call: OperationCall
+) -> Reply:
+ """Serve a call once per idempotency key and describe a failure as a problem."""
+ try:
+ return await mutations.execute(
+ str(call.__struct_config__.tag),
+ notebook_id=call.params.notebook_id,
+ key=call.headers.idempotency_key,
+ payload=call,
+ call=lambda: call.handle(bridge),
+ )
+ except HostError as e:
+ failure = problem_for(e)
+ return failure.status, failure
+
+
+def _if_match(header: str | None) -> tuple[str, ...] | None:
+ """Parse strong entity tags; weak tags never satisfy an If-Match check."""
+ if header is None or header.strip() == "*":
+ return None
+ return tuple(
+ part.strip().strip('"')
+ for part in header.split(",")
+ if part.strip() and not part.strip().startswith("W/")
+ )
diff --git a/marimo/_core/errors.py b/marimo/_core/errors.py
index a86a04bbb9..27ab622a2b 100644
--- a/marimo/_core/errors.py
+++ b/marimo/_core/errors.py
@@ -29,6 +29,14 @@ class Invalid(HostError):
"""The request could not apply to any state."""
+class Forbidden(HostError):
+ """The notebook does not allow the command."""
+
+
+class Unsupported(HostError):
+ """The host does not offer the command."""
+
+
class EditConflict(Conflict):
"""A change named a state the document no longer has.
diff --git a/marimo/_core/operations.py b/marimo/_core/operations.py
new file mode 100644
index 0000000000..397bdfeccc
--- /dev/null
+++ b/marimo/_core/operations.py
@@ -0,0 +1,322 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Retry receipts and problems shared by every transport."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from dataclasses import dataclass
+from time import monotonic
+from typing import TYPE_CHECKING, Protocol
+
+import msgspec
+
+from marimo._core import protocol
+from marimo._core.errors import (
+ Conflict,
+ DecisionRequired,
+ EditConflict,
+ Forbidden,
+ HostError,
+ Invalid,
+ NoRuntime,
+ NotFound,
+ Unsupported,
+)
+from marimo._core.host import Host
+from marimo._core.stream import RoutedEvent
+
+if TYPE_CHECKING:
+ from collections.abc import Awaitable, Callable, Mapping, Sequence
+
+Reply = tuple[int, msgspec.Struct | None]
+"""A status and body, for a transport to encode."""
+
+
+class NotebookBridge(Protocol):
+ @property
+ def host(self) -> Host: ...
+
+ async def edit(
+ self,
+ notebook_id: str,
+ changes: Sequence[protocol.Change],
+ *,
+ request_id: str,
+ ) -> protocol.EditResponse: ...
+
+ async def save(
+ self,
+ notebook_id: str,
+ *,
+ if_match: Sequence[str] | None,
+ decisions: Mapping[str, str],
+ request_id: str,
+ ) -> protocol.EditResponse: ...
+
+
+_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",
+ "decision-required": "Decision required",
+ "unsupported-operation": "Unsupported operation",
+ "internal": "Internal error",
+}
+
+
+def problem(
+ status: int,
+ kind: str,
+ detail: str | None = None,
+ *,
+ edit: protocol.EditConflict | None = None,
+ decisions: tuple[protocol.Decision, ...] | None = None,
+) -> protocol.Problem:
+ return protocol.Problem(
+ type="tag:marimo.io,2026:host/" + kind,
+ title=_TITLES[kind],
+ status=status,
+ detail=msgspec.UNSET if detail is None else detail,
+ edit=msgspec.UNSET if edit is None else edit,
+ decisions=msgspec.UNSET if decisions is None else decisions,
+ )
+
+
+def problem_for(error: HostError) -> protocol.Problem:
+ """Describe a failed command the same way on every transport."""
+ detail = str(error)
+ match error:
+ case NoRuntime():
+ return problem(409, "no-runtime", detail)
+ case DecisionRequired():
+ return problem(
+ 409, "decision-required", detail, decisions=error.decisions
+ )
+ case EditConflict():
+ return problem(
+ 409,
+ "conflict",
+ detail,
+ edit=protocol.EditConflict(
+ change=error.change,
+ cell=error.cell,
+ document=error.document,
+ ),
+ )
+ case Conflict():
+ return problem(409, "conflict", detail)
+ case Invalid():
+ return problem(400, "invalid-request", detail)
+ case NotFound():
+ return problem(404, "not-found", detail)
+ case Forbidden():
+ return problem(403, "forbidden", detail)
+ case Unsupported():
+ return problem(501, "unsupported-operation", detail)
+ return problem(500, "internal", "The host failed")
+
+
+@dataclass
+class CachedMutation:
+ """An accepted request, including its in-flight or completed result."""
+
+ fingerprint: str
+ task: asyncio.Future[Reply]
+ run: protocol.Run | None = None
+ expires_at: float | None = None
+
+
+class Mutations:
+ """Share capability checks and retry semantics across all host mutations."""
+
+ def __init__(
+ self,
+ host: Host,
+ *,
+ receipt_seconds: float = 300.0,
+ clock: Callable[[], float] = monotonic,
+ ) -> None:
+ self.host = host
+ # A receipt covers a client's retry loop after a lost response, so it
+ # outlasts retry backoff rather than a person's absence.
+ self.receipt_seconds = receipt_seconds
+ self.clock = clock
+ self.replies: dict[str, CachedMutation] = {}
+
+ def remembered(self, key: str) -> CachedMutation | None:
+ """Return the receipt for a key, dropping it if it has expired."""
+ reply = self.replies.get(key)
+ if reply is not None and self._expired(reply):
+ del self.replies[key]
+ return None
+ return reply
+
+ def settle(self, mutation: CachedMutation) -> None:
+ """Start the receipt's retention window once its work is complete."""
+ mutation.expires_at = self.clock() + self.receipt_seconds
+
+ def expire(self) -> None:
+ """Sweep expired receipts and the host's results."""
+ self.host.expire()
+ for key, reply in list(self.replies.items()):
+ if self._expired(reply):
+ del self.replies[key]
+
+ def _expired(self, reply: CachedMutation) -> bool:
+ return (
+ reply.expires_at is not None and self.clock() >= reply.expires_at
+ )
+
+ async def execute(
+ self,
+ operation: str,
+ *,
+ notebook_id: str | None,
+ key: str,
+ payload: object,
+ call: Callable[[], Awaitable[Reply]],
+ ) -> Reply:
+ """Run `call` once per idempotency key, and answer retries with its reply."""
+ capability = (
+ "runtime.run" if operation == "runtime.interrupt" else operation
+ )
+ if capability not in self.host.operations:
+ raise Unsupported(f"This host does not offer {capability}")
+ record = self.host.notebooks.get(notebook_id) if notebook_id else None
+ if record is not None and capability not in record.operations:
+ raise Forbidden(f"This notebook does not allow {capability}")
+ if not key:
+ raise Invalid("Idempotency-Key is required")
+ fingerprint = hashlib.sha256(
+ msgspec.json.encode((operation, notebook_id, payload))
+ ).hexdigest()
+ remembered = self.remembered(key)
+ if remembered is not None:
+ if remembered.fingerprint != fingerprint:
+ raise Conflict(
+ f"Idempotency-Key {key} was used for another request"
+ )
+ reply = await asyncio.shield(remembered.task)
+ # A retried run answers with the run as it is now.
+ return reply if remembered.run is None else (202, remembered.run)
+
+ task = asyncio.ensure_future(call())
+ mutation = CachedMutation(fingerprint, task)
+ self.replies[key] = mutation
+ unsubscribe: Callable[[], None] | None = None
+ lifecycle_accepted: Callable[[Reply], None] | None = None
+ if operation == "runtime.run":
+ # Retain the latest run without retaining its output payloads.
+ def updated(event: RoutedEvent) -> None:
+ if isinstance(event.event, protocol.RunEvent):
+ run = event.event.data.run
+ if event.event.data.request_id == key:
+ mutation.run = run
+ if (
+ run.status == "completed"
+ and unsubscribe is not None
+ ):
+ self.settle(mutation)
+ unsubscribe()
+
+ unsubscribe = self.host.subscribe(
+ updated, notebook_id=notebook_id, types={"run"}
+ )
+ elif operation in {"runtime.start", "runtime.stop", "runtime.restart"}:
+ assert notebook_id is not None
+ lifecycle_accepted, unsubscribe = _watch_lifecycle(
+ self,
+ mutation,
+ operation=operation,
+ notebook_id=notebook_id,
+ request_id=key,
+ )
+
+ def completed(task: asyncio.Future[Reply]) -> None:
+ if task.cancelled() or task.exception() is not None:
+ self.replies.pop(key, None)
+ if unsubscribe is not None:
+ unsubscribe()
+ elif lifecycle_accepted is not None:
+ lifecycle_accepted(task.result())
+ elif mutation.expires_at is None and (
+ mutation.run is None or mutation.run.status == "completed"
+ ):
+ self.settle(mutation)
+
+ task.add_done_callback(completed)
+ # A disconnected waiter must not cancel a shared mutation.
+ return await asyncio.shield(task)
+
+
+def _watch_lifecycle(
+ context: Mutations,
+ mutation: CachedMutation,
+ *,
+ operation: str,
+ notebook_id: str,
+ request_id: str,
+) -> tuple[Callable[[Reply], None], Callable[[], None]]:
+ runtime_id: protocol.RuntimeId | None = None
+ previous_id: protocol.RuntimeId | None = None
+ early: list[RoutedEvent] = []
+
+ def settle() -> None:
+ context.settle(mutation)
+ unsubscribe()
+
+ def updated(event: RoutedEvent) -> None:
+ nonlocal previous_id
+ if mutation.expires_at is not None:
+ return
+ if runtime_id is None:
+ # A backend can finish synchronously, before the response exists.
+ early.append(event)
+ return
+ if isinstance(event.event, protocol.NotebookRemovedEvent):
+ settle()
+ elif isinstance(event.event, protocol.RuntimeEvent):
+ runtime = event.event.data.runtime
+ if (
+ operation == "runtime.restart"
+ and event.event.data.request_id == request_id
+ and runtime.status == "terminating"
+ and runtime.id != runtime_id
+ ):
+ previous_id = runtime.id
+ if (
+ operation != "runtime.stop"
+ and runtime.id == runtime_id
+ and runtime.status in ("running", "failed")
+ ):
+ settle()
+ elif isinstance(event.event, protocol.RuntimeRemovedEvent):
+ if event.event.data.id == runtime_id or (
+ event.event.data.id == previous_id
+ and event.event.data.request_id != request_id
+ ):
+ # A later stop can cancel a restart before its replacement starts.
+ settle()
+
+ unsubscribe = context.host.subscribe(
+ updated, notebook_id=notebook_id, types={"runtime", "notebook"}
+ )
+
+ def accepted(reply: Reply) -> None:
+ nonlocal runtime_id
+ match reply:
+ # A 202 changes a runtime, and a 200 found the one already running.
+ case (202, protocol.Runtime(id=accepted_id)):
+ runtime_id = accepted_id
+ for event in early:
+ updated(event)
+ case _:
+ settle()
+ early.clear()
+
+ return accepted, unsubscribe
diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.py
index c1d1e7f608..1cc42ada38 100644
--- a/marimo/_server/host/api.py
+++ b/marimo/_server/host/api.py
@@ -4,13 +4,10 @@
from __future__ import annotations
import asyncio
-import hashlib
import threading
-from collections.abc import Awaitable, Callable
from contextlib import contextmanager
-from functools import wraps
from pathlib import Path
-from typing import TYPE_CHECKING, TypeAlias, TypeVar
+from typing import TYPE_CHECKING
from urllib.parse import quote
import msgspec
@@ -24,12 +21,9 @@ from marimo import _loggers
from marimo._core import protocol
from marimo._core.errors import (
Conflict,
- DecisionRequired,
- EditConflict,
- Invalid,
- NoRuntime,
NotFound,
)
+from marimo._core.operations import Reply
from marimo._server.api.auth import TOKEN_QUERY_PARAM, validate_auth
from marimo._server.api.deps import AppState, AppStateBase
from marimo._server.api.endpoints.ws.ws_connection_validator import (
@@ -45,14 +39,20 @@ from marimo._server.host import (
HOST_API_PATH,
stream_options,
)
-from marimo._server.host.context import CachedMutation
from marimo._server.host.events import serialize_event, serialize_sse_event
+from marimo._server.host.notebook_api import (
+ _context,
+ _decode,
+ _mutation,
+ notebook_routes,
+ problem,
+)
from marimo._server.host.session import SessionEventStream
from marimo._server.sse import SSE_HEADERS
from marimo._server.tokens import AuthToken
if TYPE_CHECKING:
- from collections.abc import AsyncIterator, Iterator
+ from collections.abc import AsyncIterator, Callable, Iterator
from anyio import CancelScope
from starlette.requests import HTTPConnection, Request
@@ -64,12 +64,6 @@ if TYPE_CHECKING:
LOGGER = _loggers.marimo_logger()
-_Endpoint: TypeAlias = Callable[["Request"], Awaitable[Response]]
-_Body = TypeVar("_Body", bound=msgspec.Struct)
-
-PROBLEM_TYPE_PREFIX = "tag:marimo.io,2026:host/"
-"""Prefix for host protocol problem types."""
-
_ATTACHMENT_HEADERS = {
"identity": ATTACHMENT_IDENTITY,
@@ -82,88 +76,27 @@ PING = b": ping\n\n"
PING_SECONDS = 15.0
-_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",
- "decision-required": "Decision required",
- "unsupported-operation": "Unsupported operation",
- "internal": "Internal error",
-}
-
-
-_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,
- *,
- edit: protocol.EditConflict | None = None,
- decisions: tuple[protocol.Decision, ...] | 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. A conflict over an edit carries `edit`, and a
- request that needs a choice first carries `decisions`.
- """
- 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],
- status=status,
- detail=msgspec.UNSET if detail is None else detail,
- edit=msgspec.UNSET if edit is None else edit,
- decisions=msgspec.UNSET if decisions is None else decisions,
- )
- return Response(
- msgspec.json.encode(body),
- status_code=status,
- media_type="application/problem+json",
- )
-
-
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"]),
- WebSocketRoute("/notebooks/{id}/events/ws", _notebook_events_ws),
- Route("/notebooks/{id}/edits", _edit_notebook, methods=["POST"]),
- Route("/notebooks/{id}/save", _save_notebook, methods=["POST"]),
- 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/{notebook_id}", _update_notebook, methods=["PATCH"]),
Route(
- "/notebooks/{id}/runtime/restart",
- _restart_runtime,
- methods=["POST"],
+ "/notebooks/{notebook_id}", _delete_notebook, methods=["DELETE"]
),
- Route("/notebooks/{id}/runtime/runs", _run, methods=["POST"]),
Route(
- "/notebooks/{id}/runtime/runs/{run_id}",
- _interrupt,
- methods=["DELETE"],
+ "/notebooks/{notebook_id}/events",
+ _notebook_events,
+ methods=["GET"],
+ ),
+ WebSocketRoute(
+ "/notebooks/{notebook_id}/events/ws", _notebook_events_ws
),
+ Route(
+ "/notebooks/{notebook_id}/open", _open_notebook, methods=["POST"]
+ ),
+ *notebook_routes(),
]
for route in routes:
# Starlette implies HEAD for every GET route, but a HEAD here would
@@ -187,20 +120,14 @@ async def _not_found(scope, receive, send) -> None: # type: ignore[no-untyped-d
await problem(404, "not-found", "No such route")(scope, receive, send)
-def _context(request: HTTPConnection) -> HostContext:
- context = getattr(request.app.state, "host_context", None)
- assert context is not None, "HostApiMiddleware admits requests only then"
- return context # type: ignore[no-any-return]
-
-
async def _notebook(request: HTTPConnection) -> Notebook:
return await _context(request).bridge.host.notebook(
- request.path_params["id"]
+ request.path_params["notebook_id"]
)
def _record(request: Request) -> protocol.Notebook:
- notebook_id = request.path_params["id"]
+ notebook_id = request.path_params["notebook_id"]
host = _context(request).bridge.host
record = host.notebooks.get(notebook_id)
if record is None:
@@ -208,214 +135,6 @@ def _record(request: Request) -> protocol.Notebook:
return record
-def _mutation(operation: str) -> Callable[[_Endpoint], _Endpoint]:
- """Apply capability checks, idempotency, and protocol errors to a command."""
-
- def decorate(endpoint: _Endpoint) -> _Endpoint:
- @wraps(endpoint)
- async def handle(request: Request) -> Response:
- context = _context(request)
- if operation not in context.bridge.host.operations:
- return problem(
- 501,
- "unsupported-operation",
- f"This host does not offer {operation}",
- )
- key = request.headers.get("Idempotency-Key", "")
- if not key:
- return problem(
- 400, "invalid-request", "Idempotency-Key is required"
- )
- digest = hashlib.sha256(await request.body()).hexdigest()
- # A precondition is part of the request, so a retry that
- # names another revision is another request.
- if_match = request.headers.get("If-Match", "")
- fingerprint = (
- f"{request.method} {request.url.path} {digest} {if_match}"
- )
- remembered = context.remembered(key)
- if remembered is not None:
- if remembered.fingerprint != fingerprint:
- return problem(
- 409,
- "conflict",
- f"Idempotency-Key {key} was used for another request",
- )
- response = await asyncio.shield(remembered.task)
- if remembered.run is not None:
- return _reply(202, remembered.run)
- return response
-
- task = asyncio.create_task(_execute_mutation(endpoint, request))
- mutation = CachedMutation(fingerprint, task)
- context.replies[key] = mutation
- unsubscribe: Callable[[], None] | None = None
- lifecycle_accepted: Callable[[Response], None] | None = None
- if operation == "runtime.run" and request.method == "POST":
- # The receipt outlives results without retaining their payloads.
- def updated(event: RoutedEvent) -> None:
- if isinstance(event.event, protocol.RunEvent):
- run = event.event.data.run
- if event.event.data.request_id == key:
- mutation.run = run
- if (
- run.status == "completed"
- and unsubscribe is not None
- ):
- context.settle(mutation)
- unsubscribe()
-
- unsubscribe = context.bridge.host.subscribe(
- updated,
- notebook_id=request.path_params["id"],
- types={"run"},
- )
- elif operation in {
- "runtime.start",
- "runtime.stop",
- "runtime.restart",
- }:
- lifecycle_accepted, unsubscribe = _watch_lifecycle(
- context,
- mutation,
- operation=operation,
- notebook_id=request.path_params["id"],
- request_id=key,
- )
-
- def completed(task: asyncio.Task[Response]) -> None:
- if (
- task.cancelled()
- or task.exception() is not None
- or task.result().status_code >= 400
- ):
- context.replies.pop(key, None)
- if unsubscribe is not None:
- unsubscribe()
- elif lifecycle_accepted is not None:
- lifecycle_accepted(task.result())
- elif mutation.expires_at is None and (
- mutation.run is None or mutation.run.status == "completed"
- ):
- context.settle(mutation)
-
- task.add_done_callback(completed)
- # A disconnected waiter must not cancel a shared mutation.
- return await asyncio.shield(task)
-
- return handle
-
- return decorate
-
-
-def _watch_lifecycle(
- context: HostContext,
- mutation: CachedMutation,
- *,
- operation: str,
- notebook_id: str,
- request_id: str,
-) -> tuple[Callable[[Response], None], Callable[[], None]]:
- runtime_id: protocol.RuntimeId | None = None
- previous_id: protocol.RuntimeId | None = None
- early: list[RoutedEvent] = []
-
- def settle() -> None:
- context.settle(mutation)
- unsubscribe()
-
- def updated(event: RoutedEvent) -> None:
- nonlocal previous_id
- if mutation.expires_at is not None:
- return
- if runtime_id is None:
- # A backend can finish synchronously, before the response exists.
- early.append(event)
- return
- if isinstance(event.event, protocol.NotebookRemovedEvent):
- settle()
- elif isinstance(event.event, protocol.RuntimeEvent):
- runtime = event.event.data.runtime
- if (
- operation == "runtime.restart"
- and event.event.data.request_id == request_id
- and runtime.status == "terminating"
- and runtime.id != runtime_id
- ):
- previous_id = runtime.id
- if (
- operation != "runtime.stop"
- and runtime.id == runtime_id
- and runtime.status in ("running", "failed")
- ):
- settle()
- elif isinstance(event.event, protocol.RuntimeRemovedEvent):
- if event.event.data.id == runtime_id or (
- event.event.data.id == previous_id
- and event.event.data.request_id != request_id
- ):
- # A later stop can cancel a restart before its replacement starts.
- settle()
-
- unsubscribe = context.bridge.host.subscribe(
- updated, notebook_id=notebook_id, types={"runtime", "notebook"}
- )
-
- def accepted(response: Response) -> None:
- nonlocal runtime_id
- if response.status_code == 202:
- runtime_id = msgspec.json.decode(
- response.body, type=protocol.Runtime
- ).id
- for event in early:
- updated(event)
- else:
- settle()
- early.clear()
-
- return accepted, unsubscribe
-
-
-async def _execute_mutation(endpoint: _Endpoint, request: Request) -> Response:
- try:
- return await endpoint(request)
- except NoRuntime as e:
- return problem(409, "no-runtime", str(e))
- except DecisionRequired as e:
- return problem(409, "decision-required", str(e), decisions=e.decisions)
- except EditConflict as e:
- return problem(
- 409,
- "conflict",
- str(e),
- edit=protocol.EditConflict(
- change=e.change, cell=e.cell, document=e.document
- ),
- )
- except Conflict as e:
- return problem(409, "conflict", str(e))
- except Invalid as e:
- return problem(400, "invalid-request", str(e))
- except NotFound as e:
- return problem(404, "not-found", str(e))
- except msgspec.DecodeError as e:
- return problem(400, "invalid-request", str(e))
- except HTTPException as e:
- return problem(e.status_code, detail=e.detail)
-
-
-def _reply(status: int, body: msgspec.Struct | None = None) -> Response:
- return Response(
- b"" if body is None else msgspec.json.encode(body),
- status_code=status,
- media_type="application/json" if body is not None else None,
- )
-
-
-async def _decode(request: Request, kind: type[_Body]) -> _Body:
- return msgspec.json.decode(await request.body() or b"{}", type=kind)
-
-
# ---- streams -------------------------------------------------------------------
@@ -475,7 +194,7 @@ async def _notebook_events(request: Request) -> Response:
def editor_events_route(base_url: str = "") -> WebSocketRoute:
"""Expose the notebook event socket through editor authentication."""
return WebSocketRoute(
- f"{base_url}{HOST_API_PATH}/notebooks/{{id}}/events/ws",
+ f"{base_url}{HOST_API_PATH}/notebooks/{{notebook_id}}/events/ws",
_editor_events_ws,
)
@@ -772,7 +491,7 @@ def _inside_project(path: str) -> Path:
@_mutation("notebook.create")
-async def _create_notebook(request: Request) -> Response:
+async def _create_notebook(request: Request) -> Reply:
"""Create an empty notebook in the project."""
context = _context(request)
key = request.headers["Idempotency-Key"]
@@ -790,11 +509,11 @@ async def _create_notebook(request: Request) -> Response:
name=None if body.name is msgspec.UNSET else body.name,
request_id=key,
)
- return _reply(201, notebook)
+ return 201, notebook
@_mutation("notebook.update")
-async def _update_notebook(request: Request) -> Response:
+async def _update_notebook(request: Request) -> Reply:
"""Change a notebook's path or display name, preserving its runtime."""
context = _context(request)
key = request.headers["Idempotency-Key"]
@@ -816,66 +535,20 @@ async def _update_notebook(request: Request) -> Response:
name=None if body.name is msgspec.UNSET else body.name,
request_id=key,
)
- return _reply(200, notebook)
+ return 200, notebook
@_mutation("notebook.delete")
-async def _delete_notebook(request: Request) -> Response:
+async def _delete_notebook(request: Request) -> Reply:
"""Delete the notebook and its file if it has no runtime."""
context = _context(request)
key = request.headers["Idempotency-Key"]
await context.bridge.delete(_record(request).id, request_id=key)
- return _reply(204, None)
-
-
-@_mutation("notebook.edit")
-async def _edit_notebook(request: Request) -> Response:
- """Apply an edit as one unit; 409 with `edit` when a precondition is stale."""
- context = _context(request)
- key = request.headers["Idempotency-Key"]
- notebook = await _notebook(request)
- body = await _decode(request, protocol.EditRequest)
- response = await context.bridge.edit(
- notebook.id, body.changes, request_id=key
- )
- return _reply(200, response)
-
-
-@_mutation("notebook.save")
-async def _save_notebook(request: Request) -> Response:
- """Write the document to its file; 409 with `edit` when `If-Match` is stale."""
- context = _context(request)
- key = request.headers["Idempotency-Key"]
- notebook = await _notebook(request)
- body = await _decode(request, protocol.SaveRequest)
- response = await context.bridge.save(
- notebook.id,
- if_match=_if_match(request.headers.get("If-Match")),
- decisions={} if body.decisions is msgspec.UNSET else body.decisions,
- request_id=key,
- )
- return _reply(200, response)
-
-
-def _if_match(header: str | None) -> tuple[str, ...] | None:
- """The etags an `If-Match` header accepts, or `None` when it accepts any.
-
- The header is `*` or a comma-separated list of entity tags, each
- optionally quoted. `If-Match` compares strongly (RFC 9110, 13.1.1),
- so a tag marked weak with `W/` never matches and is left out.
- """
- if header is None or header.strip() == "*":
- return None
- tags = []
- for part in header.split(","):
- tag = part.strip()
- if tag and not tag.startswith("W/"):
- tags.append(tag.strip('"'))
- return tuple(tags)
+ return 204, None
@_mutation("notebook.open")
-async def _open_notebook(request: Request) -> Response:
+async def _open_notebook(request: Request) -> Reply:
"""Open the notebook in the configured browser."""
record = _record(request)
file = _context(request).bridge.index.file_of(record.id)
@@ -893,7 +566,7 @@ async def _open_notebook(request: Request) -> Response:
threading.Thread(
target=_open_quietly, args=(browser, url), daemon=True
).start()
- return _reply(200, protocol.OpenNotebookResponse(url=url))
+ return 200, protocol.OpenNotebookResponse(url=url)
def _open_quietly(browser: str, url: str) -> None:
@@ -906,65 +579,4 @@ def _open_quietly(browser: str, url: str) -> None:
# ---- runtimes ------------------------------------------------------------------
-@_mutation("runtime.start")
-async def _start_runtime(request: Request) -> Response:
- """Start a runtime and return 202, or 200 if it already exists."""
- key = request.headers["Idempotency-Key"]
- notebook = await _notebook(request)
- await _decode(request, protocol.StartRuntimeRequest)
- runtime, created = notebook.start(request_id=key)
- return _reply(202 if created else 200, runtime)
-
-
-@_mutation("runtime.stop")
-async def _stop_runtime(request: Request) -> Response:
- """Request shutdown and return 202 with the runtime marked terminating."""
- key = request.headers["Idempotency-Key"]
- notebook = await _notebook(request)
- runtime = notebook.stop(request_id=key)
- return _reply(202, runtime)
-
-
-@_mutation("runtime.restart")
-async def _restart_runtime(request: Request) -> Response:
- """Return 202 with the replacement runtime in its starting state."""
- key = request.headers["Idempotency-Key"]
- notebook = await _notebook(request)
- runtime = notebook.restart(request_id=key)
- return _reply(202, runtime)
-
-
# ---- runs ----------------------------------------------------------------------
-
-
-@_mutation("runtime.run")
-async def _run(request: Request) -> Response:
- """Queue a run and return 202. Results arrive through notebook events."""
- key = request.headers["Idempotency-Key"]
- notebook = await _notebook(request)
- body = await _decode(request, protocol.RunRequest)
- if isinstance(body.code, str) and body.cells is msgspec.UNSET:
- started = notebook.run(body.code, request_id=key)
- elif body.code is msgspec.UNSET and isinstance(body.cells, tuple):
- started = notebook.run(cells=body.cells, request_id=key)
- else:
- return problem(
- 400, "invalid-request", "A run names code or cells, not both"
- )
- return _reply(202, started)
-
-
-@_mutation("runtime.run")
-async def _interrupt(request: Request) -> Response:
- """Interrupt an active run and return 202, or 409 if it has completed."""
- notebook = await _notebook(request)
- run_id = request.path_params["run_id"]
- try:
- interrupted = notebook.interrupt(run_id)
- except NotFound:
- # A completed scratch run is host history, not notebook state.
- run = _context(request).bridge.host.run(notebook.id, run_id)
- if run is not None and run.status == "completed":
- raise Conflict(f"run {run_id} has already ended.") from None
- raise
- return _reply(202, interrupted)
diff --git a/marimo/_server/host/context.py b/marimo/_server/host/context.py
index 07dcf4860f..3c00f9463f 100644
--- a/marimo/_server/host/context.py
+++ b/marimo/_server/host/context.py
@@ -4,62 +4,22 @@
from __future__ import annotations
from dataclasses import dataclass, field
-from time import monotonic
from typing import TYPE_CHECKING
-if TYPE_CHECKING:
- import asyncio
- from collections.abc import Callable
-
- from starlette.responses import Response
+from marimo._core.operations import Mutations
- from marimo._core import protocol
+if TYPE_CHECKING:
from marimo._server.host.bridge import SessionBridge
-@dataclass
-class CachedMutation:
- """One accepted request, including its in-flight or completed reply."""
-
- fingerprint: str
- task: asyncio.Task[Response]
- run: protocol.Run | None = None
- expires_at: float | None = None
-
-
@dataclass
class HostContext:
- """Host API token, address, session bridge, and cached replies."""
+ """Host API token, address, session bridge, and retry receipts."""
bridge: SessionBridge
token: str
port: int
- replies: dict[str, CachedMutation] = field(default_factory=dict)
- # A receipt covers a client's retry loop after a lost response, so it
- # outlasts retry backoff rather than a person's absence.
- receipt_seconds: float = 300.0
- clock: Callable[[], float] = monotonic
-
- def remembered(self, key: str) -> CachedMutation | None:
- """Return the receipt for a key, dropping it if it has expired."""
- reply = self.replies.get(key)
- if reply is not None and self._expired(reply):
- del self.replies[key]
- return None
- return reply
-
- def settle(self, mutation: CachedMutation) -> None:
- """Start the receipt's retention window once its work is complete."""
- mutation.expires_at = self.clock() + self.receipt_seconds
-
- def expire(self) -> None:
- """Sweep expired receipts and the host's results."""
- self.bridge.host.expire()
- for key, reply in list(self.replies.items()):
- if self._expired(reply):
- del self.replies[key]
+ mutations: Mutations = field(init=False)
- def _expired(self, reply: CachedMutation) -> bool:
- return (
- reply.expires_at is not None and self.clock() >= reply.expires_at
- )
+ def __post_init__(self) -> None:
+ self.mutations = Mutations(self.bridge.host)
diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.py
index 32134b16bd..36399e3cf3 100644
--- a/marimo/_server/host/lifespan.py
+++ b/marimo/_server/host/lifespan.py
@@ -89,7 +89,7 @@ async def host(app: Starlette) -> AsyncIterator[None]:
async def maintain() -> None:
while True:
await asyncio.sleep(1)
- context.expire()
+ context.mutations.expire()
maintenance = asyncio.create_task(maintain(), name="host.retention")
record = None
diff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.py
index 9c25e294a1..0554dce4ea 100644
--- a/marimo/_server/host/middleware.py
+++ b/marimo/_server/host/middleware.py
@@ -20,7 +20,8 @@ from starlette.websockets import WebSocket
from marimo import _loggers
from marimo._server.host import HOST_API_PATH
-from marimo._server.host.api import build_app, editor_events_route, problem
+from marimo._server.host.api import build_app, editor_events_route
+from marimo._server.host.notebook_api import problem
if TYPE_CHECKING:
from collections.abc import Sequence
diff --git a/marimo/_server/host/notebook_api.py b/marimo/_server/host/notebook_api.py
new file mode 100644
index 0000000000..4b9aa86d64
--- /dev/null
+++ b/marimo/_server/host/notebook_api.py
@@ -0,0 +1,142 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""HTTP routes for the notebook operations, and problem responses."""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, TypeVar
+
+import msgspec
+from starlette.exceptions import HTTPException
+from starlette.responses import Response
+from starlette.routing import Route
+
+from marimo import _loggers
+from marimo._core import operations, protocol
+from marimo._core.calls import CALLS, dispatch
+from marimo._core.errors import HostError
+from marimo._core.operations import Reply
+
+if TYPE_CHECKING:
+ from collections.abc import Awaitable, Callable
+
+ from starlette.requests import HTTPConnection, Request
+
+ from marimo._core.calls import OperationCall
+ from marimo._server.host.context import HostContext
+
+LOGGER = _loggers.marimo_logger()
+_Body = TypeVar("_Body", bound=msgspec.Struct)
+
+
+def _context(request: HTTPConnection) -> HostContext:
+ context = getattr(request.app.state, "host_context", None)
+ assert context is not None, "HostApiMiddleware admits requests only then"
+ return context # type: ignore[no-any-return]
+
+
+def _response(status: int, body: msgspec.Struct | None) -> Response:
+ media_type = (
+ "application/problem+json"
+ if isinstance(body, protocol.Problem)
+ else "application/json"
+ if body is not None
+ else None
+ )
+ return Response(
+ b"" if body is None else msgspec.json.encode(body),
+ status_code=status,
+ media_type=media_type,
+ )
+
+
+def problem(
+ status: int, kind: str | None = None, detail: str | None = None
+) -> Response:
+ if kind is None:
+ kind = {
+ 400: "invalid-request",
+ 404: "not-found",
+ 405: "method-not-allowed",
+ 409: "conflict",
+ }.get(status)
+ if kind is None:
+ LOGGER.error("The host API raised an unmapped status %s", status)
+ status, kind, detail = 500, "internal", "The host failed"
+ return _response(status, operations.problem(status, kind, detail))
+
+
+async def _decode(request: Request, kind: type[_Body]) -> _Body:
+ return msgspec.json.decode(await request.body() or b"{}", type=kind)
+
+
+def _mutation(
+ operation: str,
+) -> Callable[
+ [Callable[[Request], Awaitable[Reply]]],
+ Callable[[Request], Awaitable[Response]],
+]:
+ """Use the same receipt store for catalog operations implemented by the server."""
+
+ def decorate(
+ endpoint: Callable[[Request], Awaitable[Reply]],
+ ) -> Callable[[Request], Awaitable[Response]]:
+ @wraps(endpoint)
+ async def handle(request: Request) -> Response:
+ try:
+ status, body = await _context(request).mutations.execute(
+ operation,
+ notebook_id=request.path_params.get("notebook_id"),
+ key=request.headers.get("Idempotency-Key", ""),
+ payload=(
+ request.method,
+ request.url.path,
+ await request.body(),
+ request.headers.get("If-Match", ""),
+ ),
+ call=lambda: endpoint(request),
+ )
+ except msgspec.DecodeError as e:
+ return problem(400, "invalid-request", str(e))
+ except HTTPException as e:
+ return problem(e.status_code, detail=e.detail)
+ except HostError as e:
+ failure = operations.problem_for(e)
+ return _response(failure.status, failure)
+ return _response(status, body)
+
+ return handle
+
+ return decorate
+
+
+def _endpoint(
+ kind: type[OperationCall],
+) -> Callable[[Request], Awaitable[Response]]:
+ async def handle(request: Request) -> Response:
+ # Assemble the call from the request's parts, the shape the client
+ # sends to any transport, so every call passes the same validation.
+ parts: dict[str, object] = {
+ "operation": kind.__struct_config__.tag,
+ "params": request.path_params,
+ "headers": dict(request.headers),
+ }
+ if "body" in kind.__struct_fields__:
+ parts["body"] = msgspec.Raw(await request.body() or b"{}")
+ try:
+ call = msgspec.json.decode(msgspec.json.encode(parts), type=kind)
+ except msgspec.DecodeError as e:
+ return problem(400, "invalid-request", str(e))
+ context = _context(request)
+ status, body = await dispatch(context.mutations, context.bridge, call)
+ return _response(status, body)
+
+ return handle
+
+
+def notebook_routes() -> list[Route]:
+ """Serve each notebook operation at its path in the spec."""
+ return [
+ Route(kind.PATH, _endpoint(kind), methods=[kind.METHOD])
+ for kind in CALLS
+ ]
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
index 92397a0c86..e1241c41bf 100644
--- a/tests/_core/conftest.py
+++ b/tests/_core/conftest.py
@@ -6,10 +6,11 @@ from __future__ import annotations
import asyncio
from typing import TYPE_CHECKING
+import msgspec
import pytest
from marimo._core import backend as be, protocol, protocol_events
-from marimo._core.document import Document, code_hash
+from marimo._core.document import Document, DocumentCell, code_hash
from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
@@ -17,7 +18,7 @@ from marimo._core.run_log import RetentionPolicy
from marimo._core.stream import RoutedEvent, Sink, event_name
if TYPE_CHECKING:
- from collections.abc import Sequence
+ from collections.abc import Mapping, Sequence
OPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]
@@ -173,6 +174,64 @@ def log(host: Host) -> list[RoutedEvent]:
return events
+class RecordingBridge:
+ """A notebook bridge that counts edits and can hold one in flight."""
+
+ def __init__(self, host: Host) -> None:
+ self.host = host
+ self.edits = 0
+ self.started = asyncio.Event()
+ self.release = asyncio.Event()
+ self.release.set()
+ self.preconditions: list[Sequence[str] | None] = []
+
+ async def edit(
+ self,
+ notebook_id: str,
+ changes: Sequence[protocol.Change],
+ *,
+ request_id: str,
+ ) -> protocol.EditResponse:
+ self.edits += 1
+ self.started.set()
+ await self.release.wait()
+ notebook = await self.host.notebook(notebook_id)
+ return notebook.edit(changes, request_id=request_id)
+
+ async def save(
+ self,
+ notebook_id: str,
+ *,
+ if_match: Sequence[str] | None,
+ decisions: Mapping[str, str],
+ request_id: str,
+ ) -> protocol.EditResponse:
+ del decisions
+ self.preconditions.append(if_match)
+ notebook = await self.host.notebook(notebook_id)
+ return notebook.edit((), request_id=request_id)
+
+
+async def bridge() -> RecordingBridge:
+ host = Host(
+ operations=(
+ "notebook.edit",
+ "notebook.save",
+ "runtime.start",
+ "runtime.run",
+ )
+ )
+ host.update_project(project())
+ await add_notebook(
+ host,
+ msgspec.structs.replace(record(), operations=tuple(host.operations)),
+ ScriptedBackend(),
+ document=Document([DocumentCell(protocol.CellId("c1"), "x = 1")], {}),
+ )
+ return RecordingBridge(host)
+
+
def names(events: list[RoutedEvent]) -> list[str]:
return [event_name(e.event) for e in events]
diff --git a/tests/_core/test_calls.py b/tests/_core/test_calls.py
new file mode 100644
index 0000000000..90af6ef0e9
--- /dev/null
+++ b/tests/_core/test_calls.py
@@ -0,0 +1,121 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from typing import Any, get_args, get_type_hints
+
+import msgspec
+import pytest
+
+from marimo._core import calls, protocol
+from marimo._core.calls import (
+ CALLS,
+ InterruptCall,
+ MutationHeaders,
+ OperationCall,
+ RunParams,
+)
+from marimo._core.operations import NotebookBridge
+from protocols.host.generate import compose
+
+NOTEBOOK = protocol.NotebookId("n1")
+
+
+def test_calls_decode_from_request_parts() -> None:
+ def decode(**parts: object) -> OperationCall:
+ return msgspec.json.decode(
+ msgspec.json.encode(parts), type=OperationCall
+ )
+
+ headers = {"idempotency-key": "k", "authorization": "Bearer t"}
+ assert decode(
+ operation="runtime.interrupt",
+ params={"notebook_id": "n1", "run_id": "r1"},
+ headers=headers,
+ ) == InterruptCall(
+ RunParams(NOTEBOOK, protocol.RunId("r1")), MutationHeaders("k")
+ )
+ for invalid in (
+ {"operation": "runtime.interrupt", "params": {"notebook_id": "n1"}},
+ {"operation": "notebook.missing", "params": {"notebook_id": "n1"}},
+ ):
+ with pytest.raises(msgspec.ValidationError):
+ decode(**invalid, headers=headers)
+
+
+def test_calls_match_the_spec() -> None:
+ document = compose()
+
+ def resolve(value: dict[str, Any]) -> dict[str, Any]:
+ if "$ref" not in value:
+ return value
+ target = document
+ for part in value["$ref"].removeprefix("#/").split("/"):
+ target = target[part]
+ return target
+
+ def schema_name(content: dict[str, Any]) -> str:
+ reference: str = content["application/json"]["schema"]["$ref"]
+ return reference.rsplit("/", 1)[1]
+
+ def names(kind: type[msgspec.Struct]) -> set[str]:
+ return {field.encode_name for field in msgspec.structs.fields(kind)}
+
+ specified = {
+ operation["operationId"]: (method.upper(), path, item, operation)
+ for path, item in document["paths"].items()
+ for method, operation in item.items()
+ if isinstance(operation, dict) and "operationId" in operation
+ }
+ assert set(get_args(OperationCall)) == set(CALLS)
+ assert {kind.__struct_config__.tag for kind in CALLS} == {
+ operation_id
+ for operation_id in specified
+ if operation_id.startswith("runtime.")
+ or operation_id in {"notebook.edit", "notebook.save"}
+ }
+
+ for kind in CALLS:
+ method, path, item, operation = specified[
+ str(kind.__struct_config__.tag)
+ ]
+ assert (kind.METHOD, kind.PATH) == (method, path)
+
+ parameters = [
+ resolve(parameter)
+ for parameter in [
+ *item.get("parameters", []),
+ *operation.get("parameters", []),
+ ]
+ ]
+ fields = {field.name: field for field in msgspec.structs.fields(kind)}
+ assert names(fields["params"].type) == {
+ parameter["name"]
+ for parameter in parameters
+ if parameter["in"] == "path"
+ }
+ assert names(fields["headers"].type) == {
+ parameter["name"].lower()
+ for parameter in parameters
+ if parameter["in"] == "header"
+ }
+ body = operation.get("requestBody")
+ if body is None:
+ assert set(fields) == {"params", "headers"}
+ else:
+ assert set(fields) == {"params", "headers", "body"}
+ assert fields["body"].type.__name__ == schema_name(
+ resolve(body)["content"]
+ )
+
+ hints = get_type_hints(
+ kind.handle, {**vars(calls), "NotebookBridge": NotebookBridge}
+ )
+ statuses, response = get_args(hints["return"])
+ success = {
+ int(status): resolve(value)
+ for status, value in operation["responses"].items()
+ if status.startswith("2")
+ }
+ assert set(get_args(statuses)) == set(success)
+ for value in success.values():
+ assert schema_name(value["content"]) == response.__name__
diff --git a/tests/_core/test_mutations.py b/tests/_core/test_mutations.py
new file mode 100644
index 0000000000..186f66757d
--- /dev/null
+++ b/tests/_core/test_mutations.py
@@ -0,0 +1,123 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+
+import msgspec
+import pytest
+
+from marimo._core import protocol
+from marimo._core.calls import (
+ EditCall,
+ MutationHeaders,
+ NotebookParams,
+ OperationCall,
+ SaveCall,
+ SaveHeaders,
+ StopCall,
+ dispatch,
+)
+from marimo._core.operations import Mutations, Reply
+from tests._core.test_notebook_document import put
+
+NOTEBOOK = protocol.NotebookId("n1")
+PARAMS = NotebookParams(NOTEBOOK)
+
+
+def edit(key: str, *changes: protocol.Change) -> EditCall:
+ return EditCall(
+ PARAMS, MutationHeaders(key), protocol.EditRequest(changes)
+ )
+
+
+def save(key: str, if_match: str | None = None) -> SaveCall:
+ return SaveCall(PARAMS, SaveHeaders(key, if_match), protocol.SaveRequest())
+
+
+def serve(bridge):
+ mutations = Mutations(bridge.host)
+
+ async def serve(call: OperationCall) -> Reply:
+ return await dispatch(mutations, bridge, call)
+
+ return serve
+
+
+def kind(reply: Reply) -> str:
+ _, body = reply
+ assert isinstance(body, protocol.Problem)
+ return body.type.rsplit("/", 1)[1]
+
+
+async def test_edit_retry_and_atomic_conflict(bridge, serve):
+ events = []
+ bridge.host.subscribe(events.append, notebook_id=NOTEBOOK)
+ call = edit("edit", put("c1", "x = 2", "*"))
+ status, result = await serve(call)
+ assert status == 200
+ assert isinstance(result, protocol.EditResponse)
+ event_count = len(events)
+ assert event_count > 0
+ assert await serve(call) == (200, result)
+ assert (bridge.edits, len(events)) == (1, event_count)
+
+ conflict = await serve(
+ edit(
+ "conflict", put("new", "y = 1", None), put("c1", "x = 3", "stale")
+ )
+ )
+ assert conflict[0] == 409
+ assert isinstance(conflict[1], protocol.Problem)
+ assert conflict[1].edit.change == 1
+ assert conflict[1].edit.cell.code == "x = 2"
+ assert len(events) == event_count
+ notebook = await bridge.host.notebook(NOTEBOOK)
+ assert [cell.id for cell in notebook.document] == ["c1"]
+
+
+async def test_cancellation_and_concurrent_retry(bridge, serve):
+ bridge.release.clear()
+ call = edit("edit", put("c1", "x = 2", "*"))
+ first = asyncio.create_task(serve(call))
+ await asyncio.wait_for(bridge.started.wait(), 5)
+ try:
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ retry = asyncio.create_task(serve(call))
+ bridge.release.set()
+ status, result = await asyncio.wait_for(retry, 5)
+ assert status == 200
+ assert isinstance(result, protocol.EditResponse)
+ assert bridge.edits == 1
+ finally:
+ bridge.release.set()
+
+
+async def test_receipts_include_operation_and_preconditions(bridge, serve):
+ saved = await serve(save("save", '"a", W/"weak", "b"'))
+ assert saved[0] == 200
+ assert await serve(save("save", '"a", W/"weak", "b"')) == saved
+ assert kind(await serve(save("save", '"c"'))) == "conflict"
+ assert kind(await serve(edit("save"))) == "conflict"
+ assert bridge.preconditions == [("a", "b")]
+
+
+async def test_rejected_calls_do_not_reserve_keys(serve):
+ assert kind(await serve(edit("edit", put("c1", "x = 2", "stale")))) == (
+ "conflict"
+ )
+ status, _ = await serve(edit("edit", put("c1", "x = 2", "*")))
+ assert status == 200
+
+
+async def test_calls_check_capabilities_and_keys(bridge, serve):
+ stop = StopCall(PARAMS, MutationHeaders("stop"))
+ assert kind(await serve(stop)) == "unsupported-operation"
+ assert kind(await serve(edit(""))) == "invalid-request"
+ bridge.host.update_notebook(
+ msgspec.structs.replace(bridge.host.notebooks[NOTEBOOK], operations=())
+ )
+ assert kind(await serve(edit("edit"))) == "forbidden"
+ assert bridge.edits == 0
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 61475b95bc..404a1a844d 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -148,13 +148,10 @@ def harness(
monkeypatch.setattr(bridge, "_make_backend", make)
bridge.index.refresh()
- app.state.host_context = HostContext(
- bridge=bridge,
- token=TOKEN,
- port=PORT,
- receipt_seconds=30,
- clock=lambda: harness.now,
- )
+ context = HostContext(bridge=bridge, token=TOKEN, port=PORT)
+ context.mutations.receipt_seconds = 30
+ context.mutations.clock = lambda: harness.now
+ app.state.host_context = context
return harness
@@ -339,6 +336,21 @@ async def test_an_empty_cursor_is_a_400_problem(harness: Harness) -> None:
assert response.json()["type"].endswith("/invalid-request")
+async def test_a_call_reads_only_its_own_parts(harness: Harness) -> None:
+ nid = await harness.running()
+ stopped = await finished(
+ harness.app,
+ "DELETE",
+ f"/notebooks/{nid}/runtime",
+ # A header cannot stand in for a path parameter, and a call without
+ # a body ignores the one it is sent.
+ headers={**key("stop"), "Notebook-Id": "missing", "Params": "{}"},
+ body=b"not json",
+ )
+ assert stopped.status == 202, stopped.body
+ assert stopped.json()["notebook_id"] == nid
+
+
async def test_a_nul_byte_in_a_path_is_a_400_problem(harness: Harness) -> None:
response = await finished(
harness.app,
@@ -762,7 +774,7 @@ async def test_slow_restart_keeps_its_receipt(harness: Harness) -> None:
# The receipt's 30-second window must not begin during shutdown/startup.
harness.now = 100
- harness.app.state.host_context.expire()
+ harness.app.state.host_context.mutations.expire()
notebook.observe(be.Exited(runtime_id_of(notebook)))
notebook.observe(be.Running(runtime_id_of(notebook), "0.25.0"))
calls = list(harness.backend().calls)
@@ -816,7 +828,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(
assert accepted.status == 202
for now in (100, 200):
harness.now = now
- context.expire()
+ context.mutations.expire()
calls = list(harness.backend().calls)
replayed = await finished(
harness.app, method, path, headers=key("lifecycle")
@@ -837,7 +849,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(
assert harness.host._stream._listeners == listeners
calls = list(harness.backend().calls)
harness.now = 229
- context.expire()
+ context.mutations.expire()
replayed = await finished(
harness.app, method, path, headers=key("lifecycle")
)
@@ -847,7 +859,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(
calls,
)
harness.now = 230
- assert context.remembered("lifecycle") is None
+ assert context.mutations.remembered("lifecycle") is None
@pytest.mark.parametrize(
@@ -882,7 +894,7 @@ async def test_stop_settles_superseded_lifecycle_receipts(
assert harness.host._stream._listeners == listeners
calls = list(harness.backend().calls)
harness.now = 229
- context.expire()
+ context.mutations.expire()
for request_id, verb, url, response in [
("pending", method, pending_path, accepted),
("stop-1", "DELETE", path, stops[0]),
@@ -898,7 +910,7 @@ async def test_stop_settles_superseded_lifecycle_receipts(
)
harness.now = 230
assert [
- context.remembered(request_id)
+ context.mutations.remembered(request_id)
for request_id in ("pending", "stop-1", "stop-2")
] == [None, None, None]
@@ -949,7 +961,10 @@ async def test_synchronous_lifecycle_completion(
calls,
)
harness.now = 30
- assert harness.app.state.host_context.remembered("immediate") is None
+ assert (
+ harness.app.state.host_context.mutations.remembered("immediate")
+ is None
+ )
async def test_noop_and_rejected_lifecycle_requests_release_their_listeners(
@@ -968,10 +983,10 @@ async def test_noop_and_rejected_lifecycle_requests_release_their_listeners(
harness.app, "PUT", path, headers=key("invalid"), body=b"{"
)
assert rejected.status == 400
- assert context.remembered("invalid") is None
+ assert context.mutations.remembered("invalid") is None
assert harness.host._stream._listeners == listeners
harness.now = 30
- assert context.remembered("existing") is None
+ assert context.mutations.remembered("existing") is None
async def test_run_filter_over_http(harness: Harness) -> None:
@@ -1404,6 +1419,9 @@ async def test_operations_the_host_does_not_offer_are_501(
host.update_project(project)
host.add_notebook(harness.host.notebooks[notebook.id], make_notebook)
harness.bridge.host = host
+ harness.app.state.host_context = HostContext(
+ bridge=harness.bridge, token=TOKEN, port=PORT
+ )
response = await finished(
harness.app,
"PUT",
diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.py
index 3680c94e1f..1824a03b7f 100644
--- a/tests/_server/host/test_host_record.py
+++ b/tests/_server/host/test_host_record.py
@@ -162,7 +162,7 @@ async def test_idle_host_expires_results_and_stops_maintenance(
context = app.state.host_context
host = context.bridge.host
now = 0.0
- host.clock = context.clock = lambda: now
+ host.clock = context.mutations.clock = lambda: now
host.update_project(project())
notebook = await add_notebook(host, record(), ScriptedBackend())
notebook.adopt(lambda _: None)
@@ -203,6 +203,6 @@ async def test_idle_host_expires_results_and_stops_maintenance(
]
now = 300
await asyncio.wait_for(removed.wait(), timeout=5)
- assert context.replies == {}
+ assert context.mutations.replies == {}
assert maintenance.done()
assert app.state.host_context is None