switchly 0.1.1

Switchly gives you runtime control of your APIs to toggle features, schedule maintenance, enforce rate limits, and perform rollouts without redeploying.

Key features

Core (switchly.core)

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

Framework adapters

FastAPI (switchly.fastapi) ✅ supported

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

Install

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

Quickstart

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

from fastapi import FastAPI
from switchly import make_engine
from switchly.fastapi import (
    SwitchlyMiddleware, SwitchlyAdmin, apply_switchly_to_openapi,
    maintenance, env_only, disabled, force_active, deprecated,
)

engine = make_engine()

app = FastAPI()
app.add_middleware(SwitchlyMiddleware, 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_switchly_to_openapi(app, engine)
app.mount("/switchly", SwitchlyAdmin(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:

switchly config set-url http://localhost:8000/switchly
switchly login admin
switchly status
switchly enable GET:/payments
switchly 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 switchly.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 SwitchlyMiddleware, applies to every route without a per-route factory:

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

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

Rate limiting

from switchly.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
    {"free": "10/minute", "pro": "100/minute", "enterprise": "unlimited"},
    key="user",
)
async def get_reports():
    ...

Policies can be mutated at runtime without redeploying (switchly rl and switchly rate-limits are aliases):

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

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

Feature flags

switchly 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 switchly import (
    FeatureFlag, FlagType, FlagVariation, RolloutVariation,
    TargetingRule, RuleClause, Operator, EvaluationContext,
)

engine.use_openfeature()

# Define a boolean flag with a 20% rollout and individual targeting
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"]},   # individual targeting
        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:

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

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

Requires switchly[flags].

Framework support

switchly'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.

Switchly Server mode (multi-service)

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

# Switchly Server (centralised, runs once)
from switchly.server import SwitchlyServer
switchly_app = SwitchlyServer(backend=MemoryBackend(), auth=("admin", "secret"))

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

Documentation

Full documentation at attakay78.github.io/switchly

License

MIT