Skip to content

outbox

nimblebrain_server_sdk.outbox · install nimblebrain-server-sdk[outbox] · version 0.7.2

from nimblebrain_server_sdk.outbox import BODY_MAX, CursorError, DEFAULT_LEVEL

The server half of the notification contract.

Needs the [outbox] extra (pip install 'nimblebrain-server-sdk[outbox]'), which installs [db] and [observability]; imported without it, this package raises an ImportError that names the extra.

A server that learns something asynchronously — a domain it ordered went active, a reply landed — has nowhere to put the fact: nobody is calling it, and it must not grow a Slack client, learn a host’s address, or assert a workspace identity of its own. So it records, and something else moves and routes.

This is the recording half, and it is three things:

  • outbox_table / outbox_ddl — a table beside the server’s own, under the same nimblebrain_server_sdk.db RLS policy, so an outbox row is scoped by the same wall as a business row.
  • emit — an append inside the transaction that made the fact true.
  • read — the poll a host answers with, carrying the one property the design depends on: a poll never skips a row that was in flight when it ran (nimblebrain_server_sdk.outbox.core explains how).

register_outbox serves that poll as one MCP resource. It is a separate module because the core has no MCP dependency and should not gain one.

Adoption is ten lines; the README has them.

async def emit(conn: AsyncConnection, ctx: SecurityContext, envelope: dict[str, Any], *, title: str | None = None, level: str | None = None, subject: str | None = None, body: str | None = None, link_resource: str | None = None, max_rows: int = DEFAULT_MAX_ROWS, table: sa.Table | None = None) -> int | None

Append one envelope, in the caller’s transaction. Returns its seq.

Opens no transaction and takes no savepoint of its own: the append belongs to the write that made the fact true, so a rolled-back state change takes its event with it and a committed one cannot lose it. Returns None when eventId is already in this workspace’s outbox — a re-emit is a no-op, not an error.

tenant_id and workspace_id are stamped from ctx, never from the envelope, so the row is checked against the session’s identity by the INSERT policy’s WITH CHECK rather than by anything here.

Pass the presentation fields as keywords (title=, level=, subject=, body=, link_resource=) and the _meta["ai.nimblebrain/notification"] block is built for you, so no adopter types the reverse-DNS key. An envelope with no such block is still a notification, rendered from name.

def outbox_ddl(table: sa.Table) -> list[str]

The outbox’s DDL — both tables, their indexes, and the RLS policy.

For an alembic revision, beside the adopter’s other tables:

for statement in outbox_ddl(outbox_table(MetaData())):
op.execute(statement)

One statement per item, and never a semicolon inside one. asyncpg refuses multiple commands in a single execute, so a library that handed back one blob of SQL would make every adopter rediscover that and write its own splitter — which each of them has. The loop is the whole difference.

Rendered from the same Table the queries are built against, so a migration and a read cannot describe different columns.

def outbox_table(sa_metadata: sa.MetaData, name: str = DEFAULT_TABLE_NAME) -> sa.Table

Define the outbox on sa_metadata and return it.

A companion <name>_state table is defined alongside, holding the two per-workspace facts that are not events: the outbox epoch, which makes a cursor from before a database restore detectable rather than silently unmatchable, and how far the row cap has dropped, which is the only honest source for truncated. Both carry (tenant_id, workspace_id) and take the same RLS policy as the outbox itself.

async def read(conn: AsyncConnection, ctx: SecurityContext, cursor: str | None = None, max_events: int = DEFAULT_MAX_EVENTS, max_age_ms: int | None = None, *, next_poll_ms: int | None = None, table: sa.Table | None = None) -> dict[str, Any]

Answer one poll: the events after cursor, oldest first.

Returns the poll result — events, cursor, truncated, hasMore, and nextPollMs when the caller supplies one. Each event is an EventOccurrence carrying its own cursor, so a reader that stops part-way through a batch can resume from where it stopped.

cursor of None bootstraps: no history, just a cursor, so a newly installed connector does not open with a backlog nobody asked for. The rows it skips are stamped as decided rather than left unread — otherwise nothing could ever prune them or re-emit their ids (_stamp_skipped). max_age_ms bounds replay — the floor is the later of the cursor and now - max_age_ms, and rows the floor excludes make the answer truncated. max_events is capped at MAX_MAX_EVENTS; a batch cut there answers hasMore.

The read also carries retention: it stamps first_read_at on what it returns and deletes what has carried one for RETENTION, in this transaction, under this caller’s RLS.

def register_outbox(mcp: FastMCP, resource: str, session_factory: SessionFactory, identity_fn: IdentityFn, *, max_events: int = DEFAULT_MAX_EVENTS, on_read: OnRead | None = None, table: sa.Table | None = None, description: str | None = None) -> None

Serve this server’s outbox at the URI it declared.

resource is the manifest’s notifications.resource value, verbatim. The manifest is where the URI is declared and where the host reads it, so this argument must carry that same string — a server whose two disagree serves a URI the host never polls, and the failure surfaces as silence.

session_factory(ctx) opens the transaction (the server’s own secured session, such as SecuredDatabase.session); identity_fn() builds the security context from the edge-injected headers, the same call the server’s tools make. The handler runs inside the request’s header context, which is what makes both possible.

on_read(ctx, conn) runs first, in that same transaction, and may return a nextPollMs recommendation. It is how a server makes the poll its own tick: refresh what is pending, record what changed, and the events land in the answer to the poll that caused them. Returning a smaller number while something is pending asks the host to come back sooner; the host honours it inside its own floor and ceiling.

max_events is the page size when the caller names none, and the ceiling it is held to when it does.

Raises ValueError for a resource that is not a name this module can serve unchanged: a scheme, ://, then slash-separated segments of lowercase letters and digits with - or . inside a segment. That is this module’s own constraint rather than a restatement of the host’s admission rule — see _check_resource.

class CursorError(ValueError)

A cursor that cannot be honoured — malformed, or from another epoch.

Always recoverable: the caller replies with a fresh cursor and truncated: true, which is precisely what the field means.

class EnvelopeError(ValueError)

An envelope this outbox will not store. The message names the field.

BODY_MAX = 2000
DEFAULT_LEVEL = 'info'
DEFAULT_MAX_EVENTS = 100
DEFAULT_MAX_ROWS = 10000
DEFAULT_TABLE_NAME = 'notification_outbox'
ENVELOPE_MAX_BYTES = 64 * 1024
LEVELS = ('info', 'attention', 'urgent')
MAX_AGE_MS_CEILING = 100 * 365 * 24 * 60 * 60 * 1000
MAX_CURSOR_LENGTH = 1024
MAX_MAX_EVENTS = 500
NOTIFICATION_META_KEY = 'ai.nimblebrain/notification'
RETENTION = timedelta(days=7)
SUBJECT_MAX = 200
TITLE_MAX = 200