# Token Bucket

A token bucket implementation for rate limiting in Nim.

## Overview

This library provides an enhanced token bucket implementation that addresses issues found in the original `chronos/rate_limit.nim` and adds advanced features for better rate limiting control. The token bucket algorithm is commonly used for rate limiting in network applications, APIs, and distributed systems.

## Background

This is an extract from `chronos/rate_limit.nim` due to a bug in the original implementation that cannot be solved without harming the original features of the TokenBucket class. This implementation serves as a shortcut to enable progress with the nwaku rate limiter implementation.

**Reference**: [nim-chronos issue #500](https://github.com/status-im/nim-chronos/issues/500)

## Key Features

This version differs from the original `chronos/rate_limit.nim` in several ways:

- **Compensating Mode**: Calculates compensation as unused bucket capacity from previous periods (up to 25% threshold), with proper time period calculation to avoid overcompensation during non-usage periods
- **Strict Mode**: Replenishes only when the time period is over, filling the bucket to maximum capacity

## Installation

Add this to your `.nimble` file:

```nim
requires "https://github.com/waku-org/token_bucket"
```

Or install directly:

```bash
nimble install https://github.com/waku-org/token_bucket
```