# Pixa Implementation TODO

A single linear checklist of tasks to implement the complete pixa caching image reverse proxy server.

## Project Setup
- [x] Create Makefile with check, lint, test, fmt targets
- [ ] Create project structure (cmd/pixad, internal/*)
- [ ] Implement globals package
- [ ] Implement logger package
- [ ] Implement config package
- [ ] Implement database package (SQLite)
- [ ] Implement healthcheck service
- [ ] Implement middleware package
- [ ] Implement handlers package with placeholder routes
- [ ] Implement server package (lifecycle, routing, HTTP)
- [ ] Wire up fx dependency injection in main.go
- [ ] Verify basic server starts and healthcheck works

## Core Image Proxy Features
- [ ] Implement URL parsing for `/v1/image/<host>/<path>/<size>.<format>`
- [ ] Implement upstream HTTP client with TLS verification
- [ ] Implement SSRF protection (block private/internal IPs)
- [ ] Implement source host whitelist checking
- [ ] Implement HMAC-SHA256 signature generation
- [ ] Implement HMAC-SHA256 signature verification
- [ ] Implement signature expiration checking
- [ ] Implement upstream fetch with timeout and size limits
- [ ] Implement Content-Type validation (whitelist MIME types)
- [ ] Implement magic byte verification

## Caching Layer
- [ ] Design and create SQLite schema for cache metadata
- [ ] Implement source content storage (`cache/src-content/<hash>`)
- [ ] Implement source metadata storage (`cache/src-metadata/<host>/<hash>.json`)
- [ ] Implement output content storage (`cache/dst-content/<hash>`)
- [ ] Implement cache key generation
- [ ] Implement cache lookup (in-memory hot path)
- [ ] Implement cache write
- [ ] Implement negative caching (404s)
- [ ] Implement cache TTL and expiration
- [ ] Implement cache size management/eviction

## Image Processing
- [ ] Select and integrate image processing library (libvips bindings or pure Go)
- [ ] Implement image decoding (JPEG, PNG, WebP, GIF, AVIF)
- [ ] Implement image resizing with size options (WxH, 0x0, orig)
- [ ] Implement format conversion (JPEG, PNG, WebP, AVIF)
- [ ] Implement quality parameter support
- [ ] Implement max input dimensions validation
- [ ] Implement max output dimensions validation
- [ ] Implement EXIF/metadata stripping
- [ ] Implement fit modes (cover, contain, fill, inside, outside)

## Security
- [ ] Implement path traversal prevention
- [ ] Implement request sanitization
- [ ] Implement response header sanitization
- [ ] Implement referer blacklist
- [ ] Implement blocked networks configuration
- [ ] Add rate limiting per-IP
- [ ] Add rate limiting per-origin
- [ ] Add rate limiting global concurrent fetches

## HTTP Response Handling
- [ ] Implement proper Cache-Control headers
- [ ] Implement ETag generation and validation
- [ ] Implement Last-Modified headers
- [ ] Implement conditional requests (If-None-Match, If-Modified-Since)
- [ ] Implement HEAD request support
- [ ] Implement Vary header for content negotiation
- [ ] Implement X-Pixa-Cache debug header (HIT/MISS/STALE)
- [ ] Implement X-Request-ID propagation
- [ ] Implement proper error response format (JSON)

## Additional Endpoints
- [ ] Implement robots.txt endpoint
- [ ] Implement metrics endpoint with auth
- [ ] Implement auto-format selection (format=auto based on Accept header)

## Configuration
- [ ] Add all configuration options from README
- [ ] Implement environment variable overrides
- [ ] Implement YAML config file support
- [ ] Validate configuration on startup

## Operational
- [ ] Implement graceful shutdown
- [ ] Implement Sentry error reporting (optional)
- [ ] Add comprehensive request logging
- [ ] Add performance metrics (Prometheus)
- [ ] Write unit tests for URL parsing
- [ ] Write unit tests for signature generation/verification
- [ ] Write unit tests for cache operations
- [ ] Write integration tests for image proxy flow
- [ ] Write load tests to verify 1-5k req/s target

## Documentation
- [ ] Document configuration options
- [ ] Document API endpoints
- [ ] Document deployment guide
- [ ] Add example nginx/caddy reverse proxy config