feat: implement AWS Bedrock provider handler (issue #28) (#136)

## Summary

This PR implements issue #28 - AWS Bedrock provider handler as the MVP
provider for the proxy pattern. It establishes the provider abstraction
pattern that will be used for all future LLM provider integrations.

## Implementation Details

### Provider Infrastructure
- ✅ Core provider trait abstraction with async methods
- ✅ Provider registry for URL-based routing
- ✅ Zero-copy streaming support for minimal latency
- ✅ Comprehensive error handling and type safety

### AWS Bedrock Provider
- ✅ SigV4 authentication pass-through (no credential storage)
- ✅ Support for InvokeModel and InvokeModelWithResponseStream endpoints
- ✅ Model-specific handling for Claude, Titan, and Llama models
- ✅ Request/response metadata extraction
- ✅ Token usage tracking and cost calculation
- ✅ Comprehensive test coverage

### Response Processing
- ✅ Model-specific token extraction from response bodies
- ✅ Automatic cost calculation based on current pricing
- ✅ Provider metadata aggregation for audit logging

### Documentation
- ✅ Comprehensive provider integration guide
- ✅ Step-by-step instructions for adding new providers
- ✅ Testing strategies and performance considerations

## Testing

- ✅ Unit tests for all provider components
- ✅ Integration tests with mocked AWS responses
- ✅ Test coverage for authentication, routing, streaming, and error
handling
- ✅ All tests passing

## Key Design Decisions

1. **URL-based routing** - Following ADR-0011, providers are selected
based on URL path prefix
2. **Zero-copy streaming** - Responses stream directly through without
buffering
3. **Authentication pass-through** - No credential storage, headers
forwarded as-is
4. **Type-driven development** - Extensive use of newtypes and
validation at boundaries

## Files Added/Modified

### Core Provider Framework
- `src/providers/mod.rs` - Provider trait and registry
- `src/providers/response_processor.rs` - Response metadata processing

### Bedrock Provider
- `src/providers/bedrock/mod.rs` - Module organization
- `src/providers/bedrock/provider.rs` - Core provider implementation
- `src/providers/bedrock/auth.rs` - SigV4 authentication handling
- `src/providers/bedrock/models.rs` - Model-specific logic
- `src/providers/bedrock/types.rs` - Type definitions and pricing
- `src/providers/bedrock/tests.rs` - Comprehensive unit tests

### Integration Tests
- `tests/bedrock_integration.rs` - Integration tests with mocked
responses

### Documentation
- `docs/provider-integration.md` - Comprehensive integration guide

## Next Steps

This PR establishes the foundation for provider integration. Future
providers (OpenAI, Anthropic, etc.) can follow the same pattern
established here.

Closes #28

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jwilger

Cargo.lock

@@ -22,7 +22,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 eventcore = "0.1.8"
 eventcore-postgres = "0.1.8"
 eventcore-macros = "0.1.8"
-nutype = { version = "0.6", features = ["serde", "new_unchecked"] }
+nutype = { version = "0.6", features = ["serde", "new_unchecked", "regex"] }
 derive_more = { version = "2.0", features = ["debug", "display", "from", "into"] }
 chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1.0"
@@ -42,6 +42,12 @@ pin-project-lite = "0.2.16"
 crossbeam = "0.8.4"
 parking_lot = "0.12.4"
 urlencoding = "2.1.3"
+aws-config = "1.8.3"
+aws-sdk-bedrockruntime = "1.99.0"
+regex = "1.11.1"
+base64 = "0.22.1"
+rust_decimal = "1.37.2"
+currencies = { version = "0.4.1", features = ["serde"] }
 
 [dev-dependencies]
 tokio-test = "0.4"

Cargo.toml

@@ -0,0 +1,132 @@
+# 0019. Money Representation Strategy
+
+Date: 2024-01-26
+Status: Accepted
+
+## Context
+
+The Union Square proxy needs to track costs associated with LLM API calls for audit and analysis purposes. This requires:
+1. Storing prices per thousand tokens (often fractional cents, e.g., $0.003)
+2. Calculating actual costs based on token usage
+3. Serializing/deserializing monetary values for storage and API responses
+4. Ensuring proper rounding for billing purposes
+
+We evaluated several approaches:
+- Using floating-point numbers (rejected due to precision issues with money)
+- Using `rust_decimal::Decimal` throughout
+- Using dedicated money crates like `rusty-money`, `steel-cent`, or `currencies`
+- Building our own money type
+
+## Decision Drivers
+
+- **Precision**: Must accurately represent fractional cents for pricing
+- **Type Safety**: Prevent mixing monetary values with regular numbers
+- **Currency Support**: Should handle currency information (initially USD only)
+- **Serialization**: Must support serde for JSON API responses
+- **Rounding Rules**: Must support standard financial rounding (ceiling for costs)
+- **Performance**: Should not significantly impact response times
+
+## Considered Options
+
+### Option 1: Decimal Everywhere
+Use `rust_decimal::Decimal` for both prices and costs.
+
+**Pros:**
+- Simple, single type for all monetary values
+- Arbitrary precision
+- Good serde support
+
+**Cons:**
+- No currency information
+- No type distinction between prices and money
+- Easy to accidentally mix with non-monetary decimals
+
+### Option 2: rusty-money Throughout
+Use `rusty-money` crate for all monetary values.
+
+**Pros:**
+- Dedicated money type with currency support
+- Type safety
+- Rich API for money operations
+
+**Cons:**
+- No built-in serde support (deal breaker)
+- Cannot represent fractional cents well
+
+### Option 3: Hybrid Approach
+Use `Decimal` for prices (per-thousand-tokens) and a money crate for final costs.
+
+**Pros:**
+- Appropriate types for each use case
+- Type safety for actual money values
+- Can represent fractional cent prices
+
+**Cons:**
+- Two different types to manage
+- Potential confusion about when to use which
+
+## Decision Outcome
+
+We chose **Option 3: Hybrid Approach** using:
+- `rust_decimal::Decimal` for price-per-thousand-tokens
+- `currencies::Amount<USD>` for final cost calculations
+
+### Implementation Details
+
+```rust
+/// Price per thousand tokens (can be fractional cents)
+#[nutype(
+    validate(predicate = |price| *price >= Decimal::ZERO),
+    derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, AsRef)
+)]
+pub struct PricePerThousandTokens(Decimal);
+
+/// Calculate cost with ceiling rounding
+pub fn calculate_cost(
+    &self,
+    input_tokens: InputTokens,
+    output_tokens: OutputTokens,
+) -> Amount<USD> {
+    // Calculate in Decimal for precision
+    let total_cost_decimal = /* calculation */;
+
+    // Convert to cents with ceiling rounding
+    let total_cents = (total_cost_decimal * Decimal::from(100)).ceil();
+    let cents_u64 = total_cents.try_into().unwrap_or(0);
+
+    Amount::<USD>::from_raw(cents_u64)
+}
+```
+
+### Rounding Strategy
+
+All costs are rounded UP to the next penny (ceiling rounding), which is standard practice for usage-based billing systems. This ensures:
+- Providers are never under-compensated
+- Consistent with industry practices
+- Simple and predictable for users
+
+## Consequences
+
+### Positive
+- Type safety prevents mixing prices with costs
+- Currency information is preserved in cost values
+- Proper financial rounding is enforced
+- Clear distinction between pricing models and actual charges
+- Good serialization support for API responses
+
+### Negative
+- Breaking API change: `ProviderMetadata.cost_estimate` type changed
+- Developers must understand when to use each type
+- Additional dependency on `currencies` crate
+- Conversion logic needed between Decimal and Amount
+
+### Future Considerations
+- Easy to extend to other currencies when needed
+- Could add convenience methods for common conversions
+- May want to create specialized types for different pricing models
+
+## Links
+
+- [currencies crate documentation](https://docs.rs/currencies/)
+- [rust_decimal documentation](https://docs.rs/rust_decimal/)
+- PR #136 - Initial implementation

adr/0019-money-representation-strategy.md

@@ -0,0 +1,167 @@
+# 0020. Authentication Pass-Through Design
+
+Date: 2024-01-26
+Status: Accepted
+
+## Context
+
+Union Square acts as a proxy between applications and LLM providers. Each provider has different authentication mechanisms:
+- AWS Bedrock uses SigV4 signatures
+- OpenAI uses API keys in headers
+- Anthropic uses API keys in headers
+- Other providers may use OAuth, JWT, or other schemes
+
+We need to handle authentication in a way that:
+1. Maintains security without storing credentials
+2. Supports all provider authentication methods
+3. Allows the proxy to remain stateless
+4. Enables audit logging without exposing sensitive data
+
+## Decision Drivers
+
+- **Security**: Must never store or log credentials
+- **Transparency**: Proxy should not interfere with provider authentication
+- **Statelessness**: No session management or credential caching
+- **Flexibility**: Support diverse authentication schemes
+- **Auditability**: Track who makes requests without storing how
+
+## Considered Options
+
+### Option 1: Store and Manage Credentials
+Proxy stores credentials and makes requests on behalf of clients.
+
+**Pros:**
+- Centralized credential management
+- Could implement credential rotation
+- Clients don't need provider credentials
+
+**Cons:**
+- Major security risk
+- Compliance nightmare
+- Complex key management required
+- Violates principle of least privilege
+
+### Option 2: Re-sign Requests
+Proxy validates incoming auth, then re-signs with its own credentials.
+
+**Pros:**
+- Can validate authentication
+- Single set of provider credentials
+
+**Cons:**
+- Requires proxy to have provider credentials
+- Breaks direct accountability
+- Complex signature manipulation
+- Different logic for each provider
+
+### Option 3: Complete Pass-Through
+Forward authentication headers exactly as received.
+
+**Pros:**
+- No credential storage
+- Provider handles all validation
+- Maintains direct accountability
+- Simple and secure
+
+**Cons:**
+- Cannot validate authentication locally
+- Relies on provider error messages
+
+## Decision Outcome
+
+We chose **Option 3: Complete Pass-Through** for all authentication.
+
+### Implementation Pattern
+
+```rust
+// Extract auth headers without validation
+fn extract_sigv4_headers(headers: &HeaderMap) -> Result<Vec<(HeaderName, HeaderValue)>, ProviderError> {
+    let mut auth_headers = Vec::new();
+
+    for header_name in &[AUTHORIZATION, AMZ_DATE, AMZ_SECURITY_TOKEN, AMZ_CONTENT_SHA256] {
+        if let Some(value) = headers.get(header_name) {
+            auth_headers.push((header_name.clone(), value.clone()));
+        }
+    }
+
+    Ok(auth_headers)
+}
+
+// Forward exactly as received
+fn forward_request(&self, request: Request<Body>) -> Result<Response<Body>, ProviderError> {
+    // Extract headers
+    let auth_headers = extract_auth_headers(&request.headers())?;
+
+    // Forward unchanged
+    for (name, value) in auth_headers {
+        forwarded_request.headers_mut().insert(name, value);
+    }
+
+    // Let provider validate
+    client.request(forwarded_request).await
+}
+```
+
+### Security Considerations
+
+1. **No Logging**: Authentication headers are never logged
+2. **No Storage**: Credentials pass through memory only
+3. **No Validation**: We check presence, not correctness
+4. **Provider Errors**: Authentication failures return provider's error response
+
+## Consequences
+
+### Positive
+- Zero credential storage risk
+- Simple, stateless implementation
+- Supports all authentication schemes
+- Maintains accountability chain
+- Minimal attack surface
+- Easy to audit (what, not how)
+
+### Negative
+- Cannot provide early authentication validation
+- Dependent on provider error messages
+- No ability to implement credential rotation
+- Cannot aggregate requests under proxy credentials
+
+### Monitoring and Audit
+
+We track:
+- ✅ Which provider was called
+- ✅ When the request was made
+- ✅ Whether authentication succeeded (via response)
+- ❌ What credentials were used
+- ❌ Who made the request (unless in other headers)
+
+### Future Considerations
+
+If we need request attribution, we could:
+- Add optional Union Square API keys for client identification
+- Use mutual TLS for client authentication
+- Add request signing for non-repudiation
+
+But these would be IN ADDITION to, not INSTEAD OF, the pass-through authentication.
+
+### Proxy Authentication
+
+Union Square's authentication model (as per ADR-0006) uses API keys for client authentication. This is separate from provider authentication:
+
+1. **Proxy Authentication** (Union Square API key) - Identifies the client application to the proxy
+2. **Provider Authentication** (pass-through) - Authenticates the request to the LLM provider
+
+HTTP proxy standards (RFC 7235) define Proxy-Authorization headers for proxy authentication, but:
+- Traditional HTTP proxies are typically transparent to the application
+- Union Square is an application-level proxy with value-added features
+- We need to track usage per client for audit purposes
+
+Our approach:
+- Use `X-API-Key` header for Union Square authentication (already implemented)
+- Keep provider authentication separate and pass it through unchanged
+- This allows clients to use different provider credentials while sharing a proxy
+
+## Links
+
+- ADR-0006 - Authentication and Authorization (establishes API key pattern)
+- AWS SigV4 documentation
+- PR #136 - Bedrock provider implementation