sonnet-storage 0.1.0__py3-none-any.whl

sonnet_storage/__init__.py

@@ -0,0 +1,46 @@
+"""sonnet-storage -- Virtual file storage backed by PostgreSQL.
+
+Provides a UPath-compatible filesystem abstraction over a PostgreSQL
+table. Consumers use standard pathlib operations (read_text, write_text,
+iterdir, glob, etc.) and the backend is transparent.
+
+Public API
+----------
+
+Models:
+    FileStorage         SQLModel table class (for Alembic env.py import)
+
+Providers:
+    DBPath              UPath subclass for database-backed storage
+                        Extra method: undelete() -- recover soft-deleted file
+    get_storage_root    Factory: returns UPath for configured backend
+    get_storage_root_db Factory: always returns db:// UPath
+    register_protocol   Register custom protocol name (default: "db")
+
+Extension:
+    StorageExtension    Optional auto-registration + REST router mount
+
+API:
+    create_storage_router   Pre-built FastAPI router factory
+
+Seed:
+    seed_from_directory     Copy local files into database storage
+    SeedResult              Result dataclass for seed operations
+"""
+
+from .extension import StorageExtension
+from .models import FileStorage
+from .providers import get_storage_root, get_storage_root_db, register_protocol
+from .providers.db_path import DBPath
+from .seed import SeedResult, seed_from_directory
+
+__all__ = [
+    "DBPath",
+    "FileStorage",
+    "SeedResult",
+    "StorageExtension",
+    "get_storage_root",
+    "get_storage_root_db",
+    "register_protocol",
+    "seed_from_directory",
+]

sonnet_storage/api/__init__.py

@@ -0,0 +1,5 @@
+"""REST API for virtual file storage."""
+
+from .files import create_storage_router
+
+__all__ = ["create_storage_router"]

sonnet_storage/api/files.py

