Audit Phase 3: Routes and Authentication

[nycomp]

Phase 3: Routes and Authentication (JSON only)

Parent: #424

Status

• ✅ All routes implemented
• ✅ Authentication configured
• ✅ Contract tests created (PR Audit: Add contract tests for JSON endpoints #450)

Tasks (Completed)

• Create traces routes: routes/traces.py
  • POST / - Ingest spans (single or batch)
  • GET / - List recent traces with cursor placeholder
  • GET /<trace_id>/ - Full trace tree (JSON)
  • GET /<trace_id>/spans/ - Flat span list
  • GET /<trace_id>/spans/<span_id>/ - Single span detail
  • GET /search - Filter traces by path, status, etc.
• Create health route: routes/health.py
  • GET /health - Health check (no auth required)
• Implement Bearer token authentication
  • bearer_authenticate() hook
  • Validate against Campus auth
  • Skip auth for health endpoint
• Blueprint registration: init.py
• Contract tests for all endpoints (27 tests)

Test Isolation Issues (Follow-up Required)

The contract tests in tests/contract/test_audit_traces.py pass individually but have data persistence issues when run as a suite:

Root Cause: Tests share ServiceManager instance which means storage data persists between test classes.

Symptoms:

• Tests pass when run individually
• Tests fail when run as a suite due to unexpected data from previous test classes

Proposed Solutions:

1. Add reset_test_data() calls - Add a tearDown() method to each test class that calls self.services.reset_test_data() to clear storage between test runs.

2. Use non-shared instances - Create fresh ServiceManager instances per test class using services.create_service_manager(shared=False) instead of sharing the global instance.

3. Data cleanup in fixtures - Ensure each test explicitly cleans up its own test data.

Status: Contract tests cover all endpoints and verify correct behavior. Test isolation is a quality-of-life improvement for the development workflow but does not affect the correctness of the implementation.

Out of Scope (Split to Separate Issue)

• Content negotiation (text/plain responses) - Issue Audit: Add text/plain content negotiation #449
  • Waterfall format for trace trees
  • Compact format for trace lists
  • Accept header handling

Acceptance Criteria

• All endpoints return proper status codes (201, 207, 200, 401, 404, etc.)
• Auth required for all endpoints except /health
• Blueprint registers successfully
• Contract tests for all endpoints cover all behavior

References

• PRD §5: API Surface
• PRD §5.1: Authentication
• Plan §3: Route Structure & Authentication
• PR Audit: Add contract tests for JSON endpoints #450: Contract tests implementation