cql-rb 1.0.0.pre0 → 1.0.0.pre1

data/README.md

@@ -1,10 +1,146 @@
-# Ruby CQL 3 driver
+# Ruby CQL3 driver
 
-This is a work in progress, no usable version exists yet.
+_There has not yet been a stable release of this project._
+
+
+# Requirements
+
+Cassandra 1.2 with the native transport protocol turned on and a modern Ruby. Tested with Ruby 1.9.3 and JRuby and 1.7.x.
+
+# Installation
+
+    gem install --prerelease cql-rb
+
+## Configure Cassandra
+
+The native transport protocol (sometimes called binary protocol, or CQL protocol) is not on by default in Cassandra 1.2, to enable it edit the `cassandra.yaml` file on all nodes in your cluster and set `start_native_transport` to `true`. You need to restart the nodes for this to have effect.
+
+# Quick start
+
+    require 'cql'
+
+    client = Cql::Client.new(host: 'cassandra.example.com')
+    client.start!
+    client.use('system')
+    rows = client.execute('SELECT keyspace_name, columnfamily_name FROM schema_columnfamilies')
+    rows.each do |row|
+      puts "The keyspace #{row['keyspace_name']} has a table called #{row['columnfamily_name']}""
+    end
+
+when you're done you can call `#shutdown!` to disconnect from Cassandra. You can connect to multiple Cassandra nodes by passing multiple comma separated host names to the `:host` option.
+
+## Changing keyspaces
+
+    client.use('measurements')
+
+or using CQL:
+
+    client.execute('USE measurements')
+
+## Running queries
+
+You run CQL statements by passing them to `#execute`. Most statements don't have any result and the call will return nil.
+
+    client.execute("INSERT INTO events (id, date, description) VALUES (23462, '2013-02-24T10:14:23+0000', 'Rang bell, ate food')")
+
+    client.execute("UPDATE events SET description = 'Oh, my' WHERE id = 13126")
+
+
+If the CQL statement passed to `#execute` returns a result (e.g. it's a `SELECT` statement) the call returns an enumerable of rows:
+
+    rows = client.execute('SELECT date, description FROM events')
+    rows.each do |row|
+      row.each do |key, value|
+        puts "#{key} = #{value}"
+      end
+    end
+
+The enumerable also has an accessor called `metadata` which returns a description of the rows and columns:
+
+    rows = client.execute('SELECT date, description FROM events'
+    rows.metadata['date'].type # => :date
+
+## Creating keyspaces and tables
+
+There is no special facility for creating keyspaces and tables, they are created by executing CQL:
+
+    keyspace_definition = <<-KSDEF
+      CREATE KEYSPACE measurements
+      WITH replication = {
+        'class': 'SimpleStrategy',
+        'replication_factor': 3
+      }
+    KSDEF
+
+    table_definition = <<- TABLEDEF
+      CREATE TABLE events (
+        id INT,
+        date DATE,
+        comment VARCHAR,
+        PRIMARY KEY (id)
+      )
+    TABLEDEF
+
+    client.execute(keyspace_definition)
+    client.use(measurements)
+    client.execute(table_definition)
+
+You can also `ALTER` keyspaces and tables.
+
+## Prepared statements
+
+The driver supports prepared statements. Use `#prepare` to create a statement object, and then call `#execute` on that object to run a statement. You must supply values for all bound parameters when you call `#execute`.
+
+    statement = client.prepare('SELECT date, description FROM events WHERE id = ?')
+    rows = statement.execute(1235)
+
+A prepared statement can be run many times, but the CQL parsing will only be done once. Use prepared statements for queries you run over and over again.
+
+`INSERT`, `UPDATE`, `DELETE` and `SELECT` statements can be prepared, other statements may raise `QueryError`.
+
+At this time prepared statements are local to a single connection. Even if you connect to multiple nodes a prepared statement is only ever going to be executed against one of the nodes.
+
+# Consistency levels
+
+The `#execute` method supports setting the desired consistency level for the statement:
+
+    client.execute('SELECT * FROM peers', :local_quorum)
+
+The possible values are: 
+
+* `:any`
+* `:one`
+* `:two`
+* `:three`
+* `:quorum`
+* `:all`
+* `:local_quorum`
+* `:each_quorum`
+
+The default consistency level is `:quorum`.
+
+Consistency level is ignored for `USE`, `TRUNCATE`, `CREATE` and `ALTER` statements, and some (like `:any`) aren't allowed in all situations.
+
+## CQL3
+
+This is just a driver for the Cassandra native CQL protocol, it doesn't really know anything about CQL. You can run any CQL3 statement and the driver will return whatever Cassandra replies with.
+
+Read more about CQL3 in the [CQL3 syntax documentation](https://github.com/apache/cassandra/blob/cassandra-1.2/doc/cql3/CQL.textile) and the [Cassandra query documentation](http://www.datastax.com/docs/1.2/cql_cli/querying_cql).
+
+# Known bugs & limitations
+
+* If any connection raises an error the whole IO reactor shuts down.
+* JRuby 1.6.8 is not supported, although it should be. The only known issue is that connection failures aren't handled gracefully.
+* No automatic peer discovery.
+* You can't specify consistency level when executing prepared statements.
+* Authentication is not supported.
+* Compression is not supported.
+* Large results are buffered in memory until the whole response has been loaded, the protocol makes it possible to start to deliver rows to the client code as soon as the metadata is loaded, but this is not supported yet.
+* There is no cluster introspection utilities (like the `DESCRIBE` commands in `cqlsh`).
 
 ## Copyright
 
-Copyright 2013 Theo Hultberg
+Copyright 2013 Theo Hultberg/Iconara
 
 _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_
 

data/lib/cql/client.rb

@@ -1,9 +1,6 @@
 # encoding: utf-8
 
 module Cql
-  NotConnectedError = Class.new(CqlError)
-  InvalidKeyspaceNameError = Class.new(CqlError)
-
   class QueryError < CqlError
     attr_reader :code
 
@@ -13,7 +10,54 @@ module Cql
     end
   end
 
+  ClientError = Class.new(CqlError)
+
+  # A CQL client manages connections to one or more Cassandra nodes and you use
+  # it run queries, insert and update data.
+  #
+  # @example Connecting and changing to a keyspace
+  #   # create a client that will connect to two Cassandra nodes
+  #   client = Cql::Client.new(host: 'node01.cassandra.local,node02.cassandra.local')
+  #   # establish node connections
+  #   client.start!
+  #   # change to a keyspace
+  #   client.use('stuff')
+  #
+  # @example Query for data
+  #   rows = client.execute('SELECT * FROM things WHERE id = 2')
+  #   rows.each do |row|
+  #     p row
+  #   end
+  #
+  # @example Inserting and updating data
+  #   client.execute("INSERT INTO things (id, value) VALUES (4, 'foo')")
+  #   client.execute("UPDATE things SET value = 'bar' WHERE id = 5")
+  #
+  # @example Prepared statements
+  #   statement = client.prepare('INSERT INTO things (id, value) VALUES (?, ?)')
+  #   statement.execute(9, 'qux')
+  #   statement.execute(8, 'baz')
+  #
+  # Client instances are threadsafe.
+  #
   class Client
+    NotConnectedError = Class.new(ClientError)
+    InvalidKeyspaceNameError = Class.new(ClientError)
+
+    # Create a new client.
+    #
+    # Creating a client does not automatically connect to Cassandra, you need to
+    # call {#start!} to connect. `#start!` returns `self` so you can chain that
+    # call after `new`.
+    #
+    # @param [Hash] options
+    # @option options [String] :host ('localhost') One or more (comma separated)
+    #   hostnames for the Cassandra nodes you want to connect to.
+    # @option options [String] :port (9042) The port to connect to
+    # @option options [Integer] :connection_timeout (5) Max time to wait for a
+    #   connection, in seconds
+    # @option options [String] :keyspace The keyspace to change to immediately
+    #   after all connections have been established, this is optional.
     def initialize(options={})
       connection_timeout = options[:connection_timeout]
       @host = options[:host] || 'localhost'
@@ -26,24 +70,44 @@ module Cql
       @connection_keyspaces = {}
     end
 
+    # Connect to all nodes.
+    #
+    # You must call this method before you call any of the other methods of a
+    # client. Calling it again will have no effect.
+    #
+    # If `:keyspace` was specified when the client was created the current
+    # keyspace will also be changed (otherwise the current keyspace will not
+    # be set).
+    #
+    # @return self
+    #
     def start!
       @lock.synchronize do
         return if @started
         @started = true
       end
-      @io_reactor.start
-      hosts = @host.split(',')
-      start_request = Protocol::StartupRequest.new
-      connection_futures = hosts.map do |host|
-        @io_reactor.add_connection(host, @port).flat_map do |connection_id|
-          execute_request(start_request, connection_id).map { connection_id }
+      begin
+        @io_reactor.start
+        hosts = @host.split(',')
+        start_request = Protocol::StartupRequest.new
+        connection_futures = hosts.map do |host|
+          @io_reactor.add_connection(host, @port).flat_map do |connection_id|
+            execute_request(start_request, connection_id).map { connection_id }
+          end
         end
+        @connection_ids = Future.combine(*connection_futures).get
+        use(@initial_keyspace) if @initial_keyspace
+      rescue
+        @started = false
+        raise
       end
-      @connection_ids = Future.combine(*connection_futures).get
-      use(@initial_keyspace) if @initial_keyspace
       self
     end
 
+    # Disconnect from all nodes.
+    #
+    # @return self
+    #
     def shutdown!
       @lock.synchronize do
         return if @shut_down
@@ -54,12 +118,27 @@ module Cql
       self
     end
 
+    # Returns whether or not the client is connected.
+    #
+    def connected?
+      @started
+    end
+
+    # Returns the name of the current keyspace, or `nil` if no keyspace has been
+    # set yet.
+    #
     def keyspace
       @lock.synchronize do
         return @connection_ids.map { |id| @connection_keyspaces[id] }.first
       end
     end
 
+    # Changes keyspace by sending a `USE` statement to all connections.
+    #
+    # The the second parameter is meant for internal use only.
+    #
+    # @raise [Cql::NotConnectedError] raised when the client is not connected
+    #
     def use(keyspace, connection_ids=@connection_ids)
       raise NotConnectedError unless @started
       if check_keyspace_name!(keyspace)
@@ -77,16 +156,32 @@ module Cql
       end
     end
 
+    # Execute a CQL statement
+    #
+    # @raise [Cql::NotConnectedError] raised when the client is not connected
+    # @raise [Cql::QueryError] raised when the CQL has syntax errors or for
+    #   other situations when the server complains.
+    # @return [nil, Enumerable<Hash>] Most statements have no result and return
+    #   `nil`, but `SELECT` statements return an `Enumerable` of rows
+    #   (see {QueryResult}).
+    #
     def execute(cql, consistency=:quorum)
       result = execute_request(Protocol::QueryRequest.new(cql, consistency)).value
       ensure_keyspace!
       result
     end
 
+    # @private
     def execute_statement(connection_id, statement_id, metadata, values, consistency)
       execute_request(Protocol::ExecuteRequest.new(statement_id, metadata, values, consistency), connection_id).value
     end
 
+    # Returns a prepared statement that can be run over and over again with
+    # different values.
+    #
+    # @raise [Cql::NotConnectedError] raised when the client is not connected
+    # @return [Cql::PreparedStatement] an object encapsulating the prepared statement
+    #
     def prepare(cql)
       execute_request(Protocol::PrepareRequest.new(cql)).value
     end
@@ -136,58 +231,92 @@ module Cql
       use(ks, @connection_ids) if ks
     end
 
+    public
+
+    #
     class PreparedStatement
+      # @return [ResultMetadata]
+      attr_reader :metadata
+
       def initialize(*args)
-        @client, @connection_id, @statement_id, @metadata = args
+        @client, @connection_id, @statement_id, @raw_metadata = args
+        @metadata = ResultMetadata.new(@raw_metadata)
       end
 
+      # Execute the prepared statement with a list of values for the bound parameters.
+      #
       def execute(*args)
-        @client.execute_statement(@connection_id, @statement_id, @metadata, args, :quorum)
+        @client.execute_statement(@connection_id, @statement_id, @raw_metadata, args, :quorum)
       end
     end
 
     class QueryResult
       include Enumerable
 
+      # @return [ResultMetadata]
       attr_reader :metadata
 
+      # @private
       def initialize(metadata, rows)
         @metadata = ResultMetadata.new(metadata)
         @rows = rows
       end
 
+      # Returns whether or not there are any rows in this result set
+      #
       def empty?
         @rows.empty?
       end
 
+      # Iterates over each row in the result set.
+      #
+      # @yieldparam [Hash] row each row in the result set as a hash
+      # @return [Enumerable<Hash>]
+      #
       def each(&block)
         @rows.each(&block)
       end
+      alias_method :each_row, :each
     end
 
     class ResultMetadata
       include Enumerable
 
+      # @private
       def initialize(metadata)
-        @metadata = Hash[metadata.map { |m| mm = ColumnMetadata.new(*m); [mm.column_name, mm] }]
+        @metadata = metadata.each_with_object({}) { |m, h| h[m[2]] = ColumnMetadata.new(*m) }
       end
 
+      # Returns the column metadata
+      #
+      # @return [ColumnMetadata] column_metadata the metadata for the column
+      #
       def [](column_name)
         @metadata[column_name]
       end
 
+      # Iterates over the metadata for each column
+      #
+      # @yieldparam [ColumnMetadata] metadata the metadata for each column
+      # @return [Enumerable<ColumnMetadata>]
+      #
       def each(&block)
         @metadata.each_value(&block)
       end
     end
 
+    # Represents metadata about a column in a query result set or prepared
+    # statement. Apart from the keyspace, table and column names there's also
+    # the type as a symbol (e.g. `:varchar`, `:int`, `:date`).
     class ColumnMetadata
-      attr_reader :keyspace, :table, :table, :column_name, :type
+      attr_reader :keyspace, :table, :column_name, :type
       
+      # @private
       def initialize(*args)
         @keyspace, @table, @column_name, @type = args
       end
 
+      # @private
       def to_ary
         [@keyspace, @table, @column_name, @type]
       end

data/lib/cql/future.rb

@@ -3,6 +3,8 @@
 module Cql
   FutureError = Class.new(CqlError)
 
+  # A future represents the value of a process that may not yet have completed.
+  #
   class Future
     def initialize
       @complete_listeners = []
@@ -11,18 +13,43 @@ module Cql
       @state_lock = Mutex.new
     end
 
+    # Combine multiple futures into a new future which completes when all
+    # constituent futures complete, or fail when one or more of them fails.
+    #
+    # The value of the combined future is an array of the values of the
+    # constituent futures.
+    #
+    # @param [Array<Future>] futures the futures to combine
+    # @return [Future<Array>] an array of the values of the constituent futures
+    #
     def self.combine(*futures)
       CombinedFuture.new(*futures)
     end
 
+    # Creates a new future which is completed.
+    #
+    # @param [Object, nil] value the value of the created future
+    # @return [Future] a completed future
+    #
     def self.completed(value=nil)
       CompletedFuture.new(value)
     end
 
+    # Creates a new future which is failed.
+    #
+    # @param [Error] the error of the created future
+    # @return [Future] a failed future
+    #
     def self.failed(error)
       FailedFuture.new(error)
     end
 
+    # Completes the future.
+    #
+    # This will trigger all completion listeners in the calling thread.
+    #
+    # @param [Object] v the value of the future
+    #
     def complete!(v=nil)
       @state_lock.synchronize do
         raise FutureError, 'Future already completed' if complete? || failed?
@@ -37,10 +64,16 @@ module Cql
       end
     end
 
+    # Returns whether or not the future is complete
+    #
     def complete?
       defined? @value
     end
 
+    # Registers a listener for when this future completes
+    #
+    # @yieldparam [Object] value the value of the completed future
+    #
     def on_complete(&listener)
       @state_lock.synchronize do
         if complete?
@@ -51,6 +84,12 @@ module Cql
       end
     end
 
+    # Returns the value of this future, blocking until it is available, if necessary.
+    #
+    # If the future fails this method will raise the error that failed the future.
+    #
+    # @returns [Object] the value of this future
+    #
     def value
       raise @error if @error
       return @value if defined? @value
@@ -60,6 +99,12 @@ module Cql
     end
     alias_method :get, :value
 
+    # Fails the future.
+    #
+    # This will trigger all failure listeners in the calling thread.
+    #
+    # @param [Error] error the error which prevented the value from being determined
+    #
     def fail!(error)
       @state_lock.synchronize do
         raise FutureError, 'Future already completed' if failed? || complete?
@@ -74,10 +119,16 @@ module Cql
       end
     end
 
+    # Returns whether or not the future is failed.
+    #
     def failed?
       !!@error
     end
 
+    # Registers a listener for when this future fails
+    #
+    # @yieldparam [Error] error the error that failed the future
+    #
     def on_failure(&listener)
       @state_lock.synchronize do
         if failed?
@@ -88,6 +139,15 @@ module Cql
       end
     end
 
+    # Returns a new future representing a transformation of this future's value.
+    #
+    # @example
+    #   future2 = future1.map { |value| value * 2 }
+    #
+    # @yieldparam [Object] value the value of this future
+    # @yieldreturn [Object] the transformed value
+    # @return [Future] a new future representing the transformed value
+    #
     def map(&block)
       fp = Future.new
       on_failure { |e| fp.fail!(e) }
@@ -102,6 +162,18 @@ module Cql
       fp
     end
 
+    # Returns a new future representing a transformation of this future's value,
+    # but where the transformation itself may be asynchronous.
+    #
+    # @example
+    #   future2 = future1.flat_map { |value| method_returning_a_future(value) }
+    #
+    # This method is useful when you want to chain asynchronous operations.
+    #
+    # @yieldparam [Object] value the value of this future
+    # @yieldreturn [Future] a future representing the transformed value
+    # @return [Future] a new future representing the transformed value
+    #
     def flat_map(&block)
       fp = Future.new
       on_failure { |e| fp.fail!(e) }
@@ -120,6 +192,7 @@ module Cql
     end
   end
 
+  # @private
   class CompletedFuture < Future
     def initialize(value=nil)
       super()
@@ -127,6 +200,7 @@ module Cql
     end
   end
 
+  # @private
   class FailedFuture < Future
     def initialize(error)
       super()
@@ -134,6 +208,7 @@ module Cql
     end
   end
 
+  # @private
   class CombinedFuture < Future
     def initialize(*futures)
       super()

data/lib/cql/io.rb

@@ -1,8 +1,9 @@
 # encoding: utf-8
 
 module Cql
+  IoError = Class.new(CqlError)
+
   module Io
-    IoError = Class.new(CqlError)
     ConnectionError = Class.new(IoError)
     NotRunningError = Class.new(CqlError)
     ConnectionNotFoundError = Class.new(CqlError)

data/lib/cql/io/io_reactor.rb

@@ -6,7 +6,17 @@ require 'resolv-replace'
 
 module Cql
   module Io
+    # An instance of IO reactor manages the connections used by a client.
+    #
+    # The reactor starts a thread in which all IO is performed. The IO reactor
+    # instances are thread safe.
+    #
     class IoReactor
+      #
+      # @param [Hash] options
+      # @option options [Integer] :connection_timeout (5) Max time to wait for a
+      #   connection, in seconds
+      #
       def initialize(options={})
         @connection_timeout = options[:connection_timeout] || 5
         @lock = Mutex.new
@@ -18,10 +28,19 @@ module Cql
         @running = false
       end
 
+      # Returns whether or not the reactor is running
+      #
       def running?
         @running
       end
 
+      # Starts the reactor.
+      #
+      # Calling this method when the reactor is connecting or is connected has
+      # no effect.
+      #
+      # @return [Future<nil>] a future which completes when the reactor has started
+      #
       def start
         @lock.synchronize do
           unless @running
@@ -42,11 +61,25 @@ module Cql
         @started_future
       end
 
+      # Stops the reactor.
+      #
+      # Calling this method when the reactor is stopping or has stopped has
+      # no effect.
+      #
+      # @return [Future<nil>] a future which completes when the reactor has stopped
+      #
       def stop
         @running = false
         @stopped_future
       end
 
+      # Establish a new connection.
+      #
+      # @param [String] host The hostname to connect to
+      # @param [Integer] port The port to connect to
+      # @return [Future<Object>] a future representing the ID of the newly
+      #   established connection, or connection error if the connection fails.
+      #
       def add_connection(host, port)
         connection = NodeConnection.new(host, port, @connection_timeout)
         future = connection.open
@@ -65,12 +98,23 @@ module Cql
         future
       end
 
+      # Sends a request over a random, or specific connection.
+      #
+      # @param [Cql::Protocol::RequestBody] request the request to send
+      # @param [Object] connection_id the ID of the connection which should be
+      #   used to send the request
+      # @return [Future<ResultResponse>] a future representing the result of the request
+      #
       def queue_request(request, connection_id=nil)
         future = Future.new
         command_queue_push(:request, request, future, connection_id)
         future
       end
 
+      # Registers a listener to receive server sent events.
+      #
+      # @yieldparam [Cql::Protocol::EventResponse] event the event sent by the server
+      #
       def add_event_listener(&listener)
         command_queue_push(:event_listener, listener)
       end
@@ -108,6 +152,7 @@ module Cql
       end
     end
 
+    # @private
     class NodeConnection
       def initialize(*args)
         @host, @port, @connection_timeout = args
@@ -171,6 +216,9 @@ module Cql
         stream_id = next_stream_id
         Protocol::RequestFrame.new(request, stream_id).write(@write_buffer)
         @response_tasks[stream_id] = future
+      rescue => e
+        @response_tasks.delete(stream_id)
+        future.fail!(e)
       end
 
       def handle_read
@@ -201,7 +249,12 @@ module Cql
 
       def close
         if @io
-          @io.close
+          begin
+            @io.close
+          rescue SystemCallError
+            # nothing to do, it wasn't open
+          end
+          @io = nil
           if connecting?
             succeed_connection!
           end
@@ -223,7 +276,7 @@ module Cql
       EVENT_STREAM_ID = -1
 
       def connecting?
-        !@connected_future.complete?
+        !(@connected_future.complete? || @connected_future.failed?)
       end
 
       def handle_connected
@@ -246,8 +299,7 @@ module Cql
         error = ConnectionError.new(message)
         error.set_backtrace(e.backtrace) if e
         @connected_future.fail!(error)
-        @io.close if @io
-        @io = nil
+        close
       end
 
       def next_stream_id
@@ -258,6 +310,7 @@ module Cql
       end
     end
 
+    # @private
     class CommandDispatcher
       def initialize(*args)
         @io, @command_queue, @queue_lock, @node_connections = args

data/lib/cql/protocol.rb

@@ -1,8 +1,10 @@
 # encoding: utf-8
 
 module Cql
+  ProtocolError = Class.new(CqlError)
+
+  # @private
   module Protocol
-    ProtocolError = Class.new(CqlError)
     DecodingError = Class.new(ProtocolError)
     EncodingError = Class.new(ProtocolError)
     InvalidStreamIdError = Class.new(ProtocolError)

data/lib/cql/uuid.rb

@@ -1,7 +1,18 @@
 # encoding: utf-8
 
 module Cql
+  # Represents a UUID value.
+  #
+  # This is a very basic implementation of UUIDs and exists more or less just
+  # to encode and decode UUIDs from and to Cassandra.
+  #
   class Uuid
+    # Creates a new UUID either from a string (expected to be on the standard
+    # 8-4-4-4-12 form, or just 32 characters without hyphens), or from a
+    # 128 bit number.
+    #
+    # @raise [ArgumentError] if the string does not conform to the expected format
+    #
     def initialize(n)
       case n
       when String
@@ -11,6 +22,8 @@ module Cql
       end
     end
 
+    # Returns a string representation of this UUID in the standard 8-4-4-4-12 form.
+    #
     def to_s
       @s ||= begin
         parts = []
@@ -23,10 +36,15 @@ module Cql
       end
     end
 
+    # Returns the numerical representation of this UUID
+    #
+    # @return [Bignum] the 128 bit numerical representation
+    #
     def value
       @n
     end
 
+    # @private
     def eql?(other)
       self.value == other.value
     end
@@ -34,8 +52,12 @@ module Cql
 
     private
 
+    HEX_STRING_PATTERN = /^[0-9a-fA-F]+$/
+
     def from_s(str)
       str = str.gsub('-', '')
+      raise ArgumentError, "Expected 32 chars but got #{str.length}" unless str.length == 32
+      raise ArgumentError, "Expected only characters 0-9, a-f, A-F" unless str =~ HEX_STRING_PATTERN
       n = 0
       (str.length/2).times do |i|
         n = (n << 8) | str[i * 2, 2].to_i(16)

data/lib/cql/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Cql
-  VERSION = '1.0.0.pre0'.freeze
+  VERSION = '1.0.0.pre1'.freeze
 end

data/spec/cql/client_spec.rb

@@ -95,9 +95,25 @@ module Cql
 
       it 'validates the keyspace name before sending the USE command' do
         c = described_class.new(connection_options.merge(:keyspace => 'system; DROP KEYSPACE system'))
-        expect { c.start! }.to raise_error(InvalidKeyspaceNameError)
+        expect { c.start! }.to raise_error(Client::InvalidKeyspaceNameError)
         requests.should_not include(Protocol::QueryRequest.new('USE system; DROP KEYSPACE system', :one))
       end
+
+      it 're-raises any errors raised' do
+        io_reactor.stub(:add_connection).and_raise(ArgumentError)
+        expect { client.start! }.to raise_error(ArgumentError)
+      end
+
+      it 'is not connected if an error is raised' do
+        io_reactor.stub(:add_connection).and_raise(ArgumentError)
+        client.start! rescue nil
+        client.should_not be_connected
+      end
+
+      it 'is connected after #start! returns' do
+        client.start!
+        client.should be_connected
+      end
     end
 
     describe '#shutdown!' do
@@ -153,7 +169,7 @@ module Cql
       end
 
       it 'raises an error if the keyspace name is not valid' do
-        expect { client.use('system; DROP KEYSPACE system') }.to raise_error(InvalidKeyspaceNameError)
+        expect { client.use('system; DROP KEYSPACE system') }.to raise_error(Client::InvalidKeyspaceNameError)
       end
     end
 
@@ -294,6 +310,14 @@ module Cql
         last_request.should == Protocol::ExecuteRequest.new(id, metadata, ['foo'], :quorum)
       end
 
+      it 'returns a prepared statement that knows the metadata' do
+        id = 'A' * 32
+        metadata = [['stuff', 'things', 'item', :varchar]]
+        io_reactor.queue_response(Protocol::PreparedResultResponse.new(id, metadata))
+        statement = client.prepare('SELECT * FROM stuff.things WHERE item = ?')
+        statement.metadata['item'].type == :varchar
+      end
+
       it 'executes a prepared statement using the right connection' do
         client.shutdown!
         io_reactor.stop.get
@@ -326,34 +350,44 @@ module Cql
     end
 
     context 'when not connected' do
+      it 'is not connected before #start! has been called' do
+        client.should_not be_connected
+      end
+
+      it 'is not connected after #shutdown! has been called' do
+        client.start!
+        client.shutdown!
+        client.should_not be_connected
+      end
+
       it 'complains when #use is called before #start!' do
-        expect { client.use('system') }.to raise_error(NotConnectedError)
+        expect { client.use('system') }.to raise_error(Client::NotConnectedError)
       end
 
       it 'complains when #use is called after #shutdown!' do
         client.start!
         client.shutdown!
-        expect { client.use('system') }.to raise_error(NotConnectedError)
+        expect { client.use('system') }.to raise_error(Client::NotConnectedError)
       end
 
       it 'complains when #execute is called before #start!' do
-        expect { client.execute('DELETE FROM stuff WHERE id = 3') }.to raise_error(NotConnectedError)
+        expect { client.execute('DELETE FROM stuff WHERE id = 3') }.to raise_error(Client::NotConnectedError)
       end
 
       it 'complains when #execute is called after #shutdown!' do
         client.start!
         client.shutdown!
-        expect { client.execute('DELETE FROM stuff WHERE id = 3') }.to raise_error(NotConnectedError)
+        expect { client.execute('DELETE FROM stuff WHERE id = 3') }.to raise_error(Client::NotConnectedError)
       end
 
       it 'complains when #prepare is called before #start!' do
-        expect { client.prepare('DELETE FROM stuff WHERE id = 3') }.to raise_error(NotConnectedError)
+        expect { client.prepare('DELETE FROM stuff WHERE id = 3') }.to raise_error(Client::NotConnectedError)
       end
 
       it 'complains when #prepare is called after #shutdown!' do
         client.start!
         client.shutdown!
-        expect { client.prepare('DELETE FROM stuff WHERE id = 3') }.to raise_error(NotConnectedError)
+        expect { client.prepare('DELETE FROM stuff WHERE id = 3') }.to raise_error(Client::NotConnectedError)
       end
 
       it 'complains when #execute of a prepared statement is called after #shutdown!' do
@@ -361,7 +395,7 @@ module Cql
         io_reactor.queue_response(Protocol::PreparedResultResponse.new('A' * 32, []))
         statement = client.prepare('DELETE FROM stuff WHERE id = 3')
         client.shutdown!
-        expect { statement.execute }.to raise_error(NotConnectedError)
+        expect { statement.execute }.to raise_error(Client::NotConnectedError)
       end
     end
   end

data/spec/cql/io/io_reactor_spec.rb

@@ -27,8 +27,13 @@ module Cql
       end
 
       after do
-        io_reactor.stop.get if io_reactor.running?
-        server.stop!
+        begin
+          if io_reactor.running?
+            io_reactor.stop.get
+          end
+        ensure
+          server.stop!
+        end
       end
 
       describe '#initialize' do
@@ -76,7 +81,9 @@ module Cql
         end
 
         it 'succeeds connection futures when stopping while connecting' do
-          f = io_reactor.add_connection(host, port + 9)
+          server.stop!
+          server.start!(accept_delay: 2)
+          f = io_reactor.add_connection(host, port)
           io_reactor.start
           io_reactor.stop
           f.get
@@ -135,7 +142,7 @@ module Cql
           io_reactor.start
           io_reactor.add_connection(host, port).get
           io_reactor.queue_request(Cql::Protocol::StartupRequest.new)
-          sleep(0.01) until server.received_bytes.size > 0
+          await { server.received_bytes.size > 0 }
           server.received_bytes[3, 1].should == "\x01"
         end
 
@@ -143,7 +150,7 @@ module Cql
           io_reactor.queue_request(Cql::Protocol::StartupRequest.new)
           io_reactor.start
           io_reactor.add_connection(host, port).get
-          sleep(0.01) until server.received_bytes.size > 0
+          await { server.received_bytes.size > 0 }
           server.received_bytes[3, 1].should == "\x01"
         end
 
@@ -226,6 +233,13 @@ module Cql
           pending 'as it is the reactor doesn\'t try to deliver requests when all connections are busy'
         end
 
+        it 'fails if there is an error when encoding the request' do
+          io_reactor.start
+          io_reactor.add_connection(host, port).get
+          f = io_reactor.queue_request(Cql::Protocol::QueryRequest.new('USE test', :foobar))
+          expect { f.get }.to raise_error(Cql::ProtocolError)
+        end
+
         it 'yields the response when completed' do
           response = nil
           io_reactor.start
@@ -234,8 +248,9 @@ module Cql
           f.on_complete do |r, _|
             response = r
           end
+          sleep(0.1)
           server.broadcast!("\x81\x00\x00\x02\x00\x00\x00\x00")
-          sleep(0.01) until response
+          await { response }
           response.should == Cql::Protocol::ReadyResponse.new
         end
 
@@ -247,8 +262,9 @@ module Cql
           f.on_complete do |_, c|
             connection = c
           end
+          sleep(0.1)
           server.broadcast!("\x81\x00\x00\x02\x00\x00\x00\x00")
-          sleep(0.01) until connection
+          await { connection }
           connection.should_not be_nil
         end
       end
@@ -259,32 +275,12 @@ module Cql
           io_reactor.start
           io_reactor.add_connection(host, port).get
           io_reactor.add_event_listener { |e| event = e }
+          sleep(0.1)
           server.broadcast!("\x81\x00\xFF\f\x00\x00\x00+\x00\rSCHEMA_CHANGE\x00\aDROPPED\x00\nkeyspace01\x00\x05users")
-          sleep(0.01) until event
+          await { event }
           event.should == Cql::Protocol::SchemaChangeEventResponse.new('DROPPED', 'keyspace01', 'users')
         end
       end
-
-      context 'when errors occur' do
-        context 'in the IO loop' do
-          before do
-            bad_request = stub(:request)
-            bad_request.stub(:opcode).and_raise(StandardError.new('Blurgh'))
-            io_reactor.start
-            io_reactor.add_connection(host, port).get
-            io_reactor.queue_request(bad_request)
-          end
-
-          it 'stops' do
-            sleep(0.1)
-            io_reactor.should_not be_running
-          end
-
-          it 'fails the future returned from #stop' do
-            expect { io_reactor.stop.get }.to raise_error('Blurgh')
-          end
-        end
-      end
     end
   end
 end

data/spec/cql/uuid_spec.rb

@@ -10,6 +10,22 @@ module Cql
         Uuid.new('a4a70900-24e1-11df-8924-001ff3591711').to_s.should == 'a4a70900-24e1-11df-8924-001ff3591711'
       end
 
+      it 'can be created from a string without hyphens' do
+        Uuid.new('a4a7090024e111df8924001ff3591711').to_s.should == 'a4a70900-24e1-11df-8924-001ff3591711'
+      end
+
+      it 'raises an error if the string is shorter than 32 chars' do
+        expect { Uuid.new('a4a7090024e111df8924001ff359171') }.to raise_error(ArgumentError)
+      end
+
+      it 'raises an error if the string is longer than 32 chars' do
+        expect { Uuid.new('a4a7090024e111df8924001ff35917111') }.to raise_error(ArgumentError)
+      end
+
+      it 'raises an error if the string is not a hexadecimal number' do
+        expect { Uuid.new('a4a7090024e111df8924001ff359171x') }.to raise_error(ArgumentError)
+      end
+
       it 'can be created from a number' do
         Uuid.new(276263553384940695775376958868900023510).to_s.should == 'cfd66ccc-d857-4e90-b1e5-df98a3d40cd6'.force_encoding(::Encoding::ASCII)
       end

data/spec/integration/client_spec.rb

@@ -98,4 +98,14 @@ describe 'A CQL client' do
       end
     end
   end
+
+  context 'with error conditions' do
+    it 'raises an error for CQL syntax errors' do
+      expect { client.execute('BAD cql') }.to raise_error(Cql::CqlError)
+    end
+
+    it 'raises an error for bad consistency levels' do
+      expect { client.execute('SELECT * FROM system.peers', :helloworld) }.to raise_error(Cql::CqlError)
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -7,5 +7,6 @@ require 'cql'
 ENV['CASSANDRA_HOST'] ||= 'localhost'
 
 
+require 'support/await_helper'
 require 'support/fake_server'
 require 'support/fake_io_reactor'

data/spec/support/await_helper.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module AwaitHelper
+  def await(timeout=5, &test)
+    started_at = Time.now
+    until test.call
+      yield
+      time_taken = Time.now - started_at
+      if time_taken > timeout
+        fail('Test took more than %.1fs' % [time_taken.to_f])
+      else
+        sleep(0.01)
+      end
+    end
+  end
+end
+
+RSpec.configure do |c|
+  c.include(AwaitHelper)
+end

data/spec/support/fake_server.rb

@@ -13,7 +13,7 @@ class FakeServer
     @received_bytes = ''
   end
 
-  def start!
+  def start!(options={})
     @lock.synchronize do
       return if @running
       @running = true
@@ -22,6 +22,7 @@ class FakeServer
     @started = Cql::Future.new
     @thread = Thread.start do
       Thread.current.abort_on_exception = true
+      sleep(options[:accept_delay] || 0)
       @started.complete!
       io_loop
     end
@@ -34,8 +35,10 @@ class FakeServer
       return unless @running
       @running = false
     end
-    @thread.join
-    @sockets.each(&:close)
+    if defined? @started
+      @thread.join
+      @sockets.each(&:close)
+    end
   end
 
   def broadcast!(bytes)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cql-rb
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre0
+  version: 1.0.0.pre1
   prerelease: 6
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-20 00:00:00.000000000 Z
+date: 2013-02-24 00:00:00.000000000 Z
 dependencies: []
 description: A pure Ruby CQL3 driver for Cassandra
 email:
@@ -43,6 +43,7 @@ files:
 - spec/integration/client_spec.rb
 - spec/integration/protocol_spec.rb
 - spec/spec_helper.rb
+- spec/support/await_helper.rb
 - spec/support/fake_io_reactor.rb
 - spec/support/fake_server.rb
 homepage: http://github.com/iconara/cql-rb
@@ -82,6 +83,7 @@ test_files:
 - spec/integration/client_spec.rb
 - spec/integration/protocol_spec.rb
 - spec/spec_helper.rb
+- spec/support/await_helper.rb
 - spec/support/fake_io_reactor.rb
 - spec/support/fake_server.rb
 has_rdoc: