rrrmatey 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b26fa620ebb2d28f3d3ae5dbd19274f076e5c810
+  data.tar.gz: 6a10068e527b7cb91e516fc0b6e6929aa649e857
+SHA512:
+  metadata.gz: 6ebdc1b2f0341a663d3c579f808e5b83a7866c25922b8df1b427a19e3d8c065aa02bc9f9c146be69be7229e691cc1e7d570c44b3e9ddf783f27c46680162cb7d
+  data.tar.gz: e57d5187f5cb638f2db3ab7810d495a7e4ac72ff6cb9f8766f450540fa43cda5509ed5b2b5f631127bc89d4819c1d73f4eb692b68323878fda4ac90aac4e0e5b

data/LICENSE.md

@@ -0,0 +1,16 @@
+Copyright 2015-2016 James Gorlick 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.
+
+All of the files in this project are under the project-wide license
+unless they are otherwise marked.

data/README.md

@@ -0,0 +1,249 @@
+# RRRMatey
+
+`rrrmatey` is an ODM (Object-Document-Mapper) framework for use with Basho Data
+Platform (BDP) Cache Proxy and Riak KV.
+
+CRUD operations are encapsulated at the controller- and model-level for relatively
+smooth mixin for use in a `rails` or leaner `ruby` application framework.
+
+BDP Cache Proxy provides the majority of the underlying interface to the data
+layer. Redis acts as the cache layer while Riak provides availability with
+partition tolerance. Riak Search is also used to provide the Index operation (the
+silent I in CRUD).
+
+## Dependencies
+
+* Ruby
+ * 1.9.3, 2.0, 2.1, and 2.2 are supported. JRuby in 1.9 and 2.0 modes are also
+ supported.
+* BDP Cache Proxy
+ * Depends on write-around and read-through caching, so BDP EE 1.1.0+ .
+* Riak KV
+ * Depends on basic KV and Riak Search, so Riak KV v.2.0.0+ . Ensure Riak Search
+ is enabled.
+
+### Development Dependencies
+Development dependencies are handled with bundler. Install bundler
+(`gem install bundler`), if not present.
+
+```shell
+bundle install
+```
+
+### Tests
+RSpec is generally run without coverage analysis.
+
+```shell
+rake spec
+```
+
+To enable coverage analysis, run with the 'CI' environment variable set.
+
+```shell
+CI=1 rake spec
+```
+
+## Use Cases
+
+### Configuring Connections
+
+Since `rrrmatey` uses BDP Cache Proxy which speaks a subset of the Redis protocol,
+a `redis` client should be configured with  one or more host entries corresponding
+to the BDP Cache Proxies.
+
+Similarly, the `riak` client is used for Riak Search.
+
+In both cases, the use of `connection_pool` is recommended.
+
+The following example captures the essential elements of configuration. However,
+for a Rails application, the connection details should be in environment-specific
+files to avoid leaking production credentials.
+
+```ruby
+require 'rrrmatey'
+require 'connection_pool'
+
+RRRMatey::StringModel.cache_proxy = RRRMatey::Retryable.new(
+    ConnectionPool.new(:size => 5, :timeout => 5) {
+        Redis.new(:host => '127.0.0.1', :port => 22122)
+    }   
+)
+
+RRRMatey::StringModel.riak = RRRMatey::Retryable.new(
+    ConnectionPool.new(:size => 5, :timeout => 5) {
+        Riak::Client.new(:nodes => [
+            {:host => '127.0.0.1', :pb_port => 10017},
+            {:host => '127.0.0.1', :pb_port => 10027},
+            {:host => '127.0.0.1', :pb_port => 10037},
+            {:host => '127.0.0.1', :pb_port => 10047},
+            {:host => '127.0.0.1', :pb_port => 10057},
+        ])  
+    }   
+)
+```
+
+### Developing Models with Relations
+
+To provide a shipworthy example, the models for Pirate and Vessel including a
+relation for aboard follows:
+
+```ruby
+class Pirate
+    include ::RRRMatey::StringModel
+    field :name, :type => :string
+    field :created, :type => :date, :default => Date.new(1970, 1, 1)
+    field :aboard, :type => :string
+
+    def valid?
+        valid_name? &&
+            valid_created?
+    end 
+
+    private
+
+    def valid_name?
+        !name.blank?
+    end 
+
+    def valid_created?
+    !created.nil? && created < Date.today - 14 * 365.25
+    end 
+end
+
+class Vessel
+    include ::RRRMatey::StringModel
+    field :name, :type => :string
+
+    def valid?
+        valid_name?
+    end 
+
+    def boardings(offset, limit)
+        Pirate.list_by(offset, limit, :aboard_s => vessel_id)
+    end
+
+    private
+
+    def valid_name?
+        !name.blank?
+    end 
+end
+```
+
+#### Specialiing the Model Connection
+The module-level `riak` and `cache_proxy` connections may be overriden on the
+Model-level.
+
+#### Opinionated, but Open
+The StringModel is opinionted, providing reasonable defaults for the following:
+ * item_name
+  * default: the class name in snake case format (underscored)
+  * purpose: the element wrapper for json or xml content
+ * index_name
+  * default: the item_name
+  * purpose: the Riak Search index name
+  * note: the index is created automatically
+
+Several Rails "built-in" methods such as blank? and underscore are used if
+present or otherwise are monkey-patched in Rails fashion. This is mostly okey,
+but Rails inflections, ie Person => People, are not re-implemented within
+RRRMatey. For use in a Rails application, existing inflections will be used.
+To be 100% covered, if a Model is known to be an abnormal case, requiring
+inflection, specialize the item_name on the Model.
+
+### Developing an API Controller
+
+Using the Pirate and Vessel models and mixing in the CrudController requires
+only definition of non-CRUD methods, ie "A Pirate boards a Vessel":
+
+```ruby
+class PiratesController < ApplicationController
+    include RRRMatey::CrudController
+
+    def board
+        vessel_id = params['vessel_id']
+        return respond_bad_request if vessel_id.blank?
+        pirate_id = params['pirate_id']
+        return respond_bad_request if pirate_id.blank?
+
+        v = Vessel.get(vessel_id)
+        return respond_not_found if v.nil?
+
+        p = Pirate.get(pirate_id)
+        return respond_not_found if p.nil?
+        p.aboard = v.id
+        p.save
+        respond_ok(p)
+    end 
+end
+
+class VesselsController < ApplicationController
+    include RRRMatey::CrudController
+
+    def boardings
+        vessel_id = params['vessel_id']
+        return respond_bad_request if vessel_id.blank?
+        offset = params['offset'] || 0
+        limit = params['limit'] || 20
+        vessel = Vessel.new(vessel_id)
+        pirates_aboard = vessel.boardings(offset, limit)
+        respond_ok(pirates_aboard)
+    end
+end
+```
+
+#### Strong Parameters
+By mixing in the CrudController functionality, existing Rails strong_parameters
+best practice is still available within a Rails context and should be used.
+
+## How to Contribute
+
+* Fork the project on Github. If you have already forked, use `git pull --rebase`
+to reapply your changes on top of the mainline. Example:
+
+```shell
+git checkout master
+git pull --rebase basho 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:
+
+```shell
+git checkout -b topic
+```
+
+ * Existing branch:
+
+```shell
+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. Documenation 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 or rbenv to ensure cross-version
+ compatibility.
+
+ * Cleanup any trailing whitespace in your code and generally follow the coding
+ style of existing code.
+
+ * Send a pull request to the upstream repositoty.
+
+## License & Copyright
+Copyright ©2015-2016 James Gorlick 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/RELEASE_NOTES.md

