API Rate Limiting skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "API Rate Limiting"
  short_description: "Fair limits that hold under concurrency"
  default_prompt: "$api-rate-limiting Add per-tenant rate limiting to our API using Redis"

# Atomic Redis limiters (Lua)

Read this when the project has no rate-limit library that fits, or when an existing
limiter shows race conditions (read-then-write from application code). Each script uses
one key so it works in Redis Cluster, reads the clock with `TIME` on the server (no
client clock skew), and returns strings for fractional values because Redis truncates
Lua numbers to integers on the way out.

Load once with `SCRIPT LOAD` and call with `EVALSHA`, or let your client library do it
(`ioredis` `defineCommand`, redis-py `register_script`, go-redis `NewScript`).

## Token bucket

Smooth refill, allows bursts up to `capacity`, supports weighted `cost`.

```lua
-- KEYS[1] = bucket key, e.g. "rl:tb:{tenant_42}:search"
-- ARGV[1] = capacity (max tokens), ARGV[2] = refill rate (tokens/second), ARGV[3] = cost
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local cost = tonumber(ARGV[3])

local t = redis.call('TIME')
local now = tonumber(t[1]) + tonumber(t[2]) / 1000000

local state = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
local tokens = tonumber(state[1]) or capacity
local ts = tonumber(state[2]) or now

tokens = math.min(capacity, tokens + math.max(0, now - ts) * rate)

local allowed = 0
local retry_after = 0
if tokens >= cost then
  tokens = tokens - cost
  allowed = 1
else
  retry_after = (cost - tokens) / rate
end

redis.call('HSET', KEYS[1], 'tokens', tokens, 'ts', now)
redis.call('PEXPIRE', KEYS[1], math.ceil(capacity / rate * 1000) + 1000)

return { allowed, tostring(math.floor(tokens)), tostring(retry_after) }
```

Returns `{allowed (0|1), remaining, retry_after_seconds}`. Round `retry_after` up to a
whole second for the `Retry-After` header.

## GCRA (generic cell rate algorithm)

Same behavior as a token bucket but stores a single timestamp (the theoretical arrival
time), so it is cheaper and has no refill drift. `limit` requests per `period` seconds,
with up to `burst` requests allowed back to back.

```lua
-- KEYS[1] = key
-- ARGV[1] = limit, ARGV[2] = period (seconds), ARGV[3] = burst, ARGV[4] = cost
local limit = tonumber(ARGV[1])
local period = tonumber(ARGV[2])
local burst = tonumber(ARGV[3])
local cost = tonumber(ARGV[4])

local interval = period / limit           -- seconds per request at steady rate
local burst_window = interval * burst

local t = redis.call('TIME')
local now = tonumber(t[1]) + tonumber(t[2]) / 1000000

local tat = tonumber(redis.call('GET', KEYS[1])) or now
if tat < now then tat = now end

local new_tat = tat + interval * cost
local allow_at = new_tat - burst_window

if now < allow_at then
  return { 0, '0', tostring(allow_at - now) }
end

redis.call('SET', KEYS[1], tostring(new_tat), 'PX', math.ceil((new_tat - now) * 1000) + 1000)
local remaining = math.floor((now - allow_at) / interval)
return { 1, tostring(remaining), '0' }
```

Sanity check: with `burst = 5`, five calls at the same instant are allowed, the sixth
is denied with `retry_after = interval`.

## Sliding window counter

Approximates a true sliding window with two counters; error is small and memory is
constant. Good for "1000 requests per hour" quotas.

```lua
-- KEYS[1] = key; ARGV[1] = limit, ARGV[2] = window (seconds), ARGV[3] = cost
local limit = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local cost = tonumber(ARGV[3])

local t = redis.call('TIME')
local now = tonumber(t[1]) + tonumber(t[2]) / 1000000
local cur_start = math.floor(now / window) * window

local s = redis.call('HMGET', KEYS[1], 'w', 'c', 'p')
local w = tonumber(s[1])
local cur = tonumber(s[2]) or 0
local prev = tonumber(s[3]) or 0

if w == nil or w < cur_start - window then
  prev, cur = 0, 0
elseif w < cur_start then
  prev, cur = cur, 0
end

local weight = 1 - (now - cur_start) / window
local estimate = prev * weight + cur

if estimate + cost > limit then
  local retry = window - (now - cur_start)
  if prev > 0 then
    -- time until the previous window's weighted share drops enough
    local need = estimate + cost - limit
    retry = math.min(retry, need / prev * window)
  end
  redis.call('HSET', KEYS[1], 'w', cur_start, 'c', cur, 'p', prev)
  redis.call('EXPIRE', KEYS[1], window * 2)
  return { 0, '0', tostring(retry) }
end

cur = cur + cost
redis.call('HSET', KEYS[1], 'w', cur_start, 'c', cur, 'p', prev)
redis.call('EXPIRE', KEYS[1], window * 2)
return { 1, tostring(math.floor(limit - estimate - cost)), '0' }
```

## Concurrency limiter (in-flight requests)

For expensive endpoints (exports, report generation), limit simultaneous requests
instead of rate. Use a sorted set of request IDs scored by start time; remove entries
older than the maximum request duration so crashed workers do not leak slots.

```lua
-- KEYS[1] = key; ARGV[1] = max concurrent, ARGV[2] = request id, ARGV[3] = max duration (s)
local t = redis.call('TIME')
local now = tonumber(t[1]) + tonumber(t[2]) / 1000000
redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - tonumber(ARGV[3]))
if redis.call('ZCARD', KEYS[1]) >= tonumber(ARGV[1]) then
  return 0
end
redis.call('ZADD', KEYS[1], now, ARGV[2])
redis.call('EXPIRE', KEYS[1], tonumber(ARGV[3]) * 2)
return 1
```

Release with `ZREM key request_id` in a `finally` block.

## Calling from Node (ioredis)

```ts
import Redis from 'ioredis';
import { readFileSync } from 'node:fs';

const redis = new Redis(process.env.REDIS_URL!);
redis.defineCommand('tokenBucket', { numberOfKeys: 1, lua: readFileSync('token_bucket.lua', 'utf8') });

const [allowed, remaining, retryAfter] = await (redis as any).tokenBucket(
  `rl:tb:{${tenantId}}:api`, 100, 10, 1,
);
```

## Testing the scripts

- Unit-test the Lua logic without Redis by stubbing `redis.call` in a plain Lua
  interpreter and advancing a fake clock, or run against a disposable Redis
  (testcontainers) in integration tests.
- Assert: burst size is exact, the request after the burst is denied with the expected
  `retry_after`, and tokens refill after waiting.