Z-Arch Extension: firestore-sessions

firestore-sessions bootstraps Firestore-backed session state metadata.

It runs in post_project_bootstrap and enforces a fail-closed, idempotent flow:

• Optionally enables firestore.googleapis.com.
• Verifies the default Firestore database exists and is Native mode.
• Waits for the default Firestore database to report ACTIVE before document bootstrap.
• Ensures a bootstrap document exists in the configured collection (create-first on first run).
• Authenticates Firestore SDK calls with the active gcloud identity token.
• Preserves original created_at after initial bootstrap.

Install (development)

zarch ext install --editable .

zarch.yaml

extensions:
  firestore-sessions:
    type: "firestore-sessions"
    required_roles:
      - "roles/datastore.owner"
      - "roles/serviceusage.serviceUsageAdmin"
    config:
      collection_name: "zarch_sessions"
      doc_id: "sessions"
      schema_version: 1
      enable_api: true
      create_database_if_missing: true
      database_location: "us-east4"
      preflight_only: false
      retry_attempts: 3
      retry_initial_delay_seconds: 1.0
      retry_backoff_multiplier: 2.0

Hooks

• post_project_bootstrap

Config Reference

Key	Type	Default	Notes
collection_name	string	zarch_sessions	Collection used for bootstrap/session metadata.
doc_id	string	sessions	Document ID used for bootstrap/session metadata.
schema_version	integer	1	Positive integer schema marker for drift/preflight checks.
enable_api	boolean	true	When true, enables firestore.googleapis.com (unless preflight mode).
create_database_if_missing	boolean	false	When true (and not preflight), creates (default) Firestore database if absent.
database_location	string	project region	Firestore database location used when creating missing DB.
preflight_only	boolean	false	Validation-only mode; any required mutation fails.
retry_attempts	integer	3	Retry attempts for transient gcloud failures.
retry_initial_delay_seconds	float	1.0	Initial backoff delay for retries.
retry_backoff_multiplier	float	2.0	Backoff multiplier between retries.

Idempotency Guarantees

• Safe to run repeatedly.
• Existing compliant bootstrap document is left unchanged.
• created_at is written only when creating the bootstrap document.
• Schema metadata is reconciled only when drift is detected and update is safe.

Failure Behavior

• Fails fast if API enable fails (when enabled and not preflight).
• Fails if Firestore database is missing and create_database_if_missing=false.
• Creates the Firestore database when missing if create_database_if_missing=true and not in preflight mode.
• Fails if existing Firestore database is not Native mode.
• Fails if Firestore database does not become ACTIVE within configured retry/backoff limits.
• Fails if bootstrap metadata is incompatible (for example, schema downgrade).
• In preflight_only mode, fails on missing/drifted bootstrap state without mutation.

Required Roles

• roles/firestore.admin
• roles/datastore.user (required for Firestore document create/read/update operations)
• roles/serviceusage.serviceUsageAdmin (required when enable_api: true)

Notes

• Firestore database can be auto-created when create_database_if_missing=true.
• Uses only extension lifecycle hooks and project_context.gcloud(...) for CLI operations.
• Firestore SDK calls are authorized using gcloud auth print-access-token from project_context.gcloud(...).

Tests

• Unit/integration-style (in-memory, no external side effects):
  • extensions/zarch_ext_firestore_sessions/tests/test_extension.py
  • extensions/zarch_ext_firestore_sessions/tests/test_extension_integration.py
• Live integration (real GCP, non-mutating/read-only behavior):
  • extensions/zarch_ext_firestore_sessions/tests/test_extension_live_integration.py

Run default tests:

.venv/bin/pytest -q extensions/zarch_ext_firestore_sessions/tests -k "not live"

Run live non-mutating tests:

ZARCH_RUN_LIVE_GCP_TESTS=1 .venv/bin/pytest -q extensions/zarch_ext_firestore_sessions/tests/test_extension_live_integration.py

Optional project override:

ZARCH_RUN_LIVE_GCP_TESTS=1 ZARCH_LIVE_PROJECT_ID=<project-id> .venv/bin/pytest -q extensions/zarch_ext_firestore_sessions/tests/test_extension_live_integration.py