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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: identity-plan-kit
-Version: 0.2.6
+Version: 0.2.8
 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.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "identity-plan-kit"
-version = "0.2.6"
+version = "0.2.8"
 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.8"
 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.8}/src/identity_plan_kit/auth/__init__.py

@@ -5,8 +5,14 @@ from identity_plan_kit.auth.domain.entities import RefreshToken, User, UserProvi
 from identity_plan_kit.auth.domain.exceptions import (
     AuthError,
     InvalidCredentialsError,
+    OAuthError,
     PasswordValidationError,
+    ProviderNotConfiguredError,
+    RefreshTokenExpiredError,
+    RefreshTokenInvalidError,
+    RefreshTokenMissingError,
     TokenExpiredError,
+    TokenInvalidError,
     UserInactiveError,
     UserNotFoundError,
 )
@@ -22,12 +28,18 @@ __all__ = [
     # Dependencies
     "CurrentUser",
     "InvalidCredentialsError",
+    "OAuthError",
     "OptionalUser",
     "PasswordValidationError",
+    "ProviderNotConfiguredError",
     "RefreshToken",
+    "RefreshTokenExpiredError",
+    "RefreshTokenInvalidError",
+    "RefreshTokenMissingError",
     # Repositories (for direct use with external sessions)
     "RefreshTokenRepository",
     "TokenExpiredError",
+    "TokenInvalidError",
     # Entities
     "User",
     "UserInactiveError",

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.8}/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.8}/src/identity_plan_kit/auth/domain/exceptions.py

@@ -35,6 +35,27 @@ class TokenInvalidError(AuthError):
     message = "Invalid token"
 
 
+class RefreshTokenMissingError(AuthError):
+    """Refresh token not provided."""
+
+    code = "REFRESH_TOKEN_MISSING"
+    message = "Refresh token not provided"
+
+
+class RefreshTokenInvalidError(AuthError):
+    """Refresh token is invalid."""
+
+    code = "REFRESH_TOKEN_INVALID"
+    message = "Invalid refresh token"
+
+
+class RefreshTokenExpiredError(AuthError):
+    """Refresh token has expired."""
+
+    code = "REFRESH_TOKEN_EXPIRED"
+    message = "Refresh token has expired"
+
+
 class UserNotFoundError(NotFoundError):
     """User not found."""
 

{identity_plan_kit-0.2.6 → identity_plan_kit-0.2.8}/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.8}/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.6 → identity_plan_kit-0.2.8}/src/identity_plan_kit/plans/__init__.py

@@ -9,6 +9,10 @@ from identity_plan_kit.plans.domain.entities import Feature, Plan, PlanLimit, Us
 from identity_plan_kit.plans.domain.exceptions import (
     FeatureNotAvailableError,
     FeatureNotFoundError,
+    InvalidCustomLimitsError,
+    InvalidPlanDatesError,
+    PlanAssignmentError,
+    PlanAuthorizationError,
     PlanExpiredError,
     PlanNotFoundError,
     QuotaExceededError,
@@ -26,7 +30,11 @@ __all__ = [
     # Exceptions
     "FeatureNotAvailableError",
     "FeatureNotFoundError",
+    "InvalidCustomLimitsError",
+    "InvalidPlanDatesError",
     "Plan",
+    "PlanAssignmentError",
+    "PlanAuthorizationError",
     "PlanExpiredError",
     "PlanLimit",
     "PlanNotFoundError",

identity_plan_kit-0.2.8/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)