riak-client 2.1.0 → 2.2.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca7b5752fe722de4af5c0adceec72adf47c80241
-  data.tar.gz: 0a2b4e34fefb8b5c7a9ecef6fd06d8372616ba2c
+  metadata.gz: 516d08bb526f4cffe8b94314f766a3424e58b884
+  data.tar.gz: 317c345920e67e8035662a5ecf7ab6aaf5533774
 SHA512:
-  metadata.gz: 43600350e10122607eaca375a69225285a28403041e231d3bf527c04c90fedde75fc7136f7bd626d3ea448e0ecfd4deed10e8707e6a12605077662edb72a60f0
-  data.tar.gz: 1b3e910ec530a8d9e41a333b376918608aac4398be8b15af478978323e22f94cd407e008a43135c2f4bb12914e4e1ea998d88ac6acf19201242c3bd9eac6e0e9
+  metadata.gz: 9b251487856bf8dfba41427a8f1370a97541662d47c5047ee5d6a5f7f2b7567630a32b741cd821ce2320adae76ca4e334672f6fef267e7b7117941b1b77c1d0a
+  data.tar.gz: f4da60a9d5a7254e9541fa87e97fd32acd67da05a5024d972cb23e23ff1e30d93601c132266d29200eb907bdbcc9141495b6b7d490ea5f8f7f3ab3559dbc3ce6

data/Gemfile

@@ -5,7 +5,7 @@ gemspec
 group :guard do
   gem 'guard-rspec'
   gem 'rb-fsevent'
-  gem 'growl'
+  gem 'terminal-notifier-guard'
 end
 
 platforms :mri do
@@ -15,3 +15,5 @@ end
 platforms :jruby, :rbx do
   gem 'json'
 end
+
+gem 'beefcake', '1.1.0.pre1'

data/Guardfile

@@ -1,14 +1,20 @@
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
-gemset = ENV['RVM_GEMSET'] || 'ripple'
-gemset = "@#{gemset}" unless gemset.to_s == ''
 
-rvms = %w[ 1.8.7 1.9.2 1.9.3 ].map do |version|
-  "#{version}@#{gemset}"
-end
-
-guard 'rspec', :cli => '--profile --tag "~slow"', :rvm => rvms do
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rsspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separetly)
+#  * 'just' rspec: 'rspec'
+guard :rspec, cmd: 'bundle exec rspec', all_after_pass: true, all_on_start: true do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec/riak" }
+  watch(%r{^lib/riak/(.+)\.rb$})     { |m| "spec/riak/#{m[1]}_spec.rb" }
+  watch(%r{^lib/riak/client/}) { 'spec/riak/beefcake_protobuffs_backend' }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  watch(/^spec\/integration/) { 'spec:integration' }
 end
+

data/README.markdown

@@ -96,15 +96,40 @@ new_one.store
 
 ## Bucket Types
 
