better-ripple 1.0.0

data/LICENSE

@@ -0,0 +1,17 @@
+Copyright 2010-2011 Sean Cribbs and Basho Technologies, Inc.
+Improvements Copyright ©2012 Cloudability 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.
+
+All of the files in this project are under the project-wide license
+unless they are otherwise marked.

data/README.md

@@ -0,0 +1,182 @@
+# `better-ripple`: Riak Document Models
+
+`better-ripple` is an improved version of `ripple`, the rich Ruby modeling
+layer for Riak, Basho's distributed database that contains an ActiveModel-based
+document abstraction which is inspired by ActiveRecord, DataMapper, and
+MongoMapper.
+
+
+## Improvements vs. ripple
+
+To date, the improvements include:
+
+* Use `better-riak-client` instead of `riak-client`.
+* Better handling of gemspec generation (fixed Redstorm compatibility).
+
+We will be tracking upstream changes, and including them as appropriate.
+
+Release 1.0.0 corresponds to `ripple` v.1.0.0.beta2, plus changes on
+`master` as of 2012-10-09.  See `RELEASE_NOTES.md` for details.
+
+
+## Dependencies
+
+`better-ripple` requires Ruby 1.8.7 or later and versions 3 or above of
+ActiveModel and ActiveSupport (and their dependencies, including
+i18n). Naturally, it also depends on the `better-riak-client` gem to connect
+to Riak.
+
+Development dependencies are handled with bundler. Install bundler
+(`gem install bundler`) and run this command in each sub-project to
+get started:
+
+``` bash
+$ bundle install
+```
+
+Run the RSpec suite using `bundle exec`:
+
+``` bash
+$ bundle exec rake spec
+```
+
+## Document Model Examples
+
+``` ruby
+require 'ripple'
+
+# Documents are stored as JSON objects in Riak but have rich
+# semantics, including validations and associations.
+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 /riak/emails/37458abc752f8413e
+email.from = "someone@nowhere.net"
+email.save                               # PUT /riak/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 /riak/emails (Riak-assigned key)
+
+# Documents can contain embedded documents, and link to other standalone documents
+# via associations using the many and one class methods.
+class Person
+  include Ripple::Document
+  property :name, String
+  many :addresses
+  many :friends, :class_name => "Person"
+  one :account
+end
+
+# Account and Address are embeddable documents
+class Account
+  include Ripple::EmbeddedDocument
+  property :paid_until, Time
+  embedded_in :person # Adds "person" method to get parent document
+end
+
+class Address
+  include Ripple::EmbeddedDocument
+  property :street, String
+  property :city, String
+  property :state, String
+  property :zip, String
+end
+
+person = Person.find("adamhunter")
+person.friends << Person.find("seancribbs") # Links to people/seancribbs with tag "friend"
+person.addresses << Address.new(:street => "100 Main Street") # Adds an embedded address
+person.account.paid_until = 3.months.from_now
+```
+
+
+## Configuration Example
+
+When using Ripple with Rails 3, add ripple to your Gemfile and then run the `ripple` generator.  This will generate a test harness, some MapReduce functions and a configuration file. Example:
+
+```
+$ rails g ripple
+      create  config/ripple.yml
+      create  app/mapreduce
+      create  app/mapreduce/contrib.js
+      create  app/mapreduce/ripple.js
+      create  test/ripple_test_helper.rb
+      insert  test/test_helper.rb
+      insert  test/test_helper.rb
+```
+
+`config/ripple.yml` should contain your Riak connection information, and settings for the test server. Example:
+
+``` yaml
+# Configure Riak connections for the Ripple library.
+development:
+  http_port: 8098
+  pb_port: 8087
+  host: 127.0.0.1
+
+# The test environment has additional keys for configuring the
+# Riak::TestServer for your test/spec suite:
+#
+# * bin_dir specifies the path to the "riak" script that you use to
+#           start Riak (just the directory)
+# * js_source_dir specifies where your custom Javascript functions for
+#           MapReduce should be loaded from. Usually app/mapreduce.
+test:
+  http_port: 9000
+  pb_port: 9002
+  host: 127.0.0.1
+  bin_dir: /usr/local/bin   # Default for Homebrew.
+  js_source_dir: <%%= Rails.root + "app/mapreduce" %>
+
+production:
+  http_port: 8098
+  pb_port: 8087
+  host: 127.0.0.1
+```
+
+`require 'ripple/railtie'` from your `config/application.rb` file to complete the integration.
+
+
+## How to Contribute
+
+* Fork the project on [Github](http://github.com/cloudability/better-ripple).  If you have already forked, use `git pull --rebase` to reapply your changes on top of the mainline. Example:
+
+    ``` bash
+    $ git checkout master
+    $ git pull --rebase cloudability master
+    ```
+* 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:
+
+        ``` bash
+        $ git checkout -b topic
+        ```
+  * Existing branch:
+
+        ``` bash
+        $ git rebase master
+        ```
+* Write an RSpec example or set of examples 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/cloudability/better-ripple/issues), include "Closes #X" in the commit message (where X is the issue number).
+* Send me a pull request.
+
+## License & Copyright
+
+Copyright &copy;2010-2012 Sean Cribbs and Basho Technologies, Inc.
+Improvements Copyright &copy;2012 Cloudability 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.

data/RELEASE_NOTES.md

@@ -0,0 +1,284 @@
+# Ripple Release Notes
+
+## 1.0.0 Patch/Feature Release - 2012-10-09
+
+Release 1.0.0 fixes gemspec generation and uses `better-riak-client`.
+
+This release corresponds to `ripple` v.1.0.0.beta2, plus changes on
+`master` as of 2012-10-09 (commit f866ddd5e2b0a11bb11bd29683f4f41f5c1bca22).
+
+Improvements:
+
+* Change gemspec handling to facilitate working with stock Redstorm.
+
+Upstream Changes:
+
+* Do not replace accessors defined by superclass.  (Fixes ActiveModel 3.2 issue)
+
+
+## 0.9.5 Patch Release - 2011-06-14
+
+Release 0.9.5 is a minor bugfix release but also includes some small features.
+
+* Allow IO-like objects to be used as RObject data. [Josh Nichols]
+* Set the content-length or transfer-encoding appropriately for Net::HTTP. Fixes #162.
+* Fix MapReduce jobs on PBC when keep=false on certain phases. [Alexander Lang]
+* Invalidate the key-cache for a bucket when streaming.
+* Pass options through Document#all to Bucket#keys.
+* Make Hash#to_param compatible with ActiveSupport. [Dave Perrett]
+* Add support for previous_changes functionality and make available to callbacks. [Nathaniel Talbott, Sean Cribbs
+
+## 0.9.4 Patch Release - 2011-05-10
+
+Release 0.9.4 is a minor bugfix release.
+
+* Allow global JSON options to be set so that deeply nested objects can be serialized.
+* Set TCP_NODELAY on PBC sockets and send messages in a single write to reduce latency. [Technorama, Dan Hodge]
+* X510 should be X509 in OpenSSL. [Adam Hunter]
+
+## 0.9.3 Patch Release - 2011-04-18
+
+Release 0.9.3 is a minor bugfix release.
+
+* Make YAML serialization spec immune to engine differences. [Jeff Pollard]
+* Key-streaming over HTTP are immune to JSON objects that cross chunk boundaries.
+* Require 'yaml' so we can read the config file.
+* Require 'erb' so we can eval the config. [Myron Marston]
+* Move definition of validates_associated back into the validator. [Myron Marston]
+* Require 'set' before Set is extended. [André Silva]
+
+## 0.9.2 Patch Release - 2011-04-11
+
+Release 0.9.2 is a minor bugfix release.
+
+* Remove usage of autoload from all projects to reduce thread-safety problems.
+* Fix Excon backend to properly initialize response headers under error conditions. [Jeff Pollard, Myron Marston]
+* Excon yields multiple arguments to the streaming block.
+
+## 0.9.1 Patch Release - 2011-04-07
+
+Release 0.9.1 is a minor bugfix release.
+
+* Fix strange encoding problems on Ruby 1.9 when using Protocol Buffers.
+* Use http_port rather than port in the generated TestServer. [Myron Marston]
+
+## 0.9.0 Feature Release - 2011-04-03
+
+Release 0.9.0 is a huge step forward from the 0.8 series, including support for Riak 0.14.x features, Protocol Buffers transport, and many bugfixes.
+
+Following this release, the code will be branched into a 0.9-stable branch, which will only receive critical bugfixes. Development of 1.0 features will occur on the master branch.
+
+* Fixed some client semantics: separate ports for protocols, client ID responsibility.
+* Add definition of EmbeddedDocument#==. [Myron Marston]
+* Allow a many-linked doc to be removed from an association. [Myron Marston]
+* Fix one-linked association to return nil appropriately. [Myron Marston]
+* Added external JSON serialization for Ripple documents.
+* Fixed validates_associated. [Myron Marston]
+* Fixed assignment bug in one-embedded associations. [Myron Marston]
+* Added integration tests that work across all client backends.
+* Added support for Protocol Buffers transport with Beefcake library.
+* Added HTTP Basic authorization support. [Adam Hunter]
+* Added HTTPS support. [Adam Hunter]
+* Normalized project Gemfiles.
+* Extracted stream-isolating pump pattern from client backends.
+* Improve speed and reliability of test server.
+* Bubble up errors when saving a document. [Duff OMelia]
+* Add automatic expiration to Rack session store.
+* Use ISO8601 datetime format in stored documents (configurable). [Nicolas Fouché]
+* Access document attributes that do not have a declared property. [Duff OMelia]
+* Fix document callback ordering. [Nathaniel Talbott]
+* Consolidate setting of the object key when link-walking. [Kyle Kingsbury]
+* Added support for streaming MapReduce.
+* Bucket instances are now memoized in the Client. [Woody Peterson]
+* Client backends were refactored so that higher layers are not concerned with transport semantics.
+* Fix false.present? bug.
+* Riak 0.14 features:
+    * MapReduce has support for key-filters.
+    * Add list_buckets operation.
+    * HTTP resources prefixes can be discovered from the root URL.
+* Added document observers using ActiveModel::Observer. [Stefan Sprenger]
+* :key is a protected attribute on Document models. [Adam Hunter]
+
+## 0.8.3 Patch/Minor Feature Release - 2010-12-13
+
+Release 0.8.3 includes new generators for Rails 3 projects, a new HTTP backend based on Wesley Beary's Excon library, and significant bugfixes for Document models.
+
+`riak-client` is now also completely independent of ActiveSupport, and all three libraries have better support for JRuby.
+
+* Fix edge case where NetHTTPBackend would not #to_i the response code.
+* Improve handling of Time properties, including ActiveSupport::TimeWithZone. [Duff O'Melia]
+* Don't cast empty string for Numeric property types. [Marco Campana]
+* Add MapReduce built-ins generator.
+* Add generators to help with Riak::TestServer and initial Rails 3 setup. [Duff O'Melia, Sean Cribbs]
+* Improve handling of Document properties we don't know about.
+* Refactored RequestHeaders so it can be used by multiple backends.
+* Add Excon HTTP backend.
+* Control mock HTTP server via DRb so as to avoid deadlocks.
+* Monkeypatch #present? seperately from #blank?. [Kyle Kingsbury]
+* Improved RObject#inspect output. [Jay Adkisson]
+* Fix Bucket#keys raising exceptions on rare occasions. [Kyle Kingsbury]
+* Add support for mass-assignment security on Document models.
+* Moved ActiveSupport version check into CacheStore.
+* Added example TestServer config files.
+* Allow document assignment even if the value is a proxy. [Duff O'Melia]
+* Remove "install curb" warnings.
+* Improve JRuby compatibility.
+* Resolve Hash-ordering differences between 1.9 and 1.8 in specs.
+* Fix 1.8.x issue with Open3 returning a nil waitthread in the TestServer.
+* Removed riak-client dependency on ActiveSupport. [Kyle Kingsbury]
+* Report a changed attribute only if its value changes. [Duff O'Melia]
+* Reloading a Ripple::Document now casts property values. [Duff O'Melia]
+
+## 0.8.2 Patch/Minor Feature Release - 2010-10-22
+
+Release 0.8.2 includes significant additions to support features in Riak 0.13, including Riak Search and Luwak.
+
+Simply `require 'riak/search'` to add Search-related features to riak-client.
+
+* Fixed bug in embedded associations where associated validators would be added every time the association was instantiated. [Adam Hunter]
+* Update and loosen dependencies to Rails 3.0.1 and RSpec 2.
+* Add support for file-existence check in Luwak. [John Axel Eriksson]
+* Avoid clobbering an existing Boolean class or module.
+* Add Luwak support.
+* Add Search features. [Sean Cribbs, Rusty Klophaus]
+
+## 0.8.1 Patch/Minor Feature Release - 2010-10-11
+
+Release 0.8.1 includes several new features and bugfixes.
+
+* Riak::TestServer makes it easier and faster to run automated tests that need to store data in Riak. It includes an in-memory Riak backend that quickly clears its contents at the end of a test/example. All included integration tests now use this.
+* Headers are turned into strings before splitting into 8KB chunks. [Nicolas Fouché]
+* Riak::RObject#prevent_stale_writes option allows conditional PUT semantics, matching on ETag. [Lee Jensen]
+* Riak::RObject#raw_data gives access to the object data before deserialization. [Lee Jensen]
+* Boolean properties on Ripple documents now allow a default value of false. [Duff O'Melia]
+* Ripple documents now support accepts_nested_attributes_for. [Brian Kaney]
+
+## 0.8.0 Feature Release - 2010-08-31
+
+The 0.8.0 release is packed full of new features and bugfixes. Of particular note are:
+
+* Rails 3 final support
+* Session stores
+* Linked associations
+* Riak 0.12 support
+
+Full notes:
+
+* Ripple::Document classes can define their desired quorum parameters.
+* ripple and riak-sessions use Rails 3 final. riak-client is still compatible with active_support >= 2.3.5.
+* Keys are not loaded by default when requesting a Riak::Bucket. This matches the default for Riak 0.12.
+* Ripple::Document now supports update_attributes and update_attribute.
+* Inspection output has been improved for Ripple documents.
+* Ripple::Document classes can now have associations that use links.
+* Property-casting patches are now eagerly loaded.
+* Certain responses from MapReduce can be converted into Riak::RObjects. [Misha Gorodnitzky]
+* Key/bucket (un)escaping has been improved. [Nicolas Fouché]
+* Riak::CacheStore sets and uses bucket-default quorums instead of per-request parameters.
+* Riak::Bucket supports new quorum defaults.
+* The default configuration file for Ripple is now config/ripple.yml. [Ashley Woodard]
+* Added a Rails 3 model generator. [Ashley Woodard]
+* Serializing RObject data via Marshal is now simpler, using "application/x-ruby-marshal" content-type.
+* Large HTTP headers (Link tends to be one) are split into 8KB chunks for both backends.
+* Added session stores for Rack and Rails 3.
+* Document#find returns nil when all arguments are blank.
+* CurbBackend now properly handles IO objects as the request body data.
+* Ripple::Document classes that have the same bucket/key are equivalent using ==.
+* Ripple::Document classes can use a property as the key, as long as it's a String.
+
+## 0.7.1 Patch Release - 2010-06-08
+
+This release has no new features but includes bug fixes and some internal refactoring of the Ripple::Document hierarchy.
+
+* The Net::HTTP backend should handle streamed keys better (although
+  still not perfectly).
+* The Riak::MapReduce#timeout method now returns self, allowing
+  chaining.
+* The Ripple::Document and Ripple::EmbeddedDocument are less coupled
+  from one another so numerous internal confusions about calling order
+  are fixed.
+* When using Riak::RObject#to_link, a blank tag is no longer allowed.
+
+## 0.7.0 Feature Release - 2010-05-06
+
+This release includes a number of new features.  The largest change is that the library is now split into two gems, 'riak-client' and 'ripple'.  'riak-client' supports ActiveSupport 2.3.5, 'ripple' only supports 3.0.0.beta3.
+
+A big kudos goes to Adam Hunter who contributed the majority of the new associations code.
+
+In addition, these changes were made:
+
+* Keys should stream properly now from Bucket#keys (the "stream" option was left off).
+* Deletes can be issued directly from a Bucket without instantiating an RObject.
+* Added a ActiveSupport 3.0-compatible Cache Store. [Shay Frendt]
+* Added Bucket#exists?
+* A provisionally complete implementation of embedded document associations. [Adam Hunter]
+* Ripple::Document passes ActiveModel::Lint tests.
+* Updated Rails 3 dependencies to beta3 and RSpec to 2.0.0.beta6
+* Ripple::Document handles nil keys better. [John Lynch]
+
+
+## 0.6.1 Patch Release - 2010-03-17
+
+This is a minor release with fixes for a few issues:
+
+* Riak::Link objects will now be unique when added to RObject#links
+  Set. [John Lynch]
+* Attributes on Ripple::Document classes are no longer clone, which had
+  prevented non-scalar properties from being modified directly (e.g. Array).
+* Buckets, keys, and walk specs are properly escaped in URLs
+  (including slashes).
+* Time-related properties properly convert to string formats in JSON that
+  they will work in the context of MapReduce jobs.
+
+## 0.6.0 Feature Release - 2010-03-05
+
+This release contains enhancements and bugfixes in preparation for the
+Riak 0.9 release.
+
+* The CurbBackend now uses fibers to prevent curl-handle corruption when
+  a block is given to streaming operations.
+* The default prefix is now "/riak/" to match the latest version of Riak.
+* The client configuration for Ripple is now used.
+* Added Bucket#new and Bucket#get_or_new for easily creating new objects.
+* Added Bucket#allow_mult and Bucket#n_value accessors for more easily setting
+  bucket properties.
+* Added timestamps! method for easily adding created_at/updated_at to documents.
+  [Adam Hunter]
+* The 'links' collection on RObject is now a Set instead of an Array.
+* All literal messages are now stored in YAML localization files.
+* Object siblings (caused by concurrent updates when allow_mult is true) can now
+  be accessed directly.
+* Map-reduce jobs now have timeouts (in parity with Riak).
+
+## 0.5.1 Patch Release - 2010-02-22
+
+This is a minor release with fixes for Ruby 1.9, bundler/edge Rails,
+and a minor feature addition. Changes:
+
+* Qualify namespaces for Ruby 1.9.
+* Decoupled a few specs that gave the appearance of failure.
+* Added "bucket" and "key" properties on Riak::Link objects. [John Lynch]
+* Fully-qualify the `JSON` constant, using `ActiveSupport::JSON` instead.
+* Adjusted gem specification to accommodate edge Rails. [Preston Marshall]
+
+## 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