Implement PubSub Framework Infrastructure

[jbrinkman]

Overview

This issue tracks the implementation of the core PubSub framework infrastructure for the C# Valkey GLIDE client. This provides the foundational components needed to support PubSub functionality, including message handling, subscription configuration, and FFI integration.

Note: This issue focuses on the framework infrastructure only. PubSub commands are tracked separately in issue #55.

Scope

The PubSub framework implementation includes:

• Core Message Infrastructure: Message types, handlers, and queues
• Subscription Configuration: Builder patterns for standalone and cluster configurations
• FFI Integration: Callback management and native interop
• Client Integration: BaseClient PubSub support and lifecycle management
• Thread Safety: Concurrent access protection and async support

Implementation Status

✅ Completed Tasks (1-7):

• Task 1: PubSub message data structures (PubSubMessage, PubSubMessageHandler)
• Task 2: Thread-safe message queue (PubSubMessageQueue) with async support
• Task 3: Message handler for callback/queue routing with error handling
• Task 4: Subscription configuration classes with builder patterns
• Task 5: ConnectionConfiguration extensions for PubSub support
• Task 6: FFI integration for callbacks and subscription management
• Task 7: BaseClient PubSub infrastructure and lifecycle management

All tasks include comprehensive unit test coverage.

Key Components Implemented

Message Infrastructure

• PubSubMessage: Core message data structure with channel, pattern, and payload
• PubSubMessageHandler: Routes messages to callbacks or queues with error handling
• PubSubMessageQueue: Thread-safe queue with async retrieval and cancellation support

Configuration System

• BasePubSubSubscriptionConfig: Base configuration with callback support
• StandalonePubSubSubscriptionConfig: Standalone client configuration (Exact, Pattern modes)
• ClusterPubSubSubscriptionConfig: Cluster client configuration (Exact, Pattern, Sharded modes)
• Builder pattern integration with ConnectionConfiguration

FFI Integration

• PubSub callback registration and marshaling
• Native message handling and subscription management
• Memory-safe interop with Rust core

Client Integration

• BaseClient PubSub handler initialization
• Message processing and routing
• Automatic cleanup and resource management
• Immutable subscription configuration

Architecture Features

• Dual Consumption Models: Both callback-based and queue-based message handling
• Thread Safety: All operations are thread-safe with proper synchronization
• Async-First: Full async/await support with cancellation tokens
• Immutable Subscriptions: Subscriptions configured at client creation and remain immutable
• Resource Management: Automatic cleanup and proper disposal patterns

Testing Coverage

Comprehensive unit tests covering:

• Message handling and routing logic
• Thread safety under concurrent access
• Async operations with cancellation
• Configuration validation and builder patterns
• FFI integration and callback management
• Error handling and resource cleanup

Next Steps

This framework provides the foundation for:

• PubSub command implementation (tracked in C#: Pubsub Commands #55)
• Integration tests with live Valkey servers
• Performance optimization and load testing
• Documentation and usage examples

Requirements Addressed

This implementation addresses requirements 1-3, 6-12 from the PubSub specification:

• Req 1: PubSub configuration during client creation
• Req 2: Callback-based message handling
• Req 3: Queue-based message retrieval
• Req 6: Comprehensive message data structures
• Req 7: Error handling and resource management
• Req 8: Thread-safe operations
• Req 9: Async/await support
• Req 10: Configuration system integration
• Req 11: Immutable subscription configuration
• Req 12: Automatic cleanup and lifecycle management

Related Issues

• C#: Pubsub Commands #55 - PubSub Commands Implementation (depends on this framework)

Acceptance Criteria

• Core PubSub message types and data structures implemented
• Thread-safe message queue with async support
• Callback management system with error handling
• FFI integration layer for native interop
• Configuration integration with builder patterns
• BaseClient PubSub foundation and lifecycle management
• Comprehensive unit test coverage (>95%)
• Thread safety validation under concurrent access
• Proper resource cleanup and disposal patterns
• Documentation for all public APIs