@@ -0,0 +1,131 @@
+"""File storage REST endpoints.
+
+Provides a router factory that consumers mount at their preferred prefix.
+Uses the ambient DB session via db_router().
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Body, HTTPException, Query
+from loguru import logger
+from pydantic import BaseModel
+
+from sonnet_storage.providers import get_storage_root
+
+
+class FileInfo(BaseModel):
+    """File information returned by list endpoints."""
+
+    path: str
+    name: str
+    is_file: bool
+    size: int | None = None
+
+
+class StorageInfo(BaseModel):
+    """Storage backend information."""
+
+    provider: str
+    root: str
+
+
+def create_storage_router(prefix: str = "/storage", tags: list[str] | None = None) -> APIRouter:
+    """Create a FastAPI router for file storage operations.
+
+    Args:
+        prefix: URL prefix for all endpoints (default: "/storage").
+        tags: OpenAPI tags (default: ["storage"]).
+
+    Returns:
+        A configured APIRouter ready to be included in the application.
+    """
+    from sonnet_server.api.dependencies import db_router
+
+    router = db_router(prefix=prefix, tags=tags or ["storage"])
+
+    router.add_api_route("/info", _get_storage_info, methods=["GET"], response_model=StorageInfo)
+    router.add_api_route("/files", _list_files, methods=["GET"], response_model=list[FileInfo])
+    router.add_api_route("/files/{filepath:path}", _get_file, methods=["GET"])
+    router.add_api_route("/files/{filepath:path}", _put_file, methods=["PUT"])
+    router.add_api_route("/files/{filepath:path}", _delete_file, methods=["DELETE"])
+
+    return router
+
+
+def _get_storage_info() -> StorageInfo:
+    """Get storage backend information."""
+    root = get_storage_root()
+    root_str = str(root)
+    if root_str.startswith("file://") or root_str.startswith("/"):
+        provider = "file"
+    else:
+        provider = root.protocol if hasattr(root, "protocol") else "unknown"
+    return StorageInfo(provider=provider, root=root_str)
+
+
+def _list_files(path: str = Query("/", description="Directory path to list")) -> list[FileInfo]:
+    """List files in a storage directory."""
+    logger.debug("Listing storage files (path={})", path)
+    root = get_storage_root()
+    target = root / path.lstrip("/") if path != "/" else root
+
+    try:
+        if not target.exists():
+            raise HTTPException(status_code=404, detail=f"Path not found: {path}")
+        items = list(target.iterdir())
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+    result = []
+    # Sort: directories first, then files alphabetically
+    for item in sorted(items, key=lambda x: (not x.is_dir(), str(x))):
+        rel_path = "/" + str(item).replace(str(root), "").lstrip("/")
+        try:
+            size = item.stat().st_size if item.is_file() else None
+        except OSError, FileNotFoundError:
+            size = None
+        result.append(FileInfo(path=rel_path, name=item.name, is_file=item.is_file(), size=size))
+    return result
+
+
+def _get_file(filepath: str) -> dict:
+    """Get file content by path."""
+    root = get_storage_root()
+    target = root / filepath
+    try:
+        if not target.is_file():
+            raise HTTPException(status_code=404, detail=f"File not found: /{filepath}")
+        content = target.read_text()
+    except HTTPException:
+        raise
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=f"File not found: /{filepath}") from e
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {"path": f"/{filepath}", "name": target.name, "content": content}
+
+
+def _put_file(filepath: str, content: str = Body(..., media_type="text/plain")) -> dict:
+    """Create or update a text file."""
+    root = get_storage_root()
+    target = root / filepath
+    try:
+        target.write_text(content)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {"path": f"/{filepath}", "name": target.name, "status": "ok"}
+
+
+def _delete_file(filepath: str) -> dict:
+    """Soft-delete a file."""
+    root = get_storage_root()
+    target = root / filepath
+    try:
+        target.unlink()
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=f"File not found: /{filepath}") from e
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {"path": f"/{filepath}", "status": "deleted"}

sonnet_storage/cli/__init__.py

@@ -0,0 +1,20 @@
+"""sonnet-storage CLI -- file storage management commands.
+
+Consumer usage:
+
+    from sonnet_storage.cli import files as storage_cli
+
+    files_app = typer.Typer(help="File storage management")
+
+    @files_app.callback()
+    def _files_setup():
+        init_settings(log_level="WARNING")
+        register_protocol("db")
+
+    storage_cli.register(files_app)
+    main_app.add_typer(files_app, name="files")
+"""
+
+from . import files
+
+__all__ = ["files"]

sonnet_storage/cli/files.py

@@ -0,0 +1,283 @@
+"""File storage CLI commands -- ls, cat, rm, tree, purge.
+
+Provides command functions that consumers register on their own Typer app.
+The consumer is responsible for settings initialization and protocol
+registration in their Typer callback.
+
+Example (consumer's main.py):
+
+    from sonnet_storage.cli import files as storage_cli
+
+    files_app = typer.Typer(help="File storage management")
+
+    @files_app.callback()
+    def _files_setup():
+        init_settings(log_level="INFO")
+        register_protocol("db")
+
+    storage_cli.register(files_app)
+    main_app.add_typer(files_app, name="files")
+
+Transaction contract: each command opens a borrow_db_session().
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.tree import Tree
+
+console = Console()
+
+
+def _get_root():
+    from sonnet_storage.providers import get_storage_root_db
+
+    return get_storage_root_db()
+
+
+def register(app: typer.Typer) -> None:
+    """Register all storage CLI commands on the given Typer app."""
+    app.command(name="ls")(_ls)
+    app.command(name="cat")(_cat)
+    app.command(name="rm")(_rm)
+    app.command(name="tree")(_tree)
+    app.command(name="purge")(_purge)
+
+
+# ---------------------------------------------------------------------------
+# ls
+# ---------------------------------------------------------------------------
+
+
+def _ls(
+    path: str = typer.Argument("/", help="Path to list"),
+    recursive: bool = typer.Option(False, "--recursive", "-r", help="List recursively"),
+    long_format: bool = typer.Option(False, "--long", "-l", help="Show file sizes"),
+) -> None:
+    """List files in storage."""
+    from sonnet_server.database import borrow_db_session
+
+    with borrow_db_session():
+        root = _get_root()
+        target = root / path.lstrip("/") if path != "/" else root
+
+        console.print(f"[bold]Path:[/bold] {path}\n")
+
+        try:
+            items = list(target.rglob("*")) if recursive else list(target.iterdir())
+        except (OSError, FileNotFoundError) as e:
+            console.print(f"[red]Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+        if not items:
+            console.print("[yellow]No files found.[/yellow]")
+            return
+
+        dirs = sorted([i for i in items if i.is_dir()], key=str)
+        files = sorted([i for i in items if i.is_file()], key=str)
+
+        for item in dirs:
+            rel = item._db_path if hasattr(item, "_db_path") else str(item)
+            console.print(f"[blue]{rel.lstrip('/')}/[/blue]")
+
+        for item in files:
+            rel = (item._db_path if hasattr(item, "_db_path") else str(item)).lstrip("/")
+            if long_format:
+                try:
+                    console.print(f"  {item.stat().st_size:>8}  {rel}")
+                except OSError, FileNotFoundError:
+                    console.print(f"  {'?':>8}  {rel}")
+            else:
+                console.print(f"  {rel}")
+
+        dir_word = "directories" if len(dirs) != 1 else "directory"
+        file_word = "files" if len(files) != 1 else "file"
+        console.print(f"\n[dim]{len(dirs)} {dir_word}, {len(files)} {file_word}[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# cat
+# ---------------------------------------------------------------------------
+
+
+def _cat(
+    file_path: str = typer.Argument(..., help="File path to display"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Save to file"),
+) -> None:
+    """Display file content from storage."""
+    from sonnet_server.database import borrow_db_session
+
+    with borrow_db_session():
+        root = _get_root()
+        target = root / file_path.lstrip("/")
+
+        if not target.is_file():
+            console.print(f"[red]File not found: {file_path}[/red]")
+            raise typer.Exit(1)
+
+        try:
+            content = target.read_text()
+        except UnicodeDecodeError:
+            if output:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_bytes(target.read_bytes())
+                console.print(f"[green]Saved binary file to {output}[/green]")
+            else:
+                console.print("[yellow]Binary file -- use --output to save.[/yellow]")
+            return
+        except (OSError, FileNotFoundError) as e:
+            console.print(f"[red]Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(content)
+        console.print(f"[green]Saved to {output}[/green]")
+    else:
+        console.print(content)
+
+
+# ---------------------------------------------------------------------------
+# rm
+# ---------------------------------------------------------------------------
+
+
+def _rm(
+    pattern: str = typer.Argument(..., help="File path or glob pattern"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Soft-delete files from storage."""
+    from sonnet_server.database import borrow_db_session
+
+    with borrow_db_session():
+        root = _get_root()
+        files_to_delete = _find_files(root, pattern)
+
+    if not files_to_delete:
+        console.print(f"[yellow]No files found matching: {pattern}[/yellow]")
+        return
+
+    console.print(f"[yellow]Found {len(files_to_delete)} file(s) to delete:[/yellow]")
+    for f in files_to_delete[:10]:
+        console.print(f"  {f._db_path if hasattr(f, '_db_path') else str(f)}")
+    if len(files_to_delete) > 10:
+        console.print(f"  ... and {len(files_to_delete) - 10} more")
+
+    if not yes and not typer.confirm("\nSoft-delete these files?"):
+        console.print("[yellow]Cancelled.[/yellow]")
+        return
+
+    deleted, errors = 0, []
+    with borrow_db_session():
+        for f in files_to_delete:
+            try:
+                f.unlink()
+                deleted += 1
+            except (OSError, FileNotFoundError) as e:
+                errors.append(str(e))
+
+    console.print(f"[green]Deleted {deleted} file(s).[/green]")
+    for err in errors:
+        logger.warning("Delete error: {}", err)
+
+
+# ---------------------------------------------------------------------------
+# tree
+# ---------------------------------------------------------------------------
+
+
+def _tree(
+    path: str = typer.Argument("/", help="Root path for the tree"),
+) -> None:
+    """Display storage contents as a tree."""
+    from sonnet_server.database import borrow_db_session
+
+    with borrow_db_session():
+        root = _get_root()
+        target = root / path.lstrip("/") if path != "/" else root
+        tree = Tree(f"[bold]{path or '/'}[/bold]")
+
+        try:
+            items = sorted(target.rglob("*"), key=str)
+        except (OSError, FileNotFoundError) as e:
+            console.print(f"[red]Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+        tree_nodes: dict[str, Tree] = {"": tree}
+        for item in items:
+            rel = (item._db_path if hasattr(item, "_db_path") else str(item)).lstrip("/")
+            parts = rel.split("/")
+            for i in range(len(parts)):
+                current = "/".join(parts[: i + 1])
+                parent_key = "/".join(parts[:i])
+                if current not in tree_nodes:
+                    parent_node = tree_nodes.get(parent_key, tree)
+                    if i == len(parts) - 1 and item.is_file():
+                        parent_node.add(parts[i])
+                    else:
+                        tree_nodes[current] = parent_node.add(f"[blue]{parts[i]}/[/blue]")
+
+    console.print(tree)
+
+
+# ---------------------------------------------------------------------------
+# purge
+# ---------------------------------------------------------------------------
+
+
+def _purge(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Permanently hard-delete all soft-deleted files."""
+    from sqlmodel import delete, select
+
+    from sonnet_server.database import borrow_db_session, get_current_session
+    from sonnet_storage.models.db import FileStorage
+
+    with borrow_db_session():
+        session = get_current_session()
+        deleted_files = session.exec(select(FileStorage).where(FileStorage.is_deleted.is_(True))).all()
+
+        if not deleted_files:
+            console.print("[green]No soft-deleted files. Nothing to purge.[/green]")
+            return
+
+        console.print(f"[yellow]Found {len(deleted_files)} soft-deleted file(s):[/yellow]")
+        for f in deleted_files[:10]:
+            console.print(f"  {f.file_path}")
+        if len(deleted_files) > 10:
+            console.print(f"  ... and {len(deleted_files) - 10} more")
+
+        if not yes:
+            console.print("\n[bold red]WARNING: This permanently deletes these files.[/bold red]")
+            if not typer.confirm("Proceed?"):
+                console.print("[yellow]Cancelled.[/yellow]")
+                return
+
+        result = session.exec(delete(FileStorage).where(FileStorage.is_deleted.is_(True)))
+        console.print(f"[green]Purged {result.rowcount} file(s).[/green]")
+        # borrow_db_session() commits on clean exit -- no explicit commit needed.
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_files(root, pattern: str) -> list:
+    """Find files matching path or glob pattern."""
+    if "*" in pattern:
+        base = pattern.rsplit("/", 1)[0] if "/" in pattern else ""
+        glob_pat = pattern.rsplit("/", 1)[-1] if "/" in pattern else pattern
+        search = root / base.lstrip("/") if base else root
+        try:
+            return list(search.glob(glob_pat))
+        except OSError, FileNotFoundError:
+            return []
+    else:
+        target = root / pattern.lstrip("/")
+        return [target] if target.is_file() else []

sonnet_storage/extension.py

@@ -0,0 +1,46 @@
+"""StorageExtension -- optional extension for auto-registration and REST mounting.
+
+Registers the db:// protocol at startup and mounts the file storage
+REST router. Infrastructure extension (no profile) -- always active.
+
+Consumers who prefer manual wiring can skip this extension and call
+register_protocol() + create_storage_router() directly.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from sonnet_server.extensions import Extension
+from sonnet_server.settings import Settings
+
+
+class StorageExtension(Extension):
+    """Virtual file storage extension.
+
+    Registers the UPath protocol and mounts the REST router.
+
+    Args:
+        protocol: UPath protocol scheme (default: "db").
+        router_prefix: URL prefix for REST endpoints (default: "/storage").
+    """
+
+    def __init__(self, protocol: str = "db", router_prefix: str = "/storage"):
+        # protocol must be set before any DBPath instances are created.
+        # Changing it after startup has no effect -- register_protocol() is idempotent.
+        self._protocol = protocol
+        self._prefix = router_prefix
+
+    @property
+    def name(self) -> str:
+        return "storage"
+
+    async def on_startup(self, settings: Settings) -> None:
+        from sonnet_storage.providers import register_protocol
+
+        register_protocol(self._protocol)
+
+    def routers(self) -> list[APIRouter]:
+        from sonnet_storage.api import create_storage_router
+
+        return [create_storage_router(prefix=self._prefix)]

sonnet_storage/models/__init__.py

@@ -0,0 +1,7 @@
+"""Storage models -- database table and API projections."""
+
+from .db import FileStorage
+
+__all__ = [
+    "FileStorage",
+]

sonnet_storage/models/db.py

@@ -0,0 +1,69 @@
+"""FileStorage database model.
+
+Stores arbitrary files (text, JSON, binary) with metadata and versioning.
+Supports path-based organization, soft delete, and content type optimization.
+
+PostgreSQL only. JSON content uses native JSONB for queryability.
+"""
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID, uuid7
+
+import arrow
+from sqlalchemy import ARRAY, JSON, LargeBinary, String
+from sqlmodel import Field, SQLModel
+
+
+def _utcnow():
+    return arrow.utcnow().datetime
+
+
+class FileStorage(SQLModel, table=True):
+    """Virtual file storage backed by PostgreSQL.
+
+    Each row represents a file. Directories are virtual -- inferred from
+    path prefixes. Only one content column is populated per row, based
+    on content_type.
+    """
+
+    __tablename__ = "file_storage"
+
+    # Primary key -- UUID v7 (time-ordered)
+    id: UUID = Field(default_factory=uuid7, primary_key=True)
+
+    # File identification
+    file_path: str = Field(index=True, nullable=False)
+    file_name: str = Field(nullable=False)
+
+    # Content type dispatch -- "text", "json", or "binary"
+    content_type: str = Field(nullable=False)
+
+    # Content storage -- only one populated based on content_type
+    text_content: str | None = Field(default=None)
+    json_content: dict[str, Any] | list | None = Field(default=None, sa_type=JSON)
+    binary_content: bytes | None = Field(default=None, sa_type=LargeBinary)
+
+    # File metadata
+    file_size: int | None = Field(default=None)
+    mime_type: str | None = Field(default=None)
+    content_encoding: str | None = Field(default=None)
+
+    # Classification
+    tags: list[str] = Field(default_factory=list, sa_type=ARRAY(String))
+    namespace: str | None = Field(default=None, index=True)
+    description: str | None = Field(default=None)
+
+    # Soft delete
+    is_deleted: bool = Field(default=False, nullable=False)
+
+    # Versioning -- incremented on every write, no history kept
+    version: int = Field(default=1, nullable=False)
+
+    # Audit timestamps (UTC)
+    created_at: datetime = Field(default_factory=_utcnow, nullable=False)
+    updated_at: datetime = Field(default_factory=_utcnow, nullable=False)
+
+    # Audit users
+    created_by: str | None = Field(default=None)
+    updated_by: str | None = Field(default=None)

sonnet_storage/providers/__init__.py

@@ -0,0 +1,14 @@
+"""UPath providers for database-backed file storage.
+
+Provides DBPath (a UPath subclass) and factory functions for
+transparent backend switching between file:// and db:// storage.
+"""
+
+from .factory import get_storage_root, get_storage_root_db
+from .registry import register_protocol
+
+__all__ = [
+    "get_storage_root",
+    "get_storage_root_db",
+    "register_protocol",
+]