Skip to content

DEFERRED.md

Latest commit

 

History

History
101 lines (63 loc) · 5.56 KB

DEFERRED.md

File metadata and controls

101 lines (63 loc) · 5.56 KB
Raw

TraceAnywhere — Deferred Improvements

Purpose: Items worth doing eventually but not needed for Phase 1. Kept here so they don't clutter the spec but aren't lost. The design should not preclude any of these — if a current decision would make one of these harder later, reconsider.

Source: Gap analysis from Suggested-Improvements.md, filtered through practical priorities.

Phase 2

Environment Variable Configuration

Expose hardcoded values as env vars (TA_PORT, TA_DATA_DIR, TA_MAX_CONCURRENT_TRACES, TA_LOG_LEVEL, etc.). Ship a .env.example. Low effort once the code exists — just replace constants with os.getenv() calls.

Data Retention Policy

Configurable via TA_RETENTION_DAYS (default: 0 = keep forever). Daily cleanup job deletes stopped traces older than the retention period. Cascading deletes via foreign keys. Important once history browsing is implemented.

WebSocket Reconnection

Client reconnects with ?since=<timestamp>. Server resumes from that point. Prevents duplicate rendering. Already noted in spec section 6.2 as a Phase 2 item.

Backup & Restore Documentation

Document sqlite3 .backup procedure in README. Not a code feature — just operational guidance for users.

Basic Accessibility

Semantic HTML (<table> for hop table), ARIA labels for icon-only buttons, keyboard-navigable actions, color-blind safe palette. Good practice, not MVP-critical.

Phase 3

Target Allowlist

Optional TA_TARGET_ALLOWLIST env var (glob for hostnames, CIDR for IPs). Default: allow all. Only relevant for shared/public deployments, which the tool isn't designed for today — but may matter if someone runs a public demo instance.

Rate Limiting

In-memory sliding window, 10 trace starts per minute per client IP. Returns 429. Only matters if the tool is exposed to untrusted users.

Application Metrics (Prometheus)

GET /metrics endpoint exposing: active traces, total traces, probe results, probe failures, WebSocket connections, HTTP request counts. Design the internals so counters are easy to add later — don't bury state in closures.

Schema Enhancements

Additional columns for future features:

  • Trace.tags (JSON array), Trace.notes (freeform text)
  • TraceResult.destination_reached (boolean)
  • HopResult.asn (integer, for ASN lookup), HopResult.geo_country (text, for GeoIP)

Add via schema migrations when the features that use them are built.

Structured Logging

Switch from standard Python logging to structlog with JSON output. Include trace_id correlation. Makes log aggregation easier in multi-instance setups. For now, standard logging to stdout is fine — Docker captures it.

CAP_NET_RAW Security Documentation

Document in README why CAP_NET_RAW is needed, that it's scoped to the mtr binary via setcap, and that the Python process runs as non-root. Reassures security-conscious users.

Phase 4

API Versioning

When a breaking change is actually needed: prefix routes with /api/v2/. Keep v1 for 1-2 major versions. Don't version preemptively.

CORS

TA_ENABLE_CORS and TA_CORS_ORIGINS env vars for development or split frontend/backend deployments. Not needed while backend serves the frontend.

CI/CD Pipeline

GitHub Actions: lint (ruff), format check (black), unit tests, Docker build, integration tests, smoke tests. Auto-push to Docker Hub on main. Tag releases.

Performance SLOs

Define and measure: API P95 <200ms, probe interval accuracy ±10%, DB write <50ms, UI update <500ms. Useful for catching regressions once there's a test suite to measure against.

Alerting Criteria

Define alert-worthy conditions (mtr missing, DB write failures, disk >90%, trace saturation). Expose via /health detail levels. Integrate with Prometheus Alertmanager or similar.

Dark Mode

CSS variables for colors, detect prefers-color-scheme: dark, optional manual toggle in localStorage.

Keyboard Shortcuts

Ctrl+N (new trace), Space (pause/resume), Ctrl+E (export), arrow keys for hop navigation. Add <kbd> hints in UI.

Full Accessibility (WCAG 2.1 AA)

Screen reader support, focus management, live region announcements. Lighthouse audit.

Code Quality Tooling

black, ruff, mypy (gradual, not strict), pre-commit hooks. Set up when the codebase is large enough to benefit. For Phase 1, just pick a formatter and be consistent.

Branching Strategy

Trunk-based: main always deployable, feature branches, squash merge, conventional commit messages. Formalize when there are multiple contributors.

Design Principles for Future Compatibility

These aren't features to build — they're constraints on current design decisions:

  1. Configuration as constants, not magic numbers. Use named constants (e.g., MAX_CONCURRENT_TRACES = 10) so converting to env vars later is a one-line change per value.

  2. Counters where you'd want metrics. When tracking active traces or probe counts internally, use clean counter variables — not derived from querying the DB each time. Makes adding a /metrics endpoint trivial later.

  3. Logging with context. Use Python's standard logging module but include trace_id in log messages where relevant. Switching to structlog later is a logger-config change, not a code rewrite.

  4. Health endpoint is extensible. Return a dict from /health. Adding new checks (disk space, probe failure rate) means adding keys, not changing the contract.

  5. Error response format is the contract. Every error already uses {error, message, category}. Future features (rate limiting, allowlists) just add new error codes to the same format.