pixa/TODO.md

Pixa Implementation TODO

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

Project Setup

• 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 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