A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Identify host attachments and emit unstable events (#11213)
Kiran Gadhave6b5b4071dcdf
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.pyindex 7aec4a4859..2523ccb15f 100644--- a/marimo/_core/notebook.py+++ b/marimo/_core/notebook.py@@ -8,8 +8,9 @@ backend updates and publishes events.from __future__ import annotationsfrom time import monotonic-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Any+import msgspecfrom msgspec.structs import replacefrom marimo._core import backend as be, protocol@@ -21,7 +22,7 @@ from marimo._core.stream import Event, kind_of, message, utcnowif TYPE_CHECKING:from collections.abc import Callable- from marimo._core.stream import Stream+ from marimo._core.stream import Body, Streamclass Notebook:@@ -249,21 +250,43 @@ class Notebook:# ---- attachments ---------------------------------------------------- def attach(self) -> protocol.Attachment:- """Record an attached host API client."""+ def attach(+ self,+ *,+ identity: str | None = None,+ kind: str | None = None,+ name: str | None = None,+ ) -> protocol.Attachment:+ """Attach a client to this notebook.++ Each call creates a separate attachment. `identity` is stored as+ data. It does not affect the attachment lifetime. An omitted `kind`+ is `client`. An empty `name` is stored as null.++ Raises:+ msgspec.ValidationError: If a value breaks the protocol's+ constraints on the attachment field of the same name.+ """self._require_open()- attachment = protocol.Attachment(- id=mint(protocol.AttachmentId, "att"),- notebook_id=self.id,- kind="client",- name=None,- since=utcnow(),- )+ fields: dict[str, Any] = {+ "id": mint(protocol.AttachmentId, "att"),+ "notebook_id": self.id,+ "kind": kind or "client",+ "name": name or None,+ "since": utcnow(),+ }+ if identity is not None:+ fields["identity"] = identity+ attachment = msgspec.convert(fields, protocol.Attachment)self._attachments[attachment.id] = attachmentself._publish(attachment, None)return attachmentdef detach(self, attachment_id: str) -> None:+ """Remove the attachment and publish its removal.++ Unknown IDs are ignored.+ """attachment = self._attachments.pop(attachment_id, None)if attachment is not None:self._remove("attachment", attachment.id, None)@@ -338,6 +361,32 @@ class Notebook:started_at=utcnow(),)+ def emit(+ self,+ type: str, # noqa: A002+ data: Any,+ *,+ request_id: str | None = None,+ ) -> protocol.Custom:+ """Publish a custom event on the notebook stream.++ A custom event is a notebook occurrence with a producer-defined+ payload.++ Raises:+ TypeError: If `data` is not a JSON value.+ ValueError: If `type` is empty.+ """+ self._require_open()+ if not type:+ raise ValueError("type must be a non-empty string")+ # Fail here, in the producer, instead of inside every subscriber's+ # stream when the event is framed.+ msgspec.json.encode(data)+ custom = protocol.Custom(type=type, data=data)+ self._publish(custom, request_id)+ return custom+# ---- stream --------------------------------------------------------def _snapshot(self) -> list[Event]:@@ -372,11 +421,7 @@ class Notebook:runtime, self._runtime = self._runtime, Noneself._remove("runtime", runtime.id, request_id)- def _publish(- self,- body: protocol.Runtime | protocol.Attachment,- request_id: str | None,- ) -> None:+ def _publish(self, body: Body, request_id: str | None) -> None:self._stream.publish(body,notebook_id=self.id,diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex 440319e812..6430914edd 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -585,14 +585,16 @@ class Attachment(Struct, frozen=True):kind: Annotated[str,Meta(- description="What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize."+ description="What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.",+ pattern="^[a-z0-9-]+$",),]name: (Annotated[str,Meta(- description="A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty."+ description="A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.",+ max_length=256,),]| Nonediff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex 310a0d5ea7..059dded3a4 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -35,9 +35,11 @@ NOTEBOOK_KINDS = frozenset("execution","console","display",+ "custom",})+Body: TypeAlias = (protocol.Host| protocol.Project@@ -48,6 +50,7 @@ Body: TypeAlias = (| protocol.Execution| protocol.Console| protocol.Display+ | protocol.Custom)_WRAPPERS: dict[str, type[msgspec.Struct]] = {@@ -60,6 +63,7 @@ _WRAPPERS: dict[str, type[msgspec.Struct]] = {"execution": protocol.ExecutionMessage,"console": protocol.ConsoleMessage,"display": protocol.DisplayMessage,+ "custom": protocol.CustomMessage,}diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex 74b84e866a..b278f6dd5b 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -45,6 +45,17 @@ _Body = TypeVar("_Body", bound=msgspec.Struct)PROBLEM_TYPE_PREFIX = "tag:marimo.io,2026:host/""""Prefix for host protocol problem types."""+ATTACHMENT_IDENTITY = "Marimo-Attachment-Identity"+ATTACHMENT_KIND = "Marimo-Attachment-Kind"+ATTACHMENT_NAME = "Marimo-Attachment-Name"++_ATTACHMENT_HEADERS = {+ "identity": ATTACHMENT_IDENTITY,+ "kind": ATTACHMENT_KIND,+ "name": ATTACHMENT_NAME,+}+"""Attachment fields and the request headers that supply them."""+PING = b": ping\n\n"PING_SECONDS = 15.0@@ -355,7 +366,14 @@ async def _notebook_events(request: Request) -> Response:run_id = request.query_params.get("run_id")if run_id == "":return problem(400, "invalid-request", "run_id must not be empty")- attachment = notebook.attach()+ try:+ attachment = notebook.attach(+ identity=request.headers.get(ATTACHMENT_IDENTITY),+ kind=request.headers.get(ATTACHMENT_KIND),+ name=request.headers.get(ATTACHMENT_NAME),+ )+ except msgspec.ValidationError as e:+ return problem(400, "invalid-request", _attachment_problem(e))return _stream(context,cursor,@@ -382,6 +400,15 @@ def _types(request: Request) -> set[str] | None:return {kind for kind in asked.split(",") if kind}+def _attachment_problem(error: msgspec.ValidationError) -> str:+ """Name the request header behind a rejected attachment field."""+ detail = str(error)+ for field, header in _ATTACHMENT_HEADERS.items():+ if detail.endswith(f"`$.{field}`"):+ return f"{header} is invalid"+ return "attachment headers are invalid"++def _stream(context: HostContext,cursor: int | None,diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex a9c85b2132..e27cb379cb 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -614,9 +614,11 @@ components:description: |A human-readable label copied to the attachment's `name`, such as`Notebook CLI`. Omitted or empty means the attachment's name is- null. The value must be at most 256 bytes when encoded as UTF-8;- longer values receive a 400 `invalid-request` response.- schema: { type: string }+ null. The value must be at most 256 characters; longer values+ receive a 400 `invalid-request` response.+ schema:+ type: string+ maxLength: 256IdempotencyKey:name: Idempotency-Keyin: header@@ -944,9 +946,11 @@ components:individual connection or change its lifetime.kind:type: string+ pattern: '^[a-z0-9-]+$'description: What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.name:type: [string, 'null']+ maxLength: 256description: A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.since:type: stringdiff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.pyindex 1b38a0942e..937b38c377 100644--- a/tests/_core/test_notebook.py+++ b/tests/_core/test_notebook.py@@ -3,6 +3,7 @@from __future__ import annotations+import msgspecimport pytestfrom dirty_equals import IsDatetimefrom inline_snapshot import snapshot@@ -14,8 +15,11 @@ from marimo._core.errors import Conflict, NoRuntime, NotFoundfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.protocol import (+ AttachmentMessage,Console,ConsoleMessage,+ Custom,+ CustomMessage,DisplayData,Error,ErrorOutcome,@@ -950,3 +954,80 @@ class TestAttachments:assert att.kind == "client"assert att.notebook_id == "n1"assert names(log) == ["attachment", "attachment.removed"]++ def test_one_identity_attaches_separately(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ first = notebook.attach(identity="k1", kind="agent", name="Codex")+ second = notebook.attach(identity="k1", kind="agent", name="Codex")++ assert first.id != second.id+ assert first.identity == second.identity == "k1"+ assert names(log) == ["attachment", "attachment"]+ assert _attachment_ids(notebook) == {first.id, second.id}++ def test_detach_leaves_other_attachments_with_the_identity(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ first = notebook.attach(identity="k1")+ second = notebook.attach(identity="k1")+ log.clear()++ notebook.detach(first.id)++ assert names(log) == ["attachment.removed"]+ assert _attachment_ids(notebook) == {second.id}++ def test_attach_without_an_identity_omits_it_on_the_wire(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ att = notebook.attach()++ assert att.identity is UNSET+ wire = msgspec.json.decode(msgspec.json.encode(log[0].data))+ assert "identity" not in wire["attachment"]+++class TestEmit:+ def test_emit_publishes_a_custom_event_on_the_notebook_stream(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ custom = notebook.emit("marimo.test", {"hello": 1}, request_id="req-1")++ assert custom == Custom(type="marimo.test", data={"hello": 1})+ assert names(log) == ["custom"]+ assert log[0].notebook_id == notebook.id+ published = log[0].data+ assert isinstance(published, CustomMessage)+ assert published.custom == custom+ assert published.request_id == "req-1"+ assert published.time is not UNSET++ def test_emit_rejects_data_that_is_not_json(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ with pytest.raises(TypeError):+ notebook.emit("marimo.test", object())+ assert "custom" not in names(log)++ def test_emit_rejects_an_empty_type(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ with pytest.raises(ValueError):+ notebook.emit("", 1)+ assert "custom" not in names(log)++ def test_emit_on_a_closed_notebook_raises(+ self, host: Host, notebook: Notebook+ ) -> None:+ host.remove_notebook(notebook.id)+ with pytest.raises(NotFound):+ notebook.emit("marimo.test", {"hello": 1})+++def _attachment_ids(notebook: Notebook) -> set[str]:+ return {+ event.data.attachment.id+ for event in notebook._snapshot()+ if isinstance(event.data, AttachmentMessage)+ }diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.pyindex 28e4df677d..c0d15b0e97 100644--- a/tests/_core/test_stream.py+++ b/tests/_core/test_stream.py@@ -8,8 +8,8 @@ import pytestfrom marimo._core import backend as be, protocolfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook-from marimo._core.stream import Event, Stream-from tests._core.conftest import ScriptedBackend, project+from marimo._core.stream import Event, Stream, kind_of+from tests._core.conftest import ScriptedBackend, names, projectdef test_subscriber_failure_does_not_prevent_startup(@@ -159,3 +159,27 @@ def test_subscribers_cannot_start_a_runtime_during_adoption([(replacement, False)],[],)+++def test_custom_events_are_on_the_notebook_stream_only(+ host: Host, notebook: Notebook+) -> None:+ cursor = host.events(notebook_id=notebook.id)[-1].id+ assert cursor is not None+ custom = notebook.emit("marimo.test", {"hello": 1})++ assert kind_of(custom) == "custom"+ assert names(host.events(cursor, notebook_id=notebook.id)) == [+ "custom",+ "ready",+ ]+ assert "custom" not in names(host.events())+ assert names(+ host.events(cursor, notebook_id=notebook.id, types={"custom"})+ ) == ["custom", "ready"]+ assert names(+ host.events(cursor, notebook_id=notebook.id, types={"attachment"})+ ) == ["ready"]+ replayed = host._stream.since(cursor)+ assert replayed is not None+ assert names(replayed) == ["custom"]diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 5d6db882ca..6100ba7f89 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -10,6 +10,7 @@ from pathlib import Pathfrom typing import TYPE_CHECKINGfrom urllib.parse import parse_qs, urlsplit+import msgspecimport pytestfrom marimo._core import backend as be, protocol@@ -294,6 +295,132 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:assert missing.status == 404+IDENTIFIED = {+ **AUTH,+ api_module.ATTACHMENT_IDENTITY: "k1",+ api_module.ATTACHMENT_KIND: "agent",+ api_module.ATTACHMENT_NAME: "Codex",+}+++async def attachment_of(+ harness: Harness, headers: dict[str, str]+) -> protocol.Attachment:+ """Open a notebook stream with `headers` and return its attachment."""+ response, task, disconnect = request(+ harness.app,+ "GET",+ f"/notebooks/{harness.notebook_id}/events",+ headers=headers,+ query="types=attachment",+ )+ await wait_for(response, until_ready)+ assert response.names() == ["attachment", "ready"]+ message = msgspec.convert(+ response.records[0]["data"], protocol.AttachmentMessage+ )+ disconnect()+ await asyncio.wait_for(task, 5)+ return message.attachment+++async def test_attachment_headers_name_the_client(harness: Harness) -> None:+ attachment = await attachment_of(harness, IDENTIFIED)+ assert attachment.identity == "k1"+ assert attachment.kind == "agent"+ assert attachment.name == "Codex"+++async def test_an_empty_attachment_name_is_null(harness: Harness) -> None:+ attachment = await attachment_of(+ harness, {**AUTH, api_module.ATTACHMENT_NAME: ""}+ )+ assert attachment.name is None+++async def test_a_reconnect_with_one_identity_attaches_fresh(+ harness: Harness,+) -> None:+ path = f"/notebooks/{harness.notebook_id}/events"+ first, first_task, disconnect_first = request(+ harness.app, "GET", path, headers=IDENTIFIED, query="types=attachment"+ )+ await wait_for(first, until_ready)+ cursor = first.records[-1]["id"]+ old = first.records[0]["data"]["attachment"]+ disconnect_first()+ await asyncio.wait_for(first_task, 5)+ assert "attachment" not in [e.name for e in harness.host.events()]++ second, second_task, disconnect_second = request(+ harness.app,+ "GET",+ path,+ headers={**IDENTIFIED, "Last-Event-ID": cursor},+ query="types=attachment",+ )+ await wait_for(second, until_ready)+ assert second.names() == ["attachment.removed", "attachment", "ready"]+ assert second.records[0]["data"]["id"] == old["id"]+ new = second.records[1]["data"]["attachment"]+ assert new["identity"] == old["identity"] == "k1"+ assert new["id"] != old["id"]++ disconnect_second()+ await asyncio.wait_for(second_task, 5)+++async def test_custom_events_use_their_own_sse_kind(+ harness: Harness,+) -> None:+ notebook = harness.host.notebook(harness.notebook_id)+ path = f"/notebooks/{notebook.id}/events"+ custom, custom_task, disconnect_custom = request(+ harness.app, "GET", path, headers=AUTH, query="types=custom"+ )+ attachments, attach_task, disconnect_attach = request(+ harness.app, "GET", path, headers=AUTH, query="types=attachment"+ )+ await wait_for(custom, until_ready)+ await wait_for(attachments, until_ready)++ notebook.emit("marimo.test", {"hello": 1})+ await wait_for(custom, lambda response: "custom" in response.names())+ frame = next(r for r in custom.records if r.get("event") == "custom")+ message = msgspec.convert(frame["data"], protocol.CustomMessage)+ assert message.custom == protocol.Custom(+ type="marimo.test", data={"hello": 1}+ )+ assert "custom" not in attachments.names()++ disconnect_custom()+ disconnect_attach()+ await asyncio.gather(custom_task, attach_task)+++ ("header", "value"),+ [+ (api_module.ATTACHMENT_IDENTITY, ""),+ (api_module.ATTACHMENT_KIND, "Agent"),+ (api_module.ATTACHMENT_NAME, "n" * 257),+ ],+)+async def test_invalid_attachment_headers_are_rejected(+ harness: Harness, header: str, value: str+) -> None:+ response = await finished(+ harness.app,+ "GET",+ f"/notebooks/{harness.notebook_id}/events",+ headers={**AUTH, header: value},+ )+ assert response.status == 400+ body = response.json()+ assert body["type"].endswith("/invalid-request")+ assert body["detail"] == f"{header} is invalid"++async def test_runtime_lifecycle_over_http(harness: Harness) -> None:app, nid = harness.app, harness.notebook_idpath = f"/notebooks/{nid}/runtime"