Skip to content

Messaging

See the Messaging guide.

rn_forge.django.messaging

Transactional outbox and inbox messaging over the Django ORM.

Import from the submodules; this app package cannot import models before Django's app registry is ready.

MessagingConfig

Bases: AppConfig

The messaging app. Its models are abstract, so it adds no tables.

Models

rn_forge.django.messaging.models

Abstract transactional outbox and inbox models.

AbstractInboxMessage

Bases: Model

A received message, recorded so a redelivery is recognised.

message_id accepts identifiers assigned by either the sender or broker.

AbstractOutboxMessage

Bases: Model

An event written in the same transaction as the change that caused it.

Preserve the (published_at, occurred_at) index when overriding Meta.

Relay

rn_forge.django.messaging.relay

The outbox relay: claim, publish and mark one batch.

make_outbox_relay(outbox_model, bus, *, envelope_builder, batch_size=100, on_lag_observed=None, log=None, clock=timezone.now)

Build a callable that claims, publishes and marks one batch of outbox rows.

Rows are claimed with select_for_update(skip_locked=True) in transaction.atomic(). A publish error rolls the claim back, so delivery is at least once.

Parameters:

Name Type Description Default
outbox_model type[M]

The consuming app's concrete outbox model.

required
bus MessageBus

Where messages go.

required
envelope_builder Callable[[M], Mapping[str, Any]]

Row → the event mapping published. Called once per row.

required
batch_size int

The most rows claimed per call.

100
on_lag_observed Callable[[float], None] | None

Called once per non-empty batch with the age, in seconds, of its oldest row — wire it to your metrics backend.

None
log Log | None

Receives outbox.relay per non-empty batch. Defaults to AppLogger at info.

None
clock Callable[[], datetime]

Supplies published_at and the lag reference.

now

Consumer

rn_forge.django.messaging.consumer

The inbox consumer: dedupe, dispatch and record one inbound event.

UnknownMessageType(message, *message_args, error_code=-1, **error_data)

Bases: AppException

No handler is registered for the event's type.

check(value, message, *message_args, **kwargs) classmethod

Raise this exception if value is falsy.

Parameters:

Name Type Description Default
value Any

The value to test.

required
message str

Exception message (supports positional format args).

required
*message_args Any

Forwarded to message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

Example::

AppException.check(path.exists(), "Missing file: {}", path, error_code=404)

process_event(event, registry, inbox_model, *, id_key='id', type_key='type', clock=timezone.now)

Handle event once, however many times it is delivered.

Handler writes and the processed marker commit atomically. Failures are recorded on the inbox row and re-raised for broker retry or dead-lettering.

Parameters:

Name Type Description Default
event Mapping[str, Any]

The received message. id_key/type_key name its id and type members (id/type, as in CloudEvents, by default).

required
registry HandlerRegistry

Type → handler.

required
inbox_model type[AbstractInboxMessage]

The consuming app's concrete inbox model.

required
clock Callable[[], datetime]

Supplies received_at/processed_at.

now

Returns:

Type Description
bool

True when the handler ran, False for a duplicate delivery.

Raises:

Type Description
UnknownMessageType

No handler is registered for the type.