cassilds 0.9.1

data/lib/cassandra/cassandra.rb

@@ -0,0 +1,302 @@
+
+=begin rdoc
+Create a new Cassandra client instance. Accepts a keyspace name, and optional host and port.
+
+  client = Cassandra.new('twitter', '127.0.0.1:9160')
+  
+If the server requires authentication, you must authenticate before make calls
+
+  client.login!('username','password')
+
+You can then make calls to the server via the <tt>client</tt> instance.
+
+  client.insert(:UserRelationships, "5", {"user_timeline" => {SimpleUUID::UUID.new => "1"}})
+  client.get(:UserRelationships, "5", "user_timeline")
+
+For read methods, valid option parameters are:
+
+<tt>:count</tt>:: How many results to return. Defaults to 100.
+<tt>:start</tt>:: Column name token at which to start iterating, inclusive. Defaults to nil, which means the first column in the collation order.
+<tt>:finish</tt>:: Column name token at which to stop iterating, inclusive. Defaults to nil, which means no boundary.
+<tt>:reversed</tt>:: Swap the direction of the collation order.
+<tt>:consistency</tt>:: The consistency level of the request. Defaults to <tt>Cassandra::Consistency::ONE</tt> (one node must respond). Other valid options are <tt>Cassandra::Consistency::ZERO</tt>, <tt>Cassandra::Consistency::QUORUM</tt>, and <tt>Cassandra::Consistency::ALL</tt>.
+
+Note that some read options have no relevance in some contexts.
+
+For write methods, valid option parameters are:
+
+<tt>:timestamp </tt>:: The transaction timestamp. Defaults to the current time in milliseconds. This is used for conflict resolution by the server; you normally never need to change it.
+<tt>:consistency</tt>:: See above.
+
+For the initial client instantiation, you may also pass in <tt>:thrift_client<tt> with a ThriftClient subclass attached. On connection, that class will be used instead of the default ThriftClient class, allowing you to add additional behavior to the connection (e.g. query logging).
+
+=end rdoc
+
+class Cassandra
+  include Columns
+  include Protocol
+  include Helpers
+
+  class AccessError < StandardError #:nodoc:
+  end
+
+  module Consistency
+    include CassandraThrift::ConsistencyLevel
+  end
+
+  WRITE_DEFAULTS = {
+    :count => 1000,
+    :timestamp => nil,
+    :consistency => Consistency::ONE,
+    :ttl => nil
+  }.freeze
+
+  READ_DEFAULTS = {
+    :count => 100,
+    :start => nil,
+    :finish => nil,
+    :reversed => false,
+    :consistency => Consistency::ONE
+  }.freeze
+  
+  THRIFT_DEFAULTS = {
+    :transport_wrapper => Thrift::BufferedTransport,
+    :thrift_client_class => ThriftClient
+  }.freeze
+
+  attr_reader :keyspace, :servers, :schema, :thrift_client_options, :thrift_client_class, :auth_request
+
+  # Create a new Cassandra instance and open the connection.
+  def initialize(keyspace, servers = "127.0.0.1:9160", thrift_client_options = {})
+    @is_super = {}
+    @column_name_class = {}
+    @sub_column_name_class = {}
+    @auto_discover_nodes = true
+    thrift_client_options[:transport_wrapper] ||= Cassandra.DEFAULT_TRANSPORT_WRAPPER
+    @thrift_client_options = THRIFT_DEFAULTS.merge(thrift_client_options)
+    @thrift_client_class = @thrift_client_options[:thrift_client_class]
+    @keyspace = keyspace
+    @servers = Array(servers)
+  end
+
+  def disable_node_auto_discovery!
+    @auto_discover_nodes = false
+  end
+
+  def disconnect!
+    if @client
+      @client.disconnect!
+      @client = nil
+    end
+  end
+
+  def keyspaces
+    @keyspaces ||= client.describe_keyspaces()
+  end
+  
+  def login!(username, password)
+    @auth_request = CassandraThrift::AuthenticationRequest.new
+    @auth_request.credentials = {'username' => username, 'password' => password}
+    client.login(@keyspace, @auth_request)
+  end
+  
+  def inspect
+    "#<Cassandra:#{object_id}, @keyspace=#{keyspace.inspect}, @schema={#{
+      schema(false).map {|name, hash| ":#{name} => #{hash['type'].inspect}"}.join(', ')
+    }}, @servers=#{servers.inspect}>"
+  end
+
+### Write
+
+  # Insert a row for a key. Pass a flat hash for a regular column family, and
+  # a nested hash for a super column family. Supports the <tt>:consistency</tt>,
+  # <tt>:timestamp</tt> and <tt>:ttl</tt> options.
+  def insert(column_family, key, hash, options = {})
+    column_family, _, _, options = extract_and_validate_params(column_family, key, [options], WRITE_DEFAULTS)
+
+    timestamp = options[:timestamp] || Time.stamp
+    mutation_map = if is_super(column_family)
+      {
+        key => {
+          column_family => hash.collect{|k,v| _super_insert_mutation(column_family, k, v, timestamp, options[:ttl]) }
+        }
+      }
+    else
+      {
+        key => {
+          column_family => hash.collect{|k,v| _standard_insert_mutation(column_family, k, v, timestamp, options[:ttl])}
+        }
+      }
+    end
+
+    @batch ? @batch << [mutation_map, options[:consistency]] : _mutate(mutation_map, options[:consistency])
+  end
+
+
+  ## Delete
+
+  # _mutate the element at the column_family:key:[column]:[sub_column]
+  # path you request. Supports the <tt>:consistency</tt> and <tt>:timestamp</tt>
+  # options.
+  def remove(column_family, key, *columns_and_options)
+    column_family, column, sub_column, options = extract_and_validate_params(column_family, key, columns_and_options, WRITE_DEFAULTS)
+
+    args = {:column_family => column_family}
+    columns = is_super(column_family) ? {:super_column => column, :column => sub_column} : {:column => column}
+    column_path = CassandraThrift::ColumnPath.new(args.merge(columns))
+
+    mutation = [:remove, [key, column_path, options[:timestamp] || Time.stamp, options[:consistency]]]
+
+    @batch ? @batch << mutation : _remove(*mutation[1])
+  end
+
+### Read
+
+  # Count the elements at the column_family:key:[super_column] path you
+  # request. Supports the <tt>:consistency</tt> option.
+  def count_columns(column_family, key, *columns_and_options)
+    column_family, super_column, _, options = 
+      extract_and_validate_params(column_family, key, columns_and_options, READ_DEFAULTS)      
+    _count_columns(column_family, key, super_column, options[:consistency])
+  end
+
+  # Multi-key version of Cassandra#count_columns. Supports options <tt>:count</tt>,
+  # <tt>:start</tt>, <tt>:finish</tt>, <tt>:reversed</tt>, and <tt>:consistency</tt>.
+  # FIXME Not real multi; needs server support
+  def multi_count_columns(column_family, keys, *options)
+    OrderedHash[*keys.map { |key| [key, count_columns(column_family, key, *options)] }._flatten_once]
+  end
+
+  # Return a list of single values for the elements at the
+  # column_family:key:column[s]:[sub_columns] path you request. Supports the
+  # <tt>:consistency</tt> option.
+  def get_columns(column_family, key, *columns_and_options)
+    column_family, columns, sub_columns, options = 
+      extract_and_validate_params(column_family, key, columns_and_options, READ_DEFAULTS)      
+    _get_columns(column_family, key, columns, sub_columns, options[:consistency])
+  end
+
+  # Multi-key version of Cassandra#get_columns. Supports the <tt>:consistency</tt>
+  # option.
+  # FIXME Not real multi; needs to use a Column predicate
+  def multi_get_columns(column_family, keys, *options)
+    OrderedHash[*keys.map { |key| [key, get_columns(column_family, key, *options)] }._flatten_once]
+  end
+
+  # Return a hash (actually, a Cassandra::OrderedHash) or a single value
+  # representing the element at the column_family:key:[column]:[sub_column]
+  # path you request. Supports options <tt>:count</tt>, <tt>:start</tt>,
+  # <tt>:finish</tt>, <tt>:reversed</tt>, and <tt>:consistency</tt>.
+  def get(column_family, key, *columns_and_options)
+    multi_get(column_family, [key], *columns_and_options)[key]
+  end
+
+  # Multi-key version of Cassandra#get. Supports options <tt>:count</tt>,
+  # <tt>:start</tt>, <tt>:finish</tt>, <tt>:reversed</tt>, and <tt>:consistency</tt>.
+  def multi_get(column_family, keys, *columns_and_options)
+    column_family, column, sub_column, options = 
+      extract_and_validate_params(column_family, keys, columns_and_options, READ_DEFAULTS)
+
+    hash = _multiget(column_family, keys, column, sub_column, 
+      options[:start], options[:finish], options[:count], options[:reversed],
+      options[:consistency])
+    # Restore order
+    ordered_hash = OrderedHash.new
+    keys.each { |key| ordered_hash[key] = hash[key] || (OrderedHash.new if is_super(column_family) and !sub_column) }
+    ordered_hash
+  end
+
+  # Return true if the column_family:key:[column]:[sub_column] path you
+  # request exists. Supports the <tt>:consistency</tt> option.
+  def exists?(column_family, key, *columns_and_options)
+    column_family, column, sub_column, options = 
+      extract_and_validate_params(column_family, key, columns_and_options, READ_DEFAULTS)
+    ret = nil
+    if column
+      ret = _multiget(column_family, [key], column, sub_column, '', '', 1, false, options[:consistency])[key]
+    else
+      ret = _multiget(column_family, [key], nil, nil, '', '', 1, false, options[:consistency])[key]
+    end
+    return (!ret.nil? and ret.send(:length) != 0)
+  end
+
+  # Return a list of keys in the column_family you request. Requires the
+  # table to be partitioned with OrderPreservingHash. Supports the
+  # <tt>:count</tt>, <tt>:start</tt>, <tt>:finish</tt>, and <tt>:consistency</tt>
+  # options.
+  def get_range(column_family, options = {})
+    column_family, _, _, options = 
+      extract_and_validate_params(column_family, "", [options], READ_DEFAULTS)
+    _get_range(column_family, options[:start].to_s, options[:finish].to_s,
+      options[:count], options[:consistency])
+  end
+
+  # Return a list of keys in the column_family you request. Requires the
+  # table to be partitioned with OrderPreservingHash. Supports the
+  # <tt>:count</tt>, <tt>:start</tt>, <tt>:finish</tt>, and <tt>:consistency</tt>
+  # options.
+  def get_range_hash(column_family, options = {})
+    column_family, _, _, options =
+      extract_and_validate_params(column_family, "", [options], READ_DEFAULTS)
+    _get_range_hash(column_family, options[:start].to_s, options[:finish].to_s,
+      options[:count], options[:consistency])
+  end
+
+  # Return a list of keys in the column_family you request. Requires the
+  # table to be partitioned with OrderPreservingHash. Supports the
+  # <tt>:count</tt>, <tt>:start</tt>, <tt>:finish</tt>, and <tt>:consistency</tt>
+  # options.
+  def get_range_columns(column_family, *columns_and_options)
+    column_family, columns, sub_columns, options =
+      extract_and_validate_params(column_family, "", columns_and_options, READ_DEFAULTS)
+    _get_range_columns(column_family, columns, sub_columns, options[:start].to_s,
+      options[:finish].to_s, options[:count], options[:consistency])
+  end
+
+  # Count all rows in the column_family you request. Requires the table
+  # to be partitioned with OrderPreservingHash. Supports the <tt>:start</tt>,
+  # <tt>:finish</tt>, and <tt>:consistency</tt> options.
+  def count_range(column_family, options = {})
+    get_range(column_family, options).select{|r| r.columns.length > 0}.compact.length
+  end
+
+  # Open a batch operation and yield self. Inserts and deletes will be queued
+  # until the block closes, and then sent atomically to the server.  Supports
+  # the <tt>:consistency</tt> option, which overrides the consistency set in
+  # the individual commands.
+  def batch(options = {})
+    _, _, _, options = 
+      extract_and_validate_params(schema.keys.first, "", [options], WRITE_DEFAULTS)
+
+    @batch = []
+    yield(self)
+    compact_mutations!
+
+    @batch.each do |mutation|
+      case mutation.first
+      when :remove
+        _remove(*mutation[1])
+      else
+        _mutate(*mutation)
+      end
+    end
+  ensure
+    @batch = nil
+  end
+  
+  protected
+
+  def calling_method
+    "#{self.class}##{caller[0].split('`').last[0..-3]}"
+  end
+
+  # Roll up queued mutations, to improve atomicity.
+  def compact_mutations!
+    #TODO re-do this rollup
+  end
+
+  def new_client
+    thrift_client_class.new(CassandraThrift::Cassandra::Client, @servers, @thrift_client_options)
+  end
+  
+end

data/lib/cassandra/columns.rb

@@ -0,0 +1,79 @@
+
+class Cassandra
+  # A bunch of crap, mostly related to introspecting on column types
+  module Columns #:nodoc:
+
+    def is_super(column_family)
+      @is_super[column_family] ||= column_family_property(column_family, 'Type') == "Super"
+    end
+
+    def column_name_class(column_family)
+      @column_name_class[column_family] ||= column_name_class_for_key(column_family, "CompareWith")
+    end
+
+    def sub_column_name_class(column_family)
+      @sub_column_name_class[column_family] ||= column_name_class_for_key(column_family, "CompareSubcolumnsWith")
+    end
+
+    private
+
+    def column_name_class_for_key(column_family, comparator_key)
+      property = column_family_property(column_family, comparator_key)
+      property =~ /.*\.(.*?)$/
+      case $1
+      when "LongType" then Long
+      when "LexicalUUIDType", "TimeUUIDType" then SimpleUUID::UUID
+      else
+        String # UTF8, Ascii, Bytes, anything else
+      end
+    end
+
+    def column_family_property(column_family, key)
+      unless schema[column_family]
+        raise AccessError, "Invalid column family \"#{column_family}\""
+      end
+      schema[column_family][key]
+    end
+
+    def multi_column_to_hash!(hash)
+      hash.each do |key, column_or_supercolumn|
+        hash[key] = (column_or_supercolumn.column.value if column_or_supercolumn.column)
+      end
+    end
+
+    def multi_columns_to_hash!(column_family, hash)
+      hash.each do |key, columns|
+        hash[key] = columns_to_hash(column_family, columns)
+      end
+    end
+
+    def multi_sub_columns_to_hash!(column_family, hash)
+      hash.each do |key, sub_columns|
+        hash[key] = sub_columns_to_hash(column_family, sub_columns)
+      end
+    end
+
+    def columns_to_hash(column_family, columns)
+      columns_to_hash_for_classes(columns, column_name_class(column_family), sub_column_name_class(column_family))
+    end
+
+    def sub_columns_to_hash(column_family, columns)
+      columns_to_hash_for_classes(columns, sub_column_name_class(column_family))
+    end
+
+    def columns_to_hash_for_classes(columns, column_name_class, sub_column_name_class = nil)
+      hash = OrderedHash.new
+      Array(columns).each do |c|
+        c = c.super_column || c.column if c.is_a?(CassandraThrift::ColumnOrSuperColumn)
+        case c
+        when CassandraThrift::SuperColumn
+          hash.[]=(column_name_class.new(c.name), columns_to_hash_for_classes(c.columns, sub_column_name_class)) # Pop the class stack, and recurse
+        when CassandraThrift::Column
+          hash.[]=(column_name_class.new(c.name), c.value, c.timestamp)
+        end
+      end
+      hash
+    end
+
+  end
+end

