vega-framework 0.1.34__py3-none-any.whl → 0.2.0__py3-none-any.whl

vega/web/route_middleware.py

@@ -0,0 +1,266 @@
+"""Route-level middleware system for Vega Web Framework"""
+
+from typing import Callable, List, Optional, Union, Any
+from enum import Enum
+from functools import wraps
+import inspect
+
+from .request import Request
+from .response import Response, JSONResponse
+
+
+class MiddlewarePhase(str, Enum):
+    """When the middleware should execute"""
+    BEFORE = "before"  # Execute before the handler
+    AFTER = "after"    # Execute after the handler
+    BOTH = "both"      # Execute both before and after
+
+
+class RouteMiddleware:
+    """
+    Base class for route-level middleware.
+
+    Route middleware can execute before or after the handler function,
+    allowing for request preprocessing, response postprocessing, or both.
+
+    Attributes:
+        phase: When to execute (BEFORE, AFTER, or BOTH)
+
+    Example:
+        class AuthMiddleware(RouteMiddleware):
+            def __init__(self):
+                super().__init__(phase=MiddlewarePhase.BEFORE)
+
+            async def before(self, request: Request) -> Optional[Response]:
+                token = request.headers.get("Authorization")
+                if not token:
+                    return JSONResponse(
+                        {"detail": "Missing authorization"},
+                        status_code=401
+                    )
+                # Continue to handler
+                return None
+
+        @router.get("/protected")
+        @middleware(AuthMiddleware())
+        async def protected_route():
+            return {"message": "Protected data"}
+    """
+
+    def __init__(self, phase: MiddlewarePhase = MiddlewarePhase.BEFORE):
+        self.phase = phase
+
+    async def before(self, request: Request) -> Optional[Response]:
+        """
+        Execute before the handler.
+
+        Args:
+            request: The incoming request
+
+        Returns:
+            Optional[Response]: Return a Response to short-circuit,
+                              or None to continue to the handler
+        """
+        return None
+
+    async def after(
+        self,
+        request: Request,
+        response: Response
+    ) -> Response:
+        """
+        Execute after the handler.
+
+        Args:
+            request: The incoming request
+            response: The response from the handler
+
+        Returns:
+            Response: Modified or original response
+        """
+        return response
+
+    async def process(
+        self,
+        request: Request,
+        handler: Callable,
+        **kwargs
+    ) -> Response:
+        """
+        Process the middleware chain.
+
+        Args:
+            request: The incoming request
+            handler: The route handler function
+            **kwargs: Handler keyword arguments
+
+        Returns:
+            Response object
+        """
+        # Execute before phase
+        if self.phase in (MiddlewarePhase.BEFORE, MiddlewarePhase.BOTH):
+            before_response = await self.before(request)
+            if before_response is not None:
+                # Short-circuit: return response without calling handler
+                return before_response
+
+        # Call the handler
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(**kwargs)
+        else:
+            result = handler(**kwargs)
+
+        # Convert result to Response if needed
+        if isinstance(result, (Response, JSONResponse)):
+            response = result
+        elif isinstance(result, dict):
+            response = JSONResponse(content=result)
+        elif isinstance(result, (list, tuple)):
+            response = JSONResponse(content=result)
+        elif isinstance(result, str):
+            response = Response(content=result)
+        elif result is None:
+            response = Response(content=b"")
+        else:
+            response = JSONResponse(content=result)
+
+        # Execute after phase
+        if self.phase in (MiddlewarePhase.AFTER, MiddlewarePhase.BOTH):
+            response = await self.after(request, response)
+
+        return response
+
+
+class MiddlewareChain:
+    """
+    Manages a chain of middleware for a route.
+
+    Example:
+        chain = MiddlewareChain([AuthMiddleware(), LoggingMiddleware()])
+        response = await chain.execute(request, handler, user_id="123")
+    """
+
+    def __init__(self, middlewares: List[RouteMiddleware]):
+        self.middlewares = middlewares
+
+    async def execute(
+        self,
+        request: Request,
+        handler: Callable,
+        **kwargs
+    ) -> Response:
+        """
+        Execute the middleware chain.
+
+        Args:
+            request: The incoming request
+            handler: The route handler
+            **kwargs: Handler arguments
+
+        Returns:
+            Response object
+        """
+        if not self.middlewares:
+            # No middleware, call handler directly
+            if inspect.iscoroutinefunction(handler):
+                result = await handler(**kwargs)
+            else:
+                result = handler(**kwargs)
+
+            # Convert to response
+            if isinstance(result, (Response, JSONResponse)):
+                return result
+            elif isinstance(result, dict):
+                return JSONResponse(content=result)
+            elif isinstance(result, (list, tuple)):
+                return JSONResponse(content=result)
+            elif isinstance(result, str):
+                return Response(content=result)
+            elif result is None:
+                return Response(content=b"")
+            else:
+                return JSONResponse(content=result)
+
+        # Execute BEFORE middleware
+        for mw in self.middlewares:
+            if mw.phase in (MiddlewarePhase.BEFORE, MiddlewarePhase.BOTH):
+                before_response = await mw.before(request)
+                if before_response is not None:
+                    # Short-circuit
+                    return before_response
+
+        # Call handler - check if it needs request parameter
+        sig = inspect.signature(handler)
+        handler_params = sig.parameters
+
+        # Add request to kwargs if handler expects it
+        if "request" in handler_params or any(
+            p.annotation.__name__ == "Request" if hasattr(p.annotation, "__name__") else False
+            for p in handler_params.values()
+        ):
+            kwargs["request"] = request
+
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(**kwargs)
+        else:
+            result = handler(**kwargs)
+
+        # Convert to response
+        if isinstance(result, (Response, JSONResponse)):
+            response = result
+        elif isinstance(result, dict):
+            response = JSONResponse(content=result)
+        elif isinstance(result, (list, tuple)):
+            response = JSONResponse(content=result)
+        elif isinstance(result, str):
+            response = Response(content=result)
+        elif result is None:
+            response = Response(content=b"")
+        else:
+            response = JSONResponse(content=result)
+
+        # Execute AFTER middleware (in reverse order)
+        for mw in reversed(self.middlewares):
+            if mw.phase in (MiddlewarePhase.AFTER, MiddlewarePhase.BOTH):
+                response = await mw.after(request, response)
+
+        return response
+
+
+def middleware(*middlewares: RouteMiddleware) -> Callable:
+    """
+    Decorator to attach middleware to a route handler.
+
+    Args:
+        *middlewares: One or more RouteMiddleware instances
+
+    Example:
+        @router.get("/users/{user_id}")
+        @middleware(AuthMiddleware(), LoggingMiddleware())
+        async def get_user(user_id: str):
+            return {"id": user_id}
+
+        # Or single middleware
+        @router.post("/admin/action")
+        @middleware(AdminOnlyMiddleware())
+        async def admin_action():
+            return {"status": "done"}
+    """
+    middleware_list = list(middlewares)
+
+    def decorator(func: Callable) -> Callable:
+        # Store middleware list on the function
+        if not hasattr(func, '_route_middlewares'):
+            func._route_middlewares = []
+        func._route_middlewares.extend(middleware_list)
+        return func
+
+    return decorator
+
+
+__all__ = [
+    "RouteMiddleware",
+    "MiddlewarePhase",
+    "MiddlewareChain",
+    "middleware",
+]

vega/web/router.py

@@ -0,0 +1,350 @@
+"""Router class for Vega Web Framework"""
+
+from typing import Any, Callable, List, Optional, Sequence, Type
+
+from starlette.routing import Mount
+
+from .routing import Route, route as create_route
+
+
+class Router:
+    """
+    HTTP Router for organizing endpoints.
+
+    Similar to FastAPI's APIRouter, this class allows you to group related
+    endpoints together with common configuration like prefix, tags, etc.
+
+    Args:
+        prefix: URL prefix for all routes (e.g., "/api/v1")
+        tags: Default tags for all routes
+        dependencies: Shared dependencies (future feature)
+        responses: Common response models (future feature)
+
+    Example:
+        router = Router(prefix="/users", tags=["users"])
+
+        @router.get("/{user_id}")
+        async def get_user(user_id: str):
+            return {"id": user_id, "name": "John"}
+
+        @router.post("")
+        async def create_user(request: Request):
+            data = await request.json()
+            return {"id": "new_id", **data}
+    """
+
+    def __init__(
+        self,
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+        dependencies: Optional[Sequence[Any]] = None,
+        responses: Optional[dict] = None,
+    ):
+        self.prefix = prefix
+        self.tags = tags or []
+        self.dependencies = dependencies or []
+        self.responses = responses or {}
+        self.routes: List[Route] = []
+        self.child_routers: List[tuple[Router, str, Optional[List[str]]]] = []
+
+    def add_route(
+        self,
+        path: str,
+        endpoint: Callable,
+        methods: List[str],
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 200,
+    ) -> None:
+        """
+        Add a route to the router.
+
+        Args:
+            path: URL path pattern
+            endpoint: Handler function
+            methods: HTTP methods
+            name: Optional route name
+            include_in_schema: Include in API docs
+            tags: Route tags
+            summary: Short description
+            description: Longer description
+            response_model: Expected response type
+            status_code: Default status code
+        """
+        # Merge router tags with route-specific tags
+        route_tags = (tags or []) + self.tags
+
+        route_obj = Route(
+            path=path,
+            endpoint=endpoint,
+            methods=methods,
+            name=name,
+            include_in_schema=include_in_schema,
+            tags=route_tags,
+            summary=summary,
+            description=description,
+            response_model=response_model,
+            status_code=status_code,
+        )
+        self.routes.append(route_obj)
+
+    def route(
+        self,
+        path: str,
+        methods: List[str],
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 200,
+    ) -> Callable:
+        """
+        Decorator to add a route.
+
+        Example:
+            @router.route("/items", methods=["GET", "POST"])
+            async def items():
+                return {"items": []}
+        """
+
+        def decorator(func: Callable) -> Callable:
+            self.add_route(
+                path=path,
+                endpoint=func,
+                methods=methods,
+                name=name,
+                include_in_schema=include_in_schema,
+                tags=tags,
+                summary=summary,
+                description=description,
+                response_model=response_model,
+                status_code=status_code,
+            )
+            return func
+
+        return decorator
+
+    def get(
+        self,
+        path: str,
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 200,
+    ) -> Callable:
+        """
+        Decorator for GET requests.
+
+        Example:
+            @router.get("/items/{item_id}")
+            async def get_item(item_id: str):
+                return {"id": item_id}
+        """
+        return self.route(
+            path,
+            methods=["GET"],
+            name=name,
+            include_in_schema=include_in_schema,
+            tags=tags,
+            summary=summary,
+            description=description,
+            response_model=response_model,
+            status_code=status_code,
+        )
+
+    def post(
+        self,
+        path: str,
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 201,
+    ) -> Callable:
+        """
+        Decorator for POST requests.
+
+        Example:
+            @router.post("/items")
+            async def create_item(request: Request):
+                data = await request.json()
+                return {"id": "new", **data}
+        """
+        return self.route(
+            path,
+            methods=["POST"],
+            name=name,
+            include_in_schema=include_in_schema,
+            tags=tags,
+            summary=summary,
+            description=description,
+            response_model=response_model,
+            status_code=status_code,
+        )
+
+    def put(
+        self,
+        path: str,
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 200,
+    ) -> Callable:
+        """Decorator for PUT requests."""
+        return self.route(
+            path,
+            methods=["PUT"],
+            name=name,
+            include_in_schema=include_in_schema,
+            tags=tags,
+            summary=summary,
+            description=description,
+            response_model=response_model,
+            status_code=status_code,
+        )
+
+    def patch(
+        self,
+        path: str,
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 200,
+    ) -> Callable:
+        """Decorator for PATCH requests."""
+        return self.route(
+            path,
+            methods=["PATCH"],
+            name=name,
+            include_in_schema=include_in_schema,
+            tags=tags,
+            summary=summary,
+            description=description,
+            response_model=response_model,
+            status_code=status_code,
+        )
+
+    def delete(
+        self,
+        path: str,
+        *,
+        name: Optional[str] = None,
+        include_in_schema: bool = True,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        response_model: Optional[Type] = None,
+        status_code: int = 204,
+    ) -> Callable:
+        """Decorator for DELETE requests."""
+        return self.route(
+            path,
+            methods=["DELETE"],
+            name=name,
+            include_in_schema=include_in_schema,
+            tags=tags,
+            summary=summary,
+            description=description,
+            response_model=response_model,
+            status_code=status_code,
+        )
+
+    def include_router(
+        self,
+        router: "Router",
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Include another router's routes in this router.
+
+        Args:
+            router: Router to include
+            prefix: Additional prefix for included routes
+            tags: Additional tags for included routes
+
+        Example:
+            users_router = Router()
+            @users_router.get("/{user_id}")
+            async def get_user(user_id: str):
+                return {"id": user_id}
+
+            main_router = Router()
+            main_router.include_router(users_router, prefix="/users", tags=["users"])
+        """
+        self.child_routers.append((router, prefix, tags))
+
+    def get_routes(self) -> List[Route]:
+        """
+        Get all routes including child routers.
+
+        Returns:
+            List of Route objects with prefixes applied
+        """
+        routes = []
+
+        # Add direct routes with prefix
+        for route in self.routes:
+            # Create a copy with the prefix applied
+            prefixed_route = Route(
+                path=self.prefix + route.path,
+                endpoint=route.endpoint,
+                methods=route.methods,
+                name=route.name,
+                include_in_schema=route.include_in_schema,
+                tags=route.tags,
+                summary=route.summary,
+                description=route.description,
+                response_model=route.response_model,
+                status_code=route.status_code,
+            )
+            routes.append(prefixed_route)
+
+        # Add child router routes
+        for child_router, child_prefix, child_tags in self.child_routers:
+            for route in child_router.get_routes():
+                # Apply additional prefix and tags
+                combined_prefix = self.prefix + child_prefix
+                combined_tags = route.tags + (child_tags or [])
+
+                prefixed_route = Route(
+                    path=combined_prefix + route.path,
+                    endpoint=route.endpoint,
+                    methods=route.methods,
+                    name=route.name,
+                    include_in_schema=route.include_in_schema,
+                    tags=combined_tags,
+                    summary=route.summary,
+                    description=route.description,
+                    response_model=route.response_model,
+                    status_code=route.status_code,
+                )
+                routes.append(prefixed_route)
+
+        return routes
+
+
+__all__ = ["Router"]