@@ -0,0 +1,26 @@
+# RRRMatey Release Notes
+
+## 0.1.0 Release - 2016-01-04
+
+Version 0.1.0 is released as a reference for how to use the BDP Cache Proxy
+and Riak KV to implement an API.
+
+### New Features:
+* StringModel mixin integrating BDP Cache Proxy and Riak Search to support all
+ CRUD operations.
+* CrudController mixin supporting all CRUD operations, requiring only non-CRUD
+ operations to be added.
+
+### Significant Known Issues
+
+Several Rails "built-in" methods such as blank? and underscore are used if
+present or otherwise are monkey-patched in Rails fashion. This is mostly okey,
+but Rails inflections, ie Person => People, are not re-implemented within
+RRRMatey. For use in a Rails application, existing inflections will be used.
+To be 100% covered, if a Model is known to be an abnormal case, requiring
+inflection, specialize the item_name on the Model.
+
+The Update method on CrudController does not operate in a PATCHy way, merging the
+existing values from the underlying data store with the values provided via the PUT
+method. Implementing PATCH seemed to conflate understanding of the use of BDP
+Cache Proxy and Riak Search.

data/Rakefile

@@ -0,0 +1,39 @@
+require 'bundler'
+Bundler.setup
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'rrrmatey/version'
+
+task :gem => :build
+task :build do
+    system 'gem build rrrmatey.gemspec'
+end
+
+task :install => :build do
+    system "sudo gem install rrrmatey-#{RRRMatey::VERSION}.gem"
+end
+
+task :uninstall do
+    system 'sudo gem uninstall rrrmatey'
+end
+
+task :release => :build do
+    system "git tag -a v#{RRRMatey::VERSION} -m 'Tagging #{RRRMatey::VERSION}'"
+    system 'git push --tags'
+    system "gem push rrrmatey-#{RRRMatey::VERSION}.gem"
+    system "rm rrrmatey-#{RRRMatey::VERSION}.gem"
+end
+
+RSpec::Core::RakeTask.new('spec') do |spec|
+    spec.pattern = "spec/**/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new('spec:progress') do |spec|
+    spec.rspec_opts = %w(--format progress)
+    spec.pattern = "spec/**/*_spec.rb"
+end
+
+task :default => :spec

