supervisely 6.73.438__py3-none-any.whl → 6.73.513__py3-none-any.whl

supervisely/api/video/video_figure_api.py

@@ -10,7 +10,7 @@ from supervisely.api.module_api import ApiField
 from supervisely.geometry.geometry import Geometry
 from supervisely.video_annotation.key_id_map import KeyIdMap
 from supervisely.video_annotation.video_figure import VideoFigure
-
+from supervisely.annotation.label import LabelingStatus
 
 class VideoFigureApi(FigureApi):
     """
@@ -26,6 +26,7 @@ class VideoFigureApi(FigureApi):
         geometry_type: str,
         track_id: Optional[int] = None,
         meta: Optional[dict] = None,
+        status: Optional[LabelingStatus] = None,
     ) -> int:
         """
         Create new VideoFigure for given frame in given video ID.
@@ -42,6 +43,10 @@ class VideoFigureApi(FigureApi):
         :type geometry_type: str
         :param track_id: int, optional.
         :type track_id: int, optional
+        :param meta: Meta data for VideoFigure.
+        :type meta: dict, optional
+        :param status: Labeling status. Specifies if the VideoFigure was created by NN model, manually or created by NN and then manually corrected.
+        :type status: LabelingStatus, optional
         :return: New figure ID
         :rtype: :class:`int`
         :Usage example:
@@ -64,13 +69,16 @@ class VideoFigureApi(FigureApi):
         """
         if meta is None:
             meta = {}
+        meta = {**(meta or {}), ApiField.FRAME: frame_index}
+
         return super().create(
             video_id,
             object_id,
-            {**meta, ApiField.FRAME: frame_index},
+            meta,
             geometry_json,
             geometry_type,
             track_id,
+            status=status,
         )
 
     def append_bulk(self, video_id: int, figures: List[VideoFigure], key_id_map: KeyIdMap) -> None:
@@ -115,13 +123,15 @@ class VideoFigureApi(FigureApi):
 
         self._append_bulk(video_id, figures_json, keys, key_id_map)
 
-    def update(self, figure_id: int, geometry: Geometry) -> None:
+    def update(self, figure_id: int, geometry: Geometry, status: Optional[LabelingStatus] = None) -> None:
         """Updates figure feometry with given ID in Supervisely with new Geometry object.
 
         :param figure_id: ID of the figure to update
         :type figure_id: int
         :param geometry: Supervisely Gepmetry object
         :type geometry: Geometry
+        :param status: Labeling status. Specifies if the VideoFigure was created by NN model, manually or created by NN and then manually corrected.
+        :type status: LabelingStatus, optional
         :Usage example:
 
          .. code-block:: python
@@ -141,13 +151,17 @@ class VideoFigureApi(FigureApi):
 
             api.video.figure.update(figure_id, new_geometry)
         """
-        self._api.post(
-            "figures.editInfo",
-            {
-                ApiField.ID: figure_id,
-                ApiField.GEOMETRY: geometry.to_json(),
-            },
-        )
+        payload = {
+            ApiField.ID: figure_id,
+            ApiField.GEOMETRY: geometry.to_json(),
+        }
+
+        if status is not None:
+            nn_created,nn_updated = LabelingStatus.to_flags(status)
+            payload[ApiField.NN_CREATED] = nn_created
+            payload[ApiField.NN_UPDATED] = nn_updated
+
+        self._api.post("figures.editInfo", payload)
 
     def download(
         self, dataset_id: int, video_ids: List[int] = None, skip_geometry: bool = False, **kwargs
@@ -161,7 +175,6 @@ class VideoFigureApi(FigureApi):
         :type video_ids: List[int], optional
         :param skip_geometry: Skip the download of figure geometry. May be useful for a significant api request speed increase in the large datasets.
         :type skip_geometry: bool
-
         :return: A dictionary where keys are video IDs and values are lists of figures.
         :rtype: :class: `Dict[int, List[FigureInfo]]`
         """

supervisely/app/__init__.py

@@ -1,7 +1,7 @@
 from fastapi import FastAPI
 from supervisely.app.content import StateJson, DataJson
 from supervisely.app.content import get_data_dir, get_synced_data_dir
-from supervisely.app.fastapi.subapp import call_on_autostart
+from supervisely.app.fastapi.subapp import call_on_autostart, session_user_api
 import supervisely.app.fastapi as fastapi
 import supervisely.app.widgets as widgets
 import supervisely.app.development as development

