riak_json 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f4829b641aa58acf10a0b5f6b8bb465a2dda3ae7
+  data.tar.gz: bfe725495387a621908a165cac547cfc282bd0e2
+SHA512:
+  metadata.gz: 82ff9f6dc5beba9b516ec396c0ab1fb12604f3ad922d45d09db5c426016654c692b14197f7411748ef27e542570460905ed8fe34400ae4672c7fc5044a0f32b0
+  data.tar.gz: c17cd830fc7dc717b138f0621016afecfbc8e2eebeb22956163f1be4b79b9797c4cf24e8a259f1782b0b6da5026b77553de045a2a5517253817ba809cb2fddc7

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea

data/Gemfile

@@ -0,0 +1,24 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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.
+##
+## -------------------------------------------------------------------
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in riak_json.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,16 @@
+Copyright 2013 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,178 @@
+# Riak Json Ruby Client
+
+A Ruby client for [Riak Json](https://github.com/basho-labs/riak_json/).
+For ActiveModel integration for RiakJson, see [riak_json-active_model](https://github.com/dmitrizagidulin/rj-activemodel) gem.
+
+## Installation
+Since this gem is not released to the public yet, build it locally:
+
+```bash
+git clone git@github.com:basho/riak_json_ruby_client.git
+cd riak_json_ruby_client
+rake build
+gem install pkg/riak_json-0.0.2.gem
+```
+## Unit Testing
+Use bundler to install dev dependencies:
+```
+bundle install
+```
+To run both unit and integration tests:
+```
+bundle exec rake test
+```
+Note: By default, integration tests assume that Riak is listening on ```127.0.0.1:8098```
+(the result of ```make rel```).
+
+To specify alternate host and port, use the ```RIAK_HOST``` and ```RIAK_PORT``` env variables:
+```
+RIAK_HOST=127.0.0.1 RIAK_PORT=10018 bundle exec rake
+```
+To run just the unit tests:
+```
+bundle exec rake unittest
+```
+To run just the integration tests:
+```
+bundle exec rake itest
+```
+## Usage
+### Loading the Client Config File
+```ruby
+require 'riak_json'
+
+config_file = 'test/examples/riak.yml' # Loads in a config hash, by environment
+dev_config = config_file['development']
+client = RiakJson::Client.new(host=dev_config['host'], port=dev_config['http_port'])
+```
+
+### Creating / Referencing a Collection
+```ruby
+require 'riak_json'
+
+client = RiakJson::Client.new('localhost', 8098)
+# A new or existing collection
+collection = client.collection("cities")
+```
+
+### Schema Administration
+```ruby
+# You may set an optional schema
+# (or skip this step and go straight to inserting documents)
+# Supported field types:
+#   - string (no spaces, think of a url slug)
+#   - text (spaces allowed)
+#   - multi_string (an array of strings, no spaces)
+#   - integer
+schema = RiakJson::CollectionSchema.new
+schema.add_text_field(name='city', required=true)
+schema.add_string_field('state', true)
+schema.add_multi_string_field('zip_codes') # required: false 
+schema.add_integer_field('population', false)
+schema.add_string_field('country', true)
+
+# Store the schema
+collection.set_schema(schema)
+
+# Check to see if schema is present
+collection.has_schema?  # => true
+
+# Read a stored schema for a collection
+schema_result = collection.get_schema()
+#   [{
+#     :name => "city",
+#     :type => "text",
+#     :require => true
+#    }, {
+#      :name => "state",
+#      :type => "string",
+#      :require => true
+#    }, {
+#      :name => "zip_codes",
+#      :type => "multi_string",
+#      :require => false
+#    }, {
+#      :name => "population",
+#      :type => "integer",
+#      :require => false
+#    }, {
+#      :name => "country",
+#      :type => "string",
+#      :require => true
+#    }]
+
+# Delete the schema (and the index) for the collection
+# WARNING: This deletes the index for the collection, so previously saved documents
+#          will not show up in queries!
+collection.delete_schema
+```
+
+### Reading and Writing Documents
+```ruby
+# You can insert a document with no key
+# RiakJson generates a UUID type key and returns it
+doc = RiakJson::Document.new
+doc.body = { 'city'=>"Cleveland", 'state'=>'OH', 'country'=>'USA'}
+doc.key  # => nil
+collection.insert(doc)
+doc.key  # => e.g. 'EmuVX4kFHxxvlUVJj5TmPGgGPjP'
+
+# Populate the cities collection with data
+doc = RiakJson::Document.new(
+  key="nyc",
+  body={ 'city'=>"New York", 'state'=>"NY", 'country'=>"USA" })
+collection.insert(doc)
+doc = RiakJson::Document.new(
+  key="boston",
+  body={ 'city'=>"Boston", 'state'=>"MA", 'country'=>"USA" })
+collection.insert(doc)
+doc = RiakJson::Document.new(
+  key="sf",
+  body={ 'city'=>"San Francisco", 'state'=>"CA", 'country'=>"USA" })
+collection.insert(doc)
+
+# Read a document (load by key)
+doc = collection.find_by_key("nyc")
+doc['city']  # => 'New York'
+```
+
+### Querying RiakJson - find_one() and find_all()
+See [RiakJson Query Docs](https://github.com/basho-labs/riak_json/blob/master/docs/query.md) 
+for a complete list of valid query parameters.
+```ruby
+# Exact match on "city" field
+query = {"city" => "San Francisco"}.to_json
+doc = collection.find_one(query)
+# collection.find_one returns a Document instance
+doc['city']  # => 'San Francisco'
+
+# Find all documents that match the "country" field exactly
+query = {"country" => "USA"}.to_json
+results = collection.find_all(query)
+results.documents.count  # => 3
+results.num_pages  # => 1  -- total pages in result set
+results.page  # => 0  -- current page (zero-indexed)
+results.per_page  # results per page, defaults to 100
+```
+#### Limiting Query Results
+```ruby
+# Find all US cities, limit results to 10 per page
+query = {'country'=>'USA', '$per_page'=>10}.to_json
+results = collection.find_all(query)
+results.per_page  #  => 10
+```
+#### Page Offsets
+```ruby
+# Find all US cities, retrieve 2nd page (zero-offset)
+query = {'country'=>'USA', '$per_page'=>10, '$page'=>1}.to_json
+results = collection.find_all(query)
+results.page  #  => 1
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,40 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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 "bundler/gem_tasks"
+require 'rake'
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new :test do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+Rake::TestTask.new :itest do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/integration/*_test.rb'
+end
+
+Rake::TestTask.new :unittest do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/unit/*_test.rb'
+end

data/lib/riak_json/client.rb

@@ -0,0 +1,139 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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 'rest-client'
+require 'erb'
+require 'yaml'
+
+module RiakJson
+  # Default hostname of the RiakJson test server
+  RIAK_TEST_HOST = '127.0.0.1'
+  # Default http port of the RiakJson test server
+  RIAK_TEST_PORT = 8098
+
+  # RiakJson::Client makes REST calls to the Riak Json API endpoints,
+  # on behalf of a Collection.
+  # Stores the details of a Riak/RiakJson HTTP connection (host, port),
+  # and manages a cache of collection references.
+  # Uses a pluggable ClientTransport component to make the actual HTTP requests.
+  class Client
+    attr_accessor :collection_cache
+    attr_accessor :transport
+    attr_accessor :host, :port
+    
+    def initialize(host=RiakJson::RIAK_TEST_HOST, port=RiakJson::RIAK_TEST_PORT)
+      @collection_cache = {}
+      @transport = RiakJson::ClientTransport.new
+      @host = host
+      @port = port
+    end
+    
+    def base_collection_url
+      "#{self.base_riak_json_url}/collection"
+    end
+    
+    def base_riak_url
+      "http://#{self.host}:#{self.port}"
+    end
+
+    def base_riak_json_url
+      "#{self.base_riak_url}/document"
+    end
+        
+    def collection(name)
+      self.collection_cache[name] ||= RiakJson::Collection.new(name, self)
+    end
+
+    def delete_json_object(collection_name, key)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/#{key}", :delete)
+    end
+
+    def delete_schema(collection_name)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/schema", :delete)
+    end
+    
+    def get_json_object(collection_name, key)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/#{key}", :get)
+    end
+    
+    def get_query_all(collection_name, query_json)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/query/all", :put, query_json)
+    end
+    
+    def get_query_one(collection_name, query_json)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/query/one", :put, query_json)
+    end
+    
+    def get_schema(collection_name)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/schema", :get)
+    end
+    
+    # Sends a JSON document to a collection resource
+    # If a key is specified, issues a PUT to that key
+    # If key is nil, issues a POST to the collection, and returns the 
+    #  key generated by RiakJson
+    #
+    # @param format [String]
+    # @param key - can be nil
+    # @param json [String]
+    # @return [String] Returns the key for the inserted document
+    def insert_json_object(collection_name, key, json)
+      if key.nil?
+        key = self.post_to_collection(collection_name, json)
+      else
+        self.transport.send_request("#{self.base_collection_url}/#{collection_name}/#{key}", :put, json)
+        key
+      end
+    end
+    
+    # Load a config file in YAML format
+    def self.load_config_file(config_file)
+      config_file = File.expand_path(config_file)
+      config_hash = YAML.load(ERB.new(File.read(config_file)).result)
+    end
+    
+    # Perform an HTTP ping to the Riak cluster
+    def ping
+      response = self.transport.get_request("#{self.base_riak_url}/ping")
+    end
+
+    def post_to_collection(collection_name, json)
+      response = self.transport.send_request("#{self.base_collection_url}/#{collection_name}", :post, json)
+      if response.code == 201
+        location = response.headers[:location]
+        key = location.split('/').last
+      else
+        raise Exception, "Error inserting document into collection - key not returned"
+      end
+      key
+    end
+    
+    def set_schema_json(collection_name, json)
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/schema", :put, json)
+    end
+
+    def update_json_object(collection_name, key, json)
+      if key.nil? or key.empty?
+        raise Exception, "Error: cannot update document, key missing"
+      end
+      self.transport.send_request("#{self.base_collection_url}/#{collection_name}/#{key}", :put, json)
+    end
+  end
+end

data/lib/riak_json/client_transport.rb

@@ -0,0 +1,48 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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 'rest-client'
+
+module RiakJson
+  # Used by RiakJson::Client to make HTTP requests
+  class ClientTransport
+    def get_request(url)
+      self.send_request(url, :get)
+    end
+    
+    def send_request(url, http_method, data=nil)
+      begin
+        case http_method
+          when :get
+          response = RestClient.get url, {:content_type => :json}
+          when :put
+            response = RestClient.put url, data, {:content_type => :json, :accept => :json}
+          when :post
+            response = RestClient.post url, data, {:content_type => :json, :accept => :json}
+          when :delete
+            response = RestClient.delete url
+          else
+            raise ArgumentError, "Invalid HTTP :method - #{http_method}"
+        end
+      end
+      response
+    end
+  end
+end

data/lib/riak_json/collection.rb

@@ -0,0 +1,107 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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.
+##
+## -------------------------------------------------------------------
+
+module RiakJson
+  # Manages document read and write operations to RiakJson
+  # Also manages collection schema administration.
+  class Collection
+    attr_accessor :name
+    attr_accessor :client
+    
+    def initialize(collection_name, client)
+      if collection_name.nil? or collection_name.empty?
+        raise ArgumentError, "Invalid collection name (must not be nil or empty)"
+      end
+      @name = collection_name
+      @client = client
+    end
+    
+    def delete_raw_json(key)
+      self.client.delete_json_object(self.name, key)
+    end
+    
+    def delete_schema
+      self.client.delete_schema(self.name)
+    end
+    
+    # Retrieve all documents for a given query json object
+    # @param [String] JSON object representing the query
+    # @return [QueryResult]
+    def find_all(query_json)
+      json_obj = self.client.get_query_all(self.name, query_json)
+      RiakJson::QueryResult.new(json_obj)
+    end
+    
+    def find_by_key(key)
+      json_obj = self.get_raw_json(key)
+      body_hash = JSON.parse(json_obj)
+      RiakJson::Document.new(key, body_hash)
+    end
+    
+    def find_one(query_json)
+      json_obj = self.client.get_query_one(self.name, query_json)
+      return nil if json_obj.nil? or json_obj.empty?
+      body_hash = JSON.parse(json_obj)
+      return nil if body_hash.empty?
+      key = body_hash['_id']
+      RiakJson::Document.new(key, body_hash)
+    end
+    
+    def get_raw_json(key)
+      self.client.get_json_object(self.name, key)
+    end
+    
+    def get_schema
+      self.client.get_schema(self.name)
+    end
+    
+    def has_schema?
+      return true if get_schema rescue false
+    end
+    
+    def insert(document)
+      key = self.insert_raw_json(document.key, document.to_json_document)
+      document.key = key
+    end
+    
+    def insert_raw_json(key, json_obj)
+      key = self.client.insert_json_object(self.name, key, json_obj)
+    end
+    
+    def remove(document)
+      self.delete_raw_json(document.key)
+    end
+    
+    def set_schema(schema)
+      if schema.kind_of? RiakJson::CollectionSchema
+        schema = schema.build
+      end
+      self.client.set_schema_json(self.name, schema)
+    end
+    
+    def update(document)
+      self.update_raw_json(document.key, document.to_json)
+    end
+    
+    def update_raw_json(key, json_obj)
+      self.client.update_json_object(self.name, key, json_obj)
+    end
+  end
+end

data/lib/riak_json/collection_schema.rb

@@ -0,0 +1,61 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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.
+##
+## -------------------------------------------------------------------
+
+module RiakJson
+  # Helper object for creating RiakJson schemas.
+  class CollectionSchema
+    attr_accessor :fields
+    
+    def initialize
+      @fields = []
+    end
+    
+    def add_field(field_type, field_name, required=false)
+      unless self.class.valid_field_types.include? field_type.to_sym
+        raise Exception, "Invalid field type"
+      end
+      self.fields << { name: field_name.to_s, type: field_type.to_s, require: required }
+    end
+    
+    def add_integer_field(field_name, required=false)
+      self.add_field(:integer, field_name, required)
+    end
+
+    def add_multi_string_field(field_name, required=false)
+      self.add_field(:multi_string, field_name, required)
+    end
+
+    def add_string_field(field_name, required=false)
+      self.add_field(:string, field_name, required)
+    end
+    
+    def add_text_field(field_name, required=false)
+      self.add_field(:text, field_name, required)
+    end
+    
+    def build
+      self.fields.to_json
+    end
+    
+    def self.valid_field_types
+      [:text, :string, :multi_string, :integer]
+    end
+  end
+end

data/lib/riak_json/document.rb

@@ -0,0 +1,54 @@
+## ------------------------------------------------------------------- 
+## 
+## Copyright (c) "2013" Basho Technologies, Inc.
+##
+## This file is provided to you 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.
+##
+## -------------------------------------------------------------------
+
+module RiakJson
+  # Implements the RiakJson::Collection api (.key, .to_json_document)
+  # to easily store documents in a RiakJson::Collection
+  class Document
+    attr_accessor :key
+    attr_accessor :body
+    alias_method :attributes, :body
+    
+    def initialize(key=nil, body={})
+      @key = key
+      @body = body
+    end
+    
+    def [](key)
+      @body[key]
+    end
+    
+    def []=(key, value)
+      @body[key] = value
+    end
+    
+    # Returns a JSON string representation
+    def to_json
+      self.body.to_json
+    end
+    
+    # Returns a JSON string representation.
+    # Invoked by RiakJson::Collection to serialize
+    # an object for writing to RiakJson
+    def to_json_document
+      self.to_json
+    end
+  end
+end