hypern 0.3.11__cp310-cp310-macosx_11_0_arm64.whl

hypern/datastructures.py

@@ -0,0 +1,40 @@
+from typing import Optional
+from enum import Enum
+from pydantic import BaseModel, AnyUrl
+
+
+class BaseModelWithConfig(BaseModel):
+    model_config = {"extra": "allow"}
+
+
+class Contact(BaseModelWithConfig):
+    name: Optional[str] = None
+    url: Optional[AnyUrl] = None
+    email: Optional[str] = None
+
+
+class License(BaseModelWithConfig):
+    name: str
+    identifier: Optional[str] = None
+    url: Optional[AnyUrl] = None
+
+
+class Info(BaseModelWithConfig):
+    title: str
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    contact: Optional[Contact] = None
+    license: Optional[License] = None
+    version: str
+
+
+class HTTPMethod(Enum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+    TRACE = "TRACE"
+    CONNECT = "CONNECT"

hypern/enum.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+from enum import Enum
+
+
+class ErrorCode(Enum):
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+    BAD_REQUEST = "BAD_REQUEST"
+    FORBIDDEN = "FORBIDDEN"
+    SERVER_ERROR = "SERVER_ERROR"
+    NOT_FOUND = "NOT_FOUND"
+    METHOD_NOT_ALLOW = "METHOD_NOT_ALLOW"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    VALIDATION_ERROR = "VALIDATION_ERROR"

hypern/exceptions/__init__.py

@@ -0,0 +1,34 @@
+from .base import HTTPException, ResponseFormatter, HypernError
+from .errors import ErrorDefinitions
+from .formatters import SimpleFormatter, DetailedFormatter, LocalizedFormatter
+from .http import (
+    BadRequestException,
+    UnauthorizedException,
+    ForbiddenException,
+    NotFoundException,
+    ValidationException,
+    InternalServerException,
+    RateLimitException,
+)
+
+from .common import DBFieldValidationError, InvalidPortNumber, OutOfScopeApplicationException
+
+__all__ = [
+    "HTTPException",
+    "ResponseFormatter",
+    "HypernError",
+    "ErrorDefinitions",
+    "SimpleFormatter",
+    "DetailedFormatter",
+    "LocalizedFormatter",
+    "BadRequestException",
+    "UnauthorizedException",
+    "ForbiddenException",
+    "NotFoundException",
+    "ValidationException",
+    "InternalServerException",
+    "RateLimitException",
+    "DBFieldValidationError",
+    "InvalidPortNumber",
+    "OutOfScopeApplicationException",
+]

hypern/exceptions/base.py

@@ -0,0 +1,62 @@
+import uuid
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from http import HTTPStatus
+from typing import Any, Dict, Optional
+
+
+class ResponseFormatter(ABC):
+    @abstractmethod
+    def format_error(self, exception: "HTTPException") -> Dict[str, Any]:
+        """Format exception into response dictionary"""
+        pass
+
+
+class DefaultFormatter(ResponseFormatter):
+    def format_error(self, exception: "HTTPException") -> Dict[str, Any]:
+        return {
+            "error": {
+                "code": exception.error.code if exception.error else "UNKNOWN_ERROR",
+                "message": exception.error.message if exception.error else "Unknown error occurred",
+                "details": exception.details or {},
+                "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+                "request_id": str(uuid.uuid4()),
+            },
+            "status": exception.status_code,
+        }
+
+
+class HypernError:
+    """Base error definition"""
+
+    def __init__(self, message: str, code: str):
+        self.message = message
+        self.code = code
+
+
+class HTTPException(Exception):
+    """Base HTTP exception"""
+
+    _formatter: ResponseFormatter = DefaultFormatter()
+
+    @classmethod
+    def set_formatter(cls, formatter: ResponseFormatter):
+        cls._formatter = formatter
+
+    def __init__(
+        self,
+        status_code: int = HTTPStatus.BAD_REQUEST,
+        error: Optional[HypernError] = None,
+        details: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        formatter: Optional[ResponseFormatter] = None,
+    ):
+        self.status_code = status_code
+        self.error = error
+        self.details = details or {}
+        self.headers = headers or {}
+        self._instance_formatter = formatter
+
+    def to_dict(self) -> Dict[str, Any]:
+        formatter = self._instance_formatter or self._formatter
+        return formatter.format_error(self)

hypern/exceptions/common.py

@@ -0,0 +1,12 @@
+class InvalidPortNumber(Exception):
+    pass
+
+
+class OutOfScopeApplicationException(Exception):
+    pass
+
+
+class DBFieldValidationError(ValueError):
+    """Custom exception for field validation errors."""
+
+    pass

hypern/exceptions/errors.py

@@ -0,0 +1,15 @@
+from .base import HypernError
+
+
+class ErrorDefinitions:
+    """Standard error definitions"""
+
+    BAD_REQUEST = HypernError(message="Bad request", code="BAD_REQUEST")
+    UNAUTHORIZED = HypernError(message="Unauthorized access", code="UNAUTHORIZED")
+    FORBIDDEN = HypernError(message="Access forbidden", code="FORBIDDEN")
+    NOT_FOUND = HypernError(message="Resource not found", code="NOT_FOUND")
+    METHOD_NOT_ALLOWED = HypernError(message="Method not allowed", code="METHOD_NOT_ALLOWED")
+    VALIDATION_ERROR = HypernError(message="Validation error", code="VALIDATION_ERROR")
+    INTERNAL_ERROR = HypernError(message="Internal server error", code="INTERNAL_SERVER_ERROR")
+    CONFLICT = HypernError(message="Resource conflict", code="CONFLICT")
+    TOO_MANY_REQUESTS = HypernError(message="Too many requests", code="TOO_MANY_REQUESTS")

hypern/exceptions/formatters.py

@@ -0,0 +1,56 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+from .base import HTTPException, ResponseFormatter
+
+
+class SimpleFormatter(ResponseFormatter):
+    def format_error(self, exception: HTTPException) -> Dict[str, Any]:
+        return {
+            "code": exception.error.code if exception.error else "UNKNOWN_ERROR",
+            "message": exception.error.message if exception.error else "Unknown error occurred",
+        }
+
+
+class DetailedFormatter(ResponseFormatter):
+    def format_error(self, exception: HTTPException) -> Dict[str, Any]:
+        return {
+            "status": {"code": exception.status_code, "text": str(exception.status_code)},
+            "error": {
+                "type": exception.error.code if exception.error else "UNKNOWN_ERROR",
+                "message": exception.error.message if exception.error else "Unknown error occurred",
+                "details": exception.details or {},
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            },
+            "request": {"path": exception.path, "id": str(uuid.uuid4())},
+        }
+
+
+class LocalizedFormatter(ResponseFormatter):
+    def __init__(self, language: str = "en"):
+        self.language = language
+        self.translations = {
+            "en": {
+                "BAD_REQUEST": "Bad request",
+                "VALIDATION_ERROR": "Validation error",
+                "NOT_FOUND": "Resource not found",
+                # Add more translations
+            },
+            "vi": {
+                "BAD_REQUEST": "Yêu cầu không hợp lệ",
+                "VALIDATION_ERROR": "Lỗi xác thực",
+                "NOT_FOUND": "Không tìm thấy tài nguyên",
+                # Add more translations
+            },
+        }
+
+    def format_error(self, exception: HTTPException) -> Dict[str, Any]:
+        error_code = exception.error.code if exception.error else "UNKNOWN_ERROR"
+        translated_message = self.translations.get(self.language, {}).get(error_code, exception.error.message if exception.error else "Unknown error occurred")
+
+        return {
+            "error": {"code": error_code, "message": translated_message, "details": exception.details or {}},
+            "status": exception.status_code,
+            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+        }

hypern/exceptions/http.py

@@ -0,0 +1,76 @@
+from http import HTTPStatus
+from typing import Any, Dict, Optional
+
+from .base import HTTPException, ResponseFormatter, HypernError
+from .errors import ErrorDefinitions
+
+
+class BadRequestException(HTTPException):
+    def __init__(
+        self,
+        error: Optional[HypernError] = ErrorDefinitions.BAD_REQUEST,
+        details: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        formatter: Optional[ResponseFormatter] = None,
+    ):
+        super().__init__(status_code=HTTPStatus.BAD_REQUEST, error=error, details=details, headers=headers, formatter=formatter)
+
+
+class UnauthorizedException(HTTPException):
+    def __init__(
+        self,
+        error: Optional[HypernError] = ErrorDefinitions.UNAUTHORIZED,
+        details: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        formatter: Optional[ResponseFormatter] = None,
+    ):
+        super().__init__(status_code=HTTPStatus.UNAUTHORIZED, error=error, details=details, headers=headers, formatter=formatter)
+
+
+class ForbiddenException(HTTPException):
+    def __init__(
+        self,
+        error: Optional[HypernError] = ErrorDefinitions.FORBIDDEN,
+        details: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        formatter: Optional[ResponseFormatter] = None,
+    ):
+        super().__init__(status_code=HTTPStatus.FORBIDDEN, error=error, details=details, headers=headers, formatter=formatter)
+
+
+class NotFoundException(HTTPException):
+    def __init__(
+        self,
+        error: Optional[HypernError] = ErrorDefinitions.NOT_FOUND,
+        details: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        formatter: Optional[ResponseFormatter] = None,
+    ):
+        super().__init__(status_code=HTTPStatus.NOT_FOUND, error=error, details=details, headers=headers, formatter=formatter)
+
+
+class ValidationException(HTTPException):
+    def __init__(self, details: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, formatter: Optional[ResponseFormatter] = None):
+        super().__init__(status_code=HTTPStatus.BAD_REQUEST, error=ErrorDefinitions.VALIDATION_ERROR, details=details, headers=headers, formatter=formatter)
+
+
+class InternalServerException(HTTPException):
+    def __init__(
+        self,
+        error: Optional[HypernError] = ErrorDefinitions.INTERNAL_ERROR,
+        details: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        formatter: Optional[ResponseFormatter] = None,
+    ):
+        super().__init__(status_code=HTTPStatus.INTERNAL_SERVER_ERROR, error=error, details=details, headers=headers, formatter=formatter)
+
+
+class RateLimitException(HTTPException):
+    def __init__(self, retry_after: int, details: Optional[Dict[str, Any]] = None, formatter: Optional[ResponseFormatter] = None):
+        super().__init__(
+            status_code=HTTPStatus.TOO_MANY_REQUESTS,
+            error=ErrorDefinitions.TOO_MANY_REQUESTS,
+            details=details,
+            headers={"Retry-After": str(retry_after)},
+            formatter=formatter,
+        )

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)

hypern/gateway/proxy.py

@@ -0,0 +1,60 @@
+import asyncio
+from typing import Any, Dict, Optional
+
+import aiohttp
+import orjson
+import traceback
+
+from hypern.hypern import Request
+from hypern.response import JSONResponse
+
+from .service import ServiceConfig, ServiceRegistry, ServiceStatus
+
+
+class Proxy:
+    def __init__(self, service_registry: ServiceRegistry):
+        self._registry = service_registry
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._rate_limiters: Dict[str, asyncio.Semaphore] = {}
+
+    async def startup(self):
+        self._session = aiohttp.ClientSession()
+        for service in self._registry._services.values():
+            self._rate_limiters[service.name] = asyncio.Semaphore(100)  # Default 100 concurrent requests
+
+    async def shutdown(self):
+        if self._session:
+            await self._session.close()
+
+    async def forward_request(self, service: ServiceConfig, request: Request) -> Any:
+        if not self._session:
+            await self.startup()
+
+        target_path = request.path.replace(service.prefix, "", 1)
+        target_url = f"{service.url}{target_path}"
+
+        headers = request.headers.get_headers()
+        # Remove hop-by-hop headers
+        for header in ["connection", "keep-alive", "transfer-encoding"]:
+            headers.pop(header, None)
+
+        async with self._rate_limiters[service.name]:
+            try:
+                async with self._session.request(
+                    method=request.method,
+                    url=target_url,
+                    headers=headers,
+                    params=request.query_params.to_dict(),
+                    data=await request.json() if request.method in ["POST", "PUT", "PATCH"] else None,
+                    timeout=aiohttp.ClientTimeout(total=service.timeout),
+                ) as response:
+                    body = await response.read()
+                    return JSONResponse(
+                        content=orjson.loads(body) if response.content_type == "application/json" else body.decode(),
+                        status_code=response.status,
+                        headers=dict(response.headers),
+                    )
+            except Exception as e:
+                traceback.print_exc()
+                self._registry.update_status(service.name, ServiceStatus.DEGRADED)
+                return JSONResponse(content={"error": "Service unavailable", "details": str(e)}, status_code=503)

hypern/gateway/service.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class ServiceStatus(Enum):
+    ONLINE = "online"
+    OFFLINE = "offline"
+    DEGRADED = "degraded"
+
+
+@dataclass
+class ServiceConfig:
+    name: str
+    url: str
+    prefix: str
+    timeout: float = 30.0
+    max_retries: int = 3
+    health_check_path: str = "/health"
+
+
+class ServiceRegistry:
+    def __init__(self):
+        self._services: Dict[str, ServiceConfig] = {}
+        self._status: Dict[str, ServiceStatus] = {}
+        self._metadata: Dict[str, Dict[str, Any]] = {}
+
+    def register(self, service: ServiceConfig, metadata: Optional[Dict[str, Any]] = None):
+        self._services[service.name] = service
+        self._status[service.name] = ServiceStatus.ONLINE
+        self._metadata[service.name] = metadata or {}
+
+    def unregister(self, service_name: str):
+        self._services.pop(service_name, None)
+        self._status.pop(service_name, None)
+        self._metadata.pop(service_name, None)
+
+    def get_service(self, service_name: str) -> Optional[ServiceConfig]:
+        return self._services.get(service_name)
+
+    def get_service_by_prefix(self, path: str) -> Optional[ServiceConfig]:
+        for service in self._services.values():
+            if path.startswith(service.prefix):
+                return service
+        return None
+
+    def update_status(self, service_name: str, status: ServiceStatus):
+        if service_name in self._services:
+            self._status[service_name] = status
+
+    def get_status(self, service_name: str) -> ServiceStatus:
+        return self._status.get(service_name, ServiceStatus.OFFLINE)