riak-client 0.7.0

data/Rakefile

@@ -0,0 +1,74 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+gemspec = Gem::Specification.new do |gem|
+  gem.name = "riak-client"
+  gem.summary = %Q{riak-client is a rich client for Riak, the distributed database by Basho.}
+  gem.description = %Q{riak-client is a rich client for Riak, the distributed database by Basho. It supports the full HTTP interface including storage operations, bucket configuration, link-walking and map-reduce.}
+  gem.version = File.read('../VERSION').strip
+  gem.email = "seancribbs@gmail.com"
+  gem.homepage = "http://seancribbs.github.com/ripple"
+  gem.authors = ["Sean Cribbs"]
+  gem.add_development_dependency "rspec", "~>2.0.0.beta.6"
+  gem.add_development_dependency "fakeweb", ">=1.2"
+  gem.add_development_dependency "rack", ">=1.0"
+  gem.add_development_dependency "curb", ">=0.6"
+  gem.add_dependency "activesupport", ">= 2.3.5"
+  gem.requirements << "`gem install curb` for better HTTP performance"
+
+  files = FileList["**/*"]
+  files.exclude /\.DS_Store/
+  files.exclude /\#/
+  files.exclude /~/
+  files.exclude /\.swp/
+  files.exclude '**/._*'
+  files.exclude '**/*.orig'
+  files.exclude '**/*.rej'
+  files.exclude /^pkg/
+  files.exclude 'riak-client.gemspec'
+
+  gem.files = files.to_a
+
+  gem.test_files = FileList["spec/**/*.rb"].to_a
+end
+
+# Gem packaging tasks
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+task :gem => :gemspec
+
+desc %{Build the gemspec file.}
+task :gemspec do
+  gemspec.validate
+  File.open("#{gemspec.name}.gemspec", 'w'){|f| f.write gemspec.to_ruby }
+end
+
+desc %{Release the gem to RubyGems.org}
+task :release => :gem do
+  "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run Unit Specs Only"
+Rspec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = "spec/riak/**/*_spec.rb"
+end
+
+namespace :spec do
+  desc "Run Integration Specs Only"
+  Rspec::Core::RakeTask.new(:integration) do |spec|
+    spec.pattern = "spec/integration/**/*_spec.rb"
+  end
+
+  desc "Run All Specs"
+  Rspec::Core::RakeTask.new(:all) do |spec|
+    spec.pattern = "spec/**/*_spec.rb"
+  end
+end
+
+task :default => :spec

data/lib/riak.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.
+$KCODE = "UTF8" if RUBY_VERSION < "1.9"
+
+require 'active_support/all'
+require 'active_support/json'
+require 'base64'
+require 'uri'
+require 'net/http'
+require 'yaml'
+require 'riak/i18n'
+
+# The Riak module contains all aspects of the HTTP client interface
+# to Riak.
+module Riak
+  # Domain objects
+  autoload :Bucket,          "riak/bucket"
+  autoload :Client,          "riak/client"
+  autoload :Link,            "riak/link"
+  autoload :WalkSpec,        "riak/walk_spec"
+  autoload :RObject,         "riak/robject"
+  autoload :MapReduce,       "riak/map_reduce"
+
+  # Cache store
+  autoload :CacheStore,      "riak/cache_store"
+
+  # Exceptions
+  autoload :FailedRequest,   "riak/failed_request"
+  autoload :InvalidResponse, "riak/invalid_response"
+  autoload :MapReduceError,  "riak/map_reduce_error"
+
+  module Util
+    autoload :Escape,        "riak/util/escape"
+    autoload :Headers,       "riak/util/headers"
+    autoload :Multipart,     "riak/util/multipart"
+    autoload :Translation,   "riak/util/translation"
+  end
+end

data/lib/riak/bucket.rb

