FastAPI Traffic
===============

**Production-grade rate limiting for FastAPI that just works.**

.. image:: https://img.shields.io/badge/python-3.10+-blue.svg
   :target: https://www.python.org/downloads/

.. image:: https://img.shields.io/badge/license-Apache%202.0-green.svg
   :target: https://www.apache.org/licenses/LICENSE-2.0

----

FastAPI Traffic is a rate limiting library designed for real-world FastAPI applications.
It gives you five battle-tested algorithms, three storage backends, and a clean API that
stays out of your way.

Whether you're building a public API that needs to handle thousands of requests per second
or a small internal service that just needs basic protection, this library has you covered.

Quick Example
-------------

Here's how simple it is to add rate limiting to your FastAPI app:

.. code-block:: python

   from fastapi import FastAPI, Request
   from fastapi_traffic import rate_limit

   app = FastAPI()

   @app.get("/api/users")
   @rate_limit(100, 60)  # 100 requests per minute
   async def get_users(request: Request):
       return {"users": ["alice", "bob"]}

That's it. Your endpoint is now rate limited. Clients get helpful headers telling them
how many requests they have left, and when they can try again if they hit the limit.

Why FastAPI Traffic?
--------------------

Most rate limiting libraries fall into one of two camps: either they're too simple
(fixed window only, no persistence) or they're way too complicated (requires reading
a 50-page manual just to get started).

We tried to hit the sweet spot:

- **Five algorithms** — Pick the one that fits your use case. Token bucket for burst
  handling, sliding window for precision, fixed window for simplicity.

- **Three backends** — Memory for development, SQLite for single-node production,
  Redis for distributed systems.

- **Works how you'd expect** — Decorator for endpoints, middleware for global limits,
  dependency injection if that's your style.

- **Fully async** — Built from the ground up for async Python. No blocking calls,
  no thread pool hacks.

- **Type-checked** — Full type hints throughout. Works great with pyright and mypy.

What's in the Box
-----------------

.. grid:: 2
   :gutter: 3

   .. grid-item-card:: 🚦 Rate Limiting
      :link: getting-started/quickstart
      :link-type: doc

      Decorator-based rate limiting with sensible defaults.

   .. grid-item-card:: 🔧 Algorithms
      :link: user-guide/algorithms
      :link-type: doc

      Token bucket, sliding window, fixed window, leaky bucket, and more.

   .. grid-item-card:: 💾 Backends
      :link: user-guide/backends
      :link-type: doc

      Memory, SQLite, and Redis storage options.

   .. grid-item-card:: ⚙️ Configuration
      :link: user-guide/configuration
      :link-type: doc

      Load settings from environment variables or config files.

.. toctree::
   :maxdepth: 2
   :caption: Getting Started
   :hidden:

   getting-started/installation
   getting-started/quickstart

.. toctree::
   :maxdepth: 2
   :caption: User Guide
   :hidden:

   user-guide/algorithms
   user-guide/backends
   user-guide/middleware
   user-guide/configuration
   user-guide/key-extractors
   user-guide/exception-handling

.. toctree::
   :maxdepth: 2
   :caption: Advanced Topics
   :hidden:

   advanced/distributed-systems
   advanced/performance
   advanced/testing

.. toctree::
   :maxdepth: 2
   :caption: API Reference
   :hidden:

   api/decorator
   api/middleware
   api/algorithms
   api/backends
   api/config
   api/exceptions

.. toctree::
   :maxdepth: 1
   :caption: Project
   :hidden:

   changelog
   contributing

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`