ilios 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b605b28e1524aca634a188b28f9f557745673a789912e4971f173f5687d7ef6
-  data.tar.gz: 46cc89d6f8f096f926339f2e9d14e76b72858167a9332d4e53ba1800fe10f527
+  metadata.gz: dc846b97514ac6b86eccf9a06eee87d35396f26746974e6927d7d99f0bcf33ed
+  data.tar.gz: cd91086e384b4af2fc3a39cb0c5234722947dbb8dc097782a4508df9bf73615f
 SHA512:
-  metadata.gz: d7008c470792420f2ff04f03c7d48d4f267a89de816f90d1381ccef7f0c19a7a5623067c916ba58c2a3dd14e4698e68822313692b0a7e19f1e6275803297e4ce
-  data.tar.gz: 2c073c1b1b2e8227579bfd5b9e1847d4124f379615e236bf573a15a971aa55a9a26e920efa3f8e857363465cab24af2d17e49730a33043a45299f0907d81dbd6
+  metadata.gz: bf94440639db92113db0a8c06a05f2409139644268988aa7c2c94f202bab494d035fd6107596010f07222feecbe92cad8c3f14ed169061d16d91fe69db8f05f9
+  data.tar.gz: 2b514895a3a71380e5fab10198a92e1dc1a9cdea7d84d10dad344658f14efbc7884c8fa49e3c80bcd9a8cb7942f0cb1d846a7e92cfca9ae02ff8b785989c6db5

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Change Log
 
+## 1.2.0
+
+- Fix cluster setters silently ignoring invalid values in `Cluster#port`, `#protocol_version`, `#connect_timeout`, `#request_timeout` and `#resolve_timeout` (#36)
+- Fix segfault when a `Cluster` created by `allocate` or `dup` is used without running `initialize` (#37)
+- Yield the failure reason as an `Ilios::Cassandra::ExecutionError` to `Future#on_failure` blocks that accept an argument, including variadic blocks (e.g. `{ |*args| }`); zero-arity blocks are unchanged (#40)
+- The synchronous API (`Session#prepare`, `Session#execute`, `Result#next_page`, `Cluster#connect`) now raises errors carrying the server-reported message and a `#code` Integer, same as `Future#on_failure` (#40)
+- `Ilios::Cassandra::StatementError` also carries a `#code` Integer, so `#code` is answered by every error class the driver raises (#40)
+- Fix `Future#on_success` RBS signature to allow the `Statement` yielded by `prepare_async` (#42)
+
+## 1.1.2
+
+- Support username/password authentication with `Cluster#credentials` (#33)
+- Add cluster options: consistency, serial_consistency, num_threads_io, queue_size_io, core_connections_per_host, constant_reconnect, exponential_reconnect, tcp_nodelay, tcp_keepalive, connection_heartbeat_interval, connection_idle_timeout, load_balance_round_robin, load_balance_dc_aware, token_aware_routing, latency_aware_routing and use_schema (#33)
+- Accept Symbol consistency levels (e.g. `:quorum`) in `Cluster#consistency` and `Cluster#serial_consistency` (#33)
+- Fix infinite loop when binding a `list`/`set` whose element appends to the array while it is being converted (#34)
+- Fix infinite loop in `Cluster#hosts` when an element appends to the array while it is being converted (#34)
+
 ## 1.1.1
 
 - Fix out-of-bounds read when binding a `list`/`set` whose element mutates the array while it is being converted (#31)

data/README.md

@@ -171,6 +171,25 @@ Notes:
 - Because a `Symbol` map key is stored as its `String` equivalent, binding a map that contains both (for example `{ k1: 1, 'k1' => 2 }`) ends up as a single key on the server; the entry bound last wins.
 - Binding a `String` containing a NUL character (`\0`) to a `text` (or `ascii` / `varchar`) column raises `ArgumentError` (known limitation).
 
+### Authentication and cluster options
+
+Username/password authentication (Cassandra's `PasswordAuthenticator`) and
+common cluster options are configured on `Cluster` before `connect`:
+
+```ruby
+cluster = Ilios::Cassandra::Cluster.new
+cluster.hosts(['127.0.0.1'])
+cluster.credentials('username', 'password')
+cluster.consistency(:quorum) # or Ilios::Cassandra::Cluster::CONSISTENCY_QUORUM
+cluster.num_threads_io(4)
+cluster.exponential_reconnect(2_000, 60_000)
+cluster.tcp_keepalive(true, 60)
+cluster.load_balance_dc_aware('dc1')
+session = cluster.connect
+```
+
+See the RBS signatures in `sig/ilios.rbs` for the full list of options.
+
 ### Synchronous API
 `Ilios::Cassandra::Session#prepare` and `Ilios::Cassandra::Session#execute` are provided as synchronous API.
 
@@ -207,8 +226,12 @@ prepare_future.on_success { |statement|
       p result
       p "success"
     }
-    result_future.on_failure {
-      p "fail"
+    # `error` is an `Ilios::Cassandra::ExecutionError` (a StandardError with
+    # a #code Integer attribute); the block is optional-arity, so `{ p "fail" }`
+    # still works without it.
+    result_future.on_failure { |error|
+      p error.message
+      p error.code
     }
 
     futures << result_future

data/Rakefile

@@ -4,9 +4,6 @@ require 'bundler/gem_tasks'
 require 'rake/extensiontask'
 require 'rake/testtask'
 
-desc 'Run tests'
-task test: :compile
-
 task default: :test
 
 Rake::ExtensionTask.new('ilios') do |ext|
@@ -14,9 +11,10 @@ Rake::ExtensionTask.new('ilios') do |ext|
 end
 
 test_config = lambda do |t|
+  t.deps = [:compile]
   t.pattern = 'test/test_*.rb'
 end
-Rake::TestTask.new(test: :compile, &test_config)
+Rake::TestTask.new(:test, &test_config)
 
 namespace :rbs do
   desc 'Validate RBS definitions'
@@ -31,7 +29,9 @@ end
 if RUBY_PLATFORM.include?('linux')
   require 'ruby_memcheck'
 
+  RubyMemcheck.config(binary_name: 'ilios')
+
   namespace :test do
-    RubyMemcheck::TestTask.new(valgrind: :compile, &test_config)
+    RubyMemcheck::TestTask.new(:valgrind, &test_config)
   end
 end

data/docker-compose.yml

@@ -6,17 +6,32 @@ services:
     - 9042:9042
     volumes:
     - cassandra-data:/var/lib/cassandra
+  cassandra-auth:
+    image: cassandra:4
+    ports:
+      - "9043:9042"
+    command: >
+      bash -c "sed -i 's/^authenticator:.*/authenticator: PasswordAuthenticator/'
+      /etc/cassandra/cassandra.yaml
+      && exec docker-entrypoint.sh cassandra -f"
+    volumes:
+      - cassandra-auth-data:/var/lib/cassandra
   ilios:
     build:
       context: ./dockerfiles
       dockerfile: ubuntu.dockerfile
     depends_on:
     - cassandra
+    - cassandra-auth
     environment:
       CASSANDRA_HOST: cassandra
+      CASSANDRA_AUTH_HOST: cassandra-auth
+      CASSANDRA_AUTH_PORT: 9042
     command: bash -c 'sleep infinity'
     volumes:
     - "./:/opt/ilios"
 volumes:
   cassandra-data:
     driver: local
+  cassandra-auth-data:
+    driver: local

data/ext/ilios/cluster.c

@@ -23,6 +23,36 @@ static VALUE cluster_allocator(VALUE klass)
     return CREATE_CLUSTER(cassandra_cluster);
 }
 
+static void cluster_check_error(CassError error, const char *name)
+{
+    if (error != CASS_OK) {
+        rb_raise(rb_eArgError, "Invalid %s: %s", name, cass_error_desc(error));
+    }
+}
+
+// Casting a negative value to unsigned wraps it into a huge number, so check
+// the range on the signed value NUM2LONG/NUM2LL already produced. Converting a
+// second time would run to_int again, which may return a different value.
+static unsigned cluster_value_to_uint(VALUE value, const char *name)
+{
+    long v = NUM2LONG(value);
+
+    if (v < 0 || v > UINT_MAX) {
+        rb_raise(rb_eRangeError, "Invalid %s: %ld", name, v);
+    }
+    return (unsigned)v;
+}
+
+static cass_uint64_t cluster_value_to_uint64(VALUE value, const char *name)
+{
+    long long v = NUM2LL(value);
+
+    if (v < 0) {
+        rb_raise(rb_eRangeError, "Invalid %s: %lld", name, v);
+    }
+    return (cass_uint64_t)v;
+}
+
 /**
  * Creates a new cluster.
  *
@@ -32,7 +62,7 @@ static VALUE cluster_initialize(VALUE self)
 {
     CassandraCluster *cassandra_cluster;
 
-    GET_CLUSTER(self, cassandra_cluster);
+    GET_UNINITIALIZED_CLUSTER(self, cassandra_cluster);
     cassandra_cluster->cluster = cass_cluster_new();
 
     return self;
@@ -65,12 +95,10 @@ static VALUE cluster_connect(VALUE self)
     nogvl_future_wait(connect_future);
 
     if (cass_future_error_code(connect_future) != CASS_OK) {
-        char error[4096] = { 0 };
+        VALUE error = ilios_future_error_new(eConnectError, "Unable to connect", connect_future);
 
-        strncpy(error, cass_error_desc(cass_future_error_code(connect_future)), sizeof(error) - 1);
         cass_future_free(connect_future);
-        rb_raise(eConnectError, "Unable to connect: %s", error);
-        return Qnil;
+        rb_exc_raise(error);
     }
     cass_future_free(connect_future);
 
@@ -86,16 +114,18 @@ static VALUE cluster_connect(VALUE self)
 static VALUE cluster_hosts(VALUE self, VALUE hosts)
 {
     CassandraCluster *cassandra_cluster;
+    long length;
 
     GET_CLUSTER(self, cassandra_cluster);
 
     Check_Type(hosts, T_ARRAY);
-    if (RARRAY_LEN(hosts) == 0) {
+    length = RARRAY_LEN(hosts);
+    if (length == 0) {
         rb_raise(rb_eArgError, "No host exists.");
     }
 
-    for (int i = 0; i < RARRAY_LEN(hosts); i++) {
-        VALUE host = RARRAY_AREF(hosts, i);
+    for (long i = 0; i < length && i < RARRAY_LEN(hosts); i++) {
+        VALUE host = rb_ary_entry(hosts, i);
         cass_cluster_set_contact_points(cassandra_cluster->cluster, StringValueCStr(host));
     }
 
@@ -108,13 +138,14 @@ static VALUE cluster_hosts(VALUE self, VALUE hosts)
  *
  * @param port [Integer] A port number.
  * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If the port is zero or negative.
  */
 static VALUE cluster_port(VALUE self, VALUE port)
 {
     CassandraCluster *cassandra_cluster;
 
     GET_CLUSTER(self, cassandra_cluster);
-    cass_cluster_set_port(cassandra_cluster->cluster, NUM2INT(port));
+    cluster_check_error(cass_cluster_set_port(cassandra_cluster->cluster, NUM2INT(port)), "port");
 
     return self;
 }
@@ -139,17 +170,30 @@ static VALUE cluster_keyspace(VALUE self, VALUE keyspace)
 
 /**
  * Sets the protocol version. The driver will automatically downgrade to the lowest supported protocol version.
- * Default is +PROTOCOL_VERSION_V4+.
+ * Default is +PROTOCOL_VERSION_V4+, or +PROTOCOL_VERSION_DSEV1+ against DSE.
  *
- * @param timeout_ms [Integer] A connect timeout in milliseconds.
+ * The driver accepts +PROTOCOL_VERSION_V3+, +PROTOCOL_VERSION_V4+,
+ * +PROTOCOL_VERSION_DSEV1+ and +PROTOCOL_VERSION_DSEV2+ only. It ignores
+ * +PROTOCOL_VERSION_V1+ and +PROTOCOL_VERSION_V2+, which are below the lowest
+ * version it supports, and +PROTOCOL_VERSION_V5+, which is a beta version it
+ * enables through a separate setting instead. Each of those leaves the version
+ * unchanged and is reported on the driver's error log.
+ *
+ * @param version [Integer] A protocol version.
  * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
  */
 static VALUE cluster_protocol_version(VALUE self, VALUE version)
 {
     CassandraCluster *cassandra_cluster;
+    int v = NUM2INT(version);
+
+    if (v < 0) {
+        rb_raise(rb_eRangeError, "Invalid protocol_version: %d", v);
+    }
 
     GET_CLUSTER(self, cassandra_cluster);
-    cass_cluster_set_protocol_version(cassandra_cluster->cluster, NUM2INT(version));
+    cass_cluster_set_protocol_version(cassandra_cluster->cluster, v);
 
     return self;
 }
@@ -160,13 +204,14 @@ static VALUE cluster_protocol_version(VALUE self, VALUE version)
  *
  * @param timeout_ms [Integer] A connect timeout in milliseconds.
  * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
  */
 static VALUE cluster_connect_timeout(VALUE self, VALUE timeout_ms)
 {
     CassandraCluster *cassandra_cluster;
 
     GET_CLUSTER(self, cassandra_cluster);
-    cass_cluster_set_connect_timeout(cassandra_cluster->cluster, NUM2UINT(timeout_ms));
+    cass_cluster_set_connect_timeout(cassandra_cluster->cluster, cluster_value_to_uint(timeout_ms, "connect_timeout"));
 
     return self;
 }
@@ -177,13 +222,14 @@ static VALUE cluster_connect_timeout(VALUE self, VALUE timeout_ms)
  *
  * @param timeout_ms [Integer] A request timeout in milliseconds.
  * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
  */
 static VALUE cluster_request_timeout(VALUE self, VALUE timeout_ms)
 {
     CassandraCluster *cassandra_cluster;
 
     GET_CLUSTER(self, cassandra_cluster);
-    cass_cluster_set_request_timeout(cassandra_cluster->cluster, NUM2UINT(timeout_ms));
+    cass_cluster_set_request_timeout(cassandra_cluster->cluster, cluster_value_to_uint(timeout_ms, "request_timeout"));
 
     return self;
 }
@@ -194,13 +240,14 @@ static VALUE cluster_request_timeout(VALUE self, VALUE timeout_ms)
  *
  * @param timeout_ms [Integer] A request timeout in milliseconds.
  * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
  */
 static VALUE cluster_resolve_timeout(VALUE self, VALUE timeout_ms)
 {
     CassandraCluster *cassandra_cluster;
 
     GET_CLUSTER(self, cassandra_cluster);
-    cass_cluster_set_resolve_timeout(cassandra_cluster->cluster, NUM2UINT(timeout_ms));
+    cass_cluster_set_resolve_timeout(cassandra_cluster->cluster, cluster_value_to_uint(timeout_ms, "resolve_timeout"));
 
     return self;
 }
@@ -215,13 +262,407 @@ static VALUE cluster_resolve_timeout(VALUE self, VALUE timeout_ms)
 static VALUE cluster_constant_speculative_execution_policy(VALUE self, VALUE constant_delay_ms, VALUE max_speculative_executions)
 {
     CassandraCluster *cassandra_cluster;
+    long delay = NUM2LONG(constant_delay_ms);
+    int max_executions = NUM2INT(max_speculative_executions);
 
-    if (NUM2LONG(constant_delay_ms) < 0 || NUM2INT(max_speculative_executions) < 0) {
+    if (delay < 0 || max_executions < 0) {
         rb_raise(rb_eArgError, "Bad parameters.");
     }
 
     GET_CLUSTER(self, cassandra_cluster);
-    cass_cluster_set_constant_speculative_execution_policy(cassandra_cluster->cluster, NUM2LONG(constant_delay_ms), NUM2INT(max_speculative_executions));
+    cluster_check_error(cass_cluster_set_constant_speculative_execution_policy(cassandra_cluster->cluster, delay, max_executions), "constant_speculative_execution_policy");
+
+    return self;
+}
+
+/**
+ * Sets credentials for plain text authentication.
+ *
+ * @param username [String] A username.
+ * @param password [String] A password.
+ * @return [Cassandra::Cluster] self.
+ */
+static VALUE cluster_credentials(VALUE self, VALUE username, VALUE password)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    // The driver copies both strings into its own memory
+    // (cluster_config.cpp: cass_cluster_set_credentials_n), so the Ruby
+    // strings do not need to be retained.
+    cass_cluster_set_credentials(cassandra_cluster->cluster, StringValueCStr(username), StringValueCStr(password));
+
+    return self;
+}
+
+// The driver only rejects CASS_CONSISTENCY_UNKNOWN (0xFFFF) at set time; any
+// other out-of-range value is accepted and later fails every query with an
+// opaque protocol error, so validate the range here. This also keeps UNKNOWN
+// away from the driver, which is why the setters ignore its return value.
+static void cluster_check_consistency(long value, const char *name)
+{
+    if (value < CASS_CONSISTENCY_ANY || value > CASS_CONSISTENCY_LOCAL_ONE) {
+        rb_raise(rb_eArgError, "Invalid %s: %ld", name, value);
+    }
+}
+
+static struct {
+    const char *name;
+    CassConsistency consistency;
+    ID id;
+} cluster_consistency_symbols[] = {
+    { "any", CASS_CONSISTENCY_ANY, 0 },
+    { "one", CASS_CONSISTENCY_ONE, 0 },
+    { "two", CASS_CONSISTENCY_TWO, 0 },
+    { "three", CASS_CONSISTENCY_THREE, 0 },
+    { "quorum", CASS_CONSISTENCY_QUORUM, 0 },
+    { "all", CASS_CONSISTENCY_ALL, 0 },
+    { "local_quorum", CASS_CONSISTENCY_LOCAL_QUORUM, 0 },
+    { "each_quorum", CASS_CONSISTENCY_EACH_QUORUM, 0 },
+    { "serial", CASS_CONSISTENCY_SERIAL, 0 },
+    { "local_serial", CASS_CONSISTENCY_LOCAL_SERIAL, 0 },
+    { "local_one", CASS_CONSISTENCY_LOCAL_ONE, 0 },
+};
+
+// Accepts either an Integer consistency constant or a Symbol such as
+// +:quorum+/+:local_serial+ naming one of the CONSISTENCY_* constants.
+static CassConsistency cluster_value_to_consistency(VALUE value, const char *name)
+{
+    long v;
+
+    if (SYMBOL_P(value)) {
+        // rb_sym2id would intern an unknown Symbol and leave it uncollectable, so
+        // repeated invalid values grow memory with no way to reclaim it.
+        VALUE name_value = value;
+        ID id = rb_check_id(&name_value);
+
+        for (size_t i = 0; id && i < sizeof(cluster_consistency_symbols) / sizeof(cluster_consistency_symbols[0]); i++) {
+            if (id == cluster_consistency_symbols[i].id) {
+                return cluster_consistency_symbols[i].consistency;
+            }
+        }
+        rb_raise(rb_eArgError, "Invalid %s: %"PRIsVALUE"", name, value);
+    }
+
+    v = NUM2LONG(value);
+    cluster_check_consistency(v, name);
+    return (CassConsistency)v;
+}
+
+/**
+ * Sets the default consistency level of the statement.
+ * Default is +CONSISTENCY_LOCAL_ONE+.
+ *
+ * @param consistency [Integer, Symbol] A consistency level.
+ *   Symbols such as +:quorum+ or +:local_serial+ are also accepted.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If an invalid consistency level was given.
+ * @raise [RangeError] If the value does not fit in a C long.
+ */
+static VALUE cluster_consistency(VALUE self, VALUE consistency)
+{
+    CassandraCluster *cassandra_cluster;
+    CassConsistency consistency_value = cluster_value_to_consistency(consistency, "consistency");
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_consistency(cassandra_cluster->cluster, consistency_value);
+
+    return self;
+}
+
+/**
+ * Sets the default serial consistency level of the statement.
+ * Default is +CONSISTENCY_ANY+.
+ *
+ * @param consistency [Integer, Symbol] A serial consistency level. Only
+ *   +CONSISTENCY_SERIAL+/+CONSISTENCY_LOCAL_SERIAL+ (or +:serial+/+:local_serial+)
+ *   are accepted.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If an invalid consistency level was given, or if it is
+ *   not +CONSISTENCY_SERIAL+ or +CONSISTENCY_LOCAL_SERIAL+.
+ * @raise [RangeError] If the value does not fit in a C long.
+ */
+static VALUE cluster_serial_consistency(VALUE self, VALUE consistency)
+{
+    CassandraCluster *cassandra_cluster;
+    CassConsistency consistency_value = cluster_value_to_consistency(consistency, "serial_consistency");
+
+    // Cassandra only accepts SERIAL/LOCAL_SERIAL as a serial consistency
+    // level (used for lightweight transactions); any other value passes
+    // the generic range check above but is later rejected by the server
+    // at query time with an opaque error, so validate it here.
+    if (consistency_value != CASS_CONSISTENCY_SERIAL && consistency_value != CASS_CONSISTENCY_LOCAL_SERIAL) {
+        rb_raise(rb_eArgError, "Invalid serial_consistency: %"PRIsVALUE"", consistency);
+    }
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_serial_consistency(cassandra_cluster->cluster, consistency_value);
+
+    return self;
+}
+
+/**
+ * Sets the number of IO threads that will handle query requests.
+ * Default is +1+.
+ *
+ * @param num_threads [Integer] A number of IO threads.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If zero was given.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_num_threads_io(VALUE self, VALUE num_threads)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cluster_check_error(cass_cluster_set_num_threads_io(cassandra_cluster->cluster, cluster_value_to_uint(num_threads, "num_threads_io")), "num_threads_io");
+
+    return self;
+}
+
+/**
+ * Sets the size of the fixed size queue that stores pending requests.
+ * Default is +8192+.
+ *
+ * @param queue_size [Integer] A queue size.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If zero was given.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_queue_size_io(VALUE self, VALUE queue_size)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cluster_check_error(cass_cluster_set_queue_size_io(cassandra_cluster->cluster, cluster_value_to_uint(queue_size, "queue_size_io")), "queue_size_io");
+
+    return self;
+}
+
+/**
+ * Sets the number of connections made to each server in each IO thread.
+ * Default is +1+.
+ *
+ * @param num_connections [Integer] A number of connections.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If zero was given.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_core_connections_per_host(VALUE self, VALUE num_connections)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cluster_check_error(cass_cluster_set_core_connections_per_host(cassandra_cluster->cluster, cluster_value_to_uint(num_connections, "core_connections_per_host")), "core_connections_per_host");
+
+    return self;
+}
+
+/**
+ * Configures the cluster to use a reconnection policy that waits a constant
+ * time between each reconnection attempt.
+ * The exponential policy is used unless this method is called.
+ *
+ * @param delay_ms [Integer] A delay in milliseconds.
+ * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_constant_reconnect(VALUE self, VALUE delay_ms)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_constant_reconnect(cassandra_cluster->cluster, cluster_value_to_uint64(delay_ms, "constant_reconnect"));
+
+    return self;
+}
+
+/**
+ * Configures the cluster to use a reconnection policy that waits
+ * exponentially longer between each reconnection attempt; however
+ * will maintain a constant delay once the maximum delay is reached.
+ * This is the default policy, with a base delay of +2000+ milliseconds and
+ * a maximum delay of +60000+ milliseconds.
+ *
+ * @param base_delay_ms [Integer] A base delay in milliseconds.
+ * @param max_delay_ms [Integer] A maximum delay in milliseconds.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If the base delay is 1 or less, the maximum delay is 1 or less,
+ *   or the maximum delay is less than the base delay.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_exponential_reconnect(VALUE self, VALUE base_delay_ms, VALUE max_delay_ms)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cluster_check_error(cass_cluster_set_exponential_reconnect(cassandra_cluster->cluster, cluster_value_to_uint64(base_delay_ms, "exponential_reconnect base_delay_ms"), cluster_value_to_uint64(max_delay_ms, "exponential_reconnect max_delay_ms")), "exponential_reconnect");
+
+    return self;
+}
+
+/**
+ * Enables/Disables Nagle's algorithm on the connections.
+ * Default is +true+ (disables Nagle's algorithm).
+ *
+ * @param enabled [Boolean] Whether to disable Nagle's algorithm.
+ * @return [Cassandra::Cluster] self.
+ */
+static VALUE cluster_tcp_nodelay(VALUE self, VALUE enabled)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_tcp_nodelay(cassandra_cluster->cluster, RTEST(enabled) ? cass_true : cass_false);
+
+    return self;
+}
+
+/**
+ * Enables/Disables TCP keep-alive.
+ * Default is +false+ (disabled).
+ *
+ * @param enabled [Boolean] Whether to enable TCP keep-alive.
+ * @param delay_secs [Integer] The initial delay in seconds. Ignored when disabled.
+ * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_tcp_keepalive(VALUE self, VALUE enabled, VALUE delay_secs)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_tcp_keepalive(cassandra_cluster->cluster, RTEST(enabled) ? cass_true : cass_false, cluster_value_to_uint(delay_secs, "tcp_keepalive delay_secs"));
+
+    return self;
+}
+
+/**
+ * Sets the amount of time between heartbeat messages and controls the amount
+ * of time the connection must be idle before sending heartbeat messages.
+ * This is useful for preventing intermediate network devices from dropping connections.
+ * Default is +30+ seconds.
+ *
+ * @param interval_secs [Integer] An interval in seconds. +0+ disables heartbeat messages.
+ * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_connection_heartbeat_interval(VALUE self, VALUE interval_secs)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_connection_heartbeat_interval(cassandra_cluster->cluster, cluster_value_to_uint(interval_secs, "connection_heartbeat_interval"));
+
+    return self;
+}
+
+/**
+ * Sets the amount of time a connection is allowed to be without a successful
+ * heartbeat response before being terminated and scheduled for reconnection.
+ * Default is +60+ seconds.
+ *
+ * @param timeout_secs [Integer] A timeout in seconds.
+ * @return [Cassandra::Cluster] self.
+ * @raise [RangeError] If a negative value was given.
+ */
+static VALUE cluster_connection_idle_timeout(VALUE self, VALUE timeout_secs)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_connection_idle_timeout(cassandra_cluster->cluster, cluster_value_to_uint(timeout_secs, "connection_idle_timeout"));
+
+    return self;
+}
+
+/**
+ * Configures the cluster to use round-robin load balancing.
+ * The driver discovers all nodes in a cluster and cycles through them per request.
+ *
+ * @return [Cassandra::Cluster] self.
+ */
+static VALUE cluster_load_balance_round_robin(VALUE self)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_load_balance_round_robin(cassandra_cluster->cluster);
+
+    return self;
+}
+
+/**
+ * Configures the cluster to use DC-aware load balancing.
+ * For each query, all live nodes in a primary 'local' DC are tried first,
+ * followed by any node from other DCs.
+ *
+ * @param local_dc [String] The primary data center to try first.
+ * @return [Cassandra::Cluster] self.
+ * @raise [ArgumentError] If an invalid data center name was given.
+ */
+static VALUE cluster_load_balance_dc_aware(VALUE self, VALUE local_dc)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    // The 3rd and 4th parameters (used_hosts_per_remote_dc and
+    // allow_remote_dcs_for_local_cl) are deprecated in driver 2.16, so they
+    // are fixed to 0/cass_false and not exposed to Ruby.
+    cluster_check_error(cass_cluster_set_load_balance_dc_aware(cassandra_cluster->cluster, StringValueCStr(local_dc), 0, cass_false), "load_balance_dc_aware");
+
+    return self;
+}
+
+/**
+ * Configures the cluster to use token-aware request routing or not.
+ * Default is +true+ (enabled).
+ *
+ * @param enabled [Boolean] Whether to enable token-aware routing.
+ * @return [Cassandra::Cluster] self.
+ */
+static VALUE cluster_token_aware_routing(VALUE self, VALUE enabled)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_token_aware_routing(cassandra_cluster->cluster, RTEST(enabled) ? cass_true : cass_false);
+
+    return self;
+}
+
+/**
+ * Configures the cluster to use latency-aware request routing or not.
+ * Default is +false+ (disabled).
+ *
+ * @param enabled [Boolean] Whether to enable latency-aware routing.
+ * @return [Cassandra::Cluster] self.
+ */
+static VALUE cluster_latency_aware_routing(VALUE self, VALUE enabled)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_latency_aware_routing(cassandra_cluster->cluster, RTEST(enabled) ? cass_true : cass_false);
+
+    return self;
+}
+
+/**
+ * Enables/Disables retrieving and updating schema metadata. Disabling this
+ * can be useful to improve startup performance, but it means that
+ * 'Session#schema_metadata'-like features will not work.
+ * Default is +true+ (enabled).
+ *
+ * @param enabled [Boolean] Whether to keep schema metadata synchronized.
+ * @return [Cassandra::Cluster] self.
+ */
+static VALUE cluster_use_schema(VALUE self, VALUE enabled)
+{
+    CassandraCluster *cassandra_cluster;
+
+    GET_CLUSTER(self, cassandra_cluster);
+    cass_cluster_set_use_schema(cassandra_cluster->cluster, RTEST(enabled) ? cass_true : cass_false);
 
     return self;
 }
@@ -256,6 +697,10 @@ static void cluster_compact(void *ptr)
 
 void Init_cluster(void)
 {
+    for (size_t i = 0; i < sizeof(cluster_consistency_symbols) / sizeof(cluster_consistency_symbols[0]); i++) {
+        cluster_consistency_symbols[i].id = rb_intern(cluster_consistency_symbols[i].name);
+    }
+
     rb_define_alloc_func(cCluster, cluster_allocator);
     rb_define_method(cCluster, "initialize", cluster_initialize, 0);
     rb_define_method(cCluster, "connect", cluster_connect, 0);
@@ -267,6 +712,23 @@ void Init_cluster(void)
     rb_define_method(cCluster, "request_timeout", cluster_request_timeout, 1);
     rb_define_method(cCluster, "resolve_timeout", cluster_resolve_timeout, 1);
     rb_define_method(cCluster, "constant_speculative_execution_policy", cluster_constant_speculative_execution_policy, 2);
+    rb_define_method(cCluster, "credentials", cluster_credentials, 2);
+    rb_define_method(cCluster, "consistency", cluster_consistency, 1);
+    rb_define_method(cCluster, "serial_consistency", cluster_serial_consistency, 1);
+    rb_define_method(cCluster, "num_threads_io", cluster_num_threads_io, 1);
+    rb_define_method(cCluster, "queue_size_io", cluster_queue_size_io, 1);
+    rb_define_method(cCluster, "core_connections_per_host", cluster_core_connections_per_host, 1);
+    rb_define_method(cCluster, "constant_reconnect", cluster_constant_reconnect, 1);
+    rb_define_method(cCluster, "exponential_reconnect", cluster_exponential_reconnect, 2);
+    rb_define_method(cCluster, "tcp_nodelay", cluster_tcp_nodelay, 1);
+    rb_define_method(cCluster, "tcp_keepalive", cluster_tcp_keepalive, 2);
+    rb_define_method(cCluster, "connection_heartbeat_interval", cluster_connection_heartbeat_interval, 1);
+    rb_define_method(cCluster, "connection_idle_timeout", cluster_connection_idle_timeout, 1);
+    rb_define_method(cCluster, "load_balance_round_robin", cluster_load_balance_round_robin, 0);
+    rb_define_method(cCluster, "load_balance_dc_aware", cluster_load_balance_dc_aware, 1);
+    rb_define_method(cCluster, "token_aware_routing", cluster_token_aware_routing, 1);
+    rb_define_method(cCluster, "latency_aware_routing", cluster_latency_aware_routing, 1);
+    rb_define_method(cCluster, "use_schema", cluster_use_schema, 1);
 
     rb_define_const(cCluster, "PROTOCOL_VERSION_V1", INT2NUM(CASS_PROTOCOL_VERSION_V1));
     rb_define_const(cCluster, "PROTOCOL_VERSION_V2", INT2NUM(CASS_PROTOCOL_VERSION_V2));
@@ -275,4 +737,16 @@ void Init_cluster(void)
     rb_define_const(cCluster, "PROTOCOL_VERSION_V5", INT2NUM(CASS_PROTOCOL_VERSION_V5));
     rb_define_const(cCluster, "PROTOCOL_VERSION_DSEV1", INT2NUM(CASS_PROTOCOL_VERSION_DSEV1));
     rb_define_const(cCluster, "PROTOCOL_VERSION_DSEV2", INT2NUM(CASS_PROTOCOL_VERSION_DSEV2));
+
+    rb_define_const(cCluster, "CONSISTENCY_ANY", INT2NUM(CASS_CONSISTENCY_ANY));
+    rb_define_const(cCluster, "CONSISTENCY_ONE", INT2NUM(CASS_CONSISTENCY_ONE));
+    rb_define_const(cCluster, "CONSISTENCY_TWO", INT2NUM(CASS_CONSISTENCY_TWO));
+    rb_define_const(cCluster, "CONSISTENCY_THREE", INT2NUM(CASS_CONSISTENCY_THREE));
+    rb_define_const(cCluster, "CONSISTENCY_QUORUM", INT2NUM(CASS_CONSISTENCY_QUORUM));
+    rb_define_const(cCluster, "CONSISTENCY_ALL", INT2NUM(CASS_CONSISTENCY_ALL));
+    rb_define_const(cCluster, "CONSISTENCY_LOCAL_QUORUM", INT2NUM(CASS_CONSISTENCY_LOCAL_QUORUM));
+    rb_define_const(cCluster, "CONSISTENCY_EACH_QUORUM", INT2NUM(CASS_CONSISTENCY_EACH_QUORUM));
+    rb_define_const(cCluster, "CONSISTENCY_SERIAL", INT2NUM(CASS_CONSISTENCY_SERIAL));
+    rb_define_const(cCluster, "CONSISTENCY_LOCAL_SERIAL", INT2NUM(CASS_CONSISTENCY_LOCAL_SERIAL));
+    rb_define_const(cCluster, "CONSISTENCY_LOCAL_ONE", INT2NUM(CASS_CONSISTENCY_LOCAL_ONE));
 }

data/ext/ilios/future.c

@@ -136,7 +136,13 @@ static void future_result_success_yield(CassandraFuture *cassandra_future)
 static void future_result_failure_yield(CassandraFuture *cassandra_future)
 {
     if (cassandra_future->on_failure_block) {
-        rb_proc_call_with_block(cassandra_future->on_failure_block, 0, NULL, Qnil);
+        if (rb_proc_arity(cassandra_future->on_failure_block)) {
+            VALUE error = ilios_future_error_new(eExecutionError, NULL, cassandra_future->future);
+
+            rb_proc_call_with_block(cassandra_future->on_failure_block, 1, &error, Qnil);
+        } else {
+            rb_proc_call_with_block(cassandra_future->on_failure_block, 0, NULL, Qnil);
+        }
     }
 }
 
@@ -317,6 +323,9 @@ static VALUE future_on_failure_synchronize(VALUE future)
 /**
  * Run block when future resolves to error.
  *
+ * @yieldparam error [Cassandra::ExecutionError] The failure reason. Only
+ *   yielded when the block accepts an argument; a zero-arity block is still
+ *   called with no arguments.
  * @return [Cassandra::Future] self.
  * @raise [Cassandra::ExecutionError] If this method will be called twice.
  * @raise [ArgumentError] If no block was given.

data/ext/ilios/ilios.c

@@ -1,5 +1,7 @@
 #include "ilios.h"
 
+#include <string.h>
+
 VALUE mIlios;
 VALUE mCassandra;
 VALUE cCluster;
@@ -21,6 +23,7 @@ VALUE id_push;
 VALUE id_pop;
 VALUE id_alive;
 VALUE id_report_on_exception;
+VALUE id_code;
 VALUE sym_unsupported_column_type;
 
 #if defined(HAVE_MALLOC_USABLE_SIZE)
@@ -74,6 +77,45 @@ static VALUE cassandra_set_log_level(VALUE self, VALUE log_level)
     return self;
 }
 
+VALUE ilios_error_new(VALUE exception_class, VALUE message, CassError error_code)
+{
+    VALUE error = rb_exc_new_str(exception_class, message);
+
+    rb_ivar_set(error, id_code, INT2NUM(error_code));
+
+    return error;
+}
+
+VALUE ilios_future_error_new(VALUE exception_class, const char *prefix, CassFuture *future)
+{
+    CassError error_code;
+    const char *message;
+    size_t message_length;
+    VALUE body;
+    VALUE full_message;
+
+    error_code = cass_future_error_code(future);
+    cass_future_error_message(future, &message, &message_length);
+    if (message_length == 0) {
+        message = cass_error_desc(error_code);
+        message_length = strlen(message);
+    }
+
+    // The driver hands back the server's raw bytes, which rb_str_new would
+    // tag ASCII-8BIT; CQL identifiers and literals are UTF-8, so tag it
+    // UTF-8 and keep the prefixed message in that encoding too. The message
+    // can also carry driver-local text (strerror output, host names), which
+    // is not guaranteed UTF-8, so replace invalid bytes rather than handing
+    // back a string that raises ArgumentError on the first regexp match.
+    body = rb_utf8_str_new(message, message_length);
+    if (rb_enc_str_coderange(body) == ENC_CODERANGE_BROKEN) {
+        body = rb_str_scrub(body, Qnil);
+    }
+    full_message = prefix ? rb_enc_sprintf(rb_utf8_encoding(), "%s: %"PRIsVALUE, prefix, body) : body;
+
+    return ilios_error_new(exception_class, full_message, error_code);
+}
+
 void Init_ilios(void)
 {
     rb_ext_ractor_safe(true);
@@ -88,6 +130,11 @@ void Init_ilios(void)
     eConnectError = rb_define_class_under(mCassandra, "ConnectError", rb_eStandardError);
     eExecutionError = rb_define_class_under(mCassandra, "ExecutionError", rb_eStandardError);
     eStatementError = rb_define_class_under(mCassandra, "StatementError", rb_eStandardError);
+    // @code is only set on errors built by ilios_error_new; the ones raised
+    // elsewhere via plain rb_raise leave #code nil.
+    rb_define_attr(eExecutionError, "code", 1, 0);
+    rb_define_attr(eConnectError, "code", 1, 0);
+    rb_define_attr(eStatementError, "code", 1, 0);
 
     cSizedQueue = rb_const_get(rb_cThread, rb_intern("SizedQueue"));
     rb_require("set");
@@ -101,6 +148,7 @@ void Init_ilios(void)
     id_pop = rb_intern("pop");
     id_alive = rb_intern("alive?");
     id_report_on_exception = rb_intern("report_on_exception=");
+    id_code = rb_intern("@code");
     sym_unsupported_column_type = ID2SYM(rb_intern("unsupported_column_type"));
 
     rb_define_module_function(mCassandra, "log_level", cassandra_set_log_level, 1);

data/ext/ilios/ilios.h

@@ -11,7 +11,16 @@
 
 #define DEFAULT_PAGE_SIZE 10000
 
-#define GET_CLUSTER(obj, var)   TypedData_Get_Struct(obj, CassandraCluster, &cassandra_cluster_data_type, var)
+// Cluster exposes an allocator, so allocate and dup both produce an instance
+// that never ran initialize. Reject it here instead of handing NULL to the
+// driver, which segfaults.
+#define GET_CLUSTER(obj, var)   do { \
+    GET_UNINITIALIZED_CLUSTER(obj, var); \
+    if ((var)->cluster == NULL) { \
+        rb_raise(rb_eRuntimeError, "uninitialized Ilios::Cassandra::Cluster"); \
+    } \
+} while (0)
+#define GET_UNINITIALIZED_CLUSTER(obj, var) TypedData_Get_Struct(obj, CassandraCluster, &cassandra_cluster_data_type, var)
 #define GET_SESSION(obj, var)   TypedData_Get_Struct(obj, CassandraSession, &cassandra_session_data_type, var)
 #define GET_STATEMENT(obj, var) TypedData_Get_Struct(obj, CassandraStatement, &cassandra_statement_data_type, var)
 #define GET_RESULT(obj, var)    TypedData_Get_Struct(obj, CassandraResult, &cassandra_result_data_type, var)
@@ -118,6 +127,7 @@ extern VALUE id_push;
 extern VALUE id_pop;
 extern VALUE id_alive;
 extern VALUE id_report_on_exception;
+extern VALUE id_code;
 extern VALUE sym_unsupported_column_type;
 
 extern void Init_cluster(void);
@@ -136,5 +146,17 @@ extern void statement_default_config(CassandraStatement *cassandra_statement);
 extern CassStatement *statement_build_for_execution(CassandraStatement *cassandra_statement);
 extern void result_await(CassandraResult *cassandra_result);
 
+// Builds an exception of `exception_class` carrying `message` and `@code`
+// (readable via #code) set to the CassError value.
+extern VALUE ilios_error_new(VALUE exception_class, VALUE message, CassError error_code);
+
+// Builds an exception of `exception_class` from `future`'s error: the
+// driver's server-reported message (falling back to the generic
+// cass_error_desc when the driver returns none), formatted as
+// "<prefix>: <message>" when `prefix` is non-NULL, or the bare message when
+// `prefix` is NULL. `future` must still be alive (not yet cass_future_free'd)
+// when this is called.
+extern VALUE ilios_future_error_new(VALUE exception_class, const char *prefix, CassFuture *future);
+
 
 #endif // ILIOS_H

data/ext/ilios/result.c

@@ -22,10 +22,9 @@ void result_await(CassandraResult *cassandra_result)
     nogvl_future_wait(cassandra_result->future);
 
     if (cass_future_error_code(cassandra_result->future) != CASS_OK) {
-        char error[4096] = { 0 };
+        VALUE error = ilios_future_error_new(eExecutionError, "Unable to wait executing", cassandra_result->future);
 
-        strncpy(error, cass_error_desc(cass_future_error_code(cassandra_result->future)), sizeof(error) - 1);
-        rb_raise(eExecutionError, "Unable to wait executing: %s", error);
+        rb_exc_raise(error);
     }
 
     if (cassandra_result->result == NULL) {
@@ -66,8 +65,10 @@ static VALUE result_next_page(VALUE self)
 
     error_code = cass_future_error_code(result_future);
     if (error_code != CASS_OK) {
+        VALUE error = ilios_future_error_new(eExecutionError, "Unable to wait executing", result_future);
+
         cass_future_free(result_future);
-        rb_raise(eExecutionError, "Unable to wait executing: %s", cass_error_desc(error_code));
+        rb_exc_raise(error);
     }
 
     cass_result_free(cassandra_result->result);
@@ -80,10 +81,20 @@ static VALUE result_next_page(VALUE self)
     return self;
 }
 
+// No CassFuture is involved here: this fires while decoding an already
+// fetched row's column value.
+static VALUE result_check_value_error_new(CassError error_code, VALUE key)
+{
+    VALUE message = rb_enc_sprintf(rb_utf8_encoding(), "Unable to get value of %"PRIsVALUE" column: %s",
+                                   key, cass_error_desc(error_code));
+
+    return ilios_error_new(eExecutionError, message, error_code);
+}
+
 static void result_check_value(CassError error_code, VALUE key)
 {
     if (error_code != CASS_OK) {
-        rb_raise(eExecutionError, "Unable to get value of %"PRIsVALUE" column: %s", key, cass_error_desc(error_code));
+        rb_exc_raise(result_check_value_error_new(error_code, key));
     }
 }
 

data/ext/ilios/session.c

@@ -56,11 +56,10 @@ static VALUE session_prepare(VALUE self, VALUE query)
     nogvl_future_wait(prepare_future);
 
     if (cass_future_error_code(prepare_future) != CASS_OK) {
-        char error[4096] = { 0 };
+        VALUE error = ilios_future_error_new(eExecutionError, "Unable to prepare query", prepare_future);
 
-        strncpy(error, cass_error_desc(cass_future_error_code(prepare_future)), sizeof(error) - 1);
         cass_future_free(prepare_future);
-        rb_raise(eExecutionError, "Unable to prepare query: %s", error);
+        rb_exc_raise(error);
     }
 
     cassandra_statement_obj = CREATE_STATEMENT(cassandra_statement);

data/ext/ilios/statement.c

@@ -141,7 +141,10 @@ static void statement_bind_collection(statement_bind_target *target, const CassD
 static void statement_bind_check(CassError result, VALUE key)
 {
     if (result != CASS_OK) {
-        rb_raise(eStatementError, "Failed to bind value of %"PRIsVALUE" column: %s", key, cass_error_desc(result));
+        VALUE message = rb_enc_sprintf(rb_utf8_encoding(), "Failed to bind value of %"PRIsVALUE" column: %s",
+                                       key, cass_error_desc(result));
+
+        rb_exc_raise(ilios_error_new(eStatementError, message, result));
     }
 }
 
@@ -428,7 +431,7 @@ static VALUE statement_snapshot_value(const CassDataType *data_type, VALUE value
 
             length = RARRAY_LEN(array);
             snapshot = rb_ary_new_capa(length);
-            for (long i = 0; i < RARRAY_LEN(array); i++) {
+            for (long i = 0; i < length && i < RARRAY_LEN(array); i++) {
                 rb_ary_push(snapshot, statement_snapshot_value(element_type, rb_ary_entry(array, i)));
             }
             return rb_ary_freeze(snapshot);

data/lib/ilios/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Ilios
-  VERSION = '1.1.1'
+  VERSION = '1.2.0'
   public_constant :VERSION
 
   CASSANDRA_CPP_DRIVER_VERSION = '2.17.1'

data/sig/ilios.rbs

@@ -21,6 +21,18 @@ module Ilios
       PROTOCOL_VERSION_DSEV1: Integer
       PROTOCOL_VERSION_DSEV2: Integer
 
+      CONSISTENCY_ANY: Integer
+      CONSISTENCY_ONE: Integer
+      CONSISTENCY_TWO: Integer
+      CONSISTENCY_THREE: Integer
+      CONSISTENCY_QUORUM: Integer
+      CONSISTENCY_ALL: Integer
+      CONSISTENCY_LOCAL_QUORUM: Integer
+      CONSISTENCY_EACH_QUORUM: Integer
+      CONSISTENCY_SERIAL: Integer
+      CONSISTENCY_LOCAL_SERIAL: Integer
+      CONSISTENCY_LOCAL_ONE: Integer
+
       def connect: () -> Ilios::Cassandra::Session
       def hosts: (Array[String]) -> self
       def port: (Integer) -> self
@@ -30,6 +42,23 @@ module Ilios
       def request_timeout: (Integer) -> self
       def resolve_timeout: (Integer) -> self
       def constant_speculative_execution_policy: (Integer, Integer) -> self
+      def credentials: (String, String) -> self
+      def consistency: (Integer | Symbol) -> self
+      def serial_consistency: (Integer | Symbol) -> self
+      def num_threads_io: (Integer) -> self
+      def queue_size_io: (Integer) -> self
+      def core_connections_per_host: (Integer) -> self
+      def constant_reconnect: (Integer) -> self
+      def exponential_reconnect: (Integer, Integer) -> self
+      def tcp_nodelay: (bool) -> self
+      def tcp_keepalive: (bool, Integer) -> self
+      def connection_heartbeat_interval: (Integer) -> self
+      def connection_idle_timeout: (Integer) -> self
+      def load_balance_round_robin: () -> self
+      def load_balance_dc_aware: (String) -> self
+      def token_aware_routing: (bool) -> self
+      def latency_aware_routing: (bool) -> self
+      def use_schema: (bool) -> self
     end
 
     class Session
@@ -46,9 +75,21 @@ module Ilios
       def idempotent=: (bool) -> self
     end
 
+    class ExecutionError < StandardError
+      def code: () -> Integer?
+    end
+
+    class ConnectError < StandardError
+      def code: () -> Integer?
+    end
+
+    class StatementError < StandardError
+      def code: () -> Integer?
+    end
+
     class Future
-      def on_success: () { (Ilios::Cassandra::Result) -> void } -> self
-      def on_failure: () { () -> void } -> self
+      def on_success: () { (Ilios::Cassandra::Result | Ilios::Cassandra::Statement) -> void } -> self
+      def on_failure: () { (Ilios::Cassandra::ExecutionError) -> void } -> self
       def await: () -> self
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ilios
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Watson
@@ -58,7 +58,7 @@ metadata:
   homepage_uri: https://github.com/Watson1978/ilios
   source_code_uri: https://github.com/Watson1978/ilios
   bug_tracker_uri: https://github.com/Watson1978/ilios/issues
-  documentation_uri: https://www.rubydoc.info/gems/ilios/1.1.1
+  documentation_uri: https://www.rubydoc.info/gems/ilios/1.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: