Add velocity-based rate limiting to prevent GitHub secondary rate limits

[rawlingsj]

Summary

This PR reworks the rate limiting implementation to prevent GitHub's secondary rate limits, which are based on request velocity (requests/second) rather than total quota. The implementation is split into commits
for easier review:

Commit 1: Refactor existing rate limiter (no behavior change)

"Add proactive GitHub API rate limiting with shared implementation" (fb6a29d)

• Extract existing SDK rate limiter into shared pkg/httpratelimit package
• Integrate into githubreconciler (new usage)
• Refactor SDK to use shared package (100% backward compatible)
• Removes 170+ lines of duplicate code
• NO BEHAVIOR CHANGES - exact same reactive rate limiting logic

Commit 2: Add velocity-based rate limiting (new functionality)

"Add velocity-based rate limiting to prevent GitHub secondary rate limits" (32a00ad)

• Add DefaultMaxRequestsPerSecond = 15.0 constant
• Add BurstMultiplier = 2 constant
• Update NewTransport() to accept maxRequestsPerSec parameter
• Change from unlimited (rate.Inf) to actual RPS-based rate limiting
• NEW: Prevents secondary rate limit errors instead of just recovering from them

The Problem

Our previous approach (PR #1195) attempted to proactively throttle based on X-RateLimit-Remaining headers. However, testing with a rate limit reproducer revealed that secondary rate limits don't provide these
warning headers:

Status=200, Limit=5000, Remaining=3925, Used=1075, Reset=1762428229, RetryAfter=
Status=403, Limit=, Remaining=, Used=, Reset=, RetryAfter=60  ⬅️ No warning!

Key insight: Secondary limits are triggered by request velocity (req/sec), not total quota. GitHub doesn't provide predictive headers - requests simply fail with 403 + Retry-After when hit.

How It Works

Before:

Unlimited requests → Hit rate limit (403/429) → Pause → Retry

After:

Every request passes through rate limiter (15 RPS default) → Prevents bursts → Never hit secondary limit
                                                           → Still handles 403/429 reactively

Example: With 15 RPS limit and 2x burst, we can handle occasional bursts of 30 requests but maintain an average of 15 req/sec, staying well below GitHub's undocumented secondary limit threshold.

Backward Compatibility

• SDK wrapper updated, maintains compatibility
• All existing callers work without changes (sensible defaults)
• BREAKING CHANGE: Callers of NewTransport must update to use options:

Change NewTransport signature from positional parameters to variadic
options pattern for better flexibility and future extensibility.

Before:
  NewTransport(base, time.Minute)  // Old 2-param version

After:
  NewTransport(base)  // Uses defaults (15 RPS, 1 min retry)
  NewTransport(base, WithDefaultRetryAfter(time.Minute))
  NewTransport(base, WithMaxRequestsPerSecond(20))
  NewTransport(base,
    WithDefaultRetryAfter(time.Minute),
    WithMaxRequestsPerSecond(20))

Benefits:
- Explicit configuration via named options
- Future-proof for adding new options without more breaking changes
- Sensible defaults for common cases

Testing

Validated with rate limit reproducer tool that can trigger secondary limits on demand.

Future Work

• Add Prometheus metrics for rate limiter behavior (tracking, throttling events)