svc-infra 0.1.630__tar.gz → 0.1.631__tar.gz

{svc_infra-0.1.630 → svc_infra-0.1.631}/PKG-INFO

@@ -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 → svc_infra-0.1.631}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.630"
+version = "0.1.631"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"

{svc_infra-0.1.630 → svc_infra-0.1.631}/src/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-0.1.630 → svc_infra-0.1.631}/src/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-0.1.631/src/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-0.1.631/src/svc_infra/docs/cache.md

@@ -0,0 +1,76 @@
+# Cache guide
+
+The cache module wraps [cashews](https://github.com/Krukov/cashews) with decorators and namespace helpers so services can centralize key formats.
+
+```python
+from svc_infra.cache import cache_read, cache_write, init_cache
+
+init_cache()  # uses CACHE_PREFIX / CACHE_VERSION
+
+@cache_read(key="user:{user_id}", ttl=300)
+async def get_user(user_id: int):
+    ...
+```
+
+### Environment
+
+- `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/src/svc_infra/docs/cache.md

@@ -1,18 +0,0 @@
-# Cache guide
-
-The cache module wraps [cashews](https://github.com/Krukov/cashews) with decorators and namespace helpers so services can centralize key formats.
-
-```python
-from svc_infra.cache import cache_read, cache_write, init_cache
-
-init_cache()  # uses CACHE_PREFIX / CACHE_VERSION
-
-@cache_read(key="user:{user_id}", ttl=300)
-async def get_user(user_id: int):
-    ...
-```
-
-### Environment
-
-- `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】