Notifications
A server that learns something nobody asked it about, such as a domain going active or a reply landing, records it in an outbox table beside its own. The host polls the outbox, routes what it finds, and a connector delivers it. The server never calls the host, learns its address, or asserts a workspace identity of its own. The protocol is Notifications; nimblebrain-server-sdk[outbox] is the server half of it.
uv add 'nimblebrain-server-sdk[outbox]'[outbox] installs [db] and [observability]: the outbox rows live under the same row-level security as the server’s own tables, and its counters record on the same registry. Read Data first; this page builds on its notes server.
1. Declare the outbox
Section titled “1. Declare the outbox”The server’s catalog entry declares the outbox’s URI. The host polls what the entry declares, so the server registers the same string.
"_meta": { "ai.nimblebrain/host": { "host_version": "1.0", "notifications": { "resource": "notes://notifications", "description": "Notes shared with someone." }}}The URI is the server’s own name: a scheme, ://, then slash-separated segments of lowercase letters and digits, with - or . inside a segment (acme://inbox, acme://mail.bounces/hard). register_outbox refuses anything a URL parser would rewrite (a percent escape, a port, a dot segment, a capital, or a scheme such as http), because it would be registered at one address and read at another.
Declaring an outbox grants no privilege. A workspace admin raises the source’s level ceiling, which starts at info, before anything from it can match a route. See levels.
2. Add the tables
Section titled “2. Add the tables”outbox_ddl returns the tables, their indexes and the row-level security policy, one statement per item.
"""Add the outbox tables to the notes database. Run after db_migrate.py, the same way."""
import asyncioimport os
import sqlalchemy as safrom db_migrate import APP_ROLEfrom sqlalchemy.ext.asyncio import create_async_engine
from nimblebrain_server_sdk.outbox import outbox_ddl, outbox_table
OUTBOX_TABLE = outbox_table(sa.MetaData())
async def migrate_outbox(url: str) -> None: engine = create_async_engine(url) async with engine.begin() as conn: for statement in outbox_ddl(OUTBOX_TABLE): # tables, indexes and the RLS policy await conn.execute(sa.text(statement)) for table in (OUTBOX_TABLE.name, f"{OUTBOX_TABLE.name}_state"): await conn.execute( sa.text(f"GRANT SELECT, INSERT, UPDATE, DELETE ON {table} TO {APP_ROLE}") ) await conn.execute(sa.text(f"GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO {APP_ROLE}")) await engine.dispose()
if __name__ == "__main__": asyncio.run(migrate_outbox(os.environ["MIGRATION_DATABASE_URL"]))3. Serve the outbox and emit
Section titled “3. Serve the outbox and emit”"""The Postgres notes server, recording a notification when a note is shared."""
from datetime import UTC, datetime
import sqlalchemy as safrom db_notes import db, mcp, notesfrom fastmcp.server.dependencies import get_http_headers
from nimblebrain_server_sdk import CHANGES, new_prefixed_idfrom nimblebrain_server_sdk.db import SecurityContext, security_context_from_edge_headersfrom nimblebrain_server_sdk.errors import ErrorCode, ServiceErrorfrom nimblebrain_server_sdk.outbox import emit, register_outbox
OUTBOX = "notes://notifications" # the URI the server's catalog entry declares
def identity() -> SecurityContext: return security_context_from_edge_headers(get_http_headers())
# Serve the outbox with the session factory and identity the tools already use.register_outbox(mcp, OUTBOX, db.session, identity)
@mcp.tool(annotations=CHANGES)async def share_note(note_id: int, with_person: str) -> dict[str, bool]: """Share a note with someone, and tell the workspace it was shared.""" ctx = identity() async with db.session(ctx) as conn: text = await conn.scalar(sa.select(notes.c.text).where(notes.c.id == note_id)) if text is None: raise ServiceError(ErrorCode.NOT_FOUND, "No note has that id.") # The state change would go here. The notification is appended on the same # connection, so it commits with the change or not at all. await emit( conn, ctx, { "eventId": new_prefixed_id("ev"), "name": "note.shared", "timestamp": datetime.now(UTC), "data": {"note_id": note_id, "with": with_person}, }, title=f"A note was shared with {with_person}"[:200], level="info", subject=with_person[:200], ) return {"shared": True}register_outboxtakes the session factory and identity function the server’s tools already use, so the outbox is authorized by the same code as the tools.emitruns on the same connection and transaction as the state change. A rolled-back change takes its event with it, and a committed one cannot lose it.eventIdis the idempotency key, unique per workspace. Emitting the same id again is a no-op that returnsNone. Use the upstream’s delivery id when there is one.
The envelope
Section titled “The envelope”An MCP Triggers and Events EventOccurrence, with what the host renders and routes on under _meta["ai.nimblebrain/notification"]. emit builds that block from its keywords.
| Field | |
|---|---|
eventId |
Required. The idempotency key. |
name |
Required. The server’s own dotted, lower-case name (domain.active), with no whitespace. |
timestamp |
Required. ISO 8601 with an offset, or an aware datetime. |
data |
Required JSON object. Opaque: nothing in the SDK or the host reads into it. |
title, body, subject, level, link_resource |
Optional presentation, passed to emit as keywords. level is info, attention or urgent. |
emit validates and raises; it does not repair. It refuses whatever the host’s parser would drop, because the host’s poll moves past a dropped envelope and the notification is lost:
- a length over a limit, counted as the host counts it, in UTF-16 code units:
TITLE_MAX(200),BODY_MAX(2000),SUBJECT_MAX(200), event id and name 200, link 2048; - whitespace in a name;
- a presentation field that is
null(leave it out instead); - an envelope over 64 KiB as the host measures it;
- a
link_resourcewith no scheme, or ajavascript:,data:,vbscript:,file:orblob:one.
Because the raise rolls the caller’s transaction back, trim unbounded upstream text deliberately with the exported limits, as share_note does.
The poll
Section titled “The poll”register_outbox serves the template <resource>{?cursor,maxEvents,maxAgeMs} and answers:
{ "events": [], "cursor": "...", "truncated": false, "hasMore": false }Events come oldest first, each with its own cursor.
cursoris opaque. A read with none starts from now: a cursor and no history.truncated: truemeans events after the cursor exist that this answer will never carry: the row cap dropped them,maxAgeMsexcluded them, or the cursor cannot be honoured, as after a database restore. It is not an error.hasMore: truemeans the batch was cut atmaxEvents; poll again at once.on_read(ctx, conn), an argument toregister_outbox, runs before the read in the same transaction and may return anextPollMs. A server that watches something upstream refreshes it there, so the poll is its tick and it needs no scheduler.
A poll never skips a row that was in flight when it ran. Each row records the id of the transaction that wrote it, a poll returns only rows below the oldest transaction still running, and the cursor advances no further. A row that raced costs one poll of latency. Delivery is at least once; the host removes duplicates by source and eventId.
Retention and metrics
Section titled “Retention and metrics”- Retention needs no sweeper. A read stamps the rows it returned and deletes what has carried a stamp for seven days, in the same transaction. An outbox nobody polls never prunes, so
emitholds each workspace tomax_rows(10,000), dropping the oldest; that loss is whattruncatedreports. - Metrics are on the
[observability]registry:notify_emitted_total{name},notify_read_total,notify_outbox_depth(undelivered rows after a poll) andnotify_outbox_capped_total.nameis the only label, so keep event names a closed set and put per-event values indata. - Postgres 13 or later, and an app role that is neither superuser nor
BYPASSRLS.
Test it
Section titled “Test it”"""A shared note reaches the host's next poll, and only in its own workspace.
Needs a superuser URL in DB_TEST_URL, as the SDK's own database tests do; skipped without it."""
import jsonimport osfrom collections.abc import AsyncIteratorfrom typing import Any
import pytestimport sqlalchemy as safrom db_migrate import APP_ROLE, migratefrom db_notes import dbfrom fastmcp import Clientfrom outbox_migrate import OUTBOX_TABLE, migrate_outboxfrom outbox_notes import OUTBOX, mcpfrom sqlalchemy.ext.asyncio import create_async_engine
from nimblebrain_server_sdk.db.testing import edge_client
ADMIN_URL = os.environ.get("DB_TEST_URL")PASSWORD = "notes-test-only" # noqa: S105TABLES = f"notes, {OUTBOX_TABLE.name}, {OUTBOX_TABLE.name}_state"
pytestmark = pytest.mark.skipif(ADMIN_URL is None and not os.environ.get("CI"), reason="no DB")
@pytest.fixture(autouse=True)async def database(monkeypatch: pytest.MonkeyPatch) -> AsyncIterator[None]: assert ADMIN_URL is not None, "DB_TEST_URL is not set" admin = create_async_engine(ADMIN_URL) async with admin.begin() as conn: await conn.execute(sa.text(f"DROP TABLE IF EXISTS {TABLES}")) await migrate(ADMIN_URL, PASSWORD) await migrate_outbox(ADMIN_URL) app_url = sa.make_url(ADMIN_URL).set(username=APP_ROLE, password=PASSWORD) monkeypatch.setenv("NOTES_DATABASE_URL", app_url.render_as_string(hide_password=False)) yield await db.dispose() async with admin.begin() as conn: await conn.execute(sa.text(f"DROP TABLE IF EXISTS {TABLES}")) await admin.dispose()
async def poll(client: Client, cursor: str | None = None) -> dict[str, Any]: uri = OUTBOX if cursor is None else f"{OUTBOX}?cursor={cursor}" (content,) = await client.read_resource(uri) return json.loads(getattr(content, "text", ""))
async def test_a_shared_note_is_in_the_next_poll() -> None: async with edge_client(mcp, tenant_id="t1", workspace_id="ws_a") as ws_a: start = await poll(ws_a) # a first poll starts from now: a cursor and no history assert start["events"] == [] await ws_a.call_tool("add_note", {"text": "ship it"}) await ws_a.call_tool("share_note", {"note_id": 1, "with_person": "Sam"}) page = await poll(ws_a, start["cursor"]) (event,) = page["events"] assert event["name"] == "note.shared" assert event["data"] == {"note_id": 1, "with": "Sam"} assert event["_meta"]["ai.nimblebrain/notification"]["title"] == "A note was shared with Sam"
async with edge_client(mcp, tenant_id="t1", workspace_id="ws_b") as ws_b: assert (await poll(ws_b))["events"] == []Give the test database its own Postgres instance: a poll reads below the instance-wide snapshot horizon, so a transaction open anywhere on the instance holds it back.
Related
Section titled “Related”- Notifications: the protocol, and where the events end up
- Data
- API reference