maleo-foundation 0.2.78__py3-none-any.whl → 0.2.81__py3-none-any.whl

maleo_foundation/managers/service.py

@@ -90,6 +90,7 @@ class MaleoClientConfiguration(BaseModel):
     url:str = Field(..., description="Client's URL")
 
 class MaleoClientConfigurations(BaseModel):
+    telemetry:MaleoClientConfiguration = Field(..., description="MaleoTelemetry client's configuration")
     metadata:MaleoClientConfiguration = Field(..., description="MaleoMetadata client's configuration")
     identity:MaleoClientConfiguration = Field(..., description="MaleoIdentity client's configuration")
     access:MaleoClientConfiguration = Field(..., description="MaleoAccess client's configuration")
@@ -415,7 +416,7 @@ class ServiceManager:
             maleo_foundation=self._foundation
         )
         self._middleware.add_all()
-        self._loggers.application.info("Middlewares addedd successfully")
+        self._loggers.application.info("Middlewares added successfully")
 
         #* Add exception handler(s)
         self._loggers.application.info("Adding exception handlers")
@@ -427,7 +428,7 @@ class ServiceManager:
             exc_class_or_status_code=HTTPException,
             handler=BaseExceptions.http_exception_handler
         )
-        self._loggers.application.info("Exception handlers addedd successfully")
+        self._loggers.application.info("Exception handlers added successfully")
 
         #* Include router
         self._loggers.application.info("Including routers")

maleo_foundation/middlewares/base.py

@@ -4,303 +4,398 @@ import time
 import traceback
 from collections import defaultdict
 from datetime import datetime, timedelta, timezone
+from typing import Awaitable, Callable, Optional, Sequence, Dict, List
+
 from fastapi import FastAPI, Request, Response, status
 from fastapi.responses import JSONResponse
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
-from typing import Awaitable, Callable, Optional, Sequence
+
 from maleo_foundation.authentication import Authentication
 from maleo_foundation.enums import BaseEnums
 from maleo_foundation.client.manager import MaleoFoundationClientManager
 from maleo_foundation.models.schemas import BaseGeneralSchemas
 from maleo_foundation.models.responses import BaseResponses
-from maleo_foundation.models.transfers.general.token \
-    import MaleoFoundationTokenGeneralTransfers
-from maleo_foundation.models.transfers.parameters.token \
-    import MaleoFoundationTokenParametersTransfers
-from maleo_foundation.models.transfers.parameters.signature \
-    import MaleoFoundationSignatureParametersTransfers
-from maleo_foundation.utils.extractor import BaseExtractors
+from maleo_foundation.models.transfers.general.token import MaleoFoundationTokenGeneralTransfers
+from maleo_foundation.models.transfers.parameters.token import MaleoFoundationTokenParametersTransfers
+from maleo_foundation.models.transfers.parameters.signature import MaleoFoundationSignatureParametersTransfers
+from maleo_foundation.models.transfers.general import RequestContextTransfers
+from maleo_foundation.utils.extractor import extract_request_context
 from maleo_foundation.utils.logging import MiddlewareLogger
 
 RequestProcessor = Callable[[Request], Awaitable[Optional[Response]]]
 ResponseProcessor = Callable[[Response], Awaitable[Response]]
 
-class BaseMiddleware(BaseHTTPMiddleware):
+class RateLimiter:
+    """Thread-safe rate limiter with automatic cleanup."""
+
     def __init__(
         self,
-        app:FastAPI,
-        keys:BaseGeneralSchemas.RSAKeys,
-        logger:MiddlewareLogger,
-        maleo_foundation:MaleoFoundationClientManager,
-        allow_origins:Sequence[str] = (),
-        allow_methods:Sequence[str] = ("GET",),
-        allow_headers:Sequence[str] = (),
-        allow_credentials:bool = False,
-        limit:int = 10,
-        window:int = 1,
-        cleanup_interval:int = 60,
-        ip_timeout:int = 300
+        limit:int,
+        window:timedelta,
+        ip_timeout:timedelta,
+        cleanup_interval:timedelta
     ):
-        super().__init__(app)
-        self._keys = keys
-        self._logger = logger
-        self._maleo_foundation = maleo_foundation
-        self._allow_origins = allow_origins
-        self._allow_methods = allow_methods
-        self._allow_headers = allow_headers
-        self._allow_credentials = allow_credentials
-        self._limit = limit
-        self._window = timedelta(seconds=window)
-        self._cleanup_interval = timedelta(seconds=cleanup_interval)
-        self._ip_timeout = timedelta(seconds=ip_timeout)
-        self._requests:dict[str, list[datetime]] = defaultdict(list)
-        self._last_seen: dict[str, datetime] = {}
+        self.limit = limit
+        self.window = window
+        self.ip_timeout = ip_timeout
+        self.cleanup_interval = cleanup_interval
+        self._requests:Dict[str, List[datetime]] = defaultdict(list)
+        self._last_seen:Dict[str, datetime] = {}
         self._last_cleanup = datetime.now()
-        self._lock = threading.RLock()  #* Use RLock for thread safety
-
-    def _cleanup_old_data(self) -> None:
-        """
-        Periodically clean up old request data to prevent memory growth.
-        Removes:
-        1. IPs with empty request lists
-        2. IPs that haven't been seen in ip_timeout period
-        """
-        now = datetime.now()
-        if now - self._last_cleanup > self._cleanup_interval:
-            with self._lock:
-                #* Remove inactive IPs (not seen recently) and empty lists
-                inactive_ips = []
-                for ip in list(self._requests.keys()):
-                    #* Remove IPs with empty timestamp lists
-                    if not self._requests[ip]:
-                        inactive_ips.append(ip)
-                        continue
-                        
-                    #* Remove IPs that haven't been active recently
-                    last_active = self._last_seen.get(ip, datetime.min)
-                    if now - last_active > self._ip_timeout:
-                        inactive_ips.append(ip)
-                
-                #* Remove the inactive IPs
-                for ip in inactive_ips:
-                    if ip in self._requests:
-                        del self._requests[ip]
-                    if ip in self._last_seen:
-                        del self._last_seen[ip]
-                
-                # Update last cleanup time
-                self._last_cleanup = now
-                self._logger.debug(f"Cleaned up request cache. Removed {len(inactive_ips)} inactive IPs. Current tracked IPs: {len(self._requests)}")
-
-    def _check_rate_limit(
+        self._lock = threading.RLock()
+
+    def is_rate_limited(
         self,
-        client_ip:str
+        request_context:RequestContextTransfers
     ) -> bool:
-        """Check if the client has exceeded their rate limit"""
+        """Check if client IP is rate limited and record the request."""
         with self._lock:
-            now = datetime.now() #* Define current timestamp
-            self._last_seen[client_ip] = now #* Update last seen timestamp for this IP
+            now = datetime.now()
+            client_ip = request_context.ip_address
+            self._last_seen[client_ip] = now
 
-            #* Filter requests within the window
+            # Remove old requests outside the window
             self._requests[client_ip] = [
                 timestamp for timestamp in self._requests[client_ip]
-                if now - timestamp <= self._window
+                if now - timestamp <= self.window
             ]
 
-            #* Check if the request count exceeds the limit
-            if len(self._requests[client_ip]) >= self._limit:
+            # Check rate limit
+            if len(self._requests[client_ip]) >= self.limit:
                 return True
 
-            #* Add the current request timestamp
+            # Record this request
             self._requests[client_ip].append(now)
             return False
 
-    def _add_response_headers(
+    def cleanup_old_data(
+        self,
+        logger:MiddlewareLogger
+    ) -> None:
+        """Clean up old request data to prevent memory growth."""
+        now = datetime.now()
+        if now - self._last_cleanup <= self.cleanup_interval:
+            return
+
+        with self._lock:
+            inactive_ips = []
+
+            for ip in list(self._requests.keys()):
+                # Remove IPs with empty request lists
+                if not self._requests[ip]:
+                    inactive_ips.append(ip)
+                    continue
+
+                # Remove IPs that haven't been active recently
+                last_active = self._last_seen.get(ip, datetime.min)
+                if now - last_active > self.ip_timeout:
+                    inactive_ips.append(ip)
+
+            # Clean up inactive IPs
+            for ip in inactive_ips:
+                self._requests.pop(ip, None)
+                self._last_seen.pop(ip, None)
+
+            self._last_cleanup = now
+            logger.debug(
+                f"Cleaned up request cache. Removed {len(inactive_ips)} inactive IPs. "
+                f"Current tracked IPs: {len(self._requests)}"
+            )
+
+class ResponseBuilder:
+    """Handles response building and header management."""
+
+    def __init__(
+        self,
+        keys:BaseGeneralSchemas.RSAKeys,
+        maleo_foundation:MaleoFoundationClientManager
+    ):
+        self.keys = keys
+        self.maleo_foundation = maleo_foundation
+
+    def add_response_headers(
         self,
-        request:Request,
         authentication:Authentication,
         response:Response,
-        request_timestamp:datetime,
-        response_timestamp:datetime,
-        process_time:int
+        request_context:RequestContextTransfers,
+        responded_at:datetime,
+        process_time:float
     ) -> Response:
-        response.headers["X-Process-Time"] = str(process_time) #* Add Process Time Header
-        response.headers["X-Request-Timestamp"] = request_timestamp.isoformat() #* Add request timestamp header
-        response.headers["X-Response-Timestamp"] = response_timestamp.isoformat() #* Define and add response timestamp header
-        #* Generate signature header
-        message = f"{request.method}|{request.url.path}|{request_timestamp.isoformat()}|{response_timestamp.isoformat()}|{str(process_time)}"
-        sign_parameters = (
-            MaleoFoundationSignatureParametersTransfers
-            .Sign(key=self._keys.private, password=self._keys.password, message=message)
+        """Add custom headers to response."""
+        # Basic headers
+        response.headers["X-Request-ID"] = str(request_context.request_id)
+        response.headers["X-Process-Time"] = str(process_time)
+        response.headers["X-Requested-At"] = request_context.requested_at.isoformat()
+        response.headers["X-Responded-At"] = responded_at.isoformat()
+
+        # Add signature header
+        self._add_signature_header(response, request_context, responded_at, process_time)
+
+        # Add new authorization header if needed
+        self._add_new_authorization_header(request_context, authentication, response)
+
+        return response
+
+    def _add_signature_header(
+        self,
+        response:Response,
+        request_context:RequestContextTransfers,
+        responded_at:datetime,
+        process_time:float
+    ) -> None:
+        """Generate and add signature header."""
+        message = (
+            f"{request_context.method}|{request_context.url}|{request_context.requested_at.isoformat()}|"
+            f"{responded_at.isoformat()}|{str(process_time)}|{str(request_context.request_id)}"
+        )
+
+        sign_parameters = MaleoFoundationSignatureParametersTransfers.Sign(
+            key=self.keys.private,
+            password=self.keys.password,
+            message=message
         )
-        sign_result = self._maleo_foundation.services.signature.sign(parameters=sign_parameters)
+
+        sign_result = self.maleo_foundation.services.signature.sign(parameters=sign_parameters)
         if sign_result.success:
             response.headers["X-Signature"] = sign_result.data.signature
-        if (authentication.user.is_authenticated
+
+    def _add_new_authorization_header(
+        self,
+        request_context:RequestContextTransfers,
+        authentication:Authentication,
+        response:Response
+    ) -> None:
+        """Add new authorization header for refresh tokens."""
+        if not self._should_regenerate_auth(request_context, authentication, response):
+            return
+
+        payload = MaleoFoundationTokenGeneralTransfers.BaseEncodePayload.model_validate(
+            authentication.credentials.token.payload.model_dump()
+        )
+
+        parameters = MaleoFoundationTokenParametersTransfers.Encode(
+            key=self.keys.private,
+            password=self.keys.password,
+            payload=payload
+        )
+
+        result = self.maleo_foundation.services.token.encode(parameters=parameters)
+        if result.success:
+            response.headers["X-New-Authorization"] = result.data.token
+
+    def _should_regenerate_auth(
+        self,
+        request_context:RequestContextTransfers,
+        authentication:Authentication,
+        response:Response
+    ) -> bool:
+        """Check if authorization should be regenerated."""
+        return (
+            authentication.user.is_authenticated
             and authentication.credentials.token.type == BaseEnums.TokenType.REFRESH
-            and (response.status_code >= 200 and response.status_code < 300)
-            and "logout" not in request.url.path
-        ):
-            #* Regenerate new authorization
-            payload = (
-                MaleoFoundationTokenGeneralTransfers
-                .BaseEncodePayload
-                .model_validate(authentication.credentials.token.payload.model_dump())
-            )
-            parameters = (
-                MaleoFoundationTokenParametersTransfers
-                .Encode(key=self._keys.private, password=self._keys.password, payload=payload)
-            )
-            result = self._maleo_foundation.services.token.encode(parameters=parameters)
-            if result.success:
-                response.headers["X-New-Authorization"] = result.data.token
-        return response
+            and 200 <= response.status_code < 300
+            and "logout" not in request_context.url
+        )
+
+class RequestLogger:
+    """Handles request/response logging."""
+
+    def __init__(self, logger:MiddlewareLogger):
+        self.logger = logger
 
-    def _build_response(
+    def log_request_response(
         self,
-        request:Request,
         authentication:Authentication,
-        authentication_info:str,
         response:Response,
-        request_timestamp:datetime,
-        response_timestamp:datetime,
-        process_time:int,
-        log_level:str = "info",
-        client_ip:str = "unknown"
-    ) -> Response:
-        response = self._add_response_headers(
-            request,
-            authentication,
-            response,
-            request_timestamp,
-            response_timestamp,
-            process_time
-        )
-        log_func = getattr(self._logger, log_level)
+        request_context:RequestContextTransfers,
+        log_level:str = "info"
+    ) -> None:
+        """Log request and response details."""
+        authentication_info = self._get_authentication_info(authentication)
+
+        log_func = getattr(self.logger, log_level)
         log_func(
-            f"Request {authentication_info} | IP: {client_ip} | Host: {request.client.host} | Port: {request.client.port} | Method: {request.method} | URL: {request.url.path} | "
-            f"Headers: {dict(request.headers)} - Response | Status: {response.status_code}"
+            f"Request | ID: {request_context.request_id} {authentication_info} | "
+            f"IP: {request_context.ip_address} | Host: {request_context.host} | "
+            f"Method: {request_context.method} | URL: {request_context.url} - "
+            f"Response | Status: {response.status_code}"
         )
-        return response
-
-    def _handle_exception(
+    
+    def log_exception(
         self,
-        request:Request,
         authentication:Authentication,
-        authentication_info:str,
-        error,
-        request_timestamp:datetime,
-        response_timestamp:datetime,
-        process_time:int,
-        client_ip:str = "unknown"
-    ):
-        traceback_str = traceback.format_exc().split("\n")
+        error:Exception,
+        request_context:RequestContextTransfers
+    ) -> None:
+        """Log exception details."""
+        authentication_info = self._get_authentication_info(authentication)
+
         error_details = {
+            "request_context": request_context.model_dump(mode="json"),
             "error": str(error),
-            "traceback": traceback_str,
-            "client_ip": client_ip,
-            "method": request.method,
-            "url": request.url.path,
-            "headers": dict(request.headers),
+            "traceback": traceback.format_exc().split("\n")
         }
 
-        response = JSONResponse(
-            content=BaseResponses.ServerError().model_dump(),
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        self.logger.error(
+            f"Request | ID: {request_context.request_id} {authentication_info} | "
+            f"IP: {request_context.ip_address} | Host: {request_context.host} | "
+            f"Method: {request_context.method} | URL: {request_context.url} - "
+            f"Response | Status: 500 | Exception:\n{json.dumps(error_details, indent=4)}"
         )
 
-        self._logger.error(
-            f"Request {authentication_info} | IP: {client_ip} | Host: {request.client.host} | Port: {request.client.port} | Method: {request.method} | URL: {request.url.path} | "
-            f"Headers: {dict(request.headers)} - Response | Status: 500 | Exception:\n{json.dumps(error_details, indent=4)}"
-        )
+    def _get_authentication_info(self, authentication:Authentication) -> str:
+        """Get authentication info string."""
+        if not authentication.user.is_authenticated:
+            return "| Unauthenticated"
 
-        return self._add_response_headers(
-            request,
-            authentication,
-            response,
-            request_timestamp,
-            response_timestamp,
-            process_time
+        return (
+            f"| Token type: {authentication.credentials.token.type} | "
+            f"Username: {authentication.user.display_name} | "
+            f"Email: {authentication.user.identity}"
         )
 
-    async def _request_processor(self, request:Request) -> Optional[Response]:
-        return None
 
-    async def dispatch(self, request:Request, call_next:RequestResponseEndpoint):
-        self._cleanup_old_data() #* Run periodic cleanup
-        request_timestamp = datetime.now(tz=timezone.utc) #* Record the request timestamp
-        start_time = time.perf_counter() #* Record the start time
-        client_ip = BaseExtractors.extract_client_ip(request) #* Get request IP with improved extraction
-        authentication = Authentication(
-            credentials=request.auth,
-            user=request.user
+class BaseMiddleware(BaseHTTPMiddleware):
+    """Base middleware with rate limiting, logging, and response enhancement."""
+
+    def __init__(
+        self,
+        app:FastAPI,
+        keys:BaseGeneralSchemas.RSAKeys,
+        logger:MiddlewareLogger,
+        maleo_foundation:MaleoFoundationClientManager,
+        allow_origins:Sequence[str] = (),
+        allow_methods:Sequence[str] = ("GET",),
+        allow_headers:Sequence[str] = (),
+        allow_credentials:bool = False,
+        limit:int = 10,
+        window:int = 1,
+        cleanup_interval:int = 60,
+        ip_timeout:int = 300
+    ):
+        super().__init__(app)
+
+        # Core components
+        self.rate_limiter = RateLimiter(
+            limit=limit,
+            window=timedelta(seconds=window),
+            ip_timeout=timedelta(seconds=ip_timeout),
+            cleanup_interval=timedelta(seconds=cleanup_interval)
         )
-        if not authentication.user.is_authenticated:
-            authentication_info = "| Unauthenticated"
-        else:
-            authentication_info = f"| Token type: {authentication.credentials.token.type} | Username: {authentication.user.display_name} | Email:{authentication.user.identity}"
+        self.response_builder = ResponseBuilder(keys, maleo_foundation)
+        self.request_logger = RequestLogger(logger)
+
+        # CORS settings (if needed)
+        self.cors_config = {
+            'allow_origins': allow_origins,
+            'allow_methods': allow_methods,
+            'allow_headers': allow_headers,
+            'allow_credentials': allow_credentials,
+        }
+
+    async def dispatch(self, request:Request, call_next:RequestResponseEndpoint) -> Response:
+        """Main middleware dispatch method."""
+        # Setup
+        self.rate_limiter.cleanup_old_data(self.request_logger.logger)
+        request_context = extract_request_context(request)
+        request.state.request_context = request_context
+        start_time = time.perf_counter()
+        authentication = Authentication(credentials=request.auth, user=request.user)
 
         try:
-            #* 1. Rate limit check
-            if self._check_rate_limit(client_ip):
-                return self._build_response(
-                    request=request,
-                    authentication=authentication,
-                    authentication_info=authentication_info,
-                    response=JSONResponse(
-                        content=BaseResponses.RateLimitExceeded().model_dump(),
-                        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
-                    ),
-                    request_timestamp=request_timestamp,
-                    response_timestamp=datetime.now(tz=timezone.utc),
-                    process_time=time.perf_counter() - start_time,
-                    log_level="warning",
-                    client_ip=client_ip,
+            # Rate limiting check
+            if self.rate_limiter.is_rate_limited(request_context):
+                return self._create_rate_limit_response(
+                    authentication, request_context, start_time
                 )
 
-            #* 2. Optional preprocessing
+            # Optional preprocessing
             pre_response = await self._request_processor(request)
             if pre_response is not None:
-                return self._build_response(
-                    request=request,
-                    authentication=authentication,
-                    authentication_info=authentication_info,
-                    response=pre_response,
-                    request_timestamp=request_timestamp,
-                    response_timestamp=datetime.now(tz=timezone.utc),
-                    process_time=time.perf_counter() - start_time,
-                    log_level="info",
-                    client_ip=client_ip,
+                return self._build_final_response(
+                    authentication, pre_response, request_context, start_time
                 )
 
-            #* 3. Main handler
+            # Main request processing
             response = await call_next(request)
-            response = self._build_response(
-                request=request,
-                authentication=authentication,
-                authentication_info=authentication_info,
-                response=response,
-                request_timestamp=request_timestamp,
-                response_timestamp=datetime.now(tz=timezone.utc),
-                process_time=time.perf_counter() - start_time,
-                log_level="info",
-                client_ip=client_ip,
+            return self._build_final_response(
+                authentication, response, request_context, start_time
             )
 
-            return response
-
         except Exception as e:
             return self._handle_exception(
-                request=request,
-                authentication=authentication,
-                authentication_info=authentication_info,
-                error=e,
-                request_timestamp=request_timestamp,
-                response_timestamp=datetime.now(tz=timezone.utc),
-                process_time=time.perf_counter() - start_time,
-                client_ip=client_ip
+                request, authentication, e, request_context, start_time
             )
 
+    async def _request_processor(self, request:Request) -> Optional[Response]:
+        """Override this method for custom request preprocessing."""
+        return None
+
+    def _create_rate_limit_response(
+        self,
+        authentication:Authentication,
+        request_context:RequestContextTransfers,
+        start_time:float
+    ) -> Response:
+        """Create rate limit exceeded response."""
+        response = JSONResponse(
+            content=BaseResponses.RateLimitExceeded().model_dump(),
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+        )
+        
+        return self._build_final_response(
+            authentication, response, request_context, start_time, log_level="warning"
+        )
+
+    def _build_final_response(
+        self,
+        authentication:Authentication,
+        response:Response,
+        request_context:RequestContextTransfers,
+        start_time:float,
+        log_level:str = "info"
+    ) -> Response:
+        """Build final response with headers and logging."""
+        responded_at = datetime.now(tz=timezone.utc)
+        process_time = time.perf_counter() - start_time
+        
+        # Add headers
+        response = self.response_builder.add_response_headers(
+            authentication, response, request_context, responded_at, process_time
+        )
+
+        # Log request/response
+        self.request_logger.log_request_response(
+            authentication, response, request_context, log_level
+        )
+
+        return response
+
+    def _handle_exception(
+        self,
+        authentication:Authentication,
+        error:Exception,
+        request_context:RequestContextTransfers,
+        start_time:float
+    ) -> Response:
+        """Handle exceptions and create error response."""
+        responded_at = datetime.now(tz=timezone.utc)
+        process_time = time.perf_counter() - start_time
+        
+        response = JSONResponse(
+            content=BaseResponses.ServerError().model_dump(),
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+        # Log exception
+        self.request_logger.log_exception(authentication, error, request_context)
+        
+        # Add headers
+        return self.response_builder.add_response_headers(
+            authentication, response, request_context, responded_at, process_time
+        )
+
+
 def add_base_middleware(
     app:FastAPI,
     keys:BaseGeneralSchemas.RSAKeys,
@@ -316,39 +411,35 @@ def add_base_middleware(
     ip_timeout:int = 300
 ) -> None:
     """
-    Adds Base middleware to the FastAPI application.
+    Add Base middleware to the FastAPI application.
 
     Args:
-        app: FastAPI
-            The FastAPI application instance to which the middleware will be added.
-
-        logger: Logger
-            The middleware logger to be used.
-
-        limit: int
-            Request count limit in a specific window of time
-
-        window: int
-            Time window for rate limiting (in seconds).
-
-        cleanup_interval: int
-            How often to clean up old IP data (in seconds).
-
-        ip_timeout: int
-            How long to keep an IP in memory after its last activity (in seconds).
-            Default is 300 seconds (5 minutes).
-
-    Returns:
-        None: The function modifies the FastAPI app by adding Base middleware.
-
-    Note:
-        FastAPI applies middleware in reverse order of registration, so this middleware
-        will execute after any middleware added subsequently.
+        app:FastAPI application instance
+        keys:RSA keys for signing and token generation
+        logger:Middleware logger instance
+        maleo_foundation:Client manager for foundation services
+        allow_origins:CORS allowed origins
+        allow_methods:CORS allowed methods
+        allow_headers:CORS allowed headers
+        allow_credentials:CORS allow credentials flag
+        limit:Request count limit per window
+        window:Time window for rate limiting (seconds)
+        cleanup_interval:Cleanup interval for old IP data (seconds)
+        ip_timeout:IP timeout after last activity (seconds)
 
     Example:
-    ```python
-    add_base_middleware(app=app, limit=10, window=1, cleanup_interval=60, ip_timeout=300)
-    ```
+        ```python
+        add_base_middleware(
+            app=app,
+            keys=rsa_keys,
+            logger=middleware_logger,
+            maleo_foundation=client_manager,
+            limit=10,
+            window=1,
+            cleanup_interval=60,
+            ip_timeout=300
+        )
+        ```
     """
     app.add_middleware(
         BaseMiddleware,

maleo_foundation/models/transfers/general/__init__.py

@@ -1,5 +1,10 @@
 from __future__ import annotations
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+from typing import Dict
+from uuid import UUID
 from maleo_foundation.models.schemas.general import BaseGeneralSchemas
+from maleo_foundation.types import BaseTypes
 from .token import MaleoFoundationTokenGeneralTransfers
 
 class BaseGeneralTransfers:
@@ -8,4 +13,23 @@ class BaseGeneralTransfers:
 class AccessTransfers(
     BaseGeneralSchemas.AccessedBy,
     BaseGeneralSchemas.AccessedAt
-): pass
+): pass
+
+class RequestContextTransfers(BaseModel):
+    request_id:UUID = Field(..., description="Unique identifier for tracing the request")
+    requested_at:datetime = Field(datetime.now(tz=timezone.utc), description="Request timestamp")
+    method:str = Field(..., description="Request's method")
+    url:str = Field(..., description="Request's URL")
+    path_params:Dict = Field(..., description="Request's path parameters")
+    query_params:Dict = Field(..., description="Request's query parameters")
+    ip_address:str = Field("unknown", description="Client's IP address")
+    is_internal:BaseTypes.OptionalBoolean = Field(None, description="True if IP is internal")
+    user_agent:BaseTypes.OptionalString = Field(None, description="User-Agent string")
+    ua_browser:BaseTypes.OptionalString = Field(None, description="Browser info from sec-ch-ua")
+    ua_mobile:BaseTypes.OptionalString = Field(None, description="Is mobile device?")
+    platform:BaseTypes.OptionalString = Field(None, description="Client platform or OS")
+    referer:BaseTypes.OptionalString = Field(None, description="Referrer URL")
+    origin:BaseTypes.OptionalString = Field(None, description="Origin of the request")
+    host:BaseTypes.OptionalString = Field(None, description="Host header from request")
+    forwarded_proto:BaseTypes.OptionalString = Field(None, description="Forwarded protocol (http/https)")
+    language:BaseTypes.OptionalString = Field(None, description="Accepted languages from client")

maleo_foundation/utils/dependencies/context.py

@@ -0,0 +1,9 @@
+from fastapi.requests import Request
+from maleo_foundation.models.transfers.general import RequestContextTransfers
+
+class ContextDependencies:
+    @staticmethod
+    def get_request_context(
+        request:Request
+    ) -> RequestContextTransfers:
+        return request.state.request_context

maleo_foundation/utils/extractor.py

@@ -1,20 +1,55 @@
+from datetime import datetime, timezone
+from fastapi import Request
 from starlette.requests import HTTPConnection
+from uuid import uuid4
+from maleo_foundation.models.transfers.general import RequestContextTransfers
 
-class BaseExtractors:
-    @staticmethod
-    def extract_client_ip(conn:HTTPConnection) -> str:
-        """Extract client IP with more robust handling of proxies"""
-        #* Check for X-Forwarded-For header (common when behind proxy/load balancer)
-        x_forwarded_for = conn.headers.get("X-Forwarded-For")
-        if x_forwarded_for:
-            #* The client's IP is the first one in the list
-            ips = [ip.strip() for ip in x_forwarded_for.split(",")]
-            return ips[0]
-
-        #* Check for X-Real-IP header (used by some proxies)
-        x_real_ip = conn.headers.get("X-Real-IP")
-        if x_real_ip:
-            return x_real_ip
-
-        #* Fall back to direct client connection
-        return conn.client.host if conn.client else "unknown"
+def extract_client_ip(conn:HTTPConnection) -> str:
+    """Extract client IP with more robust handling of proxies"""
+    #* Check for X-Forwarded-For header (common when behind proxy/load balancer)
+    x_forwarded_for = conn.headers.get("X-Forwarded-For")
+    if x_forwarded_for:
+        #* The client's IP is the first one in the list
+        ips = [ip.strip() for ip in x_forwarded_for.split(",")]
+        return ips[0]
+
+    #* Check for X-Real-IP header (used by some proxies)
+    x_real_ip = conn.headers.get("X-Real-IP")
+    if x_real_ip:
+        return x_real_ip
+
+    #* Fall back to direct client connection
+    return conn.client.host if conn.client else "unknown"
+
+def extract_request_context(request:Request) -> RequestContextTransfers:
+    headers = request.headers
+
+    request_id = headers.get("x-request-id")
+    if request_id is None:
+        request_id = uuid4()
+
+    ip_address = extract_client_ip(request)
+
+    ua_browser = headers.get("sec-ch-ua", "")
+    if ua_browser:
+        ua_browser = ua_browser.replace('"', "").split(",")[0].strip()
+
+    return RequestContextTransfers(
+        request_id=request_id,
+        requested_at=datetime.now(tz=timezone.utc),
+        method=request.method,
+        url=request.url.path,
+        path_params=dict(request.path_params),
+        query_params=dict(request.query_params),
+        ip_address=ip_address,
+        is_internal=ip_address.startswith("10.") or ip_address.startswith("192.168.") or ip_address.startswith("172."),
+        user_agent=headers.get("user-agent"),
+        ua_browser=ua_browser,
+        ua_mobile=headers.get("sec-ch-ua-mobile"),
+        platform=headers.get("sec-ch-ua-platform"),
+        referer=headers.get("referer"),
+        origin=headers.get("origin"),
+        host=headers.get("host"),
+        forwarded_proto=headers.get("x-forwarded-proto"),
+        language=headers.get("accept-language"),
+    )

{maleo_foundation-0.2.78.dist-info → maleo_foundation-0.2.81.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maleo_foundation
-Version: 0.2.78
+Version: 0.2.81
 Summary: Foundation package for Maleo
 Author-email: Agra Bima Yuda <agra@nexmedis.com>
 License: MIT

{maleo_foundation-0.2.78.dist-info → maleo_foundation-0.2.81.dist-info}/RECORD

@@ -34,7 +34,7 @@ maleo_foundation/expanded_types/encryption/rsa.py,sha256=Esf_H8nMz2kOLAWa3M7dlD-
 maleo_foundation/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maleo_foundation/managers/db.py,sha256=cpY1IOiUytT9XXYtzS0E9OSYOuB7jBKo0XHe__uI1Jg,5340
 maleo_foundation/managers/middleware.py,sha256=77wRCC_CWc22nSDL-UJanO3rXmSB7wLzaAIXEFjXq6M,4249
-maleo_foundation/managers/service.py,sha256=_0eme0NQMsf_8UlLmrLkD9OzHrLbrKjMYUNGYcA0EPI,19179
+maleo_foundation/managers/service.py,sha256=9qPmOUh5PPXu03-xnZIRU4C3mNbMOnYrfJQs87oqt6k,19282
 maleo_foundation/managers/cache/__init__.py,sha256=CeY0oof2bVl_v5WS-FKXNwn2gf3xrEMfUsHK9cHo59s,471
 maleo_foundation/managers/cache/base.py,sha256=YyPjde4KTsp2IHV6NdFMysa0ev-1GX1rtX-0jQPuIBU,837
 maleo_foundation/managers/cache/redis.py,sha256=xLa8QfXdNtghs0eBxIqc04H3XTYmxLEzrqJZAFCigvM,1150
@@ -47,7 +47,7 @@ maleo_foundation/managers/client/google/parameter.py,sha256=Lnj7mQgxWQpsQwbmDRK5
 maleo_foundation/managers/client/google/secret.py,sha256=Ski1CHYeA8vjSk2Oc2Pf4CfFrzT_RcA6NEZwza7gM7Y,4464
 maleo_foundation/managers/client/google/storage.py,sha256=Hq79cVreWR2AGwUzpD57NzziZjqxj__TqYIBRy-A9A0,5340
 maleo_foundation/middlewares/authentication.py,sha256=UL6kL65SvqrzemlIDopoO9N1C05eWlYMHVR2tiRsVEA,4821
-maleo_foundation/middlewares/base.py,sha256=fLctfwzfWlGSPFnSiqbV-9wDhlG2SLA1DAs-hXk0diU,14600
+maleo_foundation/middlewares/base.py,sha256=r3XDTEhK6BB8YZ1Y8oyqExY78s4yzOqX7s7XokRlTlw,16308
 maleo_foundation/middlewares/cors.py,sha256=9uvBvY2N6Vxa9RP_YtESxcWo6Doi6uS0lzAG9iLY7Uc,2288
 maleo_foundation/models/__init__.py,sha256=AaKehO7c1HyKhoTGRmNHDddSeBXkW-_YNrpOGBu8Ms8,246
 maleo_foundation/models/responses.py,sha256=nE5qThK-WgcYB-9J4wHzJltMA3PLmWbMI-dkxAxAdII,5631
@@ -62,7 +62,7 @@ maleo_foundation/models/schemas/result.py,sha256=MaWDyKGvZu0IcvKMj30lrMXojGV9Mhi
 maleo_foundation/models/schemas/signature.py,sha256=-5ldTnJsjwqPRbHw7PFcLKITqEXJ_qKDdRHShK75NVA,620
 maleo_foundation/models/schemas/token.py,sha256=RYq8v1T_WZIu8lcjwyV6Pp7ZjFkr_lW9x6QyDmXBsfw,563
 maleo_foundation/models/transfers/__init__.py,sha256=oJLJ3Geeme6vBw7R2Dhvdvg4ziVvzEYAGJaP-tm_90w,299
-maleo_foundation/models/transfers/general/__init__.py,sha256=7yQNGSihJt1db6i_zIrhLdY2Tgn5lrTxuDlAVlDh2vo,340
+maleo_foundation/models/transfers/general/__init__.py,sha256=IOt9afCpDu7bO0rkZLiiLLP37w5rIZTxmnv6MD9od8E,1990
 maleo_foundation/models/transfers/general/key.py,sha256=tLKkXbwNu7Oc1MdKa8-Y7TlBAIk54h_02AmL5Yg2PrQ,751
 maleo_foundation/models/transfers/general/signature.py,sha256=J9xQy2HjpCQOnES7RJqsUnDgjFPuakQ1mxyfdTdstSE,297
 maleo_foundation/models/transfers/general/token.py,sha256=O_U6dQS7oMScJzqufl6Pe21pTxMsYhOzKH8aFLxjblQ,2895
@@ -101,7 +101,7 @@ maleo_foundation/utils/__init__.py,sha256=KoERe8U2ERGZeAKUNBPW_itk7g9YpH7v7_mD9_
 maleo_foundation/utils/client.py,sha256=F5X9TUxWQgeOHjwsMpPoSRhZANQYZ_iFv0RJDTUVhrw,2820
 maleo_foundation/utils/controller.py,sha256=D8uUfqkMpPw8M8Ykn8Uxn7dfRGwxmBxSP1h9xSkYw1I,6945
 maleo_foundation/utils/exceptions.py,sha256=eM__Mxo-BC5d7JmoBd-Wh-fmryUdfjNfOuY_eONK5Fk,6361
-maleo_foundation/utils/extractor.py,sha256=SZXVYDHWGaA-Dd1BUydwF2HHdZqexEielS4CjL0Ceng,814
+maleo_foundation/utils/extractor.py,sha256=0HoJ0hLqt3-izaekjPfxqWjvUmXTsm4Muyttu0_VyuI,2109
 maleo_foundation/utils/logging.py,sha256=W5Fhk_xAXVqSujaY8mv3hRH4wlQSpUn4ReuMoiKcQa4,7759
 maleo_foundation/utils/merger.py,sha256=z9GROLVtGpwx84bOiakBFphKazsI-9l3F3WauTDwQLs,597
 maleo_foundation/utils/query.py,sha256=nDj-9Q-5eAOvqXqKgKjtHaFAxVAY87E0BMaVXmTN7jA,7957
@@ -109,6 +109,7 @@ maleo_foundation/utils/repository.py,sha256=knBi3xOLlhBIEtChvqbZh4wXmgrFCB3rDwQX
 maleo_foundation/utils/searcher.py,sha256=gsseMkr0swKj3l-xil5qqncTbYNkS96eieFE_ehaF8I,504
 maleo_foundation/utils/dependencies/__init__.py,sha256=0KKGrdfj8Cc5A4SRk_ZBAxzOP795Mizdb4zIBh07KC4,122
 maleo_foundation/utils/dependencies/auth.py,sha256=wS9qnmd1n2WsFhiSfyq_3Io3wwZKTENVPv4rMwxJslE,727
+maleo_foundation/utils/dependencies/context.py,sha256=OXem2E00u2D3GleXhV8VI3u0cayG2CZpvVz32a0xHhs,292
 maleo_foundation/utils/formatter/__init__.py,sha256=iKf5YCbEdg1qKnFHyKqqcQbqAqEeRUf8mhI3v3dQoj8,78
 maleo_foundation/utils/formatter/case.py,sha256=TmvvlfzGdC_omMTB5vAa40TZBxQ3hnr-SYeo0M52Rlg,1352
 maleo_foundation/utils/loaders/__init__.py,sha256=P_3ycGfeDXFjAi8bE4iLWHxBveqUIdpHgGv-klRWM3s,282
@@ -118,7 +119,7 @@ maleo_foundation/utils/loaders/credential/__init__.py,sha256=qopTKvcMVoTFwyRijeg
 maleo_foundation/utils/loaders/credential/google.py,sha256=HUcuHD4tXHPt0eHInlFYxA_MDrGSOtbenpd0PX156OM,1255
 maleo_foundation/utils/loaders/key/__init__.py,sha256=hVygcC2ImHc_aVrSrOmyedR8tMUZokWUKCKOSh5ctbo,106
 maleo_foundation/utils/loaders/key/rsa.py,sha256=gDhyX6iTFtHiluuhFCozaZ3pOLKU2Y9TlrNMK_GVyGU,3796
-maleo_foundation-0.2.78.dist-info/METADATA,sha256=ClqJ8m73PDVT6xirjl0uPeyFm_r93Lk9Lkm1DyfoLOY,3598
-maleo_foundation-0.2.78.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-maleo_foundation-0.2.78.dist-info/top_level.txt,sha256=_iBos3F_bhEOdjOnzeiEYSrCucasc810xXtLBXI8cQc,17
-maleo_foundation-0.2.78.dist-info/RECORD,,
+maleo_foundation-0.2.81.dist-info/METADATA,sha256=JLiCodCLzxMikL7jL0H8wQRjpRvlolRdVr-_iSfz0xM,3598
+maleo_foundation-0.2.81.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+maleo_foundation-0.2.81.dist-info/top_level.txt,sha256=_iBos3F_bhEOdjOnzeiEYSrCucasc810xXtLBXI8cQc,17
+maleo_foundation-0.2.81.dist-info/RECORD,,