Excalibur.Data.Firestore 3.0.0-alpha.26

Excalibur.Data.Firestore

Google Cloud Firestore data provider implementation for Excalibur cloud-native data access.

Installation

dotnet add package Excalibur.Data.Firestore

Quick Start

Configuration

// In Program.cs or Startup.cs
services.AddFirestore(options =>
{
    options.ProjectId = "your-gcp-project-id";
    options.DatabaseId = "(default)"; // Optional, defaults to (default)
    options.DefaultCollection = "your-collection";
});

// Or using configuration
services.AddFirestore(configuration.GetSection("Firestore"));

appsettings.json

{
  "Firestore": {
    "ProjectId": "your-gcp-project-id",
    "DatabaseId": "(default)",
    "DefaultCollection": "your-collection",
    "UseEmulator": false,
    "EmulatorHost": "localhost:8080"
  }
}

Features

CRUD Operations

public class OrderService
{
    private readonly FirestorePersistenceProvider _provider;

    public OrderService(FirestorePersistenceProvider provider)
    {
        _provider = provider;
    }

    public async Task<Order?> GetOrderAsync(string orderId, string tenantId)
    {
        var partitionKey = new PartitionKey(tenantId, "/tenantId");
        return await _provider.GetByIdAsync<Order>(orderId, partitionKey);
    }

    public async Task<CloudOperationResult<Order>> CreateOrderAsync(Order order)
    {
        var partitionKey = new PartitionKey(order.TenantId, "/tenantId");
        return await _provider.CreateAsync(order, partitionKey);
    }

    public async Task<CloudOperationResult<Order>> UpdateOrderAsync(Order order, string etag)
    {
        var partitionKey = new PartitionKey(order.TenantId, "/tenantId");
        return await _provider.UpdateAsync(order, partitionKey, etag);
    }
}

Queries

public async Task<IReadOnlyList<Order>> GetOrdersByStatusAsync(
    string tenantId,
    string status)
{
    var partitionKey = new PartitionKey(tenantId, "/tenantId");

    // Firestore uses collection path as partition key
    var result = await _provider.QueryAsync<Order>(
        "status = @status",
        partitionKey,
        new Dictionary<string, object> { ["status"] = status });

    return result.Documents;
}

Transactional Batches

public async Task<CloudBatchResult> ProcessOrderBatchAsync(
    string tenantId,
    Order order,
    OrderLine[] lines)
{
    var partitionKey = new PartitionKey(tenantId, "/tenantId");
    var operations = new List<ICloudBatchOperation>
    {
        new CloudBatchCreateOperation(order.Id, order)
    };

    foreach (var line in lines)
    {
        operations.Add(new CloudBatchCreateOperation(line.Id, line));
    }

    return await _provider.ExecuteBatchAsync(partitionKey, operations);
}

Real-time Change Listener

public async Task SubscribeToChangesAsync(CancellationToken cancellationToken)
{
    var subscription = await _provider.CreateChangeFeedSubscriptionAsync<Order>(
        "orders",
        new ChangeFeedOptions
        {
            StartPosition = ChangeFeedStartPosition.Now,
            MaxBatchSize = 100
        },
        cancellationToken);

    await subscription.StartAsync(cancellationToken);

    await foreach (var change in subscription.ReadChangesAsync(cancellationToken))
    {
        Console.WriteLine($"Change detected: {change.DocumentId}, Type: {change.EventType}");
        // Process the change
    }
}

Optimistic Concurrency

public async Task<CloudOperationResult<Order>> SafeUpdateAsync(
    Order order,
    string etag)
{
    var partitionKey = new PartitionKey(order.TenantId, "/tenantId");

    // ETag is derived from Firestore UpdateTime
    var result = await _provider.UpdateAsync(order, partitionKey, etag);

    if (!result.Success && result.StatusCode == 412)
    {
        // Precondition failed - document was modified since etag
        Console.WriteLine("Concurrent modification detected");
    }

    return result;
}

Health Checks

services.AddHealthChecks()
    .AddCheck<FirestoreHealthCheck>(
        name: "firestore",
        tags: new[] { "database", "gcp" });

Configuration Options

Connection Settings

*Required unless using EmulatorHost.

Performance Settings

Emulator Settings

Error Handling

The provider returns CloudOperationResult<T> with status codes for error handling:

var result = await _provider.UpdateAsync(order, partitionKey, etag);

if (!result.Success)
{
    switch (result.StatusCode)
    {
        case 404:
            Console.WriteLine("Document not found");
            break;
        case 409:
            Console.WriteLine("Document already exists");
            break;
        case 412:
            Console.WriteLine("Precondition failed - document was modified (ETag mismatch)");
            break;
        case 429:
            Console.WriteLine("Resource exhausted - too many requests");
            break;
        case 503:
            Console.WriteLine("Service unavailable - retry with backoff");
            break;
    }
}

Firestore-Specific Errors

Authentication

Firestore uses Google Cloud authentication. Configure one of:

Application Default Credentials

# Local development
gcloud auth application-default login

# In GCP (GKE, Cloud Run, etc.)
# Automatically uses service account

Service Account Key

services.AddFirestore(options =>
{
    options.ProjectId = "your-project";
    options.CredentialPath = "/path/to/service-account.json";
});

Environment Variable

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Container/Kubernetes Deployment

For containerized environments where file paths are impractical:

services.AddFirestore(options =>
{
    options.ProjectId = "your-project";
    // JSON content from Kubernetes secret or environment variable
    options.CredentialsJson = Environment.GetEnvironmentVariable("GCP_CREDENTIALS_JSON");
});

Collection Structure

Firestore uses a hierarchical document model:

// Root collection
var partitionKey = new PartitionKey("orders", "/collection");

// Subcollection
var subPartitionKey = new PartitionKey("orders/order-123/items", "/collection");

Best Practices

1. Use Composite Indexes for complex queries (required for multiple equality/range filters)
2. Monitor Read/Write Quotas via GCP Console - Firestore has per-second limits
3. Use Transactions for atomic operations across documents
4. Enable Firestore Emulator for local development and testing
5. Configure Security Rules in production - never rely on client-side validation
6. Design Document Structure Carefully - Firestore charges per document read
7. Use Batch Writes for multiple operations (max 500 per batch)
8. Prefer Shallow Hierarchies - deep subcollections increase complexity
9. Cache Frequently-Read Data - Firestore charges per read operation
10. Use Appropriate Data Types - leverage Firestore's native types (timestamps, geo points)

Emulator Support

For local development and testing:

# Start Firestore emulator
gcloud emulators firestore start --host-port=localhost:8080

services.AddFirestore(options =>
{
    options.ProjectId = "test-project";
    options.UseEmulator = true;
    options.EmulatorHost = "localhost:8080";
});

License

See LICENSE files in the repository root.