feat: Add ReadFrom parsing support to ConfigurationOptions for AZ Affinity #28

jbrinkman · 2025-08-13T14:51:48Z

Summary

This PR implements comprehensive ReadFrom parsing support in ConfigurationOptions to enable AZ (Availability Zone) affinity configuration through connection strings and programmatic configuration. This addresses issue #26 by providing a complete implementation of ReadFrom strategy parsing, validation, and serialization.

Changes Made

Core Implementation

ReadFrom Parsing: Added support for parsing readFrom and az parameters from connection strings
Strategy Validation: Implemented comprehensive validation for ReadFromStrategy and AZ parameter combinations
Serialization Support: Added ToString formatting for ReadFrom configurations with round-trip integrity
Property Validation: Enhanced ReadFrom property setter with cross-validation logic
Error Handling: Comprehensive error messages and validation throughout the pipeline

Supported ReadFrom Strategies

Primary - Always read from primary nodes
PreferReplica - Prefer replica nodes, fallback to primary
AzAffinity - Prefer replicas in the same AZ, with fallback
AzAffinityReplicasAndPrimary - Prefer nodes in the same AZ (replicas first, then primary), with fallback

Connection String Examples

localhost:6379,readFrom=Primary
localhost:6379,readFrom=PreferReplica  
localhost:6379,readFrom=AzAffinity,az=us-east-1a
localhost:6379,readFrom=AzAffinityReplicasAndPrimary,az=eu-west-1b

Test Coverage

992 lines of comprehensive end-to-end integration tests
48 test cases covering complete configuration pipeline
Connection string parsing to FFI layer verification
Error handling and validation scenarios
Round-trip serialization integrity
Backward compatibility with legacy configurations
Performance testing with concurrent connections
Both standalone and cluster client scenarios

Technical Details

Implementation Approach

Connection String Parsing: Extended DoParse method to handle readFrom and az parameters
Validation Logic: Implemented ValidateAndSetReadFrom with comprehensive strategy/AZ validation
Serialization: Added FormatReadFrom method for ToString output with proper formatting
Property Validation: Enhanced ReadFrom property setter with immediate validation
Error Propagation: Ensured validation errors propagate correctly through the entire pipeline

Validation Rules

Primary and PreferReplica strategies cannot have AZ parameters
AzAffinity and AzAffinityReplicasAndPrimary strategies require non-empty AZ parameters
Case-insensitive parsing for ReadFrom strategy values
Comprehensive error messages for all validation scenarios

Backward Compatibility

Existing configurations without ReadFrom continue to work unchanged
Default behavior preserved when no ReadFrom is specified
Legacy connection strings remain fully functional

Testing

All tests pass including:

✅ 48 new end-to-end integration tests
✅ Existing unit tests for ConfigurationOptions parsing
✅ Existing unit tests for ReadFrom property validation
✅ Integration tests for ConnectionMultiplexer ReadFrom mapping

Closes

Closes #26

Checklist

Implementation follows existing code patterns and conventions
Comprehensive test coverage with end-to-end integration tests
Backward compatibility maintained
Error handling and validation implemented
Documentation through comprehensive test examples
All existing tests continue to pass
DCO signoff included in all commits

sources/Valkey.Glide/Abstract/ConfigurationOptions.cs

tests/Valkey.Glide.IntegrationTests/ConnectionMultiplexerReadFromMappingTests.cs

tests/Valkey.Glide.IntegrationTests/ReadFromEndToEndIntegrationTests.cs

tests/Valkey.Glide.UnitTests/ConfigurationOptionsReadFromTests.cs

- Implement ParseReadFromStrategy method to convert string values to ReadFromStrategy enum - Add validation for ReadFrom strategy and AZ parameter combinations - Extend DoParse method to handle readFrom and az parameters from connection strings - Add comprehensive error handling with descriptive messages - Support case-insensitive parsing for all ReadFrom strategies - Extend ToString method to include ReadFrom and AZ in connection strings - Add comprehensive unit tests covering all parsing scenarios - Reorganize private fields to follow C# analyzer rules Addresses task 1 of GitHub issue #26 Satisfies requirements: 1.1, 1.2, 1.5, 1.6, 4.1, 4.2, 4.3, 4.4, 4.5 Signed-off-by: jbrinkman <[email protected]>

- Add FormatReadFrom method to convert ReadFrom struct to string representation - Extract FormatReadFromStrategy method as proper private method - Refactor ToString method to use new FormatReadFrom method - Ensure proper formatting for all ReadFromStrategy values - Maintain backward compatibility with existing ToString format Addresses task 2 of AZ affinity support implementation Signed-off-by: jbrinkman <[email protected]>

…parameters - Add readFrom case to the switch statement in DoParse method - Add az case to the switch statement in DoParse method - Implement proper parsing logic that creates ReadFrom struct from parsed values - Add validation during parsing to catch invalid combinations early - Support case-insensitive parsing of ReadFrom strategy values - Validate AZ parameter combinations with ReadFrom strategies Addresses task 4 from AZ affinity support specification Signed-off-by: jbrinkman <[email protected]>

- Add ConnectionMultiplexerReadFromMappingTests.cs with 12 test cases - Verify ReadFrom configuration mapping from ConfigurationOptions to ClientConfigurationBuilder - Test all ReadFromStrategy values (Primary, PreferReplica, AzAffinity, AzAffinityReplicasAndPrimary) - Verify null ReadFrom handling for backward compatibility - Test both standalone and cluster client configurations - Confirm end-to-end flow from ConfigurationOptions to ConnectionConfig Addresses task 5: Verify ConnectionMultiplexer ReadFrom mapping Requirements: 3.1, 3.2, 3.4, 6.1 Signed-off-by: jbrinkman <[email protected]>

…serialization - Add ToString output tests for each ReadFromStrategy value - Add round-trip parsing tests (Parse → ToString → Parse) - Add backward compatibility tests with existing configuration strings - Add proper AZ formatting tests in ToString output - Covers requirements 5.1-5.5 and 6.2-6.3 from AZ affinity support spec All 57 tests pass, ensuring proper serialization and deserialization of ReadFrom configurations while maintaining backward compatibility. Signed-off-by: jbrinkman <[email protected]>

…property validation - Add ReadFrom property setter validation tests for all strategies - Add Clone method ReadFrom preservation tests with comprehensive scenarios - Add null ReadFrom handling and default behavior tests - Add cross-validation tests between ReadFromStrategy and AZ parameters - Ensure proper error handling for invalid configurations - Verify independence of cloned instances - Test complex configuration scenarios with ReadFrom Addresses requirements 2.1, 2.2, 2.3, 2.4, 2.5, and 6.4 from AZ affinity support spec Signed-off-by: jbrinkman <[email protected]>

…g functionality Signed-off-by: jbrinkman <[email protected]>

…rom configuration - Add ReadFromEndToEndIntegrationTests with 48 test cases covering complete pipeline - Test connection string to FFI layer flow for all ReadFromStrategy values - Test ConfigurationOptions programmatic configuration flow - Test error handling throughout the complete configuration pipeline - Test round-trip serialization (Parse → ToString → Parse) integrity - Test backward compatibility with legacy configurations - Test performance scenarios with concurrent connections - Test FFI layer integration to verify configuration reaches Rust core - Verify AZ affinity settings are properly passed to the Rust core - Cover both standalone and cluster client scenarios - Fix test case for invalid ReadFrom strategy to avoid parsing ambiguity Implements task 12 from AZ Affinity support implementation plan. Requirements covered: 3.1, 3.2, 3.3, 3.4, 3.5 Signed-off-by: jbrinkman <[email protected]>

Signed-off-by: jbrinkman <[email protected]>

…iplexer - Updated exception message assertion in ConfigurationOptionsReadFromTests to be case insensitive. - Replaced reflection-based method invocation with direct calls to CreateClientConfigBuilder in ConnectionMultiplexerReadFromMappingTests for better readability and performance. - Added new tests to verify ReadFrom configuration flows correctly to ConnectionConfig for both standalone and cluster configurations. - Removed unnecessary reflection helper method to streamline the test code. Signed-off-by: jbrinkman <[email protected]>

Signed-off-by: jbrinkman <[email protected]>

…onMultiplexerReadFromMappingTests to use explicit type declarations for variable assignments, enhancing code clarity and consistency. Signed-off-by: jbrinkman <[email protected]>

…readability Signed-off-by: jbrinkman <[email protected]>

…figurationOptions Signed-off-by: jbrinkman <[email protected]>

…rategy type Signed-off-by: jbrinkman <[email protected]>

…figurationOptions Signed-off-by: jbrinkman <[email protected]>

…FromTests for clarity Signed-off-by: jbrinkman <[email protected]>

edlng

LGTM! I do agree with Yury's comment on cutting down the tests^

sources/Valkey.Glide/Abstract/ConfigurationOptions.cs

tests/Valkey.Glide.IntegrationTests/ReadFromEndToEndIntegrationTests.cs

tests/Valkey.Glide.UnitTests/ConfigurationOptionsReadFromTests.cs

sources/Valkey.Glide/Abstract/ConfigurationOptions.cs

…upport

Signed-off-by: Yury-Fridlyand <[email protected]>

Yury-Fridlyand · 2025-08-23T03:29:29Z

I added true e2e tests, few tests were simplified and moved to UT.

jbrinkman

I can't approve b/c it is my PR. but other than the Region issue, LGTM

jbrinkman · 2025-08-25T17:11:26Z

sources/Valkey.Glide/Abstract/ConfigurationOptions.cs

@@ -87,10 +87,11 @@ public static string TryNormalize(string value)
        }
    }

-    // Private fields
+    #region Private fields


Should we be using regions? This is one of the items that StyleCop will flag - SA1123

Oh
We have regions in other places. Is StyleCop enforced in CI pipeline or in project?
If no, we can activate it and fix all code issues in another PR.

Signed-off-by: Yury-Fridlyand <[email protected]>

yipin-chen

LGTM

jbrinkman requested a review from a team as a code owner August 13, 2025 14:51

jbrinkman force-pushed the jbrinkman/az-affinity-configurationoptions-support branch from e0d1212 to ae81ad5 Compare August 13, 2025 15:50

Yury-Fridlyand reviewed Aug 13, 2025

View reviewed changes

jbrinkman force-pushed the jbrinkman/az-affinity-configurationoptions-support branch from ae81ad5 to 353265e Compare August 13, 2025 18:37

jbrinkman added 11 commits August 15, 2025 07:42

test: Add integration tests for ConnectionMultiplexer ReadFrom mappin…

fad1808

…g functionality Signed-off-by: jbrinkman <[email protected]>

test: Resolve stylecop lint errors

53f6780

Signed-off-by: jbrinkman <[email protected]>

test: streamline ConfigurationOptions cloning process

c32220b

Signed-off-by: jbrinkman <[email protected]>

jbrinkman force-pushed the jbrinkman/az-affinity-configurationoptions-support branch from 5f74a52 to c32220b Compare August 15, 2025 11:42

jbrinkman added 2 commits August 15, 2025 10:59

test:Refactor tests in ConfigurationOptionsReadFromTests and Connecti…

b92a521

…onMultiplexerReadFromMappingTests to use explicit type declarations for variable assignments, enhancing code clarity and consistency. Signed-off-by: jbrinkman <[email protected]>

refactor: Simplify Clone method in ConfigurationOptions for improved …

626acb5

…readability Signed-off-by: jbrinkman <[email protected]>

yipin-chen mentioned this pull request Aug 15, 2025

[EPIC] C# Public Preview valkey-io/valkey-glide#4369

Open

29 tasks

jbrinkman added 4 commits August 15, 2025 13:39

refactor: Simplify ReadFrom property and clean up related code in Con…

41369c9

…figurationOptions Signed-off-by: jbrinkman <[email protected]>

fix: Ensure non-null az parameter in ReadFrom constructor based on st…

c1fbdbb

…rategy type Signed-off-by: jbrinkman <[email protected]>

refactor: Remove ValidateReadFromConfiguration method to simplify Con…

b56f189

…figurationOptions Signed-off-by: jbrinkman <[email protected]>

refactor: Remove outdated tests and simplify ConfigurationOptionsRead…

46613eb

…FromTests for clarity Signed-off-by: jbrinkman <[email protected]>

edlng approved these changes Aug 16, 2025

View reviewed changes

jduo reviewed Aug 19, 2025

View reviewed changes

sources/Valkey.Glide/Abstract/ConfigurationOptions.cs Outdated Show resolved Hide resolved

jduo reviewed Aug 19, 2025

View reviewed changes

sources/Valkey.Glide/Abstract/ConfigurationOptions.cs Outdated Show resolved Hide resolved

jduo approved these changes Aug 19, 2025

View reviewed changes

Yury-Fridlyand added 3 commits August 22, 2025 12:09

Merge branch 'main' into jbrinkman/az-affinity-configurationoptions-s…

bd94403

…upport

Add e2e test

61b8d6c

Signed-off-by: Yury-Fridlyand <[email protected]>

Update tests

2ec87f6

Signed-off-by: Yury-Fridlyand <[email protected]>

jbrinkman commented Aug 25, 2025

View reviewed changes

Yury-Fridlyand added 3 commits August 25, 2025 13:05

Fix tests.

064a428

Signed-off-by: Yury-Fridlyand <[email protected]>

Fix tests.

c2faf8d

Signed-off-by: Yury-Fridlyand <[email protected]>

Rework tests

92836a5

Signed-off-by: Yury-Fridlyand <[email protected]>

yipin-chen approved these changes Aug 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add ReadFrom parsing support to ConfigurationOptions for AZ Affinity #28

feat: Add ReadFrom parsing support to ConfigurationOptions for AZ Affinity #28

Uh oh!

jbrinkman commented Aug 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edlng left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Yury-Fridlyand commented Aug 23, 2025

Uh oh!

jbrinkman left a comment

Uh oh!

jbrinkman Aug 25, 2025

Uh oh!

Yury-Fridlyand Aug 25, 2025

Uh oh!

yipin-chen left a comment

Uh oh!

Uh oh!

feat: Add ReadFrom parsing support to ConfigurationOptions for AZ Affinity #28

Are you sure you want to change the base?

feat: Add ReadFrom parsing support to ConfigurationOptions for AZ Affinity #28

Uh oh!

Conversation

jbrinkman commented Aug 13, 2025

Summary

Changes Made

Core Implementation

Supported ReadFrom Strategies

Connection String Examples

Test Coverage

Technical Details

Implementation Approach

Validation Rules

Backward Compatibility

Testing

Closes

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edlng left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Yury-Fridlyand commented Aug 23, 2025

Uh oh!

jbrinkman left a comment

Choose a reason for hiding this comment

Uh oh!

jbrinkman Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

Yury-Fridlyand Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

yipin-chen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edlng left a comment •

edited

Loading