tachyon-api 0.9.0__py3-none-any.whl

tachyon_api/processing/response_processor.py

@@ -0,0 +1,93 @@
+"""
+Response processing for Tachyon applications.
+
+Handles:
+- Response model validation
+- Struct serialization
+- Background task execution
+- Response type detection
+"""
+
+import asyncio
+import msgspec
+from typing import Any, Optional
+
+from starlette.responses import Response
+
+from ..models import Struct
+from ..responses import TachyonJSONResponse, response_validation_error_response
+
+
+class ResponseProcessor:
+    """
+    Processes endpoint return values into HTTP responses.
+    
+    This class encapsulates the logic for:
+    - Running background tasks
+    - Validating against response_model
+    - Converting Struct to JSON
+    - Creating TachyonJSONResponse
+    """
+    
+    @staticmethod
+    async def process_response(
+        payload: Any,
+        response_model: Optional[type],
+        background_tasks: Optional[Any],
+    ) -> Response:
+        """
+        Process the endpoint return value into an HTTP response.
+        
+        Args:
+            payload: The value returned by the endpoint
+            response_model: Optional Struct class for validation
+            background_tasks: Optional BackgroundTasks instance to execute
+        
+        Returns:
+            A Starlette Response object
+        """
+        # Run background tasks if any were registered
+        if background_tasks is not None:
+            await background_tasks.run_tasks()
+
+        # If the endpoint already returned a Response object, return it directly
+        if isinstance(payload, Response):
+            return payload
+
+        # Validate/convert response against response_model if provided
+        if response_model is not None:
+            try:
+                payload = msgspec.convert(payload, response_model)
+            except Exception as e:
+                return response_validation_error_response(str(e))
+
+        # Convert Struct objects to dictionaries for JSON serialization
+        if isinstance(payload, Struct):
+            payload = msgspec.to_builtins(payload)
+        elif isinstance(payload, dict):
+            # Convert any Struct values in the dictionary
+            for key, value in payload.items():
+                if isinstance(value, Struct):
+                    payload[key] = msgspec.to_builtins(value)
+
+        return TachyonJSONResponse(payload)
+    
+    @staticmethod
+    async def call_endpoint(
+        endpoint_func,
+        kwargs_to_inject: dict,
+    ) -> Any:
+        """
+        Call the endpoint function with injected parameters.
+        
+        Args:
+            endpoint_func: The endpoint function to call
+            kwargs_to_inject: Dictionary of parameters to inject
+        
+        Returns:
+            The payload returned by the endpoint
+        """
+        if asyncio.iscoroutinefunction(endpoint_func):
+            return await endpoint_func(**kwargs_to_inject)
+        else:
+            return endpoint_func(**kwargs_to_inject)

tachyon_api/responses.py

@@ -0,0 +1,92 @@
+"""
+Simple response helpers for Tachyon API
+
+Provides convenient response helpers while keeping full compatibility
+with Starlette responses.
+"""
+
+from starlette.responses import JSONResponse, HTMLResponse  # noqa
+from .models import encode_json
+
+
+class TachyonJSONResponse(JSONResponse):
+    """High-performance JSON response using orjson for serialization."""
+
+    media_type = "application/json"
+
+    def render(self, content) -> bytes:  # type: ignore[override]
+        # Use centralized encoder to support Struct, UUID, date, datetime, etc.
+        return encode_json(content)
+
+
+# Simple helper functions for common response patterns
+def success_response(data=None, message="Success", status_code=200):
+    """Create a success response with consistent structure"""
+    return TachyonJSONResponse(
+        {"success": True, "message": message, "data": data}, status_code=status_code
+    )
+
+
+def error_response(error, status_code=400, code=None):
+    """Create an error response with consistent structure"""
+    response_data = {"success": False, "error": error}
+    if code:
+        response_data["code"] = code
+
+    return TachyonJSONResponse(response_data, status_code=status_code)
+
+
+def not_found_response(error="Resource not found"):
+    """Create a 404 not found response"""
+    return error_response(error, status_code=404, code="NOT_FOUND")
+
+
+def conflict_response(error="Resource conflict"):
+    """Create a 409 conflict response"""
+    return error_response(error, status_code=409, code="CONFLICT")
+
+
+def validation_error_response(error="Validation failed", errors=None):
+    """Create a 422 validation error response"""
+    response_data = {"success": False, "error": error, "code": "VALIDATION_ERROR"}
+    if errors:
+        response_data["errors"] = errors
+
+    return TachyonJSONResponse(response_data, status_code=422)
+
+
+def response_validation_error_response(error="Response validation error"):
+    """Create a 500 response validation error response"""
+    # Normalize message with prefix and include 'detail' for backward compatibility
+    msg = str(error)
+    if not msg.lower().startswith("response validation error"):
+        msg = f"Response validation error: {msg}"
+    return TachyonJSONResponse(
+        {
+            "success": False,
+            "error": msg,
+            "detail": msg,
+            "code": "RESPONSE_VALIDATION_ERROR",
+        },
+        status_code=500,
+    )
+
+
+def internal_server_error_response():
+    """Create a 500 internal server error response for unhandled exceptions.
+
+    This intentionally avoids leaking internal exception details in the payload.
+    """
+    return TachyonJSONResponse(
+        {
+            "success": False,
+            "error": "Internal Server Error",
+            "code": "INTERNAL_SERVER_ERROR",
+        },
+        status_code=500,
+    )
+
+
+# Re-export Starlette responses for convenience
+# JSONResponse is already imported above
+# HTMLResponse is now also imported