data/lib/cassandra/comparable.rb

@@ -0,0 +1,28 @@
+
+class Cassandra
+  # Abstract base class for comparable numeric column name types
+  class Comparable
+    class TypeError < ::TypeError #:nodoc:
+    end
+  
+    def <=>(other)
+      self.to_i <=> other.to_i
+    end
+    
+    def hash
+      @bytes.hash
+    end
+    
+    def eql?(other)
+      other.is_a?(Comparable) and @bytes == other.to_s
+    end    
+    
+    def ==(other)
+      other.respond_to?(:to_i) && self.to_i == other.to_i
+    end
+    
+    def to_s
+      @bytes
+    end
+  end
+end

data/lib/cassandra/constants.rb

@@ -0,0 +1,11 @@
+
+class Cassandra
+  # A helper module you can include in your own class. Makes it easier 
+  # to work with Cassandra subclasses.
+  module Constants
+    include Cassandra::Consistency
+        
+    Long = Cassandra::Long
+    OrderedHash = Cassandra::OrderedHash
+  end
+end

data/lib/cassandra/debug.rb

@@ -0,0 +1,9 @@
+
+require 'pp'
+
+class CassandraThrift::Cassandra::Client
+  def send_message(*args)
+    pp args
+    super
+  end
+end

data/lib/cassandra/helpers.rb

@@ -0,0 +1,40 @@
+class Cassandra
+  module Helpers
+    def extract_and_validate_params(column_family, keys, args, options)
+      options = options.dup
+      column_family = column_family.to_s
+      # Keys
+      [keys].flatten.each do |key|
+        raise ArgumentError, "Key #{key.inspect} must be a String for #{caller[2].inspect}." unless key.is_a?(String)
+      end
+
+      # Options
+      if args.last.is_a?(Hash)
+        extras = args.last.keys - options.keys
+        raise ArgumentError, "Invalid options #{extras.inspect[1..-2]} for #{caller[1]}" if extras.any?
+        options.merge!(args.pop)      
+      end
+
+      # Ranges
+      column, sub_column = args[0], args[1]
+      klass, sub_klass = column_name_class(column_family), sub_column_name_class(column_family)
+      range_class = column ? sub_klass : klass
+
+      [:start, :finish].each do |opt|
+        options[opt] = options[opt] ? (options[opt] == '' ? '' : range_class.new(options[opt]).to_s) : ''
+      end
+
+      [column_family, s_map(column, klass), s_map(sub_column, sub_klass), options]
+    end
+
+    # Convert stuff to strings.
+    def s_map(el, klass)
+      case el
+      when Array then el.map { |i| s_map(i, klass) }
+      when NilClass then nil
+      else
+        klass.new(el).to_s
+      end
+    end
+  end
+end

