Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

3 watching

Forks

Latest commit

 

History

101 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Alternator - Client-side load balancing - C#

Introduction

ScyllaDB.Alternator adds client-side load balancing for ScyllaDB Alternator to the AWS SDK for .NET DynamoDB client.

DynamoDB applications normally point at one endpoint. Alternator is a distributed cluster, so a client should spread requests across live Alternator nodes and keep working when one node fails. This library discovers Alternator nodes through /localnodes, refreshes the live-node list in the background, and installs AWS SDK pipeline handlers that choose a node for each request.

The library does not replace the AWS SDK. AlternatorDynamoDBClient.builder().Build() returns a regular AmazonDynamoDBClient, and DynamoDB operations use the normal C# AWS SDK API.

Add the Package

dotnet add package ScyllaDB.Alternator

For local development from this repository:

make build
make pack

Basic Usage

using Amazon.DynamoDBv2;
using Amazon.Runtime;
using ScyllaDB.Alternator;

var credentials = new BasicAWSCredentials("myuser", "mypassword");

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .build();

If Alternator authentication is disabled, credentials can be omitted. The builder uses anonymous AWS credentials internally.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .build();

The builder also exposes C#-style method names:

AmazonDynamoDBClient client = AlternatorDynamoDBClient.Builder()
    .EndpointOverride("http://127.0.0.1:8000")
    .WithCredentials(credentials)
    .Build();

The AWS SDK for .NET still requires a region in AmazonDynamoDBConfig even when EndpointOverride sends requests to Alternator instead of an AWS DynamoDB regional endpoint. Alternator does not use this value for routing; the client discovers nodes through /localnodes and pipeline handlers choose live Alternator endpoints. The builder sets RegionEndpoint.USEast1 when no region is provided so SDK configuration, signing, and client construction have a stable default.

If that placeholder would be misleading in tracing, logging, metrics, or debug output, set the deployment or Scylla Cloud region explicitly:

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .region("eu-central-1")
    .credentialsProvider(credentials)
    .build();

The region value affects AWS SDK metadata and signing scope only; it does not change Alternator node discovery or load balancing.

Alternator API Wrapper

Use buildWithAlternatorAPI() when the application also needs Alternator-specific state, such as the live-node view.

using var alternator = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .buildWithAlternatorAPI();

AmazonDynamoDBClient client = alternator.getClient();
IReadOnlyList<Uri> liveNodes = alternator.getLiveNodes();
Uri nextNode = alternator.nextAsURI();
AlternatorLiveNodes manager = alternator.getAlternatorLiveNodes();

The wrapper owns the DynamoDB client and live-node polling. Direct node selection can trigger a refresh before the next idle polling interval. Disposing the wrapper shuts down polling and disposes the client.

Routing Scope

Routing scopes mirror the Java client API and support fallback chains.

using ScyllaDB.Alternator.Routing;

var scope = RackScope.of(
    "dc1",
    "rack1",
    DatacenterScope.of("dc1", ClusterScope.create()));

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withRoutingScope(scope)
    .build();

For cluster-wide routing in a multi-datacenter deployment, configure working seed hosts from every datacenter. ClusterScope.create() uses the bare /localnodes endpoint, and Alternator returns the nodes visible from the node that handled that request. With only one seed, discovery usually covers only that seed node's datacenter, so cluster scope will not route across datacenters unless the client is given reachable seeds from all datacenters.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .withScheme("https")
    .withPort(8043)
    .withInitialSeeds(
        "dc1-seed.example.com",
        "dc2-seed.example.com")
    .withRoutingScope(ClusterScope.create())
    .build();

Seeds passed to withInitialSeeds(...) are DNS names or IP addresses only. The scheme and port are shared by all seeds and are configured separately.

Legacy datacenter/rack helpers remain available:

AmazonDynamoDBClient client = AlternatorDynamoDBClient.Create(
    credentials,
    new Uri("http://127.0.0.1:8000"),
    datacenter: "dc1",
    rack: "rack1");

Node Health

Node health is enabled by default. Nodes move between active, quarantined, and down states based on request outcomes. Down nodes are skipped for normal routing, quarantined nodes receive limited recovery traffic, and long-running HTTP 5xx responses can be treated as server-side request timeouts rather than node failures.

Tune health behavior by building a node-health config and passing it once to the client builder:

var nodeHealth = NodeHealthStoreConfig.builder()
    .withConsecutiveServerErrorThreshold(10)
    .withQuarantineSuccessThreshold(10)
    .withQuarantinedNodeSamplingInterval(10)
    .withDownNodeProbePeriodMs(30000)
    .withServerRequestTimeoutThresholdMs(9000)
    .build();

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .withNodeHealth(nodeHealth)
    .build();

Use disabled() on the node-health config builder to keep all known nodes in the active set.

HTTP Client Configuration

The .NET SDK uses AmazonDynamoDBConfig.HttpClientFactory for transport customization. The Alternator builder configures an internal factory so TLS, header filtering, compression, connection pool tuning, and endpoint routing stay active.

Customize the default SocketsHttpHandler after Alternator defaults are applied:

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("https://127.0.0.1:8043")
    .credentialsProvider(credentials)
    .withMaxConnections(200)
    .withConnectionTimeoutMs(5000)
    .withSocketsHttpHandlerCustomizer(handler =>
    {
        handler.UseCookies = false;
    })
    .build();

withHttpClientHandlerCustomizer(...) remains available for callers that need the older HttpClientHandler API. That path cannot apply SocketsHttpHandler-only options such as pooled connection lifetime.

Use ConfigureAws(...) for C# AWS SDK configuration that belongs on AmazonDynamoDBConfig:

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .ConfigureAws(config =>
    {
        config.Timeout = TimeSpan.FromSeconds(10);
    })
    .build();

You can also provide the regular AWS SDK .NET HTTP factory directly. Java-style aliases httpClient(...) and httpClientBuilder(...) are available, but take Amazon.Runtime.HttpClientFactory because that is the C# AWS SDK transport extension point.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .httpClientFactory(myHttpClientFactory)
    .build();

Connection Pool Tuning

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withMaxConnections(200)
    .withConnectionMaxIdleTimeMs(30000)
    .withConnectionTimeToLiveMs(60000)
    .withConnectionAcquisitionTimeoutMs(5000)
    .withConnectionTimeoutMs(3000)
    .withHttpClientTimeoutMs(10000)
    .build();
Setting Default Description
maxConnections 400 Maximum connections per server.
connectionMaxIdleTimeMs 600000 Maximum idle time for pooled connections.
connectionTimeToLiveMs 0 Maximum lifetime for pooled connections; 0 means unlimited.
connectionAcquisitionTimeoutMs 10000 Stored for Java API parity; .NET does not expose a separate per-pool acquisition timeout.
connectionTimeoutMs 15000 Applied to SocketsHttpHandler.ConnectTimeout. For compatibility, setting this also updates httpClientTimeoutMs unless that value is set later.
httpClientTimeoutMs 15000 Applied to AmazonDynamoDBConfig.Timeout; use 0 to leave the AWS SDK timeout unchanged.

Additional HTTP transport aliases are available for callers using cross-SDK option names:

Alias Effective C# setting Notes
maxIdleHttpConnections maxConnections .NET exposes SocketsHttpHandler.MaxConnectionsPerServer, not a separate total idle-connection cap.
maxIdleHttpConnectionsPerHost maxConnections Maps to the per-server connection limit.
idleHttpConnectionTimeoutMs connectionMaxIdleTimeMs Maps to SocketsHttpHandler.PooledConnectionIdleTimeout.
httpClientTimeoutMs AmazonDynamoDBConfig.Timeout Controls the whole request timeout independently from socket connect timeout.

TLS

TLS options are configured on the Alternator builder and applied to the AWS SDK HTTP client factory.

var tls = TlsConfig.builder()
    .withCaCertPath("/etc/scylla/alternator-ca.pem")
    .withTrustSystemCaCerts(false)
    .build();

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("https://127.0.0.1:8043")
    .credentialsProvider(credentials)
    .withTlsConfig(tls)
    .build();

Preloaded certificates can be supplied when certificate material is already available in memory:

var tls = TlsConfig.builder()
    .withCaCertificate(caCertificate)
    .withClientCertificate(clientCertificate)
    .withTrustSystemCaCerts(false)
    .build();

A custom server certificate validation callback can be configured without replacing the HTTP client factory:

var tls = TlsConfig.builder()
    .withTrustSystemCaCerts(false)
    .withCertificateValidationCallback((sender, certificate, chain, errors) =>
        errors == SslPolicyErrors.None)
    .build();

Convenience factories:

TlsConfig trustAll = TlsConfig.trustAll();
TlsConfig systemDefault = TlsConfig.systemDefault();

TLS session resumption, including TLS session tickets when the server supports them, is enabled by default on the default .NET SocketsHttpHandler transport. It can be disabled explicitly:

var tls = TlsConfig.builder()
    .withTlsSessionResumption(false)
    .build();

.NET exposes the TLS resumption enable/disable switch but does not expose portable session ticket cache size or timeout controls through HttpClient. Use the default SocketsHttpHandler transport for this setting; the legacy withHttpClientHandlerCustomizer(...) path uses platform defaults and cannot disable TLS resumption.

The target .NET HttpClient APIs also do not expose a per-client TLS key-log writer. Runtime- or platform-level TLS key logging, when available, must be configured outside this library.

Compression and Header Optimization

Request compression is installed in the AWS SDK runtime pipeline before request signing. RequestCompressionAlgorithm.GZIP enables gzip request-body compression. NONE or null leaves request bodies uncompressed. withMinCompressionSizeBytes(...) sets the minimum request body size; bodies at or above the threshold are compressed, and bodies below the threshold are sent as-is. For seekable streams, the remaining stream length is used. Non-seekable streams are treated as compressible because their length cannot be checked without consuming the body. Requests that already include Content-Encoding: gzip are not recompressed.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withCompressionAlgorithm(RequestCompressionAlgorithm.GZIP)
    .withMinCompressionSizeBytes(2048)
    .build();

Response compression is enabled by default for gzip and deflate. The client sends Accept-Encoding: gzip, deflate when no request header is already set, and decodes supported compressed response bodies before the AWS SDK reads them. Unsupported response encodings are left unchanged.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withResponseCompression(ResponseCompressionAlgorithm.GZIP)
    .build();
AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withoutResponseCompression()
    .build();

Header optimization filters outgoing HTTP headers to an allow-list. If no allow-list is supplied, the client computes one from the effective Alternator configuration. The computed list keeps the required transport headers and adds authentication, request compression, and User-Agent headers when those features are enabled.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withCompressionAlgorithm(RequestCompressionAlgorithm.GZIP)
    .withOptimizeHeaders(true)
    .build();

Use a static whitelist when the exact header set should not change after it is configured. Static whitelists are validated against the required headers for the effective configuration.

var configBuilder = AlternatorConfig.builder()
    .withSeedNode("http://127.0.0.1:8000")
    .withCompressionAlgorithm(RequestCompressionAlgorithm.GZIP);

var headers = configBuilder.getRequiredHeaders();

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withCompressionAlgorithm(RequestCompressionAlgorithm.GZIP)
    .withOptimizeHeaders(true)
    .withHeadersWhitelist(headers)
    .build();

Use a custom optimizer when the allow-list should be computed from the final configuration.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withOptimizeHeaders(true)
    .withCustomOptimizeHeaders(config =>
        config.getRequiredHeaders().Concat(new[] { "X-Custom-Trace" }))
    .build();

User-Agent

By default, the client appends a ScyllaDB Alternator token to the AWS SDK user-agent. The builder can replace, transform, or remove the final user-agent.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .withUserAgent(userAgent => userAgent + " my-app/1.0")
    .build();
AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .withoutUserAgent()
    .build();

Key Route Affinity

Key route affinity can route qualifying write requests for the same partition key through a deterministic Alternator node order. Retries advance through the same Java/Go-compatible seeded query plan. Partition-key names can be preconfigured, or they are discovered asynchronously with DescribeTable after the first qualifying request for a table.

using ScyllaDB.Alternator.KeyRouting;

var affinity = KeyRouteAffinityConfig.builder()
    .withType(KeyRouteAffinity.RMW)
    .withPkInfo("users", "user_id")
    .build();

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withKeyRouteAffinity(affinity)
    .build();

For automatic partition-key discovery, omit withPkInfo. Requests use normal load balancing until discovery completes.

AmazonDynamoDBClient client = AlternatorDynamoDBClient.builder()
    .endpointOverride("http://127.0.0.1:8000")
    .credentialsProvider(credentials)
    .withKeyRouteAffinity(KeyRouteAffinity.ANY_WRITE)
    .build();

AlternatorLiveNodes

AlternatorLiveNodes is exposed through buildWithAlternatorAPI() for advanced inspection and compatibility with Java-style examples.

AlternatorLiveNodes liveNodes = alternator.getAlternatorLiveNodes();

List<Uri> nodes = liveNodes.getLiveNodes();
Uri localNodesEndpoint = liveNodes.nextAsURI("/localnodes", "dc=dc1");
RoutingScope scope = liveNodes.getRoutingScope();

Build, Test, and CI

make build
make check
make test-unit
make test-infrastructure
make test-integration

In CI, set IS_CICD=1 for quieter dotnet output.

Integration tests use scylla-ccm and native Scylla relocatable packages. They currently require Linux, Python 3.9 or newer, and uv. Install the repository-pinned CCM revision and run the tests with:

make ccm-install
make test-integration

make test-integration lets the test harness provision and reuse matching clusters within that test run. HTTP and HTTPS certificates, endpoint discovery, readiness, table cleanup, diagnostics, and cluster removal are managed by the harness. The Makefile also performs emergency cleanup when the test process exits abnormally.

The default cluster uses Scylla release:2025.2. Override the resolved version or CCM executable with SCYLLA_VERSION or SCYLLA_CCM_PATH. The scheduler detects host and cgroup-available memory, reserves one quarter (clamped between 512 MiB and 4 GiB), and admits at most nine physical Scylla nodes. SCYLLA_CCM_MAX_NODES may lower that ceiling and SCYLLA_CCM_AVAILABLE_MEMORY_MB may override memory detection for unusual environments.

Tests obtain clusters through explicit async leases. Reusable leases may share a matching cluster concurrently but expose no node controls; tests that stop, start, add, or remove nodes must request a private cluster. Each lease supplies unique table names and removes every table in its namespace when disposed. Private node expansion evicts idle reusable clusters when necessary, but fails immediately when the required capacity is held by active leases so that parallel tests cannot deadlock while holding their existing clusters.

await using var shared = await TestClusters.AcquireReusableAsync(ClusterSpecs.Default);
var tableName = shared.Resources.NewTableName("example");
using var client = shared.Cluster.ClientBuilder(AlternatorTransport.Http).Build();

var securedSpec = ClusterSpecs.Default.WithSecurity(new ClusterSecuritySpec(
    AuthenticationMode.Password,
    AuthorizationMode.Cassandra,
    enforceAlternatorAuthorization: true));

var privateSpec = ClusterSpecs.Default
    .WithTopology(ClusterTopology.SingleDatacenter(1))
    .WithTransports(AlternatorTransport.Http);
await using var privateCluster = await TestClusters.ProvisionPrivateAsync(privateSpec);
await privateCluster.Control.StopNodeAsync(privateCluster.Cluster.Nodes[0]);

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages