svc-infra 0.1.589__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/billing/models.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import JSON, DateTime, Index, Numeric, String, UniqueConstraint, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from svc_infra.db.sql.base import ModelBase
+
+TENANT_ID_LEN = 64
+
+
+class UsageEvent(ModelBase):
+    __tablename__ = "billing_usage_events"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(
+        String(TENANT_ID_LEN), index=True, nullable=False
+    )
+    metric: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    at_ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    metadata_json: Mapped[dict] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id", "metric", "idempotency_key", name="uq_usage_idem"
+        ),
+        Index("ix_usage_tenant_metric_ts", "tenant_id", "metric", "at_ts"),
+    )
+
+
+class UsageAggregate(ModelBase):
+    __tablename__ = "billing_usage_aggregates"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(
+        String(TENANT_ID_LEN), index=True, nullable=False
+    )
+    metric: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    period_start: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False
+    )
+    granularity: Mapped[str] = mapped_column(
+        String(8), nullable=False
+    )  # hour|day|month
+    total: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id", "metric", "period_start", "granularity", name="uq_usage_agg"
+        ),
+    )
+
+
+class Plan(ModelBase):
+    __tablename__ = "billing_plans"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(
+        String(64), unique=True, index=True, nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    description: Mapped[Optional[str]] = mapped_column(String(255))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+
+class PlanEntitlement(ModelBase):
+    __tablename__ = "billing_plan_entitlements"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    plan_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    key: Mapped[str] = mapped_column(String(64), nullable=False)
+    limit_per_window: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    window: Mapped[str] = mapped_column(String(8), nullable=False)  # day|month
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+
+class Subscription(ModelBase):
+    __tablename__ = "billing_subscriptions"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(
+        String(TENANT_ID_LEN), index=True, nullable=False
+    )
+    plan_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    effective_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False
+    )
+    ended_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+
+class Price(ModelBase):
+    __tablename__ = "billing_prices"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(
+        String(64), unique=True, index=True, nullable=False
+    )
+    currency: Mapped[str] = mapped_column(String(8), nullable=False)
+    unit_amount: Mapped[int] = mapped_column(
+        Numeric(18, 0), nullable=False
+    )  # minor units
+    metric: Mapped[Optional[str]] = mapped_column(
+        String(64)
+    )  # null for fixed recurring
+    recurring_interval: Mapped[Optional[str]] = mapped_column(String(8))  # month|year
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+
+class Invoice(ModelBase):
+    __tablename__ = "billing_invoices"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(
+        String(TENANT_ID_LEN), index=True, nullable=False
+    )
+    period_start: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False
+    )
+    period_end: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False
+    )
+    status: Mapped[str] = mapped_column(String(16), index=True, nullable=False)
+    total_amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    currency: Mapped[str] = mapped_column(String(8), nullable=False)
+    provider_invoice_id: Mapped[Optional[str]] = mapped_column(String(128), index=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+
+
+class InvoiceLine(ModelBase):
+    __tablename__ = "billing_invoice_lines"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    invoice_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    price_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    metric: Mapped[Optional[str]] = mapped_column(String(64))
+    quantity: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )

svc_infra/billing/quotas.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Annotated, Optional
+
+from fastapi import Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from svc_infra.api.fastapi.db.sql.session import SqlSessionDep
+from svc_infra.api.fastapi.tenancy.context import TenantId
+
+from .models import PlanEntitlement, Subscription, UsageAggregate
+
+
+async def _current_subscription(
+    session: AsyncSession, tenant_id: str
+) -> Optional[Subscription]:
+    now = datetime.now(tz=timezone.utc)
+    row = (
+        (
+            await session.execute(
+                select(Subscription)
+                .where(Subscription.tenant_id == tenant_id)
+                .order_by(Subscription.effective_at.desc())
+            )
+        )
+        .scalars()
+        .first()
+    )
+    if row is None:
+        return None
+    # basic check: if ended_at is set and in the past, treat as inactive
+    if row.ended_at is not None and row.ended_at <= now:
+        return None
+    return row
+
+
+def require_quota(metric: str, *, window: str = "day", soft: bool = True):
+    async def _dep(tenant_id: TenantId, session: SqlSessionDep) -> None:
+        sub = await _current_subscription(session, tenant_id)
+        if sub is None:
+            # no subscription → allow (unlimited) by default
+            return
+        ent = (
+            (
+                await session.execute(
+                    select(PlanEntitlement).where(
+                        PlanEntitlement.plan_id == sub.plan_id,
+                        PlanEntitlement.key == metric,
+                        PlanEntitlement.window == window,
+                    )
+                )
+            )
+            .scalars()
+            .first()
+        )
+        if ent is None:
+            # no entitlement → unlimited
+            return
+        # compute current window start
+        now = datetime.now(tz=timezone.utc)
+        if window == "day":
+            period_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            granularity = "day"
+        elif window == "month":
+            period_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+            granularity = "month"  # we only aggregate per day, but future-proof
+        else:
+            period_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            granularity = "day"
+
+        used_row = (
+            (
+                await session.execute(
+                    select(UsageAggregate).where(
+                        UsageAggregate.tenant_id == tenant_id,
+                        UsageAggregate.metric == metric,
+                        UsageAggregate.granularity == granularity,  # v1 daily baseline
+                        UsageAggregate.period_start == period_start,
+                    )
+                )
+            )
+            .scalars()
+            .first()
+        )
+        used = int(used_row.total) if used_row else 0
+        limit_ = int(ent.limit_per_window)
+        if used >= limit_:
+            if soft:
+                # allow but signal overage via header later (TODO: add header hook)
+                return
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail=f"Quota exceeded for {metric} in {window} window",
+            )
+
+    return _dep
+
+
+QuotaDep = Annotated[None, Depends(require_quota)]
+
+__all__ = ["require_quota"]

