Metadata-Version: 2.4
Name: limifyrate
Version: 0.1.3
Summary: Framework-agnostic, Redis-backed rate limiting engine for modern async Python systems.
Author: Pedram Aliniaye Asli
License: MIT
Project-URL: Homepage, https://github.com/pedram-aliniaye-asli/limify
Project-URL: Repository, https://github.com/pedram-aliniaye-asli/limify
Project-URL: Documentation, https://github.com/pedram-aliniaye-asli/limify
Keywords: rate limiting,redis,async,token bucket,fastapi,starlette,api,microservices,middleware
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis>=7.0.0
Provides-Extra: fastapi
Requires-Dist: starlette>=0.27; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# Limify

Framework-agnostic, Redis-backed rate limiting engine for modern Python systems.

Limify provides a clean-architecture rate limiting core with pluggable storage adapters, async and sync support, atomic Redis Lua execution, and framework adapters.

Limify is designed as infrastructure-level software for backend engineers, microservices, and API platforms.

---

## Features

* Framework-agnostic core
* Async and sync Redis support
* Atomic Redis Lua token bucket implementation
* FastAPI / Starlette middleware adapter
* Rule-based rate limiting with wildcard matching
* Plan-based rate limiting support
* Multi-identity support:

  * user_id
  * org_id
  * api_key
  * client_ip
* Clean architecture with dependency injection
* Pluggable storage and algorithms
* Fully testable design

---

## Architecture

Limify uses layered clean architecture:

```
Application (FastAPI / Flask / etc.)
        ↓
Adapter (Middleware)
        ↓
Limiter (Orchestrator)
        ↓
Resolvers
  ├─ RuleResolver
  ├─ PlanResolver
  └─ KeyResolver
        ↓
Algorithm (Token Bucket)
        ↓
Storage Adapter (Redis)
```

Core is fully independent of frameworks.

---

## Installation

### Core only

```
pip install limifyrate
```

### With FastAPI / Starlette adapter

```
pip install "limifyrate[fastapi]"
```

### Development install

```
git clone https://github.com/pedram-aliniaye-asli/limify.git
cd limify
pip install -e ".[dev]"
```

---

## Requirements

* Python 3.10+
* Redis

---

## Quick Start (Async)

Example using async Redis and FastAPI.

```python
import redis.asyncio as redis

from fastapi import FastAPI
from limify import Limify, LimifyConfig
from limify.adapters.fastapi.middleware import LimifyMiddleware
from limify.core.redis_adapter import RedisAsyncAdapter
from limify.core.algorithms.token_bucket import AsyncTokenBucketAlgorithm


redis_client = redis.from_url("redis://localhost:6379")

adapter = RedisAsyncAdapter(redis_client)

algorithm = AsyncTokenBucketAlgorithm(adapter)
await algorithm.initialize()

config = LimifyConfig(
    rules=[
        {
            "id": "default",
            "method": "*",
            "path": "/**", # This rule will include all requests with different methods on all endpoints and it's not suggested really! Just for demonstration purposes!
            "rate": "5/minute",
            "priority": 0,
        },
        {
            "id": "items",
            "method": "*",
            "path": "/items",
            "rate": "10/minute",
            "priority": 10,
        },
    ]
)

limify = Limify(
    algorithm=algorithm,
    config=config,
)

app = FastAPI()

app.add_middleware(
    LimifyMiddleware,
    limiter=limify.limiter,
)


@app.get("/items")
async def items():
    return {"status": "ok"}
```

---

## Sync Example

Example using synchronous Redis.

```python
import redis

from limify import Limify, LimifyConfig
from limify.core.redis_adapter import RedisSyncAdapter
from limify.core.algorithms.token_bucket import TokenBucketAlgorithm


redis_client = redis.Redis(host="localhost", port=6379)

adapter = RedisSyncAdapter(redis_client)

algorithm = TokenBucketAlgorithm(adapter)

config = LimifyConfig(
    rules=[
        {
            "id": "default",
            "method": "*",
            "path": "/**",
            "rate": "5/minute",
        }
    ]
)

limify = Limify(
    algorithm=algorithm,
    config=config,
)
```

---

## Redis Key Structure

Limify generates deterministic keys:

```
limify:{rule_id}:{plan_id}:{identity_type}:{identity_value}
```

Examples:

```
limify:items:default:user:42
limify:default:default:ip:127.0.0.1
limify:items:pro:apikey:abc123
```

Each identity and rule has an independent token bucket.

---

## Rules

Rules define rate limits per endpoint.

Example:

```python
{
    "id": "items",
    "method": "*",
    "path": "/items",
    "rate": "10/minute",
    "priority": 10,
}
```

Supported wildcards:

```
/items/*
/api/**
```

Higher priority rules override lower priority ones.

---

## Identity Resolution Priority

Default resolution order:

1. user_id
2. org_id
3. api_key
4. client_ip
5. anonymous

---

## Plan Support

Limify supports plan-based rate limiting using PlanProvider.

This enables multi-tier SaaS limits.

Example plans:

```
free → 10/minute
pro → 100/minute
enterprise → 1000/minute
```

---

## Algorithms

Currently implemented:

* Token Bucket (async)
* Token Bucket (sync)

Future:

* Sliding Window
* Fixed Window

---

## Storage Adapters

Currently implemented:

* RedisAsyncAdapter
* RedisSyncAdapter

Future:

* In-memory adapter
* PostgreSQL adapter

---

## FastAPI Adapter

Limify provides Starlette-compatible middleware.

```
limify.adapters.fastapi.middleware.LimifyMiddleware
```

Adds headers:

```
X-RateLimit-Limit
X-RateLimit-Remaining
Retry-After
```

---

## Project Structure

```
limify/
  adapters/
    fastapi/
  core/
    algorithms/
    resolvers/
    redis_adapter.py
    limiter.py
    ...
  config.py
  defaults.py
  plan_provider.py
  ...
```

---

## Status

Alpha

Core architecture is stable and production-grade, but API surface may evolve.

---

## Roadmap

* In-memory storage adapter
* Flask adapter
* Django adapter
* Sliding window algorithm
* Fixed window algorithm
* Metrics support

---

## License

MIT License

---

## Author

Pedram Aliniaye Asli

---

Limify is designed as reusable infrastructure for modern backend systems.
