Fleet database notifications

stado_database::notifications::subscribe listens on an existing verified PostgreSQL connection opened through the fleet database client. It does not discover another endpoint, resolve another credential or introduce a product-owned PostgreSQL pool.

Receive changes without polling

A product can use notifications to wake a consumer after committing durable state, such as a newly imported inbox message. The notification itself is not the message and is not a delivery receipt.

let mut changes = stado_database::notifications::subscribe(&connection, channel).await?;

Subscribe first, then read the authoritative rows and retain the product's cursor. After changes.next().await?, read the rows after that cursor again. This order covers a commit between the initial snapshot and the receive. The product owns its channel naming, tenant authorization, durable cursor and transactional notification publication; the library does not infer any of them.

A synchronous product can create and consume subscriptions inside its existing Client::run or Client::run_cancellable operation, retaining the shared runtime and connection ownership. Cancellation ends that operation rather than starting a polling worker. Dropping a receive future cancels that receive; dropping the subscription releases its connection.

Refusals are terminal for the subscription

• A non-PostgreSQL connection is refused with its actual backend. There is no alternate engine or polling fallback.
• An empty channel or a channel containing NUL is refused.
• The server's max_identifier_length determines the channel byte limit. A longer name is refused, not silently truncated into a different channel. Failure to read that declaration retains the database's cause.
• Connection and LISTEN failures retain the selected channel and the underlying database cause.
• A lost connection ends the handle and reports that notifications may be missing. The library does not reconnect silently. A later receive on the same handle is refused rather than pretending delivery continued. Subscription::is_ended() exposes this terminal state without parsing prose.

Recovery is an explicit new subscription followed by a fresh authoritative snapshot. Notifications received while a connection was absent are not replayed by PostgreSQL. CLI and graphical consumers must display that loss and must not turn it into an empty successful list or a continuously connected indicator.

Real database qualification

The repository journey is tests/database/notifications/journey.rs, registered as the stado-database Cargo test target notifications. It subscribes before reading an isolated table, commits a row and its PostgreSQL notification in one transaction, and checks the committed row after receiving the notification. It also exercises invalid channel refusals, closes only its own client pool, and verifies that the failed subscription remains ended on the next receive. It removes its table and queries PostgreSQL to confirm absence.

The qualification inputs are explicit:

• STADO_TEST_NOTIFICATION_DATABASE: an isolated PostgreSQL database declaration, accessible through the fleet database client with permission to create and remove the journey's uniquely named table.
• STADO_TEST_NOTIFICATION_FLEET_HOME: the fleet selection used by that client.
• STADO_TEST_SOURCE_REVISION: the committed source revision to qualify.
• STADO_TEST_CARGO: the Cargo executable selected by the qualification host.

Run the repository-owned build-and-execute journey:

node tests/database/notifications/run.mjs

The runner refuses a mismatched revision, tracked changes or untracked source. It invokes Cargo with --locked, captures its compiler-artifact messages and selects the actual notifications test executable. It checks source again after compilation and writes build-manifest.json with source_revision and the measured binary_sha256. Only then does it run that exact executable with STADO_TEST_BUILD_MANIFEST naming the generated artifact. The test independently refuses a different source revision or executable digest. Supplying a handwritten manifest is not the documented qualification path.

The runner retains its own source digest, build and execution commands, complete stdout/stderr files, statuses, signals, candidate identity and failure cause in build/database-notifications/build-*/. A failed build, missing compiler artifact or changed source does not start the database journey. The journey retains its executable digest, source revision, command exit states, database observations and final verdict under build/database-notifications/. A missing declaration, inaccessible real database or missing build provenance is a failed qualification, not a skipped or simulated pass.