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

vega/web/__init__.py

@@ -0,0 +1,100 @@
+"""
+Vega Web Framework
+
+A lightweight web framework built on Starlette, providing a FastAPI-like
+developer experience while being deeply integrated with Vega's architecture.
+
+Example:
+    from vega.web import Router, VegaApp, HTTPException, status
+
+    router = Router()
+
+    @router.get("/users/{user_id}")
+    async def get_user(user_id: str):
+        if user_id == "invalid":
+            raise HTTPException(status_code=404, detail="User not found")
+        return {"id": user_id, "name": "John"}
+
+    app = VegaApp(title="My API", version="1.0.0")
+    app.include_router(router, prefix="/api")
+
+    # Run with: uvicorn main:app --reload
+"""
+
+__version__ = "0.1.0"
+
+# Core application
+from .application import VegaApp
+
+# Routing
+from .router import Router
+
+# Request/Response
+from .request import Request
+from .response import (
+    Response,
+    JSONResponse,
+    HTMLResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    StreamingResponse,
+    FileResponse,
+)
+
+# Exceptions
+from .exceptions import (
+    HTTPException,
+    ValidationError,
+    NotFoundError,
+    UnauthorizedError,
+    ForbiddenError,
+    BadRequestError,
+    status,
+)
+
+# Middleware (optional, can be imported explicitly)
+from .middleware import (
+    VegaMiddleware,
+    CORSMiddleware,
+    RequestLoggingMiddleware,
+)
+
+# Route middleware
+from .route_middleware import (
+    RouteMiddleware,
+    MiddlewarePhase,
+    middleware,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core
+    "VegaApp",
+    "Router",
+    # Request/Response
+    "Request",
+    "Response",
+    "JSONResponse",
+    "HTMLResponse",
+    "PlainTextResponse",
+    "RedirectResponse",
+    "StreamingResponse",
+    "FileResponse",
+    # Exceptions
+    "HTTPException",
+    "ValidationError",
+    "NotFoundError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "BadRequestError",
+    "status",
+    # Middleware
+    "VegaMiddleware",
+    "CORSMiddleware",
+    "RequestLoggingMiddleware",
+    # Route Middleware
+    "RouteMiddleware",
+    "MiddlewarePhase",
+    "middleware",
+]

vega/web/application.py

@@ -0,0 +1,234 @@
+"""Main application class for Vega Web Framework"""
+
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.routing import Mount, Route as StarletteRoute
+from starlette.types import ASGIApp
+
+from .router import Router
+from .exceptions import HTTPException
+from .response import JSONResponse
+
+
+class VegaApp:
+    """
+    Main application class for Vega Web Framework.
+
+    This is the core ASGI application that handles all HTTP requests.
+    It's built on Starlette but provides a FastAPI-like API for familiarity.
+
+    Args:
+        title: Application title
+        description: Application description
+        version: Application version
+        debug: Enable debug mode
+        middleware: List of middleware to apply
+        on_startup: Functions to run on startup
+        on_shutdown: Functions to run on shutdown
+
+    Example:
+        app = VegaApp(
+            title="My API",
+            version="1.0.0",
+            debug=True
+        )
+
+        @app.get("/")
+        async def root():
+            return {"message": "Hello World"}
+
+        # Or with routers
+        router = Router(prefix="/api")
+        @router.get("/users")
+        async def get_users():
+            return {"users": []}
+
+        app.include_router(router)
+    """
+
+    def __init__(
+        self,
+        *,
+        title: str = "Vega API",
+        description: str = "",
+        version: str = "0.1.0",
+        debug: bool = False,
+        middleware: Optional[Sequence[Middleware]] = None,
+        on_startup: Optional[Sequence[Callable]] = None,
+        on_shutdown: Optional[Sequence[Callable]] = None,
+    ):
+        self.title = title
+        self.description = description
+        self.version = version
+        self.debug = debug
+
+        # Internal router for top-level routes
+        self._router = Router()
+
+        # Middleware stack
+        self._middleware = list(middleware) if middleware else []
+
+        # Lifecycle handlers
+        self._on_startup = list(on_startup) if on_startup else []
+        self._on_shutdown = list(on_shutdown) if on_shutdown else []
+
+        # Starlette app (created lazily)
+        self._starlette_app: Optional[Starlette] = None
+
+    def add_middleware(
+        self,
+        middleware_class: type,
+        **options: Any,
+    ) -> None:
+        """
+        Add middleware to the application.
+
+        Args:
+            middleware_class: Middleware class
+            **options: Middleware configuration options
+
+        Example:
+            from starlette.middleware.cors import CORSMiddleware
+
+            app.add_middleware(
+                CORSMiddleware,
+                allow_origins=["*"],
+                allow_methods=["*"],
+            )
+        """
+        self._middleware.append(Middleware(middleware_class, **options))
+        # Invalidate cached Starlette app
+        self._starlette_app = None
+
+    def on_event(self, event_type: str) -> Callable:
+        """
+        Register lifecycle event handler.
+
+        Args:
+            event_type: Either "startup" or "shutdown"
+
+        Example:
+            @app.on_event("startup")
+            async def startup():
+                print("Starting up!")
+
+            @app.on_event("shutdown")
+            async def shutdown():
+                print("Shutting down!")
+        """
+
+        def decorator(func: Callable) -> Callable:
+            if event_type == "startup":
+                self._on_startup.append(func)
+            elif event_type == "shutdown":
+                self._on_shutdown.append(func)
+            else:
+                raise ValueError(f"Invalid event type: {event_type}")
+            # Invalidate cached Starlette app
+            self._starlette_app = None
+            return func
+
+        return decorator
+
+    def include_router(
+        self,
+        router: Router,
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Include a router in the application.
+
+        Args:
+            router: Router to include
+            prefix: URL prefix for all routes
+            tags: Tags to add to all routes
+
+        Example:
+            users_router = Router()
+            @users_router.get("/{user_id}")
+            async def get_user(user_id: str):
+                return {"id": user_id}
+
+            app.include_router(users_router, prefix="/users", tags=["users"])
+        """
+        self._router.include_router(router, prefix=prefix, tags=tags)
+        # Invalidate cached Starlette app
+        self._starlette_app = None
+
+    def get(self, path: str, **kwargs: Any) -> Callable:
+        """
+        Decorator for GET requests.
+
+        Example:
+            @app.get("/items/{item_id}")
+            async def get_item(item_id: str):
+                return {"id": item_id}
+        """
+        return self._router.get(path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Callable:
+        """Decorator for POST requests."""
+        return self._router.post(path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Callable:
+        """Decorator for PUT requests."""
+        return self._router.put(path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Callable:
+        """Decorator for PATCH requests."""
+        return self._router.patch(path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Callable:
+        """Decorator for DELETE requests."""
+        return self._router.delete(path, **kwargs)
+
+    def route(self, path: str, methods: List[str], **kwargs: Any) -> Callable:
+        """
+        Decorator for custom methods.
+
+        Example:
+            @app.route("/items", methods=["GET", "POST"])
+            async def items():
+                return {"items": []}
+        """
+        return self._router.route(path, methods, **kwargs)
+
+    def _build_starlette_app(self) -> Starlette:
+        """Build the Starlette application from routes and middleware."""
+        # Convert Vega routes to Starlette routes
+        starlette_routes = [
+            route.to_starlette_route() for route in self._router.get_routes()
+        ]
+
+        # Create Starlette app
+        app = Starlette(
+            debug=self.debug,
+            routes=starlette_routes,
+            middleware=self._middleware,
+            on_startup=self._on_startup,
+            on_shutdown=self._on_shutdown,
+        )
+
+        return app
+
+    def _get_app(self) -> Starlette:
+        """Get or create the Starlette app."""
+        if self._starlette_app is None:
+            self._starlette_app = self._build_starlette_app()
+        return self._starlette_app
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        """
+        ASGI application callable.
+
+        This makes VegaApp a valid ASGI application.
+        """
+        app = self._get_app()
+        await app(scope, receive, send)
+
+
+__all__ = ["VegaApp"]

vega/web/builtin_middlewares.py

@@ -0,0 +1,288 @@
+"""Built-in route middleware implementations for Vega Web Framework"""
+
+import time
+import logging
+from typing import Optional
+
+from .route_middleware import RouteMiddleware, MiddlewarePhase
+from .request import Request
+from .response import Response, JSONResponse
+from .exceptions import HTTPException, status
+
+
+class AuthMiddleware(RouteMiddleware):
+    """
+    Authentication middleware - validates Authorization header.
+
+    Executes BEFORE the handler.
+
+    Args:
+        header_name: Name of the header to check (default: "Authorization")
+        scheme: Expected auth scheme (default: "Bearer")
+
+    Example:
+        @router.get("/protected")
+        @middleware(AuthMiddleware())
+        async def protected_route():
+            return {"data": "secret"}
+    """
+
+    def __init__(self, header_name: str = "Authorization", scheme: str = "Bearer"):
+        super().__init__(phase=MiddlewarePhase.BEFORE)
+        self.header_name = header_name
+        self.scheme = scheme
+
+    async def before(self, request: Request) -> Optional[Response]:
+        """Check for valid authentication token"""
+        auth_header = request.headers.get(self.header_name.lower())
+
+        if not auth_header:
+            return JSONResponse(
+                content={"detail": "Missing authentication credentials"},
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                headers={"WWW-Authenticate": f"{self.scheme}"},
+            )
+
+        # Parse scheme and token
+        parts = auth_header.split()
+        if len(parts) != 2 or parts[0].lower() != self.scheme.lower():
+            return JSONResponse(
+                content={"detail": f"Invalid authentication scheme. Expected: {self.scheme}"},
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                headers={"WWW-Authenticate": f"{self.scheme}"},
+            )
+
+        token = parts[1]
+
+        # TODO: Validate token here (this is a simple example)
+        if token == "invalid":
+            return JSONResponse(
+                content={"detail": "Invalid or expired token"},
+                status_code=status.HTTP_401_UNAUTHORIZED,
+            )
+
+        # Store user info in request state for handler to use
+        request.state.user_id = "user_from_token"
+        request.state.token = token
+
+        return None  # Continue to handler
+
+
+class TimingMiddleware(RouteMiddleware):
+    """
+    Request timing middleware - measures execution time.
+
+    Executes BOTH before and after the handler.
+
+    Example:
+        @router.get("/slow-operation")
+        @middleware(TimingMiddleware())
+        async def slow_operation():
+            await asyncio.sleep(1)
+            return {"status": "done"}
+    """
+
+    def __init__(self):
+        super().__init__(phase=MiddlewarePhase.BOTH)
+        self.logger = logging.getLogger("vega.web.timing")
+
+    async def before(self, request: Request) -> Optional[Response]:
+        """Record start time"""
+        request.state.start_time = time.time()
+        return None
+
+    async def after(self, request: Request, response: Response) -> Response:
+        """Calculate and log execution time"""
+        if hasattr(request.state, "start_time"):
+            duration = time.time() - request.state.start_time
+            self.logger.info(
+                f"{request.method} {request.url.path} completed in {duration:.3f}s"
+            )
+
+            # Add timing header to response
+            if hasattr(response, "headers"):
+                response.headers["X-Process-Time"] = f"{duration:.3f}"
+
+        return response
+
+
+class CacheControlMiddleware(RouteMiddleware):
+    """
+    Cache control middleware - adds cache headers to response.
+
+    Executes AFTER the handler.
+
+    Args:
+        max_age: Cache max age in seconds
+        public: Whether cache is public (default: True)
+
+    Example:
+        @router.get("/static-data")
+        @middleware(CacheControlMiddleware(max_age=3600))
+        async def get_static_data():
+            return {"data": "rarely changes"}
+    """
+
+    def __init__(self, max_age: int = 300, public: bool = True):
+        super().__init__(phase=MiddlewarePhase.AFTER)
+        self.max_age = max_age
+        self.public = public
+
+    async def after(self, request: Request, response: Response) -> Response:
+        """Add cache control headers"""
+        cache_type = "public" if self.public else "private"
+        cache_value = f"{cache_type}, max-age={self.max_age}"
+
+        if hasattr(response, "headers"):
+            response.headers["Cache-Control"] = cache_value
+
+        return response
+
+
+class CORSMiddleware(RouteMiddleware):
+    """
+    CORS middleware for specific routes.
+
+    Executes AFTER the handler to add CORS headers.
+
+    Args:
+        allow_origins: List of allowed origins or "*"
+        allow_methods: List of allowed methods
+        allow_headers: List of allowed headers
+
+    Example:
+        @router.get("/public-api/data")
+        @middleware(CORSMiddleware(allow_origins=["*"]))
+        async def public_data():
+            return {"data": "public"}
+    """
+
+    def __init__(
+        self,
+        allow_origins: list = None,
+        allow_methods: list = None,
+        allow_headers: list = None,
+    ):
+        super().__init__(phase=MiddlewarePhase.AFTER)
+        self.allow_origins = allow_origins or ["*"]
+        self.allow_methods = allow_methods or ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
+        self.allow_headers = allow_headers or ["*"]
+
+    async def after(self, request: Request, response: Response) -> Response:
+        """Add CORS headers to response"""
+        if hasattr(response, "headers"):
+            origin = request.headers.get("origin", "*")
+
+            if "*" in self.allow_origins or origin in self.allow_origins:
+                response.headers["Access-Control-Allow-Origin"] = origin
+                response.headers["Access-Control-Allow-Methods"] = ", ".join(
+                    self.allow_methods
+                )
+                response.headers["Access-Control-Allow-Headers"] = ", ".join(
+                    self.allow_headers
+                )
+
+        return response
+
+
+class RateLimitMiddleware(RouteMiddleware):
+    """
+    Simple rate limiting middleware.
+
+    Executes BEFORE the handler.
+
+    Args:
+        max_requests: Maximum requests allowed
+        window_seconds: Time window in seconds
+
+    Example:
+        @router.post("/expensive-operation")
+        @middleware(RateLimitMiddleware(max_requests=10, window_seconds=60))
+        async def expensive_op():
+            return {"status": "processing"}
+    """
+
+    def __init__(self, max_requests: int = 100, window_seconds: int = 60):
+        super().__init__(phase=MiddlewarePhase.BEFORE)
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests = {}  # IP -> [timestamps]
+
+    async def before(self, request: Request) -> Optional[Response]:
+        """Check rate limit"""
+        from datetime import datetime, timedelta
+
+        client_ip = request.client.host if request.client else "unknown"
+        now = datetime.now()
+
+        # Clean old entries
+        if client_ip in self.requests:
+            cutoff = now - timedelta(seconds=self.window_seconds)
+            self.requests[client_ip] = [
+                ts for ts in self.requests[client_ip] if ts > cutoff
+            ]
+
+        # Check limit
+        if client_ip in self.requests:
+            if len(self.requests[client_ip]) >= self.max_requests:
+                return JSONResponse(
+                    content={
+                        "detail": f"Rate limit exceeded. Max {self.max_requests} requests per {self.window_seconds}s"
+                    },
+                    status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                    headers={
+                        "Retry-After": str(self.window_seconds),
+                        "X-RateLimit-Limit": str(self.max_requests),
+                        "X-RateLimit-Remaining": "0",
+                    },
+                )
+
+        # Record request
+        if client_ip not in self.requests:
+            self.requests[client_ip] = []
+        self.requests[client_ip].append(now)
+
+        return None
+
+
+class LoggingMiddleware(RouteMiddleware):
+    """
+    Request/Response logging middleware.
+
+    Executes BOTH before and after.
+
+    Example:
+        @router.post("/important-action")
+        @middleware(LoggingMiddleware())
+        async def important_action():
+            return {"status": "done"}
+    """
+
+    def __init__(self, logger_name: str = "vega.web.routes"):
+        super().__init__(phase=MiddlewarePhase.BOTH)
+        self.logger = logging.getLogger(logger_name)
+
+    async def before(self, request: Request) -> Optional[Response]:
+        """Log incoming request"""
+        self.logger.info(
+            f"→ {request.method} {request.url.path} "
+            f"from {request.client.host if request.client else 'unknown'}"
+        )
+        return None
+
+    async def after(self, request: Request, response: Response) -> Response:
+        """Log response"""
+        self.logger.info(
+            f"← {request.method} {request.url.path} [{response.status_code}]"
+        )
+        return response
+
+
+__all__ = [
+    "AuthMiddleware",
+    "TimingMiddleware",
+    "CacheControlMiddleware",
+    "CORSMiddleware",
+    "RateLimitMiddleware",
+    "LoggingMiddleware",
+]