riak-client 1.4.5 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9016aab8aba93bb63aca3046534eda1a37d06df2
-  data.tar.gz: 7fe5882b0b6435b59f335c6dd55b2282f261cdee
+  metadata.gz: cc9b9f7497052c55bb844b4d367c34845e57ec5a
+  data.tar.gz: a40f43dc918e9f24a8cdfa52eee55eac6abe6cc7
 SHA512:
-  metadata.gz: b94915ad5556abb0383e804a63b1e1dd4eb95c948552a32c38f8c480a905f5a6d738bc5e1782e0d9f39aab5ae7979bdf09b0549214fa3f2fe4567d53e3165ad3
-  data.tar.gz: 07ab78ccb8117017897415215af4b08e605889a9f5b23f764ed52d7422eefabd329e66a7f4cf3ae5e3a8f59739bfbda1d0be933efc6be52cc5fa9f2d4999b16f
+  metadata.gz: 3d38360e5a71d50a8038fd18117c1e1bd4b525869d8e6f1215b85aa9ba7c22e3069ff795cbfac2bac6156f348feb48cd7951e32e1a0718511e40aa0d809dfd89
+  data.tar.gz: b0c5415b028c0d009cdca47c9c4ee620130ff60d4b320240a4a5593c343b232488c576f20b3602aff9b8dcf5256884de039d9dda8939ded6071b8d9a87c1dfea

data/.gitignore

@@ -27,7 +27,7 @@ _notes
 doc
 .yardoc
 .bundle
-spec/support/test_server.yml
+spec/support/test_client.yml
 Gemfile.lock
 **/bin
 *.rbc
@@ -38,3 +38,4 @@ Gemfile.lock
 vendor/erlang
 vendor/riak
 .ruby-version
+tmp

data/Gemfile

@@ -1,7 +1,6 @@
 source "https://rubygems.org"
 
 gemspec
-gem 'bundler'
 
 group :guard do
   gem 'guard-rspec'

data/README.markdown

@@ -7,13 +7,14 @@ and map-reduce.
 
 ## Dependencies
 
-`riak-client` requires i18n, builder, beefcake, and multi_json. For
-higher performance on HTTP requests, install the 'excon' gem. The
+Ruby 1.9.3, 2.0, and 2.1 are supported. JRuby in 1.9 and 2.0 modes are
+also supported. `riak-client` is not compatible with Ruby 1.8.
+
+`riak-client` requires i18n, builder, beefcake, and multi_json. The
 cache store implementation requires ActiveSupport 3 or later.
 
 Development dependencies are handled with bundler. Install bundler
-(`gem install bundler`) and run this command in each sub-project to
-get started:
+(`gem install bundler`) and run this command to get started:
 
 ``` bash
 $ bundle install
@@ -33,17 +34,30 @@ require 'riak'
 # Create a client interface
 client = Riak::Client.new
 
-# Create a client interface that uses Excon
-client = Riak::Client.new(:http_backend => :Excon)
-
-# Create a client that uses Protocol Buffers
-client = Riak::Client.new(:protocol => "pbc")
+# Create a client that uses secure Protocol Buffers
+client = Riak::Client.new(authentication: {
+      # certificate authority to validate the server cert
+      ca_file: '/home/zedo/ca.crt',
+
+      # username, required
+      user: 'zedo',
+      
+      # password for password-based authentication
+      password: 'catnip',
+
+      # client-cert authentication parameters support filenames,
+      # OpenSSL-compatible string data, or properly initialized
+      # OpenSSL objects
+      client_ca: '/home/zedo/ca.crt',
+      cert: File.read '/home/zedo/zedo.crt',
+      key: OpenSSL::PKey::RSA.new(File.read '/home/zedo/zedo.key')
+    })
 
 # Automatically balance between multiple nodes
 client = Riak::Client.new(:nodes => [
   {:host => '10.0.0.1'},
   {:host => '10.0.0.2', :pb_port => 1234},
-  {:host => '10.0.0.3', :http_port => 5678}
+  {:host => '10.0.0.3', :pb_port => 5678}
 ])
 
 # Retrieve a bucket
@@ -71,6 +85,36 @@ new_one.raw_data = "alert('Hello, World!')"
 new_one.store
 ```
 
