outbox
nimblebrain_server_sdk.outbox · install nimblebrain-server-sdk[outbox] · version 0.7.2
from nimblebrain_server_sdk.outbox import BODY_MAX, CursorError, DEFAULT_LEVELThe 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 samenimblebrain_server_sdk.dbRLS 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.coreexplains 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.
Functions
Section titled “Functions”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 | NoneAppend 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.
outbox_ddl
Section titled “outbox_ddl”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.
outbox_table
Section titled “outbox_table”def outbox_table(sa_metadata: sa.MetaData, name: str = DEFAULT_TABLE_NAME) -> sa.TableDefine 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.
register_outbox
Section titled “register_outbox”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) -> NoneServe 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.
Classes
Section titled “Classes”CursorError
Section titled “CursorError”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.
EnvelopeError
Section titled “EnvelopeError”class EnvelopeError(ValueError)An envelope this outbox will not store. The message names the field.
Constants
Section titled “Constants”BODY_MAX
Section titled “BODY_MAX”BODY_MAX = 2000DEFAULT_LEVEL
Section titled “DEFAULT_LEVEL”DEFAULT_LEVEL = 'info'DEFAULT_MAX_EVENTS
Section titled “DEFAULT_MAX_EVENTS”DEFAULT_MAX_EVENTS = 100DEFAULT_MAX_ROWS
Section titled “DEFAULT_MAX_ROWS”DEFAULT_MAX_ROWS = 10000DEFAULT_TABLE_NAME
Section titled “DEFAULT_TABLE_NAME”DEFAULT_TABLE_NAME = 'notification_outbox'ENVELOPE_MAX_BYTES
Section titled “ENVELOPE_MAX_BYTES”ENVELOPE_MAX_BYTES = 64 * 1024LEVELS
Section titled “LEVELS”LEVELS = ('info', 'attention', 'urgent')MAX_AGE_MS_CEILING
Section titled “MAX_AGE_MS_CEILING”MAX_AGE_MS_CEILING = 100 * 365 * 24 * 60 * 60 * 1000MAX_CURSOR_LENGTH
Section titled “MAX_CURSOR_LENGTH”MAX_CURSOR_LENGTH = 1024MAX_MAX_EVENTS
Section titled “MAX_MAX_EVENTS”MAX_MAX_EVENTS = 500NOTIFICATION_META_KEY
Section titled “NOTIFICATION_META_KEY”NOTIFICATION_META_KEY = 'ai.nimblebrain/notification'RETENTION
Section titled “RETENTION”RETENTION = timedelta(days=7)SUBJECT_MAX
Section titled “SUBJECT_MAX”SUBJECT_MAX = 200TITLE_MAX
Section titled “TITLE_MAX”TITLE_MAX = 200