hypern 0.3.11__cp312-cp312-musllinux_1_2_i686.whl

hypern/hypern.pyi

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Tuple
+from enum import Enum
+
+@dataclass
+class BaseSchemaGenerator:
+    remove_converter: Callable[[str], str]
+    parse_docstring: Callable[..., str]
+
+@dataclass
+class SwaggerUI:
+    title: str
+    openapi_url: str
+
+    def get_html_content(self) -> str: ...
+
+@dataclass
+class BackgroundTask:
+    """
+    A task to be executed in the background
+    id: str: The task ID
+    function: Callable[..., Any]: The function to be executed
+    args: List | Tuple: The arguments to be passed to the function
+    kwargs: Dict[str, Any]: The keyword arguments to be passed to the function
+    timeout_secs: int: The maximum time in seconds the task is allowed to run
+    cancelled: bool: Whether the task is cancelled
+
+    **Note**: function is currently running with sync mode, so it should be a sync function
+    """
+
+    id: str
+    function: Callable[..., Any]
+    args: List | Tuple
+    kwargs: Dict[str, Any]
+    timeout_secs: int
+    cancelled: bool
+
+    def get_id(self) -> str:
+        """
+        Get the task ID
+        """
+        pass
+
+    def cancel(self) -> None:
+        """
+        Cancel the task
+        """
+        pass
+
+    def is_cancelled(self) -> bool:
+        """
+        Check if the task is cancelled
+        """
+        pass
+
+    def execute(self) -> Any:
+        """
+        Execute the task
+        """
+        pass
+
+@dataclass
+class BackgroundTasks:
+    """
+    A collection of tasks to be executed in the background
+
+    **Note**: Only set tasks. pool, sender, receiver are set by the framework
+    """
+
+    def add_task(self, task: BackgroundTask) -> str:
+        """
+        Add a task to the collection
+        """
+        pass
+
+    def cancel_task(self, task_id: str) -> bool:
+        """
+        Cancel a task in the collection
+        """
+        pass
+
+    def execute_all(self) -> None:
+        """
+        Execute all tasks in the collection
+        """
+        pass
+
+    def execute_task(self, task_id: str) -> None:
+        """
+        Execute a task in the collection
+        """
+        pass
+
+class Scheduler:
+    def add_job(
+        self,
+        job_type: str,
+        schedule_param: str,
+        task: Callable[..., Any],
+        timezone: str,
+        dependencies: List[str],
+        retry_policy: Tuple[int, int, bool] | None = None,
+    ) -> str:
+        """
+        Add a job to the scheduler
+        params:
+        job_type: str: The type of the job (e.g. "cron", "interval")
+
+        schedule_param: str: The schedule parameter of the job. interval in seconds for interval jobs, cron expression for cron jobs
+
+        Exmaple:
+        //           sec  min   hour   day of month   month   day of week   year
+        expression = "0   30   9,12,15     1,15       May-Aug  Mon,Wed,Fri  2018/2";
+
+        task: Callable[..., Any]: The task to be executed
+
+        timezone: str: The timezone of the job
+
+        dependencies: List[str]: The IDs of the jobs this job depends on
+
+        retry_policy: Tuple[int, int, bool] | None: The retry policy of the job. (max_retries, retry_delay_secs, exponential_backoff)
+
+        return:
+        str: The ID of the job
+        """
+        pass
+
+    def remove_job(self, job_id: str) -> None:
+        """
+        Remove a job from the scheduler
+        """
+        pass
+
+    def start(self) -> None:
+        """
+        Start the scheduler
+        """
+        pass
+
+    def stop(self) -> None:
+        """
+        Stop the scheduler
+        """
+        pass
+
+    def get_job_status(self, job_id: str) -> Tuple[float, float, List[str], int]:
+        """
+        Get the status of a job
+        """
+        pass
+
+    def get_next_run(self, job_id: str) -> float:
+        """
+        Get the next run time of a job
+        """
+        pass
+
+@dataclass
+class FunctionInfo:
+    """
+    The function info object passed to the route handler.
+
+    Attributes:
+        handler (Callable): The function to be called
+        is_async (bool): Whether the function is async or not
+    """
+
+    handler: Callable
+    is_async: bool
+
+@dataclass
+class Server:
+    router: Router
+    websocket_router: Any
+    startup_handler: Any
+    shutdown_handler: Any
+
+    def add_route(self, route: Route) -> None: ...
+    def set_router(self, router: Router) -> None: ...
+    def set_websocket_router(self, websocket_router: WebsocketRouter) -> None: ...
+    def start(self, socket: SocketHeld, worker: int, max_blocking_threads: int) -> None: ...
+    def set_before_hooks(self, hooks: List[FunctionInfo]) -> None: ...
+    def set_after_hooks(self, hooks: List[FunctionInfo]) -> None: ...
+    def set_response_headers(self, headers: Dict[str, str]) -> None: ...
+    def set_startup_handler(self, on_startup: FunctionInfo) -> None: ...
+    def set_shutdown_handler(self, on_shutdown: FunctionInfo) -> None: ...
+    def set_database_config(self, config: DatabaseConfig) -> None: ...
+    def set_dependencies(self, dependencies: Dict[str, Any]) -> None: ...
+    def enable_http2(self) -> None: ...
+
+class Route:
+    path: str
+    function: FunctionInfo
+    method: str
+    doc: str | None = None
+
+    def matches(self, path: str, method: str) -> str: ...
+    def clone_route(self) -> Route: ...
+    def update_path(self, new_path: str) -> None: ...
+    def update_method(self, new_method: str) -> None: ...
+    def is_valid(self) -> bool: ...
+    def get_path_parans(self) -> List[str]: ...
+    def has_parameters(self) -> bool: ...
+    def normalized_path(self) -> str: ...
+    def same_handler(self, other: Route) -> bool: ...
+
+class Router:
+    routes: List[Route]
+
+    def add_route(self, route: Route) -> None: ...
+    def remove_route(self, path: str, method: str) -> bool: ...
+    def get_route(self, path: str, method) -> Route | None: ...
+    def get_routes_by_path(self, path: str) -> List[Route]: ...
+    def get_routes_by_method(self, method: str) -> List[Route]: ...
+    def extend_route(self, routes: List[Route]) -> None: ...
+
+@dataclass
+class SocketHeld:
+    socket: Any
+
+@dataclass
+class WebSocketSession:
+    sender: Callable[[str], None]
+    receiver: Callable[[], str]
+    is_closed: bool
+
+    def send(self, message: str) -> None: ...
+
+@dataclass
+class WebsocketRoute:
+    path: str
+    handler: Callable[[WebSocketSession], None]
+
+@dataclass
+class WebsocketRouter:
+    path: str
+    routes: List[WebsocketRoute]
+
+    def add_route(self, route: WebsocketRoute) -> None: ...
+    def remove_route(self, path: str) -> None: ...
+    def extend_route(self, route: WebsocketRoute) -> None: ...
+    def clear_routes(self) -> None: ...
+    def route_count(self) -> int: ...
+
+@dataclass
+class Header:
+    headers: Dict[str, str]
+
+    def get(self, key: str) -> str | None: ...
+    def set(self, key: str, value: str) -> None: ...
+    def append(self, key: str, value: str) -> None: ...
+    def update(self, headers: Dict[str, str]) -> None: ...
+    def get_headers(self) -> Dict[str, str]: ...
+
+@dataclass
+class Response:
+    status_code: int
+    response_type: str
+    headers: Header
+    description: str
+    file_path: str | None
+    context_id: str
+
+@dataclass
+class QueryParams:
+    queries: Dict[str, List[str]]
+
+    def to_dict(self) -> Dict[str, str]: ...
+
+@dataclass
+class UploadedFile:
+    name: str
+    content_type: str
+    path: str
+    size: int
+    content: bytes
+    file_name: str
+
+@dataclass
+class BodyData:
+    json: bytes
+    files: List[UploadedFile]
+
+@dataclass
+class Request:
+    path: str
+    query_params: QueryParams
+    headers: Header
+    path_params: Dict[str, str]
+    body: BodyData
+    method: str
+    remote_addr: str
+    timestamp: float
+    context_id: str
+
+    def json(self) -> Dict[str, Any]: ...
+    def set_body(self, body: BodyData) -> None: ...
+
+@dataclass
+class MiddlewareConfig:
+    priority: int = 0
+    is_conditional: bool = True
+
+    @staticmethod
+    def default(self) -> MiddlewareConfig: ...
+
+class DatabaseType(Enum):
+    Postgres: str
+    MySQL: str
+    SQLite: str
+
+@dataclass
+class DatabaseConfig:
+    driver: DatabaseType
+    url: str
+    max_connections: int = 10
+    min_connections: int = 1
+    idle_timeout: int = 30
+
+    options: Dict[str, Any] = {}
+
+@dataclass
+class DatabaseTransaction:
+    def execute(self, query: str, params: List[Any]) -> int: ...
+    def fetch_all(self, query: str, params: List[Any]) -> List[Dict[str, Any]]: ...
+    def stream_data(self, query: str, params: List[Any], chunk_size: int) -> Dict[str, Any]: ...
+    def bulk_change(self, query: str, params: List[List[Any]], batch_size: int) -> int | None: ...
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+
+def get_session_database(context_id: str) -> DatabaseTransaction: ...

