waygate 0.2.0

Control how your API behaves at runtime. Roll out changes, enforce limits, and manage endpoints without redeploying.

What is Waygate

Waygate is an API behavior control layer for Python web applications.

It lets you control how your API responds — per request, per user, and per route — at runtime, without modifying business logic or redeploying.

Most teams handle API control in the wrong place: inside business logic with conditionals, in infrastructure with limited flexibility, or through redeploys for simple changes. Waygate gives you a dedicated runtime layer for that instead.

Solve real production problems

• Roll out a new endpoint to a subset of users safely
• Disable a broken route instantly without a hotfix
• Enforce rate limits per user or plan with no code changes
• Restrict features by environment or segment
• Schedule maintenance without touching code
• Manage all of the above from one dashboard, CLI, or REST API

Key features

Core (waygate.core)

These features are framework-agnostic and available to any adapter.

Framework adapters

FastAPI (waygate.fastapi) ✅ supported

Disabled and env-gated routes hidden from /docs. Maintenance banners injected live.

Install

uv add "waygate[all]"
# or: pip install "waygate[all]"

Quickstart

We currently support FastAPI. More framework adapters are on the way.

from fastapi import FastAPI
from waygate import make_engine
from waygate.fastapi import (
    WaygateMiddleware, WaygateAdmin, apply_waygate_to_openapi,
    maintenance, env_only, disabled, force_active, deprecated,
)

engine = make_engine()

app = FastAPI()
app.add_middleware(WaygateMiddleware, engine=engine)

@app.get("/payments")
@maintenance(reason="DB migration - back at 04:00 UTC")
async def get_payments():
    return {"payments": []}

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

apply_waygate_to_openapi(app, engine)
app.mount("/waygate", WaygateAdmin(engine=engine, auth=("admin", "secret")))

GET /payments  → 503  {"error": {"code": "MAINTENANCE_MODE", ...}}
GET /health    → 200  always

Manage routes from the CLI with no code changes or restarts:

waygate config set-url http://localhost:8000/waygate
waygate login admin
waygate status
waygate enable GET:/payments
waygate global enable --reason "Deploying v2" --exempt /health

Admin dashboard — route states, audit log, rate limits, and feature flags. No JS framework required.

Decorators

Custom responses (FastAPI)

By default, blocked routes return a structured JSON error body. You can replace it with HTML, a redirect, plain text, or custom JSON in two ways:

Per-route: pass response= directly on the decorator:

from starlette.requests import Request
from starlette.responses import HTMLResponse, RedirectResponse
from waygate.fastapi import maintenance, disabled

def maintenance_page(request: Request, exc: Exception) -> HTMLResponse:
    return HTMLResponse(
        f"<h1>Down for maintenance</h1><p>{exc.reason}</p>", status_code=503
    )

@router.get("/payments")
@maintenance(reason="DB migration", response=maintenance_page)
async def payments():
    return {"payments": []}

@router.get("/orders")
@maintenance(reason="Upgrade in progress", response=lambda *_: RedirectResponse("/status"))
async def orders():
    return {"orders": []}

Global default: set once on WaygateMiddleware, applies to every route without a per-route factory:

app.add_middleware(
    WaygateMiddleware,
    engine=engine,
    responses={
        "maintenance": maintenance_page,
        "disabled": lambda req, exc: HTMLResponse(
            f"<h1>Gone</h1><p>{exc.reason}</p>", status_code=503
        ),
    },
)

Resolution order: per-route response= then global responses[...] then built-in JSON. The factory can be sync or async and receives the live Request and the WaygateException that triggered the block.

Rate limiting

from waygate.fastapi import rate_limit

@router.get("/public/posts")
@rate_limit("10/minute")               # 10 req/min per IP
async def list_posts():
    return {"posts": [...]}

@router.get("/users/me")
@rate_limit("100/minute", key="user")  # per authenticated user
async def get_current_user():
    ...

@router.get("/reports")
@rate_limit(                           # tiered limits per plan
    {"free": "10/minute", "pro": "100/minute", "enterprise": "unlimited"},
    key="user",
)
async def get_reports():
    ...

Update limits at runtime with no redeploy:

waygate rl set GET:/public/posts 20/minute   # raise the limit live
waygate rl reset GET:/public/posts           # clear counters
waygate rl hits                              # blocked requests log

Requires waygate[rate-limit]. Powered by limits.

Feature flags

waygate ships a full feature flag system built on the OpenFeature standard. All five flag types, multi-condition targeting rules, user segments, percentage rollouts, and a live evaluation stream. Managed from the dashboard or CLI with no code changes.

from waygate import (
    FeatureFlag, FlagType, FlagVariation, RolloutVariation,
    TargetingRule, RuleClause, Operator, EvaluationContext,
)

engine.use_openfeature()

await engine.save_flag(
    FeatureFlag(
        key="new-checkout",
        name="New Checkout Flow",
        type=FlagType.BOOLEAN,
        variations=[
            FlagVariation(name="on",  value=True),
            FlagVariation(name="off", value=False),
        ],
        off_variation="off",
        fallthrough=[
            RolloutVariation(variation="on",  weight=20_000),  # 20%
            RolloutVariation(variation="off", weight=80_000),  # 80%
        ],
        targets={"on": ["beta_tester_1"]},
        rules=[
            TargetingRule(
                description="Enterprise users always get the new flow",
                clauses=[RuleClause(attribute="plan", operator=Operator.IS, values=["enterprise"])],
                variation="on",
            )
        ],
    )
)

# Evaluate in an async route handler
ctx = EvaluationContext(key=user_id, attributes={"plan": user.plan})
enabled = await engine.flag_client.get_boolean_value("new-checkout", False, ctx)

# Evaluate in a sync def handler (thread-safe)
enabled = engine.sync.flag_client.get_boolean_value("new-checkout", False, {"targeting_key": user_id})

Manage flags and segments from the CLI:

waygate flags list
waygate flags eval new-checkout --user user_123
waygate flags disable new-checkout          # kill-switch
waygate flags enable new-checkout
waygate flags stream                        # live evaluation events

waygate segments create beta_users --name "Beta Users"
waygate segments include beta_users --context-key user_123,user_456
waygate segments add-rule beta_users --attribute plan --operator in --values pro,enterprise

Requires waygate[flags].

Framework support

waygate's core is completely framework-agnostic with zero framework imports. Adapters plug into the engine and expose framework-native patterns like decorators, middleware, and routers.

Want your framework supported? Open an issue.

Backends

Embedded mode (single service)

For rate limiting in multi-worker deployments, use RedisBackend. Counters are atomic and shared across all processes.

Waygate Server mode (multi-service)

Run a dedicated WaygateServer process and connect each service via WaygateSDK. State is managed centrally; enforcement happens locally with zero per-request network overhead.

# Waygate Server (centralised, runs once)
from waygate.server import WaygateServer
waygate_app = WaygateServer(backend=MemoryBackend(), auth=("admin", "secret"))

# Each service (connects to the Waygate Server)
from waygate.sdk import WaygateSDK
sdk = WaygateSDK(server_url="http://waygate-server:9000", app_id="payments-service")
sdk.attach(app)

Documentation

Full documentation at attakay78.github.io/waygate

License

MIT