add project structure files

2025-12-20 03:31:37 +01:00
parent 202e927918
commit 4cb29fa3d2
4 changed files with 360 additions and 0 deletions
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -0,0 +1,145 @@
+# FlaskPaste Roadmap
+
+## Current State
+
+FlaskPaste v1.0 is feature-complete for its core mission: a secure, minimal pastebin API.
+
+**Implemented:**
+- Full REST API (CRUD operations)
+- Binary content support with magic-byte MIME detection
+- Client certificate authentication
+- Content-hash deduplication (abuse prevention)
+- Automatic paste expiry
+- Security headers and request tracing
+- Container deployment support
+- Comprehensive test suite
+
+## Phase 1: Hardening (Current)
+
+Focus: Production readiness and operational excellence.
+
+```
+┌───┬─────────────────────────────────────┬────────────────────────────────────┐
+│ # │ Milestone                           │ Status
+├───┼─────────────────────────────────────┼────────────────────────────────────┤
+│ 1 │ Abuse prevention (dedup)            │ Implemented (pending commit)
+│ 2 │ Security headers complete           │ Done
+│ 3 │ Request tracing (X-Request-ID)      │ Done
+│ 4 │ Proxy trust validation              │ Done
+│ 5 │ Test coverage > 90%                 │ In progress
+│ 6 │ Documentation complete              │ In progress
+└───┴─────────────────────────────────────┴────────────────────────────────────┘
+```
+
+## Phase 2: Operations
+
+Focus: Deployment, monitoring, and maintenance tooling.
+
+```
+┌───┬─────────────────────────────────────┬────────────────────────────────────┐
+│ # │ Milestone                           │ Dependencies
+├───┼─────────────────────────────────────┼────────────────────────────────────┤
+│ 1 │ Prometheus metrics endpoint         │ None
+│ 2 │ Structured JSON logging             │ None
+│ 3 │ Admin API (stats, cleanup)          │ Auth improvements
+│ 4 │ Ansible deployment role             │ None
+│ 5 │ CI/CD pipeline                      │ Container registry access
+└───┴─────────────────────────────────────┴────────────────────────────────────┘
+```
+
+### Prometheus Metrics
+
+Expose `/metrics` endpoint with:
+- `flaskpaste_pastes_total` (counter)
+- `flaskpaste_pastes_created` (counter)
+- `flaskpaste_pastes_deleted` (counter)
+- `flaskpaste_pastes_expired` (counter)
+- `flaskpaste_storage_bytes` (gauge)
+- `flaskpaste_request_duration_seconds` (histogram)
+
+### Structured Logging
+
+Replace text logs with JSON format:
+- Timestamp, level, message, request_id
+- Consistent field names across all log entries
+- Compatible with log aggregation (Loki, ELK)
+
+## Phase 3: Features
+
+Focus: User-requested enhancements within scope.
+
+```
+┌───┬─────────────────────────────────────┬────────────────────────────────────┐
+│ # │ Feature                             │ Complexity
+├───┼─────────────────────────────────────┼────────────────────────────────────┤
+│ 1 │ Paste encryption (server-side)      │ Medium
+│ 2 │ Custom expiry per paste             │ Low
+│ 3 │ Paste size in response headers      │ Low
+│ 4 │ Burn-after-read option              │ Low
+│ 5 │ Paste password protection           │ Medium
+└───┴─────────────────────────────────────┴────────────────────────────────────┘
+```
+
+### Burn-After-Read
+
+Single-access pastes that delete after first retrieval:
+- `POST /` with `X-Burn-After-Read: true` header
+- Paste deleted after first `GET /<id>/raw`
+- Metadata `GET /<id>` does not trigger burn
+
+### Custom Expiry
+
+Allow per-paste expiry override:
+- `POST /` with `X-Expiry: 3600` header (seconds)
+- Capped at server maximum (e.g., 30 days)
+- Default unchanged for pastes without header
+
+## Phase 4: Ecosystem
+
+Focus: Integration with external systems.
+
+```
+┌───┬─────────────────────────────────────┬────────────────────────────────────┐
+│ # │ Integration                         │ Purpose
+├───┼─────────────────────────────────────┼────────────────────────────────────┤
+│ 1 │ CLI client (fpaste)                 │ User convenience
+│ 2 │ Neovim/Vim plugin                   │ Editor integration
+│ 3 │ Shell aliases/functions             │ Workflow integration
+│ 4 │ Webhook notifications               │ Automation triggers
+└───┴─────────────────────────────────────┴────────────────────────────────────┘
+```
+
+### CLI Client
+
+Standalone Python CLI:
+- `fpaste < file.txt` - Create paste from stdin
+- `fpaste file.txt` - Create paste from file
+- `fpaste -g <id>` - Get paste
+- `fpaste -d <id>` - Delete paste
+- Config file for server URL and cert path
+
+## Non-Goals (Explicit)
+
+These features will not be implemented:
+
+- **Web UI** - Out of scope; use API directly
+- **User accounts** - PKI handles identity
+- **Syntax highlighting** - Client responsibility
+- **Search/discovery** - Pastes are private by design
+- **Clustering** - Scale via container orchestration
+- **S3/PostgreSQL backend** - SQLite is sufficient
+
+## Decision Log
+
+| Date       | Decision                           | Rationale
+|------------|------------------------------------|-----------------------------------------
+| 2024-11    | SQLite only                        | Simplicity; no external dependencies
+| 2024-11    | No web UI                          | API-first; reduces attack surface
+| 2024-11    | Client cert auth                   | Integrates with existing PKI
+| 2024-12    | Content-hash dedup                 | Prevent spam without IP tracking
+
+## Review Schedule
+
+- **Monthly**: Review TODO.md, refine TASKLIST.md
+- **Quarterly**: Evaluate roadmap phases, adjust priorities
+- **Yearly**: Major version planning, scope review