Add GCS storage backend with storage factory pattern (Phase 3)

Cloud Run is ephemeral — /tmp data lost on cold starts. This adds a
Google Cloud Storage backend alongside the existing local filesystem
storage, controlled by the USE_LOCAL_STORAGE environment variable.

New: GCSStorage in storage/gcs.py, get_storage() factory in
storage/factory.py, 21 tests in test_storage.py (LocalStorage,
GCSStorage with mocked GCS client, factory).

Modified: DigestStorage ABC gains get_metadata() + get_digest_bytes()
abstract methods. LocalStorage gets get_digest_bytes(). query_processor
uses factory (_store_digest replaces _store_digest_locally). Download
endpoint refactored to use storage abstraction instead of direct
filesystem reads. Deploy config switches to USE_LOCAL_STORAGE=false
with GCS_BUCKET_NAME=gitunderstand-digests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

.github/workflows/deploy.yml

@@ -96,7 +96,7 @@ jobs:
             --min-instances 0 \
             --max-instances 10 \
             --timeout 300 \
-            --set-env-vars "^@^GCP_PROJECT_ID=${{ env.PROJECT_ID }}@USE_LOCAL_STORAGE=true@ALLOWED_HOSTS=gitunderstand.com,gitunderstand-308289525742.us-central1.run.app,localhost,127.0.0.1" \
+            --set-env-vars "^@^GCP_PROJECT_ID=${{ env.PROJECT_ID }}@USE_LOCAL_STORAGE=false@GCS_BUCKET_NAME=gitunderstand-digests@ALLOWED_HOSTS=gitunderstand.com,gitunderstand-308289525742.us-central1.run.app,localhost,127.0.0.1" \
             --project ${{ env.PROJECT_ID }}
 
       - name: Show Cloud Run URL

pyproject.toml

