Repository navigation
Conversation
A Cassandra persistence backend needs connection configuration that works with Polaris configuration sources and supports both standalone use and Quarkus deployments. Add the Cassandra module and Java-driver dependencies, typed driver-option mapping, and programmatic session creation. Integrate CDI-managed sessions and authentication providers, the Quarkus TLS Registry, and Micrometer metrics. Validate conflicting configuration and manage session and authentication-provider lifecycles. This establishes the connection layer for the Cassandra backend. Related to apache#6024, the illustrative Cassandra commit-stack PR.
4f0c9d7 to
3f2c999
Compare
| @WithName("advanced.ssl-engine-factory.hostname-validation") | ||
| @WithDefault("true") | ||
| boolean hostnameValidation(); | ||
|
|
||
| /** | ||
| * Session-wide Cassandra request timeout. Defaults to the larger of {@code ddl-timeout} and | ||
| * {@code dml-timeout} when omitted. | ||
| */ | ||
| @WithName("request.timeout") | ||
| @JsonFormat(shape = JsonFormat.Shape.STRING) | ||
| Optional<Duration> requestTimeout(); |
There was a problem hiding this comment.
These two properties look like driver option paths (advanced.ssl-engine-factory.hostname-validation, request.timeout) but live outside the driver. subsection, which is confusing next to e.g. driver.advanced.ssl-engine-factory.hostname-validation. Also, hostname-validation is only used when tls-configuration-name is set; otherwise it's silently ignored.
Maybe use Polaris-style names instead (e.g. tls-hostname-validation, request-timeout), and document (or warn) that hostname validation only applies together with tls-configuration-name?
There was a problem hiding this comment.
Renamed these properties to tls-hostname-validation and request-timeout, and documented that the hostname setting applies only with tls-configuration-name. Updated the configuration tests, generated reference, and mTLS startup example to use the new names.
| METRICS_SESSION_ENABLED, | ||
| Arrays.stream(DefaultSessionMetric.values()).map(DefaultSessionMetric::getPath).toList()); | ||
| options.put( | ||
| METRICS_NODE_ENABLED, |
There was a problem hiding this comment.
This enables all session metrics and all per-node metrics. Node-level metrics (several of which are timers) are tagged per node, so on larger clusters this can produce a lot of metric series. And since advanced.metrics.* options are rejected in the driver subsection, operators currently have no way to reduce this.
Would it make sense to enable a smaller default set (e.g. session-level metrics plus a few node-level ones like pool.open-connections and the errors.* counters), and let operators opt into more?
There was a problem hiding this comment.
Reduced the defaults to session connected-nodes and cql-requests, plus node pool.open-connections and selected request/connection error counters. Operators can replace either category with an explicit list through driver.advanced.metrics.session.enabled or driver.advanced.metrics.node.enabled; an empty value disables that category. Histogram tuning is also allowed. Polaris still owns the Micrometer factory and metric naming. Added tests for defaults, overrides, and empty lists, including empty values read from properties.
| private static final Set<DriverOption> POLARIS_MANAGED_OPTIONS = | ||
| Set.of(REQUEST_TIMEOUT.getRawOption()); |
There was a problem hiding this comment.
Heads-up for the next PR in the stack: in #6024 the backend sets LOCAL_QUORUM/LOCAL_SERIAL explicitly on every statement, so basic.request.consistency and basic.request.serial-consistency configured through the driver subsection would be silently ignored, although the CassandraConfiguration Javadoc uses driver.basic.request.consistency=LOCAL_QUORUM as an example.
Since this PR defines the configuration surface, it seems like the right place to settle this: either add those options to POLARIS_MANAGED_OPTIONS (and change the Javadoc example), or, preferably, expose the regular and serial consistency levels as Polaris configuration, defaulting to LOCAL_QUORUM/LOCAL_SERIAL (which suit an active-passive setup), and have the backend use them.
There was a problem hiding this comment.
Agreed. The driver fixes commit now rejects both native consistency options and replaces the Javadoc example with driver.basic.request.page-size=500. The backend commit introduces Polaris consistency-level and serial-consistency-level settings, defaulting to LOCAL_QUORUM/LOCAL_SERIAL, and uses them on statements. Regular consistency accepts LOCAL_QUORUM, QUORUM, or ALL; serial consistency accepts LOCAL_SERIAL or SERIAL. Unsupported values fail before connecting. Added statement-level tests and updated the deployment examples and generated reference.
orca-review-bot
left a comment
There was a problem hiding this comment.
Nice, clean connection layer. I traced auth resolution, the conflicting-option checks and the disposers, and they look right. Main gap: CassandraDriverOptions has no tests, and it holds most of the logic. Can we add a parameterized test covering list/map parsing, dotted-path normalization, unknown paths, and each rejection rule (request timeout, metrics, config reload, TLS with tls-configuration-name, auth with auth.username, the same option set twice)? Small tests for requestTimeout defaulting and QuarkusTlsSslEngineFactory would help too. Also, CassandraBackendConfig, driverOptions(configuration) and cqlSessionBuilder(configuration, options) have no callers yet. Can we move them to the backend-factory PR, or say in the PR description that they're placeholders? No CHANGELOG entry needed while the backend can't be selected.
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
|
|
||
| ## Runtime integration | ||
|
|
||
| `CassandraBackendFactory` supports programmatic, non-Quarkus use. In a Quarkus runtime, |
There was a problem hiding this comment.
CassandraBackendFactory, the readiness health check, and the table creation/UCS notes at the end of the file aren't in this PR. Can we trim those until the follow-up PRs that add them land?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
There was a problem hiding this comment.
Keeping the README as an overview of the complete Cassandra backend illustrated in #6024. The factory, readiness check, and schema handling arrive in the later commits in that stack.
| import java.util.List; | ||
| import java.util.Map; | ||
| import java.util.Set; | ||
| import org.jspecify.annotations.NonNull; |
There was a problem hiding this comment.
jspecify isn't declared in this module's build file. It only arrives transitively through guava. Can we add compileOnly(libs.jspecify) like mongodb/inmemory do, or drop the @NonNull on this private helper?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
There was a problem hiding this comment.
Added compileOnly(libs.jspecify) directly to the Cassandra module, matching the existing backend modules.
| * | ||
| * <p>Disabling this option is unsafe and should not be used in production. | ||
| */ | ||
| @WithName("advanced.ssl-engine-factory.hostname-validation") |
There was a problem hiding this comment.
This key looks like a driver option path, but it lives outside driver.* and only matters when tls-configuration-name is set. Someone could easily try driver.advanced.ssl-engine-factory.hostname-validation instead. Can we rename it (e.g. tls-hostname-validation), or say in the Javadoc that it only applies with Quarkus TLS?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
There was a problem hiding this comment.
Renamed the property to tls-hostname-validation and documented that it applies only with tls-configuration-name. Also renamed request.timeout to request-timeout and updated the tests, generated reference, and mTLS startup example.
| import java.util.Arrays; | ||
| import java.util.Optional; | ||
|
|
||
| @ApplicationScoped |
There was a problem hiding this comment.
mongodb and dynamodb keep their Quarkus adapters in a quarkus subpackage (#5565). Can this producer and QuarkusTlsSslEngineFactory follow the same layout?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
There was a problem hiding this comment.
Moved the producer, TLS engine factory, authentication qualifier, and CDI authentication lifecycle wrapper into the quarkus subpackage. The backend builder and readiness check added in the next commit follow the same layout. Moved the corresponding tests as well.
| METRICS_SESSION_ENABLED, | ||
| Arrays.stream(DefaultSessionMetric.values()).map(DefaultSessionMetric::getPath).toList()); | ||
| options.put( | ||
| METRICS_NODE_ENABLED, |
There was a problem hiding this comment.
This turns on every node-level metric, histograms included, for every node in the cluster. On a large cluster that's a lot of meters. Is that intended, or should node metrics be opt-in?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
There was a problem hiding this comment.
Reduced the node defaults to pool.open-connections and selected error counters; node timers are no longer enabled by default. Operators can replace the defaults with an explicit metric list, or disable all node metrics with an empty driver.advanced.metrics.node.enabled value. The changes and regression tests are prepared locally.
Let operators select explicit session and node metric lists instead of enabling every metric. Use conservative defaults, support empty lists, and retain Polaris ownership of the metrics factory and naming settings. Use distinct Polaris timeout and TLS property names, clarify TLS applicability, declare JSpecify directly, and move Quarkus adapters into their own package. Reject native consistency overrides so the backend follow-up can introduce Polaris consistency settings without silently ignoring driver configuration.
| val quarkusRuntimeOnly = | ||
| configurations.dependencyScope("quarkusRuntimeOnly") { | ||
| extendsFrom(configurations.implementation.get(), configurations.runtimeOnly.get()) | ||
| // spotbugs-annotations has only a GPL license. |
There was a problem hiding this comment.
I don't see spotbugs anywhere, are you sure we need this?
I checked with:
./gradlew :polaris-server:dependencyInsight --configuration runtimeClasspath --dependency spotbugs-annotations
./gradlew :polaris-persistence-nosql-cassandra:dependencyInsight --configuration runtimeClasspath --dependency spotbugs-annotations
| * <p>Applications can provide an {@link AuthProvider} with this qualifier and select it with {@code | ||
| * auth.provider-name}. | ||
| */ | ||
| @Qualifier |
There was a problem hiding this comment.
Nit: use @Identifier from smallrye-common-annotation, and you get Literal for free.
A Cassandra persistence backend needs connection configuration that works with Polaris configuration sources and supports both standalone use and Quarkus deployments.
Add the Cassandra module and Java-driver dependencies, typed driver-option mapping, and programmatic session creation. Integrate CDI-managed sessions and authentication providers, the Quarkus TLS Registry, and Micrometer metrics. Validate conflicting configuration and manage session and authentication-provider lifecycles.
This establishes the connection layer for the Cassandra backend.
Related to #6024, the illustrative Cassandra commit-stack PR.