hypern/logging/__init__.py

@@ -0,0 +1,3 @@
+from .logger import logger
+
+__all__ = ["logger"]

hypern/logging/logger.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+import logging
+import sys
+from copy import copy
+from datetime import datetime, timezone
+from typing import Literal, Optional
+
+import click
+
+TRACE_LOG_LEVEL = 5
+
+
+class ColourizedFormatter(logging.Formatter):
+    level_name_colors = {
+        TRACE_LOG_LEVEL: lambda level_name: click.style(str(level_name), fg="blue"),
+        logging.DEBUG: lambda level_name: click.style(str(level_name), fg="cyan"),
+        logging.INFO: lambda level_name: click.style(str(level_name), fg="green"),
+        logging.WARNING: lambda level_name: click.style(str(level_name), fg="yellow"),
+        logging.ERROR: lambda level_name: click.style(str(level_name), fg="red"),
+        logging.CRITICAL: lambda level_name: click.style(str(level_name), fg="bright_red"),
+    }
+
+    def __init__(
+        self,
+        fmt: Optional[str] = None,
+        datefmt: Optional[str] = None,
+        style: Literal["%", "{", "$"] = "%",
+        use_colors: Optional[bool] = None,
+    ):
+        if use_colors in (True, False):
+            self.use_colors = use_colors
+        else:
+            self.use_colors = sys.stdout.isatty()
+        super().__init__(fmt=fmt, datefmt=datefmt, style=style)
+
+    def color_level_name(self, level_name: str, level_no: int) -> str:
+        def default(level_name: str) -> str:
+            return str(level_name)
+
+        func = self.level_name_colors.get(level_no, default)
+        return func(level_name)
+
+    def should_use_colors(self) -> bool:
+        return True
+
+    def formatMessage(self, record: logging.LogRecord) -> str:
+        recordcopy = copy(record)
+        levelname = recordcopy.levelname
+        process = recordcopy.process
+        created = recordcopy.created
+        filename = recordcopy.filename
+        module = recordcopy.module
+        lineno = recordcopy.lineno
+        separator = " " * (5 - len(recordcopy.levelname))
+        if self.use_colors:
+            levelname = self.color_level_name(levelname, recordcopy.levelno)
+            if "color_message" in recordcopy.__dict__:
+                recordcopy.msg = recordcopy.__dict__["color_message"]
+                recordcopy.__dict__["message"] = recordcopy.getMessage()
+        recordcopy.__dict__["levelprefix"] = levelname + separator
+        recordcopy.__dict__["process"] = click.style(str(process), fg="blue")
+        recordcopy.__dict__["asctime"] = click.style(datetime.fromtimestamp(created, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ"), fg=(101, 111, 104))
+        recordcopy.__dict__["filename"] = click.style(f"{module}/{filename}:{lineno}:", fg=(101, 111, 104))
+        return super().formatMessage(recordcopy)
+
+
+class DefaultFormatter(ColourizedFormatter):
+    def should_use_colors(self) -> bool:
+        return sys.stderr.isatty()
+
+
+def create_logger(name) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)
+    formatter = DefaultFormatter(fmt="%(asctime)s %(levelprefix)s %(filename)s %(message)s", use_colors=True, datefmt="%Y-%m-%d %H:%M:%S")
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    return logger
+
+
+logger = create_logger("hypern")

hypern/middleware/__init__.py

@@ -0,0 +1,17 @@
+from .base import Middleware, MiddlewareConfig
+from .cors import CORSMiddleware
+from .limit import RateLimitMiddleware, StorageBackend, RedisBackend, InMemoryBackend
+from .compress import CompressionMiddleware
+from .cache import EdgeCacheMiddleware
+
+__all__ = [
+    "Middleware",
+    "CORSMiddleware",
+    "RateLimitMiddleware",
+    "StorageBackend",
+    "RedisBackend",
+    "InMemoryBackend",
+    "CompressionMiddleware",
+    "EdgeCacheMiddleware",
+    "MiddlewareConfig",
+]

hypern/middleware/base.py

@@ -0,0 +1,13 @@
+from typing import Optional
+from hypern.hypern import MiddlewareConfig
+
+
+class Middleware:
+    def __init__(self, config: Optional[MiddlewareConfig] = None):
+        self.config = config or MiddlewareConfig.default()
+
+    async def before_request(self, request):
+        return request
+
+    async def after_request(self, response):
+        return response

hypern/middleware/cache.py

@@ -0,0 +1,177 @@
+import hashlib
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from hypern.hypern import Header, MiddlewareConfig, Request, Response
+
+from .base import Middleware
+
+
+class CacheConfig:
+    """
+    Configuration class for caching middleware.
+
+    Attributes:
+        max_age (int): The maximum age (in seconds) for the cache. Default is 3600 seconds (1 hour).
+        s_maxage (Optional[int]): The shared maximum age (in seconds) for the cache. Default is None.
+        stale_while_revalidate (Optional[int]): The time (in seconds) the cache can be used while revalidation is performed. Default is None.
+        stale_if_error (Optional[int]): The time (in seconds) the cache can be used if an error occurs during revalidation. Default is None.
+        vary_by (List[str]): List of headers to vary the cache by. Default is ['Accept', 'Accept-Encoding'].
+        cache_control (List[str]): List of cache control directives. Default is an empty list.
+        include_query_string (bool): Whether to include the query string in the cache key. Default is True.
+        exclude_paths (List[str]): List of paths to exclude from caching. Default is ['/admin', '/api/private'].
+        exclude_methods (List[str]): List of HTTP methods to exclude from caching. Default is ['POST', 'PUT', 'DELETE', 'PATCH'].
+        private_paths (List[str]): List of paths to be marked as private. Default is an empty list.
+        cache_by_headers (List[str]): List of headers to include in the cache key. Default is an empty list.
+    """
+
+    def __init__(
+        self,
+        max_age: int = 3600,  # 1 hour default
+        s_maxage: Optional[int] = None,
+        stale_while_revalidate: Optional[int] = None,
+        stale_if_error: Optional[int] = None,
+        vary_by: List[str] = None,
+        cache_control: List[str] = None,
+        include_query_string: bool = True,
+        exclude_paths: List[str] = None,
+        exclude_methods: List[str] = None,
+        private_paths: List[str] = None,
+        cache_by_headers: List[str] = None,
+    ):
+        self.max_age = max_age
+        self.s_maxage = s_maxage
+        self.stale_while_revalidate = stale_while_revalidate
+        self.stale_if_error = stale_if_error
+        self.vary_by = vary_by or ["accept", "accept-encoding"]
+        self.cache_control = cache_control or []
+        self.include_query_string = include_query_string
+        self.exclude_paths = exclude_paths or ["/admin", "/api/private"]
+        self.exclude_methods = exclude_methods or ["POST", "PUT", "DELETE", "PATCH"]
+        self.private_paths = private_paths or []
+        self.cache_by_headers = cache_by_headers or []
+
+
+class EdgeCacheMiddleware(Middleware):
+    """
+    Middleware implementing edge caching strategies with support for:
+    - Cache-Control directives
+    - ETag generation
+    - Conditional requests (If-None-Match, If-Modified-Since)
+    - Vary header management
+    - CDN-specific headers
+    """
+
+    def __init__(self, cache_config: CacheConfig | None = None, config: Optional[MiddlewareConfig] = None):
+        super().__init__(config)
+        self.cache_config = cache_config or CacheConfig()
+        self._etag_cache: Dict[str, str] = {}
+        self.request_context = {}
+
+    def _should_cache(self, request: Request, path: str) -> bool:
+        """Determine if the request should be cached"""
+        if request.method in self.cache_config.exclude_methods:
+            return False
+
+        if any(excluded in path for excluded in self.cache_config.exclude_paths):
+            return False
+
+        return True
+
+    def _generate_cache_key(self, request: Request) -> str:
+        """Generate a unique cache key based on request attributes"""
+        components = [request.method, request.path]
+
+        if self.cache_config.include_query_string:
+            components.append(str(request.query_params))
+
+        for header in self.cache_config.cache_by_headers:
+            value = request.headers.get(str(header).lower())
+            if value:
+                components.append(f"{header}:{value}")
+
+        return hashlib.sha256(":".join(components).encode()).hexdigest()
+
+    def _generate_etag(self, response: Response) -> str:
+        """Generate ETag for response content"""
+        content = response.description
+        if not isinstance(content, bytes):
+            content = str(content).encode()
+        return hashlib.sha256(content).hexdigest()
+
+    def _build_cache_control(self, path: str) -> str:
+        """Build Cache-Control header value"""
+        directives = []
+
+        # Determine public/private caching
+        if any(private in path for private in self.cache_config.private_paths):
+            directives.append("private")
+        else:
+            directives.append("public")
+
+        # Add max-age directives
+        directives.append(f"max-age={self.cache_config.max_age}")
+
+        if self.cache_config.s_maxage is not None:
+            directives.append(f"s-maxage={self.cache_config.s_maxage}")
+
+        if self.cache_config.stale_while_revalidate is not None:
+            directives.append(f"stale-while-revalidate={self.cache_config.stale_while_revalidate}")
+
+        if self.cache_config.stale_if_error is not None:
+            directives.append(f"stale-if-error={self.cache_config.stale_if_error}")
+
+        # Add custom cache control directives
+        directives.extend(self.cache_config.cache_control)
+
+        return ", ".join(directives)
+
+    def cleanup_context(self, context_id: str):
+        try:
+            del self.request_context[context_id]
+        except Exception:
+            pass
+
+    def before_request(self, request: Request) -> Request | Response:
+        """Handle conditional requests"""
+        if not self._should_cache(request, request.path):
+            return request
+
+        cache_key = self._generate_cache_key(request)
+        etag = self._etag_cache.get(cache_key)
+
+        if etag:
+            if_none_match = request.headers.get("if-none-match")
+            if if_none_match and if_none_match == etag:
+                return Response(status_code=304, description=b"", headers=Header({"ETag": etag}))
+        self.request_context[request.context_id] = request
+        return request
+
+    def after_request(self, response: Response) -> Response:
+        """Add caching headers to response"""
+        request = self.request_context.get(response.context_id)
+        self.cleanup_context(response.context_id)
+        if not self._should_cache(request, request.path):
+            response.headers.set("Cache-Control", "no-store")
+            return response
+
+        # Generate and store ETag
+        cache_key = self._generate_cache_key(request)
+        etag = self._generate_etag(response)
+        self._etag_cache[cache_key] = etag
+
+        # Set cache headers
+        response.headers.update(
+            {
+                "Cache-Control": self._build_cache_control(request.path),
+                "ETag": etag,
+                "Vary": ", ".join(self.cache_config.vary_by),
+                "Last-Modified": datetime.now(tz=timezone.utc).strftime("%a, %d %b %Y %H:%M:%S GMT"),
+            }
+        )
+
+        # Add CDN-specific headers
+        response.headers.set("CDN-Cache-Control", response.headers["Cache-Control"])
+        response.headers.set("Surrogate-Control", f"max-age={self.cache_config.s_maxage or self.cache_config.max_age}")
+
+        return response