Skip to content

cbtor - Next Steps

Last Updated: 2026-01-28 Version: 1.3.0

Open Issues

None currently tracked.

Recently Completed

#2 - Improve OpenAPI documentation to match CB standard - CLOSED

Completed: 2026-01-28

Implemented "Documentation Maxxing" methodology: - Comprehensive API description with health states, timeout/recovery cycles - Tag metadata for fetch and tor endpoint groups - Rich endpoint docstrings with use cases, examples, response interpretation - Pydantic models with field descriptions and examples - Full .onion test endpoints table - Updated docs/index.md with architecture diagrams

#1 - TOR workers stuck in recovery loop - CLOSED

Implemented multi-endpoint TOR checks with auto-reboot recovery: - Exponential backoff: 1s, 2s, 4s, 8s, 16s, 32s then REBOOT - 4 TOR check endpoints with health tracking and failover - Endpoint success/failure rate monitoring via /api/v1/endpoints - 38 unit tests + 21 integration tests

Technical Debt

CI/CD Pipeline

  • No GitHub Actions workflows exist yet
  • Consider adding:
  • Ruff lint/format check on PR
  • pytest on PR
  • Auto-deploy to staging on merge

Test Coverage

  • Current: 63 tests passing
  • Could add: API endpoint integration tests (TestClient)
  • Could add: Load testing for worker pool

Documentation

  • OpenAPI docs need CB standard compliance (Issue #2)
  • Could add: Architecture diagram in README
  • Could add: Deployment runbook

Future Enhancements

Endpoint Health Learning

The system currently tracks which TOR check endpoints work vs fail. Could extend to: - Persist endpoint stats across restarts - Auto-disable consistently failing endpoints - Add more backup endpoints

Metrics & Observability

  • Add Prometheus metrics endpoint
  • Track: request latency, worker health, endpoint success rates
  • Integrate with existing CB monitoring stack

Worker Pool Scaling

  • Dynamic worker addition/removal
  • Auto-scale based on load
  • Geographic distribution of exit nodes

Quick Reference

# Run the API
uvicorn api.main:app --host 0.0.0.0 --port 8000

# Run tests
pytest tests/ -v

# Lint check
ruff check .

# Format code
ruff format .

# View endpoint stats
curl http://localhost:8000/api/v1/endpoints

# View worker health
curl http://localhost:8000/api/v1/health