Premier

---

Premier is a versatile Python toolkit that can be used in three main ways:

1. Lightweight Standalone API Gateway - Run as a dedicated gateway service
2. ASGI App/Middleware - Wrap existing ASGI applications or add as middleware
3. Decorator Mode - Use Premier decorators directly on functions for maximum flexibility

Premier transforms any Python web application into a full-featured API gateway with caching, rate limiting, retry logic, timeouts, and performance monitoring.

Premier comes with a nice dashboard for you to monitor your requests

Documentation

📚 Complete Documentation Site - Full documentation with examples, tutorials, and API reference

Quick links:

• Installation & Quick Start - Get started in minutes
• Configuration Guide - Complete YAML configuration reference
• Web Dashboard - Real-time monitoring and configuration management
• Examples - Complete examples and tutorials

Features

Premier provides enterprise-grade API gateway functionality with:

• API Gateway Features - caching, rate limiting, retry logic, and timeout, etc.
• Path-Based Policies - Different features per route with regex matching
• Load Balancing & Circuit Breaker - Round robin load balancing with fault tolerance
• WebSocket Support - Full WebSocket proxying with rate limiting and monitoring
• Web Dashboard - Built-in web GUI for monitoring and configuration management
• YAML Configuration - Declarative configuration with namespace support

... and more

Why Premier

Premier 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.

Key advantages:

• Zero Code Changes - Wrap existing ASGI apps without modifications
• Simple Setup - Single dependency, no external services required
• Dual Mode Operation - Plugin for existing apps OR standalone gateway
• Python Native - Built for Python developers, integrates seamlessly
• Lightweight - Minimal overhead, maximum performance
• Hot Reloadable - Update configurations without restarts

Quick Start

Plugin Mode (Recommended)

How it works: Each app instance has its own Premier gateway wrapper

┌─────────────────────────────────────────────────────────────┐
│ App Instance 1                                              │
│ ┌─────────────────┐    ┌─────────────────────────────────┐  │
│ │   Premier       │────│       Your ASGI App             │  │
│ │   Gateway       │    │     (FastAPI/Django/etc)        │  │
│ │  ┌──────────┐   │    │                                 │  │
│ │  │Cache     │   │    │  @app.get("/api/users")         │  │
│ │  │RateLimit │   │    │  async def get_users():         │  │
│ │  │Retry     │   │    │      return users               │  │
│ │  │Timeout   │   │    │                                 │  │
│ │  └──────────┘   │    │                                 │  │
│ └─────────────────┘    └─────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

You can keep your existing app.py file untouched

# app.py
from premier.asgi import ASGIGateway, GatewayConfig
from fastapi import FastAPI

# Your existing app - no changes needed
app = FastAPI()

@app.get("/api/users/{user_id}")
async def get_user(user_id: int):
    return await fetch_user_from_database(user_id)

Next, import your app instance and wrap it with ASGIGateway:

# gateway.py
from .app import app
# Load configuration and wrap app
config = GatewayConfig.from_file("gateway.yaml")
app = ASGIGateway(config=config, app=app)

Then, instead of serving the original app directly, serve the one wrapped with ASGIGateway.

Standalone Mode

How it works: Single gateway handles all requests and forwards to backend services

                        ┌─────────────────────┐
    Client Request      │   Premier Gateway   │
         │              │  ┌──────────────┐   │
         │              │  │ Cache        │   │
         └──────────────►  │ RateLimit    │   │
                        │  │ Retry        │   │
                        │  │ Timeout      │   │
                        │  │ Monitoring   │   │
                        │  └──────────────┘   │
                        └─────┬──────┬────────┘
                              │      │
                    ┌─────────┘      └─────────┐
                    ▼                          ▼
            ┌───────────────┐          ┌───────────────┐
            │   Backend 1   │          │   Backend 2   │
            │ (Any Service) │          │ (Any Service) │
            │               │          │               │
            │ Node.js API   │          │  Python API   │
            │ Java Service  │          │  .NET Service │
            │ Static Files  │          │  Database     │
            └───────────────┘          └───────────────┘

# main.py
from premier.asgi import ASGIGateway, GatewayConfig

config = GatewayConfig.from_file("gateway.yaml")
gateway = ASGIGateway(config, servers=["http://backend:8000"])

uvicorn src:main

Decorator Mode

How it works: Apply Premier features directly to individual functions with decorators - no ASGI app required

WebSocket Support

Premier supports WebSocket connections with the same feature set:

# WebSocket connections are automatically handled
# Configure WebSocket-specific policies in YAML:

premier:
  paths:
    - pattern: "/ws/chat/*"
      features:
        rate_limit:
          quota: 100  # Max 100 connections per minute
          duration: 60
        monitoring:
          log_threshold: 5.0  # Log connections lasting >5s

YAML Configuration

Configure gateway policies declaratively:

premier:
  keyspace: "my-api"

  paths:
    - pattern: "/api/users/*"
      features:
        cache:
          expire_s: 300
        rate_limit:
          quota: 100
          duration: 60
          algorithm: "sliding_window"
        timeout:
          seconds: 5.0
        retry:
          max_attempts: 3
          wait: 1.0
        monitoring:
          log_threshold: 0.1

    - pattern: "/api/admin/*"
      features:
        rate_limit:
          quota: 10
          duration: 60
          algorithm: "token_bucket"
        timeout:
          seconds: 30.0

    - pattern: "/ws/*"
      features:
        rate_limit:
          quota: 50
          duration: 60
          algorithm: "sliding_window"
        monitoring:
          log_threshold: 1.0

  default_features:
    timeout:
      seconds: 10.0
    monitoring:
      log_threshold: 0.5

Configuration Reference

Premier supports extensive configuration options for path-based policies. Here's a complete reference of all available configuration fields:

Top-Level Configuration

| Field | Type | Description | Default | |-------|------|-------------|---------| | keyspace | string | Namespace for cache keys and throttling | "asgi-gateway" | | paths | array | Path-specific configuration rules | [] | | default_features | object | Default features applied to all paths | null | | servers | array | Backend server URLs for standalone mode | null |

Path Configuration

| Field | Type | Description | Example | |-------|------|-------------|---------| | pattern | string | Path pattern (regex or glob-style) | "/api/users/*", "^/admin/.*$" | | features | object | Features to apply to this path | See feature configuration below |

Feature Configuration

Cache Configuration

| Field | Type | Description | Default | Example | |-------|------|-------------|---------|---------| | expire_s | integer | Cache expiration in seconds | null (no expiration) | 300 | | cache_key | string/function | Custom cache key | Auto-generated | "user:{user_id}" |

Rate Limiting Configuration

| Field | Type | Description | Default | Example | |-------|------|-------------|---------|---------| | quota | integer | Number of requests allowed | Required | 100 | | duration | integer | Time window in seconds | Required | 60 | | algorithm | string | Rate limiting algorithm | "fixed_window" | "sliding_window", "token_bucket", "leaky_bucket" | | bucket_size | integer | Bucket size (for leaky_bucket) | Same as quota | 50 | | error_status | integer | HTTP status code for rate limit errors | 429 | 503 | | error_message | string | Error message for rate limit errors | "Rate limit exceeded" | "Too many requests" |

Timeout Configuration

| Field | Type | Description | Default | Example | |-------|------|-------------|---------|---------| | seconds | float | Timeout duration in seconds | Required | 5.0 | | error_status | integer | HTTP status code for timeout errors | 504 | 408 | | error_message | string | Error message for timeout errors | "Request timeout" | "Request took too long" |

Retry Configuration

| Field | Type | Description | Default | Example | |-------|------|-------------|---------|---------| | max_attempts | integer | Maximum retry attempts | 3 | 5 | | wait | float/array/function | Wait time between retries | 1.0 | [1, 2, 4] | | exceptions | array | Exception types to retry on | [Exception] | Custom excepti