stemedb/applications/aphoria/dogfood/httpclient/README.md

# HTTP Client Library (`httpclient`) - Project 2

**Status:** Ready to start (Project 1 complete)
**Purpose:** Demonstrate Aphoria's autonomous flywheel through pattern reuse from dbpool
**Duration:** 4 days (faster than Project 1's 5 days due to skills + pattern reuse)

---

## What Makes This Different from Project 1

**Project 1 (dbpool):** Established baseline
- Created 27 claims from scratch (manual workflow, 4 hours)
- 2-3 naming errors to fix
- Manual CLI workflow

**Project 2 (httpclient):** Demonstrates flywheel
- Reuse 8-10 claims from dbpool (skills-driven, 1-2 hours)
- 0 naming errors (skills enforce consistency)
- Autonomous workflow via skills

**Expected Results:**
- 50-60% time reduction for Day 1
- 40% pattern reuse
- 100% naming consistency

---

## Quick Start

### Pre-Flight Check

```bash
# Verify Project 1 corpus exists
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("dbpool"))] | length'
# Must return: 27

# Verify skills installed
ls -la ~/.claude/skills/ | grep aphoria | wc -l
# Must return: 8
```

**If both pass:** You're ready to start

**If either fails:** Complete Project 1 first or install skills

---

## What We're Building

**httpclient:** Production-ready HTTP client library with connection pooling, timeout management, and TLS enforcement.

**Why This Project:**
1. **Shares patterns with dbpool:** connection_timeout, TLS config, metrics
2. **Demonstrates flywheel:** Skills discover existing patterns, enforce aligned naming
3. **Real violations:** timeout cascades, redirect loops, TLS bypasses
4. **Measurable ROI:** "50% faster due to pattern reuse" + "Aphoria prevented production timeout cascade"

---

## 7 Intentional Violations

1. **Unbounded redirect limit** (should be ≤10)
2. **Excessive request timeout** (120s vs 30s max)
3. **Excessive connection timeout** (60s vs 10s max)
4. **Missing idle timeout** (connections never expire)
5. **TLS verification disabled** (MITM vulnerability)
6. **TLS version too low** (TLS 1.0 vs 1.2 minimum)
7. **No retry limit** (retry storms amplify failures)

**All violations have clear consequences and alignment with dbpool patterns.**

---

## Pattern Reuse from dbpool

| dbpool Pattern | httpclient Adaptation |
|----------------|----------------------|
| `connection_timeout: max 30s` | `request_timeout: max 30s` |
| `tls/enabled: required` | `tls/certificate_validation: required` |
| `tls/min_version: 1.2` | `tls/min_version: 1.2` (same) |
| `max_connections: required` | `max_redirects: max 10` (bounded resource) |
| `max_lifetime: required` | `idle_timeout: required` (lifecycle) |

**Skills will discover these patterns automatically on Day 1.**

---

## Day-by-Day Plan

### Day 1: Claims with Pattern Discovery (1-2 hours)

**Use skills:**
1. `/aphoria-suggest` - Discover reusable dbpool patterns
2. `/aphoria-claims` - Extract claims with enforced naming alignment

**Target:** 22 claims (8-10 reused, 12-14 new)

**See:** `plan.md` Day 1 for detailed workflow

---

### Day 2: Implementation (4-5 hours)

**Create library with 7 violations:**
- `src/config.rs` - 5 violations
- `src/client.rs` - 2 violations

**Document violations inline with `// VIOLATION:` comments**

**See:** `plan.md` Day 2 for file structure

---

### Day 3: Scan + Custom Extractors (2-3 hours)

**Initial scan:**
```bash
aphoria scan --persist --format json > scan-results-v1.json
```

**If built-in extractors insufficient:**
```
/aphoria-custom-extractor-creator
"Generate extractors for these violations..."
```

**Target:** 7/7 violations detected

**See:** `plan.md` Day 3 for extractor generation

---

### Day 4: Remediation (4-5 hours)

**Fix violations incrementally:**
- Fix 1 → scan-v2.json
- Fix 2 → scan-v3.json
- ...
- Fix 7 → scan-v8.json (0 conflicts)

**Git commit after each fix with context**

**See:** `plan.md` Day 4 for remediation workflow

---

### Day 5: Documentation (3-4 hours)

**Create:**
- `SUCCESS-STORY.md` - Flywheel metrics and evidence
- `DEMO-SCRIPT.md` - Stakeholder presentation

**Document:**
- Time savings: 60%+ reduction
- Pattern reuse: 40%+ claims
- Naming consistency: 100%

**See:** `plan.md` Day 5 for documentation requirements

---

## Success Criteria

### Minimum (Proves Skills Work)

- ✅ Day 1 in <2 hours (vs 4 hours)
- ✅ 8+ claims reused from dbpool
- ✅ 0 naming errors
- ✅ 7/7 violations detected

### Full (Proves Flywheel Works)

- ✅ All of above, plus:
- ✅ Skills generated all extractors
- ✅ Documented flywheel value:
  - Time: 60%+ faster
  - Reuse: 40%+ patterns
  - Consistency: 100% aligned

---

## Files

**Planning:**
- `plan.md` - Complete 5-day plan
- `CHECKLIST.md` - Day-by-day execution (similar to dbpool)
- `README.md` - This file

**Authority Sources (fetch on Day 1):**
- `docs/sources/http-rfcs.md` - RFC 7230-7235
- `docs/sources/mozilla-http.md` - Mozilla HTTP best practices
- `docs/sources/requests-docs.md` - Requests library patterns

**Implementation (Day 2):**
- `src/` - HTTP client library with violations
- `tests/` - Integration tests
- `Cargo.toml` - Dependencies

**Evidence (Days 3-5):**
- `scan-results-v*.json` - Progressive scan results
- `SUCCESS-STORY.md` - Flywheel demonstration
- `DEMO-SCRIPT.md` - Presentation guide

---

## Documentation

**Detailed plan:** `plan.md`
**Execution checklist:** `CHECKLIST.md` (reference dbpool's with Project 2 context)
**Pattern reuse guide:** `../dbpool/docs/multi-project-setup.md`

---

## Ready to Start?

1. ✅ Verify pre-flight checks pass (27 dbpool claims, 8 skills)
2. ✅ Read `plan.md` for complete context
3. ✅ Start Day 1 with `/aphoria-suggest` to discover patterns

**The flywheel is ready. Project 2 will prove it works.**