riak-client 0.7.0

data/lib/riak/client/curb_backend.rb

@@ -0,0 +1,82 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+require 'riak'
+
+begin
+  require 'fiber'
+rescue LoadError
+  require 'riak/util/fiber1.8'
+end
+
+module Riak
+  class Client
+    # An HTTP backend for Riak::Client that uses the 'curb' library/gem.
+    # If the 'curb' library is present, this backend will be preferred to
+    # the backend based on Net::HTTP.
+    # Conforms to the Riak::Client::HTTPBackend interface.
+    class CurbBackend < HTTPBackend
+      private
+      def perform(method, uri, headers, expect, data=nil)
+        # Setup
+        curl.headers = headers
+        curl.url = uri.to_s
+        response_headers.initialize_http_header(nil)
+        if block_given?
+          _curl = curl
+          Fiber.new {
+            f = Fiber.current
+            _curl.on_body {|chunk| f.resume(chunk); chunk.size }
+            loop do
+              yield Fiber.yield
+            end
+          }.resume
+        else
+          curl.on_body
+        end
+        # Perform
+        case method
+        when :put, :post
+          curl.send("http_#{method}", data)
+        else
+          curl.send("http_#{method}")
+        end
+
+        # Verify
+        if valid_response?(expect, curl.response_code)
+          result = { :headers => response_headers.to_hash, :code => curl.response_code.to_i }
+          if return_body?(method, curl.response_code, block_given?)
+            result[:body] = curl.body_str
+          end
+          result
+        else
+          raise FailedRequest.new(method, expect, curl.response_code, response_headers.to_hash, curl.body_str)
+        end
+      end
+
+      def curl
+        Thread.current[:curl_easy_handle] ||= Curl::Easy.new.tap do |c|
+          c.follow_location = false
+          c.on_header do |header_line|
+            response_headers.parse(header_line)
+            header_line.size
+          end
+        end
+      end
+
+      def response_headers
+        Thread.current[:response_headers] ||= Riak::Util::Headers.new
+      end
+    end
+  end
+end

data/lib/riak/client/http_backend.rb

@@ -0,0 +1,209 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+require 'riak'
+
+module Riak
+  class Client
+    class HTTPBackend
+      include Util::Translation
+      # The Riak::Client that uses this backend
+      attr_reader :client
+
+      # Create an HTTPBackend for the Riak::Client.
+      # @param [Client] client the client
+      def initialize(client)
+        raise ArgumentError, t("client_type", :client => client) unless Client === client
+        @client = client
+      end
+
+      # Default header hash sent with every request, based on settings in the client
+      # @return [Hash] headers that will be merged with user-specified headers on every request
+      def default_headers
+        {
+          "Accept" => "multipart/mixed, application/json;q=0.7, */*;q=0.5",
+          "X-Riak-ClientId" => @client.client_id
+        }
+      end
+
+      # Performs a HEAD request to the specified resource on the Riak server.
+      # @param [Fixnum, Array] expect the expected HTTP response code(s) from Riak
+      # @param [String, Array<String,Hash>] resource a relative path or array of path segments and optional query params Hash that will be joined to the root URI
+      # @overload head(expect, *resource)
+      # @overload head(expect, *resource, headers)
+      #   Send the request with custom headers
+      #   @param [Hash] headers custom headers to send with the request
+      # @return [Hash] response data, containing only the :headers and :code keys
+      # @raise [FailedRequest] if the response code doesn't match the expected response
+      def head(expect, *resource)
+        headers = default_headers.merge(resource.extract_options!)
+        verify_path!(resource)
+        perform(:head, path(*resource), headers, expect)
+      end
+
+      # Performs a GET request to the specified resource on the Riak server.
+      # @param [Fixnum, Array] expect the expected HTTP response code(s) from Riak
+      # @param [String, Array<String,Hash>] resource a relative path or array of path segments and optional query params Hash that will be joined to the root URI
+      # @overload get(expect, *resource)
+      # @overload get(expect, *resource, headers)
+      #   Send the request with custom headers
+      #   @param [Hash] headers custom headers to send with the request
+      # @overload get(expect, *resource, headers={})
+      #   Stream the response body through the supplied block
+      #   @param [Hash] headers custom headers to send with the request
+      #   @yield [chunk] yields successive chunks of the response body as strings
+      #   @return [Hash] response data, containing only the :headers and :code keys
+      # @return [Hash] response data, containing :headers, :body, and :code keys
+      # @raise [FailedRequest] if the response code doesn't match the expected response
+      def get(expect, *resource, &block)
+        headers = default_headers.merge(resource.extract_options!)
+        verify_path!(resource)
+        perform(:get, path(*resource), headers, expect, &block)
+      end
+
+      # Performs a PUT request to the specified resource on the Riak server.
+      # @param [Fixnum, Array] expect the expected HTTP response code(s) from Riak
+      # @param [String, Array<String,Hash>] resource a relative path or array of path segments and optional query params Hash that will be joined to the root URI
+      # @param [String] body the request body to send to the server
+      # @overload put(expect, *resource, body)
+      # @overload put(expect, *resource, body, headers)
+      #   Send the request with custom headers
+      #   @param [Hash] headers custom headers to send with the request
+      # @overload put(expect, *resource, body, headers={})
+      #   Stream the response body through the supplied block
+      #   @param [Hash] headers custom headers to send with the request
+      #   @yield [chunk] yields successive chunks of the response body as strings
+      #   @return [Hash] response data, containing only the :headers and :code keys
+      # @return [Hash] response data, containing :headers, :code, and :body keys
+      # @raise [FailedRequest] if the response code doesn't match the expected response
+      def put(expect, *resource, &block)
+        headers = default_headers.merge(resource.extract_options!)
+        uri, data = verify_path_and_body!(resource)
+        perform(:put, path(*uri), headers, expect, data, &block)
+      end
+
+      # Performs a POST request to the specified resource on the Riak server.
+      # @param [Fixnum, Array] expect the expected HTTP response code(s) from Riak
+      # @param [String, Array<String>] resource a relative path or array of path segments that will be joined to the root URI
+      # @param [String] body the request body to send to the server
+      # @overload post(expect, *resource, body)
+      # @overload post(expect, *resource, body, headers)
+      #   Send the request with custom headers
+      #   @param [Hash] headers custom headers to send with the request
+      # @overload post(expect, *resource, body, headers={})
+      #   Stream the response body through the supplied block
+      #   @param [Hash] headers custom headers to send with the request
+      #   @yield [chunk] yields successive chunks of the response body as strings
+      #   @return [Hash] response data, containing only the :headers and :code keys
+      # @return [Hash] response data, containing :headers, :code and :body keys
+      # @raise [FailedRequest] if the response code doesn't match the expected response
+      def post(expect, *resource, &block)
+        headers = default_headers.merge(resource.extract_options!)
+        uri, data = verify_path_and_body!(resource)
+        perform(:post, path(*uri), headers, expect, data, &block)
+      end
+
+      # Performs a DELETE request to the specified resource on the Riak server.
+      # @param [Fixnum, Array] expect the expected HTTP response code(s) from Riak
+      # @param [String, Array<String,Hash>] resource a relative path or array of path segments and optional query params Hash that will be joined to the root URI
+      # @overload delete(expect, *resource)
+      # @overload delete(expect, *resource, headers)
+      #   Send the request with custom headers
+      #   @param [Hash] headers custom headers to send with the request
+      # @overload delete(expect, *resource, headers={})
+      #   Stream the response body through the supplied block
+      #   @param [Hash] headers custom headers to send with the request
+      #   @yield [chunk] yields successive chunks of the response body as strings
+      #   @return [Hash] response data, containing only the :headers and :code keys
+      # @return [Hash] response data, containing :headers, :code and :body keys
+      # @raise [FailedRequest] if the response code doesn't match the expected response
+      def delete(expect, *resource, &block)
+        headers = default_headers.merge(resource.extract_options!)
+        verify_path!(resource)
+        perform(:delete, path(*resource), headers, expect, &block)
+      end
+
+      # @return [URI] The calculated root URI for the Riak HTTP endpoint
+      def root_uri
+        URI.parse("http://#{@client.host}:#{@client.port}")
+      end
+
+      # Calculates an absolute URI from a relative path specification
+      # @param [Array<String,Hash>] segments a relative path or sequence of path segments and optional query params Hash that will be joined to the root URI
+      # @return [URI] an absolute URI for the resource
+      def path(*segments)
+        query = segments.extract_options!.to_param
+        root_uri.merge(segments.join("/").gsub(/\/+/, "/").sub(/^\//, '')).tap do |uri|
+          uri.query = query if query.present?
+        end
+      end
+
+      # Verifies that both a resource path and body are present in the arguments
+      # @param [Array] args the arguments to verify
+      # @raise [ArgumentError] if the body or resource is missing, or if the body is not a String
+      def verify_path_and_body!(args)
+        body = args.pop
+        begin
+          verify_path!(args)
+        rescue ArgumentError
+          raise ArgumentError, t("path_and_body_required")
+        end
+
+        raise ArgumentError, t("request_body_type") unless String === body || IO === body
+        [args, body]
+      end
+
+      # Verifies that the specified resource is valid
+      # @param [String, Array] resource the resource specification
+      # @raise [ArgumentError] if the resource path is too short
+      def verify_path!(resource)
+        resource = Array(resource).flatten
+        raise ArgumentError, t("resource_path_short") unless resource.length > 1 || resource.include?(@client.mapred)
+      end
+      
+      # Checks the expected response codes against the actual response code. Use internally when
+      # implementing {#perform}.
+      # @param [String, Fixnum, Array<String,Fixnum>] expected the expected response code(s)
+      # @param [String, Fixnum] actual the received response code
+      # @return [Boolean] whether the actual response code is acceptable given the expectations
+      def valid_response?(expected, actual)
+        Array(expected).map(&:to_i).include?(actual.to_i)
+      end
+
+      # Checks whether a combination of the HTTP method, response code, and block should
+      # result in returning the :body in the response hash. Use internally when implementing {#perform}.
+      # @param [Symbol] method the HTTP method
+      # @param [String, Fixnum] code the received response code
+      # @param [Boolean] has_block whether a streaming block was passed to {#perform}. Pass block_given? to this parameter.
+      # @return [Boolean] whether to return the body in the response hash
+      def return_body?(method, code, has_block)
+        method != :head && !valid_response?([204,205,304], code) && !has_block
+      end
+      
+      # Executes requests according to the underlying HTTP client library semantics.
+      # @abstract Subclasses must implement this internal method to perform HTTP requests
+      #           according to the API of their HTTP libraries.
+      # @param [Symbol] method one of :head, :get, :post, :put, :delete
+      # @param [URI] uri the HTTP URI to request
+      # @param [Hash] headers headers to send along with the request
+      # @param [Fixnum, Array] expect the expected response code(s)
+      # @param [String, IO] body the PUT or POST request body
+      # @return [Hash] response data, containing :headers, :code and :body keys. Only :headers and :code should be present when the body is streamed or the method is :head.
+      # @yield [chunk] if the method is not :head, successive chunks of the response body will be yielded as strings
+      # @raise [NotImplementedError] if a subclass does not implement this method
+      def perform(method, uri, headers, expect, body=nil)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/riak/client/net_http_backend.rb

@@ -0,0 +1,49 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+require 'riak'
+
+module Riak
+  class Client
+    # Uses the Ruby standard library Net::HTTP to connect to Riak.
+    # We recommend using the CurbBackend, which will
+    # be preferred when the 'curb' library is available.
+    # Conforms to the Riak::Client::HTTPBackend interface.
+    class NetHTTPBackend < HTTPBackend
+      private
+      def perform(method, uri, headers, expect, data=nil) #:nodoc:
+        Net::HTTP.start(uri.host, uri.port) do |http|
+          request = Net::HTTP.const_get(method.to_s.camelize).new(uri.request_uri, headers)
+          case data
+          when String
+            request.body = data
+          when IO
+            request.body_stream = data
+          end
+          response = http.request(request)
+
+          if valid_response?(expect, response.code)
+            result = {:headers => response.to_hash, :code => response.code.to_i}
+            response.read_body {|chunk| yield chunk } if block_given?
+            if return_body?(method, response.code, block_given?)
+              result[:body] = response.body
+            end
+            result
+          else
+            raise FailedRequest.new(method, expect, response.code, response.to_hash, response.body)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/riak/failed_request.rb

@@ -0,0 +1,37 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+require 'riak'
+
+module Riak
+  # Exception raised when the expected response code from Riak
+  # fails to match the actual response code.
+  class FailedRequest < StandardError
+    include Util::Translation
+    # @return [Symbol] the HTTP method, one of :head, :get, :post, :put, :delete
+    attr_reader :method
+    # @return [Fixnum] the expected response code
+    attr_reader :expected
+    # @return [Fixnum] the received response code
+    attr_reader :code
+    # @return [Hash] the response headers
+    attr_reader :headers
+    # @return [String] the response body, if present
+    attr_reader :body
+
+    def initialize(method, expected_code, received_code, headers, body)
+      @method, @expected, @code, @headers, @body = method, expected_code, received_code, headers, body
+      super t("failed_request", :expected => @expected.inspect, :code => @code, :body => @body)
+    end
+  end
+end

data/lib/riak/i18n.rb

@@ -0,0 +1,20 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+begin
+  require 'active_support/i18n'
+rescue LoadError
+  require 'i18n' # support ActiveSupport < 3
+end
+
+I18n.load_path << File.expand_path("../locale/en.yml", __FILE__)

data/lib/riak/invalid_response.rb

@@ -0,0 +1,25 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+require 'riak'
+
+module Riak
+  # Raised when Riak returns a response that is in an unexpected format
+  class InvalidResponse < StandardError
+    def initialize(expected, received, extra="")
+      expected = expected.inspect if Hash === expected
+      received = received.inspect if Hash === received
+      super "Expected #{expected} but received #{received} from Riak #{extra}"
+    end
+  end
+end

data/lib/riak/link.rb

@@ -0,0 +1,73 @@
+# Copyright 2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+require 'riak'
+
+module Riak
+  # Represents a link from one object to another in Riak
+  class Link
+    include Util::Translation
+    # @return [String] the URL (relative or absolute) of the related resource
+    attr_accessor :url
+
+    # @return [String] the relationship ("rel") of the other resource to this one
+    attr_accessor :rel
+    alias :tag :rel
+    alias :tag= :rel=
+
+    # @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
+
+    def initialize(url, rel)
+      @url, @rel = url, rel
+    end
+
+    # @return [String] bucket_name, if the Link url is a known Riak link ("/riak/<bucket>/<key>")
+    def bucket
+      URI.unescape($1) if url =~ %r{^/[^/]+/([^/]+)/?}
+    end
+    
+    # @return [String] key, if the Link url is a known Riak link ("/riak/<bucket>/<key>")
+    def key
+      URI.unescape($1) if url =~ %r{^/[^/]+/[^/]+/([^/]+)/?}
+    end
+
+    def inspect; to_s; end
+
+    def to_s
+      %Q[<#{@url}>; riaktag="#{@rel}"]
+    end
+
+    def hash
+      self.to_s.hash
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def ==(other)
+      other.is_a?(Link) && url == other.url && rel == other.rel
+    end
+
+    def to_walk_spec
+      raise t("bucket_link_conversion") if @rel == "up" || key.nil?
+      WalkSpec.new(:bucket => bucket, :tag => @rel)
+    end
+  end
+end