@GitHK review: doc and rename

Author: pcrespov

services/api-server/src/simcore_service_api_server/repository/_base.py

@@ -3,7 +3,58 @@
 
 from sqlalchemy.ext.asyncio import AsyncEngine
 
-DB_CACHE_TTL_SECONDS: Final = 120  # 2 minutes
+## Memory Usage of aiocache for Session Authentication Caching
+AUTH_SESSION_TTL_SECONDS: Final = 120  # 2 minutes
+"""
+    ### Memory Usage Characteristics
+
+    **aiocache** uses in-memory storage by default, which means:
+
+    1. **Linear memory growth**: Each cached item consumes RAM proportional to the serialized size of the cached data
+    2. **No automatic memory limits**: By default, there's no built-in maximum memory cap
+    3. **TTL-based cleanup**: Items are only removed when they expire (TTL) or are explicitly deleted
+
+
+    **Key limitations:**
+    - **MEMORY backend**: No built-in memory limits or LRU eviction
+    - **Maximum capacity**: Limited only by available system RAM
+    - **Risk**: Memory leaks if TTL is too long or cache keys grow unbounded
+
+    ### Recommendations for Your Use Case
+
+    **For authentication caching:**
+
+    1. **Low memory impact**: User authentication data is typically small (user_id, email, product_name)
+    2. **Short TTL**: Your 120s TTL helps prevent unbounded growth
+    3. **Bounded key space**: API keys are finite, not user-generated
+
+    **Memory estimation:**
+    ```
+    Per cache entry ≈ 200-500 bytes (user data + overhead)
+    1000 active users ≈ 500KB
+    10000 active users ≈ 5MB
+    ```
+
+    ### Alternative Approaches
+
+    **If memory becomes a concern:**
+
+    1. **Redis backend**:
+    ```python
+    cache = Cache(Cache.REDIS, endpoint="redis://localhost", ...)
+    ```
+
+    2. **Custom eviction policy**: Implement LRU manually or use shorter TTL
+
+    3. **Monitoring**: Track cache size in production:
+    ```python
+    # Check cache statistics
+    cache_stats = await cache.get_stats()
+    ```
+
+    **Verdict**:
+    For authentication use case with reasonable user counts (<10K active), memory impact should be minimal with your current TTL configuration.
+"""
 
 
 @dataclass

services/api-server/src/simcore_service_api_server/repository/api_keys.py

@@ -9,7 +9,7 @@
 from simcore_postgres_database.utils_repos import pass_or_acquire_connection
 from sqlalchemy.ext.asyncio import AsyncConnection
 
-from ._base import DB_CACHE_TTL_SECONDS, BaseRepository
+from ._base import AUTH_SESSION_TTL_SECONDS, BaseRepository
 
 _logger = logging.getLogger(__name__)
 
@@ -23,7 +23,7 @@ class ApiKeysRepository(BaseRepository):
     """Auth access"""
 
     @cached(
-        ttl=DB_CACHE_TTL_SECONDS,
+        ttl=AUTH_SESSION_TTL_SECONDS,
         key_builder=lambda *_args, **kwargs: f"api_auth:{kwargs['api_key']}",
         namespace=__name__,
         noself=True,

services/api-server/src/simcore_service_api_server/repository/users.py

@@ -8,12 +8,12 @@
 from simcore_postgres_database.utils_repos import pass_or_acquire_connection
 from sqlalchemy.ext.asyncio import AsyncConnection
 
-from ._base import DB_CACHE_TTL_SECONDS, BaseRepository
+from ._base import AUTH_SESSION_TTL_SECONDS, BaseRepository
 
 
 class UsersRepository(BaseRepository):
     @cached(
-        ttl=DB_CACHE_TTL_SECONDS,
+        ttl=AUTH_SESSION_TTL_SECONDS,
         key_builder=lambda *_args, **kwargs: f"user_email:{kwargs['user_id']}",
         cache=Cache.MEMORY,
         namespace=__name__,

services/api-server/tests/unit/_with_db/authentication/test_api_dependency_authentication.py

@@ -43,72 +43,7 @@ async def test_cache_effectiveness_in_rest_authentication_dependencies(
     users_repo: UsersRepository,
     mocker: MockerFixture,
 ):
-    """Test that caching reduces database calls and improves performance.
-
-    ## Memory Implications of aiocache
-
-    ### Memory Usage Characteristics
-
-    **aiocache** uses in-memory storage by default, which means:
-
-    1. **Linear memory growth**: Each cached item consumes RAM proportional to the serialized size of the cached data
-    2. **No automatic memory limits**: By default, there's no built-in maximum memory cap
-    3. **TTL-based cleanup**: Items are only removed when they expire (TTL) or are explicitly deleted
-
-    ### Memory Limits & Configuration
-
-    **Available configuration options:**
-
-    ```python
-    # Memory backend configuration
-    cache = Cache(Cache.MEMORY, **{
-        'serializer': {
-            'class': 'aiocache.serializers.PickleSerializer'
-        },
-        # No built-in memory limit options for MEMORY backend
-    })
-    ```
-
-    **Key limitations:**
-    - **MEMORY backend**: No built-in memory limits or LRU eviction
-    - **Maximum capacity**: Limited only by available system RAM
-    - **Risk**: Memory leaks if TTL is too long or cache keys grow unbounded
-
-    ### Recommendations for Your Use Case
-
-    **For authentication caching:**
-
-    1. **Low memory impact**: User authentication data is typically small (user_id, email, product_name)
-    2. **Short TTL**: Your 120s TTL helps prevent unbounded growth
-    3. **Bounded key space**: API keys are finite, not user-generated
-
-    **Memory estimation:**
-    ```
-    Per cache entry ≈ 200-500 bytes (user data + overhead)
-    1000 active users ≈ 500KB
-    10000 active users ≈ 5MB
-    ```
-
-    ### Alternative Approaches
-
-    **If memory becomes a concern:**
-
-    1. **Redis backend**:
-    ```python
-    cache = Cache(Cache.REDIS, endpoint="redis://localhost", ...)
-    ```
-
-    2. **Custom eviction policy**: Implement LRU manually or use shorter TTL
-
-    3. **Monitoring**: Track cache size in production:
-    ```python
-    # Check cache statistics
-    cache_stats = await cache.get_stats()
-    ```
-
-    **Verdict**:
-    For authentication use case with reasonable user counts (<10K active), memory impact should be minimal with your current TTL configuration.
-    """
+    """Test that caching reduces database calls and improves performance."""
 
     # Generate a fake API key
     credentials = HTTPBasicCredentials(