simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/media_service.py

@@ -0,0 +1,222 @@
+"""Storage + DB operations for uploaded media assets.
+
+Files live on the local filesystem under
+:attr:`PagebuilderSettings.media_root` and are served via a StaticFiles
+mount registered in :meth:`PagebuilderModule.on_startup`. The DB row
+holds the sanitized filename, original name, content-type, byte size,
+intrinsic dimensions, and a ``variants`` map of server-generated
+thumbnails. Public URLs are derived as
+``f"{settings.media_url_prefix}/{filename}"``.
+
+Filename sanitising, content sniffing, and thumbnail generation live in
+:mod:`pagebuilder.media_images`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from pathlib import Path
+
+from fastapi import HTTPException, UploadFile
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from pagebuilder import media_queries
+from pagebuilder.contracts.schemas import MediaAssetRead, MediaAssetVariant
+from pagebuilder.media_images import (
+    CONTENT_TYPE_EXTENSIONS,
+    SNIFF_BYTES,
+    normalize_folder,
+    process_image,
+    safe_extension,
+    sniff_content_type,
+)
+from pagebuilder.models import MediaAsset
+from pagebuilder.settings import PagebuilderSettings
+
+_DEFAULT_PAGE_SIZE = 60
+_MAX_PAGE_SIZE = 200
+
+# Re-exported: callers reach for these through the service module.
+__all__ = ["MediaService", "normalize_folder"]
+
+
+class MediaService:
+    def __init__(self, db: AsyncSession, settings: PagebuilderSettings) -> None:
+        self.db = db
+        self.settings = settings
+
+    @property
+    def storage_root(self) -> Path:
+        return Path(self.settings.media_root).resolve()
+
+    def url_for(self, filename: str) -> str:
+        return f"{self.settings.media_url_prefix.rstrip('/')}/{filename}"
+
+    def to_read(self, asset: MediaAsset) -> MediaAssetRead:
+        variants = {
+            key: MediaAssetVariant(
+                filename=meta["filename"],
+                url=self.url_for(meta["filename"]),
+                content_type=meta["content_type"],
+                width=meta["width"],
+                height=meta.get("height"),
+                size_bytes=meta.get("size_bytes", 0),
+            )
+            for key, meta in (asset.variants or {}).items()
+        }
+        return MediaAssetRead(
+            id=asset.id or 0,
+            filename=asset.filename,
+            original_filename=asset.original_filename,
+            content_type=asset.content_type,
+            size_bytes=asset.size_bytes,
+            url=self.url_for(asset.filename),
+            width=asset.width,
+            height=asset.height,
+            folder=asset.folder,
+            variants=variants,
+            created_at=asset.created_at,
+        )
+
+    async def count_assets(self, **filters) -> int:
+        """Total rows matching *filters* — pairs with offset paging."""
+        return await media_queries.count_assets(self.db, **filters)
+
+    async def list_assets(
+        self,
+        *,
+        cursor: int | None = None,
+        offset: int | None = None,
+        limit: int = _DEFAULT_PAGE_SIZE,
+        **filters,
+    ) -> tuple[list[MediaAsset], int | None]:
+        """One page of assets newest-first, plus the next cursor.
+
+        See :func:`pagebuilder.media_queries.list_assets` for the two paging
+        modes; the image-picker gallery uses the offset one.
+        """
+        return await media_queries.list_assets(
+            self.db, cursor=cursor, offset=offset, limit=limit, **filters
+        )
+
+    async def list_folders(self) -> list[str]:
+        """Return every distinct non-empty folder name, sorted."""
+        result = await self.db.execute(
+            select(MediaAsset.folder)
+            .where(MediaAsset.folder.is_not(None))
+            .distinct()
+        )
+        return sorted({row for row in result.scalars().all() if row})
+
+    async def get_asset(self, asset_id: int) -> MediaAsset:
+        asset = await self.db.get(MediaAsset, asset_id)
+        if asset is None:
+            raise HTTPException(status_code=404, detail="Asset not found")
+        return asset
+
+    async def upload(
+        self,
+        upload: UploadFile,
+        *,
+        folder: str | None = None,
+    ) -> MediaAsset:
+        folder_value = normalize_folder(folder)
+        original = upload.filename or "upload"
+        declared = upload.content_type or "application/octet-stream"
+        allowed = self.settings.media_allowed_content_types
+        if declared not in allowed:
+            raise HTTPException(
+                status_code=415,
+                detail=f"Content-type {declared!r} is not allowed",
+            )
+
+        head = await upload.read(SNIFF_BYTES)
+        sniffed = sniff_content_type(head)
+        if sniffed is None or sniffed not in allowed:
+            raise HTTPException(
+                status_code=415,
+                detail="File contents do not match an allowed image format",
+            )
+        if sniffed != declared:
+            raise HTTPException(
+                status_code=415,
+                detail=(
+                    f"Declared content-type {declared!r} does not match "
+                    f"sniffed type {sniffed!r}"
+                ),
+            )
+        content_type = sniffed
+
+        # Pin the on-disk extension to the sniffed type so we never store
+        # a JPEG under a `.png` name (StaticFiles serves the mime based
+        # on the extension).
+        ext = CONTENT_TYPE_EXTENSIONS.get(content_type) or safe_extension(original)
+        filename = f"{uuid.uuid4().hex}{ext}"
+
+        root = self.storage_root
+        root.mkdir(parents=True, exist_ok=True)
+        target = root / filename
+
+        size = len(head)
+        max_bytes = self.settings.media_max_bytes
+        if size > max_bytes:
+            raise HTTPException(
+                status_code=413,
+                detail=f"File exceeds {max_bytes} bytes",
+            )
+        chunk_size = 64 * 1024
+        with target.open("wb") as fh:
+            fh.write(head)
+            while True:
+                chunk = await upload.read(chunk_size)
+                if not chunk:
+                    break
+                size += len(chunk)
+                if size > max_bytes:
+                    fh.close()
+                    target.unlink(missing_ok=True)
+                    raise HTTPException(
+                        status_code=413,
+                        detail=f"File exceeds {max_bytes} bytes",
+                    )
+                fh.write(chunk)
+
+        # Pillow's decode + webp encode are sync and CPU-bound — running
+        # them on the event loop blocks other concurrent uploads. The
+        # thread offload is essentially free for a single request and
+        # turns parallel uploads back into parallel work.
+        width, height, variants = await asyncio.to_thread(
+            process_image,
+            target,
+            thumbnail_widths=self.settings.media_thumbnail_widths,
+            webp_quality=self.settings.media_webp_quality,
+        )
+
+        asset = MediaAsset(
+            filename=filename,
+            original_filename=original,
+            content_type=content_type,
+            size_bytes=size,
+            width=width,
+            height=height,
+            folder=folder_value,
+            variants=variants,
+        )
+        self.db.add(asset)
+        await self.db.flush()
+        await self.db.refresh(asset)
+        return asset
+
+    async def delete(self, asset_id: int) -> None:
+        asset = await self.get_asset(asset_id)
+        root = self.storage_root
+        (root / asset.filename).unlink(missing_ok=True)
+        for meta in (asset.variants or {}).values():
+            if isinstance(meta, dict):
+                name = meta.get("filename")
+                if name:
+                    (root / name).unlink(missing_ok=True)
+        await self.db.delete(asset)
+        await self.db.flush()

pagebuilder/models.py

@@ -0,0 +1,209 @@
+"""SQLModel tables for the pagebuilder module.
+
+The page document itself is stored as opaque JSON; only the slug,
+title, status, SEO fields, and timestamps are queried. ``draft_data`` is
+what the editor saves; ``published_data`` is the immutable snapshot
+served at ``/p/{slug}`` until a new publish overwrites it. Each publish
+also appends a row to ``PageRevision`` so the history is recoverable.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from typing import Any
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import JSON, Column, DateTime
+from sqlalchemy import Enum as SAEnum
+from sqlmodel import Field
+
+Base = create_module_base("pagebuilder")
+
+
+# Deliberately (str, Enum) rather than enum.StrEnum: these values are persisted
+# and serialised, and StrEnum changes what str()/f-strings produce for a member
+# ("draft" instead of "PageStatus.DRAFT"). Switching is a data-format change,
+# not a style fix.
+class PageStatus(str, enum.Enum):  # noqa: UP042
+    DRAFT = "draft"
+    SUBMITTED_FOR_REVIEW = "submitted_for_review"
+    PUBLISHED = "published"
+
+
+class RevisionEvent(str, enum.Enum):  # noqa: UP042  — see PageStatus above
+    """Status-transition kind recorded in :class:`PageRevision`.
+
+    ``PUBLISH`` and ``APPROVE`` rows snapshot the bytes served at
+    ``/p/{slug}`` (approve also publishes), so the editor's
+    Restore-as-draft affordance treats them identically. ``SUBMIT`` /
+    ``REJECT`` / ``UNPUBLISH`` are audit-only — their ``data`` is the
+    current draft, kept for forensics.
+    """
+
+    PUBLISH = "publish"
+    UNPUBLISH = "unpublish"
+    SUBMIT = "submit"
+    APPROVE = "approve"
+    REJECT = "reject"
+
+
+class Page(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """A page composed in the visual editor."""
+
+    __tablename__ = "pagebuilder_pages"
+
+    id: int | None = Field(default=None, primary_key=True)
+    slug: str = Field(max_length=200, unique=True, index=True)
+    title: str = Field(max_length=300)
+    meta_description: str | None = Field(default=None, max_length=500)
+    og_image: str | None = Field(default=None, max_length=500)
+    status: PageStatus = Field(
+        default=PageStatus.DRAFT,
+        sa_column=Column(
+            SAEnum(PageStatus, name="pagebuilder_page_status"),
+            nullable=False,
+            index=True,
+        ),
+    )
+    draft_data: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )
+    published_data: dict[str, Any] | None = Field(
+        default=None,
+        sa_column=Column(JSON, nullable=True),
+    )
+    canonical_url: str | None = Field(default=None, max_length=500)
+    """Override the canonical URL emitted on the public page.
+
+    Defaults to the page's own absolute URL (built from
+    ``PagebuilderSettings.public_base_url`` + ``public_route_prefix`` +
+    ``slug``) when unset, so the most common case requires no input.
+    """
+    index_in_search: bool = Field(default=True)
+    """When ``False``, emit ``<meta name="robots" content="noindex,nofollow">``
+    on the public page and exclude it from the sitemap."""
+    json_ld: dict[str, Any] | None = Field(
+        default=None,
+        sa_column=Column(JSON, nullable=True),
+    )
+    """Optional schema.org JSON-LD document rendered inside a
+    ``<script type="application/ld+json">`` tag on the public page."""
+    rejection_note: str | None = Field(default=None, max_length=2000)
+    """Latest approver-supplied reason for sending a submission back to draft.
+
+    Cleared on every ``submit`` / ``approve`` / ``publish`` so a stale
+    note doesn't shadow a new round.
+    """
+    publish_at: datetime | None = Field(
+        default=None,
+        sa_column=Column(DateTime(timezone=True), nullable=True),
+    )
+    """When set, the scheduler flips a ``DRAFT`` page to ``PUBLISHED`` at
+    or after this UTC instant. Cleared on every flip (auto or manual) so
+    the schedule is single-shot."""
+    unpublish_at: datetime | None = Field(
+        default=None,
+        sa_column=Column(DateTime(timezone=True), nullable=True),
+    )
+    """When set, the scheduler flips a ``PUBLISHED`` page back to draft at
+    or after this UTC instant. Independent of ``publish_at``; both can be
+    set so a draft goes live on Monday and takes itself down on Friday."""
+
+    @property
+    def has_published(self) -> bool:
+        return self.published_data is not None
+
+
+class PageRevision(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Append-only audit row written on every status transition.
+
+    ``Page.rejection_note`` mirrors the most recent ``REJECT`` row's
+    ``note`` so the editor banner avoids a join.
+    """
+
+    __tablename__ = "pagebuilder_page_revisions"
+
+    id: int | None = Field(default=None, primary_key=True)
+    page_id: int = Field(foreign_key="pagebuilder_pages.id", index=True)
+    title: str = Field(max_length=300)
+    meta_description: str | None = Field(default=None, max_length=500)
+    og_image: str | None = Field(default=None, max_length=500)
+    data: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )
+    event: RevisionEvent = Field(
+        default=RevisionEvent.PUBLISH,
+        sa_column=Column(
+            SAEnum(RevisionEvent, name="pagebuilder_revision_event"),
+            nullable=False,
+            index=True,
+            server_default=RevisionEvent.PUBLISH.value,
+        ),
+    )
+    note: str | None = Field(default=None, max_length=2000)
+
+
+class Layout(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Singleton — :meth:`LayoutService.get` creates the row on first read."""
+
+    __tablename__ = "pagebuilder_layout"
+
+    id: int | None = Field(default=None, primary_key=True)
+    header_data: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )
+    footer_data: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )
+
+
+class LayoutRevision(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    __tablename__ = "pagebuilder_layout_revisions"
+
+    id: int | None = Field(default=None, primary_key=True)
+    layout_id: int = Field(foreign_key="pagebuilder_layout.id", index=True)
+    header_data: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )
+    footer_data: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )
+    note: str | None = Field(default=None, max_length=2000)
+
+
+class MediaAsset(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """An uploaded media file stored on local disk.
+
+    The bytes themselves live under :attr:`PagebuilderSettings.media_root`;
+    this row holds the metadata + sanitized filename used to build the
+    public URL.
+
+    ``width`` / ``height`` are populated for raster images so the Image
+    block can emit them on ``<img>`` and avoid layout shift; ``variants``
+    lists server-generated thumbnails / webp transcodes keyed by a stable
+    label (e.g. ``"w640"``, ``"webp"``) — each entry stores at minimum
+    ``{filename, width, height, content_type}``.
+    """
+
+    __tablename__ = "pagebuilder_media"
+
+    id: int | None = Field(default=None, primary_key=True)
+    filename: str = Field(max_length=300, unique=True, index=True)
+    original_filename: str = Field(max_length=300)
+    content_type: str = Field(max_length=120)
+    size_bytes: int = Field(default=0)
+    width: int | None = Field(default=None)
+    height: int | None = Field(default=None)
+    folder: str | None = Field(default=None, max_length=300, index=True)
+    variants: dict[str, Any] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON, nullable=False, default=dict),
+    )