supervisely/app/content.py

@@ -11,12 +11,14 @@ import threading
 import time
 import traceback
 from concurrent.futures import ThreadPoolExecutor
+from typing import Optional, Union
 
 import jsonpatch
 from fastapi import Request
 
 from supervisely._utils import is_production
 from supervisely.api.api import Api
+import supervisely.app.fastapi.multi_user as multi_user
 from supervisely.app.fastapi import run_sync
 from supervisely.app.fastapi.websocket import WebsocketManager
 from supervisely.app.singleton import Singleton
@@ -109,16 +111,29 @@ class _PatchableJson(dict):
             patch.apply(self._last, in_place=True)
             self._last = copy.deepcopy(self._last)
 
-    async def synchronize_changes(self):
+    async def synchronize_changes(self, user_id: Optional[Union[int, str]] = None):
         patch = self._get_patch()
-        await self._apply_patch(patch)
-        await self._ws.broadcast(self.get_changes(patch))
+        if user_id is not None:
+            async with multi_user.async_session_context(user_id):
+                await self._apply_patch(patch)
+                await self._ws.broadcast(
+                    self.get_changes(patch), user_id=user_id
+                )
+        else:
+            await self._apply_patch(patch)
+            await self._ws.broadcast(self.get_changes(patch), user_id=user_id)
 
     async def send_changes_async(self):
-        await self.synchronize_changes()
+        user_id = None
+        if sly_env.is_multiuser_mode_enabled():
+            user_id = sly_env.user_from_multiuser_app()
+        await self.synchronize_changes(user_id=user_id)
 
     def send_changes(self):
-        run_sync(self.synchronize_changes())
+        user_id = None
+        if sly_env.is_multiuser_mode_enabled():
+            user_id = sly_env.user_from_multiuser_app()
+        run_sync(self.synchronize_changes(user_id=user_id))
 
     def raise_for_key(self, key: str):
         if key in self:
@@ -139,7 +154,7 @@ class StateJson(_PatchableJson, metaclass=Singleton):
         await StateJson._replace_global(dict(self))
 
     @classmethod
-    async def from_request(cls, request: Request) -> StateJson:
+    async def from_request(cls, request: Request, local: bool = True) -> StateJson:
         if "application/json" not in request.headers.get("Content-Type", ""):
             return None
         content = await request.json()
@@ -149,7 +164,8 @@ class StateJson(_PatchableJson, metaclass=Singleton):
         # TODO: should we always replace STATE with {}?
         d = content.get(Field.STATE, {})
         await cls._replace_global(d)
-        return cls(d, __local__=True)
+
+        return cls(d, __local__=local)
 
     @classmethod
     async def _replace_global(cls, d: dict):

supervisely/app/development/development.py

