cql-rb 2.0.0.pre2 → 2.0.0.rc0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dcb7e0235108a8f81d404fd31054f2d1ac4701d4
-  data.tar.gz: 928b20dfd3e07da9062c3443b57de7b68e82f1df
+  metadata.gz: b5d95e28951fcb350531d0899c6a4b12938677c9
+  data.tar.gz: 271b515465def1838737f6d92983958f47541f09
 SHA512:
-  metadata.gz: 31788daec8a14dd8c2a3a0588e510ff54cef4b8ad289dfb806a978b49035345b760e5602cd5142930acfd2a56e6f289304efb714b5984f117b07e9196833d580
-  data.tar.gz: 4518fdb25311bd20433aae27094015d4502c53e9f793670a85fca6ed20da351e8065f08197a5621ecec3d82fe3050e6b368c02db5ffa614ddae82baf623b8c19
+  metadata.gz: 89b8043dc895260cb8baee75a43652d7150574141863a876a663fb2427672b36ba970f3837813800edd4f106e5fc56d053d75dca2c26889ab0a25b110846a660
+  data.tar.gz: 2d910f7d38e3bb0851c6a43b1146d01f84b6c7b5c5d33682bd587dd2b0f4eb2127e5fc26798a491a4b03730fc8a16fa756bbe19445f2ddfb1b3910b8487dc51b

data/README.md

@@ -143,6 +143,8 @@ A prepared statement can be run many times, but the CQL parsing will only be don
 
 Statements are prepared on all connections and each call to `#execute` selects a random connection to run the query on.
 
+You should only create a prepared statement for a query once, and then reuse the prepared statement object. Preparing the same CQL over and over again is bad for performance since each preparation requires a roundtrip to _all_ connected Cassandra nodes.
+
 ## Batching
 
 If you're using Cassandra 2.0 or later you can build batch requests, either from regular queries or from prepared statements. Batches can consist of `INSERT`, `UPDATE` and `DELETE` statements.
@@ -210,6 +212,16 @@ batch.execute(consistency: :quorum)
 
 As you can see you can specify the options either when creating the batch or when sending it (when using the variant where you call `#execute` yourself). The options given to `#execute` take precedence. You can omit the batch type and specify the options as the only parameter when you want to use the the default batch type.
 
+If you want to execute the same prepared statement multiple times in a batch there is a special variant of the batching feature available from `PreparedStatement`:
+
+```ruby
+# the same counter_statement as in the example above
+counter_statement.batch do |batch|
+  batch.add(3, 'some_counter')
+  batch.add(2, 'another_counter')
+end
+```
+
 Cassandra 1.2 also supported batching, but only as a CQL feature, you had to build the batch as a string, and it didn't really play well with prepared statements.
 
 ## Paging
@@ -219,15 +231,11 @@ If you're using Cassandra 2.0 or later you can page your query results by adding
 ```ruby
 result_page = client.execute("SELECT * FROM large_table WHERE id = 'partition_with_lots_of_data'", page_size: 100)
 
-loop do
+while result_page
   result_page.each do |row|
     p row
   end
-  if result_page.last_page?
-    break
-  else
-    result_page = result_page.next_page
-  end
+  result_page = result_page.next_page
 end
 ```
 

data/lib/cql.rb

@@ -5,15 +5,21 @@ require 'ione'
 
 module Cql
   CqlError = Class.new(StandardError)
+  IoError = Ione::IoError
 
+  # @private
   Promise = Ione::Promise
+
+  # @private
   Future = Ione::Future
+
+  # @private
   Io = Ione::Io
-  IoError = Ione::IoError
 end
 
 require 'cql/uuid'
 require 'cql/time_uuid'
 require 'cql/compression'
 require 'cql/protocol'
+require 'cql/auth'
 require 'cql/client'

data/lib/cql/{client/authenticators.rb → auth.rb}

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 module Cql
-  module Client
+  module Auth
     # An auth provider is a factory for {Cql::Client::Authenticator} instances
     # (or objects matching that interface). Its {#create_authenticator} will be
     # called once for each connection that requires authentication.
@@ -71,46 +71,7 @@ module Cql
       # @param token [String] a token sent by the server
       # @return [nil]
     end
-
-    # Auth provider used for Cassandra's built in authentication.
-    #
-    # There is no need to create instances of this class to pass as `:auth_provider`
-    # to {Cql::Client.connect}, instead use the `:credentials` option and one
-    # will be created automatically for you.
-    class PlainTextAuthProvider
-      def initialize(username, password)
-        @username = username
-        @password = password
-      end
-
-      def create_authenticator(authentication_class)
-        if authentication_class == PASSWORD_AUTHENTICATOR_FQCN
-          PlainTextAuthenticator.new(@username, @password)
-        end
-      end
-
-      private
-
-      PASSWORD_AUTHENTICATOR_FQCN = 'org.apache.cassandra.auth.PasswordAuthenticator'.freeze
-    end
-
-    # Authenticator used for Cassandra's built in authentication,
-    # see {Cql::Client::PlainTextAuthProvider}
-    class PlainTextAuthenticator
-      def initialize(username, password)
-        @username = username
-        @password = password
-      end
-
-      def initial_response
-        "\x00#{@username}\x00#{@password}"
-      end
-
-      def challenge_response(token)
-      end
-
-      def authentication_successful(token)
-      end
-    end
   end
-end
+end
+
+require 'cql/auth/plain_text_auth'

data/lib/cql/auth/plain_text_auth.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Cql
+  module Auth
+    # Auth provider used for Cassandra's built in authentication.
+    #
+    # There is no need to create instances of this class to pass as `:auth_provider`
+    # to {Cql::Client.connect}, instead use the `:credentials` option and one
+    # will be created automatically for you.
+    class PlainTextAuthProvider
+      def initialize(username, password)
+        @username = username
+        @password = password
+      end
+
+      def create_authenticator(authentication_class)
+        if authentication_class == PASSWORD_AUTHENTICATOR_FQCN
+          PlainTextAuthenticator.new(@username, @password)
+        end
+      end
+
+      private
+
+      PASSWORD_AUTHENTICATOR_FQCN = 'org.apache.cassandra.auth.PasswordAuthenticator'.freeze
+    end
+
+    # Authenticator used for Cassandra's built in authentication,
+    # see {Cql::Auth::PlainTextAuthProvider}
+    class PlainTextAuthenticator
+      def initialize(username, password)
+        @username = username
+        @password = password
+      end
+
+      def initial_response
+        "\x00#{@username}\x00#{@password}"
+      end
+
+      def challenge_response(token)
+      end
+
+      def authentication_successful(token)
+      end
+    end
+  end
+end

data/lib/cql/client.rb

@@ -20,7 +20,6 @@ module Cql
   TimeoutError = Class.new(CqlError)
   ClientError = Class.new(CqlError)
   AuthenticationError = Class.new(ClientError)
-  IncompleteTraceError = Class.new(ClientError)
   UnsupportedProtocolVersionError = Class.new(ClientError)
   NotPreparedError = Class.new(ClientError)
 
@@ -92,9 +91,6 @@ module Cql
     # @param [Hash] options
     # @option options [Array<String>] :hosts (['localhost']) One or more
     #   hostnames used as seed nodes when connecting. Duplicates will be removed.
-    # @option options [String] :host ('localhost') A comma separated list of 
-    #   hostnames to use as seed nodes. This is a backwards-compatible version
-    #   of the :hosts option, and is deprecated.
     # @option options [String] :port (9042) The port to connect to, this port
     #   will be used for all nodes. Because the `system.peers` table does not
     #   contain the port that the nodes are listening on, the port must be the
@@ -143,7 +139,6 @@ require 'cql/client/connector'
 require 'cql/client/null_logger'
 require 'cql/client/column_metadata'
 require 'cql/client/result_metadata'
-require 'cql/client/query_trace'
 require 'cql/client/execute_options_decoder'
 require 'cql/client/keyspace_changer'
 require 'cql/client/client'
@@ -152,5 +147,4 @@ require 'cql/client/batch'
 require 'cql/client/query_result'
 require 'cql/client/void_result'
 require 'cql/client/request_runner'
-require 'cql/client/authenticators'
 require 'cql/client/peer_discovery'

data/lib/cql/client/batch.rb

@@ -2,6 +2,13 @@
 
 module Cql
   module Client
+    # Batches let you send multiple queries (`INSERT`, `UPDATE` and `DELETE`) in
+    # one go. This can lead to better performance, and depending on the options
+    # you specify can also give you different consistency guarantees.
+    #
+    # Batches can contain a mix of different queries and prepared statements.
+    #
+    # @see Cql::Client::Client#batch
     class Batch
       # @!method add(cql_or_prepared_statement, *bound_values)
       #
@@ -37,6 +44,10 @@ module Cql
       # @return [Cql::Client::VoidResult] a batch always returns a void result
     end
 
+    # A convenient wrapper that makes it easy to build batches of multiple
+    # executions of the same prepared statement.
+    #
+    # @see Cql::Client::PreparedStatement#batch
     class PreparedStatementBatch
       # @!method add(*bound_values)
       #

data/lib/cql/client/client.rb

@@ -2,18 +2,29 @@
 
 module Cql
   module Client
+    # A CQL client manages connections to one or more Cassandra nodes and you use
+    # it run queries, insert and update data, prepare statements and switch
+    # keyspaces.
+    #
+    # To get a reference to a client you call {Cql::Client.connect}. When you
+    # don't need the client anymore you can call {#close} to close all connections.
+    #
+    # Internally the client runs an IO reactor in a background thread. The reactor
+    # handles all IO and manages the connections to the Cassandra nodes. This
+    # makes it possible for the client to handle highly concurrent applications
+    # very efficiently.
+    #
+    # Client instances are threadsafe and you only need a single instance for in
+    # an application. Using multiple instances is more likely to lead to worse
+    # performance than better.
+    #
+    # Because the client opens sockets, and runs threads it cannot be used by
+    # the child created when forking a process. If your application forks (for
+    # example applications running in the Unicorn application server or Resque
+    # task queue) you _must_ connect after forking.
+    #
+    # @see Cql::Client.connect
     class Client
-      # @!method connect
-      #
-      # Connect to all nodes. See {Cql::Client.connect} for the full
-      # documentation.
-      #
-      # This method needs to be called before any other. Calling it again will
-      # have no effect.
-      #
-      # @see Cql::Client.connect
-      # @return [Cql::Client]
-
       # @!method close
       #
       # Disconnect from all nodes.
@@ -43,7 +54,7 @@ module Cql
       # @raise [Cql::NotConnectedError] raised when the client is not connected
       # @return [nil]
 
-      # @!method execute(cql, *values, options_or_consistency={})
+      # @!method execute(cql, *values, options={})
       #
       # Execute a CQL statement, optionally passing bound values.
       #
@@ -55,7 +66,8 @@ module Cql
       # bound values when you will issue the request multiple times, prepared
       # statements are almost always a better choice.
       #
-      # @note On-the-fly bound values are not supported in Cassandra 1.2
+      # _Please note that on-the-fly bound values are only supported by Cassandra
+      # 2.0 and above._
       #
       # @example A simple CQL query
       #   result = client.execute("SELECT * FROM users WHERE user_name = 'sue'")
@@ -75,6 +87,15 @@ module Cql
       # @example Specifying the consistency and other options
       #   client.execute("SELECT * FROM users", consistency: :all, timeout: 1.5)
       #
+      # @example Loading a big result page by page
+      #   result_page = client.execute("SELECT * FROM large_table WHERE id = 'partition_with_lots_of_data'", page_size: 100)
+      #   while result_page
+      #     result_page.each do |row|
+      #       p row
+      #     end
+      #     result_page = result_page.next_page
+      #   end
+      #
       # @example Activating tracing for a query
       #   result = client.execute("SELECT * FROM users", tracing: true)
       #   p result.trace_id
@@ -88,24 +109,26 @@ module Cql
       #   integers, and DOUBLE instead of FLOAT for floating point numbers. It
       #   is not recommended to use this feature for anything but convenience,
       #   and the algorithm used to guess types is to be considered experimental.
-      # @param [Hash] options_or_consistency Either a consistency as a symbol
-      #   (e.g. `:quorum`), or a options hash (see below). Passing a symbol is
-      #   equivalent to passing the options `consistency: <symbol>`.
-      # @option options_or_consistency [Symbol] :consistency (:quorum) The
+      # @param [Hash] options
+      # @option options [Symbol] :consistency (:quorum) The
       #   consistency to use for this query.
-      # @option options_or_consistency [Symbol] :serial_consistency (nil) The
+      # @option options [Symbol] :serial_consistency (nil) The
       #   consistency to use for conditional updates (`:serial` or
       #   `:local_serial`), see the CQL documentation for the semantics of
       #   serial consistencies and conditional updates. The default is assumed
       #   to be `:serial` by the server if none is specified. Ignored for non-
       #   conditional queries.
-      # @option options_or_consistency [Integer] :timeout (nil) How long to wait
+      # @option options [Integer] :timeout (nil) How long to wait
       #   for a response. If this timeout expires a {Cql::TimeoutError} will
       #   be raised.
-      # @option options_or_consistency [Boolean] :trace (false) Request tracing
+      # @option options [Boolean] :trace (false) Request tracing
       #   for this request. See {Cql::Client::QueryResult} and
       #   {Cql::Client::VoidResult} for how to retrieve the tracing data.
-      # @option options_or_consistency [Array] :type_hints (nil) When passing
+      # @option options [Integer] :page_size (nil) Instead of
+      #   returning all rows, return the response in pages of this size. The
+      #   first result will contain the first page, to load subsequent pages
+      #   use {Cql::Client::QueryResult#next_page}.
+      # @option options [Array] :type_hints (nil) When passing
       #   on-the-fly bound values the request encoder will have to guess what
       #   types to encode the values as. Using this option you can give it hints
       #   and avoid it guessing wrong. The hints must be an array that has the
@@ -127,7 +150,7 @@ module Cql
       # @!method prepare(cql)
       #
       # Returns a prepared statement that can be run over and over again with
-      # different values.
+      # different bound values.
       #
       # @see Cql::Client::PreparedStatement
       # @param [String] cql The CQL to prepare
@@ -203,7 +226,7 @@ module Cql
         @port = options[:port] || DEFAULT_PORT
         @connection_timeout = options[:connection_timeout] || DEFAULT_CONNECTION_TIMEOUT
         @credentials = options[:credentials]
-        @auth_provider = options[:auth_provider] || @credentials && PlainTextAuthProvider.new(*@credentials.values_at(:username, :password))
+        @auth_provider = options[:auth_provider] || @credentials && Auth::PlainTextAuthProvider.new(*@credentials.values_at(:username, :password))
         @connected = false
         @connecting = false
         @closing = false
@@ -314,7 +337,7 @@ module Cql
       MAX_RECONNECTION_ATTEMPTS = 5
 
       def extract_hosts(options)
-        if options[:hosts]
+        if options[:hosts] && options[:hosts].any?
           options[:hosts].uniq
         elsif options[:host]
           options[:host].split(',').uniq

data/lib/cql/client/column_metadata.rb

@@ -7,7 +7,7 @@ module Cql
     # the type as a symbol (e.g. `:varchar`, `:int`, `:date`).
     class ColumnMetadata
       attr_reader :keyspace, :table, :column_name, :type
-      
+
       # @private
       def initialize(*args)
         @keyspace, @table, @column_name, @type = args

data/lib/cql/client/keyspace_changer.rb

@@ -5,7 +5,7 @@ module Cql
     # @private
     class KeyspaceChanger
       KEYSPACE_NAME_PATTERN = /^\w[\w\d_]*$|^"\w[\w\d_]*"$/
-      
+
       def initialize(request_runner=RequestRunner.new)
         @request_runner = request_runner
       end

data/lib/cql/client/peer_discovery.rb

@@ -2,6 +2,7 @@
 
 module Cql
   module Client
+    # @private
     class PeerDiscovery
       def initialize(seed_connections)
         @seed_connections = seed_connections

data/lib/cql/client/prepared_statement.rb

@@ -2,6 +2,34 @@
 
 module Cql
   module Client
+    # A prepared statement are CQL queries that have been sent to the server
+    # to be precompiled, so that when executed only their ID and not the whole
+    # CQL string need to be sent. They support bound values, or placeholders
+    # for values.
+    #
+    # Using a prepared statement for any query that you execute more than once
+    # is highly recommended. Besides the benefit of having less network overhead,
+    # and less processing overhead on the server side, they don't require you
+    # to build CQL strings and escape special characters, or format non-character
+    # data such as UUIDs, different numeric types, or collections, in the
+    # correct way.
+    #
+    # You should only prepare a statement once and reuse the prepared statement
+    # object every time you want to execute that particular query. The statement
+    # object will make sure that it is prepared on all connections, and will
+    # (lazily, but transparently) make sure it is prepared on any new connections.
+    #
+    # It is an anti-pattern to prepare the same query over and over again. It is
+    # bad for performance, since every preparation requires a roundtrip to all
+    # connected servers, and because of some bookeeping that is done to support
+    # automatic preparation on new connections, it will lead to unnecessary
+    # extra memory usage. There is no performance benefit in creating multiple
+    # prepared statement objects for the same query.
+    #
+    # Prepared statement objects are completely thread safe and can be shared
+    # across all threads in your application.
+    #
+    # @see Cql::Client::Client#prepare
     class PreparedStatement
       # Metadata describing the bound values
       #
@@ -28,10 +56,22 @@ module Cql
       # arguments should result in an `ArgumentError` or `TypeError` being
       # raised.
       #
-      # @param args [Array] the values for the bound parameters. The last
-      #   argument can also be an options hash or a symbol (as a shortcut for
-      #   specifying the consistency), see {Cql::Client::Client#execute} for
-      #   full details.
+      # @example Preparing and executing an `INSERT` statement
+      #   statement = client.prepare(%(INSERT INTO metrics (id, time, value) VALUES (?, NOW(), ?)))
+      #   statement.execute(1234, 23432)
+      #   statement.execute(2345, 34543, tracing: true)
+      #   statement.execute(3456, 45654, consistency: :one)
+      #
+      # @example Preparing and executing a `SELECT` statement
+      #   statement = client.prepare(%(SELECT * FROM metrics WHERE id = ? AND time > ?))
+      #   result = statement.execute(1234, Time.now - 3600)
+      #   result.each do |row|
+      #     p row
+      #   end
+      #
+      # @param args [Array] the values for the bound parameters, and an optional
+      #   hash of options as last argument – see {Cql::Client::Client#execute}
+      #   for details on which options are available.
       # @raise [ArgumentError] raised when number of argument does not match
       #   the number of parameters needed to be bound to the statement.
       # @raise [Cql::NotConnectedError] raised when the client is not connected
@@ -45,6 +85,45 @@ module Cql
       #   (see {Cql::Client::VoidResult}).
       def execute(*args)
       end
+
+      # Yields a batch when called with a block. The batch is automatically
+      # executed at the end of the block and the result is returned.
+      #
+      # Returns a batch when called wihtout a block. The batch will remember
+      # the options given and merge these with any additional options given
+      # when {Cql::Client::PreparedStatementBatch#execute} is called.
+      #
+      # The batch yielded or returned by this method is not identical to the
+      # regular batch objects yielded or returned by {Cql::Client::Client#batch}.
+      # These prepared statement batch objects can be used only to add multiple
+      # executions of the same prepared statement.
+      #
+      # Please note that the batch object returned by this method _is not thread
+      # safe_.
+      #
+      # The type parameter can be ommitted and the options can then be given
+      # as first parameter.
+      #
+      # @example Executing a prepared statement in a batch
+      #   statement = client.prepare(%(INSERT INTO metrics (id, time, value) VALUES (?, NOW(), ?)))
+      #   statement.batch do |batch|
+      #     batch.add(1234, 23423)
+      #     batch.add(2346, 13)
+      #     batch.add(2342, 2367)
+      #     batch.add(4562, 1231)
+      #   end
+      #
+      # @see Cql::Client::PreparedStatementBatch
+      # @see Cql::Client::Client#batch
+      # @param [Symbol] type the type of batch, must be one of `:logged`,
+      #   `:unlogged` and `:counter`. The precise meaning of these  is defined
+      #   in the CQL specification.
+      # @yieldparam [Cql::Client::PreparedStatementBatch] batch the batch
+      # @return [Cql::Client::VoidResult, Cql::Client::Batch] when no block is
+      #   given the batch is returned, when a block is given the result of
+      #   executing the batch is returned (see {Cql::Client::Batch#execute}).
+      def batch(type=:logged, options={})
+      end
     end
 
     # @private

data/lib/cql/client/query_result.rb

@@ -2,6 +2,16 @@
 
 module Cql
   module Client
+    # Query results encapsulate the rows returned by a query.
+    #
+    # In addition to containing the rows it contains metadata about the data
+    # types of the columns of the rows, and it knows the ID of the trace,
+    # if tracing was requested for the query.
+    #
+    # When paging over a big result you can use {#last_page?} to find out if the
+    # page is the last, or {#next_page} to retrieve the next page.
+    #
+    # `QueryResult` is an `Enumerable` so it can be mapped, filtered, reduced, etc.
     class QueryResult
       include Enumerable
 
@@ -37,8 +47,31 @@ module Cql
         @rows.each(&block)
       end
       alias_method :each_row, :each
+
+      # Returns true when there are no more pages to load.
+      #
+      # This is only relevant when you have requested paging of the results with
+      # the `:page_size` option to {Cql::Client::Client#execute} or
+      # {Cql::Client::PreparedStatement#execute}.
+      #
+      # @see Cql::Client::Client#execute
+      def last_page?
+        true
+      end
+
+      # Returns the next page or nil when there is no next page.
+      #
+      # This is only relevant when you have requested paging of the results with
+      # the `:page_size` option to {Cql::Client::Client#execute} or
+      # {Cql::Client::PreparedStatement#execute}.
+      #
+      # @see Cql::Client::Client#execute
+      def next_page
+        nil
+      end
     end
 
+    # @private
     class PagedQueryResult < QueryResult
       def metadata
         @result.metadata
@@ -88,6 +121,7 @@ module Cql
       end
 
       def next_page
+        return Future.resolved(nil) if last_page?
         @client.execute(@request.cql, *@request.values, @options)
       end
     end
@@ -100,6 +134,7 @@ module Cql
       end
 
       def next_page
+        return Future.resolved(nil) if last_page?
         @prepared_statement.execute(*@request.values, @options)
       end
     end
@@ -121,7 +156,10 @@ module Cql
       end
 
       def next_page
-        synchronous_backtrace { self.class.new(@result.next_page.value) }
+        synchronous_backtrace do
+          asynchronous_result = @result.next_page.value
+          asynchronous_result && self.class.new(asynchronous_result)
+        end
       end
     end
 

data/lib/cql/client/result_metadata.rb

@@ -2,6 +2,9 @@
 
 module Cql
   module Client
+    # A collection of metadata (keyspace, table, name and type) of a result set.
+    #
+    # @see Cql::Client::ColumnMetadata
     class ResultMetadata
       include Enumerable
 
@@ -13,7 +16,6 @@ module Cql
       # Returns the column metadata
       #
       # @return [ColumnMetadata] column_metadata the metadata for the column
-      #
       def [](column_name)
         @metadata[column_name]
       end
@@ -22,7 +24,6 @@ module Cql
       #
       # @yieldparam [ColumnMetadata] metadata the metadata for each column
       # @return [Enumerable<ColumnMetadata>]
-      #
       def each(&block)
         @metadata.each_value(&block)
       end

data/lib/cql/client/void_result.rb

@@ -2,6 +2,16 @@
 
 module Cql
   module Client
+    # Many CQL queries do not return any rows, but they can still return
+    # data about the query, for example the trace ID. This class exist to make
+    # that data available.
+    #
+    # It has the exact same API as {Cql::Client::QueryResult} so that you don't
+    # need to check the return value of for example {Cql::Client::Client#execute}.
+    #
+    # @see Cql::Client::QueryResult
+    # @see Cql::Client::Client#execute
+    # @see Cql::Client::PreparedStatement#execute
     class VoidResult
       include Enumerable
 
@@ -26,6 +36,16 @@ module Cql
         true
       end
 
+      # Always returns true
+      def last_page?
+        true
+      end
+
+      # Always returns nil
+      def next_page
+        nil
+      end
+
       # No-op for API compatibility with {QueryResult}.
       #
       # @return [Enumerable]

data/lib/cql/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Cql
-  VERSION = '2.0.0.pre2'.freeze
+  VERSION = '2.0.0.rc0'.freeze
 end

data/spec/cql/{client/authenticators_spec.rb → auth/plain_text_auth_spec.rb}

@@ -4,7 +4,7 @@ require 'spec_helper'
 
 
 module Cql
-  module Client
+  module Auth
     describe PlainTextAuthProvider do
       let :auth_provider do
         described_class.new('foo', 'bar')

data/spec/cql/client/client_spec.rb

@@ -11,7 +11,7 @@ module Cql
       end
 
       let :default_connection_options do
-        {:host => 'example.com', :port => 12321, :io_reactor => io_reactor, :logger => logger}
+        {:hosts => %w[example.com], :port => 12321, :io_reactor => io_reactor, :logger => logger}
       end
 
       let :connection_options do
@@ -162,6 +162,19 @@ module Cql
           expect { client.connect.value }.to raise_error('bork')
         end
 
+        it 'connects to localhost by default' do
+          connection_options.delete(:hosts)
+          c = described_class.new(connection_options)
+          c.connect.value
+          connections.map(&:host).should == %w[localhost]
+        end
+
+        it 'connects to localhost when an empty list of hosts is given' do
+          c = described_class.new(connection_options.merge(hosts: []))
+          c.connect.value
+          connections.map(&:host).should == %w[localhost]
+        end
+
         context 'when connecting to multiple hosts' do
           before do
             client.close.value
@@ -175,6 +188,7 @@ module Cql
           end
 
           it 'connects to all hosts, when given as a comma-sepatated string' do
+            connection_options.delete(:hosts)
             c = described_class.new(connection_options.merge(host: 'h1.example.com,h2.example.com,h3.example.com'))
             c.connect.value
             connections.should have(3).items
@@ -510,7 +524,7 @@ module Cql
 
         context 'when the server requests authentication' do
           let :auth_provider do
-            PlainTextAuthProvider.new('foo', 'bar')
+            Auth::PlainTextAuthProvider.new('foo', 'bar')
           end
 
           def accepting_request_handler(request, *)

data/spec/cql/client/prepared_statement_spec.rb

@@ -236,7 +236,6 @@ module Cql
 
           it 'returns a result which knows when there are no more pages' do
             result = statement.execute(11, 'foo', page_size: 2).value
-            result = result.next_page.value
             result.should be_last_page
           end
         end

data/spec/cql/client/query_result_spec.rb

@@ -84,6 +84,18 @@ module Cql
           result.should_not be_empty
         end
       end
+
+      describe '#last_page?' do
+        it 'returns true' do
+          result.should be_last_page
+        end
+      end
+
+      describe '#next_page' do
+        it 'returns nil' do
+          result.next_page.should be_nil
+        end
+      end
     end
 
     describe LazyQueryResult do
@@ -209,11 +221,16 @@ module Cql
 
       describe '#next_page' do
         let :next_query_result do
-          double(:next_query_result, paging_state: 'thenextpagingstate')
+          described_class.new(client, request, double(:next_query_result, paging_state: 'thenextpagingstate'), options)
+        end
+
+        let :last_query_result do
+          described_class.new(client, request, double(:next_query_result, paging_state: nil), options)
         end
 
         before do
           client.stub(:execute).and_return(Future.resolved(next_query_result))
+          client.stub(:execute).with(anything, anything, hash_including(paging_state: 'thenextpagingstate')).and_return(Future.resolved(last_query_result))
         end
 
         it 'calls the client and passes the paging state' do
@@ -252,6 +269,11 @@ module Cql
           f = paged_query_result.next_page
           f.value.should equal(next_query_result)
         end
+
+        it 'returns nil when it is the last page' do
+          f = paged_query_result.next_page.value.next_page.value.next_page
+          f.value.should be_nil
+        end
       end
     end
 
@@ -280,16 +302,20 @@ module Cql
 
       describe '#next_page' do
         let :next_query_result do
-          double(:next_query_result, paging_state: 'thenextpagingstate')
+          described_class.new(statement, request, double(:next_query_result, paging_state: 'thenextpagingstate'), options)
+        end
+
+        let :last_query_result do
+          described_class.new(statement, request, double(:next_query_result, paging_state: nil), options)
         end
 
         before do
           statement.stub(:execute).and_return(Future.resolved(next_query_result))
+          statement.stub(:execute).with(anything, anything, hash_including(paging_state: 'thenextpagingstate')).and_return(Future.resolved(last_query_result))
         end
 
         it 'calls the statement and passes the paging state' do
           paged_query_result.next_page.value
-          statement.should have_received(:execute).with(anything, anything, hash_including(paging_state: 'thepagingstate'))
         end
 
         it 'calls the statement and passes the options' do
@@ -312,6 +338,11 @@ module Cql
           f = paged_query_result.next_page
           f.value.should equal(next_query_result)
         end
+
+        it 'returns nil when it is the last page' do
+          f = paged_query_result.next_page.value.next_page.value.next_page
+          f.value.should be_nil
+        end
       end
     end
 
@@ -336,6 +367,11 @@ module Cql
           second_page.next_page
           next_query_result.should have_received(:next_page)
         end
+
+        it 'returns nil when it is the last page' do
+          asynchronous_paged_query_result.stub(:next_page).and_return(Future.resolved(nil))
+          paged_query_result.next_page.should be_nil
+        end
       end
 
       describe '#last_page?' do

data/spec/cql/client/void_result_spec.rb

@@ -12,6 +12,18 @@ module Cql
         end
       end
 
+      describe '#last_page?' do
+        it 'is true' do
+          described_class.new.should be_last_page
+        end
+      end
+
+      describe '#next_page' do
+        it 'returns nil' do
+          described_class.new.next_page.should be_nil
+        end
+      end
+
       describe '#trace_id' do
         it 'is nil' do
           described_class.new.trace_id.should be_nil

data/spec/integration/client_spec.rb

@@ -192,7 +192,7 @@ describe 'A CQL client' do
 
       it 'raises an error when only an auth provider has been given' do
         pending('authentication not configured', unless: authentication_enabled) do
-          auth_provider = Cql::Client::PlainTextAuthProvider.new('cassandra', 'cassandra')
+          auth_provider = Cql::Auth::PlainTextAuthProvider.new('cassandra', 'cassandra')
           expect { Cql::Client.connect(connection_options.merge(credentials: nil, auth_provider: auth_provider, protocol_version: 1)) }.to raise_error(Cql::AuthenticationError)
         end
       end
@@ -209,7 +209,7 @@ describe 'A CQL client' do
       end
 
       it 'uses the auth provider given in the :auth_provider option' do
-        auth_provider = Cql::Client::PlainTextAuthProvider.new('cassandra', 'cassandra')
+        auth_provider = Cql::Auth::PlainTextAuthProvider.new('cassandra', 'cassandra')
         client = Cql::Client.connect(connection_options.merge(auth_provider: auth_provider, credentials: nil))
         client.execute('SELECT * FROM system.schema_keyspaces')
       end
@@ -228,7 +228,7 @@ describe 'A CQL client' do
       it 'raises an error when the credentials are bad' do
         pending('authentication not configured', unless: authentication_enabled) do
           expect {
-            auth_provider = Cql::Client::PlainTextAuthProvider.new('foo', 'bar')
+            auth_provider = Cql::Auth::PlainTextAuthProvider.new('foo', 'bar')
             Cql::Client.connect(connection_options.merge(auth_provider: auth_provider, credentials: nil))
           }.to raise_error(Cql::AuthenticationError)
         end
@@ -408,6 +408,18 @@ describe 'A CQL client' do
       result_page.count.should == row_count - page_size
       result_page.should be_last_page
     end
+
+    it 'returns nil from #next_page when the last page has been returned' do
+      page_size = row_count/5 + 1
+      statement = client.prepare('SELECT * FROM counters')
+      result_page = statement.execute(page_size: page_size)
+      page_count = 0
+      while result_page
+        page_count += 1
+        result_page = result_page.next_page
+      end
+      page_count.should == 5
+    end
   end
 
   context 'with error conditions' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cql-rb
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre2
+  version: 2.0.0.rc0
 platform: ruby
 authors:
 - Theo Hultberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-06 00:00:00.000000000 Z
+date: 2014-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ione
@@ -34,8 +34,9 @@ files:
 - .yardopts
 - README.md
 - lib/cql.rb
+- lib/cql/auth.rb
+- lib/cql/auth/plain_text_auth.rb
 - lib/cql/client.rb
-- lib/cql/client/authenticators.rb
 - lib/cql/client/batch.rb
 - lib/cql/client/client.rb
 - lib/cql/client/column_metadata.rb
@@ -47,7 +48,6 @@ files:
 - lib/cql/client/peer_discovery.rb
 - lib/cql/client/prepared_statement.rb
 - lib/cql/client/query_result.rb
-- lib/cql/client/query_trace.rb
 - lib/cql/client/request_runner.rb
 - lib/cql/client/result_metadata.rb
 - lib/cql/client/void_result.rb
@@ -91,7 +91,7 @@ files:
 - lib/cql/time_uuid.rb
 - lib/cql/uuid.rb
 - lib/cql/version.rb
-- spec/cql/client/authenticators_spec.rb
+- spec/cql/auth/plain_text_auth_spec.rb
 - spec/cql/client/batch_spec.rb
 - spec/cql/client/client_spec.rb
 - spec/cql/client/column_metadata_spec.rb
@@ -102,7 +102,6 @@ files:
 - spec/cql/client/peer_discovery_spec.rb
 - spec/cql/client/prepared_statement_spec.rb
 - spec/cql/client/query_result_spec.rb
-- spec/cql/client/query_trace_spec.rb
 - spec/cql/client/request_runner_spec.rb
 - spec/cql/client/void_result_spec.rb
 - spec/cql/compression/compression_common.rb
@@ -174,7 +173,7 @@ signing_key:
 specification_version: 4
 summary: Cassandra CQL3 driver
 test_files:
-- spec/cql/client/authenticators_spec.rb
+- spec/cql/auth/plain_text_auth_spec.rb
 - spec/cql/client/batch_spec.rb
 - spec/cql/client/client_spec.rb
 - spec/cql/client/column_metadata_spec.rb
@@ -185,7 +184,6 @@ test_files:
 - spec/cql/client/peer_discovery_spec.rb
 - spec/cql/client/prepared_statement_spec.rb
 - spec/cql/client/query_result_spec.rb
-- spec/cql/client/query_trace_spec.rb
 - spec/cql/client/request_runner_spec.rb
 - spec/cql/client/void_result_spec.rb
 - spec/cql/compression/compression_common.rb

data/lib/cql/client/query_trace.rb