@@ -0,0 +1,176 @@
+# 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 and encapsulates operations on a Riak bucket.  You may retrieve a bucket
+  # using {Client#bucket}, or create it manually and retrieve its meta-information later.
+  class Bucket
+    include Util::Translation
+    include Util::Escape
+
+    # @return [Riak::Client] the associated client
+    attr_reader :client
+
+    # @return [String] the bucket name
+    attr_reader :name
+
+    # @return [Hash] Internal Riak bucket properties.
+    attr_reader :props
+    alias_attribute :properties, :props
+
+    # Create a Riak bucket manually.
+    # @param [Client] client the {Riak::Client} for this bucket
+    # @param [String] name the name of the bucket
+    def initialize(client, name)
+      raise ArgumentError, t("client_type", :client => client.inspect) unless Client === client
+      raise ArgumentError, t("string_type", :string => name.inspect) unless String === name
+      @client, @name, @props = client, name, {}
+    end
+
+    # Load information for the bucket from a response given by the {Riak::Client::HTTPBackend}.
+    # Used mostly internally - use {Riak::Client#bucket} to get a {Bucket} instance.
+    # @param [Hash] response a response from {Riak::Client::HTTPBackend}
+    # @return [Bucket] self
+    # @see Client#bucket
+    def load(response={})
+      unless response.try(:[], :headers).try(:[],'content-type').try(:first) =~ /json$/
+        raise Riak::InvalidResponse.new({"content-type" => ["application/json"]}, response[:headers], t("loading_bucket", :name => name))
+      end
+      payload = ActiveSupport::JSON.decode(response[:body])
+      @keys = payload['keys'].map {|k| URI.unescape(k) }  if payload['keys']
+      @props = payload['props'] if payload['props']
+      self
+    end
+
+    # Accesses or retrieves a list of keys in this bucket.
+    # If a block is given, keys will be streamed through
+    # the block (useful for large buckets). When streaming,
+    # results of the operation will not be retained in the local Bucket object.
+    # @param [Hash] options extra options
+    # @yield [Array<String>] a list of keys from the current chunk
+    # @option options [Boolean] :reload (false) If present, will force reloading of the bucket's keys from Riak
+    # @return [Array<String>] Keys in this bucket
+    def keys(options={})
+      if block_given?
+        @client.http.get(200, @client.prefix, escape(name), {:props => false, :keys => 'stream'}, {}) do |chunk|
+          obj = ActiveSupport::JSON.decode(chunk) rescue {}
+          yield obj['keys'].map {|k| URI.unescape(k) } if obj['keys']
+        end
+      elsif @keys.nil? || options[:reload]
+        response = @client.http.get(200, @client.prefix, escape(name), {:props => false}, {})
+        load(response)
+      end
+      @keys
+    end
+
+    # Sets internal properties on the bucket
+    # Note: this results in a request to the Riak server!
+    # @param [Hash] properties new properties for the bucket
+    # @return [Hash] the properties that were accepted
+    # @raise [FailedRequest] if the new properties were not accepted by the Riak server
+    def props=(properties)
+      raise ArgumentError, t("hash_type", :hash => properties.inspect) unless Hash === properties
+      body = {'props' => properties}.to_json
+      @client.http.put(204, @client.prefix, escape(name), body, {"Content-Type" => "application/json"})
+      @props = properties
+    end
+
+    # Retrieve an object from within the bucket.
+    # @param [String] key the key of the object to retrieve
+    # @param [Hash] options query parameters for the request
+    # @option options [Fixnum] :r - the read quorum for the request - how many nodes should concur on the read
+    # @return [Riak::RObject] the object
+    # @raise [FailedRequest] if the object is not found or some other error occurs
+    def get(key, options={})
+      code = allow_mult ? [200,300] : 200
+      response = @client.http.get(code, @client.prefix, escape(name), escape(key), options, {})
+      RObject.new(self, key).load(response)
+    end
+    alias :[] :get
+
+    # Create a new blank object
+    # @param [String] key the key of the new object
+    # @return [RObject] the new, unsaved object
+    def new(key=nil)
+      RObject.new(self, key).tap do |obj|
+        obj.content_type = "application/json"
+      end
+    end
+
+    # Fetches an object if it exists, otherwise creates a new one with the given key
+    # @param [String] key the key to fetch or create
+    # @return [RObject] the new or existing object
+    def get_or_new(key, options={})
+      begin
+        get(key, options)
+      rescue Riak::FailedRequest => fr
+        if fr.code.to_i == 404
+          new(key)
+        else
+          raise fr
+        end
+      end
+    end
+
+    # Checks whether an object exists in Riak.
+    # @param [String] key the key to check
+    # @param [Hash] options quorum options
+    # @option options [Fixnum] :r - the read quorum value for the request (R)
+    # @return [true, false] whether the key exists in this bucket
+    def exists?(key, options={})
+      result = client.http.head([200,404], client.prefix, escape(name), escape(key), options, {})
+      result[:code] == 200
+    end
+    alias :exist? :exists?
+
+    # Deletes a key from the bucket
+    # @param [String] key the key to delete
+    # @param [Hash] options quorum options
+    # @option options [Fixnum] :rw - the read/write quorum for the delete
+    def delete(key, options={})
+      client.http.delete([204,404], client.prefix, escape(name), escape(key), options, {})
+    end
+
+    # @return [true, false] whether the bucket allows divergent siblings
+    def allow_mult
+      props['allow_mult']
+    end
+
+    # Set the allow_mult property.  *NOTE* This will result in a PUT request to Riak.
+    # @param [true, false] value whether the bucket should allow siblings
+    def allow_mult=(value)
+      self.props = {'allow_mult' => value}
+      value
+    end
+
+    # @return [Fixnum] the N value, or number of replicas for this bucket
+    def n_value
+      props['n_val']
+    end
+
+    # Set the N value (number of replicas). *NOTE* This will result in a PUT request to Riak.
+    # Setting this value after the bucket has objects stored in it may have unpredictable results.
+    # @param [Fixnum] value the number of replicas the bucket should keep of each object
+    def n_value=(value)
+      self.props = {'n_val' => value}
+      value
+    end
+
+    # @return [String] a representation suitable for IRB and debugging output
+    def inspect
+      "#<Riak::Bucket #{client.http.path(client.prefix, escape(name)).to_s}#{" keys=[#{keys.join(',')}]" if defined?(@keys)}>"
+    end
+  end
+end

data/lib/riak/cache_store.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'
+module Riak
+  class CacheStore < ActiveSupport::Cache::Store
+    attr_accessor :client
+
+    def initialize(options = {})
+      @bucket_name = options.delete(:bucket) || '_cache'
+      @n_value = options.delete(:n_value) || 2
+      @r = [options.delete(:r) || 1, @n_value].min
+      @w = [options.delete(:w) || 1, @n_value].min
+      @dw = [options.delete(:dw) || 0, @n_value].min
+      @rw = [options.delete(:rw) || 1, @n_value].min
+      @client = Riak::Client.new(options)
+    end
+
+    def bucket
+      @bucket ||= @client.bucket(@bucket_name, :keys => false).tap do |b|
+        begin
+          b.n_value = @n_value unless b.n_value == @n_value
+        rescue
+        end
+      end
+    end
+    
+    def write(key, value, options={})
+      super do
+        object = bucket.get_or_new(key, :r => @r)
+        object.content_type = 'application/yaml'
+        object.data = value
+        object.store(:r => @r, :w => @w, :dw => @dw)
+      end
+    end
+
+    def read(key, options={})
+      super do
+        begin
+          bucket.get(key, :r => @r).data
+        rescue Riak::FailedRequest => fr
+          raise fr unless fr.code == 404
+          nil
+        end
+      end
+    end
+
+    def exist?(key)
+      super do
+        bucket.exists?(key, :r => @r)
+      end
+    end
+
+    def delete_matched(matcher, options={})
+      super do
+        bucket.keys do |keys|
+          keys.grep(matcher).each do |k|
+            bucket.delete(k, :rw => @rw)
+          end
+        end
+      end
+    end
+
+    def delete(key, options={})
+      super do
+        bucket.delete(key, :rw => @rw)
+      end
+    end
+  end
+end
+
+ActiveSupport::Cache::RiakStore = Riak::CacheStore unless defined?(ActiveSupport::Cache::RiakStore)

data/lib/riak/client.rb

@@ -0,0 +1,139 @@
+# 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
+  # A client connection to Riak.
+  class Client
+    include Util::Translation
+    include Util::Escape
+
+    autoload :HTTPBackend,    "riak/client/http_backend"
+    autoload :NetHTTPBackend, "riak/client/net_http_backend"
+    autoload :CurbBackend,    "riak/client/curb_backend"
+
+    # When using integer client IDs, the exclusive upper-bound of valid values.
+    MAX_CLIENT_ID = 4294967296
+
+    # Regexp for validating hostnames, lifted from uri.rb in Ruby 1.8.6
+    HOST_REGEX = /^(?:(?:(?:[a-zA-Z\d](?:[-a-zA-Z\d]*[a-zA-Z\d])?)\.)*(?:[a-zA-Z](?:[-a-zA-Z\d]*[a-zA-Z\d])?)\.?|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[(?:(?:[a-fA-F\d]{1,4}:)*(?:[a-fA-F\d]{1,4}|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})|(?:(?:[a-fA-F\d]{1,4}:)*[a-fA-F\d]{1,4})?::(?:(?:[a-fA-F\d]{1,4}:)*(?:[a-fA-F\d]{1,4}|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}))?)\])$/n
+
+    # @return [String] The host or IP address for the Riak endpoint
+    attr_reader :host
+
+    # @return [Fixnum] The port of the Riak HTTP endpoint
+    attr_reader :port
+
+    # @return [String] The internal client ID used by Riak to route responses
+    attr_reader :client_id
+
+    # @return [String] The URL path prefix to the "raw" HTTP endpoint
+    attr_accessor :prefix
+
+    # @return [String] The URL path to the map-reduce HTTP endpoint
+    attr_accessor :mapred
+
+    # Creates a client connection to Riak
+    # @param [Hash] options configuration options for the client
+    # @option options [String] :host ('127.0.0.1') The host or IP address for the Riak endpoint
+    # @option options [Fixnum] :port (8098) The port of the Riak HTTP endpoint
+    # @option options [String] :prefix ('/riak/') The URL path prefix to the main HTTP endpoint
+    # @option options [String] :mapred ('/mapred') The path to the map-reduce HTTP endpoint
+    # @option options [Fixnum, String] :client_id (rand(MAX_CLIENT_ID)) The internal client ID used by Riak to route responses
+    # @raise [ArgumentError] raised if any options are invalid
+    def initialize(options={})
+      options.assert_valid_keys(:host, :port, :prefix, :client_id, :mapred)
+      self.host      = options[:host]      || "127.0.0.1"
+      self.port      = options[:port]      || 8098
+      self.client_id = options[:client_id] || make_client_id
+      self.prefix    = options[:prefix]    || "/riak/"
+      self.mapred    = options[:mapred]    || "/mapred"
+      raise ArgumentError, t("missing_host_and_port") unless @host && @port
+    end
+
+    # Set the client ID for this client. Must be a string or Fixnum value 0 =< value < MAX_CLIENT_ID.
+    # @param [String, Fixnum] value The internal client ID used by Riak to route responses
+    # @raise [ArgumentError] when an invalid client ID is given
+    # @return [String] the assigned client ID
+    def client_id=(value)
+      @client_id = case value
+                   when 0...MAX_CLIENT_ID
+                     b64encode(value)
+                   when String
+                     value
+                   else
+                     raise ArgumentError, t("invalid_client_id", :max_id => MAX_CLIENT_ID)
+                   end
+    end
+
+    # Set the hostname of the Riak endpoint. Must be an IPv4, IPv6, or valid hostname
+    # @param [String] value The host or IP address for the Riak endpoint
+    # @raise [ArgumentError] if an invalid hostname is given
+    # @return [String] the assigned hostname
+    def host=(value)
+      raise ArgumentError, t("hostname_invalid") unless String === value && value.present? && value =~ HOST_REGEX
+      @host = value
+    end
+
+    # Set the port number of the Riak endpoint. This must be an integer between 0 and 65535.
+    # @param [Fixnum] value The port number of the Riak endpoint
+    # @raise [ArgumentError] if an invalid port number is given
+    # @return [Fixnum] the assigned port number
+    def port=(value)
+      raise ArgumentError, t("port_invalid") unless (0..65535).include?(value)
+      @port = value
+    end
+
+    # Automatically detects and returns an appropriate HTTP backend.
+    # The HTTP backend is used internally by the Riak client, but can also
+    # be used to access the server directly.
+    # @return [HTTPBackend] the HTTP backend for this client
+    def http
+      @http ||= begin
+                  require 'curb'
+                  CurbBackend.new(self)
+                rescue LoadError, NameError
+                  warn t("install_curb")
+                  NetHTTPBackend.new(self)
+                end
+    end
+
+    # Retrieves a bucket from Riak.
+    # @param [String] bucket the bucket to retrieve
+    # @param [Hash] options options for retrieving the bucket
+    # @option options [Boolean] :keys (true) whether to retrieve the bucket keys
+    # @option options [Boolean] :props (true) whether to retreive the bucket properties
+    # @return [Bucket] the requested bucket
+    def bucket(name, options={})
+      options.assert_valid_keys(:keys, :props)
+      response = http.get(200, prefix, escape(name), options, {})
+      Bucket.new(self, name).load(response)
+    end
+    alias :[] :bucket
+
+    # @return [String] A representation suitable for IRB and debugging output.
+    def inspect
+      "#<Riak::Client #{http.root_uri.to_s}>"
+    end
+
+    private
+    def make_client_id
+      b64encode(rand(MAX_CLIENT_ID))
+    end
+
+    def b64encode(n)
+      Base64.encode64([n].pack("N")).chomp
+    end
+  end
+end