Yapılandırma referansı · Consumer

Consumer bağlantısı, topology, delivery, inbox/outbox ve lifecycle ayarlarının varsayılanları ve sınırları.

Bu referans lilyrs 0.1.0 Consumer contract’ını özetler. Süre alanlarının birimi isimlerinde yazılıdır; _millis ile _secs alanlarını karıştırmayın. Bilinmeyen typed config alanları reddedilir. TOML’i başarıyla deserialize etmek bütün runtime contract’larının doğrulandığı anlamına gelmez; topology ve bağlantı planları da hazırlanır.

Bölüm haritası#

Bölüm	Sorumluluk
`[rabbitmq.consumer]`	Consumer bağlantısı ve recovery profili
`[[rabbitmq.topology.queues]]`	Physical queue, binding ve delivery politikası
`[rabbitmq.topology.queues.retention]`	Ana queue, retry bucket ve DLQ için altı zorunlu sınır
`[rabbitmq.topology.queues.transactional_inbox]`	Seçili feature ile DB binding ve inbox/outbox policy
`[queue_client]` / `[[queue_client.cells]]`	Normal publisher bağlantıları; Consumer bağlantısından ayrıdır
`[postgresql]` / `[database]` / `[cache]`	Sırasıyla PostgreSQL / MongoDB / Redis entegrasyonları
`[lifecycle]`	Application shutdown bütçesi

Topology bölümü credential-free’dir: identity alanlarında ${secret:...} veya ${file:...} kullanmayın. Bağlantı secrets’ları ilgili connection bölümünde çözülür. Dosya keşfi, environment override ve resolver seçimi için configuration ve secrets rehberlerini izleyin.

Consumer bağlantısı#

Alan	Varsayılan	Kural
`connection_string`	Yok	URI yolu; ayrı username/password/hostname/port/vhost ile birlikte verilmez.
`username, password, hostname`	Yok	URI yoksa boş olmayan değerler zorunlu.
`port`	AMQP: 5672; AMQPS: 5671	Ayrı alanlarla kurulan bağlantının port’u.
`vhost`	/	Ayrı alan modunun varsayılanı; decoded URI vhost en çok 255 UTF-8 byte.
`use_tls`	Yok	Açık true/false zorunlu; URI scheme ile uyuşmalı.
`pool_size`	5	1–32; bağlantı sayısı, handler concurrency değildir.
`connection_timeout_secs`	10	1–120 saniye.
`confirm_timeout_secs`	10	1–300 saniye.
`heartbeat_secs`	30	5–600 saniye.
`max_reconnect_attempts`	5	1–100 bağlantı/reconnect denemesi.
`reconnect_backoff_millis`	250	50–30.000 ms.
`persistence_enabled`	true	Bağlantı seçeneklerine taşınır. Consumer retry/DLQ gelen mesajın properties değerlerini korur; transactional outbox daima persistent yayınlar. Normal publisher tercihi `[queue_client]` altındadır.

connection_string içinde query veya fragment desteklenmez; heartbeat ve timeout için typed alanları kullanın. URI’nin host, username ve password içermesi gerekir. use_tls = true amqps://, false ise amqp:// ister. Ayrı alanlardaki varsayılan / vhost ile URI’de açık trailing slash’ın empty-vhost anlamını karıştırmayın.

TLS ve mTLS materyali#

`[rabbitmq.consumer.tls]` alanı	Kural
`additional_ca_bundle`	İsteğe bağlı absolute PEM path; platform trust store’a eklenir; en çok 4 MiB.
`client_certificate_chain`	İsteğe bağlı absolute PEM path; en çok 1 MiB.
`client_private_key`	İsteğe bağlı absolute, şifresiz PEM private key path; en çok 128 KiB.

Client certificate ile private key birlikte verilir; biri eksikse bağlantıdan önce reddedilir. TLS materyalini use_tls = false ile vermeyin. Publisher single ve factory cell’leri aynı TLS contract’ını kendi tls tablolarında kullanır. Ayrıntılı kurulum transport security sayfasındadır.

Queue identity ve topology#

Alan	Varsayılan	Kural
`name, exchange_name, routing_key`	Zorunlu	1–200 UTF-8 byte; boş, çevre whitespace veya control karakter kabul edilmez.
`exchange_kind`	direct	Desteklenen exchange kind.
`queue_type`	classic	classic veya quorum.
`topology_ownership`	framework_managed	framework_managed veya external.
`durable`	true	Quorum için true zorunlu.
`exclusive`	false	true desteklenmez.
`auto_delete`	false	Quorum için true reddedilir.
`single_active_consumer`	false	Aktif consumer seçimi; process sayısı veya concurrency ayarı değildir.
`max_priority`	Yok	Classic için isteğe bağlı 1–16; quorum için verilmez.
`message_ttl_ms`	Yok	Verilirse pozitif u32; ana queue message TTL.
`dead_letter_exchange`	{exchange_name}.dlx.v2	External ownership için açıkça zorunlu.
`dead_letter_routing_key`	Queue adı	External ownership için açıkça zorunlu.

Türetilmiş retry/DLQ adları da 200-byte identity sınırına uymalıdır; uzun bir base name tek başına geçerli görünse de türetilmiş adı aşabilir. DLQ adı {queue_name}.dlq.v2 olur. External ownership kaynakları operator provision eder; Lily’nin passive kontrolü yönetim API’sinden bütün broker policy’lerini eksiksiz denetlemek anlamına gelmez.

Delivery, concurrency ve retry#

Alan	Varsayılan	Kural
`concurrency`	1	1–1024 handler permit’i.
`prefetch_count`	10	1–4096 unacked delivery.
`delivery_buffer_capacity`	prefetch_count	1–prefetch_count; bounded local buffer.
`max_message_size_bytes`	1048576	1–16777216 byte; decode/clone öncesi uygulanır.
`retry_attempts`	0	0–100; ilk delivery’den sonraki ek denemeler.
`retry_backoff_millis`	1000	100–300000 ms.
`max_retry_backoff_millis`	60000	Başlangıç backoff’u–900000 ms.
`retry_jitter_ratio`	0.0	Finite 0.0–0.5.
`delivery_execution_timeout_millis`	30000	100–900000 ms; pipeline ve cleanup için toplam delivery bütçesi.
`settlement_timeout_millis`	5000	1–60000 ms; bir original ACK/NACK işlemi için.

DeliveryDeadline, normal before/guard/extractor/handler/after işlemlerinin ortak cutoff’udur. Her aşama için yeni timeout veya normal after için ikinci reserve başlamaz. Jitter fixed queue-level TTL bucket’ları arasından deterministik seçim yapar; her mesaj için sınırsız ayrı delay queue oluşturmaz. Bir logical queue için en çok 32, toplam topology için 4096 retry bucket kabul edilir.

Altı zorunlu retention alanı#

Alan	Anlamı
`main_max_messages`	Ana queue message sayısı
`main_max_bytes`	Ana queue body byte toplamı
`retry_bucket_max_messages`	Her retry bucket’ın message sayısı
`retry_bucket_max_bytes`	Her retry bucket’ın body byte toplamı
`dead_letter_max_messages`	DLQ message sayısı
`dead_letter_max_bytes`	DLQ body byte toplamı

Bunlar [rabbitmq.topology.queues.retention] altında birlikte verilir; varsayılan yoktur. Her değer 1..=i64::MAX aralığındadır. Bu broker saklama sınırlarıdır; uygulamanın toplam heap bütçesi veya DB inbox retention süresi değildir. retry_attempts = 0 seçilse de typed retention contract’ı korunur.

Transactional inbox ve outbox#

Bu tablo, [rabbitmq.topology.queues.transactional_inbox] alanlarını kapsar. İlgili facade feature’ı açık olmalıdır. backend zorunlu postgresql veya mongodb değeridir. database_cell factory modunda zorunlu, single modunda yasaktır; verilirse 1–128 UTF-8 byte, trimmed ve control-free olmalıdır.

Alan	Varsayılan	Kural
`inbox_lock_timeout_millis`	30000	1–60000; MongoDB alt sınırı 1000.
`outbox_claim_lease_millis`	30000	1–900000; publish timeout’tan kısa olamaz.
`relay_batch_size`	100	1–1000 kayıt.
`relay_max_in_flight_bytes`	8388608	1–268435456; tek mesaj mutlak sınırı ayrıca 16 MiB.
`relay_poll_interval_millis`	250	1–60000.
`relay_publish_timeout_millis`	10000	1–60000.
`relay_max_publish_attempts`	5	1–100; ilk publish dahil.
`relay_retry_initial_backoff_millis`	250	1–60000.
`relay_retry_max_backoff_millis`	30000	1–900000; initial backoff’tan küçük olamaz.
`inbox_retention_secs`	604800	1–31536000; tamamlanmış inbox.
`outbox_retention_secs`	604800	1–31536000; delivered outbox.
`cleanup_interval_secs`	3600	1–86400; iki retention süresini de aşamaz.
`shutdown_drain_timeout_millis`	30000	1–300000; dış shutdown deadline’ını uzatmaz.

inbox_lock_timeout_millis, uygulama transaction’ının azami çalışma süresi değildir. İşin gerçek deadline’ı delivery ve host bütçeleriyle ayrıca sınırlıdır. Aynı backend/cell’e bağlı queue’ların bütün transactional config’i eşit olmalıdır. Bu relational kurallar programmatic config ile de atlanamaz.

MongoDB transaction retry policy#

Aşağıdaki alanlar [rabbitmq.topology.queues.transactional_inbox.mongodb] altındadır. Tablo verilmezse varsayılan policy kullanılır; PostgreSQL binding’i altında verilmesi hatadır.

Alan	Varsayılan	Kural
`max_transaction_attempts`	3	1–100; ilk body çalışması dahil.
`retry_initial_backoff_millis`	10	1–60000.
`retry_max_backoff_millis`	1000	1–900000; initial’dan küçük olamaz.
`commit_retry_timeout_millis`	10000	1–60000; mevcut work deadline ile ayrıca sınırlı.

Body replay, commit reconciliation ve lease contention farklı yollardır. Bunları queue’nun retry_attempts değeriyle tek sayaç gibi düşünmeyin. MongoDB transaction’ları hangi durumda pipeline’ın tekrar çalıştığını açıklar.

Lifecycle ve builder seçimleri#

Seçim	Varsayılan / sınır
`[lifecycle].shutdown_timeout_secs`	30 saniye; 1–3153600000. Tek aggregate shutdown bütçesi.
`.pipeline_initialization_timeout(Duration)`	30 saniye; sıfırdan büyük, en çok 300 saniye. Bütün pipeline constructor’ları için ortak.
Tracing	Disabled; owned config/path veya external açıkça seçilir.
AsyncAPI	Opt-in `consumer-asyncapi` ve bir `.asyncapi(config)` çağrısı.
Container	Consumer-owned veya açık `.container(Arc<ApplicationContainer>)`.

Bu üst sınırlar önerilen production timeout değerleri değildir. Kapanışta her alt aşama için yeniden süre başlatılmaz; pending DI rollback de Consumer attempt root’u ile sınırlandırılır. Source belgelerindeki eski deadline/rollback ifadelerinin düzeltilmiş karşılıkları sorun giderme sayfasında kayıtlıdır.

Publisher profilinin yeri#

[queue_client] kendi mode = "single" veya "factory" seçimini yapar. Single profilde connection alanları bu tabloda, factory modunda [[queue_client.cells]] altında ve zorunlu name ile tanımlanır. Consumer bağlantısını publisher bağlantısı yerine kullanmak için section adını değiştirmeyin. Publisher connection alanları yukarıdaki typed TLS/timeout contract’ını paylaşır; factory cell’de verilmeyen pool_size runtime varsayılanı 1, serde single profilinin varsayılanı 5’tir.

Publisher-only topology bootstrap açık bir işlemdir ve credential-free [rabbitmq.topology] planını kullanır. Mesaj göndermek için gerekli facade features, envelope ve confirm işleyişi publishing sayfasındadır. DB ve Redis alanlarının kendi backend doğrulama kuralları vardır; bunlar Consumer queue policy alanları değildir.