Skip to content

feat: add FirestoreSessionService for serverless session persistence#104

Open
anmolg1997 wants to merge 1 commit intogoogle:mainfrom
anmolg1997:feat/firestore-session-service
Open

feat: add FirestoreSessionService for serverless session persistence#104
anmolg1997 wants to merge 1 commit intogoogle:mainfrom
anmolg1997:feat/firestore-session-service

Conversation

@anmolg1997
Copy link

@anmolg1997 anmolg1997 commented Mar 21, 2026

Summary

Adds a FirestoreSessionService — a BaseSessionService implementation backed by Google Cloud Firestore, providing persistent, serverless session storage for Cloud Run, Cloud Functions, and other GCP environments where managing a SQL database is undesirable.

This was originally submitted as google/adk-python#4439, where maintainer @rohityan directed it to this community repo.

Changes

  • src/google/adk_community/sessions/firestore_session_service.py — full implementation
  • tests/unittests/sessions/test_firestore_session_service.py — 19 unit tests with lightweight in-memory Firestore mock (no GCP project required)
  • src/google/adk_community/sessions/__init__.py — export FirestoreSessionService
  • pyproject.toml — add firestore optional dependency group

Design Decisions

Concern Approach
1MB doc limit Events stored in Firestore subcollections, not embedded
Race conditions App/user state updates use Firestore transactions
N+1 in list_sessions Shared app/user state fetched once outside the loop
Bulk event deletion AsyncWriteBatch in 500-doc chunks
num_recent_events Server-side limit_to_last() instead of client-side slicing
Redundant reads create_session reuses state returned from transactional updates
Optional dependency google-cloud-firestore imported at runtime with clear error message
State management Three-tier (app/user/session) matching ADK conventions, temp state filtered

Addresses Review Feedback

All issues raised by Gemini Code Assist on the original PR have been addressed:

  • High: Race conditions in create_session and append_event → Firestore transactions
  • High: N+1 query in list_sessions → single shared fetch
  • Medium: Redundant state re-fetches → reuse transaction return values
  • Medium: Client-side slicing for recent events → limit_to_last()
  • Medium: One-by-one event deletion → AsyncWriteBatch with chunking

Test Plan

  • 19 unit tests covering all CRUD operations, state management, filtering, error cases
  • All tests pass without a GCP project (in-memory mock)
  • Existing Redis tests unaffected (1 pre-existing failure in test_session_state_management on main)
  • Manual validation with a real Firestore instance

Fixes #103
Ref: google/adk-python#3776

Adds a BaseSessionService implementation backed by Google Cloud
Firestore, providing persistent, serverless session storage suitable
for Cloud Run, Cloud Functions, and other GCP environments.

Key design decisions:
- Events stored in Firestore subcollections to avoid 1MB doc limit
- Three-tier state management (app/user/session) matching ADK conventions
- Atomic state updates via Firestore transactions (race-condition safe)
- Batch writes for bulk event deletion (500-doc chunks)
- Server-side query limits via limit_to_last() for num_recent_events
- google-cloud-firestore as an optional dependency

Includes 19 unit tests with a lightweight in-memory Firestore mock.

Fixes google#103
Ref: google/adk-python#3776, google/adk-python#4439
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add FirestoreSessionService for serverless session persistence

1 participant