WAGERBABE DOCS
All Stories
2-2-6-backpressure-load-sheddingDoneEpic 2.2

Story 2.2.6: Backpressure & Load Shedding

Status: done

Tasks

  • Task 1: Implement BackpressureController class (AC: #1, #2, #4)
    • 1.1: Create `server/app/middleware/backpressure.py` with BackpressureController class
    • 1.2: Define Priority enum (IntEnum) with AGENT=1, ACTIVE_BETTOR=2, BROWSER=3
    • 1.3: Initialize 3 separate asyncio.Queue instances with maxsize=1000
    • 1.4: Implement `try_acquire(request: Request) -> Optional[Response]` method
    • 1.5: Implement `_determine_priority(request: Request) -> Priority` helper
    • 1.6: Add max_concurrent=500 processing limit tracking
    • 1.7: Write 41 unit tests (priority determination, queue overflow, concurrent limit)
  • Task 2: Implement 429 response with Retry-After header (AC: #3)
    • 2.1: Check `queue.full()` before enqueueing
    • 2.2: Return FastAPI Response with status_code=429
    • 2.3: Add `Retry-After: 30` header to response
    • 2.4: Include JSON body: `{"error": "Server busy", "retry_after": 30, "priority": "..."}`
    • 2.5: Write unit tests (429 response format, header presence, body content)
  • Task 3: JWT claims inspection for priority (AC: #4)
    • 3.1: Access `request.state.user` (assumes auth middleware populated it)
    • 3.2: Check `user.role` attribute for "agent" role
    • 3.3: Check `user.recent_bet_count` attribute (>0 = active bettor)
    • 3.4: Handle unauthenticated requests (no user object → BROWSER priority)
    • 3.5: Write unit tests (agent priority, bettor priority, browser priority, unauthenticated, missing attributes)
  • Task 4: Metrics tracking and health endpoint (AC: #5)
    • 4.1: Track `queue_depth` for each priority level (real-time)
    • 4.2: Increment `requests_shed` counter on queue overflow (with priority tag)
    • 4.3: Track request enqueue timestamp and calculate avg_wait_time on dequeue
    • 4.4: Create `/health/backpressure` endpoint returning metrics JSON
    • 4.5: Integrate with existing `/health` endpoint (add backpressure section)
    • 4.6: Write unit tests (metrics tracking, health endpoint format, shed count, wait time calculation)
  • Task 5: Integration with FastAPI middleware (AC: #1, #2, #3, #4, #5)
    • 5.1: Register BackpressureMiddleware in `server/app/middleware/backpressure.py`
    • 5.2: Middleware excludes health, metrics, docs paths by default
    • 5.3: Middleware reads request.state.user for priority determination
    • 5.4: Test middleware initialization and exclude paths
    • 5.5: Write E2E tests (32 passing, 2 skipped for server integration)
  • Task 6: Load testing and tuning (AC: #1, #2, #3, #5)
    • 6.1: Simulate 10,000 concurrent requests with mixed priorities
    • 6.2: Validate agent requests are never shed (highest priority)
    • 6.3: Validate browser requests shed first under load (lowest priority)
    • 6.4: Measure avg_wait_time under load (target <1s for agents, <5s for bettors)
    • 6.5: Tune max_concurrent and queue_size parameters based on results
    • 6.6: Document findings in Dev Notes

Progress

Tasks5/6
Acceptance Criteria0
Total Tasks6

Navigation

View Epic 2.2All Stories