stemedb/applications/aphoria/dogfood/msgqueue/docs/sources/lapin-library.md

lapin Library Implementation Patterns - Key Excerpts for Message Queue Consumers

Authority Tier: Tier 3 (Community) Source: https://docs.rs/lapin/latest/lapin/ + GitHub issues Relevance: lapin is the most popular Rust AMQP client. Its documentation and issue tracker reveal common consumer implementation patterns and pitfalls specific to Rust async.

---

Async Runtime Requirements

lapin requires a tokio runtime. Blocking operations (std:🧵:sleep, std::fs::read, etc.) inside async functions will block the tokio event loop, degrading throughput to 1 message per blocking operation.

Key Claim:

• msgqueue/async/runtime :: blocking_forbidden = true
• Consequence: Blocking calls in async context degrade throughput to < 10 msg/sec

---

Connection Recovery Strategy

lapin supports automatic connection recovery via ConnectionProperties. Without recovery, a network blip requires manual reconnection. The recommended strategy is exponential backoff with jitter.

Key Claim:

• msgqueue/connection/recovery_strategy :: auto_reconnect_required = true
• Consequence: No auto-reconnect means transient failures become permanent until manual restart

---

Backpressure via Bounded Channels

Use tokio::sync::mpsc::channel with bounded capacity to implement backpressure. An unbounded channel (unbounded_channel) can lead to OOM if consumption is slower than production.

Key Claim:

• msgqueue/queue/max_size :: bounded_channel_required = true
• Consequence: Unbounded channel causes OOM when broker sends faster than consumer processes

---

Channel Pooling

Each AMQP channel is multiplexed over a single TCP connection. Create a small pool of channels (1-10) for parallel consumption. Too many channels exhaust broker resources.

Key Claim:

• msgqueue/connection/max_channels :: recommended_range = 1..10
• Consequence: Unbounded channels exhaust broker memory and file descriptors

---

Consumer Exclusive Mode

Set exclusive=true on basic.consume to guarantee single-consumer semantics. Without exclusivity, multiple consumers can race, leading to duplicate processing.

Key Claim:

• msgqueue/consumer/exclusive :: required_for_ordering = true
• Consequence: Non-exclusive consumers race, breaking message ordering guarantees

---

Manual Acknowledgment Patterns

Always call basic.ack after successful processing. Never ack before processing completes. Common mistake: ack in a spawned task that panics before completing.

Key Claim:

• msgqueue/consumer/ack_timing :: after_processing_only = true
• Consequence: Early ack causes data loss on panic/crash

---

Common Issues from GitHub

Issue #247: Unbounded Prefetch Causes OOM

User set prefetch_count=65535, broker sent all messages at once, consumer OOMed. Fix: Set prefetch to 10-100 based on message size.

Key Claim:

• msgqueue/consumer/prefetch_count :: max_safe_value = 100
• Consequence: prefetch > 100 risks OOM on large queues

Issue #312: No Requeue Limit Creates Poison Messages

Failed message requeued infinitely, blocking queue. Fix: Track redelivery count, reject after 3-5 attempts with requeue=false.

Key Claim:

• msgqueue/consumer/requeue_limit :: recommended_value = 3
• Consequence: Unlimited requeues create poison message loops

Issue #418: TLS Verification Disabled in Production

User disabled TLS verification for "testing", shipped to production, suffered MITM attack. Fix: Always enable TLS verification except local dev.

Key Claim:

• msgqueue/tls/certificate_validation :: production_required = true
• Consequence: Disabled TLS validation allows MITM attacks in production

---

Extraction Guide

1. Review Library Documentation:

   # Fetch lapin docs
   curl https://docs.rs/lapin/latest/lapin/ > lapin-docs.html
   

2. Search GitHub Issues:

   # Common problem patterns
   # https://github.com/amqp-rs/lapin/issues?q=is%3Aissue+label%3Abug
   

3. Look for Configuration Examples:

   • ConnectionProperties (recovery, heartbeat)
   • ConsumerOptions (ack mode, exclusive)
   • Channel usage patterns (pooling, cleanup)

4. Extract Patterns with Evidence:

   • What configurations cause bugs? (from issues)
   • What do docs recommend? (from README, examples)
   • What do async patterns require? (tokio-specific)

5. Map to Concept Paths:

   Async Runtime → msgqueue/async/runtime
   Recovery → msgqueue/connection/recovery_strategy
   Backpressure → msgqueue/queue/max_size
   Channels → msgqueue/connection/max_channels
   

---

Notes

• lapin is tokio-specific; futures-based executors won't work
• GitHub issues are gold mines for real-world failure modes
• Community examples often show anti-patterns (learn what NOT to do)