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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.630
+Version: 0.1.632
 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.632}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.630"
+version = "0.1.632"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"
@@ -123,6 +123,7 @@ python_classes = ["Test*",]
 python_functions = ["test_*"]
 markers = [
     "acceptance: End-to-end acceptance tests running against the acceptance app or BASE_URL",
+    "unit: Unit tests",
     "security: Security and auth hardening tests",
     "ratelimit: Rate limiting and abuse protection tests",
     "concurrency: Idempotency and concurrency control tests",

svc_infra-0.1.632/src/svc_infra/api/fastapi/admin/__init__.py

@@ -0,0 +1,3 @@
+from .add import add_admin, admin_router
+
+__all__ = ["add_admin", "admin_router"]

svc_infra-0.1.632/src/svc_infra/api/fastapi/admin/add.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import base64
+import hmac
+import inspect
+import json
+import logging
+import os
+import time
+from hashlib import sha256
+from types import SimpleNamespace
+from typing import Any, Callable, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+
+from ....app.env import get_current_environment
+from ....security.permissions import RequirePermission
+from ..auth.security import Identity, Principal, _current_principal
+from ..auth.state import get_auth_state
+from ..db.sql.session import SqlSessionDep
+from ..dual.protected import roles_router
+
+logger = logging.getLogger(__name__)
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64u_decode(s: str) -> bytes:
+    pad = "=" * ((4 - len(s) % 4) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def _sign(payload: dict, *, secret: str) -> str:
+    body = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    sig = hmac.new(secret.encode("utf-8"), body, sha256).digest()
+    return _b64u(body) + "." + _b64u(sig)
+
+
+def _verify(token: str, *, secret: str) -> dict:
+    try:
+        b64_body, b64_sig = token.split(".", 1)
+        body = _b64u_decode(b64_body)
+        exp_sig = _b64u_decode(b64_sig)
+        got_sig = hmac.new(secret.encode("utf-8"), body, sha256).digest()
+        if not hmac.compare_digest(exp_sig, got_sig):
+            raise ValueError("bad_signature")
+        payload = json.loads(body)
+        if int(payload.get("exp", 0)) < int(time.time()):
+            raise ValueError("expired")
+        return payload
+    except Exception as e:
+        raise ValueError("invalid_token") from e
+
+
+def admin_router(*, dependencies: Optional[list[Any]] = None, **kwargs) -> APIRouter:
+    """Role-gated admin router for coarse access control.
+
+    Use permission guards inside endpoints for fine-grained control.
+    """
+
+    return roles_router("admin", **kwargs)
+
+
+def add_admin(
+    app,
+    *,
+    base_path: str = "/admin",
+    enable_impersonation: bool = True,
+    secret: Optional[str] = None,
+    ttl_seconds: int = 15 * 60,
+    cookie_name: str = "impersonation",
+    impersonation_user_getter: Optional[Callable[[Any, str], Any]] = None,
+) -> None:
+    """Wire admin surfaces with sensible defaults.
+
+    - Mounts an admin router under base_path.
+    - Optionally enables impersonation start/stop endpoints guarded by permissions.
+    - Registers a dependency override to honor impersonation cookie globally (idempotent).
+
+    impersonation_user_getter: optional callable (request, user_id) -> user object.
+      If omitted, defaults to loading from SQLAlchemy User model returned by get_auth_state().
+    """
+
+    # Idempotency: only mount once per app instance
+    if getattr(app.state, "_admin_added", False):
+        return
+
+    env = get_current_environment()
+    _secret = (
+        secret or os.getenv("ADMIN_IMPERSONATION_SECRET") or os.getenv("APP_SECRET") or "dev-secret"
+    )
+    _ttl = int(os.getenv("ADMIN_IMPERSONATION_TTL", str(ttl_seconds)))
+    _cookie = os.getenv("ADMIN_IMPERSONATION_COOKIE", cookie_name)
+
+    r = admin_router(prefix=base_path, tags=["admin"])  # role-gated
+
+    async def _default_user_getter(request: Request, user_id: str, session: SqlSessionDep):
+        try:
+            UserModel, _, _ = get_auth_state()
+        except Exception:
+            # Fallback: simple shim if auth state not configured
+            return SimpleNamespace(id=user_id)
+        obj = await session.get(UserModel, user_id)
+        if not obj:
+            raise HTTPException(404, "user_not_found")
+        return obj
+
+    user_getter = impersonation_user_getter
+
+    @r.post(
+        "/impersonate/start", status_code=204, dependencies=[RequirePermission("admin.impersonate")]
+    )
+    async def start_impersonation(
+        body: dict, request: Request, response: Response, session: SqlSessionDep, identity: Identity
+    ):
+        target_id = (body or {}).get("user_id")
+        reason = (body or {}).get("reason", "")
+        if not target_id:
+            raise HTTPException(422, "user_id_required")
+        # Load target for validation (custom getter or default)
+        _res = (
+            user_getter(request, target_id)
+            if user_getter
+            else _default_user_getter(request, target_id, session)
+        )
+        target = await _res if inspect.isawaitable(_res) else _res
+        actor: Principal = identity
+        payload = {
+            "actor_id": getattr(getattr(actor, "user", None), "id", None),
+            "target_id": str(getattr(target, "id", target_id)),
+            "iat": int(time.time()),
+            "exp": int(time.time()) + _ttl,
+            "nonce": _b64u(os.urandom(8)),
+        }
+        token = _sign(payload, secret=_secret)
+        response.set_cookie(
+            key=_cookie,
+            value=token,
+            httponly=True,
+            samesite="lax",
+            secure=(env in ("prod", "production")),
+            path="/",
+            max_age=_ttl,
+        )
+        logger.info(
+            "admin.impersonation.started",
+            extra={
+                "actor_id": payload["actor_id"],
+                "target_id": payload["target_id"],
+                "reason": reason,
+                "expires_in": _ttl,
+            },
+        )
+        # Re-compose override now to wrap any late overrides set by tests/harness
+        try:
+            _compose_override()
+        except Exception:
+            pass
+
+    @r.post("/impersonate/stop", status_code=204)
+    async def stop_impersonation(response: Response):
+        response.delete_cookie(_cookie, path="/")
+        logger.info("admin.impersonation.stopped")
+
+    app.include_router(r)
+
+    # Dependency override: wrap the base principal to honor impersonation cookie.
+    # Compose with any existing override (e.g., acceptance app/test harness) and
+    # re-compose at startup to capture late overrides.
+    def _compose_override():
+        existing = app.dependency_overrides.get(_current_principal)
+        if existing and getattr(existing, "_is_admin_impersonation_override", False):
+            dep_provider = getattr(existing, "_admin_impersonation_base", _current_principal)
+        else:
+            dep_provider = existing or _current_principal
+
+        async def _override_current_principal(
+            base: Principal = Depends(dep_provider),
+            request: Request = None,
+            session: SqlSessionDep = None,
+        ) -> Principal:
+            token = request.cookies.get(_cookie) if request else None
+            if not token:
+                return base
+            try:
+                payload = _verify(token, secret=_secret)
+            except Exception:
+                return base
+            # Load target user
+            target_id = payload.get("target_id")
+            if not target_id:
+                return base
+            # Preserve actor roles/claims so permissions remain that of the actor
+            actor_user = getattr(base, "user", None)
+            actor_roles = getattr(actor_user, "roles", []) or []
+            _res = (
+                user_getter(request, target_id)
+                if user_getter
+                else _default_user_getter(request, target_id, session)
+            )
+            target = await _res if inspect.isawaitable(_res) else _res
+            # Swap user but keep actor for audit if needed
+            setattr(base, "actor", getattr(base, "user", None))
+            # If target lacks roles, inherit actor roles to maintain permission checks
+            try:
+                if not getattr(target, "roles", None):
+                    setattr(target, "roles", actor_roles)
+            except Exception:
+                # Best-effort; if target object is immutable, fallback by wrapping
+                target = SimpleNamespace(id=getattr(target, "id", target_id), roles=actor_roles)
+            base.user = target
+            base.via = "impersonated"
+            return base
+
+        app.dependency_overrides[_current_principal] = _override_current_principal
+        _override_current_principal._is_admin_impersonation_override = True  # type: ignore[attr-defined]
+        _override_current_principal._admin_impersonation_base = dep_provider  # type: ignore[attr-defined]
+
+    # Compose now (best-effort) and again on startup to wrap any later overrides
+    _compose_override()
+    try:
+        app.add_event_handler("startup", _compose_override)
+    except Exception:
+        # Best-effort; if app doesn't support event handlers, we already composed once
+        pass
+    app.state._admin_added = True
+
+
+# no extra helpers

{svc_infra-0.1.630 → svc_infra-0.1.632}/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.632}/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.632/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.632/src/svc_infra/docs/adr/0011-admin-scope-and-impersonation.md

@@ -0,0 +1,73 @@
+# 0011 — Admin scope, permissions, and impersonation
+
+## Context
+- The codebase already provides RBAC/permission helpers: `RequireRoles`, `RequirePermission`, ABAC via `RequireABAC`/`owns_resource`.
+- The central permission registry maps roles → permissions (`svc_infra.security.permissions.PERMISSION_REGISTRY`). Notably, the `admin` role includes: `user.read`, `user.write`, `billing.read`, `billing.write`, and `security.session.{list,revoke}`.
+- Acceptance tests demonstrate an “admin-only” route guarded by `RequirePermission("user.write")` and temporary role override to `admin`.
+- There is no dedicated admin API surface yet, and no impersonation flow; observability docs mention an optional route classifier that can label routes like `public|internal|admin`.
+
+## Goals
+- Define a consistent approach for admin-only surfaces and permission alignment.
+- Establish minimal permissions needed for admin operations, including impersonation.
+- Outline an impersonation flow with security and audit guardrails.
+- Prepare for an easy integration helper (`add_admin`) without implementing it yet.
+
+## Non-goals
+- Implement admin endpoints or impersonation logic in this ADR.
+- Replace existing permissions/guards — this ADR aligns and extends them.
+
+## Decisions
+
+1) Permissions alignment and additions
+- Keep permissions as the canonical guard unit; roles remain a mapping to permissions.
+- Extend the registry with a dedicated permission for impersonation:
+  - `admin.impersonate`
+- Keep existing entries (`security.session.{list,revoke}` etc.) as-is.
+- Recommended role → permission mapping updates:
+  - `admin`: add `admin.impersonate` (retains existing permissions).
+  - `auditor`: keep `audit.read` (already present) and may expand in the future.
+
+2) Admin router pattern
+- Provide an admin-only router pattern that layers role and permission checks consistently:
+  - Top-level: role gate via `RequireRoles("admin")` to reflect the “admin area”.
+  - Endpoint-level: permission gates via `RequirePermission(...)` for specific operations.
+- Rationale: roles communicate the coarse-grained area; fine-grained actions are enforced by permissions.
+- A future helper `admin_router()` can wrap `roles_router("admin")` (from `api.fastapi.dual.protected`) for ergonomic mounting.
+
+3) Impersonation flow (design)
+- Endpoints:
+  - `POST /admin/impersonate/start` — body: `{ user_id, reason }`; requires `admin.impersonate`.
+  - `POST /admin/impersonate/stop` — ends the session.
+- Mechanics:
+  - When starting, issue a short-lived, signed impersonation token (or set a dedicated cookie) that encodes: original admin principal id, target user id, issued-at, expires-at, and nonce.
+  - Downstream identity resolution should reflect the impersonated user for request handling, while preserving the original admin as the "actor" for auditing.
+  - Stopping invalidates the token/cookie (server-side revocation list or versioned secret), and subsequent requests fall back to the admin’s own identity.
+- Safety guardrails:
+  - Always require `admin.impersonate`.
+  - Enforce explicit `reason` and capture request fingerprint (ip hash, user-agent) with the event.
+  - Limit scope by tenant/org if applicable; optionally block actions explicitly marked non-impersonable.
+  - Set short TTL (e.g., 15 minutes) with sliding refresh disabled.
+
+4) Audit logging
+- Emit structured audit events for impersonation lifecycle:
+  - `admin.impersonation.started` with actor, target, reason, ip hash, user-agent, and expiry.
+  - `admin.impersonation.stopped` with actor, target, and termination reason (expired/manual).
+- Implementation options (future):
+  - Minimal: log via the existing logging setup (structured logger, e.g., `logger.bind(...).info("audit", ...)`).
+  - Preferred: emit to an audit outbox/table or webhook channel for retention and cross-system visibility.
+
+5) Observability and route classification
+- Encourage passing a `route_classifier` that labels admin routes as `admin` (e.g., for `/admin` base path) so metrics/SLO dashboards can split traffic into `public|internal|admin` classes.
+
+## Consequences
+- Clear, documented permissions and flow for admin-only features.
+- Minimal surface to add later: `admin_router()` and `add_admin(app, ...)` helper that mounts admin routes and wires impersonation endpoints + audit hooks.
+- Tests to plan when implementing:
+  - Role vs permission gating behavior on /admin routes.
+  - Impersonation start/stop lifecycle and audit emission.
+  - Ownership checks that permit admin bypass where intended (e.g., session revocation).
+
+## Follow-ups
+- Update the permission registry to include `admin.impersonate` (and map into `admin`).
+- Implement `admin_router()` and the `add_admin` helper following this ADR.
+- Add admin acceptance tests and documentation for guardrails and operational guidance.

svc_infra-0.1.632/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 → svc_infra-0.1.632}/src/svc_infra/security/permissions.py

@@ -16,6 +16,7 @@ PERMISSION_REGISTRY: Dict[str, Set[str]] = {
         "billing.write",
         "security.session.revoke",
         "security.session.list",
+        "admin.impersonate",
     },
     "support": {"user.read", "billing.read"},
     "auditor": {"user.read", "billing.read", "audit.read"},

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】