# 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::thread::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:**
   ```bash
   # Fetch lapin docs
   curl https://docs.rs/lapin/latest/lapin/ > lapin-docs.html
   ```

2. **Search GitHub Issues:**
   ```bash
   # 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)