{"id":28564247,"url":"https://github.com/raceychan/premier","last_synced_at":"2026-03-16T06:37:39.177Z","repository":{"id":230851562,"uuid":"780278376","full_name":"raceychan/premier","owner":"raceychan","description":"A Flexible, Lightweight API-Gateway written in python that can be used as an ASGI middleware, app, or decorators.","archived":false,"fork":false,"pushed_at":"2025-07-12T13:00:36.000Z","size":1521,"stargazers_count":48,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-06T05:36:26.469Z","etag":null,"topics":["api","api-gateway","asgi","lihil","python","retry","throttling","timeout"],"latest_commit_sha":null,"homepage":"https://lihil.cc/premier","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raceychan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-01T06:02:56.000Z","updated_at":"2025-09-01T07:52:20.000Z","dependencies_parsed_at":"2025-07-08T17:24:57.643Z","dependency_job_id":null,"html_url":"https://github.com/raceychan/premier","commit_stats":null,"previous_names":["raceychan/pythrottler","raceychan/premier"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/raceychan/premier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raceychan%2Fpremier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raceychan%2Fpremier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raceychan%2Fpremier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raceychan%2Fpremier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raceychan","download_url":"https://codeload.github.com/raceychan/premier/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raceychan%2Fpremier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30570807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-16T06:02:37.763Z","status":"ssl_error","status_checked_at":"2026-03-16T06:02:14.913Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-gateway","asgi","lihil","python","retry","throttling","timeout"],"created_at":"2025-06-10T13:30:40.995Z","updated_at":"2026-03-16T06:37:39.119Z","avatar_url":"https://github.com/raceychan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Premier\n\n[![PyPI version](https://badge.fury.io/py/premier.svg)](https://badge.fury.io/py/premier)\n[![Python Version](https://img.shields.io/pypi/pyversions/premier.svg)](https://pypi.org/project/premier/)\n[![License](https://img.shields.io/github/license/raceychan/premier)](https://github.com/raceychan/premier/blob/master/LICENSE)\n\n---\n\nPremier is a versatile Python toolkit that can be used in three main ways:\n\n1. **Lightweight Standalone API Gateway** - Run as a dedicated gateway service\n2. **ASGI App/Middleware** - Wrap existing ASGI applications or add as middleware\n3. **Decorator Mode** - Use Premier decorators directly on functions for maximum flexibility\n\nPremier transforms any Python web application into a full-featured API gateway with caching, rate limiting, retry logic, timeouts, and performance monitoring.\n\nPremier comes with a nice dashboard for you to monitor your requests\n\n![image](/docs/images/dashboard.png)\n\n## Documentation\n\n📚 **[Complete Documentation Site](https://raceychan.github.io/premier)** - Full documentation with examples, tutorials, and API reference\n\nQuick links:\n- **[Installation \u0026 Quick Start](https://raceychan.github.io/premier/quickstart/)** - Get started in minutes\n- **[Configuration Guide](https://raceychan.github.io/premier/configuration/)** - Complete YAML configuration reference\n- **[Web Dashboard](https://raceychan.github.io/premier/web-gui/)** - Real-time monitoring and configuration management\n- **[Examples](https://raceychan.github.io/premier/examples/)** - Complete examples and tutorials\n\n## Features\n\nPremier provides enterprise-grade API gateway functionality with:\n\n- **API Gateway Features** - caching, rate limiting, retry logic, and timeout, etc.\n- **Path-Based Policies** - Different features per route with regex matching\n- **Load Balancing \u0026 Circuit Breaker** - Round robin load balancing with fault tolerance\n- **WebSocket Support** - Full WebSocket proxying with rate limiting and monitoring\n- **Web Dashboard** - Built-in web GUI for monitoring and configuration management\n- **YAML Configuration** - Declarative configuration with namespace support\n\n... and more\n\n## Why Premier\n\nPremier is designed for **simplicity and accessibility** - perfect for simple applications that need API gateway functionality without introducing complex tech stacks like Kong, Ambassador, or Istio.\n\n**Key advantages:**\n\n- **Zero Code Changes** - Wrap existing ASGI apps without modifications\n- **Simple Setup** - Single dependency, no external services required\n- **Dual Mode Operation** - Plugin for existing apps OR standalone gateway\n- **Python Native** - Built for Python developers, integrates seamlessly\n- **Lightweight** - Minimal overhead, maximum performance\n- **Hot Reloadable** - Update configurations without restarts\n\n## Quick Start\n\n### Plugin Mode (Recommended)\n\n**How it works:** Each app instance has its own Premier gateway wrapper\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ App Instance 1                                              │\n│ ┌─────────────────┐    ┌─────────────────────────────────┐  │\n│ │   Premier       │────│       Your ASGI App             │  │\n│ │   Gateway       │    │     (FastAPI/Django/etc)        │  │\n│ │  ┌──────────┐   │    │                                 │  │\n│ │  │Cache     │   │    │  @app.get(\"/api/users\")         │  │\n│ │  │RateLimit │   │    │  async def get_users():         │  │\n│ │  │Retry     │   │    │      return users               │  │\n│ │  │Timeout   │   │    │                                 │  │\n│ │  └──────────┘   │    │                                 │  │\n│ └─────────────────┘    └─────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────┘\n```\n\nYou can keep your existing app.py file untouched\n\n```python\n# app.py\nfrom premier.asgi import ASGIGateway, GatewayConfig\nfrom fastapi import FastAPI\n\n# Your existing app - no changes needed\napp = FastAPI()\n\n@app.get(\"/api/users/{user_id}\")\nasync def get_user(user_id: int):\n    return await fetch_user_from_database(user_id)\n```\n\nNext, import your app instance and wrap it with ASGIGateway:\n\n```python\n# gateway.py\nfrom .app import app\n# Load configuration and wrap app\nconfig = GatewayConfig.from_file(\"gateway.yaml\")\napp = ASGIGateway(config=config, app=app)\n```\n\nThen, instead of serving the original app directly, serve the one wrapped with ASGIGateway.\n\n### Standalone Mode\n\n**How it works:** Single gateway handles all requests and forwards to backend services\n\n```\n                        ┌─────────────────────┐\n    Client Request      │   Premier Gateway   │\n         │              │  ┌──────────────┐   │\n         │              │  │ Cache        │   │\n         └──────────────►  │ RateLimit    │   │\n                        │  │ Retry        │   │\n                        │  │ Timeout      │   │\n                        │  │ Monitoring   │   │\n                        │  └──────────────┘   │\n                        └─────┬──────┬────────┘\n                              │      │\n                    ┌─────────┘      └─────────┐\n                    ▼                          ▼\n            ┌───────────────┐          ┌───────────────┐\n            │   Backend 1   │          │   Backend 2   │\n            │ (Any Service) │          │ (Any Service) │\n            │               │          │               │\n            │ Node.js API   │          │  Python API   │\n            │ Java Service  │          │  .NET Service │\n            │ Static Files  │          │  Database     │\n            └───────────────┘          └───────────────┘\n```\n\n```python\n# main.py\nfrom premier.asgi import ASGIGateway, GatewayConfig\n\nconfig = GatewayConfig.from_file(\"gateway.yaml\")\ngateway = ASGIGateway(config, servers=[\"http://backend:8000\"])\n```\n\n```bash\nuvicorn src:main\n```\n\n### Decorator Mode\n\n**How it works:** Apply Premier features directly to individual functions with decorators - no ASGI app required\n\n### WebSocket Support\n\nPremier supports WebSocket connections with the same feature set:\n\n```python\n# WebSocket connections are automatically handled\n# Configure WebSocket-specific policies in YAML:\n\npremier:\n  paths:\n    - pattern: \"/ws/chat/*\"\n      features:\n        rate_limit:\n          quota: 100  # Max 100 connections per minute\n          duration: 60\n        monitoring:\n          log_threshold: 5.0  # Log connections lasting \u003e5s\n```\n\n### YAML Configuration\n\nConfigure gateway policies declaratively:\n\n```yaml\npremier:\n  keyspace: \"my-api\"\n\n  paths:\n    - pattern: \"/api/users/*\"\n      features:\n        cache:\n          expire_s: 300\n        rate_limit:\n          quota: 100\n          duration: 60\n          algorithm: \"sliding_window\"\n        timeout:\n          seconds: 5.0\n        retry:\n          max_attempts: 3\n          wait: 1.0\n        monitoring:\n          log_threshold: 0.1\n\n    - pattern: \"/api/admin/*\"\n      features:\n        rate_limit:\n          quota: 10\n          duration: 60\n          algorithm: \"token_bucket\"\n        timeout:\n          seconds: 30.0\n\n    - pattern: \"/ws/*\"\n      features:\n        rate_limit:\n          quota: 50\n          duration: 60\n          algorithm: \"sliding_window\"\n        monitoring:\n          log_threshold: 1.0\n\n  default_features:\n    timeout:\n      seconds: 10.0\n    monitoring:\n      log_threshold: 0.5\n```\n\n## Configuration Reference\n\nPremier supports extensive configuration options for path-based policies. Here's a complete reference of all available configuration fields:\n\n### Top-Level Configuration\n\n| Field | Type | Description | Default |\n|-------|------|-------------|---------|\n| `keyspace` | string | Namespace for cache keys and throttling | `\"asgi-gateway\"` |\n| `paths` | array | Path-specific configuration rules | `[]` |\n| `default_features` | object | Default features applied to all paths | `null` |\n| `servers` | array | Backend server URLs for standalone mode | `null` |\n\n### Path Configuration\n\n| Field | Type | Description | Example |\n|-------|------|-------------|---------|\n| `pattern` | string | Path pattern (regex or glob-style) | `\"/api/users/*\"`, `\"^/admin/.*$\"` |\n| `features` | object | Features to apply to this path | See feature configuration below |\n\n### Feature Configuration\n\n#### Cache Configuration\n\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|---------|\n| `expire_s` | integer | Cache expiration in seconds | `null` (no expiration) | `300` |\n| `cache_key` | string/function | Custom cache key | Auto-generated | `\"user:{user_id}\"` |\n\n#### Rate Limiting Configuration\n\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|---------|\n| `quota` | integer | Number of requests allowed | Required | `100` |\n| `duration` | integer | Time window in seconds | Required | `60` |\n| `algorithm` | string | Rate limiting algorithm | `\"fixed_window\"` | `\"sliding_window\"`, `\"token_bucket\"`, `\"leaky_bucket\"` |\n| `bucket_size` | integer | Bucket size (for leaky_bucket) | Same as quota | `50` |\n| `error_status` | integer | HTTP status code for rate limit errors | `429` | `503` |\n| `error_message` | string | Error message for rate limit errors | `\"Rate limit exceeded\"` | `\"Too many requests\"` |\n\n#### Timeout Configuration\n\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|---------|\n| `seconds` | float | Timeout duration in seconds | Required | `5.0` |\n| `error_status` | integer | HTTP status code for timeout errors | `504` | `408` |\n| `error_message` | string | Error message for timeout errors | `\"Request timeout\"` | `\"Request took too long\"` |\n\n#### Retry Configuration\n\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|---------|\n| `max_attempts` | integer | Maximum retry attempts | `3` | `5` |\n| `wait` | float/array/function | Wait time between retries | `1.0` | `[1, 2, 4]` |\n| `exceptions` | array | Exception types to retry on | `[Exception]` | Custom exceptions |\n\n#### Circuit Breaker Configuration\n\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|---------|\n| `failure_threshold` | integer | Failures before opening circuit | `5` | `10` |\n| `recovery_timeout` | float | Seconds before attempting recovery | `60.0` | `120.0` |\n| `expected_exception` | string | Exception type that triggers circuit | `\"Exception\"` | `\"ConnectionError\"` |\n\n#### Monitoring Configuration\n\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|---------|\n| `log_threshold` | float | Log requests taking longer than this (seconds) | `0.1` | `1.0` |\n\n### Complete Configuration Example\n\n```yaml\npremier:\n  keyspace: \"production-api\"\n  servers: [\"http://backend1:8000\", \"http://backend2:8000\"]\n  \n  paths:\n    - pattern: \"/api/users/*\"\n      features:\n        cache:\n          expire_s: 300\n        rate_limit:\n          quota: 1000\n          duration: 60\n          algorithm: \"sliding_window\"\n          error_status: 429\n          error_message: \"Rate limit exceeded for user API\"\n        timeout:\n          seconds: 5.0\n          error_status: 504\n          error_message: \"User API timeout\"\n        retry:\n          max_attempts: 3\n          wait: [1, 2, 4]  # Exponential backoff\n        circuit_breaker:\n          failure_threshold: 5\n          recovery_timeout: 60.0\n        monitoring:\n          log_threshold: 0.1\n          \n    - pattern: \"/api/admin/*\"\n      features:\n        rate_limit:\n          quota: 10\n          duration: 60\n          algorithm: \"token_bucket\"\n          error_status: 403\n          error_message: \"Admin API rate limit exceeded\"\n        timeout:\n          seconds: 30.0\n          error_status: 408\n          error_message: \"Admin operation timeout\"\n        monitoring:\n          log_threshold: 0.5\n          \n  default_features:\n    timeout:\n      seconds: 10.0\n    rate_limit:\n      quota: 100\n      duration: 60\n      algorithm: \"fixed_window\"\n    monitoring:\n      log_threshold: 1.0\n```\n\n### Algorithm Options\n\n- **`fixed_window`**: Simple time-based windows\n- **`sliding_window`**: Smooth rate limiting over time\n- **`token_bucket`**: Burst capacity with steady refill rate\n- **`leaky_bucket`**: Queue-based rate limiting with controlled draining\n\n## Installation\n\n```bash\npip install premier\n```\n\nFor Redis support (optional):\n\n```bash\npip install premier[redis]\n```\n\n## Function Resilience Decorators\n\nPremier includes powerful decorators for adding resilience to individual functions:\n\n### Retry Decorator\n\n```python\nfrom premier.retry import retry\n\n@retry(max_attempts=3, wait=1.0, exceptions=(ConnectionError, TimeoutError))\nasync def api_call():\n    # Your function with retry logic\n    return await make_request()\n```\n\n### Timer Decorator\n\n```python\nfrom premier.timer import timeit, timeout\n\n@timeit(log_threshold=0.1)  # Log calls taking \u003e0.1s\nasync def slow_operation():\n    return await heavy_computation()\n\n@timeout(seconds=5)  # Timeout after 5 seconds\nasync def time_limited_task():\n    return await long_running_operation()\n```\n\n## Framework Integration\n\nWorks with any ASGI framework:\n\n```python\n# FastAPI\nfrom fastapi import FastAPI\napp = FastAPI()\n\n# Starlette\nfrom starlette.applications import Starlette\napp = Starlette()\n\n# Django ASGI\nfrom django.core.asgi import get_asgi_application\napp = get_asgi_application()\n\n# Wrap with Premier\nconfig = GatewayConfig.from_file(\"config.yaml\")\ngateway = ASGIGateway(config, app=app)\n```\n\n## Production Deployment\n\n```python\n# production.py\nfrom premier.asgi import ASGIGateway, GatewayConfig\nfrom premier.providers.redis import AsyncRedisCache\nfrom redis.asyncio import Redis\n\n# Redis backend for distributed caching\nredis_client = Redis.from_url(\"redis://localhost:6379\")\ncache_provider = AsyncRedisCache(redis_client)\n\n# Load configuration\nconfig = GatewayConfig.from_file(\"production.yaml\")\n\n# Create production gateway\ngateway = ASGIGateway(config, app=your_app, cache_provider=cache_provider)\n\n# Deploy with uvicorn\nif __name__ == \"__main__\":\n    import uvicorn\n    uvicorn.run(gateway, host=\"0.0.0.0\", port=8000, workers=4)\n```\n\n## Requirements\n\n- Python \u003e= 3.10\n- Redis \u003e= 5.0.3 (optional, for distributed deployments)\n- PyYAML (for YAML configuration)\n- aiohttp (optional, for standalone mode)\n\n## What's Next\n\n- [x] Web GUI\n- [x] Websocket Support\n- [x] Load Balancer\n- [x] Circuit Breaker\n- [ ] Auth(OAuth, jwt, etc.)\n- [ ] Authorization, Access control(RBAC, ABAC, Whitelist, etc.)\n- [ ] MCP integration\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraceychan%2Fpremier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraceychan%2Fpremier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraceychan%2Fpremier/lists"}