Algorithms

Halt supports multiple rate limiting algorithms to suit different use cases.

Token Bucket

Best for allowing bursts of traffic while maintaining a steady rate. Tokens are refilled at a constant rate.

import { Algorithm } from 'halt-rate';

const policy = {
  name: 'api_limit',
  limit: 100,        // capacity
  window: 60,        // refill period
  burst: 120,        // max burst size
  algorithm: Algorithm.TOKEN_BUCKET
};
Header note: the RateLimit-Limit header reports the configured limit (here 100), not the burst capacity. Python and TypeScript behave identically.

Fixed Window

Simple and memory efficient. Counts requests in fixed time windows (e.g., 10:00-10:01). Can have boundary issues.

import { Algorithm } from 'halt-rate';

const policy = {
  name: 'basic_limit',
  limit: 1000,
  window: 3600,      // 1 hour
  algorithm: Algorithm.FIXED_WINDOW
};

Sliding Window

Most accurate. Smooths out traffic spikes by considering the weighted average of the previous and current window.

import { Algorithm } from 'halt-rate';

const policy = {
  name: 'strict_limit',
  limit: 50,
  window: 60,
  algorithm: Algorithm.SLIDING_WINDOW,
  slidingPrecision: 20,   // optional, default 10 (see note below)
};
Precision knob (v0.5.0+): tune the rolling window's granularity with slidingPrecision / sliding_precision (default 10). Higher = more accurate + more memory; lower = coarser + cheaper. Affects the in-process path only — see Policies.

Atomic on Redis

With the Redis store, every algorithm runs as a single-key Lua script executed inside Redis, so a burst of concurrent requests can never over-admit past the limit verified at 200 concurrent requests against a limit=50 policy admitting exactly 50. Scripts read time from the Redis server, so clock skew across your fleet doesn't affect accuracy.

  • • Token-bucket, fixed-window, and leaky-bucket use a Redis HASH per key.
  • • Sliding-window uses a Redis sorted set as a true request log.
  • • Each script touches exactly one key, so Redis Cluster works out of the box.