sonnet-storage 0.1.0__tar.gz

sonnet_storage-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: sonnet-storage
+Version: 0.1.0
+Summary: Virtual file storage backed by PostgreSQL for sonnet-server applications
+Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
+License-Expression: Apache-2.0
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: sonnet-server>=0.1.12
+Requires-Dist: universal-pathlib>=0.3.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# sonnet-storage
+
+Virtual file storage backed by PostgreSQL for sonnet-server applications.
+
+Provides a [UPath](https://github.com/fsspec/universal_pathlib)-compatible
+filesystem abstraction over a database table. Consumers use standard
+pathlib operations (`read_text()`, `write_text()`, `iterdir()`, etc.)
+and the backend (local filesystem or database) is transparent.
+
+## Quick Start
+
+```python
+from sonnet_storage import get_storage_root, register_protocol
+
+# Register the db:// protocol (once at startup)
+register_protocol()
+
+# Use like pathlib
+root = get_storage_root()
+rules = root / "rules"
+for f in rules.iterdir():
+    content = f.read_text()
+```
+
+## Features
+
+- Text, JSON (native JSONB), and binary content storage
+- Soft delete with recovery
+- Versioning (monotonic counter per file)
+- Seeding from local directories / package data
+- Configurable UPath protocol name (default: `db://`)
+- Pre-built REST router factory
+- Optional `StorageExtension` for auto-registration
+
+## Database
+
+PostgreSQL only. See [docs/data-model.md](docs/data-model.md) for the
+complete schema reference. Consumers own their Alembic migrations --
+see [ADR-0002](../../docs/adr/0002-no-shipped-migrations.md).
+
+## Documentation
+
+- [Design document](docs/design/virtual-file-storage.md)
+- [Data model reference](docs/data-model.md)

sonnet_storage-0.1.0/README.md

@@ -0,0 +1,44 @@
+# sonnet-storage
+
+Virtual file storage backed by PostgreSQL for sonnet-server applications.
+
+Provides a [UPath](https://github.com/fsspec/universal_pathlib)-compatible
+filesystem abstraction over a database table. Consumers use standard
+pathlib operations (`read_text()`, `write_text()`, `iterdir()`, etc.)
+and the backend (local filesystem or database) is transparent.
+
+## Quick Start
+
+```python
+from sonnet_storage import get_storage_root, register_protocol
+
+# Register the db:// protocol (once at startup)
+register_protocol()
+
+# Use like pathlib
+root = get_storage_root()
+rules = root / "rules"
+for f in rules.iterdir():
+    content = f.read_text()
+```
+
+## Features
+
+- Text, JSON (native JSONB), and binary content storage
+- Soft delete with recovery
+- Versioning (monotonic counter per file)
+- Seeding from local directories / package data
+- Configurable UPath protocol name (default: `db://`)
+- Pre-built REST router factory
+- Optional `StorageExtension` for auto-registration
+
+## Database
+
+PostgreSQL only. See [docs/data-model.md](docs/data-model.md) for the
+complete schema reference. Consumers own their Alembic migrations --
+see [ADR-0002](../../docs/adr/0002-no-shipped-migrations.md).
+
+## Documentation
+
+- [Design document](docs/design/virtual-file-storage.md)
+- [Data model reference](docs/data-model.md)

sonnet_storage-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sonnet-storage"
+version = "0.1.0"
+authors = [
+    { name = "Wolfgang Miller", email = "wolfgang.miller@petrarca-labs.com" },
+]
+description = "Virtual file storage backed by PostgreSQL for sonnet-server applications"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.14,<4.0"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "sonnet-server>=0.1.12",
+    "universal-pathlib>=0.3.10",
+    "loguru>=0.7.3",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.3.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: marks tests as unit tests (default)",
+    "integration: marks tests as integration tests",
+]
+testpaths = ["tests"]
+addopts = [
+    "-m unit",
+    "--strict-markers",
+]
+asyncio_mode = "auto"

sonnet_storage-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sonnet_storage-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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 []