orbit-web-framework 1.0.2__py3-none-any.whl

orbit/__init__.py

@@ -0,0 +1,16 @@
+"""
+Orbit - Lightweight Advanced Python Web Framework
+Pure Standard Library Implementation
+
+A production-minded, educational-grade web framework built entirely
+with Python's standard library. No external dependencies.
+"""
+
+__version__ = "1.0.2"
+__author__ = "Orbit Framework Team"
+
+from .core.application import Orbit
+from .core.response import Response
+from .core.request import Request
+
+__all__ = ['Orbit', 'Response', 'Request']

orbit/core/__init__.py

@@ -0,0 +1 @@
+# Core module

orbit/core/application.py

@@ -0,0 +1,289 @@
+"""
+Orbit Application
+Main framework class orchestrating all components
+"""
+
+import logging
+import signal
+import sys
+from typing import Callable, List, Optional, Dict, Any
+from .router import Router, RouterGroup
+from .middleware import MiddlewareChain, Middleware
+from .request import Request
+from .response import Response
+from ..http.server import HTTPServer
+from ..static.handler import StaticFileHandler
+from ..template.engine import TemplateEngine
+
+
+class Orbit:
+    """
+    Main Orbit framework application
+    """
+    
+    def __init__(self, debug: bool = False):
+        """
+        Initialize Orbit application
+        
+        Args:
+            debug: Enable debug mode
+        """
+        self.debug = debug
+        self.router = Router()
+        self.middleware_chain = MiddlewareChain()
+        self.server: Optional[HTTPServer] = None
+        
+        # Static file handler (optional)
+        self.static_handler: Optional[StaticFileHandler] = None
+        
+        # Template engine (optional)
+        self.template_engine: Optional[TemplateEngine] = None
+        
+        # Error handlers
+        self.error_handlers: Dict[int, Callable] = {}
+        
+        # Shutdown state
+        self._is_shutting_down = False
+        
+        # Setup logging
+        self._setup_logging()
+        
+        # Graceful shutdown
+        self._setup_signal_handlers()
+    
+    def _setup_logging(self):
+        """Setup logging configuration"""
+        level = logging.DEBUG if self.debug else logging.INFO
+        
+        logging.basicConfig(
+            level=level,
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        
+        self.logger = logging.getLogger('orbit')
+    
+    def _setup_signal_handlers(self):
+        """Setup signal handlers for graceful shutdown"""
+        def signal_handler(sig, frame):
+            # Prevent multiple shutdown calls
+            if self._is_shutting_down:
+                return
+            
+            self._is_shutting_down = True
+            self.logger.info("Shutdown signal received")
+            
+            if self.server:
+                self.server.stop()
+            
+            sys.exit(0)
+        
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)
+    
+    def route(self, path: str, methods: List[str] = None, 
+              handler: Callable = None, name: str = None):
+        """
+        Register a route
+        
+        Args:
+            path: URL path pattern
+            methods: List of HTTP methods
+            handler: Handler function
+            name: Route name
+            
+        Returns:
+            Decorator if handler is None, else None
+        """
+        if methods is None:
+            methods = ['GET']
+        
+        if handler is None:
+            # Return decorator
+            def decorator(func: Callable) -> Callable:
+                self.router.add_route(path, methods, func, name)
+                return func
+            return decorator
+        else:
+            # Direct registration
+            self.router.add_route(path, methods, handler, name)
+    
+    def group(self, prefix: str) -> RouterGroup:
+        """
+        Create route group with prefix
+        
+        Args:
+            prefix: URL prefix for group
+            
+        Returns:
+            RouterGroup instance
+        """
+        return RouterGroup(self.router, prefix)
+    
+    def middleware(self, middleware: Middleware):
+        """
+        Add middleware to application
+        
+        Args:
+            middleware: Middleware instance
+        """
+        self.middleware_chain.add(middleware)
+    
+    def static(self, static_dir: str, url_prefix: str = '/static',
+               **kwargs):
+        """
+        Enable static file serving
+        
+        Args:
+            static_dir: Directory containing static files
+            url_prefix: URL prefix for static files
+            **kwargs: Additional StaticFileHandler options
+        """
+        self.static_handler = StaticFileHandler(static_dir, url_prefix, **kwargs)
+        self.logger.info(f"Static files enabled: {static_dir} -> {url_prefix}")
+    
+    def templates(self, template_dir: str):
+        """
+        Enable template engine
+        
+        Args:
+            template_dir: Directory containing templates
+        """
+        self.template_engine = TemplateEngine(template_dir)
+        self.logger.info(f"Templates enabled: {template_dir}")
+    
+    def render(self, template_name: str, context: Dict[str, Any] = None) -> Response:
+        """
+        Render template
+        
+        Args:
+            template_name: Template filename
+            context: Template context
+            
+        Returns:
+            Response with rendered HTML
+        """
+        if not self.template_engine:
+            raise RuntimeError("Template engine not configured")
+        
+        html = self.template_engine.render(template_name, context)
+        return Response.html(html)
+    
+    def error_handler(self, status_code: int):
+        """
+        Register error handler decorator
+        
+        Args:
+            status_code: HTTP status code
+            
+        Returns:
+            Decorator function
+        """
+        def decorator(func: Callable) -> Callable:
+            self.error_handlers[status_code] = func
+            return func
+        return decorator
+    
+    def handle_request(self, request: Request) -> Response:
+        """
+        Main request handler
+        
+        Args:
+            request: Request object
+            
+        Returns:
+            Response object
+        """
+        try:
+            # Pre-request middleware
+            early_response = self.middleware_chain.process_request(request)
+            if early_response:
+                return early_response
+            
+            # Check static files
+            if self.static_handler and self.static_handler.is_static_request(request.path):
+                response = self.static_handler.serve(request.path)
+            else:
+                # Route matching
+                match = self.router.match(request.path, request.method)
+                
+                if match:
+                    handler, path_params = match
+                    request.path_params = path_params
+                    
+                    # Call handler
+                    response = handler(request)
+                    
+                    # Ensure response is Response object
+                    if not isinstance(response, Response):
+                        if isinstance(response, dict):
+                            response = Response.json(response)
+                        elif isinstance(response, str):
+                            response = Response.html(response)
+                        else:
+                            response = Response(str(response))
+                else:
+                    # 404 Not Found
+                    if 404 in self.error_handlers:
+                        response = self.error_handlers[404](request)
+                    else:
+                        response = Response.error(404, "Not Found")
+            
+            # Post-response middleware
+            response = self.middleware_chain.process_response(request, response)
+            
+            return response
+            
+        except Exception as e:
+            self.logger.error(f"Request handling error: {e}", exc_info=True)
+            
+            # Error handler
+            if 500 in self.error_handlers:
+                return self.error_handlers[500](request, e)
+            
+            # Default error response
+            if self.debug:
+                import traceback
+                error_detail = traceback.format_exc()
+                return Response.error(500, f"Internal Server Error: {error_detail}")
+            else:
+                return Response.error(500, "Internal Server Error")
+    
+    def run(self, host: str = '0.0.0.0', port: int = 8080,
+            use_threading: bool = True, **kwargs):
+        """
+        Run the application server
+        
+        Args:
+            host: Host address
+            port: Port number
+            use_threading: Use threading for connections
+            **kwargs: Additional server options
+        """
+        self.server = HTTPServer(
+            host=host,
+            port=port,
+            request_handler=self.handle_request,
+            use_threading=use_threading,
+            **kwargs
+        )
+        
+        self.logger.info(f"Starting Orbit application in {'DEBUG' if self.debug else 'PRODUCTION'} mode")
+        
+        try:
+            self.server.start()
+        except KeyboardInterrupt:
+            self.logger.info("Shutting down...")
+        finally:
+            if self.server:
+                self.server.stop()
+    
+    def test_client(self):
+        """
+        Create test client for testing
+        
+        Returns:
+            TestClient instance
+        """
+        from ..testing.client import TestClient
+        return TestClient(self)

orbit/core/middleware.py

@@ -0,0 +1,236 @@
+"""
+Middleware System
+Chain-based middleware for request/response processing
+"""
+
+from typing import Callable, List, Optional
+from .request import Request
+from .response import Response
+
+
+class Middleware:
+    """
+    Base middleware class
+    """
+    
+    def process_request(self, request: Request) -> Optional[Response]:
+        """
+        Process request before handler
+        
+        Args:
+            request: Request object
+            
+        Returns:
+            Response to short-circuit, or None to continue
+        """
+        return None
+    
+    def process_response(self, request: Request, response: Response) -> Response:
+        """
+        Process response after handler
+        
+        Args:
+            request: Request object
+            response: Response object
+            
+        Returns:
+            Modified response
+        """
+        return response
+
+
+class MiddlewareChain:
+    """
+    Middleware chain manager
+    """
+    
+    def __init__(self):
+        self.middlewares: List[Middleware] = []
+        
+    def add(self, middleware: Middleware):
+        """
+        Add middleware to chain
+        
+        Args:
+            middleware: Middleware instance
+        """
+        self.middlewares.append(middleware)
+        
+    def process_request(self, request: Request) -> Optional[Response]:
+        """
+        Run request through middleware chain
+        
+        Args:
+            request: Request object
+            
+        Returns:
+            Response if short-circuited, None otherwise
+        """
+        for middleware in self.middlewares:
+            response = middleware.process_request(request)
+            if response is not None:
+                return response
+        return None
+    
+    def process_response(self, request: Request, response: Response) -> Response:
+        """
+        Run response through middleware chain (in reverse)
+        
+        Args:
+            request: Request object
+            response: Response object
+            
+        Returns:
+            Processed response
+        """
+        for middleware in reversed(self.middlewares):
+            response = middleware.process_response(request, response)
+        return response
+
+
+# Built-in Middlewares
+
+class SecurityHeadersMiddleware(Middleware):
+    """Add security headers to responses"""
+    
+    def process_response(self, request: Request, response: Response) -> Response:
+        """Add security headers"""
+        response.set_header('X-Content-Type-Options', 'nosniff')
+        response.set_header('X-Frame-Options', 'SAMEORIGIN')
+        response.set_header('X-XSS-Protection', '1; mode=block')
+        return response
+
+
+class CORSMiddleware(Middleware):
+    """Handle CORS headers"""
+    
+    def __init__(self, allow_origins: List[str] = None,
+                 allow_methods: List[str] = None,
+                 allow_headers: List[str] = None):
+        self.allow_origins = allow_origins or ['*']
+        self.allow_methods = allow_methods or ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
+        self.allow_headers = allow_headers or ['Content-Type', 'Authorization']
+        
+    def process_request(self, request: Request) -> Optional[Response]:
+        """Handle preflight requests"""
+        if request.method == 'OPTIONS':
+            response = Response('', status=204)
+            self._add_cors_headers(response)
+            return response
+        return None
+    
+    def process_response(self, request: Request, response: Response) -> Response:
+        """Add CORS headers to response"""
+        self._add_cors_headers(response)
+        return response
+    
+    def _add_cors_headers(self, response: Response):
+        """Add CORS headers"""
+        response.set_header('Access-Control-Allow-Origin', ', '.join(self.allow_origins))
+        response.set_header('Access-Control-Allow-Methods', ', '.join(self.allow_methods))
+        response.set_header('Access-Control-Allow-Headers', ', '.join(self.allow_headers))
+
+
+class RateLimitMiddleware(Middleware):
+    """
+    IP-based rate limiting
+    """
+    
+    def __init__(self, requests_per_minute: int = 60):
+        self.requests_per_minute = requests_per_minute
+        self.request_counts: dict = {}  # ip -> [(timestamp, count)]
+        
+        # Security logger
+        import logging
+        self.security_logger = logging.getLogger('orbit.security')
+        
+    def process_request(self, request: Request) -> Optional[Response]:
+        """Check rate limit"""
+        import time
+        
+        client_ip = request.client_ip
+        if not client_ip:
+            return None
+            
+        current_time = time.time()
+        
+        # Clean old entries
+        if client_ip in self.request_counts:
+            self.request_counts[client_ip] = [
+                (ts, count) for ts, count in self.request_counts[client_ip]
+                if current_time - ts < 60
+            ]
+        else:
+            self.request_counts[client_ip] = []
+        
+        # Count requests in last minute
+        total_requests = sum(count for ts, count in self.request_counts[client_ip])
+        
+        if total_requests >= self.requests_per_minute:
+            # Log rate limit hit
+            self.security_logger.warning(
+                f"{client_ip} | {request.method} {request.path} | RATE_LIMIT | "
+                f"{total_requests}/{self.requests_per_minute} req/min"
+            )
+            return Response.error(429, 'Rate limit exceeded')
+        
+        # Add current request
+        self.request_counts[client_ip].append((current_time, 1))
+        
+        return None
+
+
+class LoggingMiddleware(Middleware):
+    """Log requests and responses"""
+    
+    def __init__(self, logger):
+        self.logger = logger
+        
+    def process_request(self, request: Request) -> Optional[Response]:
+        """Log incoming request"""
+        self.logger.info(f"{request.method} {request.path} from {request.client_ip}")
+        return None
+    
+    def process_response(self, request: Request, response: Response) -> Response:
+        """Log response status"""
+        self.logger.info(f"{request.method} {request.path} -> {response.status}")
+        return response
+
+
+class CSRFProtectionMiddleware(Middleware):
+    """
+    Basic CSRF token protection
+    """
+    
+    def __init__(self):
+        import hashlib
+        import secrets
+        self.tokens: dict = {}  # session_id -> token
+        self.secret = secrets.token_hex(32)
+        
+    def generate_token(self, session_id: str) -> str:
+        """Generate CSRF token for session"""
+        import hashlib
+        import secrets
+        
+        token = secrets.token_hex(32)
+        self.tokens[session_id] = token
+        return token
+    
+    def process_request(self, request: Request) -> Optional[Response]:
+        """Validate CSRF token for state-changing requests"""
+        if request.method in ['POST', 'PUT', 'DELETE', 'PATCH']:
+            # Get session ID from cookie (simplified)
+            session_id = request.get_header('cookie', '')
+            
+            # Get token from header or form
+            token = request.get_header('x-csrf-token')
+            if not token and request.is_form():
+                token = request.get_form('csrf_token')
+            
+            # Validate token
+            if session_id in self.tokens:
+                if token != self.tokens[session_id]:
+                    return Response.error(403, 'CSRF token validation failed')
+        
+        return None

orbit/core/request.py

@@ -0,0 +1,126 @@
+"""
+Request Object
+Represents an HTTP request with parsed data
+"""
+
+from typing import Dict, Optional, Any
+import json
+
+
+class Request:
+    """
+    HTTP Request object containing all request information
+    """
+    
+    def __init__(self, method: str, path: str, version: str,
+                 headers: Dict[str, str], query_params: Dict[str, list],
+                 body: bytes, parsed_body: Optional[dict] = None,
+                 client_address: tuple = None):
+        """
+        Initialize Request object
+        
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: Request path
+            version: HTTP version
+            headers: Request headers
+            query_params: Query string parameters
+            body: Raw request body
+            parsed_body: Parsed body (JSON or form data)
+            client_address: Client IP and port tuple
+        """
+        self.method = method
+        self.path = path
+        self.version = version
+        self.headers = headers
+        self.query_params = query_params
+        self.body = body
+        self.parsed_body = parsed_body
+        self.client_address = client_address
+        
+        # Path parameters (filled by router)
+        self.path_params: Dict[str, str] = {}
+        
+        # Additional context storage
+        self.context: Dict[str, Any] = {}
+        
+    @property
+    def client_ip(self) -> Optional[str]:
+        """Get client IP address"""
+        if self.client_address:
+            return self.client_address[0]
+        return None
+    
+    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Get header value (case-insensitive)
+        
+        Args:
+            name: Header name
+            default: Default value if header not found
+            
+        Returns:
+            Header value or default
+        """
+        return self.headers.get(name.lower(), default)
+    
+    def get_query(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Get query parameter value
+        
+        Args:
+            name: Parameter name
+            default: Default value if not found
+            
+        Returns:
+            Parameter value or default
+        """
+        values = self.query_params.get(name, [])
+        return values[0] if values else default
+    
+    def get_json(self) -> Optional[dict]:
+        """
+        Get parsed JSON body
+        
+        Returns:
+            Parsed JSON data or None
+        """
+        if self.parsed_body and isinstance(self.parsed_body, dict):
+            return self.parsed_body
+        
+        # Try to parse if not already parsed
+        if self.get_header('content-type', '').startswith('application/json'):
+            try:
+                return json.loads(self.body.decode('utf-8'))
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                return None
+        
+        return None
+    
+    def get_form(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Get form data value
+        
+        Args:
+            name: Form field name
+            default: Default value if not found
+            
+        Returns:
+            Form field value or default
+        """
+        if self.parsed_body and isinstance(self.parsed_body, dict):
+            return self.parsed_body.get(name, default)
+        return default
+    
+    def is_json(self) -> bool:
+        """Check if request has JSON content type"""
+        content_type = self.get_header('content-type', '')
+        return 'application/json' in content_type
+    
+    def is_form(self) -> bool:
+        """Check if request has form content type"""
+        content_type = self.get_header('content-type', '')
+        return 'application/x-www-form-urlencoded' in content_type
+    
+    def __repr__(self) -> str:
+        return f"<Request {self.method} {self.path}>"