-Riak 2 uses [bucket types](http://docs.basho.com/riak/latest/dev/advanced/bucket-types/) to
-enable groups of similar buckets to share properties, configuration, and to namespace values
-within those buckets. Bucket type support is integral to how CRDTs work.
+Riak 2 uses [bucket types][1] to enable groups of similar buckets to share
+properties, configuration, and to namespace values within those buckets. Bucket
+type support is integral to how CRDTs work.
 
-Many operations take `type` options to perform them with a specific bucket type.
+[1]: http://docs.basho.com/riak/latest/dev/advanced/bucket-types
+
+In versions 2.2.0 and newer of this client, bucket types have a first-class
+representation, and can be used to create `BucketTyped::Bucket` objects that are
+namespaced differently from regular `Riak::Bucket` objects.
 
 ```ruby
 # This example assumes you have a "beverages" bucket type.
+beverages = client.bucket_type 'beverages'
+
+coffees = beverages.bucket 'coffees'
+untyped_coffees = client.bucket 'coffees'
+
+chapadao = coffees.new 'chapadao'
+chapadao.data = "Chapadao de Ferro"
+chapadao.store # stores this in the "beverages" bucket type
+
+untyped_coffees.get 'chapadao' # raises error, not found
+coffees.get 'chapadao' # succeeds
+
+chapadao.reload # succeeds
+
+untyped_coffees.delete 'chapadao' # silently fails to delete it
+chapadao.delete # deletes it
+coffees.delete 'chapadao' # deletes it
+```
 
+Client 2.0 and 2.1 code that uses the `type` argument to methods still works:
+
+```ruby
 coffees = client.bucket 'coffees'
 
 chapadao = coffees.new 'chapadao'
@@ -148,11 +173,14 @@ This documentation assumes there's a `yokozuna` bucket type created and activate
 ``` ruby
 # Create a client and bucket.
 client = Riak::Client.new
-bucket = client.bucket 'pizzas'
+bucket_type = client.bucket_type 'yokozuna'
+bucket = bucket_type.bucket 'pizzas'
 
 # Create an index and add it to a typed bucket. Setting the index on the bucket
 # may fail until the index creation has propagated.
-client.create_search_index 'pizzas'
+index = Riak::Search::Index.new 'pizzas'
+index.exist? #=> false
+index.create!
 client.set_bucket_props bucket, {search_index: 'pizzas'}, 'yokozuna'
 
 # Store some records for indexing
@@ -165,9 +193,18 @@ hawaiian.data = {toppings_ss: %w{ham pineapple}}
 hawaiian.store type: 'yokozuna'
 
 # Search the pizzas index for hashes that have a "ham" entry in the toppings_ss array
-result = client.search('pizzas', 'toppings_ss:ham') # Returns a results hash
-result['num_found'] # total number of results
-result['docs']      # the list of indexed documents
+query = Riak::Search::Query.new client, index, 'toppings_ss:ham'
+query.rows = 5 # return the first five pizzas
+
+result = query.results # returns a ResultsCollection object
+result.length # number of results returned
+result.num_found # total number of results found, including ones not returned
+
+pizza_result = result.first # a ResultDocument of the first pizza
+pizza_result.score # score of the match
+pizza_result.key # also pizza.bucket and pizza.bucket_type
+
+pizza = pizza_result.robject # load the actual RObject for the match
 ```
 
 ## Secondary Index Examples
@@ -482,6 +519,78 @@ The payload for each event contains the following keys:
 * `:client_id`: The client_id of the Riak client
 * `:_method_args`: The array of method arguments for the instrumented method. For instance, for `riak.get_object`, this value would resemble `[<Riak::Bucket ...>, 'key', {}]`
 
+## Running Specs
+
+We aim to have a comprehensive and fast set of tests, implemented using a modern,
+well-supported version of RSpec. These tests include both unit specs for
+individual classes, and integration specs that ensure the client works properly
+with an actual Riak instance.
+
+The [Riak Ruby Vagrant][1] virtual machine's Riak configuration is normally
+used to test this client in development. Once it's up and running, configure
+the Ruby `test_client.yml` on the host machine to connect to `pb_port: 17017`
+and test away.
+
+[1]: https://github.com/basho-labs/riak-ruby-vagrant
+
+Configuring the Riak node the tests connect to is done via the
+`spec/support/test_client.yml` file, which is loaded into a Ruby hash with
+symbolized keys, and passed to `Riak::Client.new`.
+
+```yml
+# test_client.yml
+pb_port: 10017
+# UNCOMMENT AUTHENTICATION SECTION WHEN RIAK HAS SECURITY ENABLED
+# authentication:
+#   user: user
+#   password: password
+#   ca_file: spec/support/certs/ca.crt
+```
+
+### Spec dependencies
+
+Specs depend on the following Riak configurations:
+
+* The **LevelDB backend** is necessary for testing secondary indexes.
+* **allow_mult** is required for many features: conflict resolution, and legacy
+  counters among them.
+* **Riak Search 2.0** ("Yokozuna") must be configured for testing full-text
+  search.
+
+The following bucket types are used during testing:
+
+```shell
+riak-admin bucket-type create counters '{"props":{"datatype":"counter", "allow_mult":true}}'
+riak-admin bucket-type create other_counters '{"props":{"datatype":"counter", "allow_mult":true}}'
+riak-admin bucket-type create maps '{"props":{"datatype":"map", "allow_mult":true}}'
+riak-admin bucket-type create sets '{"props":{"datatype":"set", "allow_mult":true}}'
+riak-admin bucket-type create yokozuna '{"props":{}}'
+
+riak-admin bucket-type activate other_counters
+riak-admin bucket-type activate counters
+riak-admin bucket-type activate maps
+riak-admin bucket-type activate sets
+riak-admin bucket-type activate yokozuna
+```
+
+Client tests run both with and without security enabled, as we have to test
+several positive and negative paths. The tests broadly depend on these users
+and roles:
+
+```shell
+riak-admin security add-user user password=password
+riak-admin security add-user certuser
+
+riak-admin security add-source user 0.0.0.0/0 password
+riak-admin security add-source certuser 0.0.0.0/0 certificate
+
+riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete,\
+riak_kv.index,riak_kv.list_keys,riak_kv.list_buckets,\
+riak_core.get_bucket,riak_core.set_bucket,\
+riak_core.get_bucket_type,riak_core.set_bucket_type,\
+search.admin,search.query,riak_kv.mapreduce on any to user
+```
+
 ## How to Contribute
 
 * Fork the project on [Github](http://github.com/basho/riak-ruby-client).  If you have already forked, use `git pull --rebase` to reapply your changes on top of the mainline. Example:

data/lib/riak/bucket.rb

@@ -239,7 +239,22 @@ module Riak
 
     # @return [String] a representation suitable for IRB and debugging output
     def inspect
-      "#<Riak::Bucket {#{name}}#{" keys=[#{keys.join(',')}]" if defined?(@keys)}>"
+      "#<Riak::Bucket {#{name}}>"
+    end
+
+    # Pretty prints the bucket for `pp` or `pry`.
+    def pretty_print(pp)
+      pp.object_group self do
+        pp.breakable
+        pp.text "name=#{name}"
+      end
+    end
+
+    # Does this {Bucket} have a non-default bucket type? {BucketTyped::Bucket}
+    # instances with non-default types return `true`.
+    # @return [Boolean] false
+    def needs_type?
+      false
     end
 
     # @return [true,false] whether the other is equivalent

data/lib/riak/bucket_properties.rb

@@ -0,0 +1,67 @@
+require 'riak'
+
+module Riak
+  # Provides a predictable and useful interface to bucket properties. Allows
+  # reading, reloading, and setting new values for bucket properties.
+  class BucketProperties
+    attr_reader :client
+    attr_reader :bucket
+
+    # Create a properties object for a bucket (including bucket-typed buckets).
+    # @param [Riak::Bucket, Riak::BucketTyped::Bucket] bucket
+    def initialize(bucket)
+      @bucket = bucket
+      @client = bucket.client
+    end
+
+    # Clobber the cached properties, and reload them from Riak.
+    def reload
+      @cached_props = nil
+      cached_props
+      true
+    end
+
+    # Write bucket properties and invalidate the cache in this object.
+    def store
+      client.backend do |be|
+        be.bucket_properties_operator.put bucket, cached_props
+      end
+      @cached_props = nil
+      return true
+    end
+
+    # Take bucket properties from a given {Hash} or {Riak::BucketProperties} 
+    # object.
+    # @param [Hash<String, Object>, Riak::BucketProperties] other
+    def merge!(other)
+      cached_props.merge! other
+    end
+
+    # Convert the cached properties into a hash for merging.
+    # @return [Hash<String, Object>] the bucket properties in a {Hash}
+    def to_hash
+      cached_props
+    end
+
+    # Read a bucket property
+    # @param [String] property_name
+    # @return [Object] the bucket property's value
+    def [](property_name)
+      cached_props[property_name.to_s]
+    end
+
+    # Write a bucket property
+    # @param [String] property_name
+    # @param [Object] value
+    def []=(property_name, value)
+      cached_props[property_name.to_s] = value
+    end
+
+    private
+    def cached_props
+      @cached_props ||= client.backend do |be|
+        be.bucket_properties_operator.get bucket
+      end
+    end
+  end
+end

data/lib/riak/bucket_type.rb

@@ -0,0 +1,48 @@
+require 'riak/bucket_typed/bucket'
+
+module Riak
+  # A representation of a bucket type
+  class BucketType
+    attr_reader :client, :name
+
+    # The name of Riak's default bucket type.
+    DEFAULT_NAME = 'default'
+
+    # Create a bucket type object manually.
+    # @param [Client] client the {Riak::Client} for this bucket type
+    # @param [String] name the name of this bucket type
+    def initialize(client, name)
+      @client, @name = client, name
+    end
+
+    # Is this bucket type the default?
+    # @return [Boolean]
+    def default?
+      name == DEFAULT_NAME
+    end
+
+    # Get a bucket of this type
+    # @param [String] bucket_name the name of this bucket
+    def bucket(bucket_name)
+      BucketTyped::Bucket.new client, bucket_name, self
+    end
+
+    # Pretty prints the bucket for `pp` or `pry`.
+    def pretty_print(pp)
+      pp.object_group self do
+        pp.breakable
+        pp.text "name=#{name}"
+      end
+    end
+
+    # Get the properties of this bucket type
+    # @return [Hash<Symbol,Object>]
+    def properties
+      @properties ||= client.backend do |be|
+        be.get_bucket_type_props name
+      end
+    end
+    alias :props :properties
+
+  end
+end

data/lib/riak/bucket_typed/bucket.rb

@@ -0,0 +1,113 @@
+require 'riak/bucket'
+require 'riak/bucket_type'
+
+module Riak
+  
+  # Container module for subclasses of objects with bucket type data attached.
+  # Currently only used for {BucketTyped::Bucket}.
+  module BucketTyped
+  
+    # A bucket that has a {BucketType} attached to it. Normally created using
+    # the {BucketType#bucket} method. Inherits most of its behavior from the
+    # {Riak::Bucket} class.
+    class Bucket < Riak::Bucket
+      
+      # @return [BucketType] the bucket type used with this bucket
+      attr_reader :type
+
+      # Create a bucket-typed bucket manually.
+      # @param [Client] client the {Riak::Client} for this bucket
+      # @param [String] name the name of this bucket
+      # @param [BucketType,String] type the bucket type of this bucket
+      def initialize(client, name, type)
+        if type.is_a? String
+          type = client.bucket_type type
+        elsif !(type.is_a? BucketType)
+          raise ArgumentError, t('argument_error.bucket_type', bucket_type: type)
+        end
+
+        @type = type
+
+        super client, name
+      end
+
+      # Retrieve an object from within the bucket type and 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={  })
+        super key, o(options)
+      end
+      alias :[] :get
+
+      # 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
+      # @option options [String] :vclock - the vector clock of the
+      #   object being deleted
+      def delete(key, options={  })
+        super key, o(options)
+      end
+
+      # 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 returned to the caller.
+      # @yield [Array<String>] a list of keys from the current chunk
+      # @return [Array<String>] Keys in this bucket
+      # @note This operation has serious performance implications and
+      #    should not be used in production applications.
+      def keys(options={  }, &block)
+        super o(options), &block
+      end
+
+      # @return [String] a friendly representation of this bucket-typed bucket
+      def inspect
+        "#<Riak::BucketTyped::Bucket {#{ type.name }/#{ name }}>"
+      end
+
+      def props=(new_props)
+        raise ArgumentError, t('hash_type', hash: new_props.inspect) unless new_props.is_a? Hash
+        complete_props = props.merge new_props
+        @client.set_bucket_props(self, complete_props, self.type.name)
+      end
+
+      def props
+        @props ||= @client.get_bucket_props(self, type: self.type.name)
+      end
+
+      def clear_props
+        @props = nil
+        @client.clear_bucket_props(self, type: self.type.name)
+      end
+
+      # Pretty prints the bucket for `pp` or `pry`.
+      def pretty_print(pp)
+        pp.object_group self do
+          pp.breakable
+          pp.text "bucket_type="
+          type.pretty_print(pp)
+          pp.breakable
+          pp.text "name=#{name}"
+        end
+      end
+
+      # Does this {BucketTyped::Bucket} have a non-default bucket type?
+      # @return [Boolean] true if this bucket has a non-default type.
+      def needs_type?
+        return true unless type.default?
+        return false
+      end
+
+      private
+      # merge in the type name with options
+      def o(options)
+        { type: type.name }.merge options
+      end
+    end
+  end
+end

data/lib/riak/client/beefcake/bucket_properties_operator.rb

@@ -0,0 +1,178 @@
+class Riak::Client::BeefcakeProtobuffsBackend
+  def bucket_properties_operator
+    BucketPropertiesOperator.new(self)
+  end
+
+
+  class BucketPropertiesOperator
+    attr_reader :backend
+
+    QUORUMS = Riak::Client::ProtobuffsBackend::QUORUMS
+
+    def initialize(backend)
+      @backend = backend
+    end
+
+    def get(bucket, options={})
+      response = backend.protocol do |p|
+        p.write :GetBucketReq, get_request(bucket, options)
+        p.expect :GetBucketResp, RpbGetBucketResp
+      end
+
+      properties = response.props.to_hash.stringify_keys
+
+      return rubyfy(properties)
+    end
+
+    def put(bucket, props={}, options={})
+      properties = riakify props
+
+      request = put_request bucket, properties, options
+      
+      backend.protocol do |p|
+        p.write :SetBucketReq, request
+        p.expect :SetBucketResp
+      end
+    end
+
+    private
+    def rubyfy(received_properties)
+      props = received_properties.dup
+
+      rubyfy_quorums(props)
+      rubyfy_hooks(props)
+      rubyfy_modfuns(props)
+      
+      return props
+    end
+
+    def riakify(requested_properties)
+      props = requested_properties.stringify_keys
+
+      riakify_quorums(props)
+      riakify_hooks(props)
+      riakify_modfuns(props)
+      riakify_repl_mode(props)
+
+      return props
+    end
+
+    def rubyfy_quorums(props)
+      %w{r pr w pw dw rw}.each do |k|
+        next unless props[k]
+        next unless QUORUMS.values.include? props[k]
+
+        props[k] = QUORUMS.invert[props[k]]
+      end
+    end
+
+    def riakify_quorums(props)
+      %w{r pr w pw dw rw}.each do |k|
+        next unless props[k]
+        v = props[k].to_s
+        next unless QUORUMS.keys.include? v
+
+        props[k] = QUORUMS[v]
+      end
+    end
+
+    def rubyfy_hooks(props)
+      %w{precommit postcommit}.each do |k|
+        next unless props[k]
+        props[k] = props[k].map do |v|
+          next v[:name] if v[:name]
+          rubyfy_modfun(v[:modfun])
+        end
+      end
+    end
+
+    def riakify_hooks(props)
+      %w{precommit postcommit}.each do |k|
+        next unless v = props[k]
+
+        if v.is_a? Array
+          props[k] = v.map{ |e| riakify_single_hook(e) }
+        else
+          props[k] = [riakify_single_hook(v)]
+        end
+      end
+    end
+
+    def riakify_single_hook(hook)
+      message = RpbCommitHook.new
+
+      if hook.is_a? String
+        message.name = hook
+      elsif hook['name']
+        message.name = hook['name']
+      else
+        message.modfun = riakify_modfun(hook)
+      end
+      return message
+    end
+
+    def rubyfy_modfuns(props)
+      %w{chash_keyfun linkfun}.each do |k|
+        next if props[k].nil?
+        props[k] = rubyfy_modfun(props[k])
+      end
+    end
+
+    def riakify_modfuns(props)
+      %w{chash_keyfun linkfun}.each do |k|
+        next if props[k].nil?
+        props[k] = riakify_modfun(props[k])
+      end
+    end
+
+    def rubyfy_modfun(modfun)
+      { 
+        'mod' => modfun[:module],
+        'fun' => modfun[:function]
+      }
+    end
+
+    def riakify_modfun(modfun)
+      m = modfun.stringify_keys
+      RpbModFun.new(module: m['mod'], function: m['fun'])
+    end
+
+    def riakify_repl_mode(props)
+      return unless props['repl'].is_a? Symbol
+
+      props['repl'] = case props['repl']
+                      when :false
+                        0
+                      when :realtime
+                        1
+                      when :fullsync
+                        2
+                      when :true
+                        3
+                      end
+    end
+    
+    def name_options(bucket)
+      o = {}
+      if bucket.is_a? Riak::Bucket
+        o[:bucket] = bucket.name 
+        o[:type] = bucket.type.name if bucket.needs_type?
+      else
+        o[:bucket] = bucket
+      end
+      
+      return o
+    end
+
+    def get_request(bucket, options)
+      RpbGetBucketReq.new options.merge name_options(bucket)
+    end
+
+    def put_request(bucket, props, options)
+      req_options = options.merge name_options(bucket)
+      req_options[:props] = RpbBucketProps.new props.symbolize_keys
+
+      RpbSetBucketReq.new req_options
+    end
+  end
+end