rse-files-core 0.1.0__tar.gz

rse_files_core-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: rse-files-core
+Version: 0.1.0
+Summary: RSE standard file storage helpers with Vault-backed configuration and GCS support.
+Author: RSE Team
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: google-cloud-storage (>=2.19.0,<3.0.0)
+Requires-Dist: hvac (>=2.4.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# rse-files-core
+
+RSE standard file storage package for Python APIs.
+
+Features:
+
+- GCS upload/download helpers
+- storage configuration from local environment or HashiCorp Vault
+- filename and storage key sanitization
+- SHA-256 checksums
+- PDF/content-type/max-size validation
+- standardized metadata and exceptions
+
+## Usage
+
+```python
+from rse_files import (
+    build_storage_key,
+    create_file_storage,
+    validate_pdf_bytes,
+)
+
+storage = create_file_storage()
+
+validate_pdf_bytes(content)
+
+storage_key = build_storage_key(
+    namespace="nc",
+    owner_type="action-plan-evidence",
+    owner_id=123,
+    filename="evidencia.pdf",
+)
+
+metadata = storage.upload_bytes(
+    content=content,
+    storage_key=storage_key,
+    content_type="application/pdf",
+    filename="evidencia.pdf",
+)
+```
+
+## Local Configuration
+
+When `RSE_ENV=local`, the package reads regular environment variables:
+
+```text
+RSE_FILES_STORAGE_PROVIDER=gcs
+RSE_FILES_BUCKET=my-bucket
+RSE_FILES_PREFIX=uploads
+```
+
+## Vault
+
+When `RSE_ENV` is `stg` or `prd`, the package reads Vault using:
+
+- `RSE_ENV` as the KV v2 mount point
+- `RSE_VAULT_HOST` as the Vault URL
+- `RSE_VAULT_TOKEN` as the Vault token
+- `RSE_FILES_VAULT_PATH` as the secret path, defaulting to `shared`
+
+Expected keys:
+
+```text
+rse_files_storage_provider
+rse_files_bucket
+rse_files_prefix
+```
+
+Fallback keys are also accepted for compatibility:
+
+```text
+document_storage_provider
+gcs_documents_bucket
+gcs_documents_prefix
+```
+
+Example:
+
+```text
+stg/shared.rse_files_storage_provider = gcs
+stg/shared.rse_files_bucket = rse-documents-stg
+stg/shared.rse_files_prefix = files
+```
+

rse_files_core-0.1.0/README.md

@@ -0,0 +1,83 @@
+# rse-files-core
+
+RSE standard file storage package for Python APIs.
+
+Features:
+
+- GCS upload/download helpers
+- storage configuration from local environment or HashiCorp Vault
+- filename and storage key sanitization
+- SHA-256 checksums
+- PDF/content-type/max-size validation
+- standardized metadata and exceptions
+
+## Usage
+
+```python
+from rse_files import (
+    build_storage_key,
+    create_file_storage,
+    validate_pdf_bytes,
+)
+
+storage = create_file_storage()
+
+validate_pdf_bytes(content)
+
+storage_key = build_storage_key(
+    namespace="nc",
+    owner_type="action-plan-evidence",
+    owner_id=123,
+    filename="evidencia.pdf",
+)
+
+metadata = storage.upload_bytes(
+    content=content,
+    storage_key=storage_key,
+    content_type="application/pdf",
+    filename="evidencia.pdf",
+)
+```
+
+## Local Configuration
+
+When `RSE_ENV=local`, the package reads regular environment variables:
+
+```text
+RSE_FILES_STORAGE_PROVIDER=gcs
+RSE_FILES_BUCKET=my-bucket
+RSE_FILES_PREFIX=uploads
+```
+
+## Vault
+
+When `RSE_ENV` is `stg` or `prd`, the package reads Vault using:
+
+- `RSE_ENV` as the KV v2 mount point
+- `RSE_VAULT_HOST` as the Vault URL
+- `RSE_VAULT_TOKEN` as the Vault token
+- `RSE_FILES_VAULT_PATH` as the secret path, defaulting to `shared`
+
+Expected keys:
+
+```text
+rse_files_storage_provider
+rse_files_bucket
+rse_files_prefix
+```
+
+Fallback keys are also accepted for compatibility:
+
+```text
+document_storage_provider
+gcs_documents_bucket
+gcs_documents_prefix
+```
+
+Example:
+
+```text
+stg/shared.rse_files_storage_provider = gcs
+stg/shared.rse_files_bucket = rse-documents-stg
+stg/shared.rse_files_prefix = files
+```

rse_files_core-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "rse-files-core"
+version = "0.1.0"
+description = "RSE standard file storage helpers with Vault-backed configuration and GCS support."
+authors = ["RSE Team"]
+readme = "README.md"
+packages = [{ include = "rse_files" }]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+google-cloud-storage = "^2.19.0"
+hvac = "^2.4.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

rse_files_core-0.1.0/rse_files/__init__.py

@@ -0,0 +1,40 @@
+from .checksum import sha256_bytes
+from .config import FileStorageConfig, get_file_storage_config
+from .exceptions import (
+    FileConfigurationError,
+    FileError,
+    FileNotFoundError,
+    FileStorageError,
+    FileValidationError,
+)
+from .filenames import sanitize_filename
+from .keys import build_storage_key, sanitize_path_segment, validate_storage_key
+from .metadata import FileMetadata
+from .storage.factory import create_file_storage
+from .validators import (
+    PDF_CONTENT_TYPE,
+    validate_allowed_content_type,
+    validate_max_size,
+    validate_pdf_bytes,
+)
+
+__all__ = [
+    "FileConfigurationError",
+    "FileError",
+    "FileMetadata",
+    "FileNotFoundError",
+    "FileStorageConfig",
+    "FileStorageError",
+    "FileValidationError",
+    "PDF_CONTENT_TYPE",
+    "build_storage_key",
+    "create_file_storage",
+    "get_file_storage_config",
+    "sanitize_filename",
+    "sanitize_path_segment",
+    "sha256_bytes",
+    "validate_allowed_content_type",
+    "validate_max_size",
+    "validate_pdf_bytes",
+    "validate_storage_key",
+]

rse_files_core-0.1.0/rse_files/checksum.py

@@ -0,0 +1,5 @@
+import hashlib
+
+
+def sha256_bytes(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()

rse_files_core-0.1.0/rse_files/config.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from hvac import Client
+from hvac.exceptions import Unauthorized
+
+from .exceptions import FileConfigurationError
+
+STORAGE_PROVIDER_GCS = "gcs"
+DEFAULT_STORAGE_PREFIX = "files"
+DEFAULT_VAULT_PATH = "shared"
+
+_vault_cache: dict[str, dict[str, Any]] = {}
+
+
+@dataclass(frozen=True)
+class FileStorageConfig:
+    storage_provider: str
+    bucket_name: str
+    prefix: str = DEFAULT_STORAGE_PREFIX
+
+
+def get_file_storage_config(
+    *,
+    provider: str | None = None,
+    bucket_name: str | None = None,
+    prefix: str | None = None,
+    vault_path: str | None = None,
+) -> FileStorageConfig:
+    if provider is not None or bucket_name is not None or prefix is not None:
+        return _build_config(
+            provider=provider,
+            bucket_name=bucket_name,
+            prefix=prefix,
+        )
+
+    rse_env = os.getenv("RSE_ENV", "local").strip().lower()
+    if rse_env == "local":
+        return _config_from_environment()
+    if rse_env in {"stg", "prd"}:
+        return _config_from_vault(vault_path or os.getenv("RSE_FILES_VAULT_PATH") or DEFAULT_VAULT_PATH)
+
+    raise FileConfigurationError(
+        f"Invalid RSE_ENV value: {rse_env}. Must be one of: local, stg, prd."
+    )
+
+
+def _config_from_environment() -> FileStorageConfig:
+    return _build_config(
+        provider=os.getenv("RSE_FILES_STORAGE_PROVIDER") or os.getenv("DOCUMENT_STORAGE_PROVIDER"),
+        bucket_name=os.getenv("RSE_FILES_BUCKET") or os.getenv("GCS_DOCUMENTS_BUCKET"),
+        prefix=os.getenv("RSE_FILES_PREFIX") or os.getenv("GCS_DOCUMENTS_PREFIX"),
+    )
+
+
+def _config_from_vault(vault_path: str) -> FileStorageConfig:
+    secrets = get_vault_secrets(vault_path)
+    return _build_config(
+        provider=secrets.get("rse_files_storage_provider") or secrets.get("document_storage_provider"),
+        bucket_name=secrets.get("rse_files_bucket") or secrets.get("gcs_documents_bucket"),
+        prefix=secrets.get("rse_files_prefix") or secrets.get("gcs_documents_prefix"),
+    )
+
+
+def _build_config(
+    *,
+    provider: str | None,
+    bucket_name: str | None,
+    prefix: str | None,
+) -> FileStorageConfig:
+    normalized_provider = (provider or STORAGE_PROVIDER_GCS).strip().lower()
+    if normalized_provider != STORAGE_PROVIDER_GCS:
+        raise FileConfigurationError(
+            f"Invalid file storage provider: {normalized_provider or '<empty>'}."
+        )
+
+    normalized_bucket = (bucket_name or "").strip()
+    if not normalized_bucket:
+        raise FileConfigurationError("File storage bucket is not configured.")
+
+    normalized_prefix = (prefix or DEFAULT_STORAGE_PREFIX).strip() or DEFAULT_STORAGE_PREFIX
+    return FileStorageConfig(
+        storage_provider=normalized_provider,
+        bucket_name=normalized_bucket,
+        prefix=normalized_prefix,
+    )
+
+
+def get_vault_secrets(path: str) -> dict[str, Any]:
+    if path in _vault_cache:
+        return _vault_cache[path]
+
+    vault_host = os.getenv("RSE_VAULT_HOST")
+    vault_token = os.getenv("RSE_VAULT_TOKEN")
+    rse_env = os.getenv("RSE_ENV", "local").strip().lower()
+
+    missing = []
+    if not vault_host:
+        missing.append("RSE_VAULT_HOST")
+    if not vault_token:
+        missing.append("RSE_VAULT_TOKEN")
+    if missing:
+        raise FileConfigurationError(
+            f"Required environment variables not declared: {', '.join(missing)}"
+        )
+
+    client = Client(url=vault_host, token=vault_token)
+    if not client.is_authenticated():
+        raise Unauthorized("Not authenticated in Vault")
+
+    response = client.secrets.kv.v2.read_secret_version(
+        mount_point=rse_env,
+        path=path,
+    )
+    secrets = response["data"]["data"]
+    _vault_cache[path] = secrets
+    return secrets

rse_files_core-0.1.0/rse_files/exceptions.py

@@ -0,0 +1,18 @@
+class FileError(RuntimeError):
+    """Base exception for rse-files-core."""
+
+
+class FileConfigurationError(FileError):
+    """Raised when file storage is not configured correctly."""
+
+
+class FileValidationError(FileError):
+    """Raised when file content or metadata is invalid."""
+
+
+class FileStorageError(FileError):
+    """Raised when a storage provider operation fails."""
+
+
+class FileNotFoundError(FileStorageError):
+    """Raised when a file is not found in storage."""

rse_files_core-0.1.0/rse_files/filenames.py

@@ -0,0 +1,17 @@
+import re
+import unicodedata
+
+from .exceptions import FileConfigurationError
+
+
+def sanitize_filename(value: str) -> str:
+    unsafe_name = str(value or "").replace("\\", "/").split("/")[-1]
+    normalized = unicodedata.normalize("NFKD", unsafe_name.strip())
+    ascii_value = normalized.encode("ascii", "ignore").decode("ascii")
+    safe = re.sub(r"[^a-zA-Z0-9._-]+", "-", ascii_value.lower())
+    safe = re.sub(r"-+", "-", safe).strip("-. _")
+    safe = re.sub(r"-+(\.[a-zA-Z0-9]+)$", r"\1", safe)
+    safe = safe.replace("..", ".")
+    if not safe:
+        raise FileConfigurationError("Invalid filename.")
+    return safe

rse_files_core-0.1.0/rse_files/keys.py

@@ -0,0 +1,42 @@
+import re
+
+from .exceptions import FileConfigurationError
+from .filenames import sanitize_filename
+
+
+def build_storage_key(
+    *,
+    namespace: str,
+    owner_type: str,
+    owner_id: str | int,
+    filename: str,
+    prefix: str | None = None,
+) -> str:
+    parts = [
+        sanitize_path_segment(prefix) if prefix else None,
+        sanitize_path_segment(namespace),
+        sanitize_path_segment(owner_type),
+        sanitize_path_segment(owner_id),
+        sanitize_filename(filename),
+    ]
+    return validate_storage_key("/".join(part for part in parts if part))
+
+
+def sanitize_path_segment(value: str | int | None, *, preserve_case: bool = False) -> str:
+    raw = str(value or "").strip().replace("\\", "/")
+    if "/" in raw or raw in {"", ".", ".."} or ".." in raw:
+        raise FileConfigurationError("Invalid storage key segment.")
+    safe = sanitize_filename(raw)
+    return raw if preserve_case and re.fullmatch(r"[A-Za-z0-9._-]+", raw) else safe
+
+
+def validate_storage_key(storage_key: str) -> str:
+    key = str(storage_key or "").strip()
+    if not key:
+        raise FileConfigurationError("File storage key is not configured.")
+    if key.startswith("/") or "\\" in key or "//" in key:
+        raise FileConfigurationError("Invalid file storage key.")
+    parts = key.split("/")
+    if any(part in {"", ".", ".."} or ".." in part for part in parts):
+        raise FileConfigurationError("Invalid file storage key.")
+    return key

rse_files_core-0.1.0/rse_files/metadata.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FileMetadata:
+    storage_provider: str
+    bucket_name: str
+    storage_key: str
+    filename: str | None
+    content_type: str
+    file_size: int
+    checksum: str
+    etag: str | None = None
+    generation: str | None = None
+    created: Any | None = None
+    updated: Any | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

rse_files_core-0.1.0/rse_files/storage/__init__.py

@@ -0,0 +1,5 @@
+from .base import FileStorage
+from .factory import create_file_storage
+from .gcs import GcsFileStorage
+
+__all__ = ["FileStorage", "GcsFileStorage", "create_file_storage"]

rse_files_core-0.1.0/rse_files/storage/base.py

@@ -0,0 +1,24 @@
+from typing import Protocol
+
+from rse_files.metadata import FileMetadata
+
+
+class FileStorage(Protocol):
+    def upload_bytes(
+        self,
+        *,
+        content: bytes,
+        storage_key: str,
+        content_type: str,
+        filename: str | None = None,
+    ) -> FileMetadata:
+        ...
+
+    def download_bytes(self, storage_key: str) -> bytes:
+        ...
+
+    def exists(self, storage_key: str) -> bool:
+        ...
+
+    def delete(self, storage_key: str) -> None:
+        ...

rse_files_core-0.1.0/rse_files/storage/factory.py

@@ -0,0 +1,31 @@
+from typing import Any
+
+from rse_files.config import STORAGE_PROVIDER_GCS, get_file_storage_config
+from rse_files.exceptions import FileConfigurationError
+from rse_files.storage.gcs import GcsFileStorage
+
+
+def create_file_storage(
+    *,
+    provider: str | None = None,
+    bucket_name: str | None = None,
+    prefix: str | None = None,
+    vault_path: str | None = None,
+    client: Any | None = None,
+) -> GcsFileStorage:
+    config = get_file_storage_config(
+        provider=provider,
+        bucket_name=bucket_name,
+        prefix=prefix,
+        vault_path=vault_path,
+    )
+    if config.storage_provider == STORAGE_PROVIDER_GCS:
+        return GcsFileStorage(
+            bucket_name=config.bucket_name,
+            prefix=config.prefix,
+            client=client,
+        )
+
+    raise FileConfigurationError(
+        f"Unsupported file storage provider: {config.storage_provider}."
+    )

rse_files_core-0.1.0/rse_files/storage/gcs.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any
+
+from rse_files.checksum import sha256_bytes
+from rse_files.config import DEFAULT_STORAGE_PREFIX, STORAGE_PROVIDER_GCS
+from rse_files.exceptions import (
+    FileConfigurationError,
+    FileNotFoundError,
+    FileStorageError,
+)
+from rse_files.filenames import sanitize_filename
+from rse_files.keys import sanitize_path_segment, validate_storage_key
+from rse_files.metadata import FileMetadata
+
+
+class GcsFileStorage:
+    def __init__(
+        self,
+        *,
+        bucket_name: str,
+        prefix: str | None = None,
+        client: Any | None = None,
+    ) -> None:
+        if not bucket_name.strip():
+            raise FileConfigurationError("File storage bucket is not configured.")
+        self.bucket_name = bucket_name.strip()
+        self.prefix = sanitize_path_segment(prefix or DEFAULT_STORAGE_PREFIX)
+        self.client = client or self.build_client()
+        self.bucket = self.client.bucket(self.bucket_name)
+
+    def upload_bytes(
+        self,
+        *,
+        content: bytes,
+        storage_key: str,
+        content_type: str,
+        filename: str | None = None,
+    ) -> FileMetadata:
+        key = validate_storage_key(storage_key)
+        if not content_type:
+            raise FileConfigurationError("File content_type is not configured.")
+
+        checksum = sha256_bytes(content)
+        blob = self.bucket.blob(key)
+        try:
+            blob.upload_from_string(
+                content,
+                content_type=content_type,
+                if_generation_match=0,
+            )
+        except Exception as exc:
+            raise FileStorageError("Failed to upload file to GCS.") from exc
+
+        return FileMetadata(
+            storage_provider=STORAGE_PROVIDER_GCS,
+            bucket_name=self.bucket_name,
+            storage_key=key,
+            filename=sanitize_filename(filename) if filename else None,
+            content_type=content_type,
+            file_size=len(content),
+            checksum=checksum,
+            etag=getattr(blob, "etag", None),
+            generation=_metadata_value(getattr(blob, "generation", None)),
+            created=_metadata_value(getattr(blob, "time_created", None)),
+            updated=_metadata_value(getattr(blob, "updated", None)),
+        )
+
+    def download_bytes(self, storage_key: str) -> bytes:
+        key = validate_storage_key(storage_key)
+        blob = self.bucket.blob(key)
+        try:
+            if not blob.exists():
+                raise FileNotFoundError("File not found in storage.")
+            return blob.download_as_bytes()
+        except FileNotFoundError:
+            raise
+        except Exception as exc:
+            raise FileStorageError("Failed to download file from GCS.") from exc
+
+    def exists(self, storage_key: str) -> bool:
+        key = validate_storage_key(storage_key)
+        try:
+            return bool(self.bucket.blob(key).exists())
+        except Exception as exc:
+            raise FileStorageError("Failed to check file existence in GCS.") from exc
+
+    def delete(self, storage_key: str) -> None:
+        key = validate_storage_key(storage_key)
+        blob = self.bucket.blob(key)
+        try:
+            if blob.exists():
+                blob.delete()
+        except Exception as exc:
+            raise FileStorageError("Failed to delete file from GCS.") from exc
+
+    @staticmethod
+    def build_client() -> Any:
+        try:
+            from google.cloud import storage
+        except ImportError as exc:
+            raise FileConfigurationError(
+                "Dependency google-cloud-storage is not installed."
+            ) from exc
+        return storage.Client()
+
+
+def _metadata_value(value: Any) -> Any:
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+    return value

rse_files_core-0.1.0/rse_files/validators.py

@@ -0,0 +1,23 @@
+from .exceptions import FileValidationError
+
+PDF_CONTENT_TYPE = "application/pdf"
+PDF_HEADER = b"%PDF-"
+
+
+def validate_allowed_content_type(content_type: str, allowed: set[str]) -> None:
+    if content_type not in allowed:
+        raise FileValidationError(f"Invalid content_type: {content_type}.")
+
+
+def validate_max_size(content: bytes, max_bytes: int) -> None:
+    if len(content) > max_bytes:
+        raise FileValidationError(
+            f"File exceeds maximum size of {max_bytes} bytes."
+        )
+
+
+def validate_pdf_bytes(content: bytes) -> None:
+    if not content:
+        raise FileValidationError("PDF content is empty.")
+    if not content.startswith(PDF_HEADER):
+        raise FileValidationError("Invalid PDF content.")