Skip to content

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.

Terminal window
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.

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.

outbox_ddl returns the tables, their indexes and the row-level security policy, one statement per item.

outbox_migrate.py
"""Add the outbox tables to the notes database. Run after db_migrate.py, the same way."""
import asyncio
import os
import sqlalchemy as sa
from db_migrate import APP_ROLE
from 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"]))
outbox_notes.py
"""The Postgres notes server, recording a notification when a note is shared."""
from datetime import UTC, datetime
import sqlalchemy as sa
from db_notes import db, mcp, notes
from fastmcp.server.dependencies import get_http_headers
from nimblebrain_server_sdk import CHANGES, new_prefixed_id
from nimblebrain_server_sdk.db import SecurityContext, security_context_from_edge_headers
from nimblebrain_server_sdk.errors import ErrorCode, ServiceError
from 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_outbox takes the session factory and identity function the server’s tools already use, so the outbox is authorized by the same code as the tools.
  • emit runs 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.
  • eventId is the idempotency key, unique per workspace. Emitting the same id again is a no-op that returns None. Use the upstream’s delivery id when there is one.

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_resource with no scheme, or a javascript:, data:, vbscript:, file: or blob: one.

Because the raise rolls the caller’s transaction back, trim unbounded upstream text deliberately with the exported limits, as share_note does.

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.

  • cursor is opaque. A read with none starts from now: a cursor and no history.
  • truncated: true means events after the cursor exist that this answer will never carry: the row cap dropped them, maxAgeMs excluded them, or the cursor cannot be honoured, as after a database restore. It is not an error.
  • hasMore: true means the batch was cut at maxEvents; poll again at once.
  • on_read(ctx, conn), an argument to register_outbox, runs before the read in the same transaction and may return a nextPollMs. 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 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 emit holds each workspace to max_rows (10,000), dropping the oldest; that loss is what truncated reports.
  • Metrics are on the [observability] registry: notify_emitted_total{name}, notify_read_total, notify_outbox_depth (undelivered rows after a poll) and notify_outbox_capped_total. name is the only label, so keep event names a closed set and put per-event values in data.
  • Postgres 13 or later, and an app role that is neither superuser nor BYPASSRLS.
test_outbox_notes.py
"""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 json
import os
from collections.abc import AsyncIterator
from typing import Any
import pytest
import sqlalchemy as sa
from db_migrate import APP_ROLE, migrate
from db_notes import db
from fastmcp import Client
from outbox_migrate import OUTBOX_TABLE, migrate_outbox
from outbox_notes import OUTBOX, mcp
from 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: S105
TABLES = 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.