cassandra-driver 0.1.0.alpha1 → 1.0.0.beta.1

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--markup markdown
+lib/**/*.rb
+-- README

data/README.md

@@ -0,0 +1,117 @@
+# Datastax Ruby Driver for Apache Cassandra
+
+[![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
+the Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.
+
+- Code: https://github.com/datastax/ruby-driver
+- Docs: http://datastax.github.io/ruby-driver/
+- 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) 
+
+This driver is based on [the cql-rb gem](https://github.com/iconara/cql-rb) by [Theo Hultberg](https://github.com/iconara) and we addded support for:
+
+* [asynchronous execution](/features/asynchronous_io/)
+* one-off, [prepared](/features/prepared_statements/) and [batch statements](/features/batch_statements/)
+* automatic peer discovery and cluster metadata
+* various [load-balancing](/features/load_balancing/), [retry](/features/retry_policies/) and reconnection policies, [with ability to write your own](/features/load_balancing/implementing_a_policy/)
+
+## Compability
+
+This driver works exclusively with the Cassandra Query Language v3 (CQL3) and Cassandra's native protocol. The current version works with:
+
+* Cassandra versions 1.2 and 2.0
+* Ruby 1.9.3 and 2.0
+* JRuby 1.7
+* Rubinius 2.1
+
+__Note__: JRuby 1.6 is not officially supported, although 1.6.8 should work.
+
+## Quick start
+
+```ruby
+require 'cassandra'
+
+cluster = Cassandra.connect # connects to localhost by default
+
+cluster.each_hosts do |host| # automatically discovers all peers
+  puts "Host #{host.ip}: id=#{host.id} datacenter=#{host.datacenter} rack=#{host.rack}"
+end
+
+keyspace = 'system'
+session  = cluster.connect(keyspace) # create session, optionally scoped to a keyspace, to execute queries
+
+future = session.execute_async('SELECT keyspace_name, columnfamily_name FROM schema_columnfamilies') # fully asynchronous api
+future.on_success do |rows|
+  rows.each do |row|
+    puts "The keyspace #{row['keyspace_name']} has a table called #{row['columnfamily_name']}"
+  end
+end
+future.join
+```
+
+The host you specify is just a seed node, the driver will automatically discover all peers in the cluster.
+
+Read more:
+
+* [`Cql.connect` options](/api/#connect-class_method)
+* [`Session#execute_async` options](/api/session/#execute_async-instance_method)
+* [Usage documentation](/features)
+
+## Installation
+
+Install via rubygems
+
+```bash
+gem install cassandra-driver
+```
+
+Install via Gemfile
+
+```ruby
+gem 'cassandra-driver'
+```
+
+Note: if you want to use compression you should also install [snappy](http://rubygems.org/gems/snappy) or [lz4-ruby](http://rubygems.org/gems/lz4-ruby). [Read more about compression.](/features/#compression)
+
+
+## Upgrading from cql-rb
+
+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.
+
+## Changelog & versioning
+
+Check out the [releases on GitHub](https://github.com/datastax/ruby-driver/releases). Version numbering follows the [semantic versioning](http://semver.org/) scheme.
+
+Private and experimental APIs, defined as whatever is not in the [public API documentation][1], i.e. classes and methods marked as `@private`, will change without warning. If you've been recommended to try an experimental API by the maintainers, please let them know if you depend on that API. Experimental APIs will eventually become public, and knowing how they are used helps in determining their maturity.
+
+Prereleases will be stable, in the sense that they will have finished and properly tested features only, but may introduce APIs that will change before the final release. Please use the prereleases and report bugs, but don't deploy them to production without consulting the maintainers, or doing extensive testing yourself. If you do deploy to production please let the maintainers know as this helps determining the maturity of the release.
+
+## Known bugs & limitations
+
+* JRuby 1.6 is not officially supported, although 1.6.8 should work, if you're stuck in JRuby 1.6.8 try and see if it works for you.
+* Because the driver reactor is using `IO.select`, the maximum number of tcp connections allowed is 1024.
+
+
+## Credits
+
+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. 
+
+
+## Copyright
+
+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](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.
+
+  [1]: http://datastax.github.io/ruby-driver/api
+

data/lib/cassandra.rb

@@ -0,0 +1,320 @@
+# 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.
+#++
+
+
+require 'ione'
+require 'json'
+
+require 'monitor'
+require 'ipaddr'
+require 'set'
+require 'bigdecimal'
+require 'forwardable'
+require 'timeout'
+
+module Cassandra
+  # A list of all supported request consistencies
+  # @see Cassandra::Session#execute_async
+  CONSISTENCIES = [ :any, :one, :two, :three, :quorum, :all, :local_quorum,
+                    :each_quorum, :serial, :local_serial, :local_one ].freeze
+
+  # A list of all supported serial consistencies
+  # @see Cassandra::Session#execute_async
+  SERIAL_CONSISTENCIES = [:serial, :local_serial].freeze
+
+  # Creates a {Cassandra::Cluster} instance
+  #
+  # @option options [Array<String, IPAddr>] :hosts (['127.0.0.1']) a list of
+  #   initial addresses. Note that the entire list of cluster members will be
+  #   discovered automatically once a connection to any hosts from the original
+  #   list is successful
+  #
+  # @option options [Integer] :port (9042) cassandra native protocol port
+  #
+  # @option options [String] :username (none) username to use for
+  #   authentication to cassandra. Note that you must also specify `:password`
+  #
+  # @option options [String] :password (none) password to use for
+  #   authentication to cassandra. Note that you must also specify `:username`
+  #
+  # @option options [Symbol] :compression (none) compression to use. Must be
+  #   either `:snappy` or `:lz4`. Also note, that in order for compression to
+  #   work, you must install 'snappy' or 'lz4-ruby' gems
+  #
+  # @option options [Cassandra::LoadBalancing::Policy] :load_balancing_policy
+  #   default: {Cassandra::LoadBalancing::Policies::RoundRobin}
+  #
+  # @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)`
+  #
+  # @option options [Cassandra::Retry::Policy] :retry_policy default:
+  #   {Cassandra::Retry::Policies::Default}
+  #
+  # @option options [Logger] :logger (none) logger. a {Logger} instance from the
+  #   standard library or any object responding to standard log methods
+  #   (`#debug`, `#info`, `#warn`, `#error` and `#fatal`)
+  #
+  # @option options [Enumerable<Cassandra::Listener>] :listeners (none)
+  #   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 [Boolean] :trace (false) whether or not to trace all
+  #   requests by default
+  #
+  # @option options [Integer] :page_size (nil) default page size for all select
+  #   queries
+  #
+  # @option options [Hash{String => String}] :credentials (none) a hash of credentials - to be used with [credentials authentication in cassandra 1.2](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L238-L250). Note that if you specified `:username` and `:password` options, those credentials are configured automatically
+  #
+  # @option options [Cassandra::Auth::Provider] :auth_provider (none) a custom auth provider to be used with [SASL authentication in cassandra 2.0](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v2.spec#L257-L273). Note that if you have specified `:username` and `:password`, then a {Cassandra::Auth::Providers::Password} will be used automatically
+  #
+  # @option options [Cassandra::Compressor] :compressor (none) a custom
+  #   compressor. Note that if you have specified `:compression`, an
+  #   appropriate compressor 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
+  #   to {Cassandra::Promise} api, which is not yet public. Things may change,
+  #   use at your own risk.
+  #
+  # @example Connecting to localhost
+  #   cluster = Cassandra.connect
+  #
+  # @example Configuring {Cassandra::Cluster}
+  #   cluster = Cassandra.connect(
+  #               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|
+      [ :credentials, :auth_provider, :compression, :hosts, :logger, :port,
+        :load_balancing_policy, :reconnection_policy, :retry_policy, :listeners,
+        :consistency, :trace, :page_size, :compressor, :username, :password,
+        :futures_factory
+      ].include?(key)
+    end
+
+    has_username = options.has_key?(:username)
+    has_password = options.has_key?(:password)
+    if has_username || has_password
+      if has_username && !has_password
+        raise ::ArgumentError, "both :username and :password options must be specified, but only :username given"
+      end
+
+      if !has_username && has_password
+        raise ::ArgumentError, "both :username and :password options must be specified, but only :password given"
+      end
+
+      username = String(options.delete(:username))
+      password = String(options.delete(:password))
+
+      raise ::ArgumentError, ":username cannot be empty" if username.empty?
+      raise ::ArgumentError, ":password cannot be empty" if password.empty?
+
+      options[:credentials]   = {:username => username, :password => password}
+      options[:auth_provider] = Auth::Providers::Password.new(username, password)
+    end
+
+    if options.has_key?(:credentials)
+      credentials = options[:credentials]
+
+      unless credentials.is_a?(Hash)
+        raise ::ArgumentError, ":credentials must be a hash, #{credentials.inspect} given"
+      end
+    end
+
+    if options.has_key?(:auth_provider)
+      auth_provider = options[:auth_provider]
+
+      unless auth_provider.respond_to?(:create_authenticator)
+        raise ::ArgumentError, ":auth_provider #{auth_provider.inspect} must respond to :create_authenticator, but doesn't"
+      end
+    end
+
+    if options.has_key?(:compression)
+      compression = options.delete(:compression)
+
+      case compression
+      when :snappy
+        require 'cassandra/compression/compressors/snappy'
+        options[:compressor] = Compression::Compressors::Snappy.new
+      when :lz4
+        require 'cassandra/compression/compressors/lz4'
+        options[:compressor] = Compression::Compressors::Lz4.new
+      else
+        raise ::ArgumentError, ":compression must be either :snappy or :lz4, #{compression.inspect} given"
+      end
+    end
+
+    if options.has_key?(:compressor)
+      compressor = options[:compressor]
+      methods    = [:algorithm, :compress?, :compress, :decompress]
+
+      unless methods.all? {|method| compressor.respond_to?(method)}
+        raise ::ArgumentError, ":compressor #{compressor.inspect} must respond to #{methods.inspect}, but doesn't"
+      end
+    end
+
+    if options.has_key?(:logger)
+      logger  = options[:logger]
+      methods = [:debug, :info, :warn, :error, :fatal]
+
+      unless methods.all? {|method| logger.respond_to?(method)}
+        raise ::ArgumentError, ":logger #{logger.inspect} must respond to #{methods.inspect}, but doesn't"
+      end
+    end
+
+    if options.has_key?(:port)
+      port = options[:port] = Integer(options[:port])
+
+      if port < 0 || port > 65536
+        raise ::ArgumentError, ":port must be a valid ip port, #{port.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, :distance, :plan]
+
+      unless methods.all? {|method| load_balancing_policy.respond_to?(method)}
+        raise ::ArgumentError, ":load_balancing_policy #{load_balancing_policy.inspect} must respond to #{methods.inspect}, but doesn't"
+      end
+    end
+
+    if options.has_key?(:reconnection_policy)
+      reconnection_policy = options[:reconnection_policy]
+
+      unless reconnection_policy.respond_to?(:schedule)
+        raise ::ArgumentError, ":reconnection_policy #{reconnection_policy.inspect} must respond to :schedule, but doesn't"
+      end
+    end
+
+    if options.has_key?(:retry_policy)
+      retry_policy = options[:retry_policy]
+      methods = [:read_timeout, :write_timeout, :unavailable]
+
+      unless methods.all? {|method| retry_policy.respond_to?(method)}
+        raise ::ArgumentError, ":retry_policy #{retry_policy.inspect} must respond to #{methods.inspect}, but doesn't"
+      end
+    end
+
+    if options.has_key?(:listeners)
+      listeners = options[:listeners]
+
+      unless listeners.respond_to?(:each)
+        raise ::ArgumentError, ":listeners must be an Enumerable, #{listeners.inspect} given"
+      end
+    end
+
+    if options.has_key?(:consistency)
+      consistency = options[:consistency]
+
+      unless CONSISTENCIES.include?(consistency)
+        raise ::ArgumentError, ":consistency must be one of #{CONSISTENCIES.inspect}, #{consistency.inspect} given"
+      end
+    end
+
+    if options.has_key?(:trace)
+      options[:trace] = !!options[:trace]
+    end
+
+    if options.has_key?(:page_size)
+      page_size = options[:page_size] = Integer(options[:page_size])
+
+      if page_size <= 0
+        raise ::ArgumentError, ":page_size must be a positive integer, #{page_size.inspect} given"
+      end
+    end
+
+    if options.has_key?(:futures_factory)
+      futures_factory = options[:futures_factory]
+      methods = [:error, :value, :promise, :all]
+
+      unless methods.all? {|method| futures_factory.respond_to?(method)}
+        raise ::ArgumentError, ":futures_factory #{futures_factory.inspect} must respond to #{methods.inspect}, but doesn't"
+      end
+    end
+
+    hosts = options.fetch(:hosts, [])
+    hosts << ::IPAddr.new('127.0.0.1') if hosts.empty?
+
+    hosts.map! do |host|
+      case host
+      when ::IPAddr
+        host
+      when ::String
+        ::IPAddr.new(host)
+      else
+        raise ::ArgumentError, ":hosts must be String or IPAddr, #{host.inspect} given"
+      end
+    end
+
+    Driver.new(options).connect(hosts).value
+  end
+end
+
+require 'cassandra/errors'
+require 'cassandra/uuid'
+require 'cassandra/time_uuid'
+require 'cassandra/compression'
+require 'cassandra/protocol'
+require 'cassandra/auth'
+require 'cassandra/client'
+
+require 'cassandra/future'
+require 'cassandra/cluster'
+require 'cassandra/driver'
+require 'cassandra/host'
+require 'cassandra/session'
+require 'cassandra/result'
+require 'cassandra/statement'
+require 'cassandra/statements'
+
+require 'cassandra/column'
+require 'cassandra/table'
+require 'cassandra/keyspace'
+
+require 'cassandra/execution/info'
+require 'cassandra/execution/options'
+require 'cassandra/execution/trace'
+
+require 'cassandra/load_balancing'
+require 'cassandra/reconnection'
+require 'cassandra/retry'
+
+require 'cassandra/util'
+
+module Cassandra
+  # @private
+  Io = Ione::Io
+  # @private
+  VOID_STATEMENT = Statements::Void.new
+  # @private
+  VOID_OPTIONS   = Execution::Options.new({:consistency => :one})
+  # @private
+  NO_HOSTS       = Errors::NoHostsAvailable.new
+end

data/lib/cassandra/auth.rb

@@ -0,0 +1,97 @@
+# 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 Auth
+    # An auth provider is a factory for {Cassandra::Auth::Authenticator} instances
+    # (or objects matching that interface). Its {#create_authenticator} will be
+    # called once for each connection that requires authentication.
+    #
+    # If the authentication requires keeping state, keep that in the
+    # authenticator instances, not in the auth provider.
+    #
+    # @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
+    #   subclasses of this class, but need to implement the same methods. This
+    #   class exists only for documentation purposes.
+    #
+    # @see Cassandra::Auth::Providers
+    class Provider
+      # @!method create_authenticator(authentication_class, protocol_version)
+      #
+      # Create a new authenticator object. This method will be called once per
+      # connection that requires authentication. The auth provider can create
+      # different authenticators for different authentication classes, or return
+      # nil if it does not support the authentication class.
+      #
+      # @note This method must absolutely not block.
+      #
+      # @param authentication_class [String] the authentication class used by
+      #   the server.
+      # @return [Cassandra::Auth::Authenticator, nil] an object with an
+      #   interface matching {Cassandra::Auth::Authenticator} or nil if the
+      #   authentication class is not supported.
+    end
+
+    # An authenticator handles the authentication challenge/response cycles of
+    # a single connection. It can be stateful, but it must not for any reason
+    # block. If any of the method calls block, the whole connection process
+    # will be blocked.
+    #
+    # @note Authenticators created by auth providers don't need to be subclasses
+    #   of this class, but need to implement the same methods. This class exists
+    #   only for documentation purposes.
+    #
+    # @see https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v2.spec#L257-L273 Cassandra native protocol v2 SASL authentication
+    # @see Cassandra::Auth::Provider
+    class Authenticator
+      # @!method initial_response
+      #
+      # This method must return the initial authentication token to be sent to
+      # the server.
+      #
+      # @note This method must absolutely not block.
+      #
+      # @return [String] the initial authentication token
+
+      # @!method challenge_response(token)
+      #
+      # If the authentication requires multiple challenge/response cycles this
+      # method will be called when a challenge is returned by the server. A
+      # response token must be created and will be sent back to the server.
+      #
+      # @note This method must absolutely not block.
+      #
+      # @param token [String] a challenge token sent by the server
+      # @return [String] the authentication token to send back to the server
+
+      # @!method authentication_successful(token)
+      #
+      # Called when the authentication is successful.
+      #
+      # @note This method must absolutely not block.
+      #
+      # @param token [String] a token sent by the server
+      # @return [void]
+    end
+  end
+end
+
+require 'cassandra/auth/providers'