Skip to content

feat(workspace): rate limit status API #729

@FelixTJDietrich

Description

@FelixTJDietrich

Problem

Rate limit status is tracked internally (ScopedRateLimitTracker) but not exposed to admins. When sync slows down due to rate limits, admins have no visibility into the cause.

Proposed Solution

Expose rate limit status via API endpoint so admins can see current limits, reset times, and health thresholds.

Scope

In scope:

  1. Current rate limit remaining and total
  2. Reset timestamp
  3. Health state (healthy/low/critical)
  4. Circuit breaker state (if applicable)

Out of scope:

  • Historical rate limit usage
  • Per-endpoint breakdown
  • Rate limit alerts/notifications

Technical Notes

Data source: ScopedRateLimitTracker already tracks:

  • Remaining points
  • Total limit
  • Reset time
  • Health thresholds (500=low, 100=critical)

Proposed endpoint:

GET /api/workspaces/{slug}/sync/rate-limit
Response: {
  "provider": "GITHUB" | "GITLAB",
  "remaining": 4500,
  "limit": 5000,
  "resetAt": "2025-02-04T11:00:00Z",
  "health": "HEALTHY" | "LOW" | "CRITICAL",
  "circuitBreakerOpen": false
}

Health thresholds (from existing code):

  • HEALTHY: remaining > 500
  • LOW: 100 < remaining <= 500
  • CRITICAL: remaining <= 100

GitLab differences:

  • REST API: 2000 requests/minute (header: RateLimit-Remaining)
  • GraphQL: 100 points/minute (different accounting)
  • May need separate tracking for REST vs GraphQL

Files to modify:

  • workspace/sync/SyncStatusController.java — Add rate limit endpoint
  • Create workspace/sync/dto/RateLimitStatusDTO.java

Acceptance Criteria

  • Endpoint returns current rate limit remaining and total
  • Reset timestamp included in response
  • Health state derived using existing thresholds
  • Circuit breaker state exposed
  • Works for both GitHub and GitLab workspaces
  • Admin-only authorization
  • Response uses existing ScopedRateLimitTracker (no new tracking)
  • Unit test for health state derivation

Metadata

Metadata

Assignees

No one assigned

    Labels

    application-serverSpring Boot server: APIs, business logic, databasefeatureNew feature or enhancementpriority:lowNice to have - Minimal impact

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions