feat: Migrate Eclipse Store AFS blobstore to NebulaStore

[hadv]

🚀 Abstract File System (AFS) Migration

This PR migrates the Eclipse Store Abstract File System (AFS) blobstore implementation to NebulaStore, providing a pluggable storage backend architecture with blob storage support.

✨ Key Features

Core AFS Implementation

• Complete AFS Architecture: Path abstraction, pluggable connectors, thread-safe operations
• Local Blob Store: Numbered blob system matching Eclipse Store semantics
• Caching Support: Optional caching layer for improved performance
• Thread Safety: All operations designed for concurrent access

NebulaStore Integration

• Configuration Extension: Added AFS-specific settings to IEmbeddedStorageConfiguration
• Seamless API: EmbeddedStorage.StartWithAfs() methods for easy adoption
• Storage Connection: AFS-aware storage connection with existing interface compatibility
• Statistics & Monitoring: Full integration with NebulaStore monitoring system

Advanced Features

• Batch Operations: Support for IStorer batch operations
• Garbage Collection: Full and time-budgeted GC support
• Error Handling: Comprehensive error handling and validation
• Performance Optimization: Efficient blob management and I/O operations

📁 Project Structure

Follows Eclipse Store architecture with AFS at root level:

NebulaStore/
├── afs/                           # AFS at root level (matches Eclipse Store)
│   ├── blobstore/                 # Blobstore implementation
│   │   ├── BlobStorePath.cs       # Path abstraction
│   │   ├── IBlobStoreConnector.cs # Connector interface
│   │   ├── LocalBlobStoreConnector.cs # Local file system impl
│   │   ├── BlobStoreFileSystem.cs # File system abstraction
│   │   └── BlobStoreFile.cs       # File wrappers
│   ├── types/                     # Common AFS types
│   │   └── IAfsPath.cs
│   ├── AfsStorageConnection.cs    # NebulaStore integration
│   └── README.md                  # Comprehensive documentation
├── tests/NebulaStore.Afs.Tests/   # Complete test suite
└── examples/AfsExample.cs         # Usage examples

🔧 Usage Examples

Simple AFS Usage

// Start with AFS using default settings
using var storage = EmbeddedStorage.StartWithAfs("my-storage");

var root = storage.Root<MyDataClass>();
root.SomeProperty = "value";
storage.StoreRoot();

Custom Configuration

var config = EmbeddedStorageConfiguration.New()
    .SetStorageDirectory("afs-storage")
    .SetUseAfs(true)
    .SetAfsStorageType("blobstore")
    .SetAfsUseCache(true)
    .SetChannelCount(4)
    .Build();

using var storage = EmbeddedStorage.StartWithAfs(config);

Direct AFS Operations

using var connector = new LocalBlobStoreConnector("storage", useCache: true);
using var fileSystem = BlobStoreFileSystem.New(connector);

var path = BlobStorePath.New("container", "folder", "file.txt");
var data = System.Text.Encoding.UTF8.GetBytes("Hello, AFS!");

fileSystem.IoHandler.WriteData(path, data);
var readData = fileSystem.IoHandler.ReadData(path, 0, -1);

🧪 Testing

Comprehensive Test Suite

• Unit Tests: BlobStorePathTests, LocalBlobStoreConnectorTests
• Integration Tests: AfsIntegrationTests with end-to-end scenarios
• Performance Tests: Comparison between traditional and AFS storage
• Error Handling: Comprehensive error scenario coverage

Test Coverage

• ✅ Path manipulation and validation
• ✅ File operations (create, read, write, delete, move, copy)
• ✅ Directory operations and traversal
• ✅ Caching behavior and performance
• ✅ Thread safety and concurrent access
• ✅ Configuration and integration
• ✅ Error conditions and edge cases

📊 Configuration Options

Property	Type	Default	Description
UseAfs	bool	false	Enable AFS storage
AfsStorageType	string	"blobstore"	Storage backend type
AfsConnectionString	string?	null	Connection string
AfsUseCache	bool	true	Enable caching

🔄 Migration Path

For existing NebulaStore applications:

// Before
using var storage = EmbeddedStorage.Start("storage");

// After
using var storage = EmbeddedStorage.StartWithAfs("storage");

📈 Performance Benefits

• Blob Storage: Efficient handling of large files through numbered blobs
• Caching: Optional caching layer for frequently accessed data
• Concurrent Access: Thread-safe operations with minimal locking
• I/O Optimization: Efficient read/write operations with partial access support

🔍 Files Changed

New Files

• afs/ - Complete AFS implementation
• tests/NebulaStore.Afs.Tests/ - Comprehensive test suite
• examples/AfsExample.cs - Usage examples

Modified Files

• Extended IEmbeddedStorageConfiguration with AFS options
• Updated EmbeddedStorageFoundation for AFS support
• Enhanced EmbeddedStorage with AFS factory methods
• Updated project files and solution structure

✅ Ready for Production

This implementation is:

• ✅ Feature Complete: All Eclipse Store AFS blobstore functionality
• ✅ Well Tested: Comprehensive unit and integration tests
• ✅ Documented: Complete documentation and examples
• ✅ Performance Optimized: Caching and efficient I/O operations
• ✅ Thread Safe: Designed for concurrent access
• ✅ Backward Compatible: Seamless integration with existing NebulaStore API

🎯 Future Extensibility

The AFS architecture supports additional storage backends:

• NIO-based file operations
• Database-backed storage (SQL)
• Cloud storage (AWS S3, Azure Blob, Google Cloud)
• In-memory storage (Redis)
• Custom implementations via IBlobStoreConnector

---

Pull Request opened by Augment Code with guidance from the PR author