svc_infra/billing/schemas.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Optional
+
+from pydantic import BaseModel, Field
+
+
+class UsageIn(BaseModel):
+    metric: str = Field(..., min_length=1, max_length=64)
+    amount: Annotated[
+        int, Field(ge=0, description="Non-negative amount for the metric")
+    ]
+    at: Optional[datetime] = Field(
+        default=None,
+        description="Event timestamp (UTC). Defaults to server time if omitted.",
+    )
+    idempotency_key: str = Field(..., min_length=1, max_length=128)
+    metadata: dict = Field(default_factory=dict)
+
+
+class UsageAckOut(BaseModel):
+    id: str
+    accepted: bool = True
+
+
+class UsageAggregateRow(BaseModel):
+    period_start: datetime
+    granularity: str
+    metric: str
+    total: int
+
+
+class UsageAggregatesOut(BaseModel):
+    items: list[UsageAggregateRow] = Field(default_factory=list)
+    next_cursor: Optional[str] = None

svc_infra/billing/service.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Optional
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .models import Invoice, InvoiceLine, UsageAggregate, UsageEvent
+
+ProviderSyncHook = Callable[[Invoice, list[InvoiceLine]], None]
+
+
+@dataclass
+class BillingService:
+    session: Session
+    tenant_id: str
+    provider_sync: Optional[ProviderSyncHook] = None
+
+    def record_usage(
+        self,
+        *,
+        metric: str,
+        amount: int,
+        at: datetime,
+        idempotency_key: str,
+        metadata: dict | None,
+    ) -> str:
+        # Ensure UTC
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+        evt = UsageEvent(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            metric=metric,
+            amount=amount,
+            at_ts=at,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata or {},
+        )
+        self.session.add(evt)
+        self.session.flush()
+        return evt.id
+
+    def aggregate_daily(self, *, metric: str, day_start: datetime) -> None:
+        # Compute [day_start, day_start+1d)
+        next_day = day_start.replace(
+            hour=0, minute=0, second=0, microsecond=0
+        ) + timedelta(days=1)
+        total = 0
+        rows = self.session.execute(
+            select(UsageEvent).where(
+                UsageEvent.tenant_id == self.tenant_id,
+                UsageEvent.metric == metric,
+                UsageEvent.at_ts >= day_start,
+                UsageEvent.at_ts < next_day,
+            )
+        ).scalars()
+        for r in rows:
+            total += int(r.amount)
+        # upsert aggregate
+        agg = self.session.execute(
+            select(UsageAggregate).where(
+                UsageAggregate.tenant_id == self.tenant_id,
+                UsageAggregate.metric == metric,
+                UsageAggregate.period_start == day_start,
+                UsageAggregate.granularity == "day",
+            )
+        ).scalar_one_or_none()
+        if agg:
+            agg.total = total
+        else:
+            self.session.add(
+                UsageAggregate(
+                    id=str(uuid.uuid4()),
+                    tenant_id=self.tenant_id,
+                    metric=metric,
+                    period_start=day_start,
+                    granularity="day",
+                    total=total,
+                )
+            )
+
+    def generate_monthly_invoice(
+        self, *, period_start: datetime, period_end: datetime, currency: str
+    ) -> str:
+        # Minimal: sum all daily aggregates and produce one line
+        total = 0
+        rows = self.session.execute(
+            select(UsageAggregate).where(
+                UsageAggregate.tenant_id == self.tenant_id,
+                UsageAggregate.period_start >= period_start,
+                UsageAggregate.period_start < period_end,
+                UsageAggregate.granularity == "day",
+            )
+        ).scalars()
+        for r in rows:
+            total += int(r.total)
+        inv = Invoice(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            period_start=period_start,
+            period_end=period_end,
+            status="created",
+            total_amount=total,
+            currency=currency,
+        )
+        self.session.add(inv)
+        self.session.flush()
+        line = InvoiceLine(
+            id=str(uuid.uuid4()),
+            invoice_id=inv.id,
+            price_id=None,
+            metric=None,
+            quantity=1,
+            amount=total,
+        )
+        self.session.add(line)
+        if self.provider_sync:
+            self.provider_sync(inv, [line])
+        return inv.id