data/lib/cassandra/long.rb

@@ -0,0 +1,58 @@
+
+class Cassandra
+  # A temporally-ordered Long class for use in Cassandra column names
+  class Long < Cassandra::Comparable
+
+    # FIXME Should unify with or subclass Cassandra::UUID
+    def initialize(bytes = nil)
+      case bytes
+      when self.class # Long
+        @bytes = bytes.to_s
+      when String
+        case bytes.size
+        when 8 # Raw byte array
+          @bytes = bytes
+        when 18 # Human-readable UUID-like representation; inverse of #to_guid
+          elements = bytes.split("-")
+          raise TypeError, "Expected #{bytes.inspect} to cast to a #{self.class} (malformed UUID-like representation)" if elements.size != 3
+          @bytes = [elements.join].pack('H32')
+        else
+          raise TypeError, "Expected #{bytes.inspect} to cast to a #{self.class} (invalid bytecount)"
+        end
+      when Integer
+        raise TypeError, "Expected #{bytes.inspect} to cast to a #{self.class} (integer out of range)" if bytes < 0 or bytes > 2**64
+        @bytes = [bytes >> 32, bytes % 2**32].pack("NN")
+      when NilClass, Time
+        # Time.stamp is 52 bytes, so we have 12 bytes of entropy left over
+        int = ((bytes || Time).stamp << 12) + rand(2**12)
+        @bytes = [int >> 32, int % 2**32].pack("NN")
+      else
+        raise TypeError, "Expected #{bytes.inspect} to cast to a #{self.class} (unknown source class)"
+      end
+    end
+
+    def to_i
+      @to_i ||= begin
+        ints = @bytes.unpack("NN")
+        (ints[0] << 32) +
+        ints[1]
+      end
+    end
+
+    def to_guid
+      "%08x-%04x-%04x" % @bytes.unpack("Nnn")
+    end    
+
+    def inspect
+      "<Cassandra::Long##{object_id} time: #{
+        Time.at((to_i >> 12) / 1_000_000).utc.inspect
+      }, usecs: #{
+        (to_i >> 12) % 1_000_000
+      }, jitter: #{
+        to_i % 2**12
+      }, guid: #{
+        to_guid
+      }>"
+    end
+  end
+end