feat: add SESSION_BACKEND setting to make session storage configurable

Add an explicit SESSION_BACKEND env var ("memory" or "database") to
control the ADK session service instead of inferring it from
SESSION_DATABASE_URL. When set to "database", SESSION_DATABASE_URL is
required (validated at startup) and init failures are raised immediately
rather than silently falling back to in-memory.

Updates deployment templates (Cloud Run defaults to "database", Podman
to "memory") and documentation with instructions on switching backends.

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

Author: luis5tb

.env.example

@@ -90,6 +90,18 @@ DATABASE_URL=sqlite+aiosqlite:///./lightspeed_agent.db
 # For PostgreSQL in production:
 # DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/lightspeed_agent
 
+# -----------------------------------------------------------------------------
+# Session Configuration
+# -----------------------------------------------------------------------------
+# Session storage backend: "memory" (default) or "database"
+# "memory": Sessions stored in-memory (lost on restart, suitable for dev)
+# "database": Sessions persisted to PostgreSQL (requires SESSION_DATABASE_URL)
+SESSION_BACKEND=memory
+
+# Session database URL (required when SESSION_BACKEND=database)
+# Use a SEPARATE database from DATABASE_URL for security isolation.
+# SESSION_DATABASE_URL=postgresql+asyncpg://sessions:password@localhost:5433/agent_sessions
+
 # -----------------------------------------------------------------------------
 # Google Cloud Service Control (for usage reporting)
 # -----------------------------------------------------------------------------

deploy/cloudrun/service.yaml

@@ -122,9 +122,11 @@ spec:
                 secretKeyRef:
                   name: database-url
                   key: latest
-            # Session Database (required for session persistence)
-            # If not set, uses in-memory storage (sessions lost on restart)
-            # For production, always configure this for session persistence
+            # Session backend: "database" for production persistence,
+            # "memory" for in-memory (sessions lost on restart)
+            - name: SESSION_BACKEND
+              value: "database"
+            # Session Database (required when SESSION_BACKEND=database)
             - name: SESSION_DATABASE_URL
               valueFrom:
                 secretKeyRef:

deploy/podman/lightspeed-agent-configmap.yaml

@@ -39,6 +39,11 @@ data:
   AGENT_HOST: "0.0.0.0"
   AGENT_PORT: "8000"
 
+  # Session Configuration
+  # Session backend: "memory" for dev (no persistence), "database" for persistent sessions
+  # To use "database", ensure SESSION_DATABASE_URL is configured in the secret
+  SESSION_BACKEND: "memory"
+
   # Database Configuration
   # DATABASE_URL and passwords are stored in secrets (contain credentials)
   # Marketplace PostgreSQL (in marketplace-handler pod)

docs/configuration.md

@@ -100,7 +100,12 @@ AGENT_PORT=8000
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `DATABASE_URL` | `sqlite+aiosqlite:///./lightspeed_agent.db` | Marketplace database connection URL (orders, DCR clients, auth) |
-| `SESSION_DATABASE_URL` | (uses DATABASE_URL) | Session database URL for ADK sessions. Optional - for security isolation. |
+| `SESSION_BACKEND` | `memory` | Session storage backend: `memory` (in-memory, no persistence) or `database` (PostgreSQL, persistent) |
+| `SESSION_DATABASE_URL` | *(empty)* | Session database URL for ADK sessions. Required when `SESSION_BACKEND=database`. |
+
+> **Note:** Setting `SESSION_BACKEND=database` without providing `SESSION_DATABASE_URL`
+> will cause a startup validation error. This is intentional to prevent running
+> production workloads without session persistence.
 
 **SQLite (Development):**
 
@@ -120,11 +125,14 @@ DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/lightspeed_agent
 DATABASE_URL=postgresql+asyncpg://user:password@/lightspeed_agent?host=/cloudsql/project:region:instance
 ```
 
-**Security Isolation (Optional):**
+**Security Isolation (Recommended for Production):**
 
-For production deployments, you can use separate databases for marketplace data and agent sessions:
+For production deployments, use `SESSION_BACKEND=database` with a separate database for agent sessions:
 
 ```bash
+# Explicit database backend for sessions
+SESSION_BACKEND=database
+
 # Shared marketplace database (orders, DCR clients, auth data)
 DATABASE_URL=postgresql+asyncpg://marketplace:pass@db:5432/marketplace
 
@@ -137,6 +145,14 @@ This separation ensures:
 - Compromised agents can't access DCR credentials or order information
 - Different retention policies can be applied to sessions vs. marketplace data
 
+**Switching to In-Memory Sessions:**
+
+To disable database session persistence on a running deployment (e.g., for debugging),
+set `SESSION_BACKEND=memory` and redeploy:
+
+- **Cloud Run:** Update the `SESSION_BACKEND` env var to `memory` and redeploy the service.
+- **Podman:** Update `SESSION_BACKEND` in the ConfigMap to `memory` and restart the pod.
+
 ### Dynamic Client Registration (DCR)
 
 DCR allows Google Cloud Marketplace customers to automatically register as OAuth clients.
@@ -361,6 +377,7 @@ LOG_LEVEL=DEBUG
 LOG_FORMAT=text
 AGENT_LOGGING_DETAIL=detailed
 DATABASE_URL=sqlite+aiosqlite:///./dev.db
+SESSION_BACKEND=memory
 ```
 
 ### Staging
@@ -372,6 +389,8 @@ SKIP_JWT_VALIDATION=false
 LOG_LEVEL=INFO
 LOG_FORMAT=json
 DATABASE_URL=postgresql+asyncpg://user:pass@staging-db:5432/insights
+SESSION_BACKEND=database
+SESSION_DATABASE_URL=postgresql+asyncpg://sessions:pass@staging-db:5432/sessions
 ```
 
 ### Production
@@ -382,5 +401,6 @@ DEBUG=false
 SKIP_JWT_VALIDATION=false
 LOG_LEVEL=INFO
 LOG_FORMAT=json
-# DATABASE_URL from Secret Manager
+SESSION_BACKEND=database
+# DATABASE_URL and SESSION_DATABASE_URL from Secret Manager
 ```

src/lightspeed_agent/api/a2a/a2a_setup.py

@@ -52,60 +52,48 @@ def _normalize_db_url(url: str) -> str:
 
 
 def _get_session_service() -> Any:
-    """Get the appropriate session service based on configuration.
+    """Get the appropriate session service based on SESSION_BACKEND setting.
 
-    For production, uses DatabaseSessionService which persists sessions to PostgreSQL.
-    For development, uses InMemorySessionService.
+    Uses SESSION_BACKEND to determine the session storage:
+    - ``"memory"``: InMemorySessionService (default, no persistence)
+    - ``"database"``: DatabaseSessionService (requires SESSION_DATABASE_URL)
+
+    When SESSION_BACKEND is ``"database"``, failures are raised immediately
+    rather than silently falling back to in-memory, so misconfigurations are
+    caught at startup.
 
     Security Note:
-        SESSION_DATABASE_URL must be explicitly set to use database persistence.
-        This prevents accidental use of the marketplace database (DATABASE_URL)
-        for session storage, ensuring:
-        - Agents only have access to session data, not marketplace/auth data
-        - Compromised agents can't access DCR credentials or order information
-        - Different retention policies can be applied to sessions vs. marketplace data
+        SESSION_DATABASE_URL should point to a separate database from
+        DATABASE_URL to ensure agents only access session data, not
+        marketplace/auth data.
 
     Returns:
         Session service instance (DatabaseSessionService or InMemorySessionService).
     """
     settings = get_settings()
 
-    # Only use database session service if SESSION_DATABASE_URL is explicitly set
-    # Do NOT fall back to DATABASE_URL to avoid mixing session and marketplace data
-    session_db_url = settings.session_database_url
+    if settings.session_backend == "database":
+        from google.adk.sessions import DatabaseSessionService
+
+        # SESSION_DATABASE_URL is guaranteed non-empty by the model validator
+        db_url = _normalize_db_url(settings.session_database_url)
+
+        # Log which database is being used (without credentials)
+        parsed = urlparse(db_url)
+        db_host = parsed.hostname or parsed.query or "local"
+        logger.info(
+            "Using DatabaseSessionService for session persistence (host=%s)",
+            db_host,
+        )
 
-    # Use database session service for production (non-SQLite databases)
-    if session_db_url and not session_db_url.startswith("sqlite"):
         try:
-            from google.adk.sessions import DatabaseSessionService
-
-            # ADK's DatabaseSessionService uses async SQLAlchemy
-            # (create_async_engine), so ensure the URL uses an async driver
-            db_url = _normalize_db_url(session_db_url)
-
-            # Log which database is being used (without credentials)
-            parsed = urlparse(db_url)
-            db_host = parsed.hostname or parsed.query or "local"
-            logger.info(
-                "Using DatabaseSessionService for session persistence (host=%s)",
-                db_host,
-            )
             return DatabaseSessionService(db_url=db_url)
-        except ImportError as e:
-            logger.warning(
-                "DatabaseSessionService not available (%s), falling back to InMemorySessionService",
-                e,
-            )
         except Exception as e:
             # Sanitize error message to avoid leaking credentials from URLs
-            sanitized_msg = re.sub(
-                r"://[^@]+@", "://***@", str(e)
-            )
-            logger.warning(
-                "Failed to initialize DatabaseSessionService (%s), "
-                "falling back to InMemorySessionService",
-                sanitized_msg,
-            )
+            sanitized_msg = re.sub(r"://[^@]+@", "://***@", str(e))
+            raise RuntimeError(
+                f"Failed to initialize DatabaseSessionService: {sanitized_msg}"
+            ) from None
 
     logger.info("Using InMemorySessionService for session management")
     return InMemorySessionService()  # type: ignore[no-untyped-call]

src/lightspeed_agent/config/settings.py

@@ -216,14 +216,22 @@ class Settings(BaseSettings):
         description="Maximum overflow connections beyond pool size",
     )
 
-    # Session database: stores ADK sessions, conversation history, memory
+    # Session configuration: controls ADK session storage backend
     # Separate from marketplace DB for security isolation - each agent can have its own
+    session_backend: Literal["memory", "database"] = Field(
+        default="memory",
+        description=(
+            "Session storage backend. "
+            "'memory' uses in-memory sessions (lost on restart). "
+            "'database' uses DatabaseSessionService and requires SESSION_DATABASE_URL."
+        ),
+    )
     session_database_url: str = Field(
         default="",
         description=(
             "Session database URL for ADK sessions."
-            " If empty, uses DATABASE_URL."
-            " For security isolation, use a separate database."
+            " Required when SESSION_BACKEND=database."
+            " For security isolation, use a separate database from DATABASE_URL."
         ),
     )
 
@@ -292,6 +300,17 @@ def _block_skip_jwt_in_production(self) -> "Settings":
             )
         return self
 
+    @model_validator(mode="after")
+    def _validate_session_backend(self) -> "Settings":
+        """Ensure SESSION_DATABASE_URL is set when SESSION_BACKEND=database."""
+        if self.session_backend == "database" and not self.session_database_url:
+            raise ValueError(
+                "SESSION_BACKEND=database requires SESSION_DATABASE_URL to be set. "
+                "Provide a PostgreSQL connection URL, e.g.: "
+                "SESSION_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/sessions"
+            )
+        return self
+
     # OpenTelemetry Configuration
     otel_enabled: bool = Field(
         default=False,

tests/test_a2a.py

@@ -316,6 +316,7 @@ def test_cloudsql_host_logged_correctly(self, caplog):
             "/agent_sessions?host=/cloudsql/project:region:instance"
         )
         mock_settings = MagicMock()
+        mock_settings.session_backend = "database"
         mock_settings.session_database_url = cloudsql_url
 
         mock_db_session = MagicMock()
@@ -341,6 +342,7 @@ def test_standard_host_logged_correctly(self, caplog):
         """Test that a standard PostgreSQL host is logged correctly."""
         standard_url = "postgresql+asyncpg://user:pass@db.example.com:5432/mydb"
         mock_settings = MagicMock()
+        mock_settings.session_backend = "database"
         mock_settings.session_database_url = standard_url
 
         mock_db_session = MagicMock()
@@ -360,13 +362,14 @@ def test_standard_host_logged_correctly(self, caplog):
 
         assert "host=db.example.com" in caplog.text
 
-    def test_credentials_not_leaked_on_init_failure(self, caplog):
-        """Test that database credentials are sanitized in error logs."""
+    def test_credentials_not_leaked_on_init_failure(self):
+        """Test that database credentials are sanitized in error messages."""
         db_url = (
             "postgresql+asyncpg://sessions:8dnL1i3eo4GtqwUpKKhNVA@"
             "/agent_sessions?host=/cloudsql/project:region:instance"
         )
         mock_settings = MagicMock()
+        mock_settings.session_backend = "database"
         mock_settings.session_database_url = db_url
 
         error_msg = (
@@ -376,6 +379,10 @@ def test_credentials_not_leaked_on_init_failure(self, caplog):
         )
 
         with (
+            pytest.raises(
+                RuntimeError,
+                match=r"Failed to initialize DatabaseSessionService",
+            ) as exc_info,
             patch(
                 "lightspeed_agent.api.a2a.a2a_setup.get_settings",
                 return_value=mock_settings,
@@ -384,25 +391,41 @@ def test_credentials_not_leaked_on_init_failure(self, caplog):
                 "google.adk.sessions.DatabaseSessionService",
                 side_effect=RuntimeError(error_msg),
             ),
-            caplog.at_level(logging.WARNING),
+        ):
+            _get_session_service()
+
+        # Password must not appear in the raised error
+        assert "8dnL1i3eo4GtqwUpKKhNVA" not in str(exc_info.value)
+
+        # But the sanitized URL structure should still be present for debugging
+        assert "://***@" in str(exc_info.value)
+
+    def test_memory_backend_used_when_configured(self, caplog):
+        """Test that InMemorySessionService is used when SESSION_BACKEND=memory."""
+        mock_settings = MagicMock()
+        mock_settings.session_backend = "memory"
+
+        with (
+            patch(
+                "lightspeed_agent.api.a2a.a2a_setup.get_settings",
+                return_value=mock_settings,
+            ),
+            caplog.at_level(logging.INFO),
         ):
             service = _get_session_service()
 
-        # Should fall back to InMemorySessionService
         from google.adk.sessions import InMemorySessionService
 
         assert isinstance(service, InMemorySessionService)
+        assert "InMemorySessionService" in caplog.text
 
-        # Password must not appear in logs
-        assert "8dnL1i3eo4GtqwUpKKhNVA" not in caplog.text
-
-        # But the sanitized URL structure should still be present for debugging
-        assert "://***@" in caplog.text
-
-    def test_fallback_to_inmemory_when_no_url(self, caplog):
-        """Test that InMemorySessionService is used when no session URL is set."""
+    def test_memory_backend_ignores_database_url(self, caplog):
+        """Test that SESSION_BACKEND=memory ignores SESSION_DATABASE_URL."""
         mock_settings = MagicMock()
-        mock_settings.session_database_url = ""
+        mock_settings.session_backend = "memory"
+        mock_settings.session_database_url = (
+            "postgresql+asyncpg://user:pass@host:5432/sessions"
+        )
 
         with (
             patch(
@@ -417,3 +440,29 @@ def test_fallback_to_inmemory_when_no_url(self, caplog):
 
         assert isinstance(service, InMemorySessionService)
         assert "InMemorySessionService" in caplog.text
+
+    def test_database_backend_returns_database_service(self):
+        """Test that SESSION_BACKEND=database returns DatabaseSessionService."""
+        mock_settings = MagicMock()
+        mock_settings.session_backend = "database"
+        mock_settings.session_database_url = (
+            "postgresql+asyncpg://user:pass@host:5432/sessions"
+        )
+
+        mock_db_session = MagicMock()
+
+        with (
+            patch(
+                "lightspeed_agent.api.a2a.a2a_setup.get_settings",
+                return_value=mock_settings,
+            ),
+            patch(
+                "google.adk.sessions.DatabaseSessionService",
+                mock_db_session,
+            ),
+        ):
+            _get_session_service()
+
+        mock_db_session.assert_called_once_with(
+            db_url="postgresql+asyncpg://user:pass@host:5432/sessions"
+        )