blodsband 0.0.2

data/lib/blodsband.rb

@@ -0,0 +1,27 @@
+
+require 'uri'
+require 'em-synchrony'
+require 'em-synchrony/em-http'
+require 'em-http/middleware/json_response'
+require 'yajl'
+require 'mail'
+require 'date'
+require 'cgi'
+require 'rexml/document'
+require 'digest/sha1'
+
+$LOAD_PATH.unshift(File.expand_path('lib'))
+
+require 'blodsband/future'
+require 'blodsband/multi'
+require 'blodsband/error'
+require 'blodsband/riak'
+require 'blodsband/riak/mr'
+require 'blodsband/riak/response'
+require 'blodsband/riak/lock'
+require 'blodsband/riak/list'
+require 'blodsband/riak/map'
+require 'blodsband/riak/sset'
+require 'blodsband/riak/bucket'
+require 'blodsband/riak/counter'
+require 'blodsband/riak/search'

data/lib/blodsband/error.rb

@@ -0,0 +1,18 @@
+
+module Blodsband
+  
+  #
+  # A class that collects a single HTTP based error.
+  #
+  class Error < RuntimeError
+    attr_reader :response, :status
+    def initialize(http)
+      @status = http.response_header.status
+      @response = http.response
+    end
+    def to_s
+      "#{@response}: #{@status}"
+    end
+  end
+
+end

data/lib/blodsband/future.rb

@@ -0,0 +1,31 @@
+
+module Blodsband
+
+  #
+  # A class that encapsulates an asynchronous operation.
+  #
+  # Used to avoid the callback carbonara usually produced when relying heavily on asynchronous code.
+  #
+  class Future
+
+    #
+    # Create a future that will run a block upon request.
+    #
+    # @param [block] block the block to run when {#get} is called.
+    #
+    def initialize(&block)
+      @block = block
+    end
+
+    #
+    # Get the result from the asynchronous operation.
+    #
+    # @return [Object] whatever the block given in {#initialize} produced.
+    #
+    def get
+      @value ||= @block.call
+    end
+    
+  end
+
+end

data/lib/blodsband/multi.rb

@@ -0,0 +1,37 @@
+
+module Blodsband
+
+  class Multi < EM::Synchrony::Multi
+
+    #
+    # An error that collects all errors in a single {Blodsband::Multi} and renders them in a readable way.
+    #
+    class Error < RuntimeError
+      def initialize(multi)
+        @bad = {}
+        @bad.merge!(multi.responses[:errback])
+	multi.responses[:callback].each do |key, value|
+          @bad[key] = value unless [200,204].include?(value.response_header.status)
+	end
+      end
+      def to_s
+        @bad.values.inject([]) do |sum, http|
+          if http.response_header.status == 0
+            sum + ["Connection timed out: #{http.req.uri}"]
+          else
+            sum + ["#{http.response_header.status}: #{http.response}"]
+          end
+        end.join("\n")
+      end
+    end
+    
+    #
+    # Does exactly what {::EventMachine::Synchrony::Multi} does, but keeps waiting until it is really REALLY finished (and not just until it just happens to get scheduled again).
+    #
+    def really_perform
+      perform while !finished?
+    end
+
+  end
+
+end

data/lib/blodsband/riak.rb

@@ -0,0 +1,48 @@
+module Blodsband
+
+  class Riak
+
+    #
+    # Initialize a Riak client.
+    #
+    # @param [URI] url a url pointing to the HTML port of a Riak node.
+    #
+    def initialize(url)
+      @url = url
+    end
+    
+    #
+    # Get a {Blodsband::Riak::Bucket}.
+    #
+    # @param [String] name see {Blodsband::Riak::Bucket#initialize}
+    # @param [Hash] options see {Blodsband::Riak::Bucket#initialize}
+    #
+    # @return [Blodsband::Riak::Bucket] a Bucket with the provided configuration and the {::URI} of this {Blodsband::Riak}.
+    #
+    def bucket(name, options = {})
+      Bucket.new(@url, name, options)
+    end
+
+    #
+    # Get a {Blodsband::Riak::Search}
+    #
+    # @param [URI] url a url pointing to the HTML port of a Riak node.
+    #
+    # @return [Blodsband::Riak::Search] a search instance initialized with the {::URI} of this {Blodsband::Riak}.
+    #
+    def search
+      Search.new(@url)
+    end
+
+    #
+    # Get a map/reduce helper instance.
+    #
+    # @return [Blodsband::Riak::Mr] a {Blodsband::Riak::Mr} with the {::URI} of this {Blodsband::Riak}.
+    #
+    def mr
+      Mr.new(@url)
+    end
+
+  end
+
+end

data/lib/blodsband/riak/bucket.rb

@@ -0,0 +1,1169 @@
+
+module Blodsband
+
+  class Riak
+
+    #
+    # Encapsulates functionality of Riak buckets.
+    #
+    class Bucket
+
+      #
+      # [String] The name of the Riak bucket this {Blodsband::Riak::Bucket} refers to.
+      #
+      attr_reader :name
+      #
+      # [Hash<Symbol, Object>] The default options for this {Blodsband::Riak::Bucket}
+      #  
+      attr_reader :defaults
+
+      #
+      # Create a {Blodsband::Riak::Bucket}.
+      #
+      # @param [::URI] url a url pointing to the HTML port of a Riak node.
+      # @param [String] name the name of the bucket.
+      # @param [Hash<Symbol, Object>] options
+      #  :client_id:: [String] <code>client_id</code> to use when communicating with Riak. Will default to a random 256 bit string.
+      #  :unique:: [true, false] if this bucket should always default to <code>:unique => true</code> when doing {Blodsband::Riak::Bucket#get}. Will default to <code>false</code>.
+      #
+      def initialize(url, name, options = {})
+        @url = url
+        @name = name
+        @defaults = options.merge(:client_id => rand(1 << 256).to_s(36))
+        raise "Unknown options to #{self.class}#initialize: #{options}" unless options.empty?
+      end
+
+      #
+      # Sets the {Blodsband::Riak::Bucket} property <code>:allow_mult</code> to <code>true</code>
+      # and the default option <code>:unique</code> to <code>true</code>.
+      #
+      # @return [Blodsband::Riak::Bucket] this same bucket with the new options set.
+      #
+      def unique
+        @defaults[:unique] = true
+        self.props = {:allow_mult => true}
+        self
+      end
+
+      #
+      # Sets the {Blodsband::Riak::Bucket} property <code>:search</code> to <code>true</code>.
+      #
+      # @return [Blodsband::Riak::Bucket] this same bucket.
+      #
+      def indexed
+        self.props = {:search => true}
+        self
+      end
+
+      #
+      # @return [Hash<Symbol, Object>] the properties of this Riak bucket.
+      #
+      def props
+        Yajl::Parser.parse(EM::HttpRequest.new(uri).get.response)['props']
+      end
+
+      #
+      # Sets the properties of this Riak bucket.
+      # Will merge in the given properties with the existing ones, so a complete property {::Hash} is not necessary.
+      #
+      # @param [Hash<Symbol, Object>] p the new properties.
+      #
+      def props=(p)
+        EM::HttpRequest.new(uri).put(:head => {"Content-Type" => "application/json"},
+                                     :body => Yajl::Encoder.encode(:props => p))
+      end
+
+      #
+      # {include:Bucket#delete}
+      #
+      # @param (see #delete)
+      #
+      # @return [Blodsband::Future<Blodsband::Riak::Response>] the eventual response from Riak for the resulting HTTP request.
+      #
+      def adelete(key, options = {})
+        riak_params = options.delete(:riak_params)
+        m = Multi.new
+        url = uri(key)
+        url += "?#{riak_params.collect do |k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" end.join("&")}" if riak_params
+        m.add(:resp, EM::HttpRequest.new(url).adelete)
+        return(Future.new do
+                 m.really_perform
+                 Response.parse(m)
+               end)
+      end
+
+      #
+      # Delete a key in Riak.
+      #
+      # @param [String] key the key to delete.
+      # @param [Hash<Symbol, Object>] options
+      #  :riak_params:: [Hash<String, String>] <code>param_name => param_value</code> of extra parameters to send to Riak when doing the HTTP request.
+      #
+      # @return [Blodsband::Riak::Response] the response from Riak for the resulting HTTP request.
+      #
+      def delete(key, options = {})
+        adelete(key, options).get
+      end
+
+      #
+      # {include:Bucket#put}
+      #
+      # @param [String] key the key to put the value under.
+      # @param [Object] value the value to put under the key.
+      #
+      # @return [Blodsband::Riak::Response] the response from Riak for the resulting HTTP request.
+      #
+      def []=(key, value)
+        self.put(key, value)
+      end
+
+      #
+      # {include:Bucket#put}
+      #
+      # @param (see #put)
+      #
+      # @return [Blodsband::Future<Blodsband::Riak::Response>] the eventual response from Riak for the resulting HTTP request.
+      #
+      def aput(key, value, options = {})
+        links = value.links if value.respond_to?(:links)
+        links = (links || {}).merge(options.delete(:links)) if options.include?(:links)
+        
+        index_rels = value.index_rels if value.respond_to?(:index_rels)
+        index_rels = (index_rels || {}).merge(options.delete(:index_rels)) if options.include?(:index_rels)
+        
+        riak_params = options.delete(:riak_params)
+
+        vclock = value.vclock if value.respond_to?(:vclock)
+        vclock = options.delete(:vclock) if options.include?(:vclock)
+
+        client_id = options.delete(:client_id) || @defaults[:client_id]
+
+        meta = value.meta if value.respond_to?(:meta)
+        meta = (meta || {}).merge(options.delete(:meta)) if options.include?(:meta)
+        meta ||= {}
+
+        raise "Unknown options to #{self.class}#put(#{key}, #{value}, ...): #{options.inspect}" unless options.empty?
+        head = {
+          "Content-Type" => "application/json",
+          "Accept" => "multipart/mixed, application/json"
+        }
+        meta.each do |k, v|
+          head["X-Riak-Meta-#{k}"] = v.to_s
+        end
+        head["X-Riak-ClientId"] = client_id if client_id
+        head["Link"] = create_link_header(links) if links
+        head["X-Riak-Vclock"] = vclock if vclock
+        index_rel_futures = []
+        if index_rels
+          index_rels.each do |names, relations|
+            relations.each do |rel|
+              index_rel_futures << aadd_index_rel(key, names, rel)
+            end
+          end
+        end
+        url = uri(key)
+        url += "?#{riak_params.collect do |k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" end.join("&")}" if riak_params
+        m = Multi.new
+        m.add(:resp, 
+              EM::HttpRequest.new(url).apost(:body => Yajl::Encoder.encode(value),
+                                             :head => head))
+        return(Future.new do
+                 m.really_perform
+                 index_rel_futures.each do |f|
+                   f.get
+                 end
+                 Response.parse(m, :bucket => @name, :key => key)
+               end)
+      end
+
+      #
+      # Put a value in Riak.
+      # 
+      # @param [String] key the key to put the value under.
+      # @param [Object] value the value to insert under the key. If this {::Object} responds to <code>:vclock</code>, <code>:links</code>, <code>:index_rels</code> or <code>:meta</code> the return values from those methods will be used as options in the resulting {#put}.
+      # @param [Hash<Symbol, Object>] options
+      #  :links:: [Hash<Symbol, Array<Array<String, String>>>] <code>tagname => [[bucket, key], [bucket, key], ...]</code>. Will default to the <code>#links</code> of the <code>value</code> if available.
+      #  :index_rels:: [Hash<Array<Symbol, Symbol>, Array<Array<String, String>>>] <code>[i_am_to_relation, relation_is_to_me] => [[bucket, key], [bucket, key], ...]</code>. Example: <code>bucket.put(artist.key, artist, :links_rels => {[:artists, :tracks] => artist.track_refs})</code>. Will default to the <code>#index_rels</code> of the <code>value</code> if available.
+      #  :riak_params:: [Hash<String, String>] <code>param_name => param_value</code> of extra parameters to send to Riak when doing the HTTP request.
+      #  :vclock:: [String] the <code>vclock</code> returned when the object was originally fetched. Will default to the <code>#vclock</code> of the <code>value</code> if available.
+      #  :client_id:: [String] the <code>client_id</code> to use when communicating with Riak. Will default to the <code>client_id</code> of the {Blodsband::Riak::Bucket}.
+      #  :meta:: [Hash<String, String>] <code>meta_name => meta_value</code> of Riak meta data to save with the object, that will be returned when fetching the <code>value</code> next time. Will default to the <code>#meta</code> of the <code>value</code> if available.
+      #
+      # @return [Blodsband::Riak::Response] the response from riak for the resulting HTTP request.
+      # 
+      def put(key, value, options = {})
+        aput(key, value, options).get
+      end
+
+      #
+      # Fetch a value from Riak.
+      #
+      # @param [String] key the key for the value.
+      #
+      # @return [Blodsband::Riak::Response] the response from Riak for the resulting HTTP request (which will also be ie a {::String} or a {::Hash}.
+      #
+      def [](key)
+        self.get(key)
+      end
+
+      #
+      # Efficiently check what keys correspond to existing values in Riak.
+      #
+      # @param [Array<String>] keys an {::Array} of {::String} containing the keys for which to check if values exist.
+      #
+      # @return [Set<String>] the keys having values.
+      #
+      def has_many?(keys)
+        ahas_many?(keys).get
+      end
+
+      #
+      # {include:Bucket#has_many?}
+      #
+      # @param (see #has_many?)
+      #
+      # @return [Blodsband::Future<Set<String>>] a Set eventually containing the keys for which values exist.
+      #
+      def ahas_many?(keys)
+        future = Mr.new(@url).
+          inputs(keys.collect do |key| [@name, key] end).
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  if (v.values != null) {
+    return [v];
+  } else {
+    return [];
+  }
+}
+EOF
+              }).
+          reduce({
+                   :keep => true,
+                   :language => "javascript",
+                   :source => <<EOF
+function(v) {
+  rval = [];
+  for (var i = 0; i < v.length; i++) {
+    if (v[i].values != null) {
+      rval.push(v[i].key);
+    }
+  }
+  return rval;
+}
+EOF
+                 }).arun
+        return(Future.new do
+                 Set.new(future.get)
+               end)
+      end
+
+      #
+      # Efficiently fetch values for many keys in Riak.
+      #
+      # @param [Array] keys an {::Array} of {::String} containing the keys for which to fetch the values.
+      #
+      # @return [Array<Blodsband::Riak::Response>] the response from Riak for the resulting HTTP request (which will also be ie a {::String}s or a {::Hash}es.
+      #
+      def get_many(keys)
+        aget_many(keys).get
+      end
+
+      #
+      # {include:Bucket#get_many}
+      #
+      # @param (see #get_many)
+      #
+      # @return [Blodsband::Future<Array<Blodsband::Riak::Response>>] the eventual response from Riak for the resulting HTTP request (which will also be ie a {::String}s or a {::Hash}es.
+      #
+      def aget_many(keys)
+        Mr.new(@url).
+          inputs(keys.collect do |key| [@name, key] end).
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  if (v.values != null) {
+    return [v];
+  } else {
+    return [];
+  }
+}
+EOF
+              }).
+          reduce({
+                   :keep => true,
+                   :language => "javascript",
+                   :source => <<EOF
+function(v) {
+  rval = [];
+  for (var i = 0; i < v.length; i++) {
+    if (v[i].values != null) {
+      rval.push(JSON.parse(v[i].values[0].data));
+    }
+  }
+  return rval;
+}
+EOF
+                 }).arun
+      end
+
+      #
+      # {include:Bucket#get}
+      #
+      # @param (see #get)
+      #
+      # @return [Blodsband::Future<Blodsband::Riak::Response>] the eventual response from Riak for the resulting HTTP request (which will also be ie a {::String} or a {::Hash}.
+      #
+      def aget(key, options = {})
+        links = options.delete(:links)
+        index_rels = options.delete(:index_rels)
+        riak_params = options.delete(:riak_params)
+        unique = options.include?(:unique) ? options.delete(:unique) : @defaults[:unique]
+        ary = options.delete(:ary) || @defaults[:ary]
+        raise "Unknown options to #{self.class}#get(#{key}, ...): #{options.inspect}" unless options.empty?
+        u = uri(key)
+        m = Multi.new
+        if links
+          links.each do |linkchain|
+            m.add(linkchain, EM::HttpRequest.new("#{u}#{create_link_walker(linkchain)}").aget)
+          end
+        end
+        mrs = []
+        if index_rels
+          index_rels.each do |names|
+            mrs << aindex_rels(key, names)
+          end
+        end
+        u += "?#{riak_params.collect do |k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" end.join("&")}" if riak_params
+        m.add(:resp, EM::HttpRequest.new(u).aget(:head => {"Accept" => "multipart/mixed, application/json"}))
+        return(Future.new do
+                 m.really_perform
+                 resp = Response.parse(m, :links => links, :bucket => @name, :key => key)
+                 resp = find_winner(key, resp) if unique && resp && resp.status == 300
+                 resp = arify(resp) if ary
+                 rval = resp
+                 if mrs.size > 0
+                   unless resp.is_a?(Hash)
+                     rval = [resp]
+                   end
+                   class << resp
+                     attr_reader :index_rels
+                   end
+                   mrs.each_with_index do |mr, index|
+                     resp.instance_eval do
+                       @index_rels ||= {}
+                       @index_rels[index_rels[index]] = mr.get.collect do |hash| [hash["bucket"], hash["key"]] end
+                     end
+                     if resp.is_a?(Hash)
+                       resp[index_rels[index][1].to_s] = mr.get.collect do |hash| extended_index_rel(hash) end
+                     else
+                       rval << mr.get.collect do |hash| extended_index_rel(hash) end
+                     end
+                   end
+                 end
+                 rval
+               end)
+      end
+
+      #
+      # {include:Bucket#[]}
+      #
+      # @param [String] key the key from which to fetch the value.
+      # @param [Hash<Symbol, Object>] options
+      #  :links:: [Array<Array<String>>] an {::Array} of Riak link chains to fetch for the key. Example: <code>artist.get(key, :links => [["aliases"], ["friends", "friends"]])</code>
+      #  :index_rels:: [Array<Array<Symbol>>] an {::Array} of relationships stored as index relations to fetch for the key. Example: <code>artist.get(key, :index_rels => [[:artists, :tracks], [:artists, :followers]])</code>
+      #  :unique:: [true, false] if <code>true</code>, any siblings returned from Riak will be reduced to one using a method that will return the currently likely winner in an ongoing {#put_if_missing} scenario.
+      #  :ary:: [true, false] if <code>true</code>, will be guaranteed to return an {::Array} containing zero or more values depending on the number of siblings and deleted values.
+      #
+      # @return (see #[])
+      #
+      def get(key, options = {})
+        aget(key, options).get
+      end
+
+      #
+      # Get a concurrent {Blodsband::Riak::Tree} in this {Blodsband::Riak::Bucket}.
+      #
+      # @param [String] key the key for this lock.
+      #
+      # @return [Blodsband::Riak::Lock] a lock supporting concurrent synchronization over a Riak cluster.
+      #
+      def lock(key)
+        return Lock.new(self, key)
+      end
+
+      #
+      # Get a concurrent {Blodsband::Riak::List} in this {Blodsband::Riak::Bucket}.
+      #
+      # @param [String] key the key for this list.
+      #
+      # @return [Blodsband::Riak::List] a list supporting concurrent update and reads.
+      #
+      def list(key)
+        return List.new(self, key)
+      end
+
+      #
+      # Get a concurrent {Blodsband::Riak::Map} in this {Blodsband::Riak::Bucket}.
+      #
+      # @param [String] key the key for this map.
+      #
+      # @return [Blodsband::Riak::Map] a map supporting concurrent updates and reads.
+      #
+      def map(key)
+        return Map.new(self, key)
+      end
+
+      #
+      # Get a concurrent {Blodsband::Riak::Sset} in this {Blodsband::Riak::Bucket}.
+      #
+      # @param [String] key the key for this set.
+      #
+      # @return [Blodsband::Riak::Sset] a set supporting concurrent updates and reads.
+      #
+      def sset(key)
+        return Sset.new(self, key)
+      end
+
+      #
+      # Get a concurrent {Blodsband::Riak::Counter} in this {Blodsband::Riak::Bucket}.
+      #
+      # @param [String] key the key for this counter.
+      #
+      # @return [Blodsband::Riak::Counter] a counter supporting concurrent update and reads.
+      #
+      def counter(key)
+        return Counter.new(self, key)
+      end
+
+      #
+      # Put a value in the bucket if the key is missing.
+      #
+      # @param [String] key the key to put the value under (if it doesn't already exist).
+      # @param [Object] value the value to put under the key (if the key doesn't already exist).
+      # @param [Hash<Symbol, Object>] options
+      #  :client_id:: [String] <code>client_id</code> to use when communicating with Riak for this operation. Will default to the <code>client_id</code> of this {Blodsband::Riak::Bucket}.
+      #
+      # @return [Object] whatever this call succeeded in inserting under <code>key</code>, or <code>nil</code>.
+      #
+      def put_if_missing(key, value, options = {})
+        aput_if_missing(key, value, options).get
+      end
+
+      #
+      # {include:Bucket#put_if_missing}
+      #
+      # @param (see #put_if_missing)
+      #
+      # @return  [Blodsband::Future<Object>] whatever this call eventually succeeded in inserting under <code>key</code>, or <code>nil</code>.
+      #
+      def aput_if_missing(key, value, options = {})
+        acas(key, value, nil, options)
+      end
+
+      #
+      # Compare the value of a key to an expected vclock (or nil) and uniquely set a new value if the
+      # current value matches the expectations.
+      #
+      # @param [String] key the key to look at.
+      # @param [Object] value the value to put under the key.
+      # @param [String] expected_vclock the vclock to replace, or <code>nil</code> if only set if the value is missing.
+      # @param [Hash<Symbol, Object>] options
+      #  :client_id:: [String] <code>client_id</code> to use when communicating with Riak for this operation. Will default to the <code>client_id</code> of this {Blodsband::Riak::Bucket}.
+      #
+      # @return [Object] whatever this call succeeded in inserting under <code>key</code>, or <code>nil</code>.
+      #
+      def cas(key, value, expected_vclock, options = {})
+        acas(key, value, expected_vclock, options).get
+      end
+
+      #
+      # {include:Bucket#cas}
+      #
+      # @param (see #cas)
+      #
+      # @return [Blodsband::Future<Object>] whatever this call eventually succeeded in inserting under <code>key</code>, or <code>nil</code>.
+      #
+      def acas(key, value, expected_vclock, options = {})
+        #
+        # While result is :nothing we will continue working.
+        #
+        result = :nothing
+        #
+        # Remember the fiber that started it all
+        #
+        parent = Fiber.current
+        #
+        # Create a fiber that does our dirty work for us
+        #
+        Fiber.new do
+          post_check_sleep = options.delete(:post_check_sleep)
+          post_write_sleep = options.delete(:post_write_sleep)
+          client_id = @defaults[:client_id] || rand(1 << 256).to_s(36)
+          cas_id = rand(1 << 256).to_s(36)
+
+          current = get(key)
+          sleep(post_check_sleep) if post_check_sleep
+
+          #
+          # While we lack a result
+          #
+          while result == :nothing do
+            if (expected_vclock.nil? && current.nil?) || (current.respond_to?(:vclock) && current.vclock == expected_vclock)
+              #
+              # The current value is what we expected, write our value and repeat with the response
+              #
+              current = put(key, 
+                            value, 
+                            :riak_params => {:w => :all, :returnbody => true}, 
+                            :client_id => client_id,
+                            :vclock => current.respond_to?(:vclock) ? current.vclock : nil,
+                            :meta => {
+                              "cas-state" => "prospect",
+                              "cas-voter" => cas_id,
+                              "cas-id" => cas_id
+                            })
+              sleep(post_write_sleep) if post_write_sleep
+            else
+              #
+              # The current value was not what we expected, check what is the winner.
+              #
+              winner = find_winner(key, current, options.merge(:client_id => client_id,
+                                                               :cas_voter => cas_id))
+              if winner.nil?
+                #
+                # No winner, we tried to overwrite an existing value that didn't exist.
+                #
+                result = nil
+              elsif winner.meta["cas-id"] == cas_id
+                #
+                # We are winners!
+                #
+                result = winner
+              else
+                #
+                # We lost :/
+                #           
+                result = nil
+              end
+            end
+          end
+          #
+          # Resume the parent if necessary.
+          #
+          parent.resume if parent.alive? && parent != Fiber.current
+        end.resume
+        return(Future.new do
+                 rval = nil
+                 Fiber.yield while result == :nothing
+                 result
+               end)
+      end
+
+      #
+      # {include:Bucket#delete_index_rel}
+      #
+      # @param (see #delete_index_rel)
+      #
+      # @return [Blodsband::Future<Blodsband::Riak::Response>] the eventual response from Riak for the resulting HTTP request (which will also be ie a {::String} or a {::Hash}.
+      #
+      def adelete_index_rel(key, names, rel) 
+        Bucket.new(@url, names.sort.join("-")).adelete(index_rel_key(key, names, rel))
+      end
+
+      #
+      # Remove an index stored relation from Riak.
+      #
+      # @param [String] key the key from which to remove the relation.
+      # @param [Array<Symbol, Symbol>] names the specification of the relationship type from which to remove a relation.
+      # @param [Array<String, String>] rel the bucket and key to remove from the relationship type.
+      #
+      # @return [Blodsband::Riak::Response] the eventual response from Riak for the resulting HTTP request (which will also be ie a {::String} or a {::Hash}.
+      #
+      def delete_index_rel(key, names, rel)
+        adelete_index_rel(key, names, rel).get
+      end
+
+      #
+      # {include:Bucket#add_index_rel}
+      #
+      # @note (see #add_index_rel)
+      #
+      # @param (see #add_index_rel)
+      #
+      # @return [Blodsband::Riak::Future<Blodsband::Riak::Response>] the eventual response from Riak for the resulting HTTP request.
+      #
+      def aadd_index_rel(key, names, rel)
+        Bucket.new(@url, names.sort.join("-")).aput(index_rel_key(key, names, rel), index_rel_document(names, key, rel))
+      end
+
+      #
+      # Add an index stored relation to Riak.
+      #
+      # Right now this has proven meaningful up to relation sizes of about 10000 due to Riak Search limitations
+      # when it comes to how it counts and fetches documents. After that a clear linear scaling is observable.
+      #
+      # @note The <code>rel</code> parameter can have a {::Hash} as a third element containing extra 
+      #       attributes for the relationship. These attributes will be stored in the relationship document
+      #       and can be used to filter queries on this relationship type. This is also usable from the {#put}
+      #       method and will have the same effect there.
+      #
+      # @param [String] key the key for which to add the relation.
+      # @param [Array<Symbol, Symbol>] names the specification of the relationship type for which to add a relation.
+      # @param [Array<String, String>] rel the bucket and key to add to the relationship type.
+      #
+      # @return [Blodsband::Riak::Response] the response from Riak for the resulting HTTP request.
+      #
+      def add_index_rel(key, names, rel)
+        aadd_index_rel(key, names, rel).get
+      end
+
+      #
+      # {include:Bucket#count_index_rels}
+      #
+      # @note (see #add_index_rel)
+      #
+      # @param (see #count_index_rels)
+      #
+      # @return [Blodsband::Future<Integer>] the number of matching relations eventually returned.
+      #
+      def acount_index_rels(key, names)
+        future = Search.new(@url).asearch(create_search_expression(key, names), :index => names.sort.join("-"), :page => 1, :per_page => 1)
+        return(Future.new do
+                 future.get[:total]
+               end)
+      end
+
+      #
+      # Count the number of relations of a given type.
+      #
+      # @note (see #add_index_rel)
+      #
+      # @param [String] key the key for which to count relations.
+      # @param [Array<Symbol, Symbol>] names the specification of the relationship type to count.
+      #
+      # @return [Integer] the number of matching relations.
+      #
+      def count_index_rels(key, names)
+        acount_index_rels(key, names).get
+      end
+
+      #
+      # {include:Bucket#has_index_rel?}
+      #
+      # @param (see #has_index_rel?)
+      #
+      # @return [Blodsband::Future<true,false>] the eventual response to whether the relation exists.
+      #
+      def ahas_index_rel?(key, names, rel)
+        future = Bucket.new(@url, names.sort.join("-")).aget(index_rel_key(key, names, rel))
+        return(Future.new do
+                 !future.get.nil?
+               end)
+      end
+
+      #
+      # Check whether a given relation exists.
+      #
+      # @param [String] key the key for which to check the relations.
+      # @param [Array<Symbol, Symbol>] names the specification of the relationship type in which to search.
+      # @param [Array<String, String>] rel the bucket and key to check if it exists in the relation type.
+      #
+      # @return [true, false] whether the relation exists.
+      #      
+      def has_index_rel?(key, names, rel)
+        ahas_index_rel?(key, names, rel).get
+      end
+
+      #
+      # {include:Bucket#index_rels}
+      #
+      # @note (see #index_rels)
+      #
+      # @param (see #index_rels)
+      #
+      # @return [Blodsband::Riak::Future<Array<Blodsband::Riak::Response>>] a future containing an {::Array} containing the eventually retrieved {Blodsband::Riak::Response}s stored in the index as these relations.
+      #
+      def aindex_rels(key, names)
+        index_rel_mr(key, names).arun
+      end
+      
+      #
+      # {include:Bucket#recip_index_rels}
+      #
+      # @note (see #index_rels)
+      #
+      # @param (see #index_rels)
+      #
+      # @return [Blodsband::Riak::Future<Array<Blodsband::Riak::Response>>] a future containing an {::Array} containing the retrieved {Blodsband::Riak:Response}s stored in the index as these relations.
+      #
+      def arecip_index_rels(key, names)
+        recip_index_rel_mr(key, names).arun
+      end
+
+      #
+      # Retrieve a set of relations having the same relation to us as we to them.
+      #
+      # @note (see #index_rels)
+      #
+      # @param [String] key the key to which the relations are connected.
+      # @param [Array<Symbol, Symbol>] names the specification of the relationship type to fetch.
+      #
+      # @return [Array<Blodsband::Riak::Response>] an {::Array} containing the retrieved {Blodsband::Riak:Response}s stored in the index as these relations.
+      #
+      def recip_index_rels(key, names)
+        arecip_index_rels(key, names).get
+      end
+
+      #
+      # Retrieve a set of relations stored in the Riak index.
+      #
+      # @note The <code>names</code> parameter can have a {::Hash} as third element containing a filter definition
+      #       <code>:field => :required_value</code> that will be used to filter the relations returned. This
+      #       is also usable from the {#get} method and will have the same effect there.
+      #
+      # @param [String] key the key to which the relations are connected.
+      # @param [Array<Symbol, Symbol>] names the specification of the relationship type to fetch.
+      #
+      # @return [Array<Blodsband::Riak::Response>] a future containing an {::Array} containing the retrieved {Blodsband::Riak::Response}s stored in the index as these relations.
+      #
+      def index_rels(key, names)
+        aindex_rels(key, names).get
+      end
+
+      private
+
+      def arify(resp)
+        if resp.nil?
+          []
+        elsif resp.status == 300
+          resp.compact!
+          resp
+        else
+          resp.copy_to([resp])
+        end
+      end
+
+      def vote_winner(current)
+        if current.status == 300
+          #
+          # Multiple alternatives
+          #
+          winner = nil
+          current.compact.each do |alternative|
+            #
+            # Find the one already considered a winner, OR the one with the highest cas-id and cas-voter
+            #
+            if winner.nil?
+              winner = alternative
+            elsif winner.meta["cas-state"] != "winner"
+              if (alternative.meta["cas-state"] == "winner" ||
+                  alternative.meta["cas-id"].to_s > winner.meta["cas-id"].to_s ||
+                  (alternative.meta["cas-id"].to_s == winner.meta["cas-id"].to_s && 
+                   alternative.meta["cas-voter"].to_s > winner.meta["cas-voter"].to_s))
+                winner = alternative
+              end
+            end
+          end
+          #
+          # Make the winner look like it came directly from a #get
+          #
+          current.copy_to(winner, :except => [:status])
+        else
+          current
+        end
+      end    
+
+      def find_winner(key, current, options = {})
+        client_id = options.delete(:client_id) || @defaults[:client_id]
+        cas_voter = options.delete(:cas_voter)
+        post_check_sleep = options.delete(:post_check_sleep)
+        post_write_sleep = options.delete(:post_write_sleep)
+        unique_wait_threshold = options.delete(:unique_wait_threshold) || @defaults[:unique_wait_threshold] || 3
+        raise "Unknown options to #{self}.find_winner(...): #{options.inspect}" unless options.empty?
+        #STDERR.puts("#{$$} setting read without to 0 from #{caller.join("\n")}")
+        reads_without_winner = 0
+        
+        cas_id = nil
+        result = :nothing
+        while result == :nothing
+          if current.nil?
+            #
+            # If there is no document, then the empty document is the winner
+            #
+            result = nil
+          else
+            #STDERR.puts("#{$$} trying to find a winner among #{current.inspect}")
+            status = current.status
+            winner = vote_winner(current)
+            if winner.meta["cas-state"] == "winner"
+              #
+              # If the winner is already marked as winner.
+              #
+              if cas_voter == winner.meta["cas-voter"]
+                #
+                # If the winner has our cas_voter.
+                #
+                if status == 300
+                  #
+                  # If this was a winner in a sibling horde, overwrite the sibling horde with the winner.
+                  #
+                  #STDERR.puts("#{$$} #{winner.inspect} was our winner, but it's not alone so overwriting the sibling horde")
+                  current = put(key, 
+                                winner, 
+                                :riak_params => {:w => :all, :returnbody => true}, 
+                                :client_id => client_id)
+                  sleep(post_write_sleep) if post_write_sleep
+                else
+                  #
+                  # Else just set result as current winner.
+                  #
+                  result = winner
+                end
+              else
+                #
+                # If the winner doesn't have our cas_voter, just set it as the result.
+                #
+                result = winner
+              end
+            else
+              if cas_voter.nil?
+                #
+                # If we have not yet voted.
+                #
+                if reads_without_winner < unique_wait_threshold
+                  #
+                  # If we still have patience.
+                  #
+                  #STDERR.puts("#{$$} has only tried to re-read #{reads_without_winner} times, hanging on")
+                  EM::Synchrony.sleep(0.1)
+                  current = get(key, :unique => false)
+                  reads_without_winner += 1
+                else
+                  #
+                  # We need to DO something! Lets select this winner as our own and write it, 
+                  # and see what happens.
+                  #
+                  cas_voter = rand(1 << 256).to_s(36)
+                  winner.meta["cas-voter"] = cas_voter
+                  #STDERR.puts("#{$$} we have no horse, selecting #{winner.inspect}")
+                  current = put(key,
+                                winner,
+                                :riak_params => {:w => :all, :returnbody => true},
+                                :client_id => client_id)
+                end
+              else
+                if status == 300
+                  #
+                  # We got multiple results
+                  #
+                  if cas_voter == winner.meta["cas-voter"]
+                    #
+                    # The winner has our cas_voter, try to replace the horde with the winner
+                    #
+                    #STDERR.puts("#{$$} #{winner} was our winner, but unmarked and in a horde. overwriting siblings")
+                    current = put(key,
+                                  winner,
+                                  :riak_params => {:w => :all, :returnbody => true},
+                                  :client_id => client_id)
+                  else
+                    #
+                    # The winner doesn't have our cas_voter, but it is still there after we made at least one write,
+                    # so just give up and accept it as a winner.
+                    #
+                    result = winner
+                  end
+                else
+                  #
+                  # We only got one result after at least one write.
+                  #
+                  if cas_voter == winner.meta["cas-voter"]
+                    #
+                    # It has our cas_voter, so lets mark it as a winner.
+                    #
+                    winner.meta["cas-state"] = "winner"
+                    #STDERR.puts("#{$$} #{winner} was our winner, but unmarked. marking it")
+                    current = put(key,
+                                  winner,
+                                  :riak_params => {:w => :all, :returnbody => true},
+                                  :client_id => client_id)
+                  else
+                    #
+                    # It doesn't have our id. Lets just set it as the result.
+                    #
+                    result = winner
+                  end
+                end
+              end
+            end
+          end
+        end
+        #STDERR.puts("#{$$} returning #{result.inspect}")
+        result
+      end
+
+      def create_link_walker(ary)
+        if ary.nil?
+          ""
+        else
+          rval = []
+          ary.each do |link|
+            rval << "_,#{link},1"
+          end
+          "/#{rval.join("/")}"
+        end
+      end
+
+      def create_link_header(hash) 
+        rval = []
+        hash.each do |type, links|
+          links.each do |link|
+            rval << "</#{key_uri(link[0], link[1])}>; riaktag=\"#{type}\""
+          end
+        end
+        return rval.join(", ")
+      end
+
+      def mergehash(master, stuff)
+        stuff.each do |k, v|
+          if master.include?(k)
+            current = master[k]
+            if current.respond_to?(:<<)
+              v.each do |e|
+                current << e
+              end
+            elsif current.is_a?(Hash)
+              mergehash(current, v)
+            else
+              master[k] = v
+            end
+          else
+            master[k] = v
+          end
+        end
+      end
+
+      def index_rel_subkey(bucket, key)
+        "<#{key}@#{bucket}>"
+      end
+
+      def index_rel_key(key, names, rel)
+        n = names[0...2]
+        if n.sort == n
+          "#{index_rel_subkey(name, key)}-#{index_rel_subkey(rel[0], rel[1])}"
+        else
+          "#{index_rel_subkey(rel[0], rel[1])}-#{index_rel_subkey(name, key)}"
+        end
+      end
+
+      def extended_index_rel(hash)
+        rval = hash["document"]
+        class << rval
+          attr_reader :key
+          attr_reader :bucket
+        end
+        rval.instance_eval do
+          @key = hash["key"]
+          @bucket = hash["bucket"]
+        end
+        rval
+      end
+      
+      def index_rel_document(names, key, rel)
+        rval = if rel.size == 3
+                 rel[2]
+               elsif rel.size == 2
+                 {}
+               else
+                 raise "Illegal argument to #index_rel_document(#{names}, #{key}, #{rel}): Third argument must be Array of size 2 or 3"
+               end
+        rval.merge("#{names[0]}_key" => index_rel_subkey(name, key),
+                   "#{names[1]}_key" => index_rel_subkey(rel[0], rel[1]))
+      end
+
+      def index_rel_extra_search(hash)
+        hash.collect do |k, v|
+          "#{k}:\"#{v}\""
+        end.join(" AND ")
+      end
+
+      def create_search_expression(key, names)
+        #
+        # Create a search expression that finds all relations where we are on one side of the relation.
+        # Optionally with extra search criteria.
+        #
+        search = if names.size == 3
+                   extra = names.delete_at(2)
+                   "#{names[0]}_key:\"#{index_rel_subkey(name, key)}\" AND (#{index_rel_extra_search(extra)})"
+                 elsif names.size == 2
+                   "#{names[0]}_key:\"#{index_rel_subkey(name, key)}\""
+                 else
+                   raise "Illegal argument to #index_rel_mr(#{key}, #{names}): Second argument must be Array of size 2 or 3"
+                 end
+      end
+
+      def recip_index_rel_mr(key, names)
+        search = create_search_expression(key, names)
+        Mr.new(@url).
+          #
+          # Create a new Mr where the input is the result of above search.
+          #
+          inputs(:module => "riak_search",
+                 :function => "mapred_search",
+                 :arg => [names.sort.join("-"),
+                          search]).
+          #
+          # Redirect the Mr to the reverse relation (where left and right side switch places).
+          #
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  var key_match = /^(<.*@.*>)-(<.*@.*>)$/.exec(v["key"]);
+  return [[v["bucket"], key_match[2] + "-" + key_match[1]]];
+}
+EOF
+              }).
+          #
+          # Redirect the Mr to the endpoint of the reverse relation (that is not us, ie that is what we started looking
+          # at before we reversed it), filtering out the deleted ones (where .values == null)
+          #
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  var rel_key = JSON.parse(v.values[0].data).#{names[0]}_key;
+  if ((match = /^<(.*)@(.*)>$/.exec(rel_key)) != null) {
+    return [[match[2], match[1]]];
+  } else {
+    return [];
+  }
+}
+EOF
+              }).
+          #
+          # Collect the documents on the other side of those bucket/key combos, 
+          # filtering out those that are deleted (have .values == null)
+          #
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  if (v.values != null) {
+    return [v];
+  } else {
+    return [];
+  }
+}
+EOF
+              }).
+          #
+          # Filter out the documents that actually exist (have .values != null)
+          #
+          reduce({
+                   :keep => true,
+                   :language => "javascript",
+                   :source => <<EOF
+function(v) {
+  rval = [];
+  for (var i = 0; i < v.length; i++) {
+    if (v[i].values != null) {
+      rval.push({"document": JSON.parse(v[i].values[0].data), "bucket": v[i].bucket, "key": v[i].key});
+    }
+  }
+  return rval;
+}
+EOF
+                 })
+      end
+      
+      def index_rel_mr(key, names) 
+        search = create_search_expression(key, names)
+        Mr.new(@url).
+          #
+          # Create a new Mr where the input is the result of above search.
+          #
+          inputs(:module => "riak_search",
+                 :function => "mapred_search",
+                 :arg => [names.sort.join("-"),
+                          search]).
+          #
+          # Redirect the Mr to the bucket/key combo on the other side of the relation.
+          #
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  var rel_key = JSON.parse(v.values[0].data).#{names[1]}_key;
+  if ((match = /^<(.*)@(.*)>$/.exec(rel_key)) != null) {
+    return [[match[2], match[1]]];
+  } else {
+    return [];
+  }
+}
+EOF
+              }).
+          #
+          # Collect the documents on the other side of those bucket/key combos, 
+          # filtering out those that are deleted (have .values == null)
+          #
+          map({
+                :keep => false,
+                :language => "javascript",
+                :source => <<EOF
+function(v,k,a) {
+  if (v.values != null) {
+    return [v];
+  } else {
+    return [];
+  }
+}
+EOF
+              }).
+          #
+          # Filter out the documents that actually exist (have .values != null)
+          #
+          reduce({
+                   :keep => true,
+                   :language => "javascript",
+                   :source => <<EOF
+function(v) {
+  rval = [];
+  for (var i = 0; i < v.length; i++) {
+    if (v[i].values != null) {
+      rval.push({"document": JSON.parse(v[i].values[0].data), "bucket": v[i].bucket, "key": v[i].key});
+    }
+  }
+  return rval;
+}
+EOF
+                 })
+      end
+      
+      def key_uri(bucket, key)
+        "buckets/#{CGI.escape(bucket)}/keys/#{CGI.escape(key)}"
+      end
+
+      def uri(*args)
+        if args.size == 0
+          URI.join(@url.to_s, "riak/#{CGI.escape(name)}")
+        elsif args.size == 1
+          URI.join(@url.to_s, key_uri(name, args[0]))
+        elsif args.size == 2
+          URI.join(@url.to_s, key_uri(args[0], args[1]))
+        end  
+      end
+
+    end
+
+  end
+
+end