svc-infra 0.1.630__py3-none-any.whl → 0.1.631__py3-none-any.whl

svc_infra/billing/jobs.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import inspect
 from datetime import datetime, timezone
 from typing import Any, Awaitable, Callable, Dict, Optional
 
@@ -123,6 +124,17 @@ def make_billing_job_handler(
       → emits topic 'billing.invoice.created'
     """
 
+    async def _maybe_commit(session: Any) -> None:
+        """Commit if the session exposes a commit method (await if coroutine).
+
+        This makes the handler resilient in tests/dev where a dummy session is used.
+        """
+        commit = getattr(session, "commit", None)
+        if callable(commit):
+            result = commit()
+            if inspect.isawaitable(result):
+                await result
+
     async def _handler(job: Job) -> None:
         name = job.name
         data: Dict[str, Any] = job.payload or {}
@@ -136,7 +148,7 @@ def make_billing_job_handler(
             async with session_factory() as session:
                 svc = AsyncBillingService(session=session, tenant_id=tenant_id)
                 total = await svc.aggregate_daily(metric=metric, day_start=day_start)
-                await session.commit()
+                await _maybe_commit(session)
             webhooks.publish(
                 "billing.usage_aggregated",
                 {
@@ -161,7 +173,7 @@ def make_billing_job_handler(
                 invoice_id = await svc.generate_monthly_invoice(
                     period_start=period_start, period_end=period_end, currency=currency
                 )
-                await session.commit()
+                await _maybe_commit(session)
             webhooks.publish(
                 "billing.invoice.created",
                 {

svc_infra/cache/__init__.py

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

svc_infra/cache/add.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+"""
+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.
+"""
+
+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 instance as _instance
+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 _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)  # type: ignore[misc]
+                on_event("shutdown")(_shutdown)  # type: ignore[misc]
+                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/docs/cache.md

@@ -16,3 +16,61 @@ async def get_user(user_id: int):
 
 - `CACHE_PREFIX`, `CACHE_VERSION` – change the namespace alias used by the decorators. 【F:src/svc_infra/cache/README.md†L20-L173】
 - `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG` – override canonical TTL buckets. 【F:src/svc_infra/cache/ttl.py†L26-L55】
+
+## Easy integration: add_cache
+
+Use the one-liner helper to wire cache initialization into your ASGI app lifecycle with sensible defaults. This doesn’t replace the decorators; it standardizes init/readiness/shutdown and exposes a handle for convenience.
+
+```python
+from fastapi import FastAPI
+from svc_infra.cache import add_cache, cache_read, cache_write, resource
+
+app = FastAPI()
+
+# Wires startup (init + readiness) and shutdown (graceful close). Idempotent.
+add_cache(app)
+
+user = resource("user", "user_id")
+
+@user.cache_read(suffix="profile", ttl=300)
+async def get_user_profile(user_id: int):
+    ...
+
+@user.cache_write()
+async def update_user_profile(user_id: int, payload):
+    ...
+
+# Optional: direct cache instance for advanced scenarios
+# available after startup when using add_cache(app)
+# app.state.cache -> cashews cache instance
+```
+
+### Env-driven defaults
+
+- URL: `CACHE_URL` → `REDIS_URL` → `mem://`
+- Prefix: `CACHE_PREFIX` (default `svc`)
+- Version: `CACHE_VERSION` (default `v1`)
+
+You can override explicitly:
+
+```python
+add_cache(app, url="redis://localhost:6379/0", prefix="myapp", version="v2")
+```
+
+### Behavior
+
+- Idempotent: multiple calls won’t duplicate handlers.
+- Startup/shutdown hooks: registered when supported by the app; startup performs a readiness probe. Startup is optional for correctness, but recommended for production reliability.
+- app.state exposure: by default, exposes `app.state.cache` to access the underlying cashews instance.
+
+### No-app usage
+
+If you’re not wiring an app (e.g., a script), you can initialize without startup hooks:
+
+```python
+from svc_infra.cache import add_cache
+
+shutdown = add_cache(None)  # immediate init (best-effort)
+# ... do work ...
+# call shutdown() is a no-op placeholder for symmetry
+```

{svc_infra-0.1.630.dist-info → svc_infra-0.1.631.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.630
+Version: 0.1.631
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.630.dist-info → svc_infra-0.1.631.dist-info}/RECORD

@@ -118,7 +118,7 @@ svc_infra/app/logging/formats.py,sha256=65eHUMWj7aD1RG7lCYIBSkFa_B748TutrZsta0OS
 svc_infra/app/root.py,sha256=344EWBMJCduwzJ1BBo0yGAu15TkryuvOW4qBZ6Gk-8w,1635
 svc_infra/billing/__init__.py,sha256=AdVxgBWibsz0xWk-Z91B7HecA-EhPMSRrXWIYPBgtMA,365
 svc_infra/billing/async_service.py,sha256=afJR3vqkKFm3pIrYURR0E3xUmnRcxIx2TWfeDlLV2js,4680
-svc_infra/billing/jobs.py,sha256=HY1bgGCZ3JYF_C5eu539S7_Vy3ifOnq3LvloET5NWcQ,8031
+svc_infra/billing/jobs.py,sha256=pS6f8pDIarR935rUzXJs6lWoPN5yElbiB_2R46BwX7U,8469
 svc_infra/billing/models.py,sha256=bnCGPKfnK__6x0f0bwKYQsG2GwXjJFi3YRXnq5JYs7c,6083
 svc_infra/billing/quotas.py,sha256=hreWT1ZI4f7uckAA19wlIC6JqgwBWJYrmaGsp0uqa1M,3469
 svc_infra/billing/schemas.py,sha256=fjONpVnI4s4lwlcY8EBr6qHCA5GQ7vRVrxObkoECQJ8,898
@@ -127,7 +127,8 @@ svc_infra/bundled_docs/README.md,sha256=FqTieL4ADODxTnig8yehV2KdHX9bASDega52bjp5
 svc_infra/bundled_docs/__init__.py,sha256=8_jF4fM-3Wf6j_mE4000_9AHcJ3tYZXO9hJY-pBEepM,63
 svc_infra/bundled_docs/getting-started.md,sha256=JaMOgRUK_ajaX4SCtiE3GrhQ81wMwng6y46t0032ftU,210
 svc_infra/cache/README.md,sha256=ZgIpmE0UVlGktp2nXUYv6FKJATCdkR_01v-GGxHN6Ao,10795
-svc_infra/cache/__init__.py,sha256=Fz3NS81jrY5sLikRhITCeHDT4MlOLcbMed5EjVecSAg,956
+svc_infra/cache/__init__.py,sha256=5hlTZNdV3DA4SUecAmTy2waAG5eTuNWhc9XCdPT85M4,1031
+svc_infra/cache/add.py,sha256=8JHkcXKj6CP8ioxb6RyR1gkM1hvHLbxjmpW-Kb1SO9k,5848
 svc_infra/cache/backend.py,sha256=-dbZ2qkhebzbKosQqgvBNb01A-2_jGt6_0WmJhPoHy8,4418
 svc_infra/cache/decorators.py,sha256=hsXTcdGo-Q1RKMrqQB0ROmFuce9A1JTt9sJAcWaHvMc,8330
 svc_infra/cache/demo.py,sha256=MX8LK-4Ju1xAxZtBh-p_Weh8yPNWmmPnDkOW5wAiGKI,2507
@@ -238,7 +239,7 @@ svc_infra/docs/adr/0010-timeouts-and-resource-limits.md,sha256=tpOTjncKJAjTsDN8j
 svc_infra/docs/api.md,sha256=AlPL9kBS6_dM0NrOteDQ9WqalSfKf_p9_zdy1CtGJdU,2384
 svc_infra/docs/auth.md,sha256=PRl9G4UW78cT_7c4koVh5NDlheNAr02CpJT2YFbEXto,1333
 svc_infra/docs/billing.md,sha256=MArKbKhzFwMLaOMABNDRtT_2D0zGgyFZ2r54o-99v68,7884
-svc_infra/docs/cache.md,sha256=XUsJ8p6QFBWTNuqata1HJjB6accdPANipdoNAkKirqs,673
+svc_infra/docs/cache.md,sha256=mwObz4F_9KwGO2ftcYSvWfieYekJs1dva3UzaIHFI64,2454
 svc_infra/docs/cli.md,sha256=w5og4SWrLyizlJAJiFgcWu2jDSc1Wj3NCYqzbbvg8VE,1702
 svc_infra/docs/contributing.md,sha256=a0PhmzCLFw8S3odxFbI3p5_FOiPMZLrxk15Ujrk7ao4,1175
 svc_infra/docs/data-lifecycle.md,sha256=_XFZCj9qiYgEiN9jO_lq7RcpVIeLVN7REaFziiNCnEI,2684
@@ -339,7 +340,7 @@ svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA
 svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
 svc_infra/webhooks/service.py,sha256=hh-rw0otc00vipZ998XaV5mHsk0IDGYqon0FnhaGr60,2229
 svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
-svc_infra-0.1.630.dist-info/METADATA,sha256=lr5YAY1xGvRrngGSPgH2cfCOLACfM-YFLAR21lCX_NY,8748
-svc_infra-0.1.630.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.630.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.630.dist-info/RECORD,,
+svc_infra-0.1.631.dist-info/METADATA,sha256=B-Klim62FKQqNr_a9lfHuJ3jsuWSf5HF032_SfiDDxM,8748
+svc_infra-0.1.631.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.631.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.631.dist-info/RECORD,,