maleo-foundation 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

maleo_foundation/clients/general/http.py

@@ -3,21 +3,21 @@ from contextlib import asynccontextmanager
 from typing import AsyncGenerator, Optional
 
 class HTTPClientManager:
-    _client:Optional[httpx.AsyncClient] = None
+    client:Optional[httpx.AsyncClient] = None
 
     @classmethod
     def initialize(cls) -> None:
         """Initialize the HTTP client if not already initialized."""
-        if cls._client is None:
-            cls._client = httpx.AsyncClient()
+        if cls.client is None:
+            cls.client = httpx.AsyncClient()
 
     @classmethod
     async def _client_handler(cls) -> AsyncGenerator[httpx.AsyncClient, None]:
         """Reusable generator for client handling."""
-        if cls._client is None:
+        if cls.client is None:
             raise RuntimeError("Client has not been initialized. Call initialize first.")
 
-        yield cls._client
+        yield cls.client
 
     @classmethod
     async def inject(cls) -> AsyncGenerator[httpx.AsyncClient, None]:
@@ -36,6 +36,6 @@ class HTTPClientManager:
     @classmethod
     async def dispose(cls) -> None:
         """Dispose of the HTTP client and release any resources."""
-        if cls._client is not None:
-            await cls._client.aclose()
-            cls._client = None
+        if cls.client is not None:
+            await cls.client.aclose()
+            cls.client = None

maleo_foundation/middlewares/__init__.py

@@ -0,0 +1,98 @@
+from fastapi import FastAPI
+from logging import Logger
+from typing import Optional, Sequence
+from .base import add_base_middleware, RequestProcessor
+from .cors import add_cors_middleware
+
+class MiddlewareManager:
+    _default_limit:int = 10
+    _default_window:int = 1
+    _default_cleanup_interval:int = 60
+    _default_ip_timeout:int = 300
+    _default_allow_origins:Sequence[str] = ()
+    _default_allow_methods:Sequence[str] = ("GET",)
+    _default_allow_headers:Sequence[str] = ()
+    _default_allow_credentials:bool = False
+    _default_expose_headers:Sequence[str] = ()
+    _default_request_processor:Optional[RequestProcessor] = None
+
+    def __init__(self, app:FastAPI):
+        self.app = app
+
+    def add_all_middlewares(
+        self,
+        logger:Logger,
+        limit:int = _default_limit,
+        window:int = _default_window,
+        cleanup_interval:int = _default_cleanup_interval,
+        ip_timeout:int = _default_ip_timeout,
+        allow_origins:Sequence[str] = _default_allow_origins,
+        allow_methods:Sequence[str] = _default_allow_methods,
+        allow_headers:Sequence[str] = _default_allow_headers,
+        allow_credentials:bool = _default_allow_credentials,
+        expose_headers:Sequence[str] = _default_expose_headers,
+        request_processor:Optional[RequestProcessor] = _default_request_processor
+    ):
+        self.add_cors_middleware(
+            allow_origins=allow_origins,
+            allow_methods=allow_methods,
+            allow_headers=allow_headers,
+            allow_credentials=allow_credentials,
+            expose_headers=expose_headers
+        )
+        self.add_base_middleware(
+            logger=logger,
+            allow_origins=allow_origins,
+            allow_methods=allow_methods,
+            allow_headers=allow_headers,
+            allow_credentials=allow_credentials,
+            limit=limit,
+            window=window,
+            cleanup_interval=cleanup_interval,
+            ip_timeout=ip_timeout,
+            request_processor=request_processor
+        )
+
+    def add_cors_middleware(
+        self,
+        allow_origins:Sequence[str] = _default_allow_origins,
+        allow_methods:Sequence[str] = _default_allow_methods,
+        allow_headers:Sequence[str] = _default_allow_headers,
+        allow_credentials:bool = _default_allow_credentials,
+        expose_headers:Sequence[str] = _default_expose_headers
+    ):
+        add_cors_middleware(
+            app=self.app,
+            allow_origins=allow_origins,
+            allow_methods=allow_methods,
+            allow_headers=allow_headers,
+            allow_credentials=allow_credentials,
+            expose_headers=expose_headers
+        )
+
+    def add_base_middleware(
+        self,
+        logger:Logger,
+        allow_origins:Sequence[str] = _default_allow_origins,
+        allow_methods:Sequence[str] = _default_allow_methods,
+        allow_headers:Sequence[str] = _default_allow_headers,
+        allow_credentials:bool = _default_allow_credentials,
+        limit:int = _default_limit,
+        window:int = _default_window,
+        cleanup_interval:int = _default_cleanup_interval,
+        ip_timeout:int = _default_ip_timeout,
+        request_processor:Optional[RequestProcessor] = _default_request_processor
+    ):
+        add_base_middleware(
+            app=self.app,
+            logger=logger,
+            allow_origins=allow_origins,
+            allow_methods=allow_methods,
+            allow_headers=allow_headers,
+            allow_credentials=allow_credentials,
+            limit=limit,
+            window=window,
+            cleanup_interval=cleanup_interval,
+            ip_timeout=ip_timeout,
+            request_processor=request_processor
+        )

maleo_foundation/middlewares/base.py

@@ -0,0 +1,286 @@
+import json
+import threading
+import time
+import traceback
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from fastapi import FastAPI, Request, Response, status
+from fastapi.responses import JSONResponse
+from logging import Logger
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from typing import Awaitable, Callable, Optional, Sequence
+from maleo_foundation.models.responses import BaseResponses
+
+RequestProcessor = Callable[[Request], Awaitable[Optional[Response]]]
+ResponseProcessor = Callable[[Response], Awaitable[Response]]
+
+class BaseMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app,
+        logger:Logger,
+        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,
+        request_processor:Optional[RequestProcessor] = None
+    ):
+        super().__init__(app)
+        self.logger = logger
+        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.last_cleanup = datetime.now()
+        self.request_processor = request_processor if request_processor is not None else self._request_processor
+        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 _extract_client_ip(self, request:Request) -> 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 = request.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 = request.headers.get("X-Real-IP")
+        if x_real_ip:
+            return x_real_ip
+            
+        #* Fall back to direct client connection
+        return request.client.host if request.client else "unknown"
+
+    def _check_rate_limit(self, client_ip:str) -> bool:
+        """Check if the client has exceeded their rate limit"""
+        with self._lock:
+            now = datetime.now() #* Define current timestamp
+            self.last_seen[client_ip] = now #* Update last seen timestamp for this IP
+
+            #* Filter requests within the window
+            self.requests[client_ip] = [timestamp for timestamp in self.requests[client_ip] if now - timestamp <= self.window]
+
+            #* Check if the request count exceeds the limit
+            if len(self.requests[client_ip]) >= self.limit:
+                return True
+
+            #* Add the current request timestamp
+            self.requests[client_ip].append(now)
+            return False
+
+    def _append_cors_headers(self, request:Request, response:Response) -> Response:
+        origin = request.headers.get("Origin")
+
+        if origin in self.allow_origins:
+            response.headers["Access-Control-Allow-Origin"] = origin
+            response.headers["Access-Control-Allow-Methods"] = ", ".join(self.allow_methods)
+            response.headers["Access-Control-Allow-Headers"] = ", ".join(self.allow_headers)
+            response.headers["Access-Control-Allow-Credentials"] = "true" if self.allow_credentials else "false"
+
+        return response
+
+    def _add_response_headers(self, request:Request, response:Response, request_timestamp:datetime, process_time:int) -> 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"] = datetime.now(tz=timezone.utc).isoformat() #* Add response timestamp header
+        response = self._append_cors_headers(request=request, response=response) #* Re-append CORS headers
+        return response
+
+    def _build_response(
+        self,
+        request:Request,
+        response:Response,
+        request_timestamp:datetime,
+        process_time:int,
+        log_level:str = "info",
+        client_ip:str = "unknown"
+    ) -> Response:
+        response = self._add_response_headers(request, response, request_timestamp, process_time)
+        log_func = getattr(self.logger, log_level)
+        log_func(
+            f"Request | IP: {client_ip} | Method: {request.method} | URL: {request.url.path} | "
+            f"Headers: {dict(request.headers)} - Response | Status: {response.status_code} | "
+        )
+        return response
+
+    def _handle_exception(self, request:Request, error, request_timestamp:datetime, process_time:int, client_ip):
+        traceback_str = traceback.format_exc().split("\n")
+        error_details = {
+            "error": str(error),
+            "traceback": traceback_str,
+            "client_ip": client_ip,
+            "method": request.method,
+            "url": request.url.path,
+            "headers": dict(request.headers),
+        }
+
+        response = JSONResponse(
+            content=BaseResponses.ServerError().model_dump(),
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+        self.logger.error(
+            f"Request | IP: {client_ip} | Method: {request.method} | URL: {request.url.path} | "
+            f"Headers: {dict(request.headers)} - Response | Status: 500 | Exception:\n{json.dumps(error_details, indent=4)}"
+        )
+
+        return self._add_response_headers(request, response, request_timestamp, process_time)
+
+    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 = self._extract_client_ip(request) #* Get request IP with improved extraction
+
+        try:
+            #* 1. Rate limit check
+            if self._check_rate_limit(client_ip):
+                return self._build_response(
+                    request=request,
+                    response=JSONResponse(
+                        content=BaseResponses.RateLimitExceeded().model_dump(),
+                        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                    ),
+                    request_timestamp=request_timestamp,
+                    process_time=time.perf_counter() - start_time,
+                    log_level="warning",
+                    client_ip=client_ip,
+                )
+
+            #* 2. Optional preprocessing
+            pre_response = await self.request_processor(request)
+            if pre_response is not None:
+                return self._build_response(
+                    request=request,
+                    response=pre_response,
+                    request_timestamp=request_timestamp,
+                    process_time=time.perf_counter() - start_time,
+                    log_level="info",
+                    client_ip=client_ip,
+                )
+
+            #* 3. Main handler
+            response = await call_next(request)
+            response = self._build_response(
+                request=request,
+                response=response,
+                request_timestamp=request_timestamp,
+                process_time=time.perf_counter() - start_time,
+                log_level="info",
+                client_ip=client_ip,
+            )
+
+            return response
+
+        except Exception as e:
+            return self._handle_exception(request, e, request_timestamp, time.perf_counter() - start_time, client_ip)
+
+def add_base_middleware(
+    app:FastAPI,
+    logger:Logger,
+    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,
+    request_processor:Optional[RequestProcessor] = None
+) -> None:
+    """
+    Adds 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.
+
+    Example:
+    ```python
+    add_base_middleware(app=app, limit=10, window=1, cleanup_interval=60, ip_timeout=300)
+    ```
+    """
+    app.add_middleware(
+        BaseMiddleware,
+        logger=logger,
+        allow_origins=allow_origins,
+        allow_methods=allow_methods,
+        allow_headers=allow_headers,
+        allow_credentials=allow_credentials,
+        limit=limit,
+        window=window,
+        cleanup_interval=cleanup_interval,
+        ip_timeout=ip_timeout,
+        request_processor=request_processor
+    )

maleo_foundation/middlewares/cors.py

@@ -0,0 +1,63 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from typing import Sequence
+
+def add_cors_middleware(
+    app:FastAPI,
+    allow_origins:Sequence[str] = (),
+    allow_methods:Sequence[str] = ("GET",),
+    allow_headers:Sequence[str] = (),
+    allow_credentials:bool = False,
+    expose_headers:Sequence[str] = ()
+) -> None:
+    """
+    Adds CORS (Cross-Origin Resource Sharing) middleware to the FastAPI application.
+
+    This middleware allows the server to handle requests from different origins, 
+    which is essential for enabling communication between the backend and frontend hosted on different domains.
+
+    Args:
+        app: FastAPI
+            The FastAPI application instance to which the middleware will be added.
+
+        allow_origins: Sequence[str]
+            A Sequence of allowed origins (e.g., ["http://localhost:3000", "https://example.com"]). 
+            Use ["*"] to allow requests from any origin.
+
+        allow_methods: Sequence[str]
+            A Sequence of allowed HTTP methods (e.g., ["GET", "POST", "PUT", "DELETE"]). 
+            Use ["*"] to allow all methods.
+
+        allow_headers: Sequence[str]
+            A Sequence of allowed request headers (e.g., ["Authorization", "Content-Type"]). 
+            Use ["*"] to allow all headers.
+
+        allow_credentials: bool
+            Indicates whether cookies, authorization headers, or TLS client certificates can be included in the request.
+
+        expose_headers: Sequence[str]
+            A Sequence of response headers that the browser can access (e.g., ["X-Custom-Header", "Content-Disposition"]).
+
+    Returns:
+        None: The function modifies the FastAPI app by adding CORS middleware.
+
+    Example:
+    ```python
+    add_cors_middleware(
+        app=app,
+        allow_origins=["http://localhost:3000"],
+        allow_methods=["GET", "POST", "PUT", "DELETE"],
+        allow_headers=["Authorization", "Content-Type"],
+        allow_credentials=True,
+        expose_headers=["X-Custom-Header"]
+    )
+    ```
+    """
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allow_origins,
+        allow_methods=allow_methods,
+        allow_headers=allow_headers,
+        allow_credentials=allow_credentials,
+        expose_headers=expose_headers
+    )