@@ -1,46 +0,0 @@
-# encoding: utf-8
-
-module Cql
-  module Client
-    # @private
-    class QueryTrace
-      attr_reader :coordinator, :cql, :started_at, :duration, :events
-
-      # @private
-      def initialize(session, events)
-        if session
-          raise IncompleteTraceError, 'Trace incomplete, try loading it again' unless session['duration']
-          @coordinator = session['coordinator']
-          @cql = (parameters = session['parameters']) && parameters['query']
-          @started_at = session['started_at']
-          @duration = session['duration']/1_000_000.0
-          if events
-            @events = events.map { |e| TraceEvent.new(e) }.freeze
-          end
-        else
-          @events = [].freeze
-        end
-      end
-    end
-
-    # @private
-    class TraceEvent
-      attr_reader :activity, :source, :source_elapsed, :time
-
-      # @private
-      def initialize(event)
-        @activity = event['activity']
-        @source = event['source']
-        @source_elapsed = event['source_elapsed']/1_000_000.0
-        @time = event['event_id'].to_time
-      end
-    end
-
-    # @private
-    class NullQueryTrace < QueryTrace
-      def initialize
-        super(nil, nil)
-      end
-    end
-  end
-end

data/spec/cql/client/query_trace_spec.rb

@@ -1,138 +0,0 @@
-# encoding: utf-8
-
-require 'spec_helper'
-
-
-module Cql
-  module Client
-    describe QueryTrace do
-      let :trace do
-        described_class.new(session_row, event_rows)
-      end
-
-      let :started_at do
-        Time.now
-      end
-
-      let :session_row do
-        {
-          'session_id' => Uuid.new('a1028490-3f05-11e3-9531-fb72eff05fbb'),
-          'coordinator' => IPAddr.new('127.0.0.1'),
-          'duration' => 1263,
-          'parameters' => {
-            'query' => 'SELECT * FROM something'
-          },
-          'request' => 'Execute CQL3 query',
-          'started_at' => started_at
-        }
-      end
-
-      let :event_rows do
-        [
-          {
-            'session_id' => Uuid.new('a1028490-3f05-11e3-9531-fb72eff05fbb'),
-            'event_id' => TimeUuid.new('a1028491-3f05-11e3-9531-fb72eff05fbb'),
-            'activity' => 'Parsing statement',
-            'source' => IPAddr.new('127.0.0.1'),
-            'source_elapsed' => 52,
-            'thread' => 'Native-Transport-Requests:126'
-          },
-          {
-            'session_id' => Uuid.new('a1028490-3f05-11e3-9531-fb72eff05fbb'),
-            'event_id' => TimeUuid.new('a1028492-3f05-11e3-9531-fb72eff05fbb'),
-            'activity' => 'Peparing statement',
-            'source' => IPAddr.new('127.0.0.1'),
-            'source_elapsed' => 54,
-            'thread' => 'Native-Transport-Requests:126'
-          },
-        ]
-      end
-
-      context 'when the session is nil' do
-        it 'returns nil from all methods' do
-          trace = described_class.new(nil, nil)
-          trace.coordinator.should be_nil
-          trace.cql.should be_nil
-          trace.started_at.should be_nil
-          trace.events.should be_empty
-        end
-      end
-
-      context 'when the duration field of the session is nil' do
-        it 'raises an IncompleteTraceError' do
-          session_row['duration'] = nil
-          expect { described_class.new(session_row, event_rows) }.to raise_error(IncompleteTraceError)
-        end
-      end
-
-      describe '#coordinator' do
-        it 'returns the IP address of the coordinator node' do
-          trace.coordinator.should == IPAddr.new('127.0.0.1')
-        end
-      end
-
-      describe '#cql' do
-        it 'returns the query' do
-          trace.cql.should == 'SELECT * FROM something'
-        end
-      end
-
-      describe '#started_at' do
-        it 'returns the time the request started' do
-          trace.started_at.should eql(started_at)
-        end
-      end
-
-      describe '#duration' do
-        it 'returns the duration in seconds' do
-          trace.duration.should == 0.001263
-        end
-      end
-
-      describe '#events' do
-        it 'returns a list of TraceEvents' do
-          trace.events.should have(2).items
-          trace.events.first.should be_a(TraceEvent)
-        end
-
-        it 'returns an unmodifiable list' do
-          expect { trace.events << :foo }.to raise_error
-        end
-
-        context 'returns a list of trace events whose' do
-          let :events do
-            trace.events
-          end
-
-          let :event do
-            events.first
-          end
-
-          describe '#activity' do
-            it 'returns the event activity' do
-              event.activity.should == 'Parsing statement'
-            end
-          end
-
-          describe '#source' do
-            it 'returns the event source' do
-              event.source.should == IPAddr.new('127.0.0.1')
-            end
-          end
-
-          describe '#source_elapsed' do
-            it 'returns the elapsed time at the source' do
-              event.source_elapsed.should == 0.000052
-            end
-          end
-
-          describe '#time' do
-            it 'returns the time component from the event ID' do
-              event.time.to_i.should == TimeUuid.new('a1028492-3f05-11e3-9531-fb72eff05fbb').to_time.to_i
-            end
-          end
-        end
-      end
-    end
-  end
-end