feat: Complete Google Cloud Firestore integration (#30)

Author: hadv

README.md

@@ -36,7 +36,7 @@ The module structure exactly mirrors the Eclipse Store Java repository for famil
 | `afs/blobstore` | `afs/blobstore/` | ✅ Complete |
 | `afs/aws/s3` | `afs/aws/s3/` | ✅ Complete |
 | `afs/azure/storage` | `afs/azure/storage/` | ✅ Complete |
-| `afs/googlecloud/firestore` | `afs/googlecloud/firestore/` | 🚧 In Progress |
+| `afs/googlecloud/firestore` | `afs/googlecloud/firestore/` | ✅ Complete |
 | `gigamap/gigamap` | `gigamap/` | ✅ Complete |
 
 ## 🚧 Eclipse Store Migration Progress
@@ -80,7 +80,7 @@ This project ports code from the [Eclipse Store Java repository](https://github.
 - **Java Source**: [`afs/blobstore`](https://github.com/eclipse-store/store/tree/main/afs/blobstore) → **C# Port**: `afs/blobstore/`
 - **Java Source**: [`afs/aws/s3`](https://github.com/eclipse-store/store/tree/main/afs/aws/s3) → **C# Port**: `afs/aws/s3/`
 - **Java Source**: [`afs/azure/storage`](https://github.com/eclipse-store/store/tree/main/afs/azure/storage) → **C# Port**: `afs/azure/storage/`
-- **Java Source**: [`afs/googlecloud/firestore`](https://github.com/eclipse-store/store/tree/main/afs/googlecloud/firestore) → **C# Port**: `afs/googlecloud/firestore/` (in progress)
+- **Java Source**: [`afs/googlecloud/firestore`](https://github.com/eclipse-store/store/tree/main/afs/googlecloud/firestore) → **C# Port**: `afs/googlecloud/firestore/`
 - **Java Source**: [`gigamap/gigamap`](https://github.com/eclipse-store/store/tree/main/gigamap/gigamap) → **C# Port**: `gigamap/`
 
 The .NET implementation maintains the same module structure, interfaces, and design patterns as the original Eclipse Store Java code while adapting to .NET conventions and leveraging C# language features.
@@ -157,8 +157,8 @@ NebulaStore follows the Eclipse Store module structure:
       - **src/** - Azure Storage connector and extensions
       - **test/** - Azure Storage integration tests
       - **NebulaStore.Afs.Azure.Storage.csproj** - Project file
-  - **googlecloud/** - Google Cloud storage backends (in progress)
-    - **firestore/** - Google Cloud Firestore integration (in progress)
+  - **googlecloud/** - Google Cloud storage backends
+    - **firestore/** - Google Cloud Firestore integration
       - **src/** - Firestore connector and extensions
       - **test/** - Firestore integration tests
       - **NebulaStore.Afs.GoogleCloud.Firestore.csproj** - Project file
@@ -339,6 +339,25 @@ var azureConfig = EmbeddedStorageConfiguration.New()
 using var azureStorage = EmbeddedStorage.Foundation(azureConfig).Start();
 ```
 
+#### Google Cloud Firestore Usage
+
+```csharp
+using NebulaStore.Afs.GoogleCloud.Firestore;
+using NebulaStore.Storage.Embedded;
+using NebulaStore.Storage.EmbeddedConfiguration;
+
+// Start with Google Cloud Firestore
+using var storage = EmbeddedStorage.StartWithFirestore("your-project-id");
+
+// Custom Firestore configuration
+var firestoreConfig = EmbeddedStorageConfiguration.New()
+    .UseFirestore("your-project-id", "my-storage", useCache: true)
+    .SetChannelCount(4)
+    .Build();
+
+using var firestoreStorage = EmbeddedStorage.Foundation(firestoreConfig).Start();
+```
+
 #### Custom Root Object
 ```csharp
 var myRoot = new MyDataClass { SomeProperty = "initial" };
@@ -407,6 +426,15 @@ The `examples/` directory contains comprehensive examples demonstrating NebulaSt
   - Crash recovery and data integrity validation
   - Transaction logging and performance monitoring
 
+### ☁️ Cloud Storage Examples
+- **`FirestoreExample.cs`** - **NEW!** Google Cloud Firestore integration including:
+  - Simple Firestore storage setup and configuration
+  - Configuration-based approach with custom settings
+  - Direct AFS usage for advanced scenarios
+  - Batch operations and large object handling
+- **`AzureStorageExample.cs`** - Azure Storage backend demonstrations
+- **`S3Example.cs`** - AWS S3 storage backend examples
+
 ### 🔍 Advanced Querying Examples
 - **`GigaMapAdvancedExample.cs`** - **NEW!** Advanced features including:
   - Eclipse Store compatible `GigaMap.Builder<T>()` API

afs/googlecloud/firestore/README.md

@@ -25,29 +25,65 @@ You must also have:
 ### Basic Usage
 
 ```csharp
-using Google.Cloud.Firestore;
-using NebulaStore.Afs.GoogleCloud.Firestore;
 using NebulaStore.Storage.Embedded;
 
-// Create Firestore connection
-var firestore = FirestoreDb.Create("your-project-id");
+// Simple Firestore storage - easiest way to get started
+using var storage = EmbeddedStorage.StartWithFirestore("your-project-id");
+
+// Use storage normally
+var root = storage.Root<MyDataClass>();
+if (root == null)
+{
+    root = new MyDataClass { SomeProperty = "value" };
+    storage.SetRoot(root);
+}
+else
+{
+    root.SomeProperty = "updated value";
+}
+storage.StoreRoot();
+```
 
-// Create AFS configuration with Firestore
+### Configuration-Based Usage
+
+```csharp
+using NebulaStore.Afs.GoogleCloud.Firestore;
+using NebulaStore.Storage.Embedded;
+using NebulaStore.Storage.EmbeddedConfiguration;
+
+// Using configuration builder with Firestore extension
 var config = EmbeddedStorageConfiguration.New()
-    .SetStorageDirectory("firestore-storage")
-    .SetUseAfs(true)
-    .SetAfsStorageType("firestore")
-    .SetAfsConnectionString("your-project-id")
+    .UseFirestore("your-project-id", "my-storage", useCache: true)
+    .SetChannelCount(4)
     .Build();
 
-using var storage = EmbeddedStorage.StartWithAfs(config);
+using var storage = EmbeddedStorage.Foundation(config).Start();
 
 // Use storage normally
 var root = storage.Root<MyDataClass>();
 root.SomeProperty = "value";
 storage.StoreRoot();
 ```
 
+### Alternative Convenience Methods
+
+```csharp
+using NebulaStore.Afs.GoogleCloud.Firestore;
+
+// Using the Firestore extensions directly
+using var storage1 = EmbeddedStorageFirestoreExtensions.StartWithFirestore("your-project-id");
+
+// With a root object
+var myData = new MyDataClass { SomeProperty = "initial value" };
+using var storage2 = EmbeddedStorageFirestoreExtensions.StartWithFirestore(myData, "your-project-id");
+
+// With custom settings
+using var storage3 = EmbeddedStorageFirestoreExtensions.StartWithFirestore(
+    "your-project-id",
+    "custom-storage-name",
+    useCache: false);
+```
+
 ### Direct AFS Usage
 
 ```csharp

afs/googlecloud/firestore/examples/FirestoreExample.cs

@@ -21,6 +21,48 @@ public class Person
         public string Email { get; set; } = string.Empty;
     }
 
+    /// <summary>
+    /// Example using the simple convenience method.
+    /// </summary>
+    public static void SimpleFirestoreExample()
+    {
+        Console.WriteLine("=== Simple Firestore Example ===");
+
+        try
+        {
+            // Start storage with Firestore backend - simplest approach
+            using var storage = EmbeddedStorage.StartWithFirestore("your-project-id");
+
+            // Create and store data
+            var root = storage.Root<Person>();
+            if (root == null)
+            {
+                root = new Person
+                {
+                    Name = "Alice Smith",
+                    Age = 28,
+                    Email = "alice.smith@example.com"
+                };
+                storage.SetRoot(root);
+            }
+            else
+            {
+                root.Age = 29; // Birthday!
+            }
+
+            storage.StoreRoot();
+            Console.WriteLine($"Stored person: {root.Name}, Age: {root.Age}");
+        }
+        catch (Exception ex)
+        {
+            Console.WriteLine($"Error: {ex.Message}");
+            Console.WriteLine("Make sure you have:");
+            Console.WriteLine("1. A Google Cloud Project with Firestore enabled");
+            Console.WriteLine("2. Proper authentication configured");
+            Console.WriteLine("3. The Google.Cloud.Firestore package installed");
+        }
+    }
+
     /// <summary>
     /// Example using the configuration-based approach.
     /// </summary>
@@ -37,7 +79,7 @@ public static void ConfigurationBasedExample()
 
         try
         {
-            // Start storage with Firestore backend
+            // Start storage with Firestore backend using configuration
             using var storage = EmbeddedStorage.Foundation(config).Start();
 
             // Create and store data

afs/googlecloud/firestore/src/EmbeddedStorageFirestoreExtensions.cs

@@ -23,20 +23,25 @@ public static IEmbeddedStorageManager StartWithFirestore(
         string? storageDirectory = null,
         bool useCache = true)
     {
-        // For now, we'll use the standard embedded storage with a note that
-        // full Firestore integration requires additional setup
+        if (string.IsNullOrEmpty(projectId))
+            throw new ArgumentException("Project ID cannot be null or empty", nameof(projectId));
+
+        // Create configuration with Firestore AFS backend
         var config = EmbeddedStorageConfiguration.New()
             .SetStorageDirectory(storageDirectory ?? "firestore-storage")
+            .SetUseAfs(true)
+            .SetAfsStorageType("firestore")
+            .SetAfsConnectionString(projectId)
+            .SetAfsUseCache(useCache)
             .Build();
 
-        // TODO: Implement full Firestore integration with custom storage connection
-        // For now, this creates a standard storage manager
+        // Start with AFS using Firestore connector
         return EmbeddedStorage.Foundation(config).Start();
     }
 
     /// <summary>
     /// Creates and starts an embedded storage manager with Google Cloud Firestore and root object.
-    /// Note: This creates a storage manager that uses Firestore directly, bypassing the standard AFS system.
+    /// This method configures the storage to use Firestore as the backend through the AFS system.
     /// </summary>
     /// <param name="root">The root object</param>
     /// <param name="projectId">The Google Cloud Project ID</param>
@@ -49,10 +54,19 @@ public static IEmbeddedStorageManager StartWithFirestore(
         string? storageDirectory = null,
         bool useCache = true)
     {
+        if (string.IsNullOrEmpty(projectId))
+            throw new ArgumentException("Project ID cannot be null or empty", nameof(projectId));
+
+        // Create configuration with Firestore AFS backend
         var config = EmbeddedStorageConfiguration.New()
             .SetStorageDirectory(storageDirectory ?? "firestore-storage")
+            .SetUseAfs(true)
+            .SetAfsStorageType("firestore")
+            .SetAfsConnectionString(projectId)
+            .SetAfsUseCache(useCache)
             .Build();
 
+        // Start with AFS using Firestore connector
         return EmbeddedStorage.Foundation(config).Start(root);
     }
 

afs/googlecloud/firestore/src/FirestoreConfigurationExtensions.cs

@@ -1,3 +1,4 @@
+using System;
 using NebulaStore.Storage.EmbeddedConfiguration;
 
 namespace NebulaStore.Afs.GoogleCloud.Firestore;