+## Bucket Types
+
+Riak 2 uses [bucket types](http://docs.basho.com/riak/2.0.0pre11/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.
+
+Many operations take `type` options to perform them with a specific bucket type.
+
+```ruby
+# This example assumes you have a "beverages" bucket type.
+
+coffees = client.bucket 'coffees'
+
+chapadao = coffees.new 'chapadao'
+chapadao.data = "Chapadao de Ferro"
+chapadao.store type: 'beverages' # stores this in the "beverages" bucket type
+
+coffees.get 'chapadao' # raises error, not found
+coffees.get 'chapadao', type: 'beverages' # succeeds
+
+chapadao.reload # raises error, not found
+chapadao.reload type: 'beverages' # succeeds
+
+chapadao.delete # silently fails to delete it
+coffees.delete 'chapadao' # silently fails to delete it
+
+chapadao.delete type: 'beverages' # deletes it
+coffees.delete 'chapadao', type: 'beverages' # deletes it
+```
+
 ## Map-Reduce Example
 
 ``` ruby
@@ -80,9 +124,9 @@ results = Riak::MapReduce.new(client).
                 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",
+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",
+          #     "Revolver", "Sgt. Pepper's Lonely Hearts Club Band", "Magical Mystery Tour", 
           #     "The Beatles", "Yellow Submarine", "Abbey Road", "Let It Be"]
 ```
 
@@ -137,7 +181,7 @@ client['users'].disable_index!
 
 ## Secondary Index Examples
 
-Riak supports secondary indexes. Secondary indexing, or "2i," gives you the
+Riak supports secondary indexes. Secondary indexing, or "2i," gives you the 
 ability to tag objects with multiple queryable values at write time, and then
 query them later.
 
@@ -152,7 +196,7 @@ storage logic is in `lib/riak/rcontent.rb`.
 ```ruby
 object = bucket.get_or_new 'cobb.salad'
 
-# Indexes end with the "_bin" suffix to indicate they're binary or string
+# Indexes end with the "_bin" suffix to indicate they're binary or string 
 # indexes. They can have multiple values.
 object.indexes['ingredients_bin'] = %w{lettuce tomato bacon egg chives}
 
@@ -166,7 +210,7 @@ object.store
 
 ### Finding Objects
 
-Secondary index queries return a list of keys exactly matching a scalar or
+Secondary index queries return a list of keys exactly matching a scalar or 
 within a range.
 
 ```ruby
@@ -201,7 +245,157 @@ q.has_next_page? # => true
 q2 = q.next_page
 ```
 
-## Counter examples
+## Riak 2 Data Types
+
+Riak 2 features new distributed data structures: counters, sets, and maps 
+(containing counters, flags, maps, registers, and sets).  These are implemented 
+by the Riak database as Convergent Replicated Data Types.
+
+Riak data type support requires bucket types to be configured to support each
+top-level data type. If you're just playing around, use the 
+[Riak Ruby Vagrant](https://github.com/basho-labs/riak-ruby-vagrant) setup to
+get started with the appropriate configuration and bucket types quickly.
+
+The examples below presume that the appropriate bucket types are named
+`counters`, `maps`, and `sets`; these bucket type names are the client's defaults.
+Viewing and changing the defaults is easy:
+
+```ruby
+Riak::Crdt::DEFAULT_BUCKET_TYPES[:set] #=> "sets"
+
+Riak::Crdt::DEFAULT_BUCKET_TYPES[:set] = "a_cooler_set"
+```
+
+The top-level CRDT types have both immediate and batch mode. If you're doing
+multiple writes to a single top-level counter or set, or updating multiple map
+entries, batch mode will make fewer round-trips to Riak.
+
+Top-level CRDT types accept `nil` as a key. This allows Riak to assign a random
+key for them.
+
+Deleting CRDTs requires you to use the key-value API for the time being.
+
+```ruby
+brews = Riak::Crdt::Set.new bucket, 'brews'
+brews.add 'espresso'
+brews.add 'aeropress'
+
+bucket.delete brews.key, type: brews.bucket_type
+```
+
+
+### Counters
+
+Riak 2 integer counters have one operation: increment by an integer.
+
+```ruby
+counter = Riak::Crdt::Counter.new bucket, key
+
+counter.value #=> 15
+
+counter.increment
+
+counter.value #=> 16
+
+counter.increment 3
+
+counter.value #=> 19
+
+counter.decrement
+
+counter.value #=> 18
+```
+
+Counter operations can be batched:
+
+```ruby
+counter.batch do |c|
+  c.increment
+  c.increment 5
+end
+```
+
+### Maps
+
+Riak 2 maps can contain counters, flags (booleans), registers (strings), sets, and
+other maps.
+
+Maps are similar but distinct from the standard Ruby `Hash`. Entries are
+segregated by both name and type, so you can have counters, registers, and sets inside a map that all have the same name.
+
+```ruby
+map = Riak::Crdt::Map.new bucket, key
+
+map.counters['potatoes'].value #=> 5
+map.sets['potatoes'].include? 'yukon gold' #=> true
+
+map.sets['cacti'].value #=> #<Set: {"saguaro", "prickly pear", "fishhook"}>
+map.sets['cacti'].remove 'prickly pear'
+
+map.registers['favorite butterfly'] = 'the mighty monarch'
+
+map.flags['pet cat'] = true
+
+map.maps['atlantis'].registers['location'] #=> 'kennedy space center'
+
+map.counters.delete 'thermometers'
+```
+
+Maps are a prime candidate for batched operations:
+
+```ruby
+map.batch do |m|
+  m.counters['hits'].increment
+  m.sets['followers'].add 'basho_elevator'
+end
+```
+
+Frequently, you might want a map with a Riak-assigned name instead of one you
+come up with yourself:
+
+```ruby
+map = Riak::Crdt::Map.new bucket, nil
+
+map.registers['coat_pattern'] = 'tabby'
+
+map.key #=> "2do4NvcurWhXYNQg8HoIR9zedJV"
+```
+
+### Sets
+
+Sets are an unordered collection of entries.
+
+**PROTIP:** Ruby and Riak Ruby Client both have classes called `Set`. Be careful
+to refer to the Ruby version as `::Set` and the Riak client version as
+`Riak::Crdt::Set`.
+
+```ruby
+set = Riak::Crdt::Set.new bucket, key
+
+set.members #=> #<Set: {"Edinburgh", "Leeds", "London"}>
+
+set.add "Newcastle"
+set.remove "London"
+
+set.include? "Leeds" #=> true
+```
+
+Sets support batched operations:
+
+```ruby
+set.batch do |s|
+  s.add "York"
+  s.add "Aberdeen"
+  s.remove "Newcastle"
+end
+```
+
+### Client Implementation Notes
+
+The client code for these types is in the `Riak::Crdt` namespace, and mostly
+in the `lib/riak/crdt` directory.
+
+## Riak 1.4 Counters
 
 For more information about counters in Riak, see [the Basho wiki](http://docs.basho.com/riak/latest/dev/references/http/counters/).
 
@@ -253,55 +447,6 @@ ArgumentError: Counters can only be incremented or decremented by integers.
 
 That's about it. PN Counters in Riak are distributed, so each node will receive the proper increment/decrement operation. Enjoy using them.
 
-## Instrumentation
-
-The Riak client has built-in event hooks for all major over-the-wire operations including:
-
-* riak.list_buckets
-* riak.list_keys
-* riak.set_bucket_props
-* riak.get_bucket_props
-* riak.clear_bucket_props
-* riak.get_index
-* riak.store_object
-* riak.get_object
-* riak.reload_object
-* riak.delete_object
-* riak.store_file
-* riak.get_file
-* riak.delete_file
-* riak.file_exists
-* riak.link_walk
-* riak.map_reduce
-* riak.ping
-
-Events are propogated using [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html), provided by the [Instrumentable](https://github.com/siyegen/instrumentable) gem.
-
-### Enabling
-
-Instrumentation is opt-in. If `instrumentable` is not available, instrumentation will not be available. To turn on instrumentation, simply require the `instrumentable` gem in your app's Gemfile:
-
-```ruby
-gem 'instrumentable', '~> 1.1.0'
-```
-
-Then, to subscribe to events:
-
-```ruby
-ActiveSupport::Notifications.subscribe(/^riak\.*/) do |name, start, finish, id, payload|
-  name    # => String, name of the event (such as 'riak.get_object' from above)
-  start   # => Time, when the instrumented block started execution
-  finish  # => Time, when the instrumented block ended execution
-  id      # => String, unique ID for this notification
-  payload # => Hash, the payload
-end
-```
-
-The payload for each event contains the following keys:
-
-* `:protocol`: The `client.protocol` value of the Riak client
-* `: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', {}]`
 
 ## How to Contribute
 
@@ -344,5 +489,5 @@ Unless required by applicable law or agreed to in writing, software distributed
 
 ## Auxillary Licenses
 
-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.
+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. 
 !["Creative Commons"](http://i.creativecommons.org/l/by-nc/3.0/88x31.png)

data/RELEASE_NOTES.md

@@ -1,61 +1,39 @@
 # Riak Ruby Client Release Notes
 
-## 1.4.5 Feature and Bugfix Release - 2014-10-03
+## 2.0.0 Release - TBD
 
-Release 1.4.5 includes:
+Version 2.0.0 is a major new version with many new features, API changes,
+and feature removals.
 
-Feature:
+New features:
 
-* Instrumentation: if the `instrumentable` gem is loaded, the client exposes
-  several event hooks to `ActiveSupport::Notifications`. Read the README for
-  more information, and if you'd like other events to be instrumented, please
-  file GitHub issues. Instrumentation was developed by Ryan Daigle.
+* Yokozuna: full-text search built on Solr and powered by Riak.
+* Riak security: TLS-encrypted and authenticated protocol buffers, access
+  control, and more!
+* Convergent Replicated Data Types (CRDTs): counters, maps, and sets, all with
+  convenient and safe distributed semantics.
+* Bucket types: the building blocks of Yokozuna, access control, and CRDTs.
 
-Bugfix:
+API changes:
 
-* URI escaping now uses the CGI escaper. Thanks to Sean McKibben for 
-  reporting this bug.
+* Exceptions raised by the client are subclasses of `Riak::Error`.
+* The internals of the Beefcake-based protocol buffers support have been
+  refactored for reliability and maintainability.
+* The Beefcake version has been bumped to 1.0 for improvements in speed and
+  memory usage.
+* Tests now use RSpec 3.
 
-## 1.4.4.1 Bugfix Release - 2014-04-17
-
-Release 1.4.4.1 includes the intended 1.4.4 bugfix:
-
-* Remove freedom-patched `Net::HTTPHeader#each_capitalized` method. This
-  caused infinite loops when parsing HTTP headers not related to Riak,
-  and is not necessary in Riak versions newer than 1.1.0. Thanks to
-  Morten Primdahl and Steven Davidovitz at Zendesk for helping isolate and
-  troubleshoot this.
-
-## 1.4.4 - 2014-04-17
-
-No changes from 1.4.3.
-
-## 1.4.3 Bugfix Release - 2013-12-31
-
-Release 1.4.3 fixes some bugs and improves documentation.
-
-Documentation:
-* Secondary Index examples in README now use string names.
-* 1.4 Counter usage explained better, fixed by Srdjan "batasrki" Pejic in
-  https://github.com/basho/riak-ruby-client/pull/130
-
-Bugfixes:
-
-* Redundant `gem "rake"` in `Gemfile`.
-* Escape square brackets in key names, reported and fixed by Garret Alfert in
-  https://github.com/basho/riak-ruby-client/issues/128 and
-  https://github.com/basho/riak-ruby-client/pull/129 , respectively.
+Removed:
 
+* HTTP support has been removed from the Riak Ruby Client in favor of focusing
+  on Protocol Buffers.
+* The included test-server has been removed. Tests now require a Riak node to
+  be configured and run independently of the test suite.
 
 ## 1.4.2 Bugfix Release - 2013-09-20
 
 Release 1.4.2 fixes a couple bugs.
 
-Issues:
-
-* Secondary index queries against non-2i-enabled buckets/backends now raise a
-  useful exception.
-
 Bugfixes:
 
 * 2i Requests over PBC block forever when 0 results match in 1.4.x,
@@ -64,9 +42,6 @@ Bugfixes:
   https://github.com/basho/riak-ruby-client/pull/122
 * RObject#links is an Array when loaded from PBC, reported by Dan Pisarski in
   https://github.com/basho/riak-ruby-client/pull/123
-* Bucket listing doesn't work with HTTP backend,
-  reported and fixed by Wagner Camaro in
-  https://github.com/basho/riak-ruby-client/pull/124
 
 ## 1.4.1 Patch/Bugfix Release - 2013-09-06