hypern 0.3.0__cp312-cp312-win32.whl → 0.3.2__cp312-cp312-win32.whl

hypern/application.py

@@ -8,7 +8,7 @@ import orjson
 from typing_extensions import Annotated, Doc
 
 from hypern.datastructures import Contact, HTTPMethod, Info, License
-from hypern.hypern import FunctionInfo, Router, Route as InternalRoute, WebsocketRouter
+from hypern.hypern import FunctionInfo, Router, Route as InternalRoute, WebsocketRouter, MiddlewareConfig
 from hypern.openapi import SchemaGenerator, SwaggerUI
 from hypern.processpool import run_processes
 from hypern.response import HTMLResponse, JSONResponse
@@ -17,6 +17,7 @@ from hypern.scheduler import Scheduler
 from hypern.middleware import Middleware
 from hypern.args_parser import ArgsConfig
 from hypern.ws import WebsocketRoute
+from hypern.logging import logger
 
 AppType = TypeVar("AppType", bound="Hypern")
 
@@ -190,6 +191,14 @@ class Hypern:
                 """
             ),
         ] = None,
+        auto_compression: Annotated[
+            bool,
+            Doc(
+                """
+                Enable automatic compression of responses.
+                """
+            ),
+        ] = False,
         *args: Any,
         **kwargs: Any,
     ) -> None:
@@ -202,6 +211,9 @@ class Hypern:
         self.middleware_after_request = []
         self.response_headers = {}
         self.args = ArgsConfig()
+        self.start_up_handler = None
+        self.shutdown_handler = None
+        self.auto_compression = auto_compression
 
         for route in routes or []:
             self.router.extend_route(route(app=self).routes)
@@ -287,10 +299,12 @@ class Hypern:
             function: The decorator function that registers the middleware.
         """
 
+        logger.warning("This functin will be deprecated in version 0.4.0. Please use the middleware class instead.")
+
         def decorator(func):
             is_async = asyncio.iscoroutinefunction(func)
             func_info = FunctionInfo(handler=func, is_async=is_async)
-            self.middleware_before_request.append(func_info)
+            self.middleware_before_request.append((func_info, MiddlewareConfig.default()))
             return func
 
         return decorator
@@ -306,11 +320,12 @@ class Hypern:
         Returns:
             function: The decorator function that registers the given function.
         """
+        logger.warning("This functin will be deprecated in version 0.4.0. Please use the middleware class instead.")
 
         def decorator(func):
             is_async = asyncio.iscoroutinefunction(func)
             func_info = FunctionInfo(handler=func, is_async=is_async)
-            self.middleware_after_request.append(func_info)
+            self.middleware_after_request.append((func_info, MiddlewareConfig.default()))
             return func
 
         return decorator
@@ -346,11 +361,13 @@ class Hypern:
         before_request = getattr(middleware, "before_request", None)
         after_request = getattr(middleware, "after_request", None)
 
-        if before_request:
-            self.before_request()(before_request)
-        if after_request:
-            self.after_request()(after_request)
-        return self
+        is_async = asyncio.iscoroutinefunction(before_request)
+        before_request = FunctionInfo(handler=before_request, is_async=is_async)
+        self.middleware_before_request.append((before_request, middleware.config))
+
+        is_async = asyncio.iscoroutinefunction(after_request)
+        after_request = FunctionInfo(handler=after_request, is_async=is_async)
+        self.middleware_after_request.append((after_request, middleware.config))
 
     def start(
         self,
@@ -377,6 +394,9 @@ class Hypern:
             after_request=self.middleware_after_request,
             response_headers=self.response_headers,
             reload=self.args.reload,
+            on_startup=self.start_up_handler,
+            on_shutdown=self.shutdown_handler,
+            auto_compression=self.args.auto_compression or self.auto_compression,
         )
 
     def add_route(self, method: HTTPMethod, endpoint: str, handler: Callable[..., Any]):
@@ -403,3 +423,22 @@ class Hypern:
         """
         for route in ws_route.routes:
             self.websocket_router.add_route(route=route)
+
+    def on_startup(self, handler: Callable[..., Any]):
+        """
+        Registers a function to be executed on application startup.
+
+        Args:
+            handler (Callable[..., Any]): The function to be executed on application startup.
+        """
+        # decorator
+        self.start_up_handler = FunctionInfo(handler=handler, is_async=asyncio.iscoroutinefunction(handler))
+
+    def on_shutdown(self, handler: Callable[..., Any]):
+        """
+        Registers a function to be executed on application shutdown.
+
+        Args:
+            handler (Callable[..., Any]): The function to be executed on application shutdown.
+        """
+        self.shutdown_handler = FunctionInfo(handler=handler, is_async=asyncio.iscoroutinefunction(handler))

hypern/args_parser.py

@@ -49,6 +49,12 @@ class ArgsConfig:
             action="store_true",
             help="It restarts the server based on file changes.",
         )
+
+        parser.add_argument(
+            "--auto-compression",
+            action="store_true",
+            help="It compresses the response automatically.",
+        )
         args, _ = parser.parse_known_args()
 
         self.host = args.host or "127.0.0.1"
@@ -57,3 +63,4 @@ class ArgsConfig:
         self.processes = args.processes or 1
         self.workers = args.workers or 1
         self.reload = args.reload or False
+        self.auto_compression = args.auto_compression

hypern/caching/__init__.py

@@ -0,0 +1,6 @@
+from .backend import BaseBackend
+from .redis_backend import RedisBackend
+
+from .strategies import CacheAsideStrategy, CacheEntry, CacheStrategy, StaleWhileRevalidateStrategy, cache_with_strategy
+
+__all__ = ["BaseBackend", "RedisBackend", "CacheAsideStrategy", "CacheEntry", "CacheStrategy", "StaleWhileRevalidateStrategy", "cache_with_strategy"]

hypern/caching/backend.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class BaseBackend(ABC):
+    @abstractmethod
+    async def get(self, key: str) -> Any: ...
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None: ...
+
+    @abstractmethod
+    async def delete_pattern(self, pattern: str) -> None: ...
+
+    @abstractmethod
+    async def delete(self, key: str) -> None: ...
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool: ...
+
+    @abstractmethod
+    async def set_nx(self, key: str, value: Any, ttl: Optional[int] = None) -> bool: ...
+
+    @abstractmethod
+    async def ttl(self, key: str) -> int: ...
+
+    @abstractmethod
+    async def incr(self, key: str) -> int: ...
+
+    @abstractmethod
+    async def clear(self) -> None: ...

hypern/caching/redis_backend.py

@@ -1,3 +1,201 @@
-from hypern.hypern import RedisBackend
+# src/hypern/cache/backends/redis.py
+import pickle
+from typing import Any, Optional
 
-__all__ = ["RedisBackend"]
+from redis import asyncio as aioredis
+
+from hypern.logging import logger
+
+from .backend import BaseBackend
+
+
+class RedisBackend(BaseBackend):
+    def __init__(self, url: str = "redis://localhost:6379", encoding: str = "utf-8", decode_responses: bool = False, **kwargs):
+        """
+        Initialize Redis backend with aioredis
+
+        Args:
+            url: Redis connection URL
+            encoding: Character encoding to use
+            decode_responses: Whether to decode response bytes to strings
+            **kwargs: Additional arguments passed to aioredis.from_url
+        """
+        self.redis = aioredis.from_url(url, encoding=encoding, decode_responses=decode_responses, **kwargs)
+        self._encoding = encoding
+
+    async def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from Redis
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Deserialized Python object or None if key doesn't exist
+        """
+        try:
+            value = await self.redis.get(key)
+            if value is not None:
+                return pickle.loads(value)
+            return None
+        except Exception as e:
+            logger.error(f"Error getting cache key {key}: {e}")
+            return None
+
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        """
+        Set value in Redis with optional TTL
+
+        Args:
+            key: Cache key
+            value: Python object to store
+            ttl: Time to live in seconds
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            serialized = pickle.dumps(value)
+            if ttl is not None:
+                await self.redis.setex(key, ttl, serialized)
+            else:
+                await self.redis.set(key, serialized)
+            return True
+        except Exception as e:
+            logger.error(f"Error setting cache key {key}: {e}")
+            return False
+
+    async def delete(self, key: str) -> bool:
+        """
+        Delete key from Redis
+
+        Args:
+            key: Cache key to delete
+
+        Returns:
+            bool: True if key was deleted, False otherwise
+        """
+        try:
+            return bool(await self.redis.delete(key))
+        except Exception as e:
+            logger.error(f"Error deleting cache key {key}: {e}")
+            return False
+
+    async def delete_pattern(self, pattern: str) -> int:
+        """
+        Delete all keys matching pattern
+
+        Args:
+            pattern: Redis key pattern to match
+
+        Returns:
+            int: Number of keys deleted
+        """
+        try:
+            keys = await self.redis.keys(pattern)
+            if keys:
+                return await self.redis.delete(*keys)
+            return 0
+        except Exception as e:
+            logger.error(f"Error deleting keys matching {pattern}: {e}")
+            return 0
+
+    async def exists(self, key: str) -> bool:
+        """
+        Check if key exists
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            bool: True if key exists, False otherwise
+        """
+        try:
+            return bool(await self.redis.exists(key))
+        except Exception as e:
+            logger.error(f"Error checking existence of key {key}: {e}")
+            return False
+
+    async def ttl(self, key: str) -> int:
+        """
+        Get TTL of key in seconds
+
+        Args:
+            key: Cache key
+
+        Returns:
+            int: TTL in seconds, -2 if key doesn't exist, -1 if key has no TTL
+        """
+        try:
+            return await self.redis.ttl(key)
+        except Exception as e:
+            logger.error(f"Error getting TTL for key {key}: {e}")
+            return -2
+
+    async def incr(self, key: str, amount: int = 1) -> Optional[int]:
+        """
+        Increment value by amount
+
+        Args:
+            key: Cache key
+            amount: Amount to increment by
+
+        Returns:
+            int: New value after increment or None on error
+        """
+        try:
+            return await self.redis.incrby(key, amount)
+        except Exception as e:
+            logger.error(f"Error incrementing key {key}: {e}")
+            return None
+
+    async def set_nx(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        """
+        Set key only if it doesn't exist (SET NX operation)
+
+        Args:
+            key: Cache key
+            value: Value to set
+            ttl: Optional TTL in seconds
+
+        Returns:
+            bool: True if key was set, False otherwise
+        """
+        try:
+            serialized = pickle.dumps(value)
+            if ttl is not None:
+                return await self.redis.set(key, serialized, nx=True, ex=ttl)
+            return await self.redis.set(key, serialized, nx=True)
+        except Exception as e:
+            logger.error(f"Error setting NX for key {key}: {e}")
+            return False
+
+    async def clear(self) -> bool:
+        """
+        Clear all keys from the current database
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            await self.redis.flushdb()
+            return True
+        except Exception as e:
+            logger.error(f"Error clearing cache: {e}")
+            return False
+
+    async def close(self) -> None:
+        """Close Redis connection"""
+        await self.redis.close()
+
+    async def ping(self) -> bool:
+        """
+        Check Redis connection
+
+        Returns:
+            bool: True if connection is alive, False otherwise
+        """
+        try:
+            return await self.redis.ping()
+        except Exception:
+            return False

hypern/caching/strategies.py

@@ -0,0 +1,208 @@
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Callable, Generic, Optional, TypeVar
+
+import orjson
+
+from .backend import BaseBackend
+
+T = TypeVar("T")
+
+
+class CacheStrategy(ABC, Generic[T]):
+    """Base class for cache strategies"""
+
+    @abstractmethod
+    async def get(self, key: str) -> Optional[T]:
+        pass
+
+    @abstractmethod
+    async def set(self, key: str, value: T, ttl: Optional[int] = None) -> None:
+        pass
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        pass
+
+
+class CacheEntry(Generic[T]):
+    """Represents a cached item with metadata"""
+
+    def __init__(self, value: T, created_at: float, ttl: int, revalidate_after: Optional[int] = None):
+        self.value = value
+        self.created_at = created_at
+        self.ttl = ttl
+        self.revalidate_after = revalidate_after
+        self.is_revalidating = False
+
+    def is_stale(self) -> bool:
+        """Check if entry is stale and needs revalidation"""
+        now = time.time()
+        return self.revalidate_after is not None and now > (self.created_at + self.revalidate_after)
+
+    def is_expired(self) -> bool:
+        """Check if entry has completely expired"""
+        now = time.time()
+        return now > (self.created_at + self.ttl)
+
+    def to_json(self) -> bytes:
+        """Serialize entry to JSON"""
+        return orjson.dumps(
+            {
+                "value": self.value,
+                "created_at": self.created_at,
+                "ttl": self.ttl,
+                "revalidate_after": self.revalidate_after,
+                "is_revalidating": self.is_revalidating,
+            }
+        )
+
+    @classmethod
+    def from_json(cls, data: bytes) -> "CacheEntry[T]":
+        """Deserialize entry from JSON"""
+        parsed = orjson.loads(data)
+        return cls(value=parsed["value"], created_at=parsed["created_at"], ttl=parsed["ttl"], revalidate_after=parsed["revalidate_after"])
+
+
+class StaleWhileRevalidateStrategy(CacheStrategy[T]):
+    """
+    Implements stale-while-revalidate caching strategy.
+    Allows serving stale content while revalidating in the background.
+    """
+
+    def __init__(self, backend: BaseBackend, revalidate_after: int, ttl: int, revalidate_fn: Callable[..., T]):
+        """
+        Initialize the caching strategy.
+
+        Args:
+            backend (BaseBackend): The backend storage for caching.
+            revalidate_after (int): The time in seconds after which the cache should be revalidated.
+            ttl (int): The time-to-live for cache entries in seconds.
+            revalidate_fn (Callable[..., T]): The function to call for revalidating the cache.
+
+        Attributes:
+            backend (BaseBackend): The backend storage for caching.
+            revalidate_after (int): The time in seconds after which the cache should be revalidated.
+            ttl (int): The time-to-live for cache entries in seconds.
+            revalidate_fn (Callable[..., T]): The function to call for revalidating the cache.
+            _revalidation_locks (dict): A dictionary to manage revalidation locks.
+        """
+        self.backend = backend
+        self.revalidate_after = revalidate_after
+        self.ttl = ttl
+        self.revalidate_fn = revalidate_fn
+        self._revalidation_locks: dict = {}
+
+    async def get(self, key: str) -> Optional[T]:
+        entry = await self.backend.get(key)
+        if not entry:
+            return None
+
+        if isinstance(entry, bytes):
+            entry = CacheEntry.from_json(entry)
+
+        # If entry is stale but not expired, trigger background revalidation
+        if entry.is_stale() and not entry.is_expired():
+            if not entry.is_revalidating:
+                entry.is_revalidating = True
+                await self.backend.set(key, entry.to_json())
+                asyncio.create_task(self._revalidate(key))
+            return entry.value
+
+        # If entry is expired, return None
+        if entry.is_expired():
+            return None
+
+        return entry.value
+
+    async def set(self, key: str, value: T, ttl: Optional[int] = None) -> None:
+        entry = CacheEntry(value=value, created_at=time.time(), ttl=ttl or self.ttl, revalidate_after=self.revalidate_after)
+        await self.backend.set(key, entry.to_json(), ttl=ttl)
+
+    async def delete(self, key: str) -> None:
+        await self.backend.delete(key)
+
+    async def _revalidate(self, key: str) -> None:
+        """Background revalidation of cached data"""
+        try:
+            # Prevent multiple simultaneous revalidations
+            if key in self._revalidation_locks:
+                return
+            self._revalidation_locks[key] = True
+
+            # Get fresh data
+            fresh_value = await self.revalidate_fn(key)
+
+            # Update cache with fresh data
+            await self.set(key, fresh_value)
+        finally:
+            self._revalidation_locks.pop(key, None)
+
+
+class CacheAsideStrategy(CacheStrategy[T]):
+    """
+    Implements cache-aside (lazy loading) strategy.
+    Data is loaded into cache only when requested.
+    """
+
+    def __init__(self, backend: BaseBackend, load_fn: Callable[[str], T], ttl: int, write_through: bool = False):
+        self.backend = backend
+        self.load_fn = load_fn
+        self.ttl = ttl
+        self.write_through = write_through
+
+    async def get(self, key: str) -> Optional[T]:
+        # Try to get from cache first
+        value = await self.backend.get(key)
+        if value:
+            if isinstance(value, bytes):
+                value = orjson.loads(value)
+            return value
+
+        # On cache miss, load from source
+        value = await self.load_fn(key)
+        if value is not None:
+            await self.set(key, value)
+        return value
+
+    async def set(self, key: str, value: T, ttl: Optional[int] = None) -> None:
+        await self.backend.set(key, value, ttl or self.ttl)
+
+        # If write-through is enabled, update the source
+        if self.write_through:
+            await self._write_to_source(key, value)
+
+    async def delete(self, key: str) -> None:
+        await self.backend.delete(key)
+
+    async def _write_to_source(self, key: str, value: T) -> None:
+        """Write to the source in write-through mode"""
+        if hasattr(self.load_fn, "write"):
+            await self.load_fn.write(key, value)
+
+
+def cache_with_strategy(strategy: CacheStrategy, key_prefix: str | None = None, ttl: int = 3600):
+    """
+    Decorator for using cache strategies
+    """
+
+    def decorator(func):
+        async def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = f"{key_prefix or func.__name__}:{hash(str(args) + str(kwargs))}"
+
+            result = await strategy.get(cache_key)
+            if result is not None:
+                return result
+
+            # Execute function and cache result
+            result = await func(*args, **kwargs)
+            if result is not None:
+                await strategy.set(cache_key, result, ttl)
+
+            return result
+
+        return wrapper
+
+    return decorator

hypern/gateway/__init__.py

@@ -0,0 +1,6 @@
+from .gateway import APIGateway
+from .aggregator import Aggregator
+from .proxy import Proxy
+from .service import ServiceConfig, ServiceRegistry
+
+__all__ = ["APIGateway", "Aggregator", "Proxy", "ServiceConfig", "ServiceRegistry"]

hypern/gateway/aggregator.py

@@ -0,0 +1,32 @@
+import asyncio
+from typing import Any, Dict, List
+
+from hypern.response import JSONResponse
+
+from .proxy import Proxy
+from .service import ServiceRegistry
+
+
+class Aggregator:
+    def __init__(self, registry: ServiceRegistry, proxy: Proxy):
+        self._registry = registry
+        self._proxy = proxy
+
+    async def aggregate_responses(self, requests: List[Dict[str, Any]]) -> JSONResponse:
+        tasks = []
+        for req in requests:
+            service = self._registry.get_service(req["service"])
+            if service:
+                tasks.append(self._proxy.forward_request(service, req["request"]))
+
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+        aggregated = {}
+        for i, response in enumerate(responses):
+            service_name = requests[i]["service"]
+            if isinstance(response, Exception):
+                aggregated[service_name] = {"status": "error", "error": str(response)}
+            else:
+                aggregated[service_name] = {"status": "success", "data": response.body}
+
+        return JSONResponse(content=aggregated)

hypern/gateway/gateway.py

@@ -0,0 +1,41 @@
+from typing import Any, Dict, List, Optional
+
+from hypern import Hypern
+from hypern.hypern import Request
+from hypern.response import JSONResponse
+
+from .aggregator import Aggregator
+from .proxy import Proxy
+from .service import ServiceConfig, ServiceRegistry
+
+
+class APIGateway:
+    def __init__(self, app: Hypern):
+        self.app = app
+        self.registry = ServiceRegistry()
+        self.proxy = Proxy(self.registry)
+        self.aggregator = Aggregator(self.registry, self.proxy)
+
+    def register_service(self, config: ServiceConfig, metadata: Optional[Dict[str, Any]] = None):
+        """Register a new service with the gateway"""
+        self.registry.register(config, metadata)
+
+    async def startup(self):
+        """Initialize the gateway components"""
+        await self.proxy.startup()
+
+    async def shutdown(self):
+        """Cleanup gateway resources"""
+        await self.proxy.shutdown()
+
+    async def handle_request(self, request: Request) -> Any:
+        """Main request handler"""
+        service = self.registry.get_service_by_prefix(request.path)
+        if not service:
+            return JSONResponse(content={"error": "Service not found"}, status_code=404)
+
+        return await self.proxy.forward_request(service, request)
+
+    async def aggregate(self, requests: List[Dict[str, Any]]) -> Any:
+        """Handle aggregated requests"""
+        return await self.aggregator.aggregate_responses(requests)