svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/documents/storage.py

@@ -0,0 +1,262 @@
+"""
+Document storage operations using svc-infra storage backend.
+
+This module provides CRUD operations for document management, storing file content
+in the configured storage backend (S3, local, memory) and metadata in SQL.
+
+Quick Start:
+    >>> import asyncio
+    >>> from svc_infra.storage import easy_storage
+    >>> from svc_infra.documents.storage import upload_document, get_document
+    >>>
+    >>> storage = easy_storage()
+    >>> doc = await upload_document(
+    ...     storage=storage,
+    ...     user_id="user_123",
+    ...     file=b"file content",
+    ...     filename="document.pdf",
+    ...     metadata={"category": "legal"}
+    ... )
+    >>> print(doc.id, doc.storage_path)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from svc_infra.storage.base import StorageBackend
+
+    from .models import Document
+
+# In-memory metadata storage (production: use SQL database)
+# This is a temporary solution until SQL integration is complete
+_documents_metadata: dict[str, Document] = {}
+
+
+async def upload_document(
+    storage: StorageBackend,
+    user_id: str,
+    file: bytes,
+    filename: str,
+    metadata: dict | None = None,
+    content_type: str | None = None,
+) -> Document:
+    """
+    Upload a document with file content to storage backend.
+
+    Args:
+        storage: Storage backend instance (S3, local, memory)
+        user_id: User uploading the document
+        file: File content as bytes
+        filename: Original filename
+        metadata: Optional custom metadata dictionary
+        content_type: Optional MIME type (auto-detected if not provided)
+
+    Returns:
+        Document with storage information and metadata
+
+    Examples:
+        >>> from svc_infra.storage import easy_storage
+        >>> storage = easy_storage()
+        >>>
+        >>> # Upload PDF document
+        >>> doc = upload_document(
+        ...     storage=storage,
+        ...     user_id="user_123",
+        ...     file=pdf_bytes,
+        ...     filename="contract.pdf",
+        ...     metadata={"category": "legal", "year": 2024}
+        ... )
+        >>>
+        >>> # Upload image
+        >>> doc = upload_document(
+        ...     storage=storage,
+        ...     user_id="user_456",
+        ...     file=image_bytes,
+        ...     filename="photo.jpg",
+        ...     content_type="image/jpeg"
+        ... )
+
+    Notes:
+        - Current: In-memory metadata storage (for development)
+        - Production: Store metadata in SQL database using svc-infra SQL helpers
+        - Storage path format: documents/{user_id}/{doc_id}/{filename}
+        - Checksum: SHA-256 hash for integrity validation
+    """
+    from .models import Document
+
+    # Generate unique document ID
+    doc_id = f"doc_{uuid.uuid4().hex[:12]}"
+
+    # Build storage path with user isolation
+    storage_path = f"documents/{user_id}/{doc_id}/{filename}"
+
+    # Detect content type if not provided
+    if content_type is None:
+        detected_type, _ = mimetypes.guess_type(filename)
+        content_type = detected_type or "application/octet-stream"
+
+    # Calculate checksum for integrity
+    checksum = f"sha256:{hashlib.sha256(file).hexdigest()}"
+
+    # Upload file to storage backend
+    await storage.put(storage_path, file, content_type=content_type, metadata=metadata or {})
+
+    # Create document metadata
+    doc = Document(
+        id=doc_id,
+        user_id=user_id,
+        filename=filename,
+        file_size=len(file),
+        upload_date=datetime.utcnow(),
+        storage_path=storage_path,
+        content_type=content_type,
+        checksum=checksum,
+        metadata=metadata or {},
+    )
+
+    # Store metadata (production: use SQL)
+    _documents_metadata[doc_id] = doc
+
+    return doc
+
+
+def get_document(document_id: str) -> Document | None:
+    """
+    Get document metadata by ID.
+
+    Args:
+        document_id: Document identifier
+
+    Returns:
+        Document metadata or None if not found
+
+    Examples:
+        >>> doc = get_document("doc_abc123")
+        >>> if doc:
+        ...     print(doc.filename, doc.file_size)
+    """
+    return _documents_metadata.get(document_id)
+
+
+async def download_document(storage: StorageBackend, document_id: str) -> bytes:
+    """
+    Download document file content from storage.
+
+    Args:
+        storage: Storage backend instance
+        document_id: Document identifier
+
+    Returns:
+        Document file content as bytes
+
+    Raises:
+        ValueError: If document not found
+
+    Examples:
+        >>> from svc_infra.storage import easy_storage
+        >>> storage = easy_storage()
+        >>>
+        >>> file_data = await download_document(storage, "doc_abc123")
+        >>> with open("downloaded.pdf", "wb") as f:
+        ...     f.write(file_data)
+    """
+    doc = get_document(document_id)
+    if not doc:
+        raise ValueError(f"Document not found: {document_id}")
+
+    # Download from storage backend
+    return await storage.get(doc.storage_path)
+
+
+async def delete_document(storage: StorageBackend, document_id: str) -> bool:
+    """
+    Delete document and its file content.
+
+    Args:
+        storage: Storage backend instance
+        document_id: Document identifier
+
+    Returns:
+        True if deleted, False if not found
+
+    Examples:
+        >>> from svc_infra.storage import easy_storage
+        >>> storage = easy_storage()
+        >>>
+        >>> success = delete_document(storage, "doc_abc123")
+        >>> if success:
+        ...     print("Document deleted")
+    """
+    doc = get_document(document_id)
+    if not doc:
+        return False
+
+    # Delete from storage backend
+    await storage.delete(doc.storage_path)
+
+    # Delete metadata (production: use SQL)
+    del _documents_metadata[document_id]
+
+    return True
+
+
+def list_documents(
+    user_id: str,
+    limit: int = 100,
+    offset: int = 0,
+) -> list[Document]:
+    """
+    List user's documents with pagination.
+
+    Args:
+        user_id: User identifier
+        limit: Maximum number of documents to return
+        offset: Number of documents to skip
+
+    Returns:
+        List of user's documents
+
+    Examples:
+        >>> # Get first page
+        >>> docs = list_documents("user_123", limit=20)
+        >>>
+        >>> # Get second page
+        >>> docs = list_documents("user_123", limit=20, offset=20)
+        >>>
+        >>> # Filter by metadata (future enhancement)
+        >>> # docs = list_documents("user_123", filters={"category": "legal"})
+
+    Notes:
+        - Current: In-memory filtering
+        - Production: Use SQL queries with proper indexing
+        - Future: Add metadata filtering and sorting
+    """
+    # Filter by user (production: SQL query)
+    user_docs = [doc for doc in _documents_metadata.values() if doc.user_id == user_id]
+
+    # Sort by upload date (newest first)
+    user_docs.sort(key=lambda d: d.upload_date, reverse=True)
+
+    # Apply pagination
+    return user_docs[offset : offset + limit]
+
+
+def clear_storage() -> None:
+    """
+    Clear all document metadata (for testing only).
+
+    Warning:
+        This does NOT delete files from storage backend.
+        Only use in test environments.
+
+    Examples:
+        >>> # In tests
+        >>> clear_storage()
+    """
+    _documents_metadata.clear()

svc_infra/dx/__init__.py

@@ -0,0 +1,58 @@
+"""Developer experience utilities for CI, changelog, and code quality checks.
+
+This module provides utilities to improve developer experience:
+
+- **CI Workflow**: Generate GitHub Actions CI workflow files
+- **Changelog**: Generate release sections from conventional commits
+- **Checks**: OpenAPI schema validation and migration verification
+
+Example:
+    from svc_infra.dx import write_ci_workflow, write_openapi_lint_config
+
+    # Generate CI workflow for a project
+    write_ci_workflow(target_dir="./myproject", python_version="3.12")
+
+    # Generate OpenAPI lint config
+    write_openapi_lint_config(target_dir="./myproject")
+
+    # Validate OpenAPI schema
+    from svc_infra.dx import check_openapi_problem_schema
+
+    check_openapi_problem_schema(path="openapi.json")
+
+    # Generate changelog section
+    from svc_infra.dx import Commit, generate_release_section
+
+    commits = [
+        Commit(sha="abc123", subject="feat: add new feature"),
+        Commit(sha="def456", subject="fix: resolve bug"),
+    ]
+    changelog = generate_release_section(version="1.0.0", commits=commits)
+    print(changelog)
+
+See Also:
+    - CLI commands: svc-infra dx openapi, svc-infra dx changelog
+"""
+
+from __future__ import annotations
+
+# CI workflow generation
+from .add import write_ci_workflow, write_openapi_lint_config
+
+# Changelog generation
+from .changelog import Commit, generate_release_section
+
+# Code quality checks
+from .checks import check_migrations_up_to_date, check_openapi_problem_schema
+
+__all__ = [
+    # CI workflow
+    "write_ci_workflow",
+    "write_openapi_lint_config",
+    # Changelog
+    "Commit",
+    "generate_release_section",
+    # Checks
+    "check_openapi_problem_schema",
+    "check_migrations_up_to_date",
+]

svc_infra/dx/add.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def write_ci_workflow(
+    *,
+    target_dir: str | Path,
+    name: str = "ci.yml",
+    python_version: str = "3.12",
+) -> Path:
+    """Write a minimal CI workflow file (GitHub Actions) with tests/lint/type steps."""
+    p = Path(target_dir) / ".github" / "workflows" / name
+    p.parent.mkdir(parents=True, exist_ok=True)
+    content = f"""
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '{python_version}'
+      - name: Install Poetry
+        run: pipx install poetry
+      - name: Install deps
+        run: poetry install
+      - name: Lint
+        run: poetry run flake8 --select=E,F
+      - name: Typecheck
+        run: poetry run mypy src
+      - name: Tests
+        run: poetry run pytest -q -W error
+"""
+    p.write_text(content.strip() + "\n")
+    return p
+
+
+def write_openapi_lint_config(*, target_dir: str | Path, name: str = ".redocly.yaml") -> Path:
+    """Write a minimal OpenAPI lint config placeholder (Redocly)."""
+    p = Path(target_dir) / name
+    content = """
+apis:
+  main:
+    root: openapi.json
+
+rules:
+  operation-operationId: warn
+  no-unused-components: warn
+  security-defined: off
+"""
+    p.write_text(content.strip() + "\n")
+    return p
+
+
+__all__ = ["write_ci_workflow", "write_openapi_lint_config"]

svc_infra/dx/changelog.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import date as _date
+
+
+@dataclass(frozen=True)
+class Commit:
+    sha: str
+    subject: str
+
+
+_SECTION_ORDER = [
+    ("feat", "Features"),
+    ("fix", "Bug Fixes"),
+    ("perf", "Performance"),
+    ("refactor", "Refactors"),
+]
+
+
+def _classify(subject: str) -> tuple[str, str]:
+    """Return (type, title) where title is display name of the section."""
+    lower = subject.strip().lower()
+    for t, title in _SECTION_ORDER:
+        if lower.startswith(t + ":") or lower.startswith(t + "("):
+            return (t, title)
+    return ("other", "Other")
+
+
+def _format_item(commit: Commit) -> str:
+    subj = commit.subject.strip()
+    # Strip leading type(scope): if present
+    i = subj.find(": ")
+    if i != -1 and i < 20:  # conventional commit prefix
+        pretty = subj[i + 2 :].strip()
+    else:
+        pretty = subj
+    return f"- {pretty} ({commit.sha})"
+
+
+def generate_release_section(
+    *,
+    version: str,
+    commits: Sequence[Commit],
+    release_date: str | None = None,
+) -> str:
+    """Generate a markdown release section from commits.
+
+    Group by type: feat, fix, perf, refactor; everything else under Other.
+    """
+    if release_date is None:
+        release_date = _date.today().isoformat()
+
+    buckets: dict[str, list[str]] = {k: [] for k, _ in _SECTION_ORDER}
+    buckets["other"] = []
+
+    for c in commits:
+        typ, _ = _classify(c.subject)
+        buckets.setdefault(typ, []).append(_format_item(c))
+
+    lines: list[str] = [f"## v{version} - {release_date}", ""]
+    for key, title in [*_SECTION_ORDER, ("other", "Other")]:
+        items = buckets.get(key) or []
+        if not items:
+            continue
+        lines.append(f"### {title}")
+        lines.extend(items)
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+__all__ = ["Commit", "generate_release_section"]

svc_infra/dx/checks.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+
+def _load_json(path: str | Path) -> dict[Any, Any]:
+    import json
+
+    p = Path(path)
+    return cast("dict[Any, Any]", json.loads(p.read_text()))
+
+
+def check_openapi_problem_schema(
+    schema: dict | None = None, *, path: str | Path | None = None
+) -> None:
+    """Validate OpenAPI has a Problem schema with required fields and formats.
+
+    Raises ValueError with a descriptive message on failure.
+    """
+
+    if schema is None:
+        if path is None:
+            raise ValueError("either schema or path must be provided")
+        schema = _load_json(path)
+
+    comps = (schema or {}).get("components") or {}
+    prob = (comps.get("schemas") or {}).get("Problem")
+    if not isinstance(prob, dict):
+        raise ValueError("Problem schema missing under components.schemas.Problem")
+
+    props = prob.get("properties") or {}
+    # Required keys presence
+    for key in ("type", "title", "status", "detail", "instance", "code"):
+        if key not in props:
+            raise ValueError(f"Problem.{key} missing in properties")
+
+    # instance must be uri-reference per our convention
+    inst = props.get("instance") or {}
+    if inst.get("format") != "uri-reference":
+        raise ValueError("Problem.instance must have format 'uri-reference'")
+
+
+def check_migrations_up_to_date(*, project_root: str | Path = ".") -> None:
+    """Best-effort migrations check: passes if alembic env present and head is reachable.
+
+    This is a lightweight stub that can be extended per-project. For now, it checks
+    that an Alembic env exists when 'alembic.ini' is present; it does not execute DB calls.
+    """
+
+    root = Path(project_root)
+    # If alembic.ini is absent, there's nothing to check here
+    if not (root / "alembic.ini").exists():
+        return
+    # Ensure versions/ dir exists under migrations path if configured, default to 'migrations'
+    mig_dir = root / "migrations"
+    if not mig_dir.exists():
+        # tolerate alternative layout via env; keep stub permissive
+        return
+    versions = mig_dir / "versions"
+    if not versions.exists():
+        raise ValueError("Alembic migrations directory missing versions/ subfolder")
+
+
+__all__ = [
+    "check_openapi_problem_schema",
+    "check_migrations_up_to_date",
+]

svc_infra/exceptions.py

@@ -0,0 +1,141 @@
+"""Centralized exception re-exports for svc-infra.
+
+This module provides a single import point for all svc-infra exceptions.
+Exceptions are organized by domain and all inherit from the base SvcInfraError.
+
+Example:
+    from svc_infra.exceptions import (
+        SvcInfraError,
+        WebSocketError,
+        StorageError,
+        FastApiException,
+    )
+"""
+
+# ruff: noqa: E402
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+# =============================================================================
+# Logging Helper
+# =============================================================================
+
+
+def log_exception(
+    logger: logging.Logger,
+    msg: str,
+    exc: Exception,
+    *,
+    level: str = "warning",
+    include_traceback: bool = True,
+) -> None:
+    """Log an exception with consistent formatting.
+
+    Use this helper instead of bare `except Exception:` blocks to ensure
+    all exceptions are properly logged with context.
+
+    Args:
+        logger: The logger instance to use
+        msg: Context message describing what operation failed
+        exc: The exception that was caught
+        level: Log level - "debug", "info", "warning", "error", "critical"
+        include_traceback: Whether to include full traceback (exc_info=True)
+
+    Example:
+        try:
+            result = await service.process()
+        except Exception as e:
+            log_exception(logger, "Failed to process request", e)
+            # Handle gracefully or re-raise
+    """
+    log_func = getattr(logger, level.lower(), logger.warning)
+    log_func(f"{msg}: {type(exc).__name__}: {exc}", exc_info=include_traceback)
+
+
+# =============================================================================
+# Base Error
+# =============================================================================
+
+
+class SvcInfraError(Exception):
+    """Base exception for all svc-infra errors.
+
+    All svc-infra exceptions can be caught with this single class.
+
+    Attributes:
+        message: Human-readable error description
+        details: Additional context as key-value pairs
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict[str, Any] | None = None,
+    ):
+        self.message = message
+        self.details = details or {}
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.message!r})"
+
+
+# =============================================================================
+# Re-exports from submodules
+# =============================================================================
+
+# API exceptions
+from svc_infra.api.fastapi.middleware.errors.exceptions import FastApiException
+
+# App exceptions
+from svc_infra.app.env import MissingSecretError
+
+# Security exceptions
+from svc_infra.security.passwords import PasswordValidationError
+
+# Storage exceptions
+from svc_infra.storage.base import FileNotFoundError as StorageFileNotFoundError
+from svc_infra.storage.base import (
+    InvalidKeyError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    StorageError,
+)
+
+# WebSocket exceptions
+from svc_infra.websocket.exceptions import AuthenticationError as WebSocketAuthError
+from svc_infra.websocket.exceptions import (
+    ConnectionClosedError,
+    ConnectionFailedError,
+    MessageTooLargeError,
+    WebSocketError,
+)
+
+__all__ = [
+    # Logging helper
+    "log_exception",
+    # Base
+    "SvcInfraError",
+    # WebSocket
+    "WebSocketError",
+    "WebSocketAuthError",
+    "ConnectionClosedError",
+    "ConnectionFailedError",
+    "MessageTooLargeError",
+    # Storage
+    "StorageError",
+    "StorageFileNotFoundError",
+    "InvalidKeyError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    # API
+    "FastApiException",
+    # App
+    "MissingSecretError",
+    # Security
+    "PasswordValidationError",
+]