riakpb 0.1.0

data/lib/riak/client.rb

@@ -0,0 +1,227 @@
+require 'riak'
+
+module Riak
+  # A client connection to Riak.
+  class Client
+    include Util::Translation
+    include Util::MessageCode
+
+    autoload :Rpc, 'riak/client/rpc'
+
+    # When using integer client IDs, the exclusive upper-bound of valid values.
+    MAX_CLIENT_ID = 4294967296
+
+    # Regexp for validating hostnames
+    #   http://rubular.com/r/N2HOgxFkN3
+    HOST_REGEX = /^([[:alnum:]]+(-*[[:alnum:]]+)*(\.{0,1}(([[:alnum:]]-*)*[[:alnum:]]+)+)*)+$/
+
+    attr_reader :host
+    attr_reader :port
+    attr_reader :buckets
+    attr_reader :bucket_cache
+    attr_reader :node
+    attr_reader :server_version
+    attr_reader :client_id
+
+    # Creates a client connection to Riak's Protobuf Listener
+    # @param [String] options configuration options for the client
+    # @param [String] host ('127.0.0.1') The host or IP address for the Riak endpoint
+    # @param [Fixnum] port (8087) The port of the Riak protobuf listener endpoint
+    def initialize(options={})
+      self.host         = options[:host]      ||      "127.0.0.1"
+      self.port         = options[:port]      ||      8087
+      self.client_id    = options[:client_id] unless  options[:client_id].nil?
+      @w                = options[:w]
+      @dw               = options[:dw]
+      @buckets          = []
+      @bucket_cache     = Hash.new{|k,v| k[v] = Riak::Bucket.new(self, v)}
+    end
+
+    # Set the hostname of the Riak endpoint. Must be an IPv4, IPv6, or valid hostname
+    # @param [String] value The host or IP address for the Riak endpoint
+    # @raise [ArgumentError] if an invalid hostname is given
+    # @return [String] the assigned hostname
+    def host=(value)
+      raise ArgumentError, t("hostname_invalid") unless value.is_a?(String) && value =~ HOST_REGEX
+      @host = value
+    end
+
+    # Set the port number of the Riak endpoint. This must be an integer between 0 and 65535.
+    # @param [Fixnum] value The port number of the Riak endpoint
+    # @raise [ArgumentError] if an invalid port number is given
+    # @return [Fixnum] the assigned port number
+    def port=(value)
+      raise ArgumentError, t("port_invalid") unless (0..65535).include?(value)
+      @port = value
+    end
+
+    # Set the client ID for this client. Must be a string or Fixnum value 0 =< value < MAX_CLIENT_ID.
+    # @param [String, Fixnum] value The internal client ID used by Riak to route responses
+    # @raise [ArgumentError] when an invalid client ID is given
+    # @return [String] the assigned client ID
+    def client_id=(value)
+      @client_id = case value
+                   when 0...MAX_CLIENT_ID
+                     b64encode(value)
+                   when String
+                     value
+                   else
+                     raise ArgumentError, t("invalid_client_id", :max_id => MAX_CLIENT_ID)
+                   end
+    end
+
+    # Establish a connection to the riak node, and store the Rpc instance
+    # @return [Riak::Client::Rpc] the Rpc instance that handles connections to the riak node
+    def rpc(options={})
+      options[:client_id] ||= @client_id if @client_id
+      @rpc                ||= Rpc.new(self)
+    end
+
+    # Tests connectivity with the Riak host.
+    # @return [Boolean] Successful returned as 'true', failed connection returned as 'false'
+    def ping?
+      rpc.request Util::MessageCode::PING_REQUEST
+
+      return rpc.status
+    end
+
+    # Retrieves basic information from the riak node.
+    # @return [Hash] Returns the name of the node and its software release number
+    def info
+      response        = rpc.request Riak::Util::MessageCode::GET_SERVER_INFO_REQUEST
+
+      @node           = response.node
+      @server_version = response.server_version
+
+      {:node => @node, :server_version => @server_version}
+    end
+
+    # I need bucket!  Bring me bucket! (Retrieves a bucket from Riak.  Eating disorder not included.)
+    # @param [String] bucket the bucket to retrieve
+    # @return [Bucket] the requested bucket
+    def bring_me_bucket(bucket)
+      request       = Riak::RpbGetBucketReq.new(:bucket => bucket)
+      response      = rpc.request(
+                        Util::MessageCode::GET_BUCKET_REQUEST,
+                        request
+                      )
+
+      @bucket_cache[bucket].load(response)
+    end
+    alias :[]     :bring_me_bucket
+    alias :bucket :bring_me_bucket
+
+    # Retrieves a key, using RpbGetReq, from within a given bucket, from Riak.
+    # @param [String] bucket the bucket from which to retrieve the key
+    # @param [String] key the name of the key to be received
+    # @param [Fixnum] quorum read quorum- num of replicas need to agree when retrieving the object
+    # @return [RpbGetResp] the response in which the given Key is stored
+    def get_request(bucket, key, quorum=nil)
+      request   = Riak::RpbGetReq.new({:bucket => bucket, :key => key})
+      request.r = quorum if quorum.is_a?(Fixnum)
+
+      response  = rpc.request(
+                    Util::MessageCode::GET_REQUEST,
+                    request
+                  )
+
+      return(response)
+    end
+    alias :req :get_request
+    alias :get :get_request
+
+    # Inserts a key into riak, using RpbPutReq.
+    # @option options [Fixnum] :w (write quorum) how many replicas to write to before returning a successful response.
+    # @option options [Fixnum :dw how many replicas to commit to durable storage before returning a successful response.
+    # @option options [Boolean] :return_body whether to return the contents of the stored object.
+    # @return [RpbPutResp] the response confirming Key storage and (optionally) the Key's updated/new data.
+    def put_request(options)
+      raise ArgumentError, t('invalid_bucket')  if options[:bucket].empty?
+      raise ArgumentError, t('empty_content')   if options[:content].nil?
+
+      options[:w]           ||= @w  unless @w.nil?
+      options[:dw]          ||= @dw unless @dw.nil?
+      options[:return_body] ||= true
+
+      request   = Riak::RpbPutReq.new(options)
+
+      response  = rpc.request(
+                    Util::MessageCode::PUT_REQUEST,
+                    request
+                  )
+
+      return(response)
+    end
+
+    # Deletes a key, using RpbDelReq, from within a given bucket, from Riak.
+    # @param [String] bucket the bucket from which to delete the key
+    # @param [String] key the name of the key to be deleted
+    # @param [Fixnum] rw how many replicas to delete before returning a successful response
+    # @return [RpbGetResp] the response confirming deletion
+    def del_request(bucket, key, rw=nil)
+      request         = Riak::RpbDelReq.new
+      request.bucket  = bucket
+      request.key     = key
+      request.rw    ||= rw
+
+      response        = rpc.request(
+                          Util::MessageCode::DEL_REQUEST,
+                          request
+                        )
+    end
+
+    # Sends a MapReduce operation to riak, using RpbMapRedReq, and returns the Response/phases.
+    # @param [String] mr_request map/reduce job, encoded/stringified
+    # @param [String] content_type encoding for map/reduce job
+    # @return [RpbMapRedResp] the response, encoded in the same format that was sent
+    def map_reduce_request(mr_request, content_type)
+      request               = Riak::RpbMapRedReq.new
+      request.request       = mr_request
+      request.content_type  = content_type
+
+      response              = rpc.request(
+                                Util::MessageCode::MAP_REDUCE_REQUEST,
+                                request
+                              )
+
+       return(response)
+    end
+    alias :mapred :map_reduce_request
+    alias :mr     :map_reduce_request
+
+    # Lists the buckets found in the Riak database
+    # @raise [ReturnRespError] if the message response does not correlate with the message requested
+    # @return [Array] list of buckets (String)
+    def buckets
+      response = rpc.request Util::MessageCode::LIST_BUCKETS_REQUEST
+
+      # iterate through each of the Strings in the Bucket list, returning an array of String(s)
+      @buckets = response.buckets.each{|b| b}
+    end
+
+    # Lists the keys within their respective buckets, that are found in the Riak database
+    # @param [String] bucket the bucket from which to retrieve the list of keys
+    # @raise [ReturnRespError] if the message response does not correlate with the message requested
+    # @return [Hash] Mapping of the buckets (String) to their keys (Array of Strings)
+    def keys_in(bucket)
+
+      list_keys_request = RpbListKeysReq.new(:bucket => bucket)
+
+      response = rpc.request Util::MessageCode::LIST_KEYS_REQUEST, list_keys_request
+
+      return(response.keys.each{|k| k})
+    end
+
+    # @return [String] A representation suitable for IRB and debugging output.
+#      def inspect
+#        "#<Client >"
+#      end
+
+    private
+    def b64encode(n)
+      Base64.encode64([n].pack("N")).chomp
+    end
+
+  end # class Client
+end # module Riak
+

data/lib/riak/client_pb.rb

@@ -0,0 +1,372 @@
+### Generated by rprotoc. DO NOT EDIT!
+### <proto file: riakclient.proto>
+# /* -------------------------------------------------------------------
+# **
+# ** riakclient.proto: Protocol buffers for riak
+# **
+# ** Copyright (c) 2007-2010 Basho Technologies, Inc.  All Rights Reserved.
+# **
+# ** This file is provided to you under the Apache License,
+# ** Version 2.0 (the "License"); you may not use this file
+# ** except in compliance with the License.  You may obtain
+# ** a copy of the License at
+# **
+# **   http://www.apache.org/licenses/LICENSE-2.0
+# **
+# ** Unless required by applicable law or agreed to in writing,
+# ** software distributed under the License is distributed on an
+# ** "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# ** KIND, either express or implied.  See the License for the
+# ** specific language governing permissions and limitations
+# ** under the License.
+# **
+# ** -------------------------------------------------------------------
+# */
+# /*
+# ** Revision: 1.1
+# **
+# ** Lowest Common Denominator Protocol Buffers Client
+# **   - no ENUM (protobuffs_erlang does not support)
+# **
+# ** Protocol 
+# **
+# **   The protocol encodes requests and responses as protocol buffer messages.
+# **   Each request message results in one or more response messages.
+# **   As message type and length are not encoded by PB they are sent
+# **   on the wire as
+# **
+# **     <length:32>  <msg_code:8> <pbmsg>
+# **
+# **     length is the length of msg_code (1 byte) plus the message length
+# **     in bytes encoded in network order (big endian)
+# **
+# **     msg_code indicates what is encoded as pbmsg
+# **
+# **     pbmsg is the encoded protocol buffer message
+# **
+# **   On connect, the client sends RpbHello with protocol/node information.
+# **   After that client can make requests and will receive responses.
+# **   For each request message there is a correspondign response message,
+# **   or the server will respond with an error message if something has
+# **   gone wrong.
+# **
+# **   The client should be prepared to handle messages without any pbmsg
+# **   (i.e. length==1) for requests like ping or a put without return_body set.
+# **   
+# **   RpbGetClientIdReq -> RpbGetClientIdResp
+# **   RpbSetClientIdReq -> RpbSetClientIdResp
+# **   RpbGetServerInfoReq -> RpbGetServerInfoResp
+# **   RpbPingReq -> RpbPingResp
+# **   RpbGetReq -> RpbErrorResp | RbpGetResp
+# **   RpbPutReq -> RpbErrorResp | RpbPutResp
+# **   RpbDelReq -> RpbErrorResp | RpbDelResp
+# **   RpbListBucketsReq -> RpbErrorResp | RpbListBucketsResp
+# **   RpbListKeysReq -> RpbErrorResp | RpbListKeysResp{1,}
+# **   RpbGetBucketReq -> RpbErrorResp | RpbGetBucketResp
+# **
+# **
+# ** Message Codes
+# **  0 - RpbErrorResp
+# **  1 - RpbPingReq - 0 length
+# **  2 - RpbPingResp (pong) - 0 length
+# **  3 - RpbGetClientIdReq
+# **  4 - RpbGetClientIdResp
+# **  5 - RpbSetClientIdReq
+# **  6 - RpbSetClientIdResp
+# **  7 - RpbGetServerInfoReq
+# **  8 - RpbGetServerInfoResp
+# **  9 - RpbGetReq 
+# ** 10 - RpbGetResp
+# ** 11 - RpbPutReq 
+# ** 12 - RpbPutResp - 0 length
+# ** 13 - RpbDelReq 
+# ** 14 - RpbDelResp
+# ** 15 - RpbListBucketsReq
+# ** 16 - RpbListBucketsResp{1,}
+# ** 17 - RpbListKeysReq
+# ** 18 - RpbListKeysResp{1,}
+# ** 19 - RpbGetBucketReq
+# ** 20 - RpbGetBucketResp
+# ** 21 - RpbSetBucketReq
+# ** 22 - RpbSetBucketResp
+# ** 23 - RpbMapRedReq
+# ** 24 - RpbMapRedResp
+# **
+# */
+# 
+# // Error response - may be generated for any Req
+# message RpbErrorResp {
+#     required bytes errmsg = 1;
+#     required uint32 errcode = 2;
+# }
+# 
+# // Get ClientId Request - no message defined, just send RpbGetClientIdReq message code
+# message RpbGetClientIdResp {
+#     required bytes client_id = 1; // Client id in use for this connection
+# }
+# 
+# message RpbSetClientIdReq {
+#     required bytes client_id = 1; // Client id to use for this connection
+# }
+# // Set ClientId Request - no message defined, just send RpbSetClientIdReq message code
+# 
+# // Get server info request - no message defined, just send RpbGetServerInfoReq message code
+# 
+# message RpbGetServerInfoResp {
+#     optional bytes node = 1;
+#     optional bytes server_version = 2;
+# }
+# 
+# 
+# // Get Request - retrieve bucket/key
+# message RpbGetReq {
+#     required bytes bucket = 1;
+#     required bytes key = 2;
+#     optional uint32 r = 3;
+# }
+# 
+# // Get Response - if the record was not found there will be no content/vclock
+# message RpbGetResp {
+#     repeated RpbContent content = 1;
+#     optional bytes vclock = 2;        // the opaque vector clock for the object
+# }
+# 
+# 
+# // Put request - if options.return_body is set then the updated metadata/data for
+# //               the key will be returned.
+# message RpbPutReq {
+#     required bytes bucket = 1;
+#     required bytes key = 2;
+#     optional bytes vclock = 3;
+#     required RpbContent content = 4;
+#     optional uint32 w = 5;
+#     optional uint32 dw = 6;
+#     optional bool return_body = 7;
+# }
+# 
+# // Put response - same as get response
+# message RpbPutResp {
+#     repeated RpbContent contents = 1;
+#     optional bytes vclock = 2;        // the opaque vector clock for the object
+# }
+# 
+# 
+# // Delete request
+# message RpbDelReq {
+#     required bytes bucket = 1;
+#     required bytes key = 2;
+#     optional uint32 rw = 3;
+# }
+# 
+# // Delete response - not defined, will return a RpbDelResp on success or RpbErrorResp on failure
+# 
+# // List buckets request - no message defined, just send RpbListBucketsReq
+# 
+# // List buckets response
+# message RpbListBucketsResp {
+#     repeated bytes buckets = 1;
+# }
+# 
+# 
+# // List keys in bucket request
+# message RpbListKeysReq {
+#     required bytes bucket = 1;
+# }
+# 
+# // List keys in bucket response - one or more of these packets will be sent
+# // the last one will have done set true (and may not have any keys in it)
+# message RpbListKeysResp {
+#     repeated bytes keys = 1;
+#     optional bool done = 2;
+# }
+# 
+# // Get bucket properties request
+# message RpbGetBucketReq {
+#     required bytes bucket = 1;
+# }
+# 
+# // Get bucket properties response
+# message RpbGetBucketResp {
+#     required RpbBucketProps props = 1;    
+# }
+# 
+# // Set bucket properties request
+# message RpbSetBucketReq {
+#     required bytes bucket = 1;
+#     required RpbBucketProps props = 2;
+# }
+# 
+# 
+# // Set bucket properties response - no message defined, just send RpbSetBucketResp
+# 
+# 
+# // Map/Reduce request
+# message RpbMapRedReq {
+#     required bytes request = 1;
+#     required bytes content_type = 2;
+# }
+# 
+# // Map/Reduce response
+# // one or more of these packets will be sent the last one will have done set
+# // true (and may not have phase/data in it)
+# message RpbMapRedResp {
+#     optional uint32 phase = 1;
+#     optional bytes response = 2;
+#     optional bool done = 3;
+# }
+# 
+# // Content message included in get/put responses
+# // Holds the value and associated metadata
+# message RpbContent {
+#     required bytes value = 1;
+#     optional bytes content_type = 2;     // the media type/format
+#     optional bytes charset = 3;
+#     optional bytes content_encoding = 4;
+#     optional bytes vtag = 5;
+#     repeated RpbLink links = 6;          // links to other resources
+#     optional uint32 last_mod = 7;
+#     optional uint32 last_mod_usecs = 8;
+#     repeated RpbPair usermeta = 9;       // user metadata stored with the object
+# }
+# 
+# // Key/value pair - used for user metadata
+# message RpbPair {
+#     required bytes key = 1;
+#     optional bytes value = 2;
+# }
+# 
+# // Link metadata
+# message RpbLink {
+#     optional bytes bucket = 1;
+#     optional bytes key = 2;
+#     optional bytes tag = 3;
+# }
+# 
+# // Bucket properties
+# message RpbBucketProps {
+#     optional uint32 n_val = 1;
+#     optional bool allow_mult = 2;
+# }
+
+require 'protobuf/message/message'
+require 'protobuf/message/enum'
+require 'protobuf/message/service'
+require 'protobuf/message/extend'
+
+module Riak
+  class RpbErrorResp < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :errmsg, 1
+    required :uint32, :errcode, 2
+  end
+  class RpbGetClientIdResp < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :client_id, 1
+  end
+  class RpbSetClientIdReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :client_id, 1
+  end
+  class RpbGetServerInfoResp < ::Protobuf::Message
+    defined_in __FILE__
+    optional :bytes, :node, 1
+    optional :bytes, :server_version, 2
+  end
+  class RpbGetReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :bucket, 1
+    required :bytes, :key, 2
+    optional :uint32, :r, 3
+  end
+  class RpbGetResp < ::Protobuf::Message
+    defined_in __FILE__
+    repeated :RpbContent, :content, 1
+    optional :bytes, :vclock, 2
+  end
+  class RpbPutReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :bucket, 1
+    required :bytes, :key, 2
+    optional :bytes, :vclock, 3
+    required :RpbContent, :content, 4
+    optional :uint32, :w, 5
+    optional :uint32, :dw, 6
+    optional :bool, :return_body, 7
+  end
+  class RpbPutResp < ::Protobuf::Message
+    defined_in __FILE__
+    repeated :RpbContent, :content, 1
+    optional :bytes, :vclock, 2
+  end
+  class RpbDelReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :bucket, 1
+    required :bytes, :key, 2
+    optional :uint32, :rw, 3
+  end
+  class RpbListBucketsResp < ::Protobuf::Message
+    defined_in __FILE__
+    repeated :bytes, :buckets, 1
+  end
+  class RpbListKeysReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :bucket, 1
+  end
+  class RpbListKeysResp < ::Protobuf::Message
+    defined_in __FILE__
+    repeated :bytes, :keys, 1
+    optional :bool, :done, 2
+  end
+  class RpbGetBucketReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :bucket, 1
+  end
+  class RpbGetBucketResp < ::Protobuf::Message
+    defined_in __FILE__
+    required :RpbBucketProps, :props, 1
+  end
+  class RpbSetBucketReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :bucket, 1
+    required :RpbBucketProps, :props, 2
+  end
+  class RpbMapRedReq < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :request, 1
+    required :bytes, :content_type, 2
+  end
+  class RpbMapRedResp < ::Protobuf::Message
+    defined_in __FILE__
+    repeated :uint32, :phase, 1
+    repeated :bytes, :response, 2
+    optional :bool, :done, 3
+  end
+  class RpbContent < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :value, 1
+    optional :bytes, :content_type, 2
+    optional :bytes, :charset, 3
+    optional :bytes, :content_encoding, 4
+    optional :bytes, :vtag, 5
+    repeated :RpbLink, :links, 6
+    optional :uint32, :last_mod, 7
+    optional :uint32, :last_mod_usecs, 8
+    repeated :RpbPair, :usermeta, 9
+  end
+  class RpbPair < ::Protobuf::Message
+    defined_in __FILE__
+    required :bytes, :key, 1
+    optional :bytes, :value, 2
+  end
+  class RpbLink < ::Protobuf::Message
+    defined_in __FILE__
+    optional :bytes, :bucket, 1
+    optional :bytes, :key, 2
+    optional :bytes, :tag, 3
+  end
+  class RpbBucketProps < ::Protobuf::Message
+    defined_in __FILE__
+    optional :uint32, :n_val, 1
+    optional :bool, :allow_mult, 2
+  end
+end

data/lib/riak/failed_exchange.rb

@@ -0,0 +1,21 @@
+require 'riak'
+
+module Riak
+  # Exception raised when the expected response code from Riak
+  # fails to match the actual response code.
+  class FailedExchange < StandardError
+    include Util::Translation
+
+    attr_reader :expected
+    attr_reader :actual
+    attr_reader :output
+    attr_reader :stub
+
+    def initialize(expected, actual, output, stub)
+      @expected, @actual, @output, @stub = expected, actual, output, stub
+      super t("failed_rx", :failure => 
+                t(@stub, :expected => @expected, :actual => @actual, :output => @output.inspect)
+            )
+    end
+  end
+end

data/lib/riak/failed_request.rb

@@ -0,0 +1,22 @@
+require 'riak'
+
+module Riak
+  # Exception raised when the expected response code from Riak
+  # fails to match the actual response code.
+  class FailedRequest < StandardError
+    include Riak::Util::Translation
+
+    attr_reader :expected
+    attr_reader :actual
+    attr_reader :output
+    attr_reader :message
+
+    def initialize(expected=nil, actual=nil, output=nil, message=nil)
+      @expected = expected
+      @actual   = actual
+      @output   = output
+      @message  = message || "failed_request"
+      super t(@message, :expected => @expected, :actual => @actual, :output => @output.inspect)
+    end
+  end
+end

data/lib/riak/i18n.rb

@@ -0,0 +1,7 @@
+begin
+  require 'active_support/i18n'
+rescue LoadError
+  require 'i18n' # support ActiveSupport < 3
+end
+
+I18n.load_path << File.expand_path("../locale/en.yml", __FILE__)