Skip to content

docs: correct what the outbox page says about a failed Post - #216

Merged
iancooper merged 1 commit into
BrighterCommand:masterfrom
guilhermeappel:docs/4489-outbox-post-section
Nov 7, 2026
Merged

iancooper merged 1 commit into
BrighterCommand:masterfrom
guilhermeappel:docs/4489-outbox-post-section

Conversation

@guilhermeappel

Copy link
Copy Markdown
Contributor

Corrects what the Outbox Support page says about a failed Post. This is the smaller direction in issue BrighterCommand/Brighter#4489, "an update to the Post section in line with ADR 0063". It doesn't finish that issue: the failure channel is still being designed in PR BrighterCommand/Brighter#4725.

The page told readers that Post throws once the retries are used up, and to catch that with a Fallback method. That holds for a failed write to the outbox, which throws a ChannelFailureException. A failed send to the broker is logged, Post returns and the message stays in the outbox. ADR 0063-failed-delivery-context says the same for producers that confirm through a callback: "message stays un-dispatched, nothing bubbles, Sweeper still retries". So a Fallback method never sees a failed send, and without a sweeper or a resend from your own code nothing sends it again. The Post section now says which failure throws and which does not, and links to the sweeper section.

It also named CommandProcessor.RETRYPOLICY in four places, for the write and the send. Both run in the CommandProcessor.OutboxProducer resilience pipeline, which retries three times with a linear back-off from 50 ms by default, and RETRYPOLICY is marked obsolete. Three of those places now name the pipeline, two of them outside the Post section, in Deposit and Clear and in Explicit Clear, and Explicit Clear now also says that a failed send does not throw. The fourth, the UsePolicy caveat, now talks about ChannelFailureException and names UseResiliencePipeline beside UsePolicy. The Post section also links to the page on registering pipelines.

I read this in OutboxProducerMediator at the 10.7.0 and 10.8.1 tags and on master. I did not run Brighter for this PR. linkcheck and symbolcheck report nothing, and pagelint reports no errors and no warnings for the page. I did not run blockcheck, because this change touches no code block.

Two other pages make the same claim about RETRYPOLICY: the Command Processor Configuration Reference, and the legacy section of How Configuring the Command Processor Works. I left them out to keep this to one page, because the reference section also covers the circuit breaker, which this PR doesn't touch. I can send them in a separate PR if you'd like.

The page says an exception bubbles out of Post after the retries and
points to a Fallback method to catch it. A failed send to the broker
does not bubble out: Brighter logs it, Post returns and the message
stays in the outbox. A failed write to the outbox does throw, as a
ChannelFailureException.

The page also names CommandProcessor.RETRYPOLICY for that write and
that send. Both run in the CommandProcessor.OutboxProducer resilience
pipeline, and RETRYPOLICY is marked obsolete. The same name in Deposit
and Clear and in Explicit Clear changes too, and Explicit Clear now
says that a failed send does not throw.
@iancooper
iancooper merged commit a4569f4 into BrighterCommand:master Nov 7, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants