documentation: Updating README

CLAUDE.md

···
    - `SqliteHandleResolver`: SQLite-backed persistent caching
    - Uses binary serialization via `HandleResolutionResult` for space efficiency
    - Resolution stack: Cache → RateLimited (optional) → Base → DNS/HTTP
+   - Includes resolution timing measurements for metrics
 
 2. **Binary Serialization** (`src/handle_resolution_result.rs`)
    - Compact storage format using bincode
···
    - XRPC endpoints for AT Protocol compatibility
    - Health check endpoint
    - DID document serving via .well-known
+   - CORS headers support for cross-origin requests
+   - Cache-Control headers with configurable max-age and stale directives
+   - ETag support with configurable seed for cache invalidation
+
+5. **Metrics System** (`src/metrics.rs`)
+   - Pluggable metrics publishing with StatsD support
+   - Tracks counters, gauges, and timings
+   - Configurable tags for environment/service identification
+   - No-op adapter for development environments
 
 ## Key Technical Details
 
···
 - `HTTP_EXTERNAL`: External hostname for service endpoints (e.g., `localhost:3007`)
 - `SERVICE_KEY`: Private key for service identity (DID format)
 
-### Optional
+### Optional - Core Configuration
 - `HTTP_PORT`: Server port (default: 8080)
 - `PLC_HOSTNAME`: PLC directory hostname (default: plc.directory)
+- `RUST_LOG`: Logging level (e.g., debug, info)
+
+### Optional - Caching
 - `REDIS_URL`: Redis connection URL for caching
 - `SQLITE_URL`: SQLite database URL for caching (e.g., `sqlite:./quickdid.db`)
+- `CACHE_TTL_MEMORY`: TTL for in-memory cache in seconds (default: 600)
+- `CACHE_TTL_REDIS`: TTL for Redis cache in seconds (default: 7776000)
+- `CACHE_TTL_SQLITE`: TTL for SQLite cache in seconds (default: 7776000)
+
+### Optional - Queue Configuration
 - `QUEUE_ADAPTER`: Queue type - 'mpsc', 'redis', 'sqlite', 'noop', or 'none' (default: mpsc)
 - `QUEUE_REDIS_PREFIX`: Redis key prefix for queues (default: queue:handleresolver:)
 - `QUEUE_WORKER_ID`: Worker ID for queue operations (default: worker1)
 - `QUEUE_BUFFER_SIZE`: Buffer size for MPSC queue (default: 1000)
 - `QUEUE_SQLITE_MAX_SIZE`: Max queue size for SQLite work shedding (default: 10000)
-- `CACHE_TTL_MEMORY`: TTL for in-memory cache in seconds (default: 600)
-- `CACHE_TTL_REDIS`: TTL for Redis cache in seconds (default: 7776000)
-- `CACHE_TTL_SQLITE`: TTL for SQLite cache in seconds (default: 7776000)
 - `QUEUE_REDIS_TIMEOUT`: Redis blocking timeout in seconds (default: 5)
+
+### Optional - Rate Limiting
 - `RESOLVER_MAX_CONCURRENT`: Maximum concurrent handle resolutions (default: 0 = disabled)
 - `RESOLVER_MAX_CONCURRENT_TIMEOUT_MS`: Timeout for acquiring rate limit permit in ms (default: 0 = no timeout)
-- `RUST_LOG`: Logging level (e.g., debug, info)
+
+### Optional - HTTP Cache Control
+- `CACHE_MAX_AGE`: Max-age for Cache-Control header in seconds (default: 86400)
+- `CACHE_STALE_IF_ERROR`: Stale-if-error directive in seconds (default: 172800)
+- `CACHE_STALE_WHILE_REVALIDATE`: Stale-while-revalidate directive in seconds (default: 86400)
+- `CACHE_MAX_STALE`: Max-stale directive in seconds (default: 86400)
+- `ETAG_SEED`: Seed value for ETag generation (default: application version)
+
+### Optional - Metrics
+- `METRICS_ADAPTER`: Metrics adapter type - 'noop' or 'statsd' (default: noop)
+- `METRICS_STATSD_HOST`: StatsD host and port (required when METRICS_ADAPTER=statsd, e.g., localhost:8125)
+- `METRICS_PREFIX`: Prefix for all metrics (default: quickdid)
+- `METRICS_TAGS`: Comma-separated tags (e.g., env:prod,service:quickdid)
 
 ## Error Handling
 
···
 - Connection pooling for Redis
 - Configurable TTLs for cache entries
 - Rate limiting via semaphore-based concurrency control
+- HTTP caching with ETag and Cache-Control headers
+- Resolution timing metrics for performance monitoring
 
 ### Code Style
 - Follow existing Rust idioms and patterns
 - Use `tracing` for logging, not `println!`
 - Prefer `Arc` for shared state across async tasks
 - Handle errors explicitly, avoid `.unwrap()` in production code
+- Use `httpdate` crate for HTTP date formatting (not `chrono`)
 
 ## Common Tasks
 
···
 - For in-memory: Set `CACHE_TTL_MEMORY` environment variable
 - For Redis: Set `CACHE_TTL_REDIS` environment variable
 - For SQLite: Set `CACHE_TTL_SQLITE` environment variable
+
+### Configuring Metrics
+1. Set `METRICS_ADAPTER=statsd` and `METRICS_STATSD_HOST=localhost:8125`
+2. Configure tags with `METRICS_TAGS=env:prod,service:quickdid`
+3. Use Telegraf + TimescaleDB for aggregation (see `docs/telegraf-timescaledb-metrics-guide.md`)
+4. Railway deployment resources available in `railway-resources/telegraf/`
 
 ### Debugging Resolution Issues
 1. Enable debug logging: `RUST_LOG=debug`
···
 4. Monitor queue processing in logs
 5. Check rate limiting: Look for "Rate limit permit acquisition timed out" errors
 6. Verify DNS/HTTP connectivity to AT Protocol infrastructure
+7. Monitor metrics for resolution timing and cache hit rates
 
 ## Dependencies
 - `atproto-identity`: Core AT Protocol identity resolution
···
 - `deadpool-redis`: Redis connection pooling
 - `metrohash`: Fast non-cryptographic hashing
 - `tokio`: Async runtime
-- `axum`: Web framework
+- `axum`: Web framework
+- `httpdate`: HTTP date formatting (replacing chrono)
+- `cadence`: StatsD metrics client
+- `thiserror`: Error handling

README.md

···
   - In-memory caching with configurable TTL (default: 600 seconds)
   - Redis-backed persistent caching (default: 90-day TTL)
   - SQLite-backed persistent caching (default: 90-day TTL)
+- **HTTP Caching**: Client-side caching support with:
+  - ETag generation with configurable seed for cache invalidation
+  - Cache-Control headers with max-age, stale-while-revalidate, and stale-if-error directives
+  - CORS headers for cross-origin requests
 - **Rate Limiting**: Semaphore-based concurrency control with optional timeout to protect upstream services
 - **Binary Serialization**: Compact storage format reduces cache size by ~40% compared to JSON
 - **Queue Processing**: Asynchronous handle resolution with multiple adapters:
···
   - Redis (distributed)
   - SQLite (persistent with work shedding)
   - No-op (testing)
+- **Metrics & Monitoring**: 
+  - StatsD metrics support for counters, gauges, and timings
+  - Resolution timing measurements
+  - Configurable tags for environment/service identification
+  - Integration guides for Telegraf and TimescaleDB
 - **AT Protocol Compatible**: Implements XRPC endpoints for seamless integration with AT Protocol infrastructure
 - **Comprehensive Error Handling**: Structured errors with unique identifiers (e.g., `error-quickdid-config-1`), health checks, and graceful shutdown
 - **12-Factor App**: Environment-based configuration following cloud-native best practices
···
 - `RESOLVER_MAX_CONCURRENT`: Maximum concurrent handle resolutions (default: 0 = disabled)
 - `RESOLVER_MAX_CONCURRENT_TIMEOUT_MS`: Timeout for acquiring rate limit permit in ms (default: 0 = no timeout)
 
+#### HTTP Cache Control
+- `CACHE_MAX_AGE`: Max-age for Cache-Control header in seconds (default: 86400)
+- `CACHE_STALE_IF_ERROR`: Stale-if-error directive in seconds (default: 172800)
+- `CACHE_STALE_WHILE_REVALIDATE`: Stale-while-revalidate in seconds (default: 86400)
+- `CACHE_MAX_STALE`: Max-stale directive in seconds (default: 86400)
+- `ETAG_SEED`: Seed value for ETag generation (default: application version)
+
+#### Metrics
+- `METRICS_ADAPTER`: Metrics adapter type - 'noop' or 'statsd' (default: noop)
+- `METRICS_STATSD_HOST`: StatsD host and port (required when METRICS_ADAPTER=statsd)
+- `METRICS_PREFIX`: Prefix for all metrics (default: quickdid)
+- `METRICS_TAGS`: Comma-separated tags (e.g., env:prod,service:quickdid)
+
 #### Logging
 - `RUST_LOG`: Logging level (e.g., debug, info, warn, error)
 
 ### Production Examples
 
-#### Redis-based (Multi-instance/HA)
+#### Redis-based with Metrics (Multi-instance/HA)
 ```bash
 HTTP_EXTERNAL=quickdid.example.com \
 SERVICE_KEY=did:key:yourkeyhere \
···
 QUEUE_WORKER_ID=prod-worker-1 \
 RESOLVER_MAX_CONCURRENT=100 \
 RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=5000 \
+METRICS_ADAPTER=statsd \
+METRICS_STATSD_HOST=localhost:8125 \
+METRICS_PREFIX=quickdid \
+METRICS_TAGS=env:prod,service:quickdid \
+CACHE_MAX_AGE=86400 \
 RUST_LOG=info \
 ./target/release/quickdid
 ```
···
 - `GET /_health` - Health check endpoint
 - `GET /xrpc/com.atproto.identity.resolveHandle` - Resolve handle to DID
 - `GET /.well-known/atproto-did` - Serve DID document for the service
+- `OPTIONS /*` - CORS preflight support for all endpoints
 
 ## Docker Deployment
 
···
 
 - [Configuration Reference](docs/configuration-reference.md) - Complete list of all configuration options
 - [Production Deployment Guide](docs/production-deployment.md) - Docker, monitoring, and production best practices
+- [Metrics Guide](docs/telegraf-timescaledb-metrics-guide.md) - Setting up metrics with Telegraf and TimescaleDB
 - [Development Guide](CLAUDE.md) - Architecture details and development patterns
+
+## Railway Deployment
+
+QuickDID includes Railway deployment resources in the `railway-resources/` directory for easy deployment with metrics support via Telegraf. See the deployment configurations for one-click deployment options.
 
 ## License