django-bolt 0.1.0__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

django_bolt/params.py

@@ -0,0 +1,337 @@
+"""
+Parameter markers and validation constraints for Django-Bolt.
+
+Provides explicit parameter source annotations and validation metadata.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Pattern
+
+__all__ = [
+    "Param",
+    "Query",
+    "Path",
+    "Body",
+    "Header",
+    "Cookie",
+    "Form",
+    "File",
+    "Depends",
+]
+
+
+@dataclass(frozen=True)
+class Param:
+    """
+    Base parameter marker with validation constraints.
+
+    Used internally by Query, Path, Body, etc. markers.
+    """
+
+    source: str
+    """Parameter source: 'query', 'path', 'body', 'header', 'cookie', 'form', 'file'"""
+
+    alias: Optional[str] = None
+    """Alternative name for the parameter in the request"""
+
+    embed: Optional[bool] = None
+    """Whether to embed body parameter in wrapper object"""
+
+    # Numeric constraints
+    gt: Optional[float] = None
+    """Greater than (exclusive minimum)"""
+
+    ge: Optional[float] = None
+    """Greater than or equal (inclusive minimum)"""
+
+    lt: Optional[float] = None
+    """Less than (exclusive maximum)"""
+
+    le: Optional[float] = None
+    """Less than or equal (inclusive maximum)"""
+
+    multiple_of: Optional[float] = None
+    """Value must be multiple of this number"""
+
+    # String/collection constraints
+    min_length: Optional[int] = None
+    """Minimum length for strings or collections"""
+
+    max_length: Optional[int] = None
+    """Maximum length for strings or collections"""
+
+    pattern: Optional[str] = None
+    """Regex pattern for string validation"""
+
+    # Metadata
+    description: Optional[str] = None
+    """Parameter description for documentation"""
+
+    example: Any = None
+    """Example value for documentation"""
+
+    deprecated: bool = False
+    """Mark parameter as deprecated"""
+
+
+def Query(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    gt: Optional[float] = None,
+    ge: Optional[float] = None,
+    lt: Optional[float] = None,
+    le: Optional[float] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    pattern: Optional[str] = None,
+    description: Optional[str] = None,
+    example: Any = None,
+    deprecated: bool = False,
+) -> Any:
+    """
+    Mark parameter as query parameter.
+
+    Args:
+        default: Default value (... for required)
+        alias: Alternative parameter name in URL
+        gt: Value must be greater than this
+        ge: Value must be greater than or equal to this
+        lt: Value must be less than this
+        le: Value must be less than or equal to this
+        min_length: Minimum string/collection length
+        max_length: Maximum string/collection length
+        pattern: Regex pattern to match
+        description: Parameter description
+        example: Example value
+        deprecated: Mark as deprecated
+
+    Returns:
+        Param marker instance
+    """
+    return Param(
+        source="query",
+        alias=alias,
+        gt=gt,
+        ge=ge,
+        lt=lt,
+        le=le,
+        min_length=min_length,
+        max_length=max_length,
+        pattern=pattern,
+        description=description,
+        example=example,
+        deprecated=deprecated,
+    )
+
+
+def Path(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    gt: Optional[float] = None,
+    ge: Optional[float] = None,
+    lt: Optional[float] = None,
+    le: Optional[float] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    pattern: Optional[str] = None,
+    description: Optional[str] = None,
+    example: Any = None,
+    deprecated: bool = False,
+) -> Any:
+    """
+    Mark parameter as path parameter.
+
+    Args:
+        default: Must be ... (path params are always required)
+        alias: Alternative parameter name
+        gt: Value must be greater than this
+        ge: Value must be greater than or equal to this
+        lt: Value must be less than this
+        le: Value must be less than or equal to this
+        min_length: Minimum string length
+        max_length: Maximum string length
+        pattern: Regex pattern to match
+        description: Parameter description
+        example: Example value
+        deprecated: Mark as deprecated
+
+    Returns:
+        Param marker instance
+    """
+    if default is not ...:
+        raise ValueError("Path parameters cannot have default values")
+
+    return Param(
+        source="path",
+        alias=alias,
+        gt=gt,
+        ge=ge,
+        lt=lt,
+        le=le,
+        min_length=min_length,
+        max_length=max_length,
+        pattern=pattern,
+        description=description,
+        example=example,
+        deprecated=deprecated,
+    )
+
+
+def Body(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    embed: bool = False,
+    description: Optional[str] = None,
+    example: Any = None,
+) -> Any:
+    """
+    Mark parameter as request body.
+
+    Args:
+        default: Default value (... for required)
+        alias: Alternative parameter name
+        embed: Whether to wrap in {<alias>: <value>}
+        description: Parameter description
+        example: Example value
+
+    Returns:
+        Param marker instance
+    """
+    return Param(
+        source="body",
+        alias=alias,
+        embed=embed,
+        description=description,
+        example=example,
+    )
+
+
+def Header(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    description: Optional[str] = None,
+    example: Any = None,
+    deprecated: bool = False,
+) -> Any:
+    """
+    Mark parameter as HTTP header.
+
+    Args:
+        default: Default value (... for required)
+        alias: Alternative header name
+        description: Parameter description
+        example: Example value
+        deprecated: Mark as deprecated
+
+    Returns:
+        Param marker instance
+    """
+    return Param(
+        source="header",
+        alias=alias,
+        description=description,
+        example=example,
+        deprecated=deprecated,
+    )
+
+
+def Cookie(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    description: Optional[str] = None,
+    example: Any = None,
+    deprecated: bool = False,
+) -> Any:
+    """
+    Mark parameter as cookie value.
+
+    Args:
+        default: Default value (... for required)
+        alias: Alternative cookie name
+        description: Parameter description
+        example: Example value
+        deprecated: Mark as deprecated
+
+    Returns:
+        Param marker instance
+    """
+    return Param(
+        source="cookie",
+        alias=alias,
+        description=description,
+        example=example,
+        deprecated=deprecated,
+    )
+
+
+def Form(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    description: Optional[str] = None,
+    example: Any = None,
+) -> Any:
+    """
+    Mark parameter as form data field.
+
+    Args:
+        default: Default value (... for required)
+        alias: Alternative form field name
+        description: Parameter description
+        example: Example value
+
+    Returns:
+        Param marker instance
+    """
+    return Param(
+        source="form",
+        alias=alias,
+        description=description,
+        example=example,
+    )
+
+
+def File(
+    default: Any = ...,
+    *,
+    alias: Optional[str] = None,
+    description: Optional[str] = None,
+) -> Any:
+    """
+    Mark parameter as file upload.
+
+    Args:
+        default: Default value (... for required)
+        alias: Alternative form field name
+        description: Parameter description
+
+    Returns:
+        Param marker instance
+    """
+    return Param(
+        source="file",
+        alias=alias,
+        description=description,
+    )
+
+
+@dataclass(frozen=True)
+class Depends:
+    """
+    Dependency injection marker.
+
+    Marks a parameter as a dependency that will be resolved
+    by calling the specified function.
+    """
+
+    dependency: Optional[Callable[..., Any]] = None
+    """Function to call for dependency resolution"""
+
+    use_cache: bool = True
+    """Whether to cache the dependency result per request"""

django_bolt/request_parsing.py

@@ -0,0 +1,128 @@
+"""Request parsing utilities for form and multipart data."""
+from typing import Any, Dict, Tuple
+from io import BytesIO
+import multipart
+
+# Cache for max upload size (read once from Django settings)
+_MAX_UPLOAD_SIZE = None
+
+
+def get_max_upload_size() -> int:
+    """Get max upload size from Django settings (cached after first call)."""
+    global _MAX_UPLOAD_SIZE
+    if _MAX_UPLOAD_SIZE is None:
+        try:
+            from django.conf import settings
+            _MAX_UPLOAD_SIZE = getattr(settings, 'BOLT_MAX_UPLOAD_SIZE', 10 * 1024 * 1024)  # 10MB default
+        except ImportError:
+            _MAX_UPLOAD_SIZE = 10 * 1024 * 1024
+    return _MAX_UPLOAD_SIZE
+
+
+def parse_form_data(request: Dict[str, Any], headers_map: Dict[str, str]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Parse form and multipart data from request using python "multipart" library."""
+    content_type = headers_map.get("content-type", "")
+
+    # Early return if not form data (optimization for JSON/empty requests)
+    if not content_type.startswith(("application/x-www-form-urlencoded", "multipart/form-data")):
+        return {}, {}
+
+    form_map: Dict[str, Any] = {}
+    files_map: Dict[str, Any] = {}
+
+    if content_type.startswith("application/x-www-form-urlencoded"):
+        from urllib.parse import parse_qs
+        body_bytes: bytes = request["body"]
+        form_data = parse_qs(body_bytes.decode("utf-8"))
+        # parse_qs returns lists, but for single values we want the value directly
+        form_map = {k: v[0] if len(v) == 1 else v for k, v in form_data.items()}
+    elif content_type.startswith("multipart/form-data"):
+        form_map, files_map = parse_multipart_data(request, content_type)
+
+    return form_map, files_map
+
+
+def parse_multipart_data(request: Dict[str, Any], content_type: str) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """
+    Parse multipart form data using python "multipart" library.
+
+    SECURITY: Uses battle-tested multipart library with proper boundary validation,
+    size limits, and header parsing.
+    """
+
+    form_map: Dict[str, Any] = {}
+    files_map: Dict[str, Any] = {}
+
+    # Parse content-type header to get boundary
+    content_type_parsed, content_type_options = multipart.parse_options_header(content_type)
+
+    if content_type_parsed != 'multipart/form-data':
+        return form_map, files_map
+
+    boundary = content_type_options.get('boundary')
+    if not boundary:
+        return form_map, files_map
+
+    # SECURITY: Validate boundary (multipart does this, but explicit check)
+    if not boundary or len(boundary) > 200:  # RFC 2046 suggests max 70, we allow 200
+        return form_map, files_map
+
+    # Get max upload size (cached from Django settings)
+    max_size = get_max_upload_size()
+
+    body_bytes: bytes = request["body"]
+
+    # SECURITY: Check body size before parsing
+    if len(body_bytes) > max_size:
+        raise ValueError(f"Upload size {len(body_bytes)} exceeds maximum {max_size} bytes")
+
+    # Create a file-like object from bytes
+    body_file = BytesIO(body_bytes)
+
+    # Parse using multipart library
+    try:
+        parser = multipart.MultipartParser(
+            body_file,
+            boundary=boundary.encode() if isinstance(boundary, str) else boundary,
+            content_length=len(body_bytes),
+            memory_limit=max_size,
+            disk_limit=0,  # Don't allow disk spooling for security
+            part_limit=100  # Limit number of parts
+        )
+
+        # Iterate through parts
+        for part in parser:
+            name = part.name
+            if not name:
+                continue
+
+            # Check if it's a file or form field
+            if part.filename:
+                # It's a file upload
+                content = part.file.read()
+                file_info = {
+                    "filename": part.filename,
+                    "content": content,
+                    "content_type": part.content_type,
+                    "size": len(content)
+                }
+
+                if name in files_map:
+                    if isinstance(files_map[name], list):
+                        files_map[name].append(file_info)
+                    else:
+                        files_map[name] = [files_map[name], file_info]
+                else:
+                    files_map[name] = file_info
+            else:
+                # It's a form field
+                form_map[name] = part.value
+
+    except Exception as e:
+        # Return empty maps on parse error (don't expose internal errors)
+        import logging
+        import traceback
+        logging.warning(f"Multipart parsing failed: {e}\n{traceback.format_exc()}")
+        return {}, {}
+
+    return form_map, files_map

django_bolt/responses.py

@@ -0,0 +1,214 @@
+import msgspec
+from typing import Any, Dict, Optional, List
+from pathlib import Path
+
+# Cache for BOLT_ALLOWED_FILE_PATHS - loaded once at server startup
+_ALLOWED_FILE_PATHS_CACHE: Optional[List[Path]] = None
+_ALLOWED_FILE_PATHS_INITIALIZED = False
+
+
+def initialize_file_response_settings():
+    """
+    Initialize FileResponse settings cache at server startup.
+    This should be called once when the server starts to cache BOLT_ALLOWED_FILE_PATHS.
+    """
+    global _ALLOWED_FILE_PATHS_CACHE, _ALLOWED_FILE_PATHS_INITIALIZED
+
+    if _ALLOWED_FILE_PATHS_INITIALIZED:
+        return
+
+    try:
+        from django.conf import settings
+        if hasattr(settings, 'BOLT_ALLOWED_FILE_PATHS'):
+            allowed_paths = settings.BOLT_ALLOWED_FILE_PATHS
+            if allowed_paths:
+                # Resolve all paths once at startup
+                _ALLOWED_FILE_PATHS_CACHE = [Path(p).resolve() for p in allowed_paths]
+            else:
+                _ALLOWED_FILE_PATHS_CACHE = None
+        else:
+            _ALLOWED_FILE_PATHS_CACHE = None
+    except ImportError:
+        # Django not configured, allow any path (development mode)
+        _ALLOWED_FILE_PATHS_CACHE = None
+
+    _ALLOWED_FILE_PATHS_INITIALIZED = True
+
+
+class Response:
+    """
+    Generic HTTP response with custom headers.
+
+    Use this when you need to return a response with custom headers (like Allow for OPTIONS).
+
+    Examples:
+        # OPTIONS handler with Allow header
+        @api.options("/items")
+        async def options_items():
+            return Response({}, headers={"Allow": "GET, POST, PUT, DELETE"})
+
+        # Custom response with additional headers
+        @api.get("/data")
+        async def get_data():
+            return Response(
+                {"result": "data"},
+                status_code=200,
+                headers={"X-Custom-Header": "value"}
+            )
+    """
+    def __init__(
+        self,
+        content: Any = None,
+        status_code: int = 200,
+        headers: Optional[Dict[str, str]] = None,
+        media_type: str = "application/json"
+    ):
+        self.content = content if content is not None else {}
+        self.status_code = status_code
+        self.headers = headers or {}
+        self.media_type = media_type
+
+    def to_bytes(self) -> bytes:
+        if self.media_type == "application/json":
+            return msgspec.json.encode(self.content)
+        elif isinstance(self.content, str):
+            return self.content.encode()
+        elif isinstance(self.content, bytes):
+            return self.content
+        else:
+            return str(self.content).encode()
+
+
+class JSON:
+    def __init__(self, data: Any, status_code: int = 200, headers: Optional[Dict[str, str]] = None):
+        self.data = data
+        self.status_code = status_code
+        self.headers = headers or {}
+
+    def to_bytes(self) -> bytes:
+        return msgspec.json.encode(self.data)
+
+
+
+class PlainText:
+    def __init__(self, text: str, status_code: int = 200, headers: Optional[Dict[str, str]] = None):
+        self.text = text
+        self.status_code = status_code
+        self.headers = headers or {}
+
+    def to_bytes(self) -> bytes:
+        return self.text.encode()
+
+
+class HTML:
+    def __init__(self, html: str, status_code: int = 200, headers: Optional[Dict[str, str]] = None):
+        self.html = html
+        self.status_code = status_code
+        self.headers = headers or {}
+
+    def to_bytes(self) -> bytes:
+        return self.html.encode()
+
+
+class Redirect:
+    def __init__(self, url: str, status_code: int = 307, headers: Optional[Dict[str, str]] = None):
+        self.url = url
+        self.status_code = status_code
+        self.headers = headers or {}
+
+
+class File:
+    def __init__(self, path: str, *, media_type: Optional[str] = None, filename: Optional[str] = None, status_code: int = 200, headers: Optional[Dict[str, str]] = None):
+        self.path = path
+        self.media_type = media_type
+        self.filename = filename
+        self.status_code = status_code
+        self.headers = headers or {}
+
+    def read_bytes(self) -> bytes:
+        with open(self.path, "rb") as f:
+            return f.read()
+
+
+class UploadFile:
+    def __init__(self, name: str, filename: Optional[str], content_type: Optional[str], path: str):
+        self.name = name
+        self.filename = filename
+        self.content_type = content_type
+        self.path = path
+
+    def read(self) -> bytes:
+        with open(self.path, "rb") as f:
+            return f.read()
+
+
+
+class FileResponse:
+    def __init__(
+        self,
+        path: str,
+        *,
+        media_type: Optional[str] = None,
+        filename: Optional[str] = None,
+        status_code: int = 200,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        # SECURITY: Validate and canonicalize path to prevent traversal
+
+        # Convert to absolute path and resolve any .. or symlinks
+        try:
+            resolved_path = Path(path).resolve()
+        except (OSError, RuntimeError) as e:
+            raise ValueError(f"Invalid file path: {e}")
+
+        # Check if the file exists and is a regular file (not a directory or special file)
+        if not resolved_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        if not resolved_path.is_file():
+            raise ValueError(f"Path is not a regular file: {path}")
+
+        # Check against allowed directories if configured (using cached value)
+        if _ALLOWED_FILE_PATHS_CACHE is not None:
+            # Ensure the resolved path is within one of the allowed directories
+            is_allowed = False
+            for allowed_path in _ALLOWED_FILE_PATHS_CACHE:
+                try:
+                    # Check if resolved_path is relative to allowed_path
+                    resolved_path.relative_to(allowed_path)
+                    is_allowed = True
+                    break
+                except ValueError:
+                    # Not a subpath, continue checking
+                    continue
+
+            if not is_allowed:
+                raise PermissionError(
+                    f"File path '{path}' is not within allowed directories. "
+                    f"Configure BOLT_ALLOWED_FILE_PATHS in Django settings."
+                )
+
+        self.path = str(resolved_path)
+        self.media_type = media_type
+        self.filename = filename
+        self.status_code = status_code
+        self.headers = headers or {}
+
+
+
+class StreamingResponse:
+    def __init__(
+        self,
+        content: Any,
+        *,
+        status_code: int = 200,
+        media_type: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        # content can be an iterator/generator, iterable, or a callable returning an iterator
+        self.content = content
+        self.status_code = status_code
+        self.media_type = media_type or "application/octet-stream"
+        self.headers = headers or {}
+        # do not enforce type of content here; Rust side will adapt common iterator/callable patterns
+