better-riak-client 1.0.5

data/lib/riak/link.rb

@@ -0,0 +1,94 @@
+
+require 'riak/util/translation'
+require 'riak/util/escape'
+require 'riak/walk_spec'
+
+module Riak
+  # Represents a link from one object to another in Riak
+  class Link
+    include Util::Translation
+    include Util::Escape
+
+    # @return [String] the relationship tag (or "rel") of the other resource to this one
+    attr_accessor :tag
+    alias_method :rel, :tag
+    alias_method :rel=, :tag=
+
+    # @return [String] the bucket of the related resource
+    attr_accessor :bucket
+
+    # @return [String] the key of the related resource
+    attr_accessor :key
+
+    %w{bucket key}.each do |m|
+      define_method("#{m}=") { |value|
+        @url = nil
+        instance_variable_set("@#{m}", value)
+      }
+    end
+
+    # @param [String] header_string the string value of the Link: HTTP header from a Riak response
+    # @return [Array<Link>] an array of Riak::Link structs parsed from the header
+    def self.parse(header_string)
+      header_string.scan(%r{<([^>]+)>\s*;\s*(?:rel|riaktag)=\"([^\"]+)\"}).map do |match|
+        new(match[0], match[1])
+      end
+    end
+
+    # @overload initialize(url, tag)
+    #   @param [String] url the url of the related resource
+    #   @param [String] tag the tag for the related resource
+    # @overload initialize(bucket, key, tag)
+    #   @param [String] bucket the bucket of the related resource
+    #   @param [String] key the key of the related resource
+    #   @param [String] tag the tag for the related resource
+    def initialize(*args)
+      raise ArgumentError unless (2..3).include?(args.size)
+      if args.size == 2
+        self.url, @tag = args
+      else
+        @bucket, @key, @tag = args
+      end
+    end
+
+    # @return [String] the URL (relative or absolute) of the related resource
+    def url(new_scheme=false)
+      return @url unless @bucket
+
+      if new_scheme
+        "/buckets/#{escape(bucket)}" + (key.blank? ? "" : "/keys/#{escape(key)}")
+      else
+        "/riak/#{escape(bucket)}" + (key.blank? ? "" : "/#{escape(key)}")
+      end
+    end
+
+    def url=(value)
+      @url = value
+      @bucket = unescape($1) if value =~ %r{^/buckets/([^/]+)/?} || value =~ %r{^/[^/]+/([^/]+)/?}
+      @key = unescape($1) if value =~ %r{^/buckets/[^/]+/keys/([^/]+)/?} || value =~ %r{^/[^/]+/[^/]+/([^/]+)/?}
+    end
+
+    def inspect; to_s; end
+
+    def to_s(new_scheme=false)
+      %Q[<#{url(new_scheme)}>; riaktag="#{tag}"]
+    end
+
+    def hash
+      self.to_s.hash
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def ==(other)
+      other.is_a?(Link) && url == other.url && tag == other.tag
+    end
+
+    def to_walk_spec
+      raise t("bucket_link_conversion") if tag == "up" || key.nil?
+      WalkSpec.new(:bucket => bucket, :tag => tag)
+    end
+  end
+end

data/lib/riak/locale/en.yml

@@ -0,0 +1,53 @@
+en:
+  riak:
+    backwards_clock: "System clock moved backwards, ID generation will fail for %{delay} more milliseconds."
+    bucket_link_conversion: "Can't convert a bucket link to a walk spec"
+    client_type: "invalid argument %{client} is not a Riak::Client"
+    conflict_resolver_invalid: "The given resolver (%{resolver}) did not respond to :call"
+    content_type_undefined: "content_type is not defined!"
+    deprecated:
+      port: "DEPRECATION: Riak::Client#port has been deprecated, use #http_port or #pb_port for the appropriate protocol.\n%{backtrace}"
+      search: "DEPRECATION: Riak Search features are included in the main client, you no longer need to require 'riak/search'.\n%{backtrace}"
+    empty_map_reduce_query: "Specify one or more query phases to your MapReduce."
+    failed_request: "Client request failed."
+    filter_needs_block: "Filter %{filter} expects a block."
+    filter_arity_mismatch: "Filter %{filter} expects %{expected} arguments but %{received} were given."
+    full_bucket_mapred: "Full-bucket MapReduce, including key filters, invokes list-keys which is an expensive operation that should not be used in production.\n    %{backtrace}"
+    hash_type: "invalid argument %{hash} is not a Hash"
+    http_configuration: "The %{backend} HTTP backend cannot be used. Please check its requirements."
+    http_failed_request: "Expected %{expected} from Riak but received %{code}. %{body}"
+    hostname_invalid: "host must be a valid hostname"
+    protocol_invalid: "'%{invalid}' is not a valid protocol, valid values are %{valid}"
+    invalid_basic_auth: "basic auth must be set using 'user:pass'"
+    invalid_client_id: "Invalid client ID, must be a string or between 0 and %{max_id}"
+    invalid_io_object: "Invalid IO-like object assigned to RObject#data.  It should be assigned to raw_data instead."
+    invalid_function_value: "invalid value for function: %{value}"
+    invalid_options: "Invalid configuration options given."
+    invalid_phase_type: "type must be :map, :reduce, or :link"
+    invalid_ssl_verify_mode: "%{invalid} is not a valid :verify_mode option for SSL. Valid options are 'peer' and 'none'."
+    invalid_index_query: "%{value} is not a valid index query term, only Strings, Integers, and Ranges of those are allowed."
+    indexes_unsupported: "Riak server does not support secondary indexes."
+    loading_bucket: "while loading bucket '%{name}'"    
+    list_buckets: "Riak::Client#buckets is an expensive operation that should not be used in production.\n    %{backtrace}"
+    list_keys: "Riak::Bucket#keys is an expensive operation that should not be used in production.\n    %{backtrace}"
+    luwak_unsupported: "Riak server does not support Luwak. Enable it in app.config before using."
+    missing_block: "A block must be given."
+    missing_host_and_port: "You must specify a host and port, or use the defaults of 127.0.0.1:8098"
+    module_function_pair_required: "function must have two elements when an array"
+    not_found: "The requested object was not found."
+    no_pipes: "Could not find or open pipes for Riak console in %{path}."
+    port_invalid: "port must be an integer between 0 and 65535"
+    protobuffs_failed_request: "Expected success from Riak but received %{code}. %{body}"
+    protobuffs_configuration: "The %{backend} Protobuffs backend cannot be used. Please check its requirements."
+    request_body_type: "Request body must be a String or respond to :read."
+    search_unsupported: "Riak server does not support search."
+    search_docs_require_id: "Search index documents must include the 'id' field."
+    search_remove_requires_id_or_query: "Search index documents to be removed must have 'id' or 'query' keys."
+    serializer_not_implemented: "No serializer has been registered for content type %{content_type}"
+    source_and_root_required: "Riak::Node configuration must include :source and :root keys."
+    stale_write_prevented: "Stale write prevented by client."
+    stored_function_invalid: "function must have :bucket and :key when a hash"
+    string_type: "invalid_argument %{string} is not a String"
+    too_few_arguments: "too few arguments: %{params}"
+    walk_spec_invalid_unless_link: "WalkSpec is only valid for a function when the type is :link"
+    wrong_argument_count_walk_spec: "wrong number of arguments (one Hash or bucket,tag,keep required)"

data/lib/riak/locale/fr.yml

@@ -0,0 +1,52 @@
+fr:
+  riak:
+    backwards_clock: "L'horloge système a reculé. La génération des ID échouera pour les %{delay} millisecondes à venir."
+    bucket_link_conversion: "Ne peut convertir un lien de bucket vers un walk spec"
+    client_type: "argument invalide : %{client} n'est pas un Riak::Client"
+    conflict_resolver_invalid: "Le résolveur (%{resolver}) n'a pas répondu à :call"
+    content_type_undefined: "content_type n'est pas défini !"
+    deprecated:
+      port: "DEPRECATION: Riak::Client#port ne doit plus être utilisé (deprecated), utilisez #http_port ou #pb_port pour spécifier le protocol.\n%{backtrace}"
+      search: "DEPRECATION: Les fonctionnalités Riak Search sont désormais inclues dans le client principal. Vous n'avez plus besoin d'inclure 'riak/search'.\n%{backtrace}"
+    empty_map_reduce_query: "Spécifiez une ou plusieurs requêtes pour MapReduce."
+    failed_request: "La requête client a échouée."
+    filter_needs_block: "Le filtre %{filter} nécessite un bloc."
+    filter_arity_mismatch: "Le filtre %{filter} nécessite %{expected} arguments. Seulement %{received} ont été fournis."
+    full_bucket_mapred: "Les MapReduce sur un bucket complet, y compris les filtres de clé, invoque 'list-keys' qui est une opération coûteuse et ne doit pas être utilisée en production.\n    %{backtrace}"
+    hash_type: "argument invalide : %{hash} n'est pas un Hash"
+    http_configuration: "Le moteur HTTP %{backend} ne peut être utilisé. Merci de vérifier ses dépendances et/ou sa configuration."
+    http_failed_request: "%{expected} attendu depuis Riak mais %{code} reçu. %{body}"
+    hostname_invalid: "host doit être un nom d'hôte valide"
+    protocol_invalid: "'%{invalid}' n'est pas un protocole valide. Les valeurs possibles sont %{valid}"
+    invalid_basic_auth: "L'authentification basique doit être utilisée comme ceci : 'user:pass'"
+    invalid_client_id: "ID client invalide, doit être une chaîne ou un entier entre 0 et %{max_id}"
+    invalid_io_object: "Object de type IO invalide assigné à RObject#data. Il devrait plutôt être assigné à raw_data"
+    invalid_function_value: "Valeur invalide pour la fonction : %{value}"
+    invalid_options: "Options de configuration invalides."
+    invalid_phase_type: "type doit être :map, :reduce, ou :link"
+    invalid_ssl_verify_mode: "%{invalid} n'est pas une option :verify_mode valide pour SSL. Les options valides sont 'peer' and 'none'."
+    invalid_index_query: "%{value} n'est pas un term de requête valide. Seules les String, Integer et Range de ces types sont autorisés"
+    indexes_unsupported: "Le serveur Riak ne supporte pas les index secondaires."
+    loading_bucket: "pendant le chargement du bucket '%{name}'"
+    list_buckets: "Riak::Client#buckets est une opération coûteuse et ne doit pas être utilisée en production.\n    %{backtrace}"
+    list_keys: "Riak::Bucket#keys est une opération coûteuse et ne doit pas être utilisée en production.\n    %{backtrace}"
+    luwak_unsupported: "Le serveur Riak ne supporte pas Luwak. Activez-le dans app.config avant de l'utiliser"
+    missing_block: "Un bloc doit être fourni."
+    missing_host_and_port: "Vous devez spécifier un hôte et un port, utiliser la valeur par défaut : 127.0.0.1:8098"
+    module_function_pair_required: "la fonction doit avoir deux élément lorsqu'elle est définie par un tableau"
+    not_found: "L'objet demandé n'a pas été trouvé."
+    no_pipes: "Ne peut trouver ou ne peut ouvrir un pipe pour la console Riak dans %{path}."
+    port_invalid: "le port doit être un entier entre 0 et 65535"
+    protobuffs_failed_request: "Riak a retourné le code d'erreur %{code} au lieu d'une réponse réussie. %{body}"
+    request_body_type: "Le corps de la requête doit être une chaine ou répondre à :read."
+    search_unsupported: "Le serveur Riak ne supporte pas la recherche."
+    search_docs_require_id: "Search index documents must include the 'id' field."
+    search_remove_requires_id_or_query: "Les documents d'index de recherche doivent avoir des clés 'id' ou 'query'"
+    serializer_not_implemented: "Aucun sérialiseur n'a été défini pour le type de contenu %{content_type}"
+    source_and_root_required: "La configuration de Riak::Node configuration doit inclure les clés :source and :root."
+    stale_write_prevented: "Le client a empêché une écriture périmée."
+    stored_function_invalid: "Une fonction définie par un hash doit avoir :bucket et :key"
+    string_type: "invalid_argument %{string} n'est pas une String"
+    too_few_arguments: "pas assez d'arguments : %{params}"
+    walk_spec_invalid_unless_link: "Le WalkSpec n'est valide pour une fonction que lorsque le type est :link"
+    wrong_argument_count_walk_spec: "nombre d'argument invalide (un Hash ou bucket,tag,keep requis)"

data/lib/riak/map_reduce/filter_builder.rb

@@ -0,0 +1,103 @@
+
+require 'riak/util/translation'
+
+module Riak
+  class MapReduce
+    # Builds key-filter lists for MapReduce inputs in a DSL-like fashion.
+    class FilterBuilder
+      include Util::Translation
+
+      # Known filters available in riak_kv_mapred_filters, mapped to
+      # their arities. These are turned into instance methods.
+      # Example:
+      #
+      #    FilterBuilder.new do
+      #      string_to_int
+      #      less_than 50
+      #    end
+      FILTERS = {
+        :int_to_string => 0,
+        :string_to_int => 0,
+        :float_to_string => 0,
+        :string_to_float => 0,
+        :to_upper => 0,
+        :to_lower => 0,
+        :tokenize => 2,
+        :urldecode => 0,
+        :greater_than => 1,
+        :less_than => 1,
+        :greater_than_eq => 1,
+        :less_than_eq => 1,
+        :between => [2,3],
+        :matches => 1,
+        :neq => 1,
+        :eq => 1,
+        :set_member => -1,
+        :similar_to => 2,
+        :starts_with => 1,
+        :ends_with => 1
+      }
+
+      # Available logical operations for joining filter chains. These
+      # are turned into instance methods with leading underscores,
+      # with aliases to uppercase versions.
+      # Example:
+      #
+      #    FilterBuilder.new do
+      #      string_to_int
+      #      AND do
+      #        seq { greater_than_eq 50 }
+      #        seq { neq 100 }
+      #      end
+      #    end
+      LOGICAL_OPERATIONS = %w{and or not}
+
+      FILTERS.each do |f,arity|
+        arities = [arity].flatten
+
+        define_method(f) { |*args|
+          unless arities.include?(-1) or arities.include?(args.size)
+            raise ArgumentError.new t("filter_arity_mismatch",
+              :filter => f,
+              :expected => arities,
+              :received => args.size
+            )
+          end
+
+          @filters << [f, *args]
+        }
+      end
+
+      LOGICAL_OPERATIONS.each do |op|
+        # NB: string eval is needed here because in ruby 1.8, blocks can't yield to
+        # other blocks
+        class_eval <<-CODE
+          def _#{op}(&block)
+            raise ArgumentError.new(t('filter_needs_block', :filter => '#{op}')) unless block_given?
+            @filters << [:#{op}, self.class.new(&block).to_a]
+          end
+          alias :#{op.to_s.upcase} :_#{op}
+        CODE
+      end
+
+      # Creates a new FilterBuilder. Pass a block that will be
+      # instance_eval'ed to construct the sequence of filters.
+      def initialize(&block)
+        @filters = []
+        instance_eval(&block) if block_given?
+      end
+
+      # Wraps multi-step filters for use inside logical
+      # operations. Does not correspond to an actual filter.
+      def sequence(&block)
+        @filters << self.class.new(&block).to_a
+      end
+      alias :seq :sequence
+
+      # @return A list of filters for handing to the MapReduce inputs.
+      def to_a
+        @filters
+      end
+    end
+  end
+end

data/lib/riak/map_reduce/phase.rb

@@ -0,0 +1,98 @@
+
+require 'riak/json'
+require 'riak/util/translation'
+require 'riak/walk_spec'
+
+module Riak
+  class MapReduce
+    # Represents an individual phase in a map-reduce pipeline. Generally you'll want to call
+    # methods of MapReduce instead of using this directly.
+    class Phase
+      include Util::Translation
+      # @return [Symbol] the type of phase - :map, :reduce, or :link
+      attr_accessor :type
+
+      # @return [String, Array<String, String>, Hash, WalkSpec] For :map and :reduce types, the Javascript function to run (as a string or hash with bucket/key), or the module + function in Erlang to run. For a :link type, a {Riak::WalkSpec} or an equivalent hash.
+      attr_accessor :function
+
+      # @return [String] the language of the phase's function - "javascript" or "erlang". Meaningless for :link type phases.
+      attr_accessor :language
+
+      # @return [Boolean] whether results of this phase will be returned
+      attr_accessor :keep
+
+      # @return [Array] any extra static arguments to pass to the phase
+      attr_accessor :arg
+
+      # Creates a phase in the map-reduce pipeline
+      # @param [Hash] options options for the phase
+      # @option options [Symbol] :type one of :map, :reduce, :link
+      # @option options [String] :language ("javascript") "erlang" or "javascript"
+      # @option options [String, Array, Hash] :function In the case of Javascript, a literal function in a string, or a hash with :bucket and :key. In the case of Erlang, an Array of [module, function].  For a :link phase, a hash including any of :bucket, :tag or a WalkSpec.
+      # @option options [Boolean] :keep (false) whether to return the results of this phase
+      # @option options [Array] :arg (nil) any extra static arguments to pass to the phase
+      def initialize(options={})
+        self.type = options[:type]
+        self.language = options[:language] || "javascript"
+        self.function = options[:function]
+        self.keep = options[:keep] || false
+        self.arg = options[:arg]
+      end
+
+      def type=(value)
+        raise ArgumentError, t("invalid_phase_type") unless value.to_s =~ /^(map|reduce|link)$/i
+        @type = value.to_s.downcase.to_sym
+      end
+
+      def function=(value)
+        case value
+        when Array
+          raise ArgumentError, t("module_function_pair_required") unless value.size == 2
+          @language = "erlang"
+        when Hash
+          raise ArgumentError, t("stored_function_invalid") unless type == :link || value.has_key?(:bucket) && value.has_key?(:key)
+          @language = "javascript"
+        when String
+          @language = "javascript"
+        when WalkSpec
+          raise ArgumentError, t("walk_spec_invalid_unless_link") unless type == :link
+        else
+          raise ArgumentError, t("invalid_function_value", :value => value.inspect)
+        end
+        @function = value
+      end
+
+      # Converts the phase to JSON for use while invoking a job.
+      # @return [String] a JSON representation of the phase
+      def to_json(*a)
+        as_json.to_json(*a)
+      end
+
+      # Converts the phase to its JSON-compatible representation for job invocation.
+      # @return [Hash] a Hash-equivalent of the phase
+      def as_json(options=nil)
+        obj = case type
+              when :map, :reduce
+                defaults = {"language" => language, "keep" => keep}
+                case function
+                when Hash
+                  defaults.merge(function)
+                when String
+                  if function =~ /\s*function/
+                    defaults.merge("source" => function)
+                  else
+                    defaults.merge("name" => function)
+                  end
+                when Array
+                  defaults.merge("module" => function[0], "function" => function[1])
+                end
+              when :link
+                spec = WalkSpec.normalize(function).first
+                {"bucket" => spec.bucket, "tag" => spec.tag, "keep" => spec.keep || keep}
+              end
+        obj["arg"] = arg if arg
+        { type => obj }
+      end
+    end
+  end
+end

data/lib/riak/map_reduce.rb

@@ -0,0 +1,225 @@
+require 'riak/util/translation'
+require 'riak/util/escape'
+require 'riak/json'
+require 'riak/client'
+require 'riak/bucket'
+require 'riak/robject'
+require 'riak/walk_spec'
+require 'riak/failed_request'
+require 'riak/map_reduce_error'
+require 'riak/map_reduce/phase'
+require 'riak/map_reduce/filter_builder'
+
+module Riak
+  # Class for invoking map-reduce jobs using the HTTP interface.
+  class MapReduce
+    include Util::Translation
+    include Util::Escape
+
+    # @return [Array<[bucket,key]>,String,Hash<:bucket,:filters>] The
+    #       bucket/keys for input to the job, or the bucket (all
+    #       keys), or a hash containing the bucket and key-filters.
+    # @see #add
+    attr_accessor :inputs
+
+    # @return [Array<Phase>] The map and reduce phases that will be executed
+    # @see #map
+    # @see #reduce
+    # @see #link
+    attr_accessor :query
+
+    # Creates a new map-reduce job.
+    # @param [Client] client the Riak::Client interface
+    # @yield [self] helpful for initializing the job
+    def initialize(client)
+      @client, @inputs, @query = client, [], []
+      yield self if block_given?
+    end
+
+    # Add or replace inputs for the job.
+    # @overload add(bucket)
+    #   Run the job across all keys in the bucket.  This will replace any other inputs previously added.
+    #   @param [String, Bucket] bucket the bucket to run the job on
+    # @overload add(bucket,key)
+    #   Add a bucket/key pair to the job.
+    #   @param [String,Bucket] bucket the bucket of the object
+    #   @param [String] key the key of the object
+    # @overload add(object)
+    #   Add an object to the job (by its bucket/key)
+    #   @param [RObject] object the object to add to the inputs
+    # @overload add(bucket, key, keydata)
+    #   @param [String,Bucket] bucket the bucket of the object
+    #   @param [String] key the key of the object
+    #   @param [String] keydata extra data to pass along with the object to the job
+    # @overload add(bucket, filters)
+    #   Run the job across all keys in the bucket, with the given
+    #   key-filters. This will replace any other inputs previously
+    #   added. (Requires Riak 0.14)
+    #   @param [String,Bucket] bucket the bucket to filter keys from
+    #   @param [Array<Array>] filters a list of key-filters to apply
+    #                                 to the key list
+    # @return [MapReduce] self
+    def add(*params)
+      params = params.dup
+      params = params.first if Array === params.first
+      case params.size
+      when 1
+        p = params.first
+        case p
+        when Bucket
+          warn(t('full_bucket_mapred', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
+          @inputs = maybe_escape(p.name)
+        when RObject
+          @inputs << [maybe_escape(p.bucket.name), maybe_escape(p.key)]
+        when String
+          warn(t('full_bucket_mapred', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
+          @inputs = maybe_escape(p)
+        end
+      when 2..3
+        bucket = params.shift
+        bucket = bucket.name if Bucket === bucket
+        if Array === params.first
+          warn(t('full_bucket_mapred', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
+          @inputs = {:bucket => maybe_escape(bucket), :key_filters => params.first }
+        else
+          key = params.shift
+          @inputs << params.unshift(maybe_escape(key)).unshift(maybe_escape(bucket))
+        end
+      end
+      self
+    end
+    alias :<< :add
+    alias :include :add
+
+    # Adds a bucket and key-filters built by the given
+    # block. Equivalent to #add with a list of filters.
+    # @param [String] bucket the bucket to apply key-filters to
+    # @yield [] builder block - instance_eval'ed into a FilterBuilder
+    # @return [MapReduce] self
+    # @see MapReduce#add
+    def filter(bucket, &block)
+      add(bucket, FilterBuilder.new(&block).to_a)
+    end
+
+    # (Riak Search) Use a search query to start a map/reduce job.
+    # @param [String, Bucket] bucket the bucket/index to search
+    # @param [String] query the query to run
+    # @return [MapReduce] self
+    def search(bucket, query)
+      bucket = bucket.name if bucket.respond_to?(:name)
+      @inputs = {:module => "riak_search", :function => "mapred_search", :arg => [bucket, query]}
+      self
+    end
+
+    # (Secondary Indexes) Use a secondary index query to start a
+    # map/reduce job.
+    # @param [String, Bucket] bucket the bucket whose index to query
+    # @param [String] index the index to query
+    # @param [String, Integer, Range] query the value of the index, or
+    #   a range of values (of Strings or Integers)
+    # @return [MapReduce] self
+    def index(bucket, index, query)
+      bucket = bucket.name if bucket.respond_to?(:name)
+      case query
+      when String, Fixnum
+        @inputs = {:bucket => maybe_escape(bucket), :index => index, :key => query}
+      when Range
+        raise ArgumentError, t('invalid_index_query', :value => query.inspect) unless String === query.begin || Integer === query.begin
+        @inputs = {:bucket => maybe_escape(bucket), :index => index, :start => query.begin, :end => query.end}
+      else
+        raise ArgumentError, t('invalid_index_query', :value => query.inspect)
+      end
+      self
+    end
+
+    # Add a map phase to the job.
+    # @overload map(function)
+    #   @param [String, Array] function a Javascript function that represents the phase, or an Erlang [module,function] pair
+    # @overload map(function?, options)
+    #   @param [String, Array] function a Javascript function that represents the phase, or an Erlang [module, function] pair
+    #   @param [Hash] options extra options for the phase (see {Phase#initialize})
+    # @return [MapReduce] self
+    # @see Phase#initialize
+    def map(*params)
+      options = params.extract_options!
+      @query << Phase.new({:type => :map, :function => params.shift}.merge(options))
+      self
+    end
+
+    # Add a reduce phase to the job.
+    # @overload reduce(function)
+    #   @param [String, Array] function a Javascript function that represents the phase, or an Erlang [module,function] pair
+    # @overload reduce(function?, options)
+    #   @param [String, Array] function a Javascript function that represents the phase, or an Erlang [module, function] pair
+    #   @param [Hash] options extra options for the phase (see {Phase#initialize})
+    # @return [MapReduce] self
+    # @see Phase#initialize
+    def reduce(*params)
+      options = params.extract_options!
+      @query << Phase.new({:type => :reduce, :function => params.shift}.merge(options))
+      self
+    end
+
+    # Add a link phase to the job. Link phases follow links attached to objects automatically (a special case of map).
+    # @overload link(walk_spec, options={})
+    #   @param [WalkSpec] walk_spec a WalkSpec that represents the types of links to follow
+    #   @param [Hash] options extra options for the phase (see {Phase#initialize})
+    # @overload link(bucket, tag, keep, options={})
+    #   @param [String, nil] bucket the bucket to limit links to
+    #   @param [String, nil] tag the tag to limit links to
+    #   @param [Boolean] keep whether to keep results of this phase (overrides the phase options)
+    #   @param [Hash] options extra options for the phase (see {Phase#initialize})
+    # @overload link(options)
+    #   @param [Hash] options options for both the walk spec and link phase
+    #   @see WalkSpec#initialize
+    # @return [MapReduce] self
+    # @see Phase#initialize
+    def link(*params)
+      options = params.extract_options!
+      walk_spec_options = options.slice!(:type, :function, :language, :arg) unless params.first
+      walk_spec = WalkSpec.normalize(params.shift || walk_spec_options).first
+      @query << Phase.new({:type => :link, :function => walk_spec}.merge(options))
+      self
+    end
+
+    # Sets the timeout for the map-reduce job.
+    # @param [Fixnum] value the job timeout, in milliseconds
+    def timeout(value)
+      @timeout = value
+      return self
+    end
+    alias :timeout= :timeout
+
+    # Convert the job to JSON for submission over the HTTP interface.
+    # @return [String] the JSON representation
+    def to_json(*a)
+      hash = {"inputs" => inputs, "query" => query.map(&:as_json)}
+      hash['timeout'] = @timeout.to_i if @timeout
+      hash.to_json(*a)
+    end
+
+    # Executes this map-reduce job.
+    # @overload run
+    #   Return the entire collection of results.
+    #   @return [Array<Array>] similar to link-walking, each element is
+    #     an array of results from a phase where "keep" is true. If there
+    #     is only one "keep" phase, only the results from that phase will
+    #     be returned.
+    # @overload run
+    #   Stream the results through the given block without accumulating.
+    #   @yield [phase, data] A block to stream results through
+    #   @yieldparam [Fixnum] phase the phase from which the results were
+    #          generated
+    #   @yieldparam [Array] data a list of results from the phase
+    #   @return [nil] nothing
+    def run(&block)
+      @client.mapred(self, &block)
+    rescue FailedRequest => fr
+      if fr.server_error? && fr.is_json?
+        raise MapReduceError.new(fr.body)
+      else
+        raise fr
+      end
+    end
+  end
+end