identity-plan-kit 0.2.6__tar.gz → 0.2.7__tar.gz

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: identity-plan-kit
-Version: 0.2.6
+Version: 0.2.7
 Summary: Modern FastAPI library for authentication, RBAC, subscription plans, and usage tracking
 Author-email: harut <harut.avetisyan2002@gmail.com>
 License: MIT

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "identity-plan-kit"
-version = "0.2.6"
+version = "0.2.7"
 description = "Modern FastAPI library for authentication, RBAC, subscription plans, and usage tracking"
 readme = "README.md"
 authors = [
@@ -140,7 +140,7 @@ testpaths = ["tests"]
 addopts = "-v --tb=short"
 
 [tool.bumpversion]
-current_version = "0.2.6"
+current_version = "0.2.7"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 tag = true

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/src/identity_plan_kit/auth/dependencies.py

@@ -1,6 +1,7 @@
 """Auth FastAPI dependencies."""
 
-from typing import Annotated
+from collections.abc import Callable, Coroutine
+from typing import Annotated, Any
 
 from fastapi import Cookie, Depends, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
@@ -21,6 +22,84 @@ logger = get_logger(__name__)
 bearer_scheme = HTTPBearer(auto_error=False)
 
 
+def current_user(
+    include_role: bool = True,
+) -> Callable[..., Coroutine[Any, Any, User]]:
+    """
+    Create a parameterized current user dependency.
+
+    Use this when you need to control whether role is loaded:
+
+    Example::
+
+        # Skip role loading for better performance
+        @router.get("/generate")
+        async def generate(
+            user: Annotated[User, Depends(current_user(include_role=False))],
+        ):
+            ...
+
+    Args:
+        include_role: If True, eagerly load the user's role (default: True).
+            Set to False to skip the role query when role info is not needed.
+
+    Returns:
+        FastAPI dependency function
+    """
+
+    async def _get_user(
+        request: Request,
+        credentials: Annotated[
+            HTTPAuthorizationCredentials | None,
+            Depends(bearer_scheme),
+        ] = None,
+        access_token: Annotated[str | None, Cookie(alias="access_token")] = None,
+    ) -> User:
+        token: str | None = None
+        if credentials:
+            token = credentials.credentials
+        elif access_token:
+            token = access_token
+
+        if not token:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Not authenticated",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        kit = request.app.state.identity_plan_kit
+        auth_service = kit.auth_service
+
+        try:
+            return await auth_service.get_user_from_token(token, include_role=include_role)
+        except TokenExpiredError:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Token has expired",
+                headers={"WWW-Authenticate": "Bearer"},
+            ) from None
+        except (TokenInvalidError, AuthError):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token",
+                headers={"WWW-Authenticate": "Bearer"},
+            ) from None
+        except UserNotFoundError:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found",
+                headers={"WWW-Authenticate": "Bearer"},
+            ) from None
+        except UserInactiveError:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="User account is inactive",
+            ) from None
+
+    return _get_user
+
+
 async def get_current_user(
     request: Request,
     credentials: Annotated[
@@ -137,3 +216,7 @@ async def get_optional_user(
 # Type aliases for dependency injection
 CurrentUser = Annotated[User, Depends(get_current_user)]
 OptionalUser = Annotated[User | None, Depends(get_optional_user)]
+
+# Optimized variant that skips role loading (saves 1 DB query)
+# Use when role info is not needed for the endpoint
+CurrentUserNoRole = Annotated[User, Depends(current_user(include_role=False))]

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/src/identity_plan_kit/auth/repositories/user_repo.py

@@ -26,6 +26,7 @@ class UserRepository:
         self,
         user_id: UUID,
         for_update: bool = False,
+        include_role: bool = True,
     ) -> User | None:
         """
         Get user by ID.
@@ -34,13 +35,16 @@ class UserRepository:
             user_id: User UUID
             for_update: If True, lock the row for update (prevents race conditions
                 in operations that depend on current user state like is_active)
+            include_role: If True, eagerly load the user's role (default: True).
+                Set to False to skip the role query when role info is not needed.
 
         Returns:
             User entity or None if not found
         """
-        stmt = (
-            select(UserModel).options(selectinload(UserModel.role)).where(UserModel.id == user_id)
-        )
+        stmt = select(UserModel).where(UserModel.id == user_id)
+
+        if include_role:
+            stmt = stmt.options(selectinload(UserModel.role))
 
         if for_update:
             stmt = stmt.with_for_update()
@@ -57,6 +61,7 @@ class UserRepository:
         self,
         email: str,
         for_update: bool = False,
+        include_role: bool = True,
     ) -> User | None:
         """
         Get user by email address.
@@ -64,13 +69,16 @@ class UserRepository:
         Args:
             email: User email
             for_update: If True, lock the row for update
+            include_role: If True, eagerly load the user's role (default: True).
+                Set to False to skip the role query when role info is not needed.
 
         Returns:
             User entity or None if not found
         """
-        stmt = (
-            select(UserModel).options(selectinload(UserModel.role)).where(UserModel.email == email)
-        )
+        stmt = select(UserModel).where(UserModel.email == email)
+
+        if include_role:
+            stmt = stmt.options(selectinload(UserModel.role))
 
         if for_update:
             stmt = stmt.with_for_update()

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/src/identity_plan_kit/auth/services/auth_service.py

@@ -98,12 +98,19 @@ class AuthService:
         """Get Google OAuth service."""
         return self._google_oauth
 
-    async def get_user_from_token(self, token: str) -> User:
+    async def get_user_from_token(
+        self,
+        token: str,
+        include_role: bool = True,
+    ) -> User:
         """
         Get user from access token.
 
         Args:
             token: JWT access token
+            include_role: If True, eagerly load the user's role (default: True).
+                Set to False to skip the role query when role info is not needed,
+                reducing database queries for better performance.
 
         Returns:
             User entity
@@ -134,7 +141,7 @@ class AuthService:
             raise TokenInvalidError("Missing user ID in token")
 
         async with self._create_uow() as uow:
-            user = await uow.users.get_by_id(UUID(user_id))
+            user = await uow.users.get_by_id(UUID(user_id), include_role=include_role)
 
             if user is None:
                 raise UserNotFoundError()

identity_plan_kit-0.2.7/src/identity_plan_kit/plans/cache/user_plan_cache.py

@@ -0,0 +1,205 @@
+"""User plan cache for fast user plan lookups."""
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from identity_plan_kit.plans.domain.entities import Plan, UserPlan
+from identity_plan_kit.shared.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class UserPlanCacheEntry:
+    """Cache entry for user plan with expiration."""
+
+    user_plan: UserPlan
+    plan: Plan
+    expires_at: datetime
+    fetched_at: float = field(default_factory=time.monotonic)
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if entry has expired."""
+        return datetime.now(UTC) > self.expires_at
+
+
+class UserPlanCache:
+    """
+    In-memory user plan cache.
+
+    Caches user plan assignments (by user_id) to reduce database queries.
+    User plans change less frequently than usage, so caching provides
+    significant benefit for quota check operations.
+
+    Cache key: user_id (UUID)
+    Cache value: (UserPlan, Plan) tuple with full plan details
+
+    **Invalidation:**
+
+    Call invalidate() when:
+    - User's plan is assigned/changed
+    - User's plan is cancelled
+    - User's plan is extended
+    - User's custom limits are updated
+
+    **TTL:**
+
+    Default TTL is 5 minutes. This balances:
+    - Reducing database load (cache hits avoid 2-4 queries)
+    - Ensuring plan changes propagate within reasonable time
+    - Memory usage (entries expire and get cleaned up)
+    """
+
+    def __init__(self, ttl_seconds: int = 300) -> None:
+        """
+        Initialize user plan cache.
+
+        Args:
+            ttl_seconds: Cache TTL in seconds (default: 5 minutes, 0 to disable)
+        """
+        self._ttl = timedelta(seconds=ttl_seconds)
+        self._cache: dict[UUID, UserPlanCacheEntry] = {}
+        self._write_lock = asyncio.Lock()
+        self._enabled = ttl_seconds > 0
+        self._invalidated_at: dict[UUID, float] = {}
+        self._global_invalidated_at: float = 0.0
+
+    async def get(self, user_id: UUID) -> tuple[UserPlan, Plan] | None:
+        """
+        Get cached user plan by user ID.
+
+        Args:
+            user_id: User UUID
+
+        Returns:
+            Tuple of (UserPlan, Plan) or None if not cached/expired
+        """
+        if not self._enabled:
+            return None
+
+        entry = self._cache.get(user_id)
+
+        if entry is None:
+            return None
+
+        if entry.is_expired:
+            return None
+
+        return entry.user_plan, entry.plan
+
+    def get_fetch_timestamp(self) -> float:
+        """
+        Get a monotonic timestamp to associate with a DB fetch.
+
+        Call this BEFORE fetching from the database, then pass the timestamp
+        to set() to enable stale write prevention.
+
+        Returns:
+            Monotonic timestamp
+        """
+        return time.monotonic()
+
+    async def set(
+        self,
+        user_id: UUID,
+        user_plan: UserPlan,
+        plan: Plan,
+        fetched_at: float | None = None,
+    ) -> bool:
+        """
+        Cache user plan by user ID.
+
+        Args:
+            user_id: User UUID
+            user_plan: UserPlan entity to cache
+            plan: Plan entity with full details (permissions, limits)
+            fetched_at: Monotonic timestamp when data was fetched from DB
+
+        Returns:
+            True if the entry was cached, False if rejected as stale
+        """
+        if not self._enabled:
+            return False
+
+        if fetched_at is not None:
+            if fetched_at < self._global_invalidated_at:
+                logger.debug(
+                    "user_plan_cache_stale_write_rejected",
+                    user_id=str(user_id),
+                    reason="global_invalidation",
+                )
+                return False
+
+            key_invalidated_at = self._invalidated_at.get(user_id, 0.0)
+            if fetched_at < key_invalidated_at:
+                logger.debug(
+                    "user_plan_cache_stale_write_rejected",
+                    user_id=str(user_id),
+                    reason="key_invalidation",
+                )
+                return False
+
+        entry = UserPlanCacheEntry(
+            user_plan=user_plan,
+            plan=plan,
+            expires_at=datetime.now(UTC) + self._ttl,
+            fetched_at=fetched_at or time.monotonic(),
+        )
+        self._cache[user_id] = entry
+        return True
+
+    async def invalidate(self, user_id: UUID) -> None:
+        """
+        Invalidate cached user plan by user ID.
+
+        Call this when a user's plan changes (assigned, cancelled, extended, etc.).
+
+        Args:
+            user_id: User UUID to invalidate
+        """
+        self._invalidated_at[user_id] = time.monotonic()
+        self._cache.pop(user_id, None)
+        logger.debug("user_plan_cache_invalidated", user_id=str(user_id))
+
+    async def invalidate_all(self) -> None:
+        """
+        Invalidate all cached user plans.
+
+        Call this when plans are modified globally.
+        """
+        async with self._write_lock:
+            self._global_invalidated_at = time.monotonic()
+            self._cache.clear()
+            self._invalidated_at.clear()
+            logger.info("user_plan_cache_cleared")
+
+    async def cleanup_expired(self) -> int:
+        """
+        Remove expired entries from cache.
+
+        Returns:
+            Number of entries removed
+        """
+        async with self._write_lock:
+            expired_keys = [
+                key for key, entry in self._cache.items() if entry.is_expired
+            ]
+            for key in expired_keys:
+                del self._cache[key]
+
+            if expired_keys:
+                logger.debug(
+                    "user_plan_cache_cleanup",
+                    removed_count=len(expired_keys),
+                )
+
+            return len(expired_keys)
+
+    @property
+    def size(self) -> int:
+        """Get current cache size."""
+        return len(self._cache)

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/src/identity_plan_kit/plans/services/plan_service.py

@@ -9,6 +9,7 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from identity_plan_kit.config import IdentityPlanKitConfig
 from identity_plan_kit.plans.cache.plan_cache import PlanCache
+from identity_plan_kit.plans.cache.user_plan_cache import UserPlanCache
 from identity_plan_kit.plans.domain.entities import Feature, Plan, UserPlan
 from identity_plan_kit.plans.domain.exceptions import (
     FeatureNotAvailableError,
@@ -88,12 +89,14 @@ class PlanService:
         config: IdentityPlanKitConfig,
         session_factory: async_sessionmaker[AsyncSession],
         plan_cache_ttl_seconds: int = DEFAULT_PLAN_CACHE_TTL_SECONDS,
+        user_plan_cache_ttl_seconds: int = DEFAULT_PLAN_CACHE_TTL_SECONDS,
         state_store_manager: StateStoreManager | None = None,
         authorization_callback: AuthorizationCallback | None = None,
     ) -> None:
         self._config = config
         self._session_factory = session_factory
         self._plan_cache = PlanCache(ttl_seconds=plan_cache_ttl_seconds)
+        self._user_plan_cache = UserPlanCache(ttl_seconds=user_plan_cache_ttl_seconds)
         self._state_store_manager = state_store_manager
         self._authorization_callback = authorization_callback
 
@@ -234,12 +237,29 @@ class PlanService:
             Database errors and other infrastructure failures will propagate.
         """
         try:
+            # Check user plan cache first
+            cached_user_plan = await self._user_plan_cache.get(user_id)
+            if cached_user_plan is not None:
+                _user_plan, plan = cached_user_plan
+                limit = plan.get_feature_limit(feature_code)
+                return limit is not None
+
             async with self._create_uow(session=session) as uow:
-                user_plan = await uow.plans.get_user_active_plan(user_id)
-                if user_plan is None:
+                # Fetch from database and cache
+                fetch_ts = self._user_plan_cache.get_fetch_timestamp()
+                result = await uow.plans.get_user_active_plan_with_details(user_id)
+                if result is None:
                     return False
 
-                limit = await uow.plans.get_plan_limit(user_plan.plan_id, feature_code)
+                user_plan, plan = result
+
+                # Cache the result
+                await self._user_plan_cache.set(
+                    user_id, user_plan, plan, fetched_at=fetch_ts
+                )
+
+                # Extract limit from already-loaded plan (no extra query needed)
+                limit = plan.get_feature_limit(feature_code)
                 return limit is not None
 
         except (UserPlanNotFoundError, FeatureNotAvailableError):
@@ -347,17 +367,41 @@ class PlanService:
                     exc_info=True,
                 )
 
+        # Check user plan cache first
+        cached_user_plan = await self._user_plan_cache.get(user_id)
+        user_plan: UserPlan | None = None
+        plan: Plan | None = None
+
+        if cached_user_plan is not None:
+            user_plan, plan = cached_user_plan
+            logger.debug(
+                "user_plan_cache_hit",
+                user_id=str(user_id),
+                plan_code=user_plan.plan_code,
+            )
+
         async with self._create_uow(session=session) as uow:
-            # Get user's active plan
-            user_plan = await uow.plans.get_user_active_plan(user_id)
-            if user_plan is None:
-                raise UserPlanNotFoundError()
+            # If not in cache, fetch from database
+            if user_plan is None or plan is None:
+                fetch_ts = self._user_plan_cache.get_fetch_timestamp()
+                result = await uow.plans.get_user_active_plan_with_details(user_id)
+                if result is None:
+                    raise UserPlanNotFoundError()
+
+                user_plan, plan = result
+
+                # Cache the result
+                await self._user_plan_cache.set(
+                    user_id, user_plan, plan, fetched_at=fetch_ts
+                )
 
             if user_plan.is_expired:
+                # Invalidate cache for expired plans
+                await self._user_plan_cache.invalidate(user_id)
                 raise PlanExpiredError()
 
-            # Get feature limit
-            limit = await uow.plans.get_plan_limit(user_plan.plan_id, feature_code)
+            # Extract limit from already-loaded plan (no extra query needed)
+            limit = plan.get_feature_limit(feature_code)
             if limit is None:
                 raise FeatureNotAvailableError(feature_code, user_plan.plan_code)
 
@@ -464,12 +508,31 @@ class PlanService:
         Returns:
             UsageInfo with current usage
         """
+        # Check user plan cache first
+        cached_user_plan = await self._user_plan_cache.get(user_id)
+        user_plan: UserPlan | None = None
+        plan: Plan | None = None
+
+        if cached_user_plan is not None:
+            user_plan, plan = cached_user_plan
+
         async with self._create_uow() as uow:
-            user_plan = await uow.plans.get_user_active_plan(user_id)
-            if user_plan is None:
-                raise UserPlanNotFoundError()
+            # If not in cache, fetch from database
+            if user_plan is None or plan is None:
+                fetch_ts = self._user_plan_cache.get_fetch_timestamp()
+                result = await uow.plans.get_user_active_plan_with_details(user_id)
+                if result is None:
+                    raise UserPlanNotFoundError()
+
+                user_plan, plan = result
+
+                # Cache the result
+                await self._user_plan_cache.set(
+                    user_id, user_plan, plan, fetched_at=fetch_ts
+                )
 
-            limit = await uow.plans.get_plan_limit(user_plan.plan_id, feature_code)
+            # Extract limit from already-loaded plan (no extra query needed)
+            limit = plan.get_feature_limit(feature_code)
             if limit is None:
                 raise FeatureNotAvailableError(feature_code, user_plan.plan_code)
 
@@ -666,6 +729,9 @@ class PlanService:
                 custom_limits=custom_limits,
             )
 
