cassandra-driver 1.0.0.beta.3 → 1.0.0.rc.1

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: dd171d621192a4a0e4bbebd4601a9e5c2dab6654
-  data.tar.gz: b779c047aef25ed28329f4237f677f13b985c494
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTA3NTE1Y2M2Y2U5MmJmNGVlODZlZmI4YjI1NWE3OGNhOTY4OTgzOA==
+  data.tar.gz: !binary |-
+    ZDg0NTUxZTFmNDBjYmVjZDFlYjE1MzUwODc3MGFkODkwNTBjZmZjOQ==
 SHA512:
-  metadata.gz: 97de07b2338b3d68cd89ca452121666e638775fde7237f33f3c7e2a4db4ae364ad4ce799bf30e4c671befa8dd921a141cb8980ef4d9a95009c3bd3728b1f0dd9
-  data.tar.gz: be2236c32cf4dabbcb4ea7ed8597f8dec6cf03ef55cabbbe7b5bf13a20150cd854382d8609dd91ec0f0f2e9d8759890b3cfbf3a5e291e7aadceb7032fb6c980e
+  metadata.gz: !binary |-
+    OGI2NTA0NDQ2ZTk2ODlmNDFkNTkyMTYxZDBmY2I3OTNhNjQ3Y2ExNGQzZDlh
+    YzkzZDA0MGIwM2MzODRkMmJjYjI1OTRjNzYzYzg1MTNiNzFjMmJmOGUyZWEz
+    MjczMzZmNzg1OTZjN2NjY2JhMjc3YjYxMTJhOTc2MTVjOTI1MTQ=
+  data.tar.gz: !binary |-
+    MTc1ZDhiYmMyZDYzMDhjZDQzZmUxM2MzMzQ0NDNjNWFhOTIxZGY4ZjNiZDRm
+    Y2I2YmYzYmNkZmY0NGIyNzNkOGU3YWM4MTg3MDhjYTZhOTYyNWY2YWQ4ODI2
+    YmU3OTQ4ZjQ4NGU4NWY0MTkzOTQ4MWFiM2U0YzRiYTI4MzVjZmE=

data/README.md

@@ -1,5 +1,7 @@
 # Datastax Ruby Driver for Apache Cassandra
 
+*If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can [find the documentation for latest version through ruby driver docs](http://datastax.github.io/ruby-driver/) or via the release tags, [e.g. v1.0.0-beta.3](https://github.com/datastax/ruby-driver/tree/v1.0.0-beta.3).*
+
 [![Build Status](https://travis-ci.org/datastax/ruby-driver.svg?branch=master)](https://travis-ci.org/datastax/ruby-driver)
 
 A Ruby client driver for Apache Cassandra. This driver works exclusively with
@@ -10,7 +12,7 @@ the Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.
 - JIRA: https://datastax-oss.atlassian.net/browse/RUBY
 - MAILING LIST: https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user
 - IRC: #datastax-drivers on [irc.freenode.net](http://freenode.net>)
-- TWITTER: Follow the latest news about DataStax Drivers - [@avalanche123](http://twitter.com/avalanche123), [@mfiguiere](http://twitter.com/mfiguiere), [@al3xandru](https://twitter.com/al3xandru) 
+- TWITTER: Follow the latest news about DataStax Drivers - [@avalanche123](http://twitter.com/avalanche123), [@mfiguiere](http://twitter.com/mfiguiere), [@al3xandru](https://twitter.com/al3xandru)
 
 This driver is based on [the cql-rb gem](https://github.com/iconara/cql-rb) by [Theo Hultberg](https://github.com/iconara) and we added support for:
 
@@ -18,6 +20,7 @@ This driver is based on [the cql-rb gem](https://github.com/iconara/cql-rb) by [
 * one-off, [prepared](http://datastax.github.io/ruby-driver/features/basics/prepared_statements/) and [batch statements](http://datastax.github.io/ruby-driver/features/basics/batch_statements/)
 * automatic peer discovery and cluster metadata
 * various [load-balancing](http://datastax.github.io/ruby-driver/features/load_balancing/), [retry](http://datastax.github.io/ruby-driver/features/retry_policies/) and reconnection policies, [with ability to write your own](http://datastax.github.io/ruby-driver/features/load_balancing/implementing_a_policy/)
+* [SSL encryption](http://datastax.github.io/ruby-driver/features/security/ssl_encryption/)
 
 ## Compability
 
@@ -35,7 +38,7 @@ __Note__: JRuby 1.6 is not officially supported, although 1.6.8 should work.
 ```ruby
 require 'cassandra'
 
-cluster = Cassandra.connect # connects to localhost by default
+cluster = Cassandra.cluster # connects to localhost by default
 
 cluster.each_host do |host| # automatically discovers all peers
   puts "Host #{host.ip}: id=#{host.id} datacenter=#{host.datacenter} rack=#{host.rack}"
@@ -57,7 +60,7 @@ The host you specify is just a seed node, the driver will automatically discover
 
 Read more:
 
-* [`Cassandra.connect` options](http://datastax.github.io/ruby-driver/api/#connect-class_method)
+* [`Cassandra.cluster` options](http://datastax.github.io/ruby-driver/api/#cluster-class_method)
 * [`Session#execute_async` options](http://datastax.github.io/ruby-driver/api/session/#execute_async-instance_method)
 * [Usage documentation](http://datastax.github.io/ruby-driver/features)
 
@@ -82,7 +85,7 @@ Note: if you want to use compression you should also install [snappy](http://rub
 
 Some of the new features added to the driver have unfortunately led to changes in the original cql-rb API. In the examples directory, you can find [an example of how to wrap the ruby driver to achieve almost complete interface parity with cql-rb](https://github.com/datastax/ruby-driver/blob/master/examples/cql-rb-wrapper.rb) to assist you with gradual upgrade.
 
-## What's new in v1.0.0.beta.2
+## What's new in v1.0.0.beta.3
 
 Current release introduces the following new features:
 
@@ -108,7 +111,7 @@ Prereleases will be stable, in the sense that they will have finished and proper
 
 This driver is based on the original work of [Theo Hultberg](https://github.com/iconara) on [cql-rb](https://github.com/iconara/cql-rb/) and adds a series of advanced features that are common across all other DataStax drivers for Apache Cassandra.
 
-The development effort to provide an up to date, high performance, fully featured Ruby Driver for Apache Cassandra will continue on this project, while [cql-rb](https://github.com/iconara/cql-rb/) will be discontinued. 
+The development effort to provide an up to date, high performance, fully featured Ruby Driver for Apache Cassandra will continue on this project, while [cql-rb](https://github.com/iconara/cql-rb/) will be discontinued.
 
 
 ## Copyright
@@ -122,4 +125,3 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
   [1]: http://datastax.github.io/ruby-driver/api
-

data/lib/cassandra.rb

@@ -30,9 +30,13 @@ require 'digest'
 require 'stringio'
 require 'resolv'
 require 'openssl'
+require 'securerandom'
+require 'time'
 
 module Cassandra
   # A list of all supported request consistencies
+  # @see http://www.datastax.com/documentation/cassandra/2.0/cassandra/dml/dml_config_consistency_c.html Consistency levels in Apache Cassandra 2.0
+  # @see http://www.datastax.com/documentation/cassandra/1.2/cassandra/dml/dml_config_consistency_c.html Consistency levels in Apache Cassandra 1.2
   # @see Cassandra::Session#execute_async
   CONSISTENCIES = [ :any, :one, :two, :three, :quorum, :all, :local_quorum,
                     :each_quorum, :serial, :local_serial, :local_one ].freeze
@@ -41,6 +45,12 @@ module Cassandra
   # @see Cassandra::Session#execute_async
   SERIAL_CONSISTENCIES = [:serial, :local_serial].freeze
 
+  # A list of all possible write types that a
+  # {Cassandra::Errors::WriteTimeoutError} can have.
+  #
+  # @see https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L591-L603 Description of possible types of writes in Apache Cassandra native protocol spec v1
+  WRITE_TYPES = [:simple, :batch, :unlogged_batch, :counter, :batch_log].freeze
+
   # Creates a {Cassandra::Cluster} instance
   #
   # @option options [Array<String, IPAddr>] :hosts (['127.0.0.1']) a list of
@@ -50,9 +60,28 @@ module Cassandra
   #
   # @option options [Integer] :port (9042) cassandra native protocol port.
   #
+  # @option options [String] :datacenter (nil) name of current datacenter.
+  #   First datacenter found will be assumed current by default. Note that you
+  #   can skip this option if you specify only hosts from the local datacenter
+  #   in `:hosts` option.
+  #
   # @option options [Numeric] :connect_timeout (10) connection timeout in
   #   seconds.
   #
+  # @option options [Numeric] :timeout (10) request execution timeout in
+  #   seconds.
+  #
+  # @option options [Numeric] :heartbeat_interval (30) how often should a
+  #   heartbeat be sent to determine if a connection is alive. Several things to
+  #   note about this option. Only one heartbeat request will ever be
+  #   outstanding on a given connection. Each heatbeat will be sent in at least
+  #   `:heartbeat_interval` seconds after the last request has been sent on a
+  #   given connection.
+  #
+  # @option options [Numeric] :idle_timeout (60) period of inactivity after
+  #   which a connection is considered dead. Note that this value should be at
+  #   least a few times larger than `:heartbeat_interval`.
+  #
   # @option options [String] :username (none) username to use for
   #   authentication to cassandra. Note that you must also specify `:password`.
   #
@@ -83,12 +112,15 @@ module Cassandra
   #   work, you must install 'snappy' or 'lz4-ruby' gems.
   #
   # @option options [Cassandra::LoadBalancing::Policy] :load_balancing_policy
-  #   default: {Cassandra::LoadBalancing::Policies::RoundRobin}.
+  #   default: token aware data center aware round robin.
+  #
+  # @option options [Symbol] :address_resolution (:none) a pre-configured
+  #   address resolver to use. Must be one of `:none` or
+  #   `:ec2_multi_region`.
   #
   # @option options [Cassandra::Reconnection::Policy] :reconnection_policy
   #   default: {Cassandra::Reconnection::Policies::Exponential}. Note that the
-  #   default policy is configured with
-  #   `Reconnection::Policies::Exponential.new(0.5, 30, 2)`.
+  #   default policy is configured with `(0.5, 30, 2)`.
   #
   # @option options [Cassandra::Retry::Policy] :retry_policy default:
   #   {Cassandra::Retry::Policies::Default}.
@@ -101,8 +133,8 @@ module Cassandra
   #   initial listeners. A list of initial cluster state listeners. Note that a
   #   `:load_balancing` policy is automatically registered with the cluster.
   #
-  # @option options [Symbol] :consistency (:quorum) default consistency to use
-  #   for all requests. Must be one of {Cassandra::CONSISTENCIES}.
+  # @option options [Symbol] :consistency (:one) default consistency to use for
+  #   all requests. Must be one of {Cassandra::CONSISTENCIES}.
   #
   # @option options [Boolean] :trace (false) whether or not to trace all
   #   requests by default.
@@ -118,6 +150,12 @@ module Cassandra
   #   compressor. Note that if you have specified `:compression`, an
   #   appropriate compressor will be provided automatically.
   #
+  # @option options [Cassandra::AddressResolution::Policy]
+  #   :address_resolution_policy default:
+  #   {Cassandra::AddressResolution::Policies::None} a custom address resolution
+  #   policy. Note that if you have specified `:address_resolution`, an
+  #   appropriate address resolution policy will be provided automatically.
+  #
   # @option options [Object<#all, #error, #value, #promise>] :futures_factory
   #   (none) a custom futures factory to assist with integration into existing
   #   futures library. Note that promises returned by this object must conform
@@ -125,23 +163,24 @@ module Cassandra
   #   use at your own risk.
   #
   # @example Connecting to localhost
-  #   cluster = Cassandra.connect
+  #   cluster = Cassandra.cluster
   #
   # @example Configuring {Cassandra::Cluster}
-  #   cluster = Cassandra.connect(
+  #   cluster = Cassandra.cluster(
   #               username: username,
   #               password: password,
   #               hosts: ['10.0.1.1', '10.0.1.2', '10.0.1.3']
   #             )
   #
   # @return [Cassandra::Cluster] a cluster instance
-  def self.connect(options = {})
-    options.select! do |key, value|
+  def self.cluster(options = {})
+    options = options.select do |key, value|
       [ :credentials, :auth_provider, :compression, :hosts, :logger, :port,
         :load_balancing_policy, :reconnection_policy, :retry_policy, :listeners,
         :consistency, :trace, :page_size, :compressor, :username, :password,
         :ssl, :server_cert, :client_cert, :private_key, :passphrase,
-        :connect_timeout, :futures_factory
+        :connect_timeout, :futures_factory, :datacenter, :address_resolution,
+        :address_resolution_policy, :idle_timeout, :heartbeat_interval, :timeout
       ].include?(key)
     end
 
@@ -241,7 +280,7 @@ module Cassandra
       ssl = options[:ssl]
 
       unless ssl.is_a?(::TrueClass) || ssl.is_a?(::FalseClass) || ssl.is_a?(::OpenSSL::SSL::SSLContext)
-        raise ":ssl must be a boolean or an OpenSSL::SSL::SSLContext, #{ssl.inspect} given"
+        raise ::ArgumentError, ":ssl must be a boolean or an OpenSSL::SSL::SSLContext, #{ssl.inspect} given"
       end
     end
 
@@ -286,6 +325,10 @@ module Cassandra
       end
     end
 
+    if options.has_key?(:datacenter)
+      options[:datacenter] = String(options[:datacenter])
+    end
+
     if options.has_key?(:connect_timeout)
       timeout = options[:connect_timeout] = Integer(options[:connect_timeout])
 
@@ -294,6 +337,30 @@ module Cassandra
       end
     end
 
+    if options.has_key?(:timeout)
+      timeout = options[:timeout] = Integer(options[:timeout])
+
+      if timeout < 0
+        raise ::ArgumentError, ":timeout must be a positive value, #{timeout.given}"
+      end
+    end
+
+    if options.has_key?(:heartbeat_interval)
+      timeout = options[:heartbeat_interval] = Integer(options[:heartbeat_interval])
+
+      if timeout < 0
+        raise ::ArgumentError, ":heartbeat_interval must be a positive value, #{timeout.given}"
+      end
+    end
+
+    if options.has_key?(:idle_timeout)
+      timeout = options[:idle_timeout] = Integer(options[:idle_timeout])
+
+      if timeout < 0
+        raise ::ArgumentError, ":idle_timeout must be a positive value, #{timeout.given}"
+      end
+    end
+
     if options.has_key?(:load_balancing_policy)
       load_balancing_policy = options[:load_balancing_policy]
       methods = [:host_up, :host_down, :host_found, :host_lost, :setup, :distance, :plan]
@@ -357,6 +424,26 @@ module Cassandra
       end
     end
 
+    if options.has_key?(:address_resolution)
+      address_resolution = options.delete(:address_resolution)
+
+      case address_resolution
+      when :none
+      when :ec2_multi_region
+        options[:address_resolution_policy] = AddressResolution::Policies::EC2MultiRegion.new
+      else
+        raise ::ArgumentError, ":address_resolution must be either :none or :ec2_multi_region, #{address_resolution.inspect} given"
+      end
+    end
+
+    if options.has_key?(:address_resolution_policy)
+      address_resolver = options[:address_resolution_policy]
+
+      unless address_resolver.respond_to?(:resolve)
+        raise ::ArgumentError, ":address_resolution_policy must respond to :resolve, #{address_resolver.inspect} but doesn't"
+      end
+    end
+
     hosts = []
 
     Array(options.fetch(:hosts, '127.0.0.1')).each do |host|
@@ -408,6 +495,7 @@ require 'cassandra/execution/trace'
 require 'cassandra/load_balancing'
 require 'cassandra/reconnection'
 require 'cassandra/retry'
+require 'cassandra/address_resolution'
 
 require 'cassandra/util'
 
@@ -415,8 +503,6 @@ require 'cassandra/util'
 require 'cassandra_murmur3'
 
 module Cassandra
-  # @private
-  Io = Ione::Io
   # @private
   VOID_STATEMENT = Statements::Void.new
   # @private

data/lib/cassandra/address_resolution.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  # Address Resolution policy allows translating a node ip address from what is
+  # recorded in Cassandra's system tables to an actual ip address for the driver
+  # to use. It is very useful in various multi-region scenarios (e.g. on EC2).
+  module AddressResolution
+    class Policy
+      # Resolves a node ip address.
+      #
+      # @param address [IPAddr] node ip address from Cassandra's system table
+      #
+      # @return [IPAddr] actual ip address of the node
+      def resolve(address)
+      end
+    end
+  end
+end
+
+require 'cassandra/address_resolution/policies'

data/lib/cassandra/address_resolution/policies.rb

@@ -0,0 +1,2 @@
+require 'cassandra/address_resolution/policies/none'
+require 'cassandra/address_resolution/policies/ec2_multi_region'

data/lib/cassandra/address_resolution/policies/ec2_multi_region.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module AddressResolution
+    module Policies
+      # This policy resolves private ips of the hosts in the same datacenter and
+      # public ips of hosts in other datacenters.
+      #
+      # @note Initializing this policy is not necessary, you should just pass
+      #   `:ec_multi_region` to the `:address_resolution` option of
+      #   {Cassandra.cluster}
+      class EC2MultiRegion
+        # @private
+        def initialize(resolver = Resolv)
+          @resolver = resolver
+        end
+
+        # Returns ip address after a double DNS lookup. First, it will get
+        # hostname from a given ip, then resolve the resulting hostname. This
+        # policy works because AWS public hostnames resolve to a private ip
+        # address within the same datacenter.
+        #
+        # @param address [IPAddr] node ip address from Cassandra's system table
+        #
+        # @return [IPAddr] private ip withing the same datacenter, public ip
+        #   otherwise. Returns original address if DNS lookups fail.
+        def resolve(address)
+          @resolver.each_name(Resolv::DNS::Name.create(address.reverse)) do |name|
+            @resolver.each_address(name) do |addr|
+              return ::IPAddr.new(addr)
+            end
+          end
+
+          # default to original address if reverse DNS lookup failed
+          address
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/address_resolution/policies/none.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module AddressResolution
+    module Policies
+      # The default address resolution policy. Always returns original address.
+      class None
+        # Returns original address.
+        #
+        # @param address [IPAddr] node ip address from Cassandra's system table
+        #
+        # @return [IPAddr] same as `address`
+        def resolve(address)
+          address
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/auth.rb

@@ -28,7 +28,7 @@ module Cassandra
     # @note Creating an authenticator must absolutely not block, or the whole
     #   connection process will block.
     #
-    # @abstract Auth providers given to {Cassandra.connect} don't need to be
+    # @abstract Auth providers given to {Cassandra.cluster} don't need to be
     #   subclasses of this class, but need to implement the same methods. This
     #   class exists only for documentation purposes.
     #