RubyGems - ripple - Versions diffs - 0.5.0 - Mend

ripple 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

data/.document +5 -0
data/.gitignore +26 -0
data/LICENSE +13 -0
data/README.textile +126 -0
data/RELEASE_NOTES.textile +24 -0
data/Rakefile +61 -0
data/VERSION +1 -0
data/lib/riak.rb +45 -0
data/lib/riak/bucket.rb +105 -0
data/lib/riak/client.rb +138 -0
data/lib/riak/client/curb_backend.rb +63 -0
data/lib/riak/client/http_backend.rb +209 -0
data/lib/riak/client/net_http_backend.rb +49 -0
data/lib/riak/failed_request.rb +37 -0
data/lib/riak/i18n.rb +15 -0
data/lib/riak/invalid_response.rb +25 -0
data/lib/riak/link.rb +54 -0
data/lib/riak/locale/en.yml +37 -0
data/lib/riak/map_reduce.rb +240 -0
data/lib/riak/map_reduce_error.rb +20 -0
data/lib/riak/robject.rb +234 -0
data/lib/riak/util/headers.rb +44 -0
data/lib/riak/util/multipart.rb +52 -0
data/lib/riak/util/translation.rb +29 -0
data/lib/riak/walk_spec.rb +113 -0
data/lib/ripple.rb +48 -0
data/lib/ripple/core_ext/casting.rb +96 -0
data/lib/ripple/document.rb +60 -0
data/lib/ripple/document/attribute_methods.rb +111 -0
data/lib/ripple/document/attribute_methods/dirty.rb +52 -0
data/lib/ripple/document/attribute_methods/query.rb +49 -0
data/lib/ripple/document/attribute_methods/read.rb +38 -0
data/lib/ripple/document/attribute_methods/write.rb +36 -0
data/lib/ripple/document/bucket_access.rb +38 -0
data/lib/ripple/document/finders.rb +84 -0
data/lib/ripple/document/persistence.rb +93 -0
data/lib/ripple/document/persistence/callbacks.rb +48 -0
data/lib/ripple/document/properties.rb +85 -0
data/lib/ripple/document/validations.rb +44 -0
data/lib/ripple/embedded_document.rb +38 -0
data/lib/ripple/embedded_document/persistence.rb +46 -0
data/lib/ripple/i18n.rb +15 -0
data/lib/ripple/locale/en.yml +16 -0
data/lib/ripple/property_type_mismatch.rb +23 -0
data/lib/ripple/translation.rb +24 -0
data/ripple.gemspec +159 -0
data/spec/fixtures/cat.jpg +0 -0
data/spec/fixtures/multipart-blank.txt +7 -0
data/spec/fixtures/multipart-with-body.txt +16 -0
data/spec/riak/bucket_spec.rb +141 -0
data/spec/riak/client_spec.rb +169 -0
data/spec/riak/curb_backend_spec.rb +50 -0
data/spec/riak/headers_spec.rb +34 -0
data/spec/riak/http_backend_spec.rb +136 -0
data/spec/riak/link_spec.rb +50 -0
data/spec/riak/map_reduce_spec.rb +347 -0
data/spec/riak/multipart_spec.rb +36 -0
data/spec/riak/net_http_backend_spec.rb +28 -0
data/spec/riak/object_spec.rb +444 -0
data/spec/riak/walk_spec_spec.rb +208 -0
data/spec/ripple/attribute_methods_spec.rb +149 -0
data/spec/ripple/bucket_access_spec.rb +48 -0
data/spec/ripple/callbacks_spec.rb +86 -0
data/spec/ripple/document_spec.rb +35 -0
data/spec/ripple/embedded_document_spec.rb +52 -0
data/spec/ripple/finders_spec.rb +146 -0
data/spec/ripple/persistence_spec.rb +89 -0
data/spec/ripple/properties_spec.rb +195 -0
data/spec/ripple/ripple_spec.rb +43 -0
data/spec/ripple/validations_spec.rb +64 -0
data/spec/spec.opts +1 -0
data/spec/spec_helper.rb +32 -0
data/spec/support/http_backend_implementation_examples.rb +215 -0
data/spec/support/mock_server.rb +58 -0
metadata +221 -0

data/.document ADDED

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore ADDED

@@ -0,0 +1,26 @@
+## MAC OS
+.DS_Store
+## TEXTMATE
+*.tmproj
+tmtags
+## EMACS
+*~
+\#*
+.\#*
+## VIM
+*.swp
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+## PROJECT::SPECIFIC
+_notes
+doc
+.yardoc
+create
+update-rails

data/LICENSE ADDED

@@ -0,0 +1,13 @@
+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.

data/README.textile ADDED

@@ -0,0 +1,126 @@
+h1. ripple
+ripple is a rich Ruby client for Riak, Basho's distributed database. It includes two namespaces:
+* @Riak@ contains a basic wrapper around typical operations, including bucket manipulation, object CRUD, link-walking, and map-reduce.
+* @Ripple@ contains an ActiveModel-compatible modeling layer that is inspired by ActiveRecord, DataMapper, and MongoMapper.
+h2. Dependencies
+ripple requires Ruby 1.8.7 or later and versions 3 or above of ActiveModel and ActiveSupport (and their dependencies, including i18n).  Please see the Rails 3 beta release notes for installing those gems.  I highly recommend the "curb":http://curb.rubyforge.org/ gem for better HTTP client performance.
+In development, you will also need these gems:
+* jeweler
+* rspec >= 1.3
+* fakeweb >= 1.2
+* curb >= 0.6
+* rack >= 1.0
+* yard >= 0.5.2
+h2. Basic Example
+<notextile><pre>require 'riak'
+# Create a client interface
+client = Riak::Client.new
+# Retrieve a bucket
+bucket = client.bucket("doc")  # a Riak::Bucket
+# Get an object from the bucket
+object = bucket.get("index.html")   # a Riak::RObject
+# Change the object's data and save
+object.data = "<html><body>Hello, world!</body></html>"
+object.store
+# Reload an object you already have
+object.reload                  # Works if you have the key and vclock, using conditional GET
+object.reload :force => true   # Reloads whether you have the vclock or not
+# Access more like a hash, client[bucket][key]
+client['doc']['index.html']   # the Riak::RObject
+# Create a new object
+new_one = Riak::RObject.new(bucket, "application.js")
+new_one.content_type = "application/javascript" # You must set the content type.
+new_one.data = "alert('Hello, World!')"
+new_one.store</pre></notextile>
+h2. Map-Reduce Example
+<notextile><pre>
+# Assuming you've already instantiated a client, get the album titles for The Beatles
+results = Riak::MapReduce.new(client).
+                add("artists","Beatles").
+                link(:bucket => "albums").
+                map("function(v){ return [JSON.parse(v.values[0].data).title]; }", :keep => true).run
+p results # => ["Please Please Me", "With The Beatles", "A Hard Day's Night",
+          #     "Beatles For Sale", "Help!", "Rubber Soul",
+          #     "Revolver", "Sgt. Pepper's Lonely Hearts Club Band", "Magical Mystery Tour",
+          #     "The Beatles", "Yellow Submarine", "Abbey Road", "Let It Be"]</pre></notextile>
+h2. Document model Example
+<notextile><pre>
+require 'ripple'
+class Email
+  include Ripple::Document
+  property :from,    String, :presence => true
+  property :to,      String, :presence => true
+  property :sent,    Time,   :default => proc { Time.now }
+  property :body,    String
+end
+email = Email.find("37458abc752f8413e")  # GET /raw/emails/37458abc752f8413e
+email.from = "someone@nowhere.net"
+email.save                               # PUT /raw/emails/37458abc752f8413e
+reply = Email.new
+reply.from = "justin@bashoooo.com"
+reply.to   = "sean@geeemail.com"
+reply.body = "Riak is a good fit for scalable Ruby apps."
+reply.save                               # POST /raw/emails (Riak-assigned key)
+</pre></notextile>
+h2. How to Contribute
+* Fork the project on "Github":http://github.com/seancribbs/ripple.  If you have already forked, use @git pull --rebase@ to reapply your changes on top of the mainline. Example:
+  <notextile><pre>$ git checkout master
+$ git pull --rebase seancribbs master</pre></notextile>
+* Create a topic branch. If you've already created a topic branch, rebase it on top of changes from the mainline "master" branch. Examples:
+** New branch:
+  <pre>$ git checkout -b topic</pre>
+** Existing branch:
+  <pre>$ git rebase master</pre>
+* Write an RSpec example, set of examples, and/or Cucumber story that demonstrate the necessity and validity of your changes. *Patches without specs will most often be ignored. Just do it, you'll thank me later.* Documentation patches need no specs, of course.
+* Make your feature addition or bug fix. Make your specs and stories pass (green).
+* Run the suite using multiruby or rvm to ensure cross-version compatibility.
+* Cleanup any trailing whitespace in your code (try @whitespace-mode@ in Emacs, or "Remove Trailing Spaces in Document" in the "Text" bundle in Textmate).
+* Commit, do not mess with Rakefile or VERSION.  If related to an existing issue in the "tracker":http://github.com/seancribbs/ripple/issues, include "Closes #X" in the commit message (where X is the issue number).
+* Send me a pull request.
+h2. License & Copyright
+Copyright &copy;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":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.
+h2. Auxillary License
+The included photo (spec/fixtures/cat.jpg) is Copyright &copy;2009 "Sean Cribbs":http://seancribbs.com/, and is
+licensed under the "Creative Commons Attribution Non-Commercial 3.0":http://creativecommons.org/licenses/by-nc/3.0 license. !http://i.creativecommons.org/l/by-nc/3.0/88x31.png!

