✨ Add Google Cloud Firestore backend support

Summary

Add an optional Google Cloud Firestore backend for users on GCP.

Motivation

Aspect	DynamoDB	Firestore
Latency (p50)	36-51ms (txn)	20-50ms (txn)
Transactions	✅ TransactWriteItems	✅ Batched writes
Cost model	Pay-per-request	Pay-per-op
Multi-region	✅ Global Tables	✅ Multi-region

Firestore offers:

• Native GCP integration
• Familiar document model
• Real-time listeners (could replace streams)

Usage

from zae_limiter import RateLimiter
from zae_limiter.backends.firestore import FirestoreRepository

repo = FirestoreRepository(
    project="my-project",
    database="(default)",  # or named database
    collection="rate-limits",
)
limiter = RateLimiter(repository=repo)

Implementation Considerations

Transaction Support

Firestore transactions:

@firestore.transactional
async def consume_tokens(transaction, entity_ref, bucket_refs):
    # Read all documents
    entity = await transaction.get(entity_ref)
    buckets = [await transaction.get(ref) for ref in bucket_refs]
    
    # Calculate new values
    # ...
    
    # Write all updates atomically
    for ref, new_value in updates:
        transaction.update(ref, new_value)

Note: Firestore transactions are optimistic and retry automatically.

Document Structure

rate-limits/
  entities/
    {entity_id}/
      meta: {name, parent_id, cascade, created_at}
      buckets/
        {resource}:{limit_name}: {tokens_milli, last_update_ms, version}

Change Streams (for Aggregator)

Firestore has real-time listeners:

# Could trigger Cloud Functions
def on_snapshot(doc_snapshot, changes, read_time):
    for change in changes:
        if change.type.name == 'MODIFIED':
            process_bucket_update(change.document)

doc_ref.on_snapshot(on_snapshot)

Dependencies

• #150 - Repository Protocol extraction (must be completed first)

Investigation Tasks

• Benchmark Firestore transaction latency
• Evaluate document structure for cascade
• Compare cost at various volumes
• Prototype transaction for acquire()

Acceptance Criteria

• FirestoreRepository implements RepositoryProtocol
• Token bucket via transactions
• Entity CRUD operations
• Cascade support
• Optional dependency: pip install zae-limiter[firestore]
• Benchmark comparison with DynamoDB
• Cloud Functions aggregator (or documented as unsupported)

Related

• #150 - Repository Protocol extraction
• #149 - Redis backend (similar pattern)
• #158 - Cosmos DB backend

Start with prerequisite issue #150 and compare the repository patterns in #149 and #158. Prototype the Firestore transaction for acquire(), then assess the document structure and cascade behavior. Done means a FirestoreRepository implements RepositoryProtocol with token transactions, entity CRUD, cascade support, an optional dependency, benchmark coverage, and either a Cloud Functions aggregator or documentation that it is unsupported.