simple-module-file-storage 0.0.1__py3-none-any.whl

file_storage/__init__.py

@@ -0,0 +1 @@
+"""FileStorage module."""

file_storage/backends/__init__.py

@@ -0,0 +1,77 @@
+"""Storage backend registry — extension point for storage providers.
+
+Built-in providers (filesystem, S3) self-register on import. Third-party
+packages add new providers via :func:`register_backend`::
+
+    from file_storage.backends import register_backend
+    from file_storage.contracts.service import StorageBackend
+
+    @register_backend("azure_blob")
+    def _build(settings) -> StorageBackend:
+        return AzureBlobBackend(...)
+
+The factory receives the parsed :class:`FileStorageSettings` so providers
+can read their own ``SM_FILE_STORAGE_*`` keys (or extend the settings
+class with extra fields). :func:`build_backend` resolves the active
+factory by ``settings.backend`` and raises :class:`ConfigurationError`
+on an unknown id, listing all currently registered providers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from file_storage.contracts.service import ConfigurationError
+
+if TYPE_CHECKING:
+    from file_storage.contracts.service import StorageBackend
+    from file_storage.settings import FileStorageSettings
+
+BackendFactory = Callable[["FileStorageSettings"], "StorageBackend"]
+
+_REGISTRY: dict[str, BackendFactory] = {}
+
+
+def register_backend(backend_id: str) -> Callable[[BackendFactory], BackendFactory]:
+    """Decorator that registers a factory under ``backend_id``."""
+
+    def decorator(factory: BackendFactory) -> BackendFactory:
+        _REGISTRY[backend_id] = factory
+        return factory
+
+    return decorator
+
+
+def unregister_backend(backend_id: str) -> None:
+    """Remove a registered backend. Primarily for tests."""
+    _REGISTRY.pop(backend_id, None)
+
+
+def registered_backends() -> list[str]:
+    """Return all currently registered backend ids, sorted."""
+    return sorted(_REGISTRY)
+
+
+def build_backend(settings: FileStorageSettings) -> StorageBackend:
+    """Construct the backend selected by ``settings.backend``."""
+    factory = _REGISTRY.get(settings.backend)
+    if factory is None:
+        raise ConfigurationError(
+            f"Unknown storage backend {settings.backend!r}. Registered: {registered_backends()}."
+        )
+    return factory(settings)
+
+
+# Trigger self-registration of built-in providers. Order is irrelevant; both
+# add themselves to the same module-global registry.
+from file_storage.backends import filesystem as _filesystem  # noqa: E402,F401
+from file_storage.backends import s3 as _s3  # noqa: E402,F401
+
+__all__ = [
+    "BackendFactory",
+    "build_backend",
+    "register_backend",
+    "registered_backends",
+    "unregister_backend",
+]

file_storage/backends/filesystem.py

@@ -0,0 +1,84 @@
+"""Filesystem storage backend — writes objects under a configurable root."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import aiofiles
+
+from file_storage import constants
+from file_storage.backends import register_backend
+from file_storage.contracts.service import (
+    NotSupportedError,
+    StorageBackendError,
+    StorageNotFoundError,
+)
+from file_storage.settings import FileStorageSettings
+
+
+class FilesystemBackend:
+    """Stores objects on the local filesystem under ``root``.
+
+    Keys are sharded by their first two characters to keep any single
+    directory from accumulating millions of entries (which slows ``readdir``
+    on most filesystems). A key like ``2026/04/19/abc123.png`` is written to
+    ``<root>/20/2026/04/19/abc123.png``.
+    """
+
+    backend_id = constants.BackendId.FILESYSTEM
+    supports_presigned_url = False
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def _resolve(self, key: str) -> Path:
+        # Reject path traversal: ".." segments and absolute paths can escape root.
+        if key.startswith("/") or ".." in Path(key).parts:
+            raise StorageBackendError(f"Invalid storage key: {key!r}")
+        shard = key[:2] if len(key) >= 2 else "_"
+        return self.root / shard / key
+
+    async def put(
+        self,
+        key: str,
+        stream: AsyncIterator[bytes],
+        *,
+        content_type: str,
+        size: int,
+    ) -> None:
+        path = self._resolve(key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        async with aiofiles.open(path, "wb") as fh:
+            async for chunk in stream:
+                await fh.write(chunk)
+
+    async def get(self, key: str) -> AsyncIterator[bytes]:
+        path = self._resolve(key)
+        if not path.exists():
+            raise StorageNotFoundError(key)
+        return _stream_file(path)
+
+    async def delete(self, key: str) -> None:
+        path = self._resolve(key)
+        path.unlink(missing_ok=True)
+
+    async def exists(self, key: str) -> bool:
+        return self._resolve(key).exists()
+
+    async def presigned_get_url(self, key: str, ttl_seconds: int) -> str:
+        raise NotSupportedError("Filesystem backend cannot mint presigned URLs.")
+
+
+async def _stream_file(path: Path) -> AsyncIterator[bytes]:
+    async with aiofiles.open(path, "rb") as fh:
+        while True:
+            chunk = await fh.read(constants.DEFAULT_CHUNK_SIZE)
+            if not chunk:
+                break
+            yield chunk
+
+
+@register_backend(constants.BackendId.FILESYSTEM)
+def _build(settings: FileStorageSettings) -> FilesystemBackend:
+    return FilesystemBackend(root=settings.resolved_fs_root())

file_storage/backends/s3.py

@@ -0,0 +1,156 @@
+"""S3-compatible storage backend (AWS S3, MinIO, Cloudflare R2, ...).
+
+``aioboto3`` is imported lazily at backend construction so the module loads
+even when the optional S3 extra isn't installed; the failure mode is a clear
+:class:`ConfigurationError` at boot rather than a confusing import error.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from tempfile import SpooledTemporaryFile
+from typing import TYPE_CHECKING, Any
+
+from file_storage import constants
+from file_storage.backends import register_backend
+from file_storage.contracts.service import (
+    ConfigurationError,
+    StorageBackendError,
+    StorageNotFoundError,
+)
+from file_storage.settings import FileStorageSettings
+
+if TYPE_CHECKING:
+    pass
+
+
+class S3Backend:
+    """S3-compatible object storage.
+
+    Each operation opens a fresh ``aioboto3`` client context (cheap; the
+    underlying ``aiobotocore`` session is reused via ``self._session``). We
+    deliberately do not hold one long-lived client across requests because
+    aioboto3 client contexts are per-event-loop and tests run multiple loops.
+    """
+
+    backend_id = constants.BackendId.S3
+    supports_presigned_url = True
+
+    def __init__(self, *, bucket: str, region: str, client_kwargs: dict[str, Any]) -> None:
+        try:
+            import aioboto3
+        except ImportError as exc:
+            raise ConfigurationError(
+                "S3 backend requires the 'aioboto3' package. "
+                "Install with: uv add --optional s3 aioboto3"
+            ) from exc
+        self._aioboto3 = aioboto3
+        self._session = aioboto3.Session()
+        self.bucket = bucket
+        self.region = region
+        self.client_kwargs = client_kwargs
+
+    def _client(self):
+        return self._session.client("s3", **self.client_kwargs)
+
+    async def put(
+        self,
+        key: str,
+        stream: AsyncIterator[bytes],
+        *,
+        content_type: str,
+        size: int,
+    ) -> None:
+        # Spool to memory up to SPOOL_MAX_SIZE_BYTES, then to a temp file.
+        # put_object needs a seekable file-like; multipart upload would be
+        # the next step for very large files (deferred to v2).
+        with SpooledTemporaryFile(max_size=constants.SPOOL_MAX_SIZE_BYTES) as buf:
+            async for chunk in stream:
+                buf.write(chunk)
+            length = buf.tell()
+            buf.seek(0)
+            try:
+                async with self._client() as client:
+                    await client.put_object(
+                        Bucket=self.bucket,
+                        Key=key,
+                        Body=buf,
+                        ContentType=content_type,
+                        ContentLength=length,
+                    )
+            except Exception as exc:
+                raise StorageBackendError(f"S3 put_object failed: {exc}") from exc
+
+    async def get(self, key: str) -> AsyncIterator[bytes]:
+        try:
+            async with self._client() as client:
+                resp = await client.get_object(Bucket=self.bucket, Key=key)
+                # ``Body.read()`` works uniformly across aioboto3 (real) and
+                # moto's patched aiobotocore (tests); ``iter_chunks`` is sync
+                # under moto, breaking ``async for``.
+                data = await resp["Body"].read()
+        except Exception as exc:
+            if _is_not_found(exc):
+                raise StorageNotFoundError(key) from exc
+            raise StorageBackendError(f"S3 get_object failed: {exc}") from exc
+
+        for offset in range(0, len(data), constants.DEFAULT_CHUNK_SIZE):
+            yield data[offset : offset + constants.DEFAULT_CHUNK_SIZE]
+
+    async def delete(self, key: str) -> None:
+        try:
+            async with self._client() as client:
+                await client.delete_object(Bucket=self.bucket, Key=key)
+        except Exception as exc:
+            raise StorageBackendError(f"S3 delete_object failed: {exc}") from exc
+
+    async def exists(self, key: str) -> bool:
+        try:
+            async with self._client() as client:
+                await client.head_object(Bucket=self.bucket, Key=key)
+                return True
+        except Exception as exc:
+            if _is_not_found(exc):
+                return False
+            raise StorageBackendError(f"S3 head_object failed: {exc}") from exc
+
+    async def presigned_get_url(self, key: str, ttl_seconds: int) -> str:
+        try:
+            async with self._client() as client:
+                return await client.generate_presigned_url(
+                    "get_object",
+                    Params={"Bucket": self.bucket, "Key": key},
+                    ExpiresIn=ttl_seconds,
+                )
+        except Exception as exc:
+            raise StorageBackendError(f"presign failed: {exc}") from exc
+
+
+def _is_not_found(exc: Exception) -> bool:
+    """Detect a 404 from botocore's heterogeneous error shapes."""
+    response = getattr(exc, "response", None)
+    if isinstance(response, dict):
+        code = response.get("Error", {}).get("Code")
+        if code in {"NoSuchKey", "404", "NotFound"}:
+            return True
+    return getattr(exc, "__class__", type(exc)).__name__ in {
+        "NoSuchKey",
+        "ClientError",
+    } and "404" in str(exc)
+
+
+@register_backend(constants.BackendId.S3)
+def _build(settings: FileStorageSettings) -> S3Backend:
+    if not settings.s3_bucket or not settings.s3_region:
+        raise ConfigurationError("S3 backend requires s3_bucket and s3_region.")
+    client_kwargs: dict[str, Any] = {"region_name": settings.s3_region}
+    if settings.s3_endpoint_url:
+        client_kwargs["endpoint_url"] = settings.s3_endpoint_url
+    if settings.s3_access_key_id and settings.s3_secret_access_key:
+        client_kwargs["aws_access_key_id"] = settings.s3_access_key_id
+        client_kwargs["aws_secret_access_key"] = settings.s3_secret_access_key
+    return S3Backend(
+        bucket=settings.s3_bucket,
+        region=settings.s3_region,
+        client_kwargs=client_kwargs,
+    )

file_storage/constants.py

@@ -0,0 +1,107 @@
+"""Single source of truth for every literal in the file_storage module.
+
+Permissions, event topics, route prefixes, env-var prefix, page names, table
+names, error codes, default config values — all live here. Other files in the
+module import from this one rather than embedding string literals, so renames
+stay localised and `rg` can prove there are no magic strings outside of this
+file.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# ── Module identity ──────────────────────────────────────────────────
+# ``MODULE_NAME`` is the snake_case package name; ``MODULE_PASCAL`` matches the
+# Inertia page-prefix convention (PascalCase of the module dir). ``meta.name``
+# uses ``MODULE_PASCAL`` so the diagnostic code SM003 lines up against
+# ``FileStorage/Browse.tsx``. ``MODULE_DISPLAY_NAME`` is the user-visible label
+# (menu, permission group) — keep it free-form.
+MODULE_NAME: Final = "file_storage"
+MODULE_PASCAL: Final = "FileStorage"
+MODULE_DISPLAY_NAME: Final = "Files"
+
+# ── Configuration ────────────────────────────────────────────────────
+ENV_PREFIX: Final = "SM_FILE_STORAGE_"
+
+# ── Routing ──────────────────────────────────────────────────────────
+ROUTE_PREFIX_API: Final = "/api/file-storage"
+ROUTE_PREFIX_VIEW: Final = "/file-storage"
+
+# REST sub-paths (joined to ROUTE_PREFIX_API by the router)
+PATH_UPLOAD: Final = "/upload"
+PATH_FILES: Final = "/files"
+PATH_FILE_BY_ID: Final = "/files/{file_id}"
+PATH_FILE_DOWNLOAD: Final = "/files/{file_id}/download"
+
+# ── Inertia page names ───────────────────────────────────────────────
+PAGE_BROWSE: Final = "FileStorage/Browse"
+
+# ── Database ─────────────────────────────────────────────────────────
+SCHEMA_NAME: Final = "file_storage"
+TABLE_STORED_FILE: Final = "file_storage_stored_file"
+
+# ── i18n ─────────────────────────────────────────────────────────────
+LOCALE_NAMESPACE: Final = MODULE_NAME
+
+
+class BackendId:
+    """Stable identifiers for built-in storage providers.
+
+    Third-party providers register themselves under any string id, but the
+    built-ins are referenced from settings, the model, and tests, so they
+    deserve named constants.
+    """
+
+    FILESYSTEM: Final = "filesystem"
+    S3: Final = "s3"
+
+
+class Permission:
+    UPLOAD: Final = "file_storage.upload"
+    DOWNLOAD: Final = "file_storage.download"
+    DELETE: Final = "file_storage.delete"
+    MANAGE: Final = "file_storage.manage"
+
+
+class Event:
+    FILE_UPLOADED: Final = "file_storage.file.uploaded"
+    FILE_DELETED: Final = "file_storage.file.deleted"
+
+
+class FeatureFlag:
+    PUBLIC_UPLOADS: Final = "file_storage.public_uploads"
+
+
+class ErrorCode:
+    """Machine-readable codes returned in 4xx response bodies."""
+
+    TOO_LARGE: Final = "file_storage.too_large"
+    BAD_TYPE: Final = "file_storage.bad_type"
+    NOT_FOUND: Final = "file_storage.not_found"
+    BACKEND_ERROR: Final = "file_storage.backend_error"
+
+
+class I18nKey:
+    """Translator keys (full dotted paths). Mirror locales/en.json shape."""
+
+    ERR_NOT_FOUND: Final = "file_storage.errors.not_found"
+    ERR_TOO_LARGE: Final = "file_storage.errors.too_large"
+    ERR_BAD_TYPE: Final = "file_storage.errors.bad_type"
+    ERR_BACKEND: Final = "file_storage.errors.backend_error"
+
+
+# ── Defaults ─────────────────────────────────────────────────────────
+DEFAULT_BACKEND: Final = BackendId.FILESYSTEM
+DEFAULT_FS_ROOT: Final = "./uploads"
+DEFAULT_MAX_FILE_SIZE_BYTES: Final = 100 * 1024 * 1024  # 100 MB
+DEFAULT_PRESIGN_TTL_SECONDS: Final = 300  # 5 minutes
+DEFAULT_CHUNK_SIZE: Final = 64 * 1024  # 64 KB
+SPOOL_MAX_SIZE_BYTES: Final = 10 * 1024 * 1024  # 10 MB before disk-spill
+
+# ── Menu ─────────────────────────────────────────────────────────────
+MENU_ICON: Final = "files"
+MENU_ORDER: Final = 40
+MENU_ROLES: Final = ("admin",)
+ADMIN_ROLE: Final = "admin"
+USER_ROLE: Final = "user"

file_storage/contracts/__init__.py

@@ -0,0 +1,25 @@
+"""file_storage contracts — public interface for other modules."""
+
+from file_storage.contracts.events import FileDeleted, FileUploaded
+from file_storage.contracts.schemas import StoredFileListOut, StoredFileOut
+from file_storage.contracts.service import (
+    ConfigurationError,
+    NotSupportedError,
+    StorageBackend,
+    StorageBackendError,
+    StorageError,
+    StorageNotFoundError,
+)
+
+__all__ = [
+    "ConfigurationError",
+    "FileDeleted",
+    "FileUploaded",
+    "NotSupportedError",
+    "StorageBackend",
+    "StorageBackendError",
+    "StorageError",
+    "StorageNotFoundError",
+    "StoredFileListOut",
+    "StoredFileOut",
+]

file_storage/contracts/events.py

@@ -0,0 +1,23 @@
+"""file_storage domain events."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class FileUploaded(Event):
+    file_id: uuid.UUID
+    key: str
+    backend: str
+    size_bytes: int
+    uploaded_by: str | None
+
+
+@dataclass
+class FileDeleted(Event):
+    file_id: uuid.UUID
+    key: str

file_storage/contracts/schemas.py

@@ -0,0 +1,37 @@
+"""SQLModel DTOs for the file_storage module."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import ConfigDict
+from sqlmodel import Field, SQLModel
+
+
+class StoredFileOut(SQLModel):
+    """Metadata returned for a stored file."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    key: str
+    filename: str
+    content_type: str
+    size_bytes: int
+    backend: str
+    checksum_sha256: str
+    uploaded_by: str | None = Field(
+        default=None,
+        description="User id from AuditMixin.created_by — populated by the audit listener.",
+    )
+    created_at: datetime | None = None
+
+
+class StoredFileListOut(SQLModel):
+    """Paginated list response."""
+
+    items: list[StoredFileOut]
+    total: int
+    page: int
+    per_page: int

file_storage/contracts/service.py

@@ -0,0 +1,82 @@
+"""Storage backend contract — extension point for new providers.
+
+A storage provider is anything that satisfies :class:`StorageBackend`. Adding
+a new provider (Azure Blob, GCS, R2 with custom auth, in-memory for tests)
+means writing one module that implements this Protocol and self-registers via
+:func:`file_storage.backends.register_backend`.
+
+The Protocol is deliberately narrow: ``put``, ``get``, ``delete``, ``exists``,
+plus capability flags so the service layer can dispatch (e.g. presigned-URL
+download vs proxied stream) without inspecting backend identity.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+
+class StorageError(Exception):
+    """Base class for all storage backend errors."""
+
+
+class StorageNotFoundError(StorageError):
+    """Raised when an object key does not exist in the backend."""
+
+
+class StorageBackendError(StorageError):
+    """Raised when the backend itself fails (network, IO, auth)."""
+
+
+class NotSupportedError(StorageError):
+    """Raised when a backend does not implement an optional capability."""
+
+
+class ConfigurationError(StorageError):
+    """Raised at backend construction when required config is missing."""
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    """Async object storage abstraction.
+
+    Implementations must be safe to share across requests — they're held as
+    a singleton on ``app.state.file_storage.backend``.
+    """
+
+    backend_id: str
+    """Stable identifier matching the registry key (e.g. ``"filesystem"``)."""
+
+    supports_presigned_url: bool
+    """Whether :meth:`presigned_get_url` returns a usable URL.
+
+    The download endpoint reads this flag to choose between proxying bytes
+    and issuing a 302 redirect — no `if backend == "s3"` branching.
+    """
+
+    async def put(
+        self,
+        key: str,
+        stream: AsyncIterator[bytes],
+        *,
+        content_type: str,
+        size: int,
+    ) -> None:
+        """Persist ``stream`` under ``key``. ``size`` is the total byte count."""
+
+    async def get(self, key: str) -> AsyncIterator[bytes]:
+        """Yield the object's bytes in chunks. Raises :class:`StorageNotFoundError`."""
+
+    async def delete(self, key: str) -> None:
+        """Remove the object at ``key``. No-op if absent."""
+
+    async def exists(self, key: str) -> bool:
+        """Return whether an object exists at ``key``."""
+
+    async def presigned_get_url(self, key: str, ttl_seconds: int) -> str:
+        """Return a short-lived URL the client can fetch directly.
+
+        Implementations without presigned-URL support must raise
+        :class:`NotSupportedError`. The endpoint will not call this on
+        backends with ``supports_presigned_url=False``.
+        """

file_storage/deps.py

@@ -0,0 +1,26 @@
+"""FastAPI dependencies for the file_storage module."""
+
+from __future__ import annotations
+
+from fastapi import Depends, Request
+from simple_module_core.events import EventBus
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from file_storage.service import FileStorageService
+from file_storage.services import FileStorageServices
+
+
+def get_file_storage_services(request: Request) -> FileStorageServices:
+    return request.app.state.file_storage
+
+
+async def get_file_storage_service(
+    db: AsyncSession = Depends(get_db),
+    services: FileStorageServices = Depends(get_file_storage_services),
+) -> FileStorageService:
+    return FileStorageService(db, services.backend, services.settings)
+
+
+def get_event_bus(request: Request) -> EventBus:
+    return request.app.state.sm.event_bus