data/RELEASE_NOTES.textile ADDED

@@ -0,0 +1,24 @@
+h1. Ripple Release Notes
+h2. 0.5 Initial Release - 2010-02-10
+This is the first release of Ripple, which would not have been possible
+without the generous support of Sonian and Basho Technologies.  Many thanks.
+It includes:
+* A robust basic client, @Riak@, with:
+** multiple HTTP backends (curb, net/http)
+** sensible client defaults (local, default port)
+** bucket access and manipulation, including key-streaming
+** object reading, storing, deleting and reloading
+** automatic de-serialization of JSON, YAML, and Marshal (when given the right content type)
+** streaming POST/PUT bodies (when given an IO)
+** method-chained map-reduce job construction
+* A document-style modeling library, Ripple, with:
+** ActiveModel 3.0 compatibility
+** Property/attribute definition with automatic type-casting
+** Bucket selection based on class name, with single-bucket inheritance (configurable)
+** Validations
+** Dirty-tracking
+** Simple finders - all documents, by key
+** Reloading

data/Rakefile ADDED

@@ -0,0 +1,61 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ripple"
+    gem.summary = %Q{ripple is a rich Ruby client for Riak, Basho's distributed database.}
+    gem.description = %Q{ripple is a rich Ruby client for Riak, Basho's distributed database.  It includes all the basics of accessing and manipulating Riak buckets and objects, and an object mapper library for building a rich domain on top of Riak.}
+    gem.email = "seancribbs@gmail.com"
+    gem.homepage = "http://seancribbs.github.com/ripple"
+    gem.authors = ["Sean Cribbs"]
+    gem.add_development_dependency "rspec", ">= 1.3"
+    gem.add_development_dependency "fakeweb", ">=1.2"
+    gem.add_development_dependency "rack", ">=1.0"
+    gem.add_development_dependency "yard", ">=0.5.2"
+    gem.add_development_dependency "curb", ">=0.6"
+    gem.add_dependency "activesupport", "3.0.0.beta"
+    gem.add_dependency "activemodel", "3.0.0.beta"
+    gem.requirements << "`gem install curb` for better HTTP performance"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.rcov_opts = ['--exclude', 'lib\/spec,bin\/spec,config\/boot.rb,gems,spec_helper']
+end
+task :spec => :check_dependencies
+task :default => :spec
+require 'yard'
+YARD::Rake::YardocTask.new do |yard|
+  docfiles = FileList['lib/**/*.rb', 'README*', 'VERSION', 'LICENSE', 'RELEASE_NOTES.textile']
+  yard.files = docfiles
+  yard.options = ["--no-private"]
+end
+task :doc => :yard do
+  original_dir = Dir.pwd
+  docs_dir = File.expand_path(File.join(original_dir, "..", "ripple-docs"))
+  rm_rf File.join(docs_dir, "*")
+  cp_r File.join(original_dir, "doc", "."), docs_dir
+  touch File.join(docs_dir, '.nojekyll')
+end
+CLOBBER.include(".yardoc")
+CLOBBER.include("doc")

data/VERSION ADDED

	@@ -0,0 +1 @@
1	+ 0.5.0

data/lib/riak.rb ADDED

@@ -0,0 +1,45 @@
+# 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"
+  # Exceptions
+  autoload :FailedRequest,   "riak/failed_request"
+  autoload :InvalidResponse, "riak/invalid_response"
+  autoload :MapReduceError,  "riak/map_reduce_error"
+  module Util
+    autoload :Headers,       "riak/util/headers"
+    autoload :Multipart,     "riak/util/multipart"
+    autoload :Translation,   "riak/util/translation"
+  end
+end

data/lib/riak/bucket.rb ADDED

@@ -0,0 +1,105 @@
+# 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
+    # @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 = 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 = JSON.parse(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, name, {:props => false}, {}) do |chunk|
+          obj = JSON.parse(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, 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, 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={})
+      response = @client.http.get(200, @client.prefix, name, key, options, {})
+      RObject.new(self, key).load(response)
+    end
+    alias :[] :get
+    # @return [String] a representation suitable for IRB and debugging output
+    def inspect
+      "#<Riak::Bucket #{client.http.path(client.prefix, name).to_s}#{" keys=[#{keys.join(',')}]" if defined?(@keys)}>"
+    end
+  end
+end

data/lib/riak/client.rb ADDED

@@ -0,0 +1,138 @@
+# 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
+    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 ('/raw/') The URL path prefix to the "raw" 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]    || "/raw/"
+      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, 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