@@ -8,6 +8,7 @@ dependencies = [
     "click>=8.0.0",
     "fastapi[standard]>=0.109.1",
     "gitpython>=3.1.0",
+    "google-cloud-storage>=2.10.0",
     "httpx",
     "jinja2",
     "pathspec>=0.12.1",

requirements.txt

@@ -1,6 +1,7 @@
 click>=8.0.0
 fastapi[standard]>=0.109.1
 gitpython>=3.1.0
+google-cloud-storage>=2.10.0
 httpx
 jinja2
 pathspec>=0.12.1

src/api/query_processor.py

@@ -16,7 +16,7 @@
 from core.parser import parse_remote_repo
 from core.utils.git_utils import validate_github_token
 from core.utils.pattern_utils import process_patterns
-from storage.local import LocalStorage
+from storage.factory import get_storage
 
 logger = logging.getLogger(__name__)
 
@@ -40,15 +40,18 @@ def _cleanup_repository(clone_config: CloneConfig) -> None:
         logger.exception("Could not delete repository at %s", clone_config.local_path)
 
 
-def _store_digest_locally(
+def _store_digest(
     query: IngestionQuery,
     clone_config: CloneConfig,
     digest_content: str,
     summary: str,
     tree: str,
     content: str,
 ) -> str:
-    """Store digest content to local storage.
+    """Store digest content using the configured storage backend.
+
+    Uses the storage factory to select either local filesystem or GCS
+    based on application settings.
 
     Parameters
     ----------
@@ -71,7 +74,7 @@ def _store_digest_locally(
         The download URL for the stored digest.
 
     """
-    storage = LocalStorage(base_path=settings.local_storage_path)
+    storage = get_storage()
     digest_id = str(query.id)
 
     storage.store_digest(
@@ -149,7 +152,7 @@ async def process_query(
     try:
         summary, tree, content, token_counts = ingest_query(query)
         digest_content = tree + "\n" + content
-        digest_url = _store_digest_locally(query, clone_config, digest_content, summary, tree, content)
+        digest_url = _store_digest(query, clone_config, digest_content, summary, tree, content)
     except Exception as exc:
         logger.error(
             "Query processing failed for %s: %s",
@@ -273,7 +276,7 @@ async def process_query_streaming(
             reporter.report(ProgressStage.STORING, {"message": "Saving digest..."})
 
         digest_content = tree + "\n" + content
-        digest_url = _store_digest_locally(query, clone_config, digest_content, summary, tree, content)
+        digest_url = _store_digest(query, clone_config, digest_content, summary, tree, content)
     except Exception as exc:
         logger.error("Query processing failed for %s: %s", query.url, exc)
         if reporter:

src/api/routers/ingest.py

@@ -5,11 +5,10 @@
 import asyncio
 import contextlib
 import logging
-from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from fastapi import APIRouter, HTTPException, Request, status
-from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
+from fastapi import APIRouter, HTTPException, Request, Response, status
+from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
 
 from api.config import get_settings
 from api.middleware import limiter
@@ -19,6 +18,7 @@
 from api.shared import templates
 from core.output_formats import OutputFormat
 from core.progress import ProgressStage
+from storage.factory import get_storage
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator
@@ -299,47 +299,40 @@ async def api_ingest_get(
 @router.get("/api/download/file/{ingest_id}", response_model=None)
 async def download_ingest(
     ingest_id: UUID,
-) -> FileResponse | JSONResponse:  # noqa: FA100
+) -> Response | JSONResponse:  # noqa: FA100
     """Download the text file produced for an ingest ID.
 
+    Uses the configured storage backend (local filesystem or GCS) to
+    retrieve the digest content.
+
     Parameters
     ----------
     ingest_id : UUID
         Identifier that the ingest step emitted.
 
     Returns
     -------
-    FileResponse
+    Response
         Streamed response with media type ``text/plain``.
 
     Raises
     ------
     HTTPException
-        404 if digest directory is missing or contains no ``.txt`` file.
-        403 if there is a permission error reading the file.
+        404 if the digest does not exist in storage.
 
     """
-    tmp_base = Path(settings.local_storage_path)
-    directory = (tmp_base / str(ingest_id)).resolve()
-
-    if not str(directory).startswith(str(tmp_base.resolve())):
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Invalid ingest ID: {ingest_id!r}")
+    storage = get_storage()
+    digest_id = str(ingest_id)
 
-    if not directory.is_dir():
+    if not storage.digest_exists(digest_id):
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Digest {ingest_id!r} not found")
 
-    try:
-        first_txt_file = next(directory.glob("*.txt"))
-    except StopIteration as exc:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"No .txt file found for digest {ingest_id!r}",
-        ) from exc
+    content_bytes = storage.get_digest_bytes(digest_id)
+    if content_bytes is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"No content for digest {ingest_id!r}")
 
-    try:
-        return FileResponse(path=first_txt_file, media_type="text/plain", filename=first_txt_file.name)
-    except PermissionError as exc:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail=f"Permission denied for {first_txt_file}",
-        ) from exc
+    return Response(
+        content=content_bytes,
+        media_type="text/plain",
+        headers={"Content-Disposition": f'attachment; filename="digest-{ingest_id}.txt"'},
+    )

src/storage/__init__.py

@@ -1,6 +1,7 @@
 """Storage module for GitUnderstand digest persistence."""
 
 from storage.base import DigestStorage
+from storage.gcs import GCSStorage
 from storage.local import LocalStorage
 
-__all__ = ["DigestStorage", "LocalStorage"]
+__all__ = ["DigestStorage", "GCSStorage", "LocalStorage"]

src/storage/base.py

@@ -49,6 +49,40 @@ def get_digest(self, digest_id: str) -> str | None:
 
         """
 
+    @abstractmethod
+    def get_metadata(self, digest_id: str) -> dict[str, Any] | None:
+        """Retrieve metadata for a digest.
+
+        Parameters
+        ----------
+        digest_id : str
+            Unique identifier for the digest.
+
+        Returns
+        -------
+        dict[str, Any] | None
+            The metadata dictionary, or ``None`` if not found.
+
+        """
+
+    @abstractmethod
+    def get_digest_bytes(self, digest_id: str) -> bytes | None:
+        """Retrieve the raw bytes of a digest.
+
+        Useful for streaming downloads where text decoding is not needed.
+
+        Parameters
+        ----------
+        digest_id : str
+            Unique identifier for the digest.
+
+        Returns
+        -------
+        bytes | None
+            The raw bytes of the digest content, or ``None`` if not found.
+
+        """
+
     @abstractmethod
     def digest_exists(self, digest_id: str) -> bool:
         """Check if a digest exists in storage.

src/storage/factory.py

@@ -0,0 +1,42 @@
+"""Storage backend factory for GitUnderstand.
+
+Returns the configured storage backend based on application settings.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from storage.base import DigestStorage
+
+
+def get_storage() -> DigestStorage:
+    """Return the configured storage backend instance.
+
+    Uses ``settings.use_local_storage`` to decide which backend to use:
+
+    - ``True``  → :class:`~storage.local.LocalStorage` (filesystem)
+    - ``False`` → :class:`~storage.gcs.GCSStorage` (Google Cloud Storage)
+
+    Returns
+    -------
+    DigestStorage
+        The storage backend instance.
+
+    """
+    from api.config import get_settings  # noqa: PLC0415
+
+    settings = get_settings()
+
+    if settings.use_local_storage:
+        from storage.local import LocalStorage  # noqa: PLC0415
+
+        return LocalStorage(base_path=settings.local_storage_path)
+
+    from storage.gcs import GCSStorage  # noqa: PLC0415
+
+    return GCSStorage(
+        bucket_name=settings.gcs_bucket_name,
+        project_id=settings.gcp_project_id,
+    )