stemedb/applications/aphoria/dogfood/httpclient/DAY2-SUMMARY.md

Day 2 Summary: HTTP Client Implementation with Violations

Date: 2026-02-10 Status: ✅ COMPLETE Duration: ~2 hours Lines of Code: ~700

---

What We Built

HTTP Client Library (httpclient v0.1.0):

• Production-ready architecture with intentional violations for Aphoria detection
• Full Rust implementation using reqwest + tokio + rustls
• Inline claim markers (@aphoria:claim) for documentation
• Comprehensive test coverage validating violations exist

---

7 Intentional Violations Embedded

Violation 1: Unbounded Redirect Limit

Location: src/config.rs:33

// @aphoria:claim[safety] Redirect limit MUST NOT exceed 10
pub max_redirects: Option<usize>,  // Current: None (unbounded)

Authority: RFC 7231 Section 6.4 Should be: Some(10) Consequence: Infinite redirect loops exhaust client resources

---

Violation 2: Excessive Request Timeout

Location: src/config.rs:46

// @aphoria:claim[safety] Request timeout MUST NOT exceed 30 seconds
#[serde(default = "default_request_timeout")]
pub request_timeout: Duration,  // Current: 120s

Authority: Mozilla HTTP docs, RFC 7230 Should be: 30s Consequence: Slow services cause cascade failures

---

Violation 3: Excessive Connection Timeout

Location: src/config.rs:38

// @aphoria:claim[safety] Connection timeout MUST NOT exceed 10 seconds
#[serde(default = "default_connect_timeout")]
pub connect_timeout: Duration,  // Current: 60s

Authority: Mozilla HTTP docs, Requests library Should be: 10s Consequence: Unresponsive endpoints block connection pool

---

Violation 4: Missing Idle Timeout

Location: src/config.rs:56

// @aphoria:claim[safety] Idle timeout MUST be configured
#[serde(default)]
pub idle_timeout: Option<Duration>,  // Current: None

Authority: RFC 7230 Section 6.3 Should be: Some(60s) Consequence: Stale connections accumulate, waste resources

---

Violation 5: TLS Verification Disabled

Location: src/config.rs:66

// @aphoria:claim[security] TLS certificate validation MUST be enabled
#[serde(default = "default_verify_tls")]
pub verify_tls: bool,  // Current: false

Authority: OWASP A07:2021, Mozilla Security Guidelines Should be: true Consequence: Man-in-the-middle attacks, credential theft

---

Violation 6: TLS Version Too Low

Location: src/config.rs:76

// @aphoria:claim[security] TLS version MUST be >= 1.2
#[serde(default = "default_min_tls_version")]
pub min_tls_version: TlsVersion,  // Current: TLS 1.0

Authority: OWASP, Mozilla Security Guidelines Should be: TLS 1.2 Consequence: Vulnerable to protocol downgrade attacks (BEAST, POODLE)

---

Violation 7: No Retry Limit

Location: src/retry.rs:19

// @aphoria:claim[safety] Retry attempts MUST NOT exceed 3
#[serde(default)]
pub max_retries: Option<u32>,  // Current: None (unbounded)

Authority: Requests library, Mozilla HTTP docs Should be: Some(3) Consequence: Unlimited retries cause retry storms, amplify cascading failures

---

File Structure

httpclient/
├── Cargo.toml                   # Package manifest with workspace config
├── src/
│   ├── lib.rs                   # Library root (documentation)
│   ├── config.rs                # 6 violations (1-6)
│   ├── retry.rs                 # 1 violation (7)
│   ├── client.rs                # HTTP client implementation
│   ├── connection.rs            # Connection pool wrapper
│   ├── error.rs                 # Error types
│   └── tests/
│       └── basic.rs             # Placeholder for integration tests
├── .aphoria/
│   ├── config.toml              # Persistent mode config
│   └── claims.toml              # 22 claims from Day 1
├── docs/
│   └── sources/                 # Authority source documents
│       ├── http-rfcs.md
│       ├── mozilla-http.md
│       └── requests-library.md
├── create-claims.sh             # Day 1 batch claim creation
├── DAY1-SUMMARY.md              # Day 1 results
└── DAY2-SUMMARY.md              # This file

---

Test Coverage

15 tests, all passing:

Configuration Tests (config.rs)

• ✅ default_config_has_violations - Validates config fails validation
• ✅ production_config_is_valid - Production config passes validation
• ✅ violation_1_unbounded_redirects - Verifies max_redirects == None
• ✅ violation_2_excessive_request_timeout - Verifies 120s request timeout
• ✅ violation_3_excessive_connect_timeout - Verifies 60s connect timeout
• ✅ violation_4_missing_idle_timeout - Verifies idle_timeout == None
• ✅ violation_5_tls_verification_disabled - Verifies verify_tls == false
• ✅ violation_6_tls_version_too_low - Verifies min_tls_version == TLS 1.0

