svc-infra 0.1.640__py3-none-any.whl → 0.1.664__py3-none-any.whl

svc_infra/docs/versioned-integrations.md

@@ -0,0 +1,146 @@
+# Using add_* Functions Under Versioned Routing
+
+## Problem
+
+By default, `add_*` functions from svc-infra and fin-infra mount routes at root level (e.g., `/banking/*`, `/_sql/*`). However, you may want all features consolidated under a single versioned API prefix (e.g., `/v0/banking`) to keep your API organized under version namespaces.
+
+## Simple Solution (Recommended)
+
+Use the `extract_router()` helper:
+
+```python
+# src/your_api/routers/v0/banking.py
+from svc_infra.api.fastapi.versioned import extract_router
+from fin_infra.banking import add_banking
+
+# Extract router and provider from add_banking()
+router, banking_provider = extract_router(
+    add_banking,
+    prefix="/banking",
+    provider="plaid",
+    cache_ttl=60,
+)
+
+# That's it! svc-infra auto-discovers 'router' and mounts at /v0/banking
+```
+
+### Result
+
+- ✅ All banking endpoints under `/v0/banking/*`
+- ✅ Banking docs included in `/v0/docs` (not separate card)
+- ✅ Full `add_banking()` functionality preserved
+- ✅ Returns provider instance for additional use
+
+## Complete Example
+
+```python
+# Directory structure
+your_api/
+  routers/
+    v0/
+      __init__.py
+      status.py
+      banking.py      # <- Integration using helper
+      payments.py     # <- Another integration
+
+# banking.py - Clean and simple
+"""Banking integration under v0 routing."""
+from svc_infra.api.fastapi.versioned import extract_router
+from fin_infra.banking import add_banking
+
+router, banking_provider = extract_router(
+    add_banking,
+    prefix="/banking",
+    provider="plaid",  # or "teller"
+    cache_ttl=60,
+)
+
+# Optional: Store provider on app state for later use
+# This happens in app.py after router discovery:
+# app.state.banking = banking_provider
+```
+
+## Works With
+
+Any svc-infra or fin-infra function that calls `app.include_router()`:
+
+```python
+# Banking integration
+from fin_infra.banking import add_banking
+router, provider = extract_router(add_banking, prefix="/banking", provider="plaid")
+
+# Market data
+from fin_infra.markets import add_market_data
+router, provider = extract_router(add_market_data, prefix="/markets")
+
+# Analytics
+from fin_infra.analytics import add_analytics
+router, provider = extract_router(add_analytics, prefix="/analytics")
+
+# Budgets
+from fin_infra.budgets import add_budgets
+router, provider = extract_router(add_budgets, prefix="/budgets")
+
+# Documents
+from fin_infra.documents import add_documents
+router, provider = extract_router(add_documents, prefix="/documents")
+
+# Any custom add_* function following the pattern
+```
+
+## When to Use
+
+**Use when:**
+- Building a monolithic versioned API where all features belong under `/v0`, `/v1`, etc.
+- You want unified documentation at `/v0/docs` showing all features together
+- You're consolidating multiple integrations under one version
+- You need version-specific behavior for third-party integrations
+
+**Don't use when:**
+- Feature should have its own root-level endpoint (e.g., public webhooks at `/webhooks`)
+- Integration is shared across multiple versions (mount at root instead)
+- You only need a subset of endpoints (define manually)
+
+## Alternative: Manual Definition
+
+For simple integrations, define routes manually:
+
+```python
+# routers/v0/banking.py
+from svc_infra.api.fastapi.dual.public import public_router
+from fin_infra.banking import easy_banking
+
+router = public_router(prefix="/banking", tags=["Banking"])
+banking = easy_banking(provider="plaid")
+
+@router.post("/link")
+async def create_link(request: CreateLinkRequest):
+    return banking.create_link_token(user_id=request.user_id)
+
+# ... define other endpoints
+```
+
+Use manual definition when:
+- Only need a subset of integration endpoints
+- Want custom validation/transforms per endpoint
+- Integration is very simple (2-3 endpoints)
+- Need version-specific behavior per endpoint
+
+## How It Works
+
+The `extract_router()` helper:
+
+1. **Creates Mock App**: Temporary FastAPI instance to capture router
+2. **Intercepts Router**: Monkey-patches `include_router()` to capture instead of mount
+3. **Calls Integration**: Runs `add_*()` function which creates all routes normally
+4. **Returns Router**: Exports captured router for svc-infra auto-discovery
+5. **Auto-Mounts**: svc-infra finds `router` in `v0.banking` and mounts at `/v0/banking`
+
+The provider/integration instance is also returned for additional use if needed.
+
+## See Also
+
+- [API Versioning](./api.md#versioning) - How svc-infra version routing works
+- [Router Auto-Discovery](./api.md#router-discovery) - How routers are found and mounted
+- [Dual Routers](./api.md#dual-routers) - Similar pattern for public/protected routers
+- `svc_infra.api.fastapi.versioned` - Source code for helper function

svc_infra/security/models.py

@@ -6,7 +6,17 @@ import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
-from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Index, String, Text, UniqueConstraint
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    text,
+)
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from svc_infra.db.sql.base import ModelBase
@@ -34,7 +44,7 @@ class AuthSession(ModelBase):
     )
 
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
 
@@ -54,7 +64,7 @@ class RefreshToken(ModelBase):
     expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), index=True)
 
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
     __table_args__ = (UniqueConstraint("token_hash", name="uq_refresh_token_hash"),)
@@ -126,7 +136,7 @@ class Organization(ModelBase):
     slug: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
 
@@ -139,7 +149,7 @@ class Team(ModelBase):
     )
     name: Mapped[str] = mapped_column(String(128), nullable=False)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
 
@@ -155,7 +165,7 @@ class OrganizationMembership(ModelBase):
     )
     role: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
     deactivated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
 
@@ -177,7 +187,7 @@ class OrganizationInvitation(ModelBase):
         GUID(), ForeignKey("users.id", ondelete="SET NULL"), index=True
     )
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
     last_sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
     resend_count: Mapped[int] = mapped_column(default=0)
@@ -185,6 +195,11 @@ class OrganizationInvitation(ModelBase):
     revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
 
 
+# ------------------------ OAuth Provider Accounts -----------------------------
+# MOVED to svc_infra.security.oauth_models for opt-in OAuth support
+# Projects that enable OAuth should import ProviderAccount from there
+
+
 # ------------------------ Utilities -------------------------------------------
 
 
@@ -238,6 +253,11 @@ __all__ = [
     "FailedAuthAttempt",
     "RolePermission",
     "AuditLog",
+    "Organization",
+    "Team",
+    "OrganizationMembership",
+    "OrganizationInvitation",
+    # ProviderAccount moved to svc_infra.security.oauth_models (opt-in)
     "generate_refresh_token",
     "hash_refresh_token",
     "compute_audit_hash",

svc_infra/security/oauth_models.py

@@ -0,0 +1,59 @@
+"""
+OAuth provider account models (opt-in).
+
+These models are only registered when a project explicitly enables OAuth.
+Import this module only when enable_oauth=True is passed to add_auth_users.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Index, String, Text, UniqueConstraint, text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from svc_infra.db.sql.base import ModelBase
+from svc_infra.db.sql.types import GUID
+
+if TYPE_CHECKING:
+    from svc_infra.security.models import User
+
+
+class ProviderAccount(ModelBase):
+    """OAuth provider account linking (Google, GitHub, etc.)."""
+
+    __tablename__ = "provider_accounts"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    provider_account_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    access_token: Mapped[Optional[str]] = mapped_column(Text)
+    refresh_token: Mapped[Optional[str]] = mapped_column(Text)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    raw_claims: Mapped[Optional[dict]] = mapped_column(JSON)
+
+    # Bidirectional relationship to User model
+    user: Mapped["User"] = relationship(back_populates="provider_accounts")
+
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+    updated_at = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("provider", "provider_account_id", name="uq_provider_account"),
+        Index("ix_provider_accounts_user_provider", "user_id", "provider"),
+    )
+
+
+__all__ = ["ProviderAccount"]

svc_infra/storage/__init__.py

@@ -0,0 +1,93 @@
+"""
+Generic file storage system for svc-infra.
+
+Provides backend-agnostic file storage with support for multiple providers:
+- Local filesystem (Railway volumes, Render, development)
+- S3-compatible (AWS S3, DigitalOcean Spaces, Wasabi, Backblaze B2, Minio)
+- Google Cloud Storage (coming soon)
+- Cloudinary (coming soon)
+- In-memory (testing)
+
+Quick Start:
+    >>> from svc_infra.storage import add_storage, easy_storage
+    >>> from fastapi import FastAPI
+    >>>
+    >>> app = FastAPI()
+    >>>
+    >>> # Auto-detect backend from environment
+    >>> storage = add_storage(app)
+    >>>
+    >>> # Or explicit backend
+    >>> backend = easy_storage(backend="s3", bucket="my-uploads")
+    >>> storage = add_storage(app, backend)
+
+Usage in Routes:
+    >>> from svc_infra.storage import get_storage, StorageBackend
+    >>> from fastapi import Depends, UploadFile
+    >>>
+    >>> @router.post("/upload")
+    >>> async def upload_file(
+    ...     file: UploadFile,
+    ...     storage: StorageBackend = Depends(get_storage),
+    ... ):
+    ...     content = await file.read()
+    ...     url = await storage.put(
+    ...         key=f"uploads/{file.filename}",
+    ...         data=content,
+    ...         content_type=file.content_type or "application/octet-stream",
+    ...         metadata={"user_id": "user_123"}
+    ...     )
+    ...     return {"url": url}
+
+Environment Variables:
+    STORAGE_BACKEND: Backend type (local, s3, gcs, cloudinary, memory)
+
+    Local:
+        STORAGE_BASE_PATH: Directory for files (default: /data/uploads)
+        STORAGE_BASE_URL: URL for file serving (default: http://localhost:8000/files)
+
+    S3:
+        STORAGE_S3_BUCKET: Bucket name (required)
+        STORAGE_S3_REGION: AWS region (default: us-east-1)
+        STORAGE_S3_ENDPOINT: Custom endpoint for S3-compatible services
+        STORAGE_S3_ACCESS_KEY: Access key (falls back to AWS_ACCESS_KEY_ID)
+        STORAGE_S3_SECRET_KEY: Secret key (falls back to AWS_SECRET_ACCESS_KEY)
+
+See Also:
+    - ADR-0012: Generic File Storage System design
+    - docs/storage.md: Comprehensive storage guide
+"""
+
+from .add import add_storage, get_storage, health_check_storage
+from .backends import LocalBackend, MemoryBackend, S3Backend
+from .base import (
+    FileNotFoundError,
+    InvalidKeyError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    StorageBackend,
+    StorageError,
+)
+from .easy import easy_storage
+from .settings import StorageSettings
+
+__all__ = [
+    # Main API
+    "add_storage",
+    "easy_storage",
+    "get_storage",
+    "health_check_storage",
+    # Base types
+    "StorageBackend",
+    "StorageSettings",
+    # Backends
+    "LocalBackend",
+    "MemoryBackend",
+    "S3Backend",
+    # Exceptions
+    "StorageError",
+    "FileNotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "InvalidKeyError",
+]

svc_infra/storage/add.py

@@ -0,0 +1,250 @@
+"""
+FastAPI integration for storage system.
+
+Provides helpers to integrate storage backends with FastAPI applications.
+"""
+
+import logging
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+
+from .base import FileNotFoundError, PermissionDeniedError, StorageBackend, StorageError
+from .easy import easy_storage
+
+logger = logging.getLogger(__name__)
+
+
+def add_storage(
+    app: FastAPI,
+    backend: Optional[StorageBackend] = None,
+    serve_files: bool = False,
+    file_route_prefix: str = "/files",
+) -> StorageBackend:
+    """
+    Add storage backend to FastAPI application.
+
+    This function:
+    - Stores backend in app.state.storage
+    - Registers startup/shutdown hooks
+    - Optionally mounts file serving route
+    - Adds health check integration
+
+    Args:
+        app: FastAPI application instance
+        backend: Storage backend instance (auto-detected if None)
+        serve_files: If True, mount route to serve files (LocalBackend only)
+        file_route_prefix: URL prefix for file serving (default: "/files")
+
+    Returns:
+        Storage backend instance
+
+    Example:
+        >>> from fastapi import FastAPI
+        >>> from svc_infra.storage import add_storage, easy_storage
+        >>>
+        >>> app = FastAPI()
+        >>>
+        >>> # Auto-detect backend
+        >>> storage = add_storage(app)
+        >>>
+        >>> # Explicit backend
+        >>> backend = easy_storage(backend="s3", bucket="my-uploads")
+        >>> storage = add_storage(app, backend)
+        >>>
+        >>> # With file serving (LocalBackend only)
+        >>> backend = easy_storage(backend="local")
+        >>> storage = add_storage(app, backend, serve_files=True)
+
+    Note:
+        File serving is only supported for LocalBackend. For S3/GCS,
+        use presigned URLs instead.
+    """
+    # Auto-detect backend if not provided
+    if backend is None:
+        backend = easy_storage()
+
+    # Store in app state
+    app.state.storage = backend
+
+    # Get existing lifespan or create new one
+    existing_lifespan = getattr(app.router, "lifespan_context", None)
+
+    @asynccontextmanager
+    async def storage_lifespan(app: FastAPI):
+        # Startup
+        logger.info(f"Storage backend initialized: {backend.__class__.__name__}")
+
+        # Test connection for S3 backend
+        if hasattr(backend, "bucket"):
+            try:
+                # Try to list keys (limit 1 to minimize cost)
+                await backend.list_keys(limit=1)
+                logger.info(f"Successfully connected to storage: {backend.bucket}")
+            except Exception as e:
+                logger.error(f"Failed to connect to storage: {e}")
+                # Don't fail startup, let health check catch it
+
+        # Call existing lifespan if present
+        if existing_lifespan is not None:
+            async with existing_lifespan(app):
+                yield
+        else:
+            yield
+
+        # Shutdown
+        logger.info("Storage backend shutdown")
+
+    # Replace lifespan
+    app.router.lifespan_context = storage_lifespan
+
+    # Mount file serving route if requested (LocalBackend only)
+    if serve_files:
+        from .backends.local import LocalBackend
+
+        if not isinstance(backend, LocalBackend):
+            logger.warning(
+                f"File serving only supported for LocalBackend, "
+                f"got {backend.__class__.__name__}. Skipping route mount."
+            )
+        else:
+            # Create file serving route
+            @app.get(f"{file_route_prefix}/{{key:path}}")
+            async def serve_file(
+                key: str,
+                expires: str = Query(..., description="Expiration timestamp"),
+                signature: str = Query(..., description="HMAC signature"),
+                download: bool = Query(False, description="Force download"),
+            ):
+                """
+                Serve files from local storage with signature validation.
+
+                Requires valid signature generated by LocalBackend.get_url().
+                """
+                # Verify signature
+                if not backend.verify_url(key, expires, signature, download):
+                    raise HTTPException(
+                        status_code=403,
+                        detail="Invalid or expired signature",
+                    )
+
+                # Get file
+                try:
+                    data = await backend.get(key)
+                    metadata = await backend.get_metadata(key)
+
+                    # Determine content disposition
+                    if download:
+                        filename = key.split("/")[-1]
+                        content_disposition = f'attachment; filename="{filename}"'
+                    else:
+                        content_disposition = "inline"
+
+                    # Return file
+                    return StreamingResponse(
+                        iter([data]),
+                        media_type=metadata.get("content_type", "application/octet-stream"),
+                        headers={
+                            "Content-Disposition": content_disposition,
+                            "Content-Length": str(len(data)),
+                        },
+                    )
+
+                except FileNotFoundError:
+                    raise HTTPException(status_code=404, detail="File not found")
+                except PermissionDeniedError:
+                    raise HTTPException(status_code=403, detail="Permission denied")
+                except StorageError as e:
+                    logger.error(f"Storage error serving file {key}: {e}")
+                    raise HTTPException(status_code=500, detail="Storage error")
+
+            logger.info(f"File serving enabled at {file_route_prefix}")
+
+    return backend
+
+
+def get_storage(request: Request) -> StorageBackend:
+    """
+    FastAPI dependency to inject storage backend.
+
+    Use this in route handlers to access the storage backend.
+
+    Example:
+        >>> from fastapi import APIRouter, Depends, UploadFile
+        >>> from svc_infra.storage import get_storage, StorageBackend
+        >>>
+        >>> router = APIRouter()
+        >>>
+        >>> @router.post("/upload")
+        >>> async def upload_file(
+        ...     file: UploadFile,
+        ...     storage: StorageBackend = Depends(get_storage),
+        ... ):
+        ...     content = await file.read()
+        ...     url = await storage.put(
+        ...         key=f"uploads/{file.filename}",
+        ...         data=content,
+        ...         content_type=file.content_type or "application/octet-stream"
+        ...     )
+        ...     return {"url": url}
+
+    Raises:
+        RuntimeError: If storage not initialized with add_storage()
+    """
+    if not hasattr(request.app.state, "storage"):
+        raise RuntimeError(
+            "Storage not initialized. " "Call add_storage(app) during application setup."
+        )
+
+    return request.app.state.storage
+
+
+async def health_check_storage(request: Request) -> dict:
+    """
+    Health check for storage backend.
+
+    Returns storage status and basic statistics.
+
+    Example:
+        >>> from fastapi import FastAPI
+        >>> from svc_infra.storage import add_storage, health_check_storage
+        >>>
+        >>> app = FastAPI()
+        >>> add_storage(app)
+        >>>
+        >>> @app.get("/_health/storage")
+        >>> async def storage_health(request: Request):
+        ...     return await health_check_storage(request)
+
+    Returns:
+        Dict with status and backend information
+    """
+    try:
+        storage = get_storage(request)
+
+        # Get backend type
+        backend_type = storage.__class__.__name__.replace("Backend", "").lower()
+
+        # Try a simple operation
+        await storage.list_keys(limit=1)
+
+        return {
+            "status": "healthy",
+            "backend": backend_type,
+        }
+
+    except Exception as e:
+        logger.error(f"Storage health check failed: {e}")
+        return {
+            "status": "unhealthy",
+            "error": str(e),
+        }
+
+
+__all__ = [
+    "add_storage",
+    "get_storage",
+    "health_check_storage",
+]

svc_infra/storage/backends/__init__.py

@@ -0,0 +1,11 @@
+"""Storage backend implementations."""
+
+from .local import LocalBackend
+from .memory import MemoryBackend
+from .s3 import S3Backend
+
+__all__ = [
+    "LocalBackend",
+    "MemoryBackend",
+    "S3Backend",
+]