svc_infra/bundled_docs/README.md

@@ -0,0 +1,5 @@
+# Bundled Docs
+
+This directory contains a minimal set of Markdown files that the `svc-infra docs` CLI can fall back to when the project running the CLI doesn't have a local `docs/` directory.
+
+You can add more topics here as needed; each `*.md` file becomes a topic named after its stem (e.g., `getting-started.md` -> `getting-started`).

svc_infra/bundled_docs/__init__.py

@@ -0,0 +1 @@
+# Bundled docs package for zip-safe importlib.resources access

svc_infra/bundled_docs/getting-started.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+Welcome to svc-infra docs. Use `svc-infra docs list` to see topics.
+
+- This content is bundled with the package.
+- If your project doesn't have a local `docs/` folder, you'll still see this.

svc_infra/cache/__init__.py

@@ -5,6 +5,11 @@ This module offers high-level decorators for read/write caching, cache invalidat
 and resource-based cache management.
 """
 
+from .add import add_cache
+
+# Cache instance access for object-oriented usage
+from .backend import get_cache
+
 # Core decorators - main public API
 from .decorators import cached  # alias for cache_read
 from .decorators import mutates  # alias for cache_write
@@ -32,4 +37,8 @@ __all__ = [
     # Resource-based caching
     "resource",
     "entity",
+    # Easy integration helper
+    "add_cache",
+    # Cache instance access
+    "get_cache",
 ]

svc_infra/cache/add.py

@@ -0,0 +1,170 @@
+"""Easy integration helper to wire the cache backend into an ASGI app lifecycle.
+
+Contract:
+- Idempotent: multiple calls are safe; startup/shutdown handlers are registered once.
+- Env-driven defaults: respects CACHE_URL/REDIS_URL, CACHE_PREFIX, CACHE_VERSION, APP_ENV.
+- Lifecycle: registers startup (init + readiness probe) and shutdown (graceful close).
+- Ergonomics: exposes the underlying cache instance at app.state.cache by default.
+
+This does not replace the per-function decorators (`cache_read`, `cache_write`) and
+does not alter existing direct APIs; it simply standardizes initialization and wiring.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Callable, Optional
+
+from svc_infra.cache.backend import DEFAULT_READINESS_TIMEOUT
+from svc_infra.cache.backend import get_cache as _get_cache
+from svc_infra.cache.backend import setup_cache as _setup_cache
+from svc_infra.cache.backend import shutdown_cache as _shutdown_cache
+from svc_infra.cache.backend import wait_ready as _wait_ready
+
+logger = logging.getLogger(__name__)
+
+
+def _instance() -> Any:
+    """Return the current cache instance.
+
+    This is a thin compatibility shim used by tests and older callers.
+    """
+
+    return _get_cache()
+
+
+def _derive_settings(
+    url: Optional[str], prefix: Optional[str], version: Optional[str]
+) -> tuple[str, str, str]:
+    """Derive cache settings from parameters or environment variables.
+
+    Precedence:
+      - explicit function arguments
+      - environment variables (CACHE_URL/REDIS_URL, CACHE_PREFIX, CACHE_VERSION)
+      - sensible defaults (mem://, "svc", "v1")
+    """
+
+    derived_url = url or os.getenv("CACHE_URL") or os.getenv("REDIS_URL") or "mem://"
+    derived_prefix = prefix or os.getenv("CACHE_PREFIX") or "svc"
+    derived_version = version or os.getenv("CACHE_VERSION") or "v1"
+    return derived_url, derived_prefix, derived_version
+
+
+def add_cache(
+    app: Any | None = None,
+    *,
+    url: str | None = None,
+    prefix: str | None = None,
+    version: str | None = None,
+    readiness_timeout: float | None = None,
+    expose_state: bool = True,
+    state_key: str = "cache",
+) -> Callable[[], None]:
+    """Wire cache initialization and lifecycle into the ASGI app.
+
+    If an app is provided, registers startup/shutdown handlers. Otherwise performs
+    immediate initialization (best-effort) without awaiting readiness.
+
+    Returns a no-op shutdown callable for API symmetry with other helpers.
+    """
+
+    # Compute effective settings
+    eff_url, eff_prefix, eff_version = _derive_settings(url, prefix, version)
+
+    # If no app provided, do a simple init and return
+    if app is None:
+        try:
+            _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+            logger.info(
+                "Cache initialized (no app wiring): backend=%s namespace=%s",
+                eff_url,
+                f"{eff_prefix}:{eff_version}",
+            )
+        except Exception:
+            logger.exception("Cache initialization failed (no app wiring)")
+        return lambda: None
+
+    # Idempotence: avoid duplicate wiring
+    try:
+        state = getattr(app, "state", None)
+        already = bool(getattr(state, "_svc_cache_wired", False))
+    except Exception:
+        state = None
+        already = False
+
+    if already:
+        logger.debug("add_cache: app already wired; skipping re-registration")
+        return lambda: None
+
+    # Define lifecycle handlers
+    async def _startup():
+        _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+        try:
+            await _wait_ready(timeout=readiness_timeout or DEFAULT_READINESS_TIMEOUT)
+        except Exception:
+            # Bubble up to fail fast on startup; tests and prod prefer visibility
+            logger.exception("Cache readiness probe failed during startup")
+            raise
+        # Expose cache instance for convenience
+        if expose_state and hasattr(app, "state"):
+            try:
+                setattr(app.state, state_key, _instance())
+            except Exception:
+                logger.debug(
+                    "Unable to expose cache instance on app.state", exc_info=True
+                )
+
+    async def _shutdown():
+        try:
+            await _shutdown_cache()
+        except Exception:
+            # Best-effort; shutdown should not crash the app
+            logger.debug("Cache shutdown encountered errors (ignored)", exc_info=True)
+
+    # Register event handlers when supported
+    register_ok = False
+    try:
+        if hasattr(app, "add_event_handler"):
+            app.add_event_handler("startup", _startup)
+            app.add_event_handler("shutdown", _shutdown)
+            register_ok = True
+    except Exception:
+        register_ok = False
+
+    if not register_ok:
+        # Fallback: attempt FastAPI/Starlette .on_event decorators dynamically
+        try:
+            on_event = getattr(app, "on_event", None)
+            if callable(on_event):
+                on_event("startup")(_startup)
+                on_event("shutdown")(_shutdown)
+                register_ok = True
+        except Exception:
+            register_ok = False
+
+    # Mark wired and expose state immediately if desired
+    if hasattr(app, "state"):
+        try:
+            setattr(app.state, "_svc_cache_wired", True)
+            if expose_state and not hasattr(app.state, state_key):
+                setattr(app.state, state_key, _instance())
+        except Exception:
+            pass
+
+    if register_ok:
+        logger.info(
+            "Cache wired: url=%s namespace=%s", eff_url, f"{eff_prefix}:{eff_version}"
+        )
+    else:
+        # If we cannot register handlers, at least initialize now
+        try:
+            _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+        except Exception:
+            logger.exception("Cache initialization failed (no event registration)")
+
+    # Return a simple shutdown handle for symmetry with other add_* helpers
+    return lambda: None
+
+
+__all__ = ["add_cache"]