tachyon_api/router.py

@@ -0,0 +1,161 @@
+"""
+Tachyon Router Module
+
+Provides route grouping functionality similar to FastAPI's APIRouter,
+allowing for better organization of routes with common prefixes, tags, and dependencies.
+"""
+
+from functools import partial
+from typing import List, Optional, Any, Callable, Dict
+
+from .di import Depends
+
+
+class Router:
+    """
+    Router class for grouping related routes with common configuration.
+
+    Similar to FastAPI's APIRouter, allows grouping routes with:
+    - Common prefixes
+    - Common tags
+    - Common dependencies
+    - Better organization of related endpoints
+
+    Note: Router stores route definitions but doesn't implement the actual routing logic.
+    The routing logic is handled by the main Tachyon app when the router is included.
+    """
+
+    def __init__(
+        self,
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+        dependencies: Optional[List[Depends]] = None,
+        responses: Optional[Dict[int, Dict[str, Any]]] = None,
+    ):
+        """
+        Initialize a new Router instance.
+
+        Args:
+            prefix: Common prefix for all routes in this router
+            tags: List of tags to apply to all routes
+            dependencies: List of dependencies to apply to all routes
+            responses: Common responses for OpenAPI documentation
+        """
+        # Normalize prefix - ensure it starts with / if not empty
+        if prefix and not prefix.startswith("/"):
+            prefix = "/" + prefix
+        elif prefix is None:
+            prefix = ""
+
+        self.prefix = prefix
+        self.tags = tags or []
+        self.dependencies = dependencies or []
+        self.responses = responses or {}
+        self.routes: List[Dict[str, Any]] = []
+
+        # Create HTTP method decorators using the same pattern as Tachyon
+        http_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
+        for method in http_methods:
+            setattr(
+                self,
+                method.lower(),
+                partial(self._create_route_decorator, http_method=method),
+            )
+
+    def _create_route_decorator(self, path: str, *, http_method: str, **kwargs):
+        """
+        Create a decorator for the specified HTTP method.
+
+        This method is similar to Tachyon's _create_decorator but stores routes
+        instead of registering them immediately.
+
+        Args:
+            path: URL path pattern (will be prefixed with router prefix)
+            http_method: HTTP method name (GET, POST, PUT, DELETE, etc.)
+            **kwargs: Additional route options (summary, description, tags, etc.)
+
+        Returns:
+            A decorator function that stores the endpoint with the router
+        """
+
+        def decorator(endpoint_func: Callable):
+            # Combine router tags with route-specific tags
+            route_tags = list(self.tags)  # Start with router tags
+            if "tags" in kwargs:
+                if isinstance(kwargs["tags"], list):
+                    route_tags.extend(kwargs["tags"])
+                else:
+                    route_tags.append(kwargs["tags"])
+
+            # Update kwargs with combined tags
+            if route_tags:
+                kwargs["tags"] = route_tags
+
+            # Store the route information for later registration
+            route_info = {
+                "path": path,
+                "method": http_method,
+                "func": endpoint_func,
+                "dependencies": self.dependencies.copy(),
+                **kwargs,
+            }
+
+            self.routes.append(route_info)
+            return endpoint_func
+
+        return decorator
+
+    def websocket(self, path: str):
+        """
+        Decorator to register a WebSocket endpoint with this router.
+
+        Args:
+            path: URL path pattern for the WebSocket endpoint
+
+        Returns:
+            A decorator that stores the WebSocket handler
+
+        Example:
+            router = Router(prefix="/api")
+
+            @router.websocket("/ws")
+            async def websocket_endpoint(websocket):
+                await websocket.accept()
+                await websocket.send_text("Hello from router!")
+                await websocket.close()
+        """
+
+        def decorator(endpoint_func: Callable):
+            route_info = {
+                "path": path,
+                "method": "WEBSOCKET",
+                "func": endpoint_func,
+                "is_websocket": True,
+            }
+            self.routes.append(route_info)
+            return endpoint_func
+
+        return decorator
+
+    def get_full_path(self, path: str) -> str:
+        """
+        Get the full path by combining router prefix with route path.
+
+        Args:
+            path: The route path
+
+        Returns:
+            Full path with prefix applied
+        """
+        if not self.prefix:
+            return path
+
+        # Handle root path specially
+        if path == "/":
+            return self.prefix
+
+        # Combine prefix and path, avoiding double slashes
+        if path.startswith("/"):
+            return self.prefix + path
+        else:
+            return self.prefix + "/" + path

