Transactional outbox ve relay

Transactional outbox, iş verisini kaydetmek ile bu değişikliği başka servise bildirmek arasındaki boşluğu kapatır. Handler, yayınlanacak olayın kaydını kendi DB transaction’ına ekler. Commit başarılı olduktan sonra Lily’nin yönettiği relay bu kaydı broker’a publish eder.

Mesajı transaction’a ekleyin#

Public API, TransactionalOutboxMessage::try_new ile doğrulanan mesajı PostgresTransaction::enqueue veya MongoTransaction::enqueue üzerinden kabul eder. Ayrı bir Outbox::publish ya da handler tarafından yönetilen relay döngüsü yoktur. Aşağıdaki parça backend örneğindeki handler body’sine aittir; transaction ve outgoing o örneklerde tanımlıdır.

transaction.enqueue(TransactionalOutboxMessage::try_new(
    outgoing,
    "domain.events",
    "orders.persisted",
    1,
    PublishContentKind::Json,
    br#"{"status":"persisted"}"#.as_slice(),
)?).await?;

outgoing, uygulamanın verdiği nil olmayan UUID’dir. Event ID outbox tablosu/collection’ı içinde benzersizdir ve relay’in bütün publish denemelerinde değişmeden kalır. Aynı mantıksal olayı tekrar yayınlarken kimliği koruyun. Tamamen rollback edilmiş bir MongoDB body denemesinin yeni UUID üretmesi tek başına atomiklik ihlali değildir; commit edilmiş outgoing olayın yeniden yayınında yeni kimlik üretmek ise downstream deduplication’ı bozar.

Publish sırası ve başarının anlamı#

1. Relay, DB’den sınırlı sayıda ve byte bütçesinde kayıt claim eder.
2. Publish attempt sayısını kalıcı olarak ilerletir.
3. Canonical event/version/content headers ile persistent, mandatory publish yapar ve broker confirm bekler.
4. Başarılı confirm’den sonra DB kaydını delivered olarak işaretler.

Confirm, downstream handler’ın işini bitirdiğini göstermez. Confirm’den sonra process kapanıp delivered işareti yazılamazsa aynı kayıt yeniden publish edilebilir. Event ID sabit kalır; downstream consumer da idempotent olmalıdır. Unroutable mandatory publish başarılı teslimat sayılmaz; exchange ve destination binding’lerinin sahibi deployment/topology tasarımınızdır.

Kayıt, batch ve retry sınırları#

MongoDB ayrıca claim/failure metadata’sı için gereken alanla birlikte BSON belge boyutunu doğrular. Bu nedenle 16 MiB body’nin her MongoDB outbox belgesine sığacağı garanti edilmez. Boyut politikası DB enqueue aşamasında da geçerlidir; relay batch limitini artırmak tek mesajın mutlak sınırını artırmaz.

Publish denemeleri tükenirse kayıt silinmez; relay terminal hatayla sonuçlanır ve provider’ın failure sonucu Consumer lifecycle’ına taşınır. Bu durum sonsuz arka plan retry’si değildir. Public bir manual retry/reset API’si yoktur. Kalıcı kayıt ve operational evidence üzerinden nedeni inceleyin; kayıtları silip başarısız yayını gizlemeyin.

Ortak relay ve kapanış#

Aynı backend ve database_cell eşleşmesi bir relay paylaşır. O DB’yi kullanan queue’ların yalnız relay_* alanları değil, bütün TransactionalInboxConfig değerleri eşit olmalıdır. Queue başına aktif transaction takibi ayrı kalır. Çelişen policy startup sırasında reddedilir.

Graceful shutdown aktif işleri ve relay owner’larını mevcut application deadline altında kapatır; outbox’ın tamamen boşaldığını garanti etmez. Admission durduktan sonra commit olan veya publish edilemeyen kayıtlar DB’de kalıp sonraki startup’ta devam edebilir. shutdown_drain_timeout_millis, dış application deadline’ına süre eklemez. Operational snapshots ve shutdown ile sonucu gözleyin.