# AUDIT PROTOCOL: RUST WORKER / INDEXER

**Target Stack:** Rust (Tokio, SeaORM/SQLx, async streams)
**Context:** Long-running workers, blockchain indexers, batch processors
**Executor:** AI Agent / LLM
**Quality Target:** 90-95%

---

## 0. QUALITY PHILOSOPHY

Same as backend-rust.md: Target **90-95% quality**. Stop when >= 90.

---

## 1. PRIME DIRECTIVE: LEAN CODE

Same rules: Value, Necessity, Uniqueness, Relevance (YAGNI).

---

## 2. ARCHITECTURE & MODULARITY (WORKER-SPECIFIC)

### 2.1 Entry Point Clarity

- **Rule**: `main.rs` must clearly show operational modes and flow.
- **Violation**: Nested conditionals obscuring what the worker does.
- **Fix**: Clear mode switch at top level, documented with comments.

### 2.2 Module Separation

- **Rule**: Separate concerns by operational mode (production vs maintenance).
- **Violation**: Reindexing logic mixed with production indexing.
- **Fix**: Dedicated modules: `indexer/` for production, `reindexer/` for batch.

### 2.3 Repository Pattern

- **Rule**: Database operations isolated in repository structs.
- **Violation**: SQL queries scattered across service/processor code.
- **Acceptable**: Simple queries in processors if truly one-off.

### 2.4 Service Layer

- **Rule**: Business logic in services, not in processors or main.
- **Violation**: Complex parsing/validation in loop bodies.

---

## 3. PERFORMANCE & CONCURRENCY

### 3.1 Batch Operations

- **Rule**: Prefer batch inserts over individual writes in loops.
- **Violation**: `for item in items { repo.save(item).await }`.
- **Fix**: Accumulate in Vec, then `repo.save_batch(items).await`.

### 3.2 Parallel Processing

- **Rule**: Use `stream::iter().buffer_unordered(N)` for CPU-bound parallel work.
- **Violation**: Sequential processing when items are independent.
- **Acceptable**: Sequential when order matters or DB constraints require it.

### 3.3 Connection Pooling

- **Rule**: Share database connection pools, don't create per-operation.
- **Violation**: `Database::connect()` inside loops.

### 3.4 Connection Pool Sizing

- **Rule**: DB pool `max_connections` must be proportional to RAM: `RAM_MB / 10` max.
- **Violation**: `max_connections(100)` on a 512MB machine.
- **Violation**: `idle_timeout > 120s` or `max_lifetime > 1800s`.
- **Violation**: `acquire_timeout > 10s` — masks pool exhaustion.
- **Fix**: Apply limits from `stack/apis.md` Connection Pool section.
- **Severity**: **Critical** — causes OOM and connection exhaustion.

### 3.5 Blocking in Async

- **Rule**: No blocking operations in async without `spawn_blocking`.
- **Violation**: Heavy computation, file I/O, or `std::thread::sleep` in async fn.

---

## 4. RELIABILITY & RESILIENCE

### 4.1 Error Propagation

- **Rule**: Use `?` operator with proper error types. No silent failures.
- **Violation**: `let _ = dangerous_operation().await;` without logging.
- **Fix**: Log errors or propagate them.

### 4.2 Graceful Shutdown

- **Rule**: Workers must handle SIGTERM/SIGINT gracefully via `tokio::signal::ctrl_c()`.
- **Violation**: Abrupt termination losing in-flight work or leaking DB connections.
- **Acceptable**: Simple workers that checkpoint frequently.
- **Fix**: Add signal handler that sets a shutdown flag, then drain work before exiting.

### 4.2.1 HTTP Workers: Request Timeouts

- **Rule**: Workers exposing HTTP endpoints MUST have `TimeoutLayer` and `tcp_keepalive`.
- **Violation**: No timeout layer → zombie TCP connections accumulate.
- **Fix**: `TimeoutLayer::new(Duration::from_secs(30))` + `tcp_keepalive(Some(Duration::from_secs(60)))`.
- **Severity**: **Critical** — direct cause of connection exhaustion in production.

### 4.3 Checkpointing

- **Rule**: Long-running batch jobs must save progress periodically.
- **Violation**: Processing 100K items with no intermediate saves.
- **Fix**: Update bookmark/checkpoint every N items or every block.

### 4.4 Idempotency

- **Rule**: Operations should be safe to retry.
- **Violation**: Duplicate inserts causing failures on restart.
- **Fix**: Use `ON CONFLICT DO NOTHING` or check existence.

---

## 5. CODE HYGIENE (SAME AS BACKEND)

### 5.1 Error Handling

- **Rule**: `unwrap()` PROHIBITED in hot paths.
- **Acceptable**: `expect()` for startup initialization.

### 5.2 Dead Code

- **Rule**: No unused functions, imports, or variables.
- **Fix**: Delete or `#[allow(dead_code)]` with justification.

### 5.3 Logging

- **Rule**: Structured logging for observability.
- **Violation**: `println!` in production code.
- **Acceptable**: Progress logging at configurable intervals.

### 5.4 Comments

- **Rule**: Code should be self-documenting. Comments for "why", not "what".
- **Violation**: Obvious comments like `// increment counter`.

---

## 6. SECURITY

### 6.1 SQL Injection

- **Rule**: Parameterized queries only. Never string interpolation.

### 6.2 Secrets

- **Rule**: No hardcoded credentials. Use environment variables.

### 6.3 Input Validation

- **Rule**: Validate external data (RPC responses, user input).

---

## 7. AUDIT EXECUTION

1. **Scan** `src/` focusing on: main.rs, processors, services, repositories
2. **Identify** violations per category
3. **Categorize**:
   - **Critical**: Security, data loss risk, unwrap in hot paths
   - **Major**: Architecture violations, missing error handling, no batching
   - **Minor**: Dead code, cosmetic, logging gaps
4. **Score** (0-100):
   - < 80 = FAILED
   - 80-89 = NEEDS WORK
   - 90-95 = PASSED
   - > 95 = EXCELLENT
5. **Report** with file:line references