tachyon_api/security.py

@@ -0,0 +1,295 @@
+"""
+Tachyon Security Module
+
+Provides security schemes for authentication and authorization,
+compatible with FastAPI's security utilities.
+"""
+
+import base64
+from typing import Optional
+
+from starlette.requests import Request
+
+from .exceptions import HTTPException
+
+
+class HTTPAuthorizationCredentials:
+    """
+    Credentials extracted from HTTP Authorization header.
+
+    Attributes:
+        scheme: The authentication scheme (e.g., "Bearer", "Basic")
+        credentials: The credentials value (e.g., the token or encoded credentials)
+    """
+
+    def __init__(self, scheme: str, credentials: str):
+        self.scheme = scheme
+        self.credentials = credentials
+
+
+class HTTPBasicCredentials:
+    """
+    Credentials extracted from HTTP Basic authentication.
+
+    Attributes:
+        username: The decoded username
+        password: The decoded password
+    """
+
+    def __init__(self, username: str, password: str):
+        self.username = username
+        self.password = password
+
+
+class HTTPBearer:
+    """
+    HTTP Bearer token authentication scheme.
+
+    Extracts Bearer token from the Authorization header.
+
+    Args:
+        auto_error: If True (default), raises HTTPException on missing/invalid token.
+                   If False, returns None instead.
+
+    Example:
+        security = HTTPBearer()
+
+        @app.get("/protected")
+        def protected(credentials: HTTPAuthorizationCredentials = Depends(security)):
+            return {"token": credentials.credentials}
+    """
+
+    def __init__(self, auto_error: bool = True):
+        self.auto_error = auto_error
+
+    async def __call__(
+        self, request: Request
+    ) -> Optional[HTTPAuthorizationCredentials]:
+        authorization = request.headers.get("Authorization")
+
+        if not authorization:
+            if self.auto_error:
+                raise HTTPException(status_code=403, detail="Not authenticated")
+            return None
+
+        parts = authorization.split()
+        if len(parts) != 2:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=403, detail="Invalid authorization header"
+                )
+            return None
+
+        scheme, credentials = parts
+
+        if scheme.lower() != "bearer":
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=403, detail="Invalid authentication scheme"
+                )
+            return None
+
+        return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
+
+
+class HTTPBasic:
+    """
+    HTTP Basic authentication scheme.
+
+    Extracts and decodes username/password from the Authorization header.
+
+    Args:
+        auto_error: If True (default), raises HTTPException on missing/invalid credentials.
+                   If False, returns None instead.
+        realm: The realm name to include in WWW-Authenticate header.
+
+    Example:
+        security = HTTPBasic()
+
+        @app.get("/admin")
+        def admin(credentials: HTTPBasicCredentials = Depends(security)):
+            if credentials.username == "admin" and credentials.password == "secret":
+                return {"message": "Welcome, admin!"}
+            raise HTTPException(status_code=401, detail="Invalid credentials")
+    """
+
+    def __init__(self, auto_error: bool = True, realm: Optional[str] = None):
+        self.auto_error = auto_error
+        self.realm = realm or "simple"
+
+    async def __call__(self, request: Request) -> Optional[HTTPBasicCredentials]:
+        authorization = request.headers.get("Authorization")
+
+        if not authorization:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Not authenticated",
+                    headers={"WWW-Authenticate": f'Basic realm="{self.realm}"'},
+                )
+            return None
+
+        parts = authorization.split()
+        if len(parts) != 2 or parts[0].lower() != "basic":
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Invalid authentication credentials",
+                    headers={"WWW-Authenticate": f'Basic realm="{self.realm}"'},
+                )
+            return None
+
+        try:
+            decoded = base64.b64decode(parts[1]).decode("utf-8")
+            username, password = decoded.split(":", 1)
+            return HTTPBasicCredentials(username=username, password=password)
+        except Exception:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Invalid authentication credentials",
+                    headers={"WWW-Authenticate": f'Basic realm="{self.realm}"'},
+                )
+            return None
+
+
+class APIKeyHeader:
+    """
+    API Key authentication via HTTP header.
+
+    Args:
+        name: The header name to look for (e.g., "X-API-Key")
+        auto_error: If True (default), raises HTTPException on missing key.
+
+    Example:
+        api_key = APIKeyHeader(name="X-API-Key")
+
+        @app.get("/api")
+        def api_endpoint(key: str = Depends(api_key)):
+            return {"api_key": key}
+    """
+
+    def __init__(self, name: str, auto_error: bool = True):
+        self.name = name
+        self.auto_error = auto_error
+
+    async def __call__(self, request: Request) -> Optional[str]:
+        api_key = request.headers.get(self.name)
+
+        if not api_key:
+            if self.auto_error:
+                raise HTTPException(status_code=403, detail="Not authenticated")
+            return None
+
+        return api_key
+
+
+class APIKeyQuery:
+    """
+    API Key authentication via query parameter.
+
+    Args:
+        name: The query parameter name to look for (e.g., "api_key")
+        auto_error: If True (default), raises HTTPException on missing key.
+
+    Example:
+        api_key = APIKeyQuery(name="api_key")
+
+        @app.get("/api")
+        def api_endpoint(key: str = Depends(api_key)):
+            return {"api_key": key}
+    """
+
+    def __init__(self, name: str, auto_error: bool = True):
+        self.name = name
+        self.auto_error = auto_error
+
+    async def __call__(self, request: Request) -> Optional[str]:
+        api_key = request.query_params.get(self.name)
+
+        if not api_key:
+            if self.auto_error:
+                raise HTTPException(status_code=403, detail="Not authenticated")
+            return None
+
+        return api_key
+
+
+class APIKeyCookie:
+    """
+    API Key authentication via cookie.
+
+    Args:
+        name: The cookie name to look for (e.g., "session_token")
+        auto_error: If True (default), raises HTTPException on missing key.
+
+    Example:
+        api_key = APIKeyCookie(name="session_token")
+
+        @app.get("/api")
+        def api_endpoint(key: str = Depends(api_key)):
+            return {"api_key": key}
+    """
+
+    def __init__(self, name: str, auto_error: bool = True):
+        self.name = name
+        self.auto_error = auto_error
+
+    async def __call__(self, request: Request) -> Optional[str]:
+        api_key = request.cookies.get(self.name)
+
+        if not api_key:
+            if self.auto_error:
+                raise HTTPException(status_code=403, detail="Not authenticated")
+            return None
+
+        return api_key
+
+
+class OAuth2PasswordBearer:
+    """
+    OAuth2 Password Bearer token scheme.
+
+    Extracts the token from Authorization header (Bearer scheme).
+    Similar to HTTPBearer but returns just the token string and uses 401 status.
+
+    Args:
+        tokenUrl: The URL to obtain the token (for OpenAPI documentation).
+        auto_error: If True (default), raises HTTPException on missing token.
+
+    Example:
+        oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")
+
+        @app.get("/users/me")
+        def get_current_user(token: str = Depends(oauth2_scheme)):
+            # Decode and validate token here
+            return {"token": token}
+    """
+
+    def __init__(self, tokenUrl: str, auto_error: bool = True):
+        self.tokenUrl = tokenUrl
+        self.auto_error = auto_error
+
+    async def __call__(self, request: Request) -> Optional[str]:
+        authorization = request.headers.get("Authorization")
+
+        if not authorization:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Not authenticated",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            return None
+
+        parts = authorization.split()
+        if len(parts) != 2 or parts[0].lower() != "bearer":
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Invalid authentication credentials",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            return None
+
+        return parts[1]