cql-rb 2.0.0.pre0 → 2.0.0.pre1

data/lib/cql/client/authenticators.rb

@@ -2,6 +2,76 @@
 
 module Cql
   module Client
+    # 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.
+    #
+    # 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.
+    #
+    # @note Auth providers given to {Cql::Client.connect} as the `:auth_provider`
+    #   option don't need to be subclasses of this class, but need to
+    #   implement the same methods. This class exists only for documentation
+    #   purposes.
+    class AuthProvider
+      # @!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 [Cql::Client::Authenticator, nil] an object with an interface
+      #   matching {Cql::Client::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.
+    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 [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`

data/lib/cql/client/batch.rb

@@ -2,6 +2,60 @@
 
 module Cql
   module Client
+    class Batch
+      # @!method add(cql_or_prepared_statement, *bound_values)
+      #
+      # Add a query or a prepared statement to the batch.
+      #
+      # @example Adding a mix of statements to a batch
+      #   batch.add(%(UPDATE people SET name = 'Miriam' WHERE id = 3435))
+      #   batch.add(%(UPDATE people SET name = ? WHERE id = ?), 'Miriam', 3435)
+      #   batch.add(prepared_statement, 'Miriam', 3435)
+      #
+      # @param [String, Cql::Client::PreparedStatement] cql_or_prepared_statement
+      #   a CQL string or a prepared statement object (obtained through
+      #   {Cql::Client::Client#prepare})
+      # @param [Array] bound_values a list of bound values -- only applies when
+      #   adding prepared statements and when there are binding markers in the
+      #   given CQL. If the last argument is a hash and it has the key
+      #   `:type_hints` this will be passed as type hints to the request encoder
+      #   (if the last argument is any other hash it will be assumed to be a
+      #   bound value of type MAP). See {Cql::Client::Client#execute} for more
+      #   info on type hints.
+      # @return [nil]
+
+      # @!method execute(options={})
+      #
+      # Execute the batch and return the result.
+      #
+      # @param options [Hash] an options hash or a symbol (as a shortcut for
+      #   specifying the consistency), see {Cql::Client::Client#execute} for
+      #   full details about how this value is interpreted.
+      # @raise [Cql::QueryError] raised when there is an error on the server side
+      # @raise [Cql::NotPreparedError] raised in the unlikely event that a
+      #   prepared statement was not prepared on the chosen connection
+      # @return [Cql::Client::VoidResult] a batch always returns a void result
+    end
+
+    class PreparedStatementBatch
+      # @!method add(*bound_values)
+      #
+      # Add the statement to the batch with the specified bound values.
+      #
+      # @param [Array] bound_values the values to bind to the added statement,
+      #   see {Cql::Client::PreparedStatement#execute}.
+      # @return [nil]
+
+      # @!method execute(options={})
+      #
+      # Execute the batch and return the result.
+      #
+      # @raise [Cql::QueryError] raised when there is an error on the server side
+      # @raise [Cql::NotPreparedError] raised in the unlikely event that a
+      #   prepared statement was not prepared on the chosen connection
+      # @return [Cql::Client::VoidResult] a batch always returns a void result
+    end
+
     # @private
     class AsynchronousBatch < Batch
       def initialize(type, execute_options_decoder, connection_manager, options=nil)

data/lib/cql/client/{asynchronous_client.rb → client.rb}

@@ -2,6 +2,188 @@
 
 module Cql
   module Client
+    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.
+      #
+      # @return [Cql::Client]
+
+      # @!method connected?
+      #
+      # Returns whether or not the client is connected.
+      #
+      # @return [true, false]
+
+      # @!method keyspace
+      #
+      # Returns the name of the current keyspace, or `nil` if no keyspace has been
+      # set yet.
+      #
+      # @return [String]
+
+      # @!method use(keyspace)
+      #
+      # Changes keyspace by sending a `USE` statement to all connections.
+      #
+      # The the second parameter is meant for internal use only.
+      #
+      # @param [String] keyspace
+      # @raise [Cql::NotConnectedError] raised when the client is not connected
+      # @return [nil]
+
+      # @!method execute(cql, *values, options_or_consistency={})
+      #
+      # Execute a CQL statement, optionally passing bound values.
+      #
+      # When passing bound values the request encoder will have to guess what
+      # types to encode the values as. For most types this will be no problem,
+      # but for integers and floating point numbers the larger size will be
+      # chosen (e.g. `BIGINT` and `DOUBLE` and not `INT` and `FLOAT`). You can
+      # override the guessing with the `:type_hint` option. Don't use on-the-fly
+      # 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
+      #
+      # @example A simple CQL query
+      #   result = client.execute("SELECT * FROM users WHERE user_name = 'sue'")
+      #   result.each do |row|
+      #     p row
+      #   end
+      #
+      # @example Using on-the-fly bound values
+      #   client.execute('INSERT INTO users (user_name, full_name) VALUES (?, ?)', 'sue', 'Sue Smith')
+      #
+      # @example Using on-the-fly bound values with type hints
+      #   client.execute('INSERT INTO users (user_name, age) VALUES (?, ?)', 'sue', 33, type_hints: [nil, :int])
+      #
+      # @example Specifying the consistency as a symbol
+      #   client.execute("UPDATE users SET full_name = 'Sue S. Smith' WHERE user_name = 'sue'", consistency: :one)
+      #
+      # @example Specifying the consistency and other options
+      #   client.execute("SELECT * FROM users", consistency: :all, timeout: 1.5)
+      #
+      # @example Activating tracing for a query
+      #   result = client.execute("SELECT * FROM users", tracing: true)
+      #   p result.trace_id
+      #
+      # @param [String] cql
+      # @param [Array] values Values to bind to any binding markers in the
+      #   query (i.e. "?" placeholders) -- using this feature is similar to
+      #   using a prepared statement, but without the type checking. The client
+      #   needs to guess which data types to encode the values as, and will err
+      #   on the side of caution, using types like BIGINT instead of INT for
+      #   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
+      #   consistency to use for this query.
+      # @option options_or_consistency [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
+      #   for a response. If this timeout expires a {Cql::TimeoutError} will
+      #   be raised.
+      # @option options_or_consistency [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
+      #   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
+      #   same number of arguments as the number of bound values, and each
+      #   element should be the type of the corresponding value, or nil if you
+      #   prefer the encoder to guess. The types should be provided as lower
+      #   case symbols, e.g. `:int`, `:time_uuid`, etc.
+      # @raise [Cql::NotConnectedError] raised when the client is not connected
+      # @raise [Cql::TimeoutError] raised when a timeout was specified and no
+      #   response was received within the timeout.
+      # @raise [Cql::QueryError] raised when the CQL has syntax errors or for
+      #   other situations when the server complains.
+      # @return [nil, Cql::Client::QueryResult, Cql::Client::VoidResult] Some
+      #   queries have no result and return `nil`, but `SELECT` statements
+      #   return an `Enumerable` of rows (see {Cql::Client::QueryResult}), and
+      #   `INSERT` and `UPDATE` return a similar type
+      #   (see {Cql::Client::VoidResult}).
+
+      # @!method prepare(cql)
+      #
+      # Returns a prepared statement that can be run over and over again with
+      # different values.
+      #
+      # @see Cql::Client::PreparedStatement
+      # @param [String] cql The CQL to prepare
+      # @raise [Cql::NotConnectedError] raised when the client is not connected
+      # @raise [Cql::Io::IoError] raised when there is an IO error, for example
+      #   if the server suddenly closes the connection
+      # @raise [Cql::QueryError] raised when there is an error on the server
+      #   side, for example when you specify a malformed CQL query
+      # @return [Cql::Client::PreparedStatement] an object encapsulating the
+      #   prepared statement
+
+      # @!method batch(type=:logged, options={})
+      #
+      # 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::Batch#execute} is called.
+      #
+      # 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 queries in a batch
+      #   client.batch do |batch|
+      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (1234, NOW(), 23423)))
+      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (2346, NOW(), 13)))
+      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (2342, NOW(), 2367)))
+      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (4562, NOW(), 1231)))
+      #   end
+      #
+      # @example Using the returned batch object
+      #   batch = client.batch(:counter, trace: true)
+      #   batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 4, 87654)
+      #   batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 3, 6572)
+      #   result = batch.execute(timeout: 10)
+      #   puts result.trace_id
+      #
+      # @example Providing type hints for on-the-fly bound values
+      #   batch = client.batch
+      #   batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 4, type_hints: [:int])
+      #   batch.execute
+      #
+      # @see Cql::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::Batch] 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}).
+    end
+
     # @private
     class AsynchronousClient < Client
       def initialize(options={})
@@ -9,7 +191,7 @@ module Cql
         @cql_version = options[:cql_version]
         @logger = options[:logger] || NullLogger.new
         @protocol_version = options[:protocol_version] || 2
-        @io_reactor = options[:io_reactor] || Io::IoReactor.new(protocol_handler_factory)
+        @io_reactor = options[:io_reactor] || Io::IoReactor.new
         @hosts = extract_hosts(options)
         @initial_keyspace = options[:keyspace]
         @connections_per_node = options[:connections_per_node] || 1
@@ -131,10 +313,6 @@ module Cql
       DEFAULT_CONNECTION_TIMEOUT = 10
       MAX_RECONNECTION_ATTEMPTS = 5
 
-      def protocol_handler_factory
-        lambda { |connection, timeout| Protocol::CqlProtocolHandler.new(connection, timeout, @protocol_version, @compressor) }
-      end
-
       def extract_hosts(options)
         if options[:hosts]
           options[:hosts].uniq
@@ -148,9 +326,10 @@ module Cql
       def create_cluster_connector
         cql_version = @cql_version || DEFAULT_CQL_VERSIONS[@protocol_version]
         authentication_step = @protocol_version == 1 ? CredentialsAuthenticationStep.new(@credentials) : SaslAuthenticationStep.new(@auth_provider)
+        protocol_handler_factory = lambda { |connection| Protocol::CqlProtocolHandler.new(connection, @io_reactor, @protocol_version, @compressor) }
         ClusterConnector.new(
           Connector.new([
-            ConnectStep.new(@io_reactor, @port, @connection_timeout, @logger),
+            ConnectStep.new(@io_reactor, protocol_handler_factory, @port, @connection_timeout, @logger),
             CacheOptionsStep.new,
             InitializeStep.new(cql_version, @compressor, @logger),
             authentication_step,
@@ -308,5 +487,61 @@ module Cql
         end
       end
     end
+
+    # @private
+    class SynchronousClient < Client
+      include SynchronousBacktrace
+
+      def initialize(async_client)
+        @async_client = async_client
+      end
+
+      def connect
+        synchronous_backtrace { @async_client.connect.value }
+        self
+      end
+
+      def close
+        synchronous_backtrace { @async_client.close.value }
+        self
+      end
+
+      def connected?
+        @async_client.connected?
+      end
+
+      def keyspace
+        @async_client.keyspace
+      end
+
+      def use(keyspace)
+        synchronous_backtrace { @async_client.use(keyspace).value }
+      end
+
+      def execute(cql, *args)
+        synchronous_backtrace do
+          result = @async_client.execute(cql, *args).value
+          result = SynchronousPagedQueryResult.new(result) if result.is_a?(PagedQueryResult)
+          result
+        end
+      end
+
+      def prepare(cql)
+        async_statement = synchronous_backtrace { @async_client.prepare(cql).value }
+        SynchronousPreparedStatement.new(async_statement)
+      end
+
+      def batch(type=:logged, options={}, &block)
+        if block_given?
+          synchronous_backtrace { @async_client.batch(type, options, &block).value }
+        else
+          SynchronousBatch.new(@async_client.batch(type, options))
+        end
+      end
+
+      def async
+        @async_client
+      end
+    end
   end
 end

data/lib/cql/client/connector.rb

@@ -72,8 +72,9 @@ module Cql
 
     # @private
     class ConnectStep
-      def initialize(io_reactor, port, connection_timeout, logger)
+      def initialize(io_reactor, protocol_handler_factory, port, connection_timeout, logger)
         @io_reactor = io_reactor
+        @protocol_handler_factory = protocol_handler_factory
         @port = port
         @connection_timeout = connection_timeout
         @logger = logger
@@ -81,7 +82,7 @@ module Cql
 
       def run(pending_connection)
         @logger.debug('Connecting to node at %s:%d' % [pending_connection.host, @port])
-        @io_reactor.connect(pending_connection.host, @port, @connection_timeout).map do |connection|
+        @io_reactor.connect(pending_connection.host, @port, @connection_timeout, &@protocol_handler_factory).map do |connection|
           pending_connection.with_connection(connection)
         end
       end

data/lib/cql/client/{asynchronous_prepared_statement.rb → prepared_statement.rb}

@@ -2,6 +2,51 @@
 
 module Cql
   module Client
+    class PreparedStatement
+      # Metadata describing the bound values
+      #
+      # @return [ResultMetadata]
+      attr_reader :metadata
+
+      # Metadata about the result (i.e. rows) that is returned when executing
+      # this prepared statement.
+      #
+      # @return [ResultMetadata]
+      attr_reader :result_metadata
+
+      # Execute the prepared statement with a list of values to be bound to the
+      # statements parameters.
+      #
+      # The number of arguments must equal the number of bound parameters. You
+      # can also specify options as the last argument, or a symbol as a shortcut
+      # for just specifying the consistency.
+      #
+      # Because you can specify options, or not, there is an edge case where if
+      # the last parameter of your prepared statement is a map, and you forget
+      # to specify a value for your map, the options will end up being sent to
+      # Cassandra. Most other cases when you specify the wrong number of
+      # 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.
+      # @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
+      # @raise [Cql::Io::IoError] raised when there is an IO error, for example
+      #   if the server suddenly closes the connection
+      # @raise [Cql::QueryError] raised when there is an error on the server side
+      # @return [nil, Cql::Client::QueryResult, Cql::Client::VoidResult] Some
+      #   queries have no result and return `nil`, but `SELECT` statements
+      #   return an `Enumerable` of rows (see {Cql::Client::QueryResult}), and
+      #   `INSERT` and `UPDATE` return a similar type
+      #   (see {Cql::Client::VoidResult}).
+      def execute(*args)
+      end
+    end
+
     # @private
     class AsynchronousPreparedStatement < PreparedStatement
       # @private
@@ -102,5 +147,63 @@ module Cql
         f
       end
     end
+
+    # @private
+    class SynchronousPreparedStatement < PreparedStatement
+      include SynchronousBacktrace
+
+      def initialize(async_statement)
+        @async_statement = async_statement
+        @metadata = async_statement.metadata
+        @result_metadata = async_statement.result_metadata
+      end
+
+      def execute(*args)
+        synchronous_backtrace do
+          result = @async_statement.execute(*args).value
+          result = SynchronousPagedQueryResult.new(result) if result.is_a?(PagedQueryResult)
+          result
+        end
+      end
+
+      def batch(type=:logged, options=nil, &block)
+        if block_given?
+          synchronous_backtrace { @async_statement.batch(type, options, &block).value }
+        else
+          SynchronousPreparedStatementBatch.new(@async_statement.batch(type, options))
+        end
+      end
+
+      def pipeline
+        pl = Pipeline.new(@async_statement)
+        yield pl
+        synchronous_backtrace { pl.value }
+      end
+
+      def async
+        @async_statement
+      end
+
+      # @private
+      def add_to_batch(batch, connection, bound_arguments)
+        @async_statement.add_to_batch(batch, connection, bound_arguments)
+      end
+    end
+
+    # @private
+    class Pipeline
+      def initialize(async_statement)
+        @async_statement = async_statement
+        @futures = []
+      end
+
+      def execute(*args)
+        @futures << @async_statement.execute(*args)
+      end
+
+      def value
+        Future.all(*@futures).value
+      end
+    end
   end
 end