# 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
- [x] Create project structure (cmd/pixad, internal/*)
- [x] Implement globals package
- [x] Implement logger package
- [x] Implement config package
- [x] Implement database package (SQLite)
- [x] Implement healthcheck service
- [x] Implement middleware package
- [x] Implement handlers package with placeholder routes
- [x] Implement server package (lifecycle, routing, HTTP)
- [x] Wire up fx dependency injection in main.go
- [x] Verify basic server starts and healthcheck works

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

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

## Image Processing
- [x] Select and integrate image processing library (libvips bindings or pure Go)
- [x] Implement image decoding (JPEG, PNG, WebP, GIF, AVIF)
- [x] Implement image resizing with size options (WxH, 0x0, orig)
- [x] Implement format conversion (JPEG, PNG, WebP, AVIF)
- [x] Implement quality parameter support
- [ ] Implement max input dimensions validation
- [ ] Implement max output dimensions validation
- [ ] Implement EXIF/metadata stripping
- [x] 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
- [x] 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
- [x] Implement X-Pixa-Cache debug header (HIT/MISS/STALE)
- [ ] Implement X-Request-ID propagation
- [x] Implement proper error response format (JSON)

## Additional Endpoints
- [x] 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)
- [x] Write unit tests for URL parsing
- [x] Write unit tests for signature generation/verification
- [x] Write unit tests for cache operations
- [x] Write unit tests for image processing
- [ ] 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