Connection configuration semantics differ from the documented cross-transport contract

Summary

Several transport-neutral connection settings have different effective meanings across Apache, Netty, and CRT. Some documented zero-value behavior is not implemented, and maxConnections does not represent the same scope on each backend.

connectionMaxIdleTimeMs(0)

The API and README state that zero disables idle eviction. Current behavior:

• Apache: the factory skips connectionMaxIdleTime(...) and disables only the background reaper. AWS SDK's 60-second default remains as the connection lease expiry, so the next lease after roughly 60 seconds closes and replaces the connection.
• Netty: the factory skips the setting and falls back to Netty's five-second SDK default with idle reaping enabled.
• CRT: the factory skips the setting and falls back to the 60-second SDK default.

Relevant code:

• src/main/java/com/scylladb/alternator/AlternatorConfig.java:1298-1313, 1438-1442
• src/main/java/com/scylladb/alternator/internal/ApacheSyncClientFactory.java:61-67
• src/main/java/com/scylladb/alternator/internal/NettyAsyncClientFactory.java:62-68
• src/main/java/com/scylladb/alternator/internal/CrtSyncClientFactory.java:63-69
• src/main/java/com/scylladb/alternator/internal/CrtAsyncClientFactory.java:65-71
• README.md:187-197

Raw-socket probes confirmed replacement after 65 seconds for Apache idle-zero and after seven seconds for Netty idle-zero. Main clients using the normal 600-second default reused their original connections.

Zero connection/acquisition timeouts

AlternatorConfig documents zero as unlimited for Apache and Netty. Netty rejects zero-duration values, so the factory skips them and falls back to SDK defaults instead:

• connection acquisition: 10 seconds
• connection establishment: 2 seconds

CRT is correctly described as requiring positive durations. Apache accepts zero.

Relevant code:

• src/main/java/com/scylladb/alternator/AlternatorConfig.java:1334-1374
• src/main/java/com/scylladb/alternator/internal/NettyAsyncClientFactory.java:72-85

maxConnections scope

The API describes one maximum pool size, but backend behavior differs:

• Apache sets both a global maximum and a per-route maximum of 400.
• Netty creates a URI-keyed pool and applies 400 per endpoint.
• CRT creates a URI-keyed pool and applies 400 per endpoint.

A client with N endpoints can therefore approach 400 × N Netty/CRT connections, while Apache remains globally capped at 400.

Relevant code:

• src/main/java/com/scylladb/alternator/AlternatorConfig.java:631-650, 1280-1296
• src/main/java/com/scylladb/alternator/internal/ApacheSyncClientFactory.java:59-73
• src/main/java/com/scylladb/alternator/internal/NettyAsyncClientFactory.java:59-86
• src/main/java/com/scylladb/alternator/internal/CrtSyncClientFactory.java:60-90

Expected behavior

Transport-neutral settings should have one documented meaning, or the API should explicitly expose backend-specific differences and unsupported values.

Acceptance criteria

• Idle zero either disables eviction on supported transports or fails validation when unsupported.
• Netty zero timeout behavior matches documentation or is rejected with a clear error.
• maxConnections documentation states whether the limit is global or per endpoint for each backend.
• Tests inspect effective transport behavior, not only stored AlternatorConfig values.
• Stale comments and README claims are corrected.

Read the connection settings in src/main/java/com/scylladb/alternator/AlternatorConfig.java and compare the Apache, Netty, and CRT factory implementations listed in the issue. Start by tracing how zero idle and timeout values, plus maxConnections, reach each transport, then inspect or add tests that measure effective behavior. Done means the documented semantics, validation, tests, and README/comments agree across the supported backends.