sneak
4ef9141960
- check: default target, runs fmt-check, lint, and test - fmt-check: verifies code is properly formatted - fmt: formats code with gofmt - lint: runs golangci-lint - test: runs go test - build: builds pixad binary with version info - clean: removes build artifacts
102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# 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
|