nornweave 0.1.2__py3-none-any.whl

nornweave/storage/gcs.py

@@ -0,0 +1,144 @@
+"""Google Cloud Storage backend for attachments."""
+
+from datetime import timedelta
+from typing import Any, cast
+
+from nornweave.core.storage import AttachmentMetadata, AttachmentStorageBackend, StorageResult
+
+
+class GCSStorage(AttachmentStorageBackend):
+    """Store attachments in Google Cloud Storage.
+
+    Recommended for production deployments on GCP.
+    Uses signed URLs for secure downloads.
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        prefix: str = "attachments",
+        credentials_path: str | None = None,
+        project: str | None = None,
+    ) -> None:
+        """
+        Initialize GCS storage.
+
+        Args:
+            bucket: GCS bucket name
+            prefix: Blob prefix for attachments
+            credentials_path: Path to service account JSON (uses ADC if not set)
+            project: GCP project ID
+        """
+        self.bucket_name = bucket
+        self.prefix = prefix.strip("/")
+        self._credentials_path = credentials_path
+        self._project = project
+        self._client: Any = None
+        self._bucket: Any = None
+
+    @property
+    def backend_name(self) -> str:
+        return "gcs"
+
+    def _get_client(self) -> tuple[Any, Any]:
+        """Get or create GCS client and bucket (lazy initialization)."""
+        if self._client is None:
+            try:
+                from google.cloud import storage
+            except ImportError:
+                raise ImportError(
+                    "google-cloud-storage is required for GCS storage. "
+                    "Install with: pip install google-cloud-storage"
+                )
+
+            if self._credentials_path:
+                self._client = storage.Client.from_service_account_json(
+                    self._credentials_path,
+                    project=self._project,
+                )
+            else:
+                self._client = storage.Client(project=self._project)
+
+            self._bucket = self._client.bucket(self.bucket_name)
+
+        return self._client, self._bucket
+
+    def _build_blob_name(self, attachment_id: str, filename: str) -> str:
+        """Build GCS blob name."""
+        return f"{self.prefix}/{attachment_id}/{filename}"
+
+    async def store(
+        self,
+        attachment_id: str,
+        content: bytes,
+        metadata: AttachmentMetadata,
+    ) -> StorageResult:
+        """Store attachment in GCS."""
+        _, bucket = self._get_client()
+        storage_key = self._build_blob_name(attachment_id, metadata.filename)
+
+        blob = bucket.blob(storage_key)
+        blob.metadata = {
+            "message_id": metadata.message_id,
+            "content_disposition": metadata.content_disposition,
+            "content_id": metadata.content_id or "",
+        }
+
+        blob.upload_from_string(
+            content,
+            content_type=metadata.content_type,
+        )
+
+        return StorageResult(
+            storage_key=storage_key,
+            size_bytes=len(content),
+            content_hash=self.compute_hash(content),
+            backend=self.backend_name,
+        )
+
+    async def retrieve(self, storage_key: str) -> bytes:
+        """Retrieve attachment from GCS."""
+        _, bucket = self._get_client()
+        blob = bucket.blob(storage_key)
+
+        if not blob.exists():
+            raise FileNotFoundError(f"Attachment not found: {storage_key}")
+
+        return cast("bytes", blob.download_as_bytes())
+
+    async def delete(self, storage_key: str) -> bool:
+        """Delete attachment from GCS."""
+        _, bucket = self._get_client()
+        blob = bucket.blob(storage_key)
+
+        if not blob.exists():
+            return False
+
+        blob.delete()
+        return True
+
+    async def get_download_url(
+        self,
+        storage_key: str,
+        expires_in: timedelta = timedelta(hours=1),
+        filename: str | None = None,
+    ) -> str:
+        """Generate signed download URL."""
+        _, bucket = self._get_client()
+        blob = bucket.blob(storage_key)
+
+        kwargs: dict[str, Any] = {
+            "expiration": expires_in,
+        }
+
+        if filename:
+            kwargs["response_disposition"] = f'attachment; filename="{filename}"'
+
+        url = blob.generate_signed_url(**kwargs)
+        return cast("str", url)
+
+    async def exists(self, storage_key: str) -> bool:
+        """Check if attachment exists in GCS."""
+        _, bucket = self._get_client()
+        blob = bucket.blob(storage_key)
+        return cast("bool", blob.exists())

nornweave/storage/local.py

@@ -0,0 +1,152 @@
+"""Local filesystem storage backend for attachments."""
+
+import hashlib
+import hmac
+import time
+from datetime import datetime, timedelta
+from pathlib import Path
+from urllib.parse import urlencode
+
+from nornweave.core.storage import AttachmentMetadata, AttachmentStorageBackend, StorageResult
+
+
+class LocalFilesystemStorage(AttachmentStorageBackend):
+    """Store attachments on local filesystem.
+
+    Good for development and simple deployments.
+    Files are organized by date: base_path/YYYY/MM/DD/attachment_id/filename
+    """
+
+    def __init__(
+        self,
+        base_path: str = "./data/attachments",
+        serve_url_prefix: str = "/v1/attachments",
+        signing_secret: str | None = None,
+    ) -> None:
+        """
+        Initialize local storage.
+
+        Args:
+            base_path: Base directory for attachment storage
+            serve_url_prefix: URL prefix for download URLs
+            signing_secret: Secret for signing download URLs (uses app secret if not set)
+        """
+        self.base_path = Path(base_path)
+        self.serve_url_prefix = serve_url_prefix.rstrip("/")
+        self._signing_secret = signing_secret or "default-signing-secret"
+
+    @property
+    def backend_name(self) -> str:
+        return "local"
+
+    async def store(
+        self,
+        attachment_id: str,
+        content: bytes,
+        metadata: AttachmentMetadata,
+    ) -> StorageResult:
+        """Store attachment on local filesystem."""
+        # Create date-based path
+        date_path = datetime.utcnow().strftime("%Y/%m/%d")
+        storage_key = f"{date_path}/{attachment_id}/{metadata.filename}"
+
+        full_path = self.base_path / storage_key
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content
+        full_path.write_bytes(content)
+
+        return StorageResult(
+            storage_key=storage_key,
+            size_bytes=len(content),
+            content_hash=self.compute_hash(content),
+            backend=self.backend_name,
+        )
+
+    async def retrieve(self, storage_key: str) -> bytes:
+        """Retrieve attachment from filesystem."""
+        full_path = self.base_path / storage_key
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"Attachment not found: {storage_key}")
+
+        return full_path.read_bytes()
+
+    async def delete(self, storage_key: str) -> bool:
+        """Delete attachment from filesystem."""
+        full_path = self.base_path / storage_key
+
+        if not full_path.exists():
+            return False
+
+        full_path.unlink()
+
+        # Try to clean up empty parent directories
+        import contextlib
+
+        with contextlib.suppress(OSError):
+            full_path.parent.rmdir()
+
+        return True
+
+    async def get_download_url(
+        self,
+        storage_key: str,
+        expires_in: timedelta = timedelta(hours=1),
+        filename: str | None = None,
+    ) -> str:
+        """Generate a signed download URL."""
+        # Extract attachment_id from storage key
+        parts = storage_key.split("/")
+        attachment_id = parts[-2] if len(parts) >= 2 else storage_key
+
+        # Create signed token
+        expiry = int(time.time() + expires_in.total_seconds())
+        signature = self._sign_url(attachment_id, expiry)
+
+        # Build URL with query params
+        params = {"token": signature, "expires": str(expiry)}
+        if filename:
+            params["filename"] = filename
+
+        return f"{self.serve_url_prefix}/{attachment_id}/download?{urlencode(params)}"
+
+    async def exists(self, storage_key: str) -> bool:
+        """Check if attachment exists."""
+        full_path = self.base_path / storage_key
+        return full_path.exists()
+
+    def _sign_url(self, attachment_id: str, expiry: int) -> str:
+        """Create HMAC signature for URL."""
+        message = f"{attachment_id}:{expiry}"
+        signature = hmac.new(
+            self._signing_secret.encode(),
+            message.encode(),
+            hashlib.sha256,
+        ).hexdigest()[:32]
+        return signature
+
+    def verify_signed_url(
+        self,
+        attachment_id: str,
+        token: str,
+        expires: int,
+    ) -> bool:
+        """
+        Verify a signed download URL.
+
+        Args:
+            attachment_id: The attachment ID from the URL
+            token: The signature token from the URL
+            expires: The expiry timestamp from the URL
+
+        Returns:
+            True if signature is valid and not expired
+        """
+        # Check expiry
+        if expires < time.time():
+            return False
+
+        # Verify signature
+        expected = self._sign_url(attachment_id, expires)
+        return hmac.compare_digest(token, expected)

nornweave/storage/s3.py

@@ -0,0 +1,164 @@
+"""AWS S3 storage backend for attachments."""
+
+from datetime import timedelta
+from typing import Any, cast
+
+from nornweave.core.storage import AttachmentMetadata, AttachmentStorageBackend, StorageResult
+
+
+class S3Storage(AttachmentStorageBackend):
+    """Store attachments in AWS S3.
+
+    Recommended for production deployments.
+    Uses presigned URLs for secure downloads.
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        prefix: str = "attachments",
+        region: str = "us-east-1",
+        access_key: str | None = None,
+        secret_key: str | None = None,
+        endpoint_url: str | None = None,
+    ) -> None:
+        """
+        Initialize S3 storage.
+
+        Args:
+            bucket: S3 bucket name
+            prefix: Key prefix for attachments
+            region: AWS region
+            access_key: AWS access key (uses IAM role if not set)
+            secret_key: AWS secret key (uses IAM role if not set)
+            endpoint_url: Custom endpoint URL (for S3-compatible services)
+        """
+        self.bucket = bucket
+        self.prefix = prefix.strip("/")
+        self.region = region
+        self._access_key = access_key
+        self._secret_key = secret_key
+        self._endpoint_url = endpoint_url
+        self._client: Any = None
+
+    @property
+    def backend_name(self) -> str:
+        return "s3"
+
+    def _get_client(self) -> Any:
+        """Get or create S3 client (lazy initialization)."""
+        if self._client is None:
+            try:
+                import boto3
+            except ImportError:
+                raise ImportError(
+                    "boto3 is required for S3 storage. Install with: pip install boto3"
+                )
+
+            client_kwargs: dict[str, Any] = {
+                "service_name": "s3",
+                "region_name": self.region,
+            }
+
+            if self._access_key and self._secret_key:
+                client_kwargs["aws_access_key_id"] = self._access_key
+                client_kwargs["aws_secret_access_key"] = self._secret_key
+
+            if self._endpoint_url:
+                client_kwargs["endpoint_url"] = self._endpoint_url
+
+            self._client = boto3.client(**client_kwargs)
+
+        return self._client
+
+    def _build_key(self, attachment_id: str, filename: str) -> str:
+        """Build S3 object key."""
+        return f"{self.prefix}/{attachment_id}/{filename}"
+
+    async def store(
+        self,
+        attachment_id: str,
+        content: bytes,
+        metadata: AttachmentMetadata,
+    ) -> StorageResult:
+        """Store attachment in S3."""
+        client = self._get_client()
+        storage_key = self._build_key(attachment_id, metadata.filename)
+
+        # Upload with metadata
+        client.put_object(
+            Bucket=self.bucket,
+            Key=storage_key,
+            Body=content,
+            ContentType=metadata.content_type,
+            Metadata={
+                "message_id": metadata.message_id,
+                "content_disposition": metadata.content_disposition,
+                "content_id": metadata.content_id or "",
+            },
+        )
+
+        return StorageResult(
+            storage_key=storage_key,
+            size_bytes=len(content),
+            content_hash=self.compute_hash(content),
+            backend=self.backend_name,
+        )
+
+    async def retrieve(self, storage_key: str) -> bytes:
+        """Retrieve attachment from S3."""
+        client = self._get_client()
+
+        try:
+            response = client.get_object(Bucket=self.bucket, Key=storage_key)
+            return cast("bytes", response["Body"].read())
+        except client.exceptions.NoSuchKey:
+            raise FileNotFoundError(f"Attachment not found: {storage_key}")
+
+    async def delete(self, storage_key: str) -> bool:
+        """Delete attachment from S3."""
+        client = self._get_client()
+
+        try:
+            # Check if exists first
+            client.head_object(Bucket=self.bucket, Key=storage_key)
+        except client.exceptions.ClientError:
+            return False
+
+        client.delete_object(Bucket=self.bucket, Key=storage_key)
+        return True
+
+    async def get_download_url(
+        self,
+        storage_key: str,
+        expires_in: timedelta = timedelta(hours=1),
+        filename: str | None = None,
+    ) -> str:
+        """Generate presigned download URL."""
+        client = self._get_client()
+
+        params: dict[str, Any] = {
+            "Bucket": self.bucket,
+            "Key": storage_key,
+        }
+
+        if filename:
+            params["ResponseContentDisposition"] = f'attachment; filename="{filename}"'
+
+        url = client.generate_presigned_url(
+            "get_object",
+            Params=params,
+            ExpiresIn=int(expires_in.total_seconds()),
+        )
+
+        return cast("str", url)
+
+    async def exists(self, storage_key: str) -> bool:
+        """Check if attachment exists in S3."""
+        client = self._get_client()
+
+        try:
+            client.head_object(Bucket=self.bucket, Key=storage_key)
+            return True
+        except client.exceptions.ClientError:
+            return False

nornweave/urdr/__init__.py

@@ -0,0 +1,14 @@
+"""Urdr (The Well): Storage layer."""
+
+from nornweave.urdr.adapters import PostgresAdapter, SQLiteAdapter
+from nornweave.urdr.orm import Base, EventORM, InboxORM, MessageORM, ThreadORM
+
+__all__ = [
+    "Base",
+    "EventORM",
+    "InboxORM",
+    "MessageORM",
+    "PostgresAdapter",  # May be None if asyncpg not installed
+    "SQLiteAdapter",
+    "ThreadORM",
+]

nornweave/urdr/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Storage adapters: Postgres, SQLite."""
+
+from nornweave.urdr.adapters.base import BaseSQLAlchemyAdapter
+from nornweave.urdr.adapters.sqlite import SQLiteAdapter
+
+# PostgresAdapter requires asyncpg - import conditionally
+try:
+    from nornweave.urdr.adapters.postgres import PostgresAdapter
+except ImportError:
+    PostgresAdapter = None  # type: ignore[misc, assignment]
+
+__all__ = [
+    "BaseSQLAlchemyAdapter",
+    "PostgresAdapter",
+    "SQLiteAdapter",
+]