edocapi 0.0.2__py3-none-any.whl

edocapi/responses.py

@@ -0,0 +1,88 @@
+"""Response helpers for eDocAPI."""
+
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+from typing import Any, Mapping
+
+from starlette.responses import FileResponse as StarletteFileResponse
+from starlette.responses import JSONResponse as StarletteJSONResponse
+from starlette.responses import Response
+
+
+class JSONResponse(StarletteJSONResponse):
+    """JSON response that serializes normal Python dicts / lists."""
+
+    def __init__(
+        self,
+        content: Any = None,
+        status_code: int = 200,
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            content=content if content is not None else {},
+            status_code=status_code,
+            headers=headers,
+            **kwargs,
+        )
+
+
+class FileResponse(StarletteFileResponse):
+    """File response with sensible defaults for document downloads.
+
+    Automatically sets Content-Type and Content-Disposition when possible.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        filename: str | None = None,
+        media_type: str | None = None,
+        status_code: int = 200,
+        headers: Mapping[str, str] | None = None,
+        background: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        path = Path(path)
+        if filename is None:
+            filename = path.name
+
+        if media_type is None:
+            guessed, _ = mimetypes.guess_type(filename)
+            media_type = guessed or "application/octet-stream"
+
+        super().__init__(
+            path=str(path),
+            filename=filename,
+            media_type=media_type,
+            status_code=status_code,
+            headers=headers,
+            background=background,
+            **kwargs,
+        )
+
+
+def make_error_response(
+    error: Exception,
+    *,
+    status_code: int = 400,
+    debug: bool = False,
+) -> JSONResponse:
+    """Create a consistent JSON error response from an exception."""
+    from edocapi.exceptions import EdocAPIError
+
+    if isinstance(error, EdocAPIError):
+        body = error.to_dict()
+        if debug:
+            body["detail"] = str(error)
+    else:
+        body = {
+            "error": type(error).__name__,
+            "message": str(error) if debug else "An unexpected error occurred.",
+        }
+        if debug:
+            body["detail"] = str(error)
+
+    return JSONResponse(content=body, status_code=status_code)

edocapi/storage/__init__.py

@@ -0,0 +1,3 @@
+from edocapi.storage.temporary import TemporaryStorage, safe_filename
+
+__all__ = ["TemporaryStorage", "safe_filename"]

edocapi/storage/temporary.py

@@ -0,0 +1,132 @@
+"""Temporary file management for eDocAPI."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import shutil
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Iterator
+
+logger = logging.getLogger("edocapi.storage")
+
+
+class TemporaryStorage:
+    """Manages a private temporary directory for document processing.
+
+    Files created here are cleaned up when the storage instance is closed
+    or when the process exits (via atexit).
+    """
+
+    def __init__(self, base_dir: Path | str | None = None) -> None:
+        if base_dir is not None:
+            self._root = Path(base_dir)
+            self._root.mkdir(parents=True, exist_ok=True)
+            self._owned = False
+        else:
+            self._root = Path(tempfile.mkdtemp(prefix="edocapi_"))
+            self._owned = True
+
+        self._files: set[Path] = set()
+        self._cleanup_callback = self.cleanup
+        atexit.register(self._cleanup_callback)
+        logger.debug("Temporary storage created at %s", self._root)
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def create_file(
+        self,
+        suffix: str = "",
+        prefix: str = "tmp_",
+        content: bytes | None = None,
+    ) -> Path:
+        """Create a new temporary file path (and optionally write content)."""
+        name = f"{prefix}{uuid.uuid4().hex}{suffix}"
+        path = self._root / name
+        if content is not None:
+            path.write_bytes(content)
+        else:
+            path.touch()
+        self._files.add(path)
+        return path
+
+    def create_dir(self, prefix: str = "dir_") -> Path:
+        """Create a subdirectory inside the temporary root."""
+        name = f"{prefix}{uuid.uuid4().hex}"
+        path = self._root / name
+        path.mkdir(parents=True, exist_ok=True)
+        self._files.add(path)
+        return path
+
+    def register(self, path: Path | str) -> Path:
+        """Register an existing path for later cleanup."""
+        path = Path(path)
+        self._files.add(path)
+        return path
+
+    def discard(self, path: Path | str) -> None:
+        """Remove a file from managed storage after its response is sent."""
+        path = Path(path)
+        self._files.discard(path)
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as exc:
+            logger.warning("Failed to remove temporary file %s: %s", path, exc)
+
+    def cleanup(self) -> None:
+        """Remove all tracked files and, if owned, the root directory."""
+        for path in list(self._files):
+            try:
+                if path.is_file():
+                    path.unlink(missing_ok=True)
+                elif path.is_dir():
+                    shutil.rmtree(path, ignore_errors=True)
+            except OSError as exc:
+                logger.warning("Failed to clean up %s: %s", path, exc)
+        self._files.clear()
+
+        if self._owned and self._root.exists():
+            try:
+                shutil.rmtree(self._root, ignore_errors=True)
+                logger.debug("Removed temporary root %s", self._root)
+            except OSError as exc:
+                logger.warning("Failed to remove temp root %s: %s", self._root, exc)
+
+        # The instance may be explicitly cleaned up before interpreter exit.
+        try:
+            atexit.unregister(self._cleanup_callback)
+        except Exception:
+            pass
+
+    def __enter__(self) -> "TemporaryStorage":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.cleanup()
+
+    def __del__(self) -> None:
+        try:
+            self.cleanup()
+        except Exception:
+            pass
+
+
+def safe_filename(name: str) -> str:
+    """Sanitize a filename to prevent path traversal and unsafe characters."""
+    # Take only the basename
+    name = os.path.basename(name)
+    # Remove null bytes and control characters
+    name = "".join(c for c in name if c.isprintable() and c not in r'<>:"/\|?*')
+    name = name.strip().strip(".")
+    if not name:
+        name = "unnamed"
+    # Limit length
+    if len(name) > 200:
+        stem, ext = os.path.splitext(name)
+        name = stem[:190] + ext
+    return name

edocapi/validation/__init__.py

@@ -0,0 +1,13 @@
+from edocapi.validation.files import (
+    SUPPORTED_EXTENSIONS,
+    SUPPORTED_MIME_TYPES,
+    validate_file,
+    validate_upload,
+)
+
+__all__ = [
+    "SUPPORTED_EXTENSIONS",
+    "SUPPORTED_MIME_TYPES",
+    "validate_file",
+    "validate_upload",
+]

edocapi/validation/files.py

@@ -0,0 +1,209 @@
+"""File validation utilities for eDocAPI."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import BinaryIO
+
+from edocapi.exceptions import (
+    FileTooLarge,
+    InvalidDocument,
+    UnsupportedFileType,
+    ValidationError,
+)
+
+logger = logging.getLogger("edocapi.validation")
+
+# Supported formats for v0.0.2
+SUPPORTED_EXTENSIONS = {
+    ".pdf",
+    ".docx",
+    ".html",
+    ".htm",
+    ".md",
+    ".markdown",
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".webp",
+    ".txt",
+}
+
+SUPPORTED_MIME_TYPES = {
+    "application/pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "text/html",
+    "text/markdown",
+    "text/x-markdown",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "text/plain",
+}
+
+# Magic byte signatures (first few bytes)
+MAGIC_SIGNATURES: dict[bytes, str] = {
+    b"%PDF": "pdf",
+    b"PK\x03\x04": "zip",  # DOCX is a ZIP; further checks needed
+    b"\xff\xd8\xff": "jpeg",
+    b"\x89PNG\r\n\x1a\n": "png",
+    b"RIFF": "webp",  # needs further check for WEBP
+}
+
+
+def detect_type_from_bytes(data: bytes) -> str | None:
+    """Attempt to detect document type from magic bytes."""
+    if not data:
+        return None
+
+    for sig, kind in MAGIC_SIGNATURES.items():
+        if data.startswith(sig):
+            if kind == "zip":
+                # Could be DOCX or other Office format
+                if b"word/" in data[:4096] or b"[Content_Types].xml" in data[:4096]:
+                    return "docx"
+                return "zip"
+            if kind == "webp":
+                if b"WEBP" in data[8:16]:
+                    return "webp"
+                return None
+            return kind
+
+    # HTML / Markdown / TXT heuristics
+    sample = data[:1024].decode("utf-8", errors="ignore").strip().lower()
+    if sample.startswith("<!doctype html") or sample.startswith("<html"):
+        return "html"
+    if sample.startswith("# ") or sample.startswith("---\n"):
+        return "markdown"
+    # Plain text fallback only if mostly printable
+    if all(32 <= b < 127 or b in (9, 10, 13) for b in data[:512]):
+        return "txt"
+    return None
+
+
+def validate_extension(filename: str) -> str:
+    """Validate and return the normalized extension (including dot)."""
+    from edocapi.storage.temporary import safe_filename
+
+    name = safe_filename(filename)
+    ext = Path(name).suffix.lower()
+    if ext not in SUPPORTED_EXTENSIONS:
+        raise UnsupportedFileType(
+            f"File extension '{ext}' is not supported.",
+            extension=ext,
+        )
+    return ext
+
+
+def validate_size(size: int, max_size: int) -> None:
+    """Raise FileTooLarge if size exceeds the limit."""
+    if size > max_size:
+        raise FileTooLarge(size=size, max_size=max_size)
+
+
+def validate_file(
+    path: Path,
+    *,
+    max_size: int,
+    expected_type: str | None = None,
+) -> str:
+    """Perform basic validation on a file path.
+
+    Returns the detected document type string (e.g. 'pdf', 'docx').
+    """
+    if not path.exists():
+        raise ValidationError(f"File does not exist: {path}")
+    if not path.is_file():
+        raise ValidationError(f"Path is not a regular file: {path}")
+
+    size = path.stat().st_size
+    validate_size(size, max_size)
+
+    # Read a small header for magic detection
+    with path.open("rb") as f:
+        header = f.read(4096)
+
+    detected = detect_type_from_bytes(header)
+    ext = path.suffix.lower()
+
+    # Map extension to type
+    ext_to_type = {
+        ".pdf": "pdf",
+        ".docx": "docx",
+        ".html": "html",
+        ".htm": "html",
+        ".md": "markdown",
+        ".markdown": "markdown",
+        ".jpg": "jpeg",
+        ".jpeg": "jpeg",
+        ".png": "png",
+        ".webp": "webp",
+        ".txt": "txt",
+    }
+    ext_type = ext_to_type.get(ext)
+
+    if detected is None and ext_type is None:
+        raise UnsupportedFileType(
+            "Unable to determine file type.",
+            extension=ext,
+        )
+
+    # Prefer detected type; fall back to extension
+    doc_type = detected or ext_type
+
+    # Basic consistency check
+    if detected and ext_type and detected != ext_type:
+        # Allow some flexibility (e.g. .txt that looks like markdown)
+        if not (detected in ("txt", "markdown") and ext_type in ("txt", "markdown")):
+            logger.warning(
+                "Magic type %s does not match extension type %s for %s",
+                detected,
+                ext_type,
+                path.name,
+            )
+
+    if expected_type and doc_type != expected_type:
+        raise InvalidDocument(
+            f"Expected document type '{expected_type}', got '{doc_type}'."
+        )
+
+    return doc_type  # type: ignore[return-value]
+
+
+def validate_upload(
+    filename: str | None,
+    content: bytes | BinaryIO,
+    *,
+    max_size: int,
+) -> tuple[str, bytes]:
+    """Validate an uploaded file and return (safe_filename, content_bytes)."""
+    from edocapi.storage.temporary import safe_filename
+
+    if not filename:
+        raise ValidationError("Uploaded file has no filename.")
+
+    safe_name = safe_filename(filename)
+    validate_extension(safe_name)
+
+    if hasattr(content, "read"):
+        data = content.read()
+    else:
+        data = content
+
+    if not isinstance(data, (bytes, bytearray)):
+        raise ValidationError("File content must be bytes.")
+
+    validate_size(len(data), max_size)
+
+    detected = detect_type_from_bytes(data)
+    if detected is None:
+        # Still allow based on extension for text formats
+        ext = Path(safe_name).suffix.lower()
+        if ext not in {".txt", ".md", ".markdown", ".html", ".htm"}:
+            raise UnsupportedFileType(
+                "Unable to determine a supported file type from content.",
+                extension=ext,
+            )
+
+    return safe_name, bytes(data)