{maleo_foundation-0.0.3.dist-info → maleo_foundation-0.0.5.dist-info}/METADATA

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

{maleo_foundation-0.0.3.dist-info → maleo_foundation-0.0.5.dist-info}/RECORD

@@ -3,7 +3,7 @@ maleo_foundation/constants.py,sha256=l6WQp0nu2y4Ucs8bFcEdzVUJfR1dRM_nveuHGMhe3rY
 maleo_foundation/controller.py,sha256=91OK1W4MnO85m0GUOQv1F8m50nlTZpZJ2HJcScH7OGA,2980
 maleo_foundation/clients/__init__.py,sha256=W8vydJYeDEi6gdmOZSBFSSDsfZJtb8C05CHErZgsZ30,188
 maleo_foundation/clients/general/__init__.py,sha256=l9eQrBeLW4aXtGU5aK3i6fD-msVR4526W7D9V8WCXIg,91
-maleo_foundation/clients/general/http.py,sha256=cE-sYlC1fXURwxE1d8pgNoUU9GKKSlPbwqF4EbslX8Q,1361
+maleo_foundation/clients/general/http.py,sha256=Awvs470hgdhZSZW_uoIFJGcJ5hcfDEIX0A2yUaP9UCA,1353
 maleo_foundation/clients/google/__init__.py,sha256=1uv6nF9QbATsSAcMimQOT7Y-eBljjDunBojNX6oAtS8,90
 maleo_foundation/clients/google/cloud/__init__.py,sha256=WGMPxEKKdkz3XGY5dZn9E-nYhD1kv1MgRHbmVnky4zk,245
 maleo_foundation/clients/google/cloud/logging.py,sha256=l8EL8rZAf1uatMil_ARmRL0z4K4iX2HqUUpdctNGXMw,1584