Retry Tests (retry.rs)

• ✅ default_retry_config_has_violation - Validates retry config fails validation
• ✅ production_retry_config_is_valid - Production retry config passes validation
• ✅ violation_7_no_retry_limit - Verifies max_retries == None
• ✅ backoff_is_exponential - Verifies exponential backoff (correct, not a violation)
• ✅ idempotent_only_is_true - Verifies idempotent-only retries (correct, not a violation)

Client Tests (client.rs)

• ✅ default_client_has_violations - Validates default client inherits violations
• ✅ idempotent_methods - Verifies GET/PUT/DELETE are idempotent, POST is not

---

Inline Claim Markers

8 inline claim markers embedded in code using @aphoria:claim syntax:

• 6 in src/config.rs (violations 1-6)
• 1 in src/retry.rs (violation 7)
• All markers include: category, invariant, consequence, authority

Example:

/// # VIOLATION 5: TLS Verification Disabled
/// @aphoria:claim[security] TLS certificate validation MUST be enabled -- MITM attacks, credential theft
///
/// **Authority:** OWASP A07:2021, Mozilla Security Guidelines
/// **Current value:** false
/// **Should be:** true
#[serde(default = "default_verify_tls")]
pub verify_tls: bool,

Benefits:

• Violations are self-documenting
• Markers can be detected during aphoria scan
• Can be formalized via aphoria claims formalize-marker <id>

---

Production-Safe Alternative

ClientConfig::production() and RetryConfig::production() provide violation-free configurations:

let config = ClientConfig::production();
// - max_redirects: Some(10)
// - connect_timeout: 10s
// - request_timeout: 30s
// - idle_timeout: Some(60s)
// - verify_tls: true
// - min_tls_version: TLS 1.2

assert!(config.validate().is_ok());  // ✅ Passes validation

---

Validation Functions

Built-in validation against Aphoria claims:

let config = ClientConfig::default();
assert!(config.validate().is_err());
// Error: "max_redirects MUST be <= 10 (RFC 7231);
//         connect_timeout MUST be <= 10s (Mozilla/Requests);
//         request_timeout MUST be <= 30s (Mozilla/RFC 7230);
//         idle_timeout MUST be configured (RFC 7230 Section 6.3);
//         verify_tls MUST be true (OWASP A07:2021);
//         min_tls_version MUST be >= 1.2 (OWASP/Mozilla)"

This validates our claims are accurate and testable.

---

Compilation & Build

Status: ✅ Compiles cleanly in release mode

cargo build --release
# Finished `release` profile [optimized] target(s) in 15.34s

cargo test
# test result: ok. 15 passed; 0 failed; 0 ignored; 0 measured

Dependencies:

• reqwest v0.12 (with rustls-tls, no default features)
• tokio v1.0 (async runtime)
• serde + serde_json (configuration serialization)
• thiserror (error handling)
• tracing (structured logging)

---

Next Steps (Day 3)

1. Initial scan with built-in extractors:

   aphoria scan --persist --format json > scan-results-v1.json
   

   Expected: 2-3/7 violations detected (TLS patterns, maybe timeout patterns)

2. Generate custom extractors if needed:

   /aphoria-custom-extractor-creator
   "Generate extractors for these HTTP client violations: ..."
   

   Expected: Skills generate declarative extractors for all 7 violations

3. Re-scan with custom extractors:

   aphoria scan --persist --format json > scan-results-v2.json
   

   Expected: 7/7 violations detected

---

Success Metrics (Day 2)

Metric	Target	Actual	Status
Violations embedded	7	7	✅
Files created	5-6	7	✅
Lines of code	~700	~700	✅
Tests passing	100%	15/15 (100%)	✅
Compiles cleanly	Yes	Yes	✅
Inline markers	7	8	✅
Time to complete	4-5 hours	~2 hours	✅

---

Key Insights

1. Inline claim markers work: @aphoria:claim syntax documents violations inline, making them discoverable during scan

2. Validation is testable: validate() methods prove claims are enforceable programmatically

3. Production-safe alternative demonstrates fixed state: ClientConfig::production() shows what "compliant" looks like

4. All violations are realistic: Each violation has:

   • Real-world consequence (not hypothetical)
   • Standards-based authority (RFC, OWASP, Mozilla)
   • Alignment with dbpool patterns (naming consistency)

5. Intentional violations are HARD: It's surprisingly difficult to write unsafe code in Rust without fighting the compiler. This demonstrates Aphoria's value — catching logic-level violations that pass type checking.

---

Conclusion

Day 2 complete: HTTP client library with 7 well-documented violations ready for Aphoria scanning.

Next: Day 3 - Scan and verify Aphoria detects all violations (with skills-generated extractors if needed).