Metadata-Version: 2.3
Name: svc-infra
Version: 1.16.1
Summary: Infrastructure for building and deploying prod-ready services
License: MIT
Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
Author: Ali Khatami
Author-email: aliikhatami94@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: adyen
Provides-Extra: duckdb
Provides-Extra: metrics
Provides-Extra: mongodb
Provides-Extra: mssql
Provides-Extra: mysql
Provides-Extra: payments
Provides-Extra: pg
Provides-Extra: pg2
Provides-Extra: redshift
Provides-Extra: s3
Provides-Extra: snowflake
Provides-Extra: sqlite
Provides-Extra: stripe
Requires-Dist: adyen (>=10.0.0) ; extra == "payments" or extra == "adyen"
Requires-Dist: aioboto3 (>=12.0.0) ; extra == "s3"
Requires-Dist: aiofiles (>=24.0.0)
Requires-Dist: aiosqlite (>=0.19.0) ; extra == "sqlite"
Requires-Dist: alembic (>=1.13.0)
Requires-Dist: asyncpg (>=0.29.0) ; extra == "pg"
Requires-Dist: authlib (>=1.6.9)
Requires-Dist: cashews[redis] (>=7.0)
Requires-Dist: cryptography (>=41.0.0)
Requires-Dist: duckdb (>=0.10.0) ; extra == "duckdb"
Requires-Dist: email-validator (>=2.0.0)
Requires-Dist: fastapi (>=0.110.0)
Requires-Dist: fastapi-users-db-sqlalchemy (>=7.0.0)
Requires-Dist: fastapi-users[oauth] (>=14.0.0)
Requires-Dist: greenlet (>=3.0)
Requires-Dist: httpx (>=0.25.0)
Requires-Dist: httpx-oauth (>=0.15.0)
Requires-Dist: itsdangerous (>=2.0.0)
Requires-Dist: mcp (>=1.0.0)
Requires-Dist: motor (>=3.0.0) ; extra == "mongodb"
Requires-Dist: mysqlclient (>=2.2.0) ; extra == "mysql"
Requires-Dist: opentelemetry-exporter-otlp (>=1.20.0)
Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.41b0)
Requires-Dist: opentelemetry-instrumentation-httpx (>=0.41b0)
Requires-Dist: opentelemetry-instrumentation-requests (>=0.41b0)
Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.41b0)
Requires-Dist: opentelemetry-propagator-b3 (>=1.20.0)
Requires-Dist: opentelemetry-sdk (>=1.20.0)
Requires-Dist: passlib[bcrypt] (>=1.7.4)
Requires-Dist: prometheus-client (>=0.18.0) ; extra == "metrics"
Requires-Dist: psycopg2-binary (>=2.9.0) ; extra == "pg2"
Requires-Dist: psycopg[binary] (>=3.0) ; extra == "pg"
Requires-Dist: pydantic-settings (>=2.0)
Requires-Dist: pyjwt (>=2.12.0)
Requires-Dist: pymysql (>=1.1.0) ; extra == "mysql"
Requires-Dist: pyodbc (>=5.0.0) ; extra == "mssql"
Requires-Dist: pyotp (>=2.9.0)
Requires-Dist: python-dotenv (>=1.0.0)
Requires-Dist: redis (>=5.0.0)
Requires-Dist: redshift-connector (>=2.0.0) ; extra == "redshift"
Requires-Dist: segno (>=1.6.6,<2.0.0)
Requires-Dist: snowflake-connector-python (>=3.0.0) ; extra == "snowflake"
Requires-Dist: sqlalchemy[asyncio] (>=2.0)
Requires-Dist: stripe (>=7.0.0) ; extra == "payments" or extra == "stripe"
Requires-Dist: typer (>=0.12.0)
Requires-Dist: websockets (>=12.0)
Project-URL: Documentation, https://nfrax.com/svc-infra
Project-URL: Homepage, https://github.com/nfraxlab/svc-infra
Project-URL: Issues, https://github.com/nfraxlab/svc-infra/issues
Project-URL: Repository, https://github.com/nfraxlab/svc-infra
Description-Content-Type: text/markdown

# svc-infra

**Production-ready FastAPI infrastructure in one import.**

[![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
[![CI](https://github.com/nfraxlab/svc-infra/actions/workflows/ci.yml/badge.svg)](https://github.com/nfraxlab/svc-infra/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/svc-infra.svg)](https://pypi.org/project/svc-infra/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Overview

Stop rebuilding auth, billing, webhooks, and background jobs for every project.

### Key Features

- **Auth** - JWT, sessions, OAuth/OIDC, MFA, API keys
- **Billing** - Usage tracking, subscriptions, invoices, Stripe sync
- **Database** - PostgreSQL + MongoDB, migrations, inbox/outbox
- **Jobs** - Background tasks, scheduling, retries, DLQ
- **Webhooks** - Subscriptions, HMAC signing, delivery retries
- **Observability** - Prometheus, Grafana dashboards, OTEL

## Why svc-infra?

Every FastAPI project needs the same things: authentication, database setup, background jobs, caching, webhooks, billing... You've written this code before. Multiple times.

**svc-infra** packages battle-tested infrastructure used in production, so you can focus on your actual product:

```python
from svc_infra.api.fastapi.ease import easy_service_app

app = easy_service_app(name="MyAPI", release="1.0.0")
# Health checks, CORS, security headers, structured logging
# Prometheus metrics, OpenTelemetry tracing
# Request IDs, idempotency middleware
# That's it. Ship it.
```

## Quick Install

```bash
pip install svc-infra
```

## What's Included

| Feature | What You Get | One-liner |
|---------|-------------|-----------|
| **Auth** | JWT, sessions, OAuth/OIDC, MFA, API keys | `add_auth_users(app)` |
| **Billing** | Usage tracking, subscriptions, invoices, Stripe sync | `add_billing(app)` |
| **Database** | PostgreSQL + MongoDB, migrations, inbox/outbox | `add_sql_db(app)` |
| **Jobs** | Background tasks, scheduling, retries, DLQ | `easy_jobs()` |
| **Webhooks** | Subscriptions, HMAC signing, delivery retries | `add_webhooks(app)` |
| **Cache** | Redis/memory, decorators, namespacing | `init_cache()` |
| **Observability** | Prometheus, Grafana dashboards, OTEL | Built-in |
| **Storage** | S3, local, memory backends | `add_storage(app)` |
| **Multi-tenancy** | Tenant isolation, scoped queries | Built-in |
| **Rate Limiting** | Per-user, per-endpoint, headers | Built-in |

## 30-Second Example

Build a complete SaaS backend:

```python
from fastapi import Depends
from svc_infra.api.fastapi.ease import easy_service_app
from svc_infra.api.fastapi.db.sql.add import add_sql_db
from svc_infra.api.fastapi.auth import add_auth_users, current_active_user
from svc_infra.jobs.easy import easy_jobs
from svc_infra.webhooks.fastapi import require_signature

# Create app with batteries included
app = easy_service_app(name="MySaaS", release="1.0.0")

# Add infrastructure
add_sql_db(app)                    # PostgreSQL with migrations
add_auth_users(app)                # Full auth system
queue, scheduler = easy_jobs()     # Background jobs

# Your actual business logic
@app.post("/api/process")
async def process_data(user=Depends(current_active_user)):
    job = queue.enqueue("heavy_task", {"user_id": user.id})
    return {"job_id": job.id, "status": "queued"}

# Webhook endpoint with signature verification
@app.post("/webhooks/stripe")
async def stripe_webhook(payload=Depends(require_signature(lambda: ["whsec_..."]))):
    queue.enqueue("process_payment", payload)
    return {"received": True}
```

**That's a production-ready API** with auth, database, background jobs, and webhook handling.

## Feature Highlights

### Authentication & Security

Full auth system with zero boilerplate:

```python
from svc_infra.api.fastapi.auth import add_auth_users, current_active_user

add_auth_users(app)  # Registers /auth/* routes automatically

@app.get("/me")
async def get_profile(user=Depends(current_active_user)):
    return {"email": user.email, "mfa_enabled": user.mfa_enabled}
```

**Includes:** JWT tokens, session cookies, OAuth/OIDC (Google, GitHub, etc.), MFA/TOTP, password policies, account lockout, key rotation.

### Usage-Based Billing

Track usage and generate invoices:

```python
from svc_infra.billing import BillingService

billing = BillingService(session=db, tenant_id="tenant_123")

# Record API usage (idempotent)
billing.record_usage(metric="api_calls", amount=1, idempotency_key="req_abc")

# Generate monthly invoice
invoice = billing.generate_monthly_invoice(
    period_start=datetime(2025, 1, 1),
    period_end=datetime(2025, 2, 1),
)
```

**Includes:** Usage events, aggregation, plans & entitlements, subscriptions, invoices, Stripe sync hooks.

### Background Jobs

Redis-backed job queue with retries:

```python
from svc_infra.jobs.easy import easy_jobs

queue, scheduler = easy_jobs()  # Auto-detects Redis or uses memory

# Enqueue work
queue.enqueue("send_email", {"to": "user@example.com", "template": "welcome"})

# Schedule recurring tasks
scheduler.add("cleanup", interval_seconds=3600, target="myapp.tasks:cleanup")
```

```bash
# Run the worker
svc-infra jobs run
```

**Includes:** Visibility timeout, exponential backoff, dead letter queue, interval scheduler, CLI worker.

### Webhooks

Send and receive webhooks with proper security:

```python
from svc_infra.webhooks import add_webhooks, WebhookService

add_webhooks(app)  # Adds subscription management routes

# Publish events
webhook_service.publish("invoice.paid", {"invoice_id": "inv_123"})

# Verify incoming webhooks
@app.post("/webhooks/external")
async def receive(payload=Depends(require_signature(lambda: ["secret1", "secret2"]))):
    return {"ok": True}
```

**Includes:** Subscription store, HMAC-SHA256 signing, delivery retries, idempotent processing.

### Observability

Production monitoring out of the box:

```python
app = easy_service_app(name="MyAPI", release="1.0.0")
# Prometheus metrics at /metrics
# Health checks at /healthz, /readyz, /startupz
# Request tracing with OpenTelemetry
```

```bash
# Generate Grafana dashboards
svc-infra obs dashboard --service myapi --output ./dashboards/
```

**Includes:** Prometheus metrics, Grafana dashboard generator, OTEL integration, SLO helpers.

## Configuration

Everything is configurable via environment variables:

```bash
# Database
SQL_URL=postgresql://user:pass@localhost/mydb
MONGO_URL=mongodb://localhost:27017

# Auth
AUTH_JWT__SECRET=your-secret-key
AUTH_SMTP_HOST=smtp.sendgrid.net

# Jobs
JOBS_DRIVER=redis
REDIS_URL=redis://localhost:6379

# Storage
STORAGE_BACKEND=s3
STORAGE_S3_BUCKET=my-uploads

# Observability
ENABLE_OBS=true
METRICS_PATH=/metrics
```

See the [Environment Reference](docs/environment.md) for all options.

## Documentation

| Module | Description | Guide |
|--------|-------------|-------|
| **API** | FastAPI bootstrap, middleware, versioning | [docs/api.md](docs/api.md) |
| **Auth** | Sessions, OAuth/OIDC, MFA, API keys | [docs/auth.md](docs/auth.md) |
| **Billing** | Usage tracking, subscriptions, invoices | [docs/billing.md](docs/billing.md) |
| **Database** | SQL + MongoDB, migrations, patterns | [docs/database.md](docs/database.md) |
| **Jobs** | Background tasks, scheduling | [docs/jobs.md](docs/jobs.md) |
| **Webhooks** | Publishing, signing, verification | [docs/webhooks.md](docs/webhooks.md) |
| **Cache** | Redis/memory caching, TTL helpers | [docs/cache.md](docs/cache.md) |
| **Storage** | S3, local, memory file storage | [docs/storage.md](docs/storage.md) |
| **Observability** | Metrics, tracing, dashboards | [docs/observability.md](docs/observability.md) |
| **Security** | Password policy, headers, MFA | [docs/security.md](docs/security.md) |
| **Tenancy** | Multi-tenant isolation | [docs/tenancy.md](docs/tenancy.md) |
| **CLI** | Command-line tools | [docs/cli.md](docs/cli.md) |

## Running the Example

See all features working together:

```bash
git clone https://github.com/nfraxlab/svc-infra.git
cd svc-infra

# Setup and run
make setup-template    # Creates DB, runs migrations
make run-template      # Starts at http://localhost:8001
```

Visit http://localhost:8001/docs to explore the API.

## Related Packages

svc-infra is part of the **nfrax** infrastructure suite:

| Package | Purpose |
|---------|---------|
| **[svc-infra](https://github.com/nfraxlab/svc-infra)** | Backend infrastructure (auth, billing, jobs, webhooks) |
| **[ai-infra](https://github.com/nfraxlab/ai-infra)** | AI/LLM infrastructure (agents, tools, RAG, MCP) |
| **[fin-infra](https://github.com/nfraxlab/fin-infra)** | Financial infrastructure (banking, portfolio, insights) |

## License

MIT License - use it for anything.

---

<div align="center">

**Built by [nfraxlab](https://github.com/nfraxlab)**

[Star us on GitHub](https://github.com/nfraxlab/svc-infra) · [View on PyPI](https://pypi.org/project/svc-infra/)

</div>