@@ -13,6 +13,9 @@ maleo_foundation/db/__init__.py,sha256=fFqGxpsiowiws70AqOfcOWFhwaahfOj9_05JSJ0iR
 maleo_foundation/db/database.py,sha256=RQBWeUearfrgq2L8-8cFVBByjNku9OiY3AmucRWXUOw,2064
 maleo_foundation/db/engine.py,sha256=kw2SMMiWy5KARquh4TLk7v6HwlHW97lUIUvqdFbhNxk,1600
 maleo_foundation/db/session.py,sha256=tI13DJ6rLo8FOpSIFZrmD4dbuxY_c0RTjwEGb76ZOo0,2681
+maleo_foundation/middlewares/__init__.py,sha256=bqE2EIFC3rWcR2AwFPR0fk2kSFfeTRzgA24GbnuT5RA,3697
+maleo_foundation/middlewares/base.py,sha256=KcpODNs0DQXX8Cwc6T9dC6aiZIqxTLtuJjVAGWXPSKk,11633
+maleo_foundation/middlewares/cors.py,sha256=9uvBvY2N6Vxa9RP_YtESxcWo6Doi6uS0lzAG9iLY7Uc,2288
 maleo_foundation/models/__init__.py,sha256=Wh92XAduE1Sg9qi2GMhptyXig0fKcTS5AbGo3tE3tLs,348
 maleo_foundation/models/enums.py,sha256=Ob2v312JxypHEq7hTKZKOV462FEeLkIjIhpx-YF6Jdw,2203
 maleo_foundation/models/responses.py,sha256=z2XEHwuxU05NDJSgrA7B7e2fzEQP6Kl3ZM2BO-lDw_A,3786
@@ -44,7 +47,7 @@ maleo_foundation/utils/exceptions.py,sha256=mcvBwHm6uWpVQkPtO1T2j-GaTYEiyPOeGxiD
 maleo_foundation/utils/logger.py,sha256=ICrFi0MxuAjDy8KTRL7pex1miwzZqZX-HHArgN3niJM,2453
 maleo_foundation/utils/formatter/__init__.py,sha256=iKf5YCbEdg1qKnFHyKqqcQbqAqEeRUf8mhI3v3dQoj8,78
 maleo_foundation/utils/formatter/case.py,sha256=TmvvlfzGdC_omMTB5vAa40TZBxQ3hnr-SYeo0M52Rlg,1352
-maleo_foundation-0.0.3.dist-info/METADATA,sha256=lWTnBmXUOk40L3zgDxdlzSxd95bihx8hOdXKePMrHdA,3159
-maleo_foundation-0.0.3.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-maleo_foundation-0.0.3.dist-info/top_level.txt,sha256=_iBos3F_bhEOdjOnzeiEYSrCucasc810xXtLBXI8cQc,17
-maleo_foundation-0.0.3.dist-info/RECORD,,
+maleo_foundation-0.0.5.dist-info/METADATA,sha256=ZoV6fmlg40gLu2oS_bOMIX-oCiT3TWNuiSLBxN_AT2w,3159
+maleo_foundation-0.0.5.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+maleo_foundation-0.0.5.dist-info/top_level.txt,sha256=_iBos3F_bhEOdjOnzeiEYSrCucasc810xXtLBXI8cQc,17
+maleo_foundation-0.0.5.dist-info/RECORD,,