svc_infra/cache/backend.py

@@ -80,9 +80,12 @@ def setup_cache(
         logger.info(f"Cache version updated to: {_current_version}")
 
     # Setup backend connection
+    # Newer cashews versions require an explicit settings_url; default to in-memory
+    # backend when no URL is provided so acceptance/unit tests work out of the box.
     try:
-        setup_awaitable = _cache.setup(url) if url else _cache.setup()
-        logger.info(f"Cache backend setup initiated with URL: {url or 'default'}")
+        settings_url = url or "mem://"
+        setup_awaitable = _cache.setup(settings_url)
+        logger.info(f"Cache backend setup initiated with URL: {settings_url}")
     except Exception as e:
         logger.error(f"Failed to setup cache backend: {e}")
         raise
@@ -115,9 +118,7 @@ async def wait_ready(timeout: float = DEFAULT_READINESS_TIMEOUT) -> None:
         retrieved_value = await _cache.get(probe_key)
 
         if retrieved_value != PROBE_VALUE:
-            error_msg = (
-                f"Cache readiness probe failed. Expected '{PROBE_VALUE}', got '{retrieved_value}'"
-            )
+            error_msg = f"Cache readiness probe failed. Expected '{PROBE_VALUE}', got '{retrieved_value}'"
             logger.error(error_msg)
             raise RuntimeError(error_msg)
 
@@ -144,7 +145,7 @@ async def shutdown_cache() -> None:
         logger.warning(f"Error during cache shutdown (ignored): {e}")
 
 
-def instance():
+def get_cache():
     """
     Get the underlying cashews cache instance.