+            # Invalidate user plan cache
+            await self._user_plan_cache.invalidate(user_id)
+
             logger.info(
                 "plan_assigned",
                 user_id=str(user_id),
@@ -726,6 +792,9 @@ class PlanService:
             result = await uow.plans.cancel_user_plan(user_id, immediate=immediate)
 
             if result:
+                # Invalidate user plan cache
+                await self._user_plan_cache.invalidate(user_id)
+
                 logger.info(
                     "plan_cancelled",
                     user_id=str(user_id),
@@ -795,6 +864,9 @@ class PlanService:
             if updated_plan is None:
                 raise UserPlanNotFoundError()
 
+            # Invalidate user plan cache
+            await self._user_plan_cache.invalidate(user_id)
+
             logger.info(
                 "plan_extended",
                 user_id=str(user_id),
@@ -877,6 +949,9 @@ class PlanService:
             if updated_plan is None:
                 raise UserPlanNotFoundError()
 
+            # Invalidate user plan cache
+            await self._user_plan_cache.invalidate(user_id)
+
             logger.info(
                 "plan_limits_updated",
                 user_id=str(user_id),
@@ -1041,6 +1116,26 @@ class PlanService:
         """
         await self._plan_cache.invalidate_all()
 
+    async def invalidate_user_plan_cache(self, user_id: UUID) -> None:
+        """
+        Invalidate cached user plan by user ID.
+
+        Call this when a user's plan assignment changes.
+
+        Args:
+            user_id: User UUID to invalidate
+        """
+        await self._user_plan_cache.invalidate(user_id)
+        logger.debug("user_plan_cache_invalidated", user_id=str(user_id))
+
+    async def invalidate_all_user_plan_cache(self) -> None:
+        """
+        Invalidate all cached user plans.
+
+        Call this when plans are modified globally (e.g., plan limits change).
+        """
+        await self._user_plan_cache.invalidate_all()
+
     # =========================================================================
     # Plan Listing Methods (for public display)
     # =========================================================================

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.7}/uv.lock

@@ -962,7 +962,7 @@ wheels = [
 
 [[package]]
 name = "identity-plan-kit"
-version = "0.2.5"
+version = "0.2.6"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },