한양과학기술고등학교

토큰은 매 순간 refill 속도로 다시 차오르지만 capacity를 넘지 못한다. 한동안 요청이 없으면 버킷이 가득 차서, 갑자기 몰린 요청(burst)을 용량만큼은 즉시 받아준다. 그 뒤로는 채워지는 속도만큼만 통과한다. → 평소엔 여유, 순간 폭주도 어느 정도 허용.

파란 선(들어온 요청)이 주황 선(refill 속도)보다 높게 유지되면, 초반 버킷을 다 쓴 뒤부터 초과분이 빨간 영역(429)으로 잘려 나간다.

토큰 버킷 vs 리키 버킷: 둘은 사실 동전의 양면이다. 토큰 버킷은 "토큰이 쌓이고 요청이 소모", 리키 버킷은 "요청이 쌓이고 시간이 소모". 토큰 버킷은 버스트 허용, 리키 버킷은 출력 평활화에 방점.

import time

class TokenBucket:
    def __init__(self, capacity, refill_per_sec):
        self.capacity = capacity            # 버킷 최대 토큰 수
        self.rate     = refill_per_sec      # 초당 채워지는 양
        self.tokens   = capacity            # 처음엔 가득
        self.updated  = time.monotonic()

    def allow(self, cost=1):
        now = time.monotonic()
        # 마지막 호출 이후 흐른 시간만큼 토큰을 채운다 (상한 = capacity)
        self.tokens = min(self.capacity,
                          self.tokens + (now - self.updated) * self.rate)
        self.updated = now
        if self.tokens >= cost:
            self.tokens -= cost
            return True          # 200 OK
        return False              # 429 Too Many Requests

# 사용자별 버킷을 dict에 두고 IP/API 키로 조회
buckets = {}
def check(key):
    b = buckets.setdefault(key, TokenBucket(capacity=10, refill_per_sec=3))
    return b.allow()

핵심 트릭: 주기적으로 토큰을 더하는 백그라운드 작업이 필요 없다. 요청이 들어온 순간 "지난번 이후 몇 초 지났으니 그만큼 채운다"라고 계산하면 끝. 상태는 tokens, updated 두 값뿐이라 Redis 같은 곳에 저장해 여러 서버가 공유하기도 쉽다.