rateLimitHook static method

HookRegistration rateLimitHook({ required int maxCallsPerMinute, })

Hook that enforces rate limits on API calls.

Tracks call counts per time window and returns HookRetry when the limit is exceeded.

Implementation

static HookRegistration rateLimitHook({required int maxCallsPerMinute}) {
  final callTimestamps = <DateTime>[];

  return HookRegistration(
    id: 'builtin:rate-limit',
    type: HookType.preApiCall,
    priority: HookPriority.high,
    name: 'Rate Limit',
    description: 'Enforces rate limits on API calls.',
    source: 'builtin',
    tags: {'safety', 'rate-limit'},
    handler: (context) {
      final now = DateTime.now();
      final windowStart = now.subtract(const Duration(minutes: 1));

      // Clean old entries
      callTimestamps.removeWhere((t) => t.isBefore(windowStart));

      if (callTimestamps.length >= maxCallsPerMinute) {
        final oldestInWindow = callTimestamps.first;
        final waitTime = oldestInWindow
            .add(const Duration(minutes: 1))
            .difference(now);
        return HookRetry(
          waitTime.isNegative ? const Duration(seconds: 1) : waitTime,
        );
      }

      callTimestamps.add(now);
      return const HookContinue();
    },
  );
}