data/lib/rrrmatey.rb

@@ -0,0 +1,8 @@
+require 'redis'
+require 'riak'
+require_relative 'rrrmatey/type_coercion.rb'
+require_relative 'rrrmatey/errors.rb'
+require_relative 'rrrmatey/retryable.rb'
+require_relative 'rrrmatey/discrete_result.rb'
+require_relative 'rrrmatey/string_model/string_model.rb'
+require_relative 'rrrmatey/crud_controller.rb'

data/lib/rrrmatey/crud_controller.rb

@@ -0,0 +1,97 @@
+module RRRMatey
+    module CrudController
+        def self.included(base)
+            base.extend(ModelMethods)
+        end
+
+        module ModelMethods
+            def model(*model_klass_n_stuff)
+                if model_klass_n_stuff.blank?
+                    model_klass
+                else
+                    @model_klass = model_klass_n_stuff[0]
+                end
+            end
+
+            def model_klass
+                @model_klass ||= opinionated_model
+            end
+
+            private
+
+            def opinionated_model
+                # remove sController from Controller klass name
+                self.name[0..-12].constantize
+            end
+        end
+
+        def index
+            offset = params[:offset] || 0
+            limit = params[:limit] || 20
+            items = self.class.model_klass.list(offset, limit)
+            respond_ok(items)
+        end
+
+        def show
+            id = params[:id]
+            if id.blank?
+                return respond_bad_request
+            end
+            item = self.class.model_klass.get(id)
+            if item.nil?
+                return respond_not_found
+            end
+            respond_ok(item)
+        end
+
+        def destroy
+            id = params[:id]
+            if id.blank?
+                return respond_bad_request
+            end
+            self.class.model_klass.delete(id)
+            respond_ok(nil)
+        end
+
+        def update
+            # TODO: get and merge with params if a patch-y update is desired
+            item = self.class.model_klass.from_params(params)
+            begin
+                item.save
+            rescue RRRMatey::InvalidModelError
+                return respond_bad_request
+            rescue StandardError => e
+                return respond_internal_server_error(e)
+            end
+            respond_ok(nil)
+        end
+
+        def respond_bad_request
+            respond_to do |format|
+                format.json { render :json => nil, :status => 400 }
+                format.xml { render :xml => nil, :status => 400 }
+            end
+        end
+
+        def respond_not_found
+            respond_to do |format|
+                format.json { render :json => 'Not Found', :status => 404 }
+                format.xml { render :xml => 'Not Found', :status => 404 }
+            end
+        end
+
+        def respond_internal_server_error(e)
+            respond_to do |format|
+                format.json { render :json => { :mesage => e.message }, :status => 500 }
+                format.xml { render :xml => { :message => e.message }, :status => 500 }
+            end
+        end
+
+        def respond_ok(item)
+            respond_to do |format|
+                format.json { render :json => item }
+                format.xml { render :xml => item  }
+            end
+        end
+    end
+end