Module write_hooks 

Write hooks: code that runs inside a write’s own transaction, with the change in hand.

GenericCrudService runs every write of an entity (create, update, patch, delete, restore, hard delete, their bulk forms, and a state-machine transition) inside one database transaction (backbone_orm::in_write_tx), in this order:

1. the write guard,
2. ServiceLifecycle::before_*,
3. WriteHooks::before,
4. the repository write,
5. ServiceLifecycle::after_*,
6. WriteHooks::after,
7. commit.

A failure at any step rolls the whole write back: the row, whatever the hooks wrote and every event they staged. After the commit the service’s [CrudEventPublisher] keeps its best-effort in-process role, and nothing else.

The schema generator emits a WriteHooks implementation per model from its declared events (on: in a hook file’s events:), which stages them with WriteCtx::stage. Hand code can implement the trait too, and compose it with with_write_hooks.

What a hook may rely on

• Statements it runs through the ORM’s scoped helpers, the repository, or WriteCtx::stage ride the write’s transaction and see its uncommitted rows.
• A connection a hook opens itself (a bare pool.begin()) is another transaction: it cannot see the row being written, and a statement of it that waits for a lock the write holds waits for a commit that is waiting for the hook.
• A hook that holds the transaction open for a slow call (HTTP, a queue) holds a database connection and the row locks for as long. Stage an event and let the relay do the slow part.

Structs

NoWriteHooks

The hooks of a service that has none: every write runs in its transaction and nothing more.

OutboxRecord

A serialized domain event staged in the outbox and carried to consumers.

WriteCtx

What a write hook knows about the write it runs in.

Enums

Change

One row change, as a write hook sees it.

ChangeKind

The kind of a Change, without its rows.

Traits

DeclaredEvent

A fact the module declares it publishes (events: in a schema file), as the generated typed struct of its payload.

WriteHooks

Code that runs inside a write’s transaction, before and after the repository write.

Functions

current_correlation_id

The correlation id with_correlation_id bound for the current task.

migrate_outbox

Create the outbox and inbox tables of schema (idempotent), where the events its hooks stage are written. The composing service runs it at startup, with a role that may create tables; the generated module offers it for each schema it stages in (declared::migrate_outbox).

payload_from_row

The payload of a declared event, read out of the row the write stored: the fields listed, by their serialized names, deserialized into the event’s struct. A listed field the row lacks is left out, so an optional one reads as None and a required one is an error — the generator only lists fields the aggregate has.

with_correlation_id

Run f with id as the correlation id of every write it makes: the id the events staged by those writes carry, so one request’s rows, events and logs share it. The generic write routes do this from the x-correlation-id request header (see correlation_middleware).