Metadata-Version: 2.3
Name: svc-infra
Version: 0.1.687
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 :: 4 - Beta
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: Typing :: Typed
Provides-Extra: duckdb
Provides-Extra: metrics
Provides-Extra: mssql
Provides-Extra: mysql
Provides-Extra: pg
Provides-Extra: pg2
Provides-Extra: redshift
Provides-Extra: s3
Provides-Extra: snowflake
Provides-Extra: sqlite
Requires-Dist: adyen (>=13.4.0,<14.0.0)
Requires-Dist: ai-infra (>=0.1.63,<0.2.0)
Requires-Dist: aioboto3 (>=13.0.0,<14.0.0) ; extra == "s3"
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: aiosqlite (>=0.20.0,<0.21.0) ; extra == "sqlite"
Requires-Dist: alembic (>=1.13.2,<2.0.0)
Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "pg"
Requires-Dist: authlib (>=1.6.2,<2.0.0)
Requires-Dist: cashews[redis] (>=7.4.1,<8.0.0)
Requires-Dist: duckdb (>=1.1.3,<2.0.0) ; extra == "duckdb"
Requires-Dist: email-validator (>=2.2.0,<3.0.0)
Requires-Dist: fastapi (>=0.116.1,<0.117.0)
Requires-Dist: fastapi-users-db-sqlalchemy (>=7.0.0,<8.0.0)
Requires-Dist: fastapi-users[oauth] (>=14.0.1,<15.0.0)
Requires-Dist: greenlet (>=3,<4)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: httpx-oauth (>=0.16.1,<0.17.0)
Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
Requires-Dist: mcp (>=1.13.0,<2.0.0)
Requires-Dist: motor (>=3.7.1,<4.0.0)
Requires-Dist: mysqlclient (>=2.2.4,<3.0.0) ; extra == "mysql"
Requires-Dist: opentelemetry-exporter-otlp (>=1.36.0,<2.0.0)
Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-httpx (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-requests (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-propagator-b3 (>=1.36.0,<2.0.0)
Requires-Dist: opentelemetry-sdk (>=1.36.0,<2.0.0)
Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
Requires-Dist: pre-commit (>=4.3.0,<5.0.0)
Requires-Dist: prometheus-client (>=0.22.1,<0.23.0) ; extra == "metrics"
Requires-Dist: psycopg2-binary (>=2.9.10,<3.0.0) ; extra == "pg2"
Requires-Dist: psycopg[binary] (>=3.2.10,<4.0.0) ; extra == "pg"
Requires-Dist: pydantic-settings (>=2.10.1,<3.0.0)
Requires-Dist: pymysql (>=1.1.1,<2.0.0) ; extra == "mysql"
Requires-Dist: pyodbc (>=5.1.0,<6.0.0) ; extra == "mssql"
Requires-Dist: pyotp (>=2.9.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
Requires-Dist: redis (>=6.4.0,<7.0.0)
Requires-Dist: redshift-connector (>=2.0.918,<3.0.0) ; extra == "redshift"
Requires-Dist: snowflake-connector-python (>=3.12.0,<4.0.0) ; extra == "snowflake"
Requires-Dist: sqlalchemy[asyncio] (>=2.0.43,<3.0.0)
Requires-Dist: stripe (>=13.0.1,<14.0.0)
Requires-Dist: typer (>=0.16.1,<0.17.0)
Requires-Dist: websockets (>=15.0.1,<16.0.0)
Project-URL: Documentation, https://github.com/your-org/svc-infra#readme
Project-URL: Homepage, https://github.com/your-org/svc-infra
Project-URL: Issues, https://github.com/your-org/svc-infra/issues
Project-URL: Repository, https://github.com/your-org/svc-infra
Description-Content-Type: text/markdown

<div align="center">

# 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/) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Downloads](https://static.pepy.tech/badge/svc-infra/month)](https://pepy.tech/project/svc-infra)

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

[Documentation](docs/) · [Examples](examples/) · [PyPI](https://pypi.org/project/svc-infra/)

</div>

---

## 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/nfraxio/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/nfraxio/svc-infra)** | Backend infrastructure (auth, billing, jobs, webhooks) |
| **[ai-infra](https://github.com/nfraxio/ai-infra)** | AI/LLM infrastructure (agents, tools, RAG, MCP) |
| **[fin-infra](https://github.com/nfraxio/fin-infra)** | Financial infrastructure (banking, portfolio, insights) |

## 📄 License

MIT License - use it for anything.

---

<div align="center">

**Built with ❤️ by [nfraxio](https://github.com/nfraxio)**

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

</div>