@@ -156,7 +156,10 @@ def supervisely_vpn_network(
 
 
 def create_debug_task(
-    team_id: int = None, port: int = 8000, update_status: bool = True
+    team_id: int = None,
+    port: int = 8000,
+    update_status: bool = True,
+    project_id: Optional[int] = None,
 ) -> Dict[str, Any]:
     """Gets or creates a debug task for the current user.
 
@@ -167,6 +170,8 @@ def create_debug_task(
     :type port: int
     :param update_status: If True, the task status will be updated to STARTED.
     :type update_status: bool
+    :param project_id: Project ID to filter existing debug tasks. Creates a new task if no match is found. Default is None.
+    :type project_id: Optional[int]
     :return: The task details.
     :rtype: Dict[str, Any]
     """
@@ -189,6 +194,10 @@ def create_debug_task(
         if (session.details["meta"].get("redirectRequests") == redirect_requests) and (
             session.details["status"] in [str(api.app.Status.QUEUED), str(api.app.Status.STARTED)]
         ):
+            if project_id is not None:
+                state = session.details["meta"].get("params", {}).get("state", {})
+                if state.get("slyProjectId") != project_id:
+                    continue  # project_id not set in state, skip this session
             task = session.details
             if "id" not in task:
                 task["id"] = task["taskId"]
@@ -196,6 +205,7 @@ def create_debug_task(
             break
     workspaces = api.workspace.get_list(team_id)
     if task is None:
+        params = {"state": {"slyProjectId": project_id}} if project_id is not None else None
         task = api.task.start(
             agent_id=None,
             module_id=module_id,
@@ -203,6 +213,7 @@ def create_debug_task(
             task_name=session_name,
             redirect_requests=redirect_requests,
             proxy_keep_url=False,  # to ignore /net/<token>/endpoint
+            params=params,
         )
         if type(task) is list:
             task = task[0]
@@ -222,6 +233,7 @@ def enable_advanced_debug(
     vpn_action: Literal["up", "down"] = "up",
     vpn_raise_on_error: bool = True,
     only_for_development: bool = True,
+    project_id: Optional[int] = None,
 ) -> Optional[int]:
     """Enables advanced debugging for the app.
     At first, it establishes a WireGuard VPN connection to the Supervisely network.
@@ -244,6 +256,8 @@ def enable_advanced_debug(
     :param only_for_development: If True, the debugging will be started only if the app is running in development mode.
         It's not recommended to set this parameter to False in production environments.
     :type only_for_development: bool
+    :param project_id: Project ID to filter existing debug tasks. Creates a new task if no match is found. Default is None.
+    :type project_id: Optional[int]
     :return: The task ID of the debug task or None if the debugging was not started.
     :rtype: Optional[int]
 
@@ -285,7 +299,9 @@ def enable_advanced_debug(
     )
 
     supervisely_vpn_network(action=vpn_action, raise_on_error=vpn_raise_on_error)
-    task = create_debug_task(team_id=team_id, port=port, update_status=update_status)
+    task = create_debug_task(
+        team_id=team_id, port=port, update_status=update_status, project_id=project_id
+    )
     task_id = task.get("id", None)
 
     logger.debug(

supervisely/app/fastapi/__init__.py

@@ -5,6 +5,7 @@ from supervisely.app.fastapi.subapp import (
     Application,
     get_name_from_env,
     _MainServer,
+    session_user_api,
 )
 from supervisely.app.fastapi.templating import Jinja2Templates
 from supervisely.app.fastapi.websocket import WebsocketManager

supervisely/app/fastapi/custom_static_files.py

@@ -42,7 +42,7 @@ class CustomStaticFiles(StaticFiles):
         def _get_range_header(range_header: str, file_size: int) -> typing.Tuple[int, int]:
             def _invalid_range():
                 return HTTPException(
-                    status.HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE,
+                    status.HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE, #TODO: change to status.HTTP_416_RANGE_NOT_SATISFIABLE if update starlette to 0.48.0+
                     detail=f"Invalid request range (Range:{range_header!r})",
                 )
 

supervisely/app/fastapi/multi_user.py

@@ -0,0 +1,105 @@
+import hashlib
+from contextlib import contextmanager, asynccontextmanager
+from typing import Optional, Union
+
+from fastapi import Request
+
+import supervisely.io.env as sly_env
+from supervisely.api.module_api import ApiField
+from supervisely.app.fastapi.websocket import WebsocketManager
+from supervisely.sly_logger import logger
+
+
+def _parse_int(value):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _user_identity_from_cookie(request: Request) -> Optional[str]:
+    cookie_header = request.headers.get("cookie")
+    if not cookie_header:
+        return None
+    return hashlib.sha256(cookie_header.encode("utf-8")).hexdigest()
+
+
+async def extract_user_id_from_request(request: Request) -> Optional[Union[int, str]]:
+    """Extract user ID from various parts of the request."""
+    if not sly_env.is_multiuser_mode_enabled():
+        return None
+    user_id = _parse_int(request.query_params.get("userId"))
+    if user_id is None:
+        header_user = _parse_int(request.headers.get("x-user-id"))
+        if header_user is not None:
+            user_id = header_user
+    if user_id is None:
+        referer = request.headers.get("referer", "")
+        if referer:
+            from urllib.parse import parse_qs, urlparse
+
+            try:
+                parsed_url = urlparse(referer)
+                query_params = parse_qs(parsed_url.query)
+                referer_user = query_params.get("userId", [None])[0]
+                user_id = _parse_int(referer_user)
+            except Exception as e:
+                logger.error(f"Error parsing userId from referer: {e}")
+    if user_id is None and "application/json" in request.headers.get("Content-Type", ""):
+        try:
+            payload = await request.json()
+        except Exception:
+            payload = {}
+        context = payload.get("context") or {}
+        user_id = _parse_int(context.get("userId") or context.get(ApiField.USER_ID))
+        if user_id is None:
+            state_payload = payload.get("state") or {}
+            user_id = _parse_int(state_payload.get("userId") or state_payload.get(ApiField.USER_ID))
+    if user_id is None:
+        user_id = _user_identity_from_cookie(request)
+    return user_id
+
+
+def _session_context_impl(user_id: Optional[Union[int, str]]):
+    """Internal implementation for session context."""
+    if not sly_env.is_multiuser_mode_enabled() or user_id is None:
+        return None
+    return sly_env.set_user_for_multiuser_app(user_id)
+
+@contextmanager
+def session_context(user_id: Optional[Union[int, str]]):
+    """
+    Context manager to set and reset user context for multiuser applications.
+    Call this at the beginning of a request handling to ensure the correct user context is set in environment variables (`supervisely_multiuser_app_user_id` ContextVar).
+    """
+    token = _session_context_impl(user_id)
+    try:
+        yield
+    finally:
+        if token is not None:
+            sly_env.reset_user_for_multiuser_app(token)
+
+@asynccontextmanager
+async def async_session_context(user_id: Optional[Union[int, str]]):
+    """
+    Asynchronous context manager to set and reset user context for multiuser applications.
+    Call this at the beginning of an async request handling to ensure the correct user context is set in environment variables (`supervisely_multiuser_app_user_id` ContextVar).
+    """
+    token = _session_context_impl(user_id)
+    try:
+        yield
+    finally:
+        if token is not None:
+            sly_env.reset_user_for_multiuser_app(token)
+
+
+def remember_cookie(request: Request, user_id: Optional[Union[int, str]]):
+    """
+    Remember user cookie for the given user ID. This is used to associate WebSocket connections with users in multiuser applications based on cookies.
+    Allows WebSocket connections to be correctly routed to the appropriate user.
+    """
+    if not sly_env.is_multiuser_mode_enabled() or user_id is None:
+        return
+    cookie_header = request.headers.get("cookie")
+    if cookie_header:
+        WebsocketManager().remember_user_cookie(cookie_header, user_id)

supervisely/app/fastapi/subapp.py

@@ -1,23 +1,25 @@
+import hashlib
 import inspect
 import json
 import os
 import signal
 import sys
 import time
-from contextlib import suppress
+from contextlib import contextmanager, suppress
 from contextvars import ContextVar
 from functools import wraps
 from pathlib import Path
 from threading import Event as ThreadingEvent
 from threading import Thread
 from time import sleep
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
 
 import arel
 import jinja2
 import numpy as np
 import psutil
 from async_asgi_testclient import TestClient
+from cachetools import TTLCache
 from fastapi import (
     Depends,
     FastAPI,
@@ -32,6 +34,7 @@ from fastapi.responses import JSONResponse
 from fastapi.routing import APIRouter
 from fastapi.staticfiles import StaticFiles
 
+import supervisely.app.fastapi.multi_user as multi_user
 import supervisely.io.env as sly_env
 from supervisely._utils import (
     is_debug_with_sly_net,
@@ -68,6 +71,10 @@ HEALTH_ENDPOINTS = ["/health", "/is_ready"]
 # Context variable for response time
 response_time_ctx: ContextVar[float] = ContextVar("response_time", default=None)
 
+# Mapping from user_id to Api instance
+_USER_API_CACHE = TTLCache(maxsize=500, ttl=60 * 15)  # Cache up to 15 minutes
+
+
 class ReadyzFilter(logging.Filter):
     def filter(self, record):
         if "/readyz" in record.getMessage() or "/livez" in record.getMessage():
@@ -623,18 +630,30 @@ def create(
         shutdown(process_id, before_shutdown_callbacks)
 
     if headless is False:
-
         @app.post("/data")
         async def send_data(request: Request):
-            data = DataJson()
-            response = JSONResponse(content=dict(data))
+            if not sly_env.is_multiuser_mode_enabled():
+                data = DataJson()
+                response = JSONResponse(content=dict(data))
+                return response
+            user_id = await multi_user.extract_user_id_from_request(request)
+            multi_user.remember_cookie(request, user_id)
+            with multi_user.session_context(user_id):
+                data = DataJson()
+                response = JSONResponse(content=dict(data))
             return response
 
         @app.post("/state")
         async def send_state(request: Request):
-            state = StateJson()
-
-            response = JSONResponse(content=dict(state))
+            if not sly_env.is_multiuser_mode_enabled():
+                state = StateJson()
+                response = JSONResponse(content=dict(state))
+            else:
+                user_id = await multi_user.extract_user_id_from_request(request)
+                multi_user.remember_cookie(request, user_id)
+                with multi_user.session_context(user_id):
+                    state = StateJson()
+                    response = JSONResponse(content=dict(state))
             gettrace = getattr(sys, "gettrace", None)
             if (gettrace is not None and gettrace()) or is_development():
                 response.headers["x-debug-mode"] = "1"
@@ -813,41 +832,59 @@ def _init(
     async def get_state_from_request(request: Request, call_next):
         # Start timer for response time measurement
         start_time = time.perf_counter()
-        if headless is False:
-            await StateJson.from_request(request)
-
-        if not ("application/json" not in request.headers.get("Content-Type", "")):
-            # {'command': 'inference_batch_ids', 'context': {}, 'state': {'dataset_id': 49711, 'batch_ids': [3120204], 'settings': None}, 'user_api_key': 'XXX', 'api_token': 'XXX', 'instance_type': None, 'server_address': 'https://app.supervisely.com'}
-            content = await request.json()
-
-            request.state.context = content.get("context")
-            request.state.state = content.get("state")
-            request.state.api_token = content.get(
-                "api_token",
-                (
-                    request.state.context.get("apiToken")
-                    if request.state.context is not None
-                    else None
-                ),
-            )
-            # logger.debug(f"middleware request api_token {request.state.api_token}")
-            request.state.server_address = content.get(
-                "server_address", sly_env.server_address(raise_not_found=False)
-            )
-            # request.state.server_address = sly_env.server_address(raise_not_found=False)
-            # logger.debug(f"middleware request server_address {request.state.server_address}")
-            # logger.debug(f"middleware request context {request.state.context}")
-            # logger.debug(f"middleware request state {request.state.state}")
-            if request.state.server_address is not None and request.state.api_token is not None:
-                request.state.api = Api(request.state.server_address, request.state.api_token)
-            else:
-                request.state.api = None
 
-        try:
-            response = await call_next(request)
-        except Exception as exc:
-            need_to_handle_error = is_production()
-            response = await process_server_error(request, exc, need_to_handle_error)
+        async def _process_request(request: Request, call_next):
+            if "application/json" in request.headers.get("Content-Type", ""):
+                content = await request.json()
+                request.state.context = content.get("context")
+                request.state.state = content.get("state")
+                request.state.api_token = content.get(
+                    "api_token",
+                    (
+                        request.state.context.get("apiToken")
+                        if request.state.context is not None
+                        else None
+                    ),
+                )
+                request.state.server_address = content.get(
+                    "server_address", sly_env.server_address(raise_not_found=False)
+                )
+                if (
+                    request.state.server_address is not None
+                    and request.state.api_token is not None
+                ):
+                    request.state.api = Api(
+                        request.state.server_address, request.state.api_token
+                    )
+                    if sly_env.is_multiuser_mode_enabled():
+                        user_id = sly_env.user_from_multiuser_app()
+                        if user_id is not None:
+                            _USER_API_CACHE[user_id] = request.state.api
+                else:
+                    request.state.api = None
+
+            try:
+                response = await call_next(request)
+            except Exception as exc:
+                need_to_handle_error = is_production()
+                response = await process_server_error(
+                    request, exc, need_to_handle_error
+                )
+
+            return response
+
+        if not sly_env.is_multiuser_mode_enabled():
+            if headless is False:
+                await StateJson.from_request(request)
+            response = await _process_request(request, call_next)
+        else:
+            user_id = await multi_user.extract_user_id_from_request(request)
+            multi_user.remember_cookie(request, user_id)
+
+            with multi_user.session_context(user_id):
+                if headless is False:
+                    await StateJson.from_request(request, local=False)
+                response = await _process_request(request, call_next)
         # Calculate response time and set it for uvicorn logger in ms
         elapsed_ms = round((time.perf_counter() - start_time) * 1000)
         response_time_ctx.set(elapsed_ms)
@@ -1277,3 +1314,12 @@ def call_on_autostart(
 
 def get_name_from_env(default="Supervisely App"):
     return os.environ.get("APP_NAME", default)
+
+def session_user_api() -> Optional[Api]:
+    """Returns the API instance for the current session user."""
+    if not sly_env.is_multiuser_mode_enabled():
+        return Api.from_env()
+    user_id = sly_env.user_from_multiuser_app()
+    if user_id is None:
+        return None
+    return _USER_API_CACHE.get(user_id, None)

supervisely/app/fastapi/websocket.py

@@ -1,5 +1,10 @@
-from typing import List
+import hashlib
+import time
+from typing import Dict, List, Optional, Tuple, Union
+
 from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+import supervisely.io.env as sly_env
 from supervisely.app.singleton import Singleton
 
 
@@ -8,6 +13,9 @@ class WebsocketManager(metaclass=Singleton):
         self.app = None
         self.path = path
         self.active_connections: List[WebSocket] = []
+        self._connection_users: Dict[WebSocket, Optional[Union[int, str]]] = {}
+        self._cookie_user_map: Dict[str, Tuple[Union[int, str], float]] = {}
+        self._cookie_ttl_seconds = 60 * 60
 
     def set_app(self, app: FastAPI):
         if self.app is not None:
@@ -17,17 +25,42 @@ class WebsocketManager(metaclass=Singleton):
 
     async def connect(self, websocket: WebSocket):
         await websocket.accept()
+        user_id = self._resolve_user_id(websocket)
         self.active_connections.append(websocket)
+        self._connection_users[websocket] = user_id
 
     def disconnect(self, websocket: WebSocket):
-        self.active_connections.remove(websocket)
-
-    async def broadcast(self, d: dict):
-        # if self.app is None:
-        #     raise ValueError(
-        #         "WebSocket is not initialized, use Websocket middleware for that"
-        #     )
-        for connection in self.active_connections:
+        if websocket in self.active_connections:
+            self.active_connections.remove(websocket)
+        self._connection_users.pop(websocket, None)
+
+    def remember_user_cookie(
+        self, cookie_header: Optional[str], user_id: Optional[Union[int, str]]
+    ):
+        if cookie_header is None or user_id is None:
+            return
+        fingerprint = self._cookie_fingerprint(cookie_header)
+        if fingerprint is None:
+            return
+        self._purge_cookie_cache()
+        self._cookie_user_map[fingerprint] = (user_id, time.monotonic())
+
+    async def broadcast(self, d: dict, user_id: Optional[Union[int, str]] = None):
+        if sly_env.is_multiuser_mode_enabled():
+            if user_id is None:
+                user_id = sly_env.user_from_multiuser_app()
+            if user_id is None:
+                targets = list(self.active_connections)
+            else:
+                targets = [
+                    connection
+                    for connection in self.active_connections
+                    if self._connection_users.get(connection) == user_id
+                ]
+        else:
+            targets = list(self.active_connections)
+
+        for connection in list(targets):
             await connection.send_json(d)
 
     async def endpoint(self, websocket: WebSocket):
@@ -37,3 +70,38 @@ class WebsocketManager(metaclass=Singleton):
                 data = await websocket.receive_text()
         except WebSocketDisconnect:
             self.disconnect(websocket)
+
+    def _resolve_user_id(self, websocket: WebSocket) -> Optional[int]:
+        if not sly_env.is_multiuser_mode_enabled():
+            return None
+        query_user = websocket.query_params.get("userId")
+        if query_user is not None:
+            try:
+                return int(query_user)
+            except ValueError:
+                pass
+        fingerprint = self._cookie_fingerprint(websocket.headers.get("cookie"))
+        if fingerprint is None:
+            return None
+        cached = self._cookie_user_map.get(fingerprint)
+        if cached is None:
+            return None
+        user_id, ts = cached
+        if time.monotonic() - ts > self._cookie_ttl_seconds:
+            self._cookie_user_map.pop(fingerprint, None)
+            return None
+        return user_id
+
+    @staticmethod
+    def _cookie_fingerprint(cookie_header: Optional[str]) -> Optional[str]:
+        if not cookie_header:
+            return None
+        return hashlib.sha256(cookie_header.encode("utf-8")).hexdigest()
+
+    def _purge_cookie_cache(self) -> None:
+        if not self._cookie_user_map:
+            return
+        cutoff = time.monotonic() - self._cookie_ttl_seconds
+        expired = [key for key, (_, ts) in self._cookie_user_map.items() if ts < cutoff]
+        for key in expired:
+            self._cookie_user_map.pop(key, None)