Package com.google.genkit.plugins.firebase.session

Class FirestoreSessionStore<S>

java.lang.Object
com.google.genkit.plugins.firebase.session.FirestoreSessionStore<S>
Type Parameters:
S - the type of custom session state
All Implemented Interfaces:
SessionStore<S>, SnapshotReader<S>, SnapshotSubscriber, SnapshotWriter<S>
public final class FirestoreSessionStore<S> extends Object implements SessionStore<S>, SnapshotSubscriber
Firestore-backed implementation of SessionStore and SnapshotSubscriber.

Persists session snapshots with a sharded checkpoint + diff + pointer layout, mirroring the upstream Go (go/plugins/firebase/exp/firestore_session_store.go) and JS ( js/plugins/google-cloud/src/session-store/firestore.ts) implementations.

Storage layout

For a configured collection and per-tenant prefix (default "global"):

  • <collection>/<prefix>/snapshots/<snapshotId> — one metadata document per snapshot. kind is "checkpoint" (full state stored out-of-band in shards) or "diff" (RFC-6902 statePatch from its parent). Each document carries checkpointId (nearest checkpoint ancestor), checkpointShardCount, segmentPath (ordered diff ids from the checkpoint exclusive → this doc inclusive) and the snapshot metadata fields. statePatch and error are stored as opaque JSON strings because Firestore disallows nested arrays.
  • <collection>-shards/<prefix>/shards/<checkpointId>_<index> — checkpoint state JSON (UTF-8) split into shardSize-byte chunks.
  • <collection>-pointers/<prefix>/pointers/<sessionId> — the current leaf pointer for a session (currentSnapshotId, checkpointId, checkpointShardCount, segmentPath, currentCreatedAt, updatedAt). Carries no state.

Concurrency

saveSnapshot(java.lang.String, com.google.genkit.ai.agent.SnapshotMutator<S>, com.google.genkit.ai.agent.SessionStoreOptions) runs inside a Firestore transaction (read existing → apply mutator → write). The mutator is treated as pure and may be re-invoked on transaction retry.

  • Constructor Details

    • FirestoreSessionStore

      public FirestoreSessionStore(com.google.cloud.firestore.Firestore db)
      Creates a store with default options.
      Parameters:
      db - the Firestore client

    • FirestoreSessionStore

      public FirestoreSessionStore(com.google.cloud.firestore.Firestore db, FirestoreSessionStoreOptions options)
      Creates a store.
      Parameters:
      db - the Firestore client
      options - the store options

  • Method Details

    • saveSnapshot

      public String saveSnapshot(String snapshotId, SnapshotMutator<S> mutator, SessionStoreOptions options)
      Atomically reads the snapshot identified by snapshotId (or creates a new one), applies mutator, and persists the result.

      Runs a Firestore transaction implementing the same identity/sessionId/status defaulting contract as the in-memory reference store:

      1. Read the existing snapshot doc; reconstruct its full state when present.
      2. Apply the (pure) mutator. If it returns null, no write occurs and null is returned.
      3. Mint a UUID id when none supplied; preserve sessionId from the existing row; reject empty sessionId with INVALID_ARGUMENT; default null status to COMPLETED.
      4. Decide checkpoint vs diff and write the snapshot doc (+ shards for a checkpoint).
      5. Advance the session pointer to the new leaf (never backward).
      Specified by:
      saveSnapshot in interface SnapshotWriter<S>
      Parameters:
      snapshotId - the ID of the snapshot to write; if null the store mints a UUID
      mutator - the pure read-modify-write function; receives the existing snapshot (or null) and returns the snapshot to persist, or null to decline
      options - store options
      Returns:
      the snapshot ID that was written, or null if the mutator declined

    • getSnapshot

      public SessionSnapshot<S> getSnapshot(GetSnapshotOptions opts)
      Retrieves a session snapshot.

      When GetSnapshotOptions.getSnapshotId() is set the store returns that specific snapshot. When GetSnapshotOptions.getSessionId() is set the store resolves and returns the latest leaf snapshot for that session. Returns null if no matching snapshot exists.

      By snapshotId: loads the snapshot doc and reconstructs its full state from the nearest checkpoint's shards plus the ordered segmentPath diffs. By sessionId: reads the session pointer, then loads and reconstructs the pointed snapshot.

      Specified by:
      getSnapshot in interface SnapshotReader<S>
      Parameters:
      opts - options specifying which snapshot to retrieve; exactly one of snapshotId/sessionId must be set
      Returns:
      the matching snapshot, or null if none exists

    • onSnapshotStateChange

      public AutoCloseable onSnapshotStateChange(String snapshotId, Consumer<SessionSnapshot<?>> cb, SessionStoreOptions options)
      Subscribes to status changes for the snapshot identified by snapshotId.

      Invokes cb immediately with the current snapshot and again on every subsequent change. The returned AutoCloseable unsubscribes when closed.

      Registers a Firestore realtime listener on the snapshot document. On every event (including the initial snapshot when the document exists) the snapshot is reconstructed off-band (via a read transaction) and passed to cb. The returned AutoCloseable removes the listener.

      Specified by:
      onSnapshotStateChange in interface SnapshotSubscriber
      Parameters:
      snapshotId - the snapshot to observe
      cb - callback invoked with the updated snapshot on each change
      options - store options
      Returns:
      a handle that cancels the subscription when AutoCloseable.close() is called