riakpb 0.1.0

data/lib/riak/key.rb

@@ -0,0 +1,284 @@
+require 'riak'
+
+module Riak
+  # Represents and encapsulates operations on a Riak bucket.  You may retrieve a bucket
+  # using {Client#bucket}, or create it manually and retrieve its meta-information later.
+  class Key
+    include Util::Translation
+    include Util::MessageCode
+
+    # @return [Riak::Client] the associated client
+    attr_reader :bucket
+
+    # @return [String] the bucket name
+    attr_reader :name
+
+    # @return [String] the bucket name
+    attr_reader :vclock
+
+    # Create a Riak bucket manually.
+    # @param [Bucket] bucket the Bucket object within which this Key exists
+    # @option options [String] name the name assigned to this Key entity
+    # @option options [Fixnum] vclock Careful! Do not set this unless you have a reason to
+    # @option options [RiakContent] content a content object, that's to be inserted in this Key
+    def initialize(bucket, key, get_response=nil)
+#      options.assert_valid_keys(:name, :vclock, :content)
+
+      self.bucket   = bucket
+      self.name     = key
+
+      @contents     = Hash.new{|k,v| k[v] = Riak::RiakContent.new(self)}
+
+#      @contents[:new]
+
+      load(get_response) unless get_response.nil?
+    end
+
+    # Load information for the key from the response object, Riak::RpbGetResp.
+    #
+    # @param [RpbGetResp/Hash] response an RpbGetResp/RpbPutResp object or a Hash.
+    # @return [Key] self
+    def load(response)
+      @blargh = response
+      raise ArgumentError, t("response_type") unless response.is_a?(Protobuf::Message)
+
+      self.vclock       = response.vclock if response.has_field?(:vclock)
+
+      if response.has_field?(:content)
+        self.content    = response.content
+      elsif @contents.empty?
+        @contents[:new]
+      end
+
+      return(self)
+    end
+
+    # Load information for the key from Riak::RpbGetResp object.
+    #
+    # @param [RpbGetResp/Hash] response an RpbGetResp/RpbPutResp object or a Hash.
+    # @return [Key] self
+    def load!(response)
+      raise ArgumentError, t("response_type") unless response.is_a?(Riak::RpbGetResp)
+
+      if response.has_field?(:vclock) and response.has_field?(:content)
+
+        self.vclock   = response.vclock
+        self.content  = response.content
+
+      elsif response.has_field?(:vclock) or response.has_field?(:content)
+        raise MalformedKeyError # This should never happen
+
+      else
+        raise KeyNotFoundError
+
+      end
+
+      return(self)
+    end
+
+    # Indicates whether or not the Key is empty
+    # @return [Boolean] true or false, whether or not the vclock/content is empty
+    def empty?
+      return(true) if @vclock.empty? && (@contents.nil? || @contents.empty?)
+      return(false)
+    end
+
+    # Refreshes the Key and its content with fresh data, if there's concern that separate updates may have taken place.
+    # @return 
+    def reload!
+
+    end
+
+    # Retrieves any Keys that are linked to, inside RiakContent elements.
+    # @return [Key] the Key to which the RiakContent is linked (may be empty if it does not exist)
+    def get_linked(bucket, key, options={})
+      @bucket.get_linked(bucket, key, options)
+    end
+
+    # Sets the name attribute for this Key object
+    # @param [String] key_name sets the name of the Key
+    # @return [Hash] the properties that were accepted
+    # @raise [FailedRequest] if the new properties were not accepted by the Riak server
+    def name=(key_name)
+      raise ArgumentError, t("key_name_type") unless key_name.is_a?(String)
+
+      @name = key_name
+    end
+
+    # Sets the content object for this Key.  I do not yet support siblings in this method and, therefore,
+    #  you may or may not destroy them if you use this and are not careful.
+    # @param [Riak::RiakContent] content a RiakContent instance that should be contained within this Key
+    # @return [Riak::RiakContent] the RiakContent instance that was just set
+    # @raise [ArgumentError] will yell at you if the supplied riak_content is not of the RiakContent class
+    def content=(riak_contents)
+
+      if riak_contents.is_a?(Protobuf::Field::FieldArray)
+        @contents.clear
+        
+        return(false) if riak_contents.empty?
+
+        riak_contents.each do |rc|
+          @contents[rc.vtag].load(rc)
+        end
+        
+        return(true)
+      elsif riak_contents.is_a?(Riak::RiakContent)
+
+        @contents.clear
+
+        @contents[riak_contents.vtag].load(riak_contents)
+
+      elsif riak_contents.nil?
+        @contents.clear
+
+      else
+        raise ArgumentError, t("riak_content_type")
+      end # if riak_contents
+
+    end # def content=
+
+    # "@contents" is an array of RiakContent objects, though only contains more than one in the event that
+    #   there are siblings.
+    # @return [Riak::RiakContent] the content of this Key instance's value (ie, key/value)
+    def content
+      case @contents.size
+      when 0 then @contents[:new]
+      when 1 then contents[0]
+      else        contents
+      end
+    end
+
+    # "@contents" is an array of RiakContent objects.  This gives you that entire array.
+    # @return [Array<Riak::RiakContent>] the contents of this Key instance's value and its siblings, if any
+    def contents
+      retr_c = []
+
+      @contents.each{|k,v| retr_c << v}
+
+      return(retr_c)
+    end
+
+    # Save the Key+RiakContent instance in riak.
+    # @option options [RiakContent] content RiakContent instance to be saved in this Key.  Must be specified if there are siblings.
+    # @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 or not to have riak return the key, once saved.  default = true
+    # TODO: Add in content checking, perhaps?
+    def save(options={})
+      rcontent = options[:content]
+
+      if rcontent.nil?
+        case contents.size
+        when 0 then raise ArgumentError, t('empty_content')
+        when 1 then rcontent = contents[0]
+        else        raise SiblingError.new(self.name)
+        end
+      end
+
+      options[:content] = rcontent.to_pb  if      rcontent.is_a?(Riak::RiakContent)
+      options[:content] = rcontent        if      rcontent.is_a?(Riak::RpbContent)
+      options[:key]     = @name
+      options[:vclock]  = @vclock         unless  @vclock.nil?
+
+      begin
+        response = @bucket.store(options)
+        load(response)
+        return(true) if @contents.count == 1
+        return(false)
+      rescue FailedRequest
+        return(false)
+      end
+    end
+
+    # Save the RiakContent instance in riak.  Raise/do not rescue on failure.
+    # @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 or not to have riak return the key, once saved.  default = true
+    def save!(options={})
+      begin
+        save(options)
+        return(true) if @contents.count == 1
+        raise FailedRequest.new("save_resp_siblings", 1, @contents.count, @contents) if @contents.count > 1
+      rescue FailedRequest
+        raise FailedRequest.new("save_resp_err")
+      end
+    end
+
+    # Creates an RpbPutReq instance, to be shipped off to riak and saved
+    # @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 or not to have riak return the key, once saved.  default = true
+    # @return [Riak::RpbPutReq]
+    def to_pb_put(options={})
+      rcontent    = options[:content]
+
+      if rcontent.nil?
+        case contents.size
+        when 0 then raise ArgumentError, t('empty_content')
+        when 1 then rcontent = contents[0]
+        else        raise SiblingError.new(self.name)
+        end
+      end
+
+      pb_put_req              = Riak::RpbPutReq.new
+      pb_put_req.key          = @name
+      pb_put_req.content      = rcontent.to_pb  if      rcontent.is_a?(Riak::RiakContent)
+      pb_put_req.content      = rcontent        if      rcontent.is_a?(Riak::RpbContent)
+      pb_put_req.vclock       = @vclock         unless  @vclock.nil?
+
+      return(pb_put_req)
+    end
+
+    # "@contents" is an array of RiakContent objects.  This gives you that entire array.
+    # @return [Riak::RpbLink]
+    def to_pb_link
+      pb_link = Riak::RpbLink.new
+      pb_link[:bucket]  = @bucket.name
+      pb_link[:key]     = @name
+
+      return(pb_link)
+    end
+
+    # Converts this Key into an array, that can be used by a RiakContent, if desired.
+    # @return [Array] contains the name of the bucket and the name of the key
+    def to_link
+      [@bucket.name, @name]
+    end
+    alias :to_input :to_link
+
+    # Deletes this key from its Bucket container
+    # @param [Hash] options quorum options
+    # @option options [Fixnum] :rw - the read/write quorum for the delete
+    def delete(options={})
+      bucket.delete(@name, options)
+    end
+
+    # @return [String] a representation suitable for IRB and debugging output
+    def inspect
+      "#<Riak::Key name=#{@name.inspect}, vclock=#{@vclock.inspect}, contents=#{contents.inspect}>"
+    end
+
+    private
+
+    # Sets the name attribute for this Key object
+    # @param [String] key_name sets the name of the Key
+    # @return [Hash] the properties that were accepted
+    # @raise [FailedRequest] if the new properties were not accepted by the Riak server
+    def bucket=(bucket)
+      raise ArgumentError, t("invalid_bucket") unless bucket.is_a?(Riak::Bucket)
+
+      @bucket ||= bucket
+    end
+
+    # Sets the vclock attribute for this Key, which was supplied by the Riak node (if you're doing it right)
+    # @param [Fixnum] vclock the vector clock
+    # @return [Fixnum] the vector clock
+    # @raise [ArgumentError] if you failed at this task, you'll be instructed to place your head on the keyboard
+    def vclock=(vclock)
+      raise ArgumentError, t("vclock_type") unless vclock.is_a?(String)
+
+      @vclock = vclock
+    end
+
+  end # class Key
+end # module Riak

data/lib/riak/locale/en.yml

@@ -0,0 +1,37 @@
+en:
+  riak:
+    client_type: "invalid argument {{client}} is not a Riak::Client"
+    string_type: "invalid_argument {{string}} is not a String"
+    loading_bucket: "while loading bucket '{{name}}'"
+    invalid_bucket: "the specified bucket is invalid"
+    invalid_key: "the specified key does not exist"
+    value_empty: "a value must be set in order to serialize into a protocol buffer"
+    failed_request: "Expected message code {{expected}} from Riak but received {{actual}}. {{output}}"
+    decode_error: "Riak reported a message length of {{expected}} but length was {{actual}}. {{output}}"
+    save_resp_siblings: "The save operation has resulted in unresolved siblings. {{output}}"
+    save_resp_err: "The attempted save operation resulted in an error response from riak."
+    failed_rx: "You might have discovered a bug. {{failure}}"
+    hash_type: "invalid argument {{hash}} is not a Hash"
+    path_and_body_required: "You must supply both a resource path and a body."
+    request_body_type: "Request body must be a string or IO."
+    resource_path_short: "Resource path too short"
+    missing_host_and_port: "You must specify a host and port, or use the defaults of 127.0.0.1:8098"
+    invalid_client_id: "Invalid client ID, must be a string or between 0 and {{max_id}}"
+    hostname_invalid: "host must be a valid hostname"
+    port_invalid: "port must be an integer between 0 and 65535"
+    install_curb: "curb library not found! Please `gem install curb` for better performance."
+    bucket_link_conversion: "Can't convert a bucket link to a walk spec"
+    invalid_phase_type: "type must be :map, :reduce, or :link"
+    module_function_pair_required: "function must have two elements when an array"
+    stored_function_invalid: "function must have :bucket and :key when a hash"
+    walk_spec_invalid_unless_link: "WalkSpec is only valid for a function when the type is :link"
+    invalid_function_value: "invalid value for function: {{value}}"
+    content_type_undefined: "content_type is not defined!"
+    too_few_arguments: "too few arguments: {{params}}"
+    wrong_argument_count_walk_spec: "wrong number of arguments (one Hash or bucket,tag,keep required)"
+    boolean_type: "invalid_argument {{value}} is not true or false"
+    fixnum_type: "invalid_argument {{value}} must be an integer"
+    error_response: "the riak node responded with an error message code"
+    unresolved_siblings: "this Key contains unresolved siblings, which must first be resolved"
+    empty_content: "key instance cannot be serialized into a protobuf without a valid key name and content"
+

data/lib/riak/riak_content.rb

@@ -0,0 +1,219 @@
+require 'riak'
+require 'set'
+
+module Riak
+  # Parent class of all object types supported by ripple. {Riak::RObject} represents
+  # the data and metadata stored in a bucket/key pair in the Riak database.
+  class RiakContent
+    include Util::Translation
+    include Util::MessageCode
+
+    # @return [Key] the key in which this RiakContent is stored.
+    attr_accessor   :key
+
+    # @return [String] the data stored in Riak at this object's key.  Varies in format by content-type.
+    attr_accessor   :value
+    alias_attribute :data, :value
+
+    # @return [String] the MIME content type of the object
+    attr_accessor   :content_type
+
+    # @return [String] the charset of the object
+    attr_accessor   :charset
+
+    # @return [String] the content encoding of the object
+    attr_accessor   :content_encoding
+
+    # @return [String] the vtag of the object
+    attr_accessor   :vtag
+
+    # @return [Set<Link>] an Set of {Riak::Link} objects for relationships between this object and other resources
+    attr_accessor   :links
+
+    # @return [Time] the Last-Modified header from the most recent HTTP response, useful for caching and reloading
+    attr_accessor   :last_mod
+    alias_attribute :last_modified, :last_mod
+
+    # @return [Time] the Last-Modified header from the most recent HTTP response, useful for caching and reloading
+    attr_accessor   :last_mod_usecs
+    alias_attribute :last_modified_usecs, :last_mod_usecs
+
+    # @return [Hash] a hash of any user-supplied metadata, consisting of a key/value pair
+    attr_accessor   :usermeta
+    alias_attribute :meta, :usermeta
+
+    # Create a new riak_content object manually
+    # @param [Riak::Key] key Key instance that owns this RiakContent (really, you should use the Key to get this)
+    # @param [Hash] contents Any contents to initialize this instance with
+    # @see Key#content
+    # @see RiakContent#load
+    def initialize(key, contents={})
+      @key              = key unless key.nil?
+      @links            = Hash.new{|k,v| k[v] = []}
+      @_links           = []
+      @usermeta         = {}
+
+      load(contents) unless contents.empty?
+
+      yield self if block_given?
+    end
+
+    # Load information for the content from the response object, Riak::RpbContent.
+    #
+    # @param [RpbContent/Hash] contents an RpbContent object or a Hash.
+    # @return [RiakContent] self
+    def load(contents)
+      if contents.is_a?(Riak::RpbContent) or contents.is_a?(Hash)
+        @content_type     = contents[:content_type]     unless contents[:content_type].blank?
+        @charset          = contents[:charset]          unless contents[:charset].blank?
+        @content_encoding = contents[:content_encoding] unless contents[:content_encoding].blank?
+        @vtag             = contents[:vtag]             unless contents[:vtag].blank?
+        self.links        = contents[:links]            unless contents[:links].blank?
+        @last_mod         = contents[:last_mod]
+        @last_mod_usecs   = contents[:last_mod_usecs]
+        self.usermeta     = contents[:usermeta]         unless contents[:usermeta].blank?
+
+        unless contents[:value].blank?
+          case @content_type
+          when /json/
+            @value = ActiveSupport::JSON.decode(contents[:value]) 
+          when /octet/
+            @value = Marshal.load(contents[:value])
+          else
+            @value = contents[:value]
+          end
+        end
+
+        return(self)
+      end
+
+      raise ArgumentError, t("riak_content_type")
+    end
+
+    # Save the RiakContent instance in riak.
+    # @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 [true/false] return_body whether or not to have riak return the key, once saved.  default = true
+    def save(options={})
+      begin
+        save!(options)
+      rescue FailedRequest
+        return(false)
+      end
+      return(true)
+    end
+
+    # Save the RiakContent instance in riak.  Raise/do not rescue on failure.
+    # @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 [true/false] return_body whether or not to have riak return the key, once saved.  default = true
+    def save!(options={})
+      options[:content] = self
+      return(true) if @key.save(options)
+      return(false) # Create and raise Error message for this?  Extend "Failed Request"?
+    end
+
+    # Internalizes a link to a Key, which will be saved on next call to... uh, save
+    # @param [Hash] tags name of the tag, pointing to a Key instance, or an array ["bucket", "key"]
+    # @return [Hash] links that this RiakContent points to
+    def link_key(tags)
+      raise TypeError.new t('invalid_tag') unless tag.is_a?(Hash)
+      tags.each do |tag, link|
+        case link
+        when Array
+          bucket            ||= link[0]
+          key               ||= link[1]
+          raise TypeError.new t('invalid_tag') if bucket.nil? or key.nil?
+
+          get_link          ||= @key.get_linked(bucket, key, {:safely => true})
+          raise RuntimeError.new t('invalid_key') if get_link.nil?
+
+          @links[tag.to_s]  <<  get_link
+
+        when Riak::Key
+          @links[tag.to_s] << link
+
+        else
+          raise TypeError.new t('invalid_tag')
+        end
+      end # tags.each do |tag, link|
+    end
+
+    # Set the links to other Key in riak.
+    # @param [RpbGetResp, RpbPutResp] contains the tag/bucket/key of a given link
+    # @return [Set] links that this RiakContent points to
+    def links=(pb_links)
+      @links.clear
+
+      pb_links.each do |pb_link|
+        @links[pb_link.tag] << @key.get_linked(pb_link.bucket, pb_link.key, {:safely => true})
+      end
+
+      return(@links)
+    end
+
+    # @return [Riak::RpbContent] An instance of a RpbContent, suitable for protobuf exchange
+    def to_pb
+      raise TypeError.new t('value_empty') if @value.nil?
+
+      rpb_content                   = Riak::RpbContent.new
+
+      links                         = []
+      @links.each do |link|
+        pb_link       = link[1].to_pb_link
+        pb_link[:tag] = link[0]
+        links << pb_link
+      end
+
+      usermeta                      = []
+      @usermeta.each do |key,value|
+        pb_pair         =   Riak::RpbPair.new
+        pb_pair[:key]   =   key
+        pb_pair[:value] =   value
+        usermeta        <<  pb_pair
+      end
+
+      catch(:redo) do
+        case @content_type
+        when /octet/
+          rpb_content.value = Marshal.dump(@value)
+        when /json/
+          rpb_content.value = ActiveSupport::JSON.encode(@value)
+        when "", nil
+          @content_type     = "application/json"
+          redo
+        else
+          rpb_content.value = @value.to_s
+        end
+      end
+
+      rpb_content.content_type      = @content_type     unless @content_type.nil?
+      rpb_content.charset           = @charset          unless @charset.nil? # || @charset.empty?
+      rpb_content.content_encoding  = @content_encoding unless @content_encoding.nil? # || @content_encoding.empty?
+      rpb_content.vtag              = @vtag             unless @vtag.nil?
+      rpb_content.links             = links             unless links.empty?
+      rpb_content.usermeta          = usermeta          unless usermeta.empty?
+
+      return(rpb_content)
+    end
+
+    # @return [String] A representation suitable for IRB and debugging output
+    def inspect
+      "#<#Riak::RiakContent " + [
+          (@value.nil?)             ? nil : "value=#{@value.inspect}",
+          (@content_type.nil?)      ? nil : "content_type=#{@content_type.inspect}",
+          (@charset.nil?)           ? nil : "charset=#{@charset.inspect}",
+          (@content_encoding.nil?)  ? nil : "content_encoding=#{@content_encoding.inspect}",
+          (@vtag.nil?)              ? nil : "vtag=#{@vtag.inspect}",
+          (@links.nil?)             ? nil : "links=#{@_links.inspect}",
+          (@last_mod.nil?)          ? nil : "last_mod=#{last_mod.inspect}",
+          (@last_mod_usecs.nil?)    ? nil : "last_mod_usecs=#{last_mod_usecs.inspect}",
+          (@usermeta.nil?)          ? nil : "usermeta=#{@usermeta.inspect}"
+
+        ].compact.join(", ") + ">"
+    end
+
+    private
+
+  end # class RiakContent
+end # module Riak

data/lib/riak/sibling_error.rb

@@ -0,0 +1,16 @@
+require 'riak'
+
+module Riak
+  # Exception raised when the expected response code from Riak
+  # fails to match the actual response code.
+  class SiblingError < StandardError
+    include Riak::Util::Translation
+
+    attr_reader :key
+
+    def initialize(key)
+      @key = key
+      super t("unresolved_siblings", :key => @key)
+    end
+  end
+end

data/lib/riak/util/decode.rb

@@ -0,0 +1,37 @@
+require 'riak'
+
+module Riak
+  module Util
+
+    module Decode
+      PLEN  = (0..3)
+      PBMC  = PLEN.count
+      POFF  = (PBMC+1)
+
+      def decode_message(message)
+        pb_len  = 0
+        pb_mc   = ''
+        pb_msg  = ''
+
+        until message.empty?
+          pb_len  = message[PLEN].unpack('N')[0]    # message[0..3]unpack('N')[0]
+          pb_mc   = pb_mc + message[PBMC]           # prior message codes + message[4]
+
+          prange  = POFF..(pb_len+3)                # range for the start->finish of the pb message
+          mrange  = (pb_len+4)..(message.size-1)    # range for any remaining portions of message
+
+          if(prange.count != message[prange].size)
+            raise FailedExchange.new(prange.count, message[prange].size, message[prange], "decode_error")
+          end
+
+          pb_msg  = pb_msg + message[prange]
+          message = message[mrange]      # message[(5+pb_len)..(message.size)]
+        end
+
+        [pb_msg, pb_mc.unpack("c" * pb_mc.size)]
+      end
+
+    end # module Decode
+  end
+end
+

data/lib/riak/util/encode.rb

@@ -0,0 +1,31 @@
+require 'riak'
+
+module Riak
+  module Util
+    
+    module Encode
+      
+      # Construct a Request Message for Riak, which adheres to the following structure:
+      #
+      #   00 00 00 07 09 0A 01 62 12 01 6B
+      #   |----Len---|MC|----Message-----|
+      #
+      # @raise [TypeError] if an invalid hostname is given
+      # @return [String] the assigned hostname
+      def assemble_request(mc, msg='')
+        raise TypeError, t("message_code_invalid")  unless mc.is_a?(Fixnum)
+        raise TypeError, t("pb_message_invalid")    unless msg.is_a?(String)
+        
+        encode_message mc, msg
+      end
+      
+      def encode_message(mc, msg='')
+        message = [mc].pack('c') + msg
+        
+        message = [message.size].pack('N') + message
+      end
+
+    end
+  end
+end
+