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 |
None
|
clock
|
Callable[[], datetime]
|
Supplies |
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 |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
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. |
required |
registry
|
HandlerRegistry
|
Type → handler. |
required |
inbox_model
|
type[AbstractInboxMessage]
|
The consuming app's concrete inbox model. |
required |
clock
|
Callable[[], datetime]
|
Supplies |
now
|
Returns:
| Type | Description |
|---|---|
bool
|
|
Raises:
| Type | Description |
|---|---|
UnknownMessageType
|
No handler is registered for the type. |