simplevoc-open 1.8.0

data/VERSION

@@ -0,0 +1 @@
+1.8.0

data/config.yml.sample

@@ -0,0 +1,4 @@
+protocol: http
+host: localhost
+port: 12345
+strict_mode: true

data/lib/simplevoc-open.rb

@@ -0,0 +1,16 @@
+# Copyright:: 2011 triAGENS GmbH
+# Author:: Oliver Kiessler (mailto:kiessler@inceedo.com)
+require 'rubygems'
+gem 'httparty'
+require 'httparty'
+gem 'json'
+require 'json'
+require 'uri'
+require 'logger'
+require 'yaml'
+
+require File.dirname(__FILE__) + '/simplevoc/open/configuration.rb'
+require File.dirname(__FILE__) + '/simplevoc/open/base.rb'
+require File.dirname(__FILE__) + '/simplevoc/open/client.rb'
+require File.dirname(__FILE__) + '/simplevoc/open/exceptions.rb'
+require File.dirname(__FILE__) + '/simplevoc/open/hash.rb'

data/lib/simplevoc/open/base.rb

@@ -0,0 +1,68 @@
+# Copyright:: 2011 triAGENS GmbH
+# Author:: Oliver Kiessler (mailto:kiessler@inceedo.com)
+module Simplevoc
+  module Open
+    # This ruby library is a REST client for the SimpleVOC key/value store.
+    #
+    # SimpleVOC is a pure in-memory key/value store with a REST Interface. It was developed with easy installation, administration 
+    # and operation in mind. Checkout [World of Voc](http://www.worldofvoc.com) for more information.
+    class Base
+      VERSION = '1.8.0'
+      attr_accessor :configuration, :logger
+
+      # SimpleVOC messages used in the response JSON.
+      MESSAGES = {
+        :stored => "stored",
+        :insert_failed => "use 'PUT /value/<key>' to overwrite value",
+        :deleted => "deleted",
+        :delete_failed => 'key not found',
+        :get_failed => 'key not found',
+        :update_failed => 'not stored',
+        :flush => 'flush started'
+      }
+
+      # === Parameters
+      # * host = Hostname (required)
+      # * port = Port (required)
+      # * protocol = "http"/"https", defaults to "http"
+      # * strict_mode = true/false, defaults to true
+      # * log_level = defaults to LOGGER::INFO
+      def initialize(options = {})
+        default_options = {'host' => 'localhost', 'port' => '12345', 'protocol' => 'http', 'log_level' => Logger::INFO, 'strict_mode' => true}
+        options = default_options.merge(options)
+        options.empty? ? read_configuration : self.configuration = Simplevoc::Open::Configuration.new(options)
+        self.logger = Logger.new(STDOUT)
+        self.logger.level = options['log_level']
+        self.logger.info("SimpleVOC Ruby Client Version: #{VERSION}")
+      end
+
+      protected
+      # Reads the configuration from the current directory and when it doesn't find it falls back to the
+      # global configuration in the home directory (~/.simplevoc.yml) under which this ruby interpreter is run.
+      def read_configuration
+        if File.exists?("config.yml")
+          puts "Using config in this directory"
+          self.configuration = Simplevoc::Open::Configuration.new(YAML.load(File.read("config.yml")))
+        else
+          begin
+            puts "Using config in your home directory"
+            self.configuration = Simplevoc::Open::Configuration.new(YAML.load(File.read("#{ENV['HOME']}/.simplevoc.yml")))
+          rescue Errno::ENOENT
+            raise Simplevoc::Open::ConfigurationMissingException, "config.yml expected in current directory or ~/.simplevoc.yml"
+          end
+        end
+      end
+
+      # Returns the HTTP base URL for the SimpleVOC Rest Service.
+      def base_url
+        "#{self.configuration.options['protocol']}://#{self.configuration.options['host']}:#{self.configuration.options['port']}"
+      end
+
+      # Returns true/false whether to use the client in strict-mode or not.
+      # In strict-mode exceptions are raised for the most common client operations.
+      def use_strict_mode?
+        self.configuration.options['strict_mode']
+      end
+    end
+  end
+end

data/lib/simplevoc/open/client.rb

@@ -0,0 +1,225 @@
+# Copyright:: 2011 triAGENS GmbH
+# Author:: Oliver Kiessler (mailto:kiessler@inceedo.com)
+module Simplevoc
+  module Open
+    # You can setup the client by passing options into the constructor or by using a configuration file in YAML.
+    # client = Simplevoc::Open::Client.new('host' => 'localhost', 'port' => 12345)
+    #
+    # To avoid exceptions, create a client in non-strict mode
+    #
+    # client = Simplevoc::Open::Client.new('host' => 'localhost', 'port' => 12345, 'log_level' => LOGGER::DEBUG, 'strict_mode' => false)
+    class Client < Base
+      # The insert method creates a new key-value pair in SimpleVOC.
+      # === Parameters
+      # * key = Key string
+      # * value = Value string
+      # * options = Optional header options hash with meta values for the values (x-voc-expires, x-voc-flags, x-voc-delete-time, x-voc-flush-delay, x-voc-extended)
+      def insert(key, value, options = {})
+        if key and value
+          response = get_response(:post, "/value/#{key}", options.merge(:body => value.to_s))
+          if response and response.parsed_response
+            return true if response.response.is_a?(Net::HTTPOK) and not response.parsed_response["error"] and response.parsed_response["message"] == MESSAGES[:stored]
+            if response.parsed_response["message"] == MESSAGES[:insert_failed]
+              raise Simplevoc::Open::ValueExistsException, MESSAGES[:insert_failed] if use_strict_mode?
+            else
+              raise Simplevoc::Open::OperationFailedException, response.parsed_response["message"] if use_strict_mode?
+            end
+          end
+        else
+          raise Simplevoc::Open::EmptyKeyException if use_strict_mode? and not key
+          raise Simplevoc::Open::EmptyValueException if use_strict_mode? and not value
+        end
+        false
+      end
+
+      # Convenience method to insert a key-value pair with extended values. The extended value is expected to be a JSON formatted string with
+      # key-values know to the SimpleVOC server. The server needs to be started with the "--server.extended-key-values=your_key:your_type" argument.
+      # === Parameters
+      # * key = Key string
+      # * value = Value string
+      # * extended_values_json = JSON string
+      # * options = Options headers hash
+      def insert_with_extended_values(key, value, extended_values_json, options = {})
+        json = extended_values_json.is_a?(String) ? extended_values_json : extended_values_json.to_json
+        insert(key, value, options.merge(:headers => {'x-voc-extended' => json}))
+      end
+
+      # Updates an existing key-value. The key must exist in SimpleVOC, otherwise an exception is raised.
+      # === Parameters
+      # * key = Key string
+      # * value = Value string
+      # * options = Options headers hash
+      def update(key, value, options = {})
+        if key and value
+          response = get_response(:put, "/value/#{key}", options.merge(:body => value.to_s))
+          if response and response.parsed_response
+            return true if response.response.is_a?(Net::HTTPOK) and not response.parsed_response["error"] and response.parsed_response["message"] == MESSAGES[:stored]
+            if response.parsed_response["message"] == MESSAGES[:update_failed]
+              raise Simplevoc::Open::KeyNotFoundException, MESSAGES[:update_failed] if use_strict_mode?
+            else
+              raise Simplevoc::Open::OperationFailedException, response.parsed_response["message"] if use_strict_mode?
+            end
+          end
+        else
+          raise Simplevoc::Open::EmptyKeyException if use_strict_mode? and not key
+          raise Simplevoc::Open::EmptyValueException if use_strict_mode? and not value
+        end
+        false
+      end
+
+      # Convenience method to insert or update a key-value pair in one go. Raises an exception if the key doesn't exist in SimpleVOC.
+      # === Parameters
+      # * key = Key string
+      # * value = Value string
+      # * options = Options headers hash
+      def insert_or_update(key, value, options = {})
+        if key and value
+          response = get_response(:put, "/value/#{key}?create=1", options.merge(:body => value.to_s))
+          if response and response.parsed_response
+            return true if response.response.is_a?(Net::HTTPOK) and not response.parsed_response["error"] and response.parsed_response["message"] == MESSAGES[:stored]
+            raise Simplevoc::Open::OperationFailedException, response.parsed_response["message"] if use_strict_mode?
+          end
+        else
+          raise Simplevoc::Open::EmptyKeyException if use_strict_mode? and not key
+          raise Simplevoc::Open::EmptyValueException if use_strict_mode? and not value
+        end
+        false
+      end
+
+      # Deletes a key-value pair in SimpleVOC identified by its key. Raises an exception if the key doesn't exist in SimpleVOC.
+      # === Parameters
+      # * key = Key string
+      def delete(key)
+        if key
+          response = get_response(:delete, "/value/#{key}")
+          if response and response.parsed_response
+            return true if response.response.is_a?(Net::HTTPOK) and not response.parsed_response["error"] and response.parsed_response["message"] == MESSAGES[:deleted]
+            if response.parsed_response["message"] == MESSAGES[:delete_failed]
+              raise Simplevoc::Open::KeyNotFoundException, MESSAGES[:delete_failed] if use_strict_mode?
+            else
+              raise Simplevoc::Open::OperationFailedException, response.parsed_response["message"] if use_strict_mode?
+            end
+          end
+        else
+          raise Simplevoc::Open::EmptyKeyException if use_strict_mode?
+        end
+        false
+      end
+
+      # Returns a hash with the value and known meta information about a given key. Raises an exception if the key doesn't exist in SimpleVOC.
+      # === Parameters
+      # * key = Key string
+      # * with_response_headers = true/false, set to true if you only want the value
+      def get(key, with_response_headers = true)
+        if key
+          response = get_response(:get, "/value/#{key}")
+          if response and response.parsed_response
+            if response.response.is_a?(Net::HTTPOK)
+              if with_response_headers
+                sv_response = {'value' => response.parsed_response}
+                sv_response['created'] = DateTime.parse(response.headers['x-voc-created']) if response.headers['x-voc-created']
+                sv_response['expires'] = DateTime.parse(response.headers['x-voc-expires']) if response.headers['x-voc-expires']
+                sv_response['flags'] = response.headers['x-voc-flags'].to_i if response.headers['x-voc-flags']
+                sv_response['extended-values'] = JSON response.headers['x-voc-extended'] if response.headers['x-voc-extended']
+                return sv_response
+              else
+                return response.parsed_response
+              end
+            elsif response.parsed_response.is_a?(::Hash) and response.parsed_response["error"] and response.parsed_response["message"] == MESSAGES[:get_failed]
+              raise Simplevoc::Open::KeyNotFoundException, MESSAGES[:get_failed] if use_strict_mode?
+            end
+          end
+        else
+          raise Simplevoc::Open::EmptyKeyException if use_strict_mode?
+        end
+        nil
+      end
+
+      # Returns an array of known keys. Use a prefix to query for keys and you can also use a filter expression. Raises an exception if the prefix is
+      # unknown or doesn't match.
+      # === Parameters
+      # * prefix = Prefix string
+      # * filter = Optional filter expression
+      def keys(prefix, filter = nil)
+        if prefix
+          response = get_response(:get, filter ? "/keys/#{prefix}?filter=#{filter}" : "/keys/#{prefix}")
+          if response.response.is_a?(Net::HTTPOK)
+            return response.parsed_response
+          elsif response.response.is_a?(Net::HTTPNoContent)
+            raise Simplevoc::Open::NoContentAtURLPathException if use_strict_mode?
+          else
+            raise Simplevoc::Open::PrefixNotFoundException if use_strict_mode?
+          end
+        else
+          raise Simplevoc::Open::EmptyPrefixException if use_strict_mode?
+        end
+        nil
+      end
+
+      # Deletes all key-value pairs in SimpleVOC.
+      def flush
+        response = get_response(:put, "/flush")
+        if response and response.parsed_response
+          return true if response.response.is_a?(Net::HTTPOK) and response.parsed_response["message"] == MESSAGES[:flush]
+          raise Simplevoc::Open::OperationFailedException, response.parsed_response["message"] if use_strict_mode?
+        end
+        false
+      end
+
+      # Returns information about the SimpleVOC server.
+      def server_info
+        info = {}
+        response = get_response(:get, '/version')
+        if response and response.parsed_response
+          info['version'] = response.parsed_response['version']
+          info['server'] = response.header['server']
+        end
+        info
+      end
+
+      # Returns the server version of the SimpleVOC server.
+      def server_version
+        server_info['version']
+      end
+
+      # Convenience method to create a option headers hash with common attributes.
+      # === Parameters
+      # * expires
+      # * flags
+      # * delete_time
+      # * flush_delay
+      # === Examples
+      # expires = your_time_object.utc.iso8601
+      # flags = 1
+      def extra_options(expires = nil, flags = nil, delete_time = nil, flush_delay = nil)
+        options = {:headers => {}}
+        options[:headers]['x-voc-expires'] = expires.to_s if expires
+        options[:headers]['x-voc-flags'] = flags.to_s if flags
+        options[:headers]['x-voc-delete-time'] = delete_time.to_s if delete_time
+        options[:headers]['x-voc-flush-delay'] = flush_delay.to_s if flush_delay
+        logger.debug "Using header options: #{options[:headers].inspect}"
+        options
+      end
+
+      private
+      # Internal method to create the httparty request and return the http response that is already parsed by httparty.
+      # === Parameters
+      # * http_verb = HTTP verb symbol (:get, :post, :put, :delete)
+      # * endpoint = HTTP URL endpoint
+      # * options = Optional options with body and headers 
+      def get_response(http_verb, endpoint, options = {})
+        begin
+          endpoint_value = "#{base_url}#{URI.escape(endpoint)}"
+          logger.debug "Using endpoint: #{endpoint_value}"
+          body = {}; body.merge!(options) if options and options.any?
+          response = (http_verb == :post or http_verb == :put) ? HTTParty.send(http_verb, endpoint_value, body) : HTTParty.send(http_verb, endpoint_value)
+          logger.debug "Response: #{response.inspect}" if response
+          response
+        rescue => e
+          logger.error("Could not connect to SimpleVOC: #{e.message}")
+          raise Simplevoc::Open::ConnectionRefusedException
+        end
+      end
+    end
+  end
+end

data/lib/simplevoc/open/configuration.rb

@@ -0,0 +1,24 @@
+# Copyright:: 2011 triAGENS GmbH
+# Author:: Oliver Kiessler (mailto:kiessler@inceedo.com)
+module Simplevoc
+  module Open
+    # You can also provide a configuration file in the current directory of your client to avoid setting up the client within your code.
+    # Checkout the config.yml.sample file as an example.
+    # 
+    # If this configuration file isn't found in the current directory, the client will look for a "global" configuration file in your 
+    # home directory (~/.simplevoc.yml).
+    class Configuration
+      attr_accessor :options
+
+      # === Parameters
+      # * host = Hostname (required)
+      # * port = Port (required)
+      # * protocol = "http"/"https", defaults to "http"
+      # * strict_mode = true/false, defaults to true
+      # * log_level = defaults to LOGGER::INFO
+      def initialize(options)
+        self.options = options
+      end
+    end
+  end
+end

data/lib/simplevoc/open/exceptions.rb

@@ -0,0 +1,40 @@
+# Copyright:: 2011 triAGENS GmbH
+# Author:: Oliver Kiessler (mailto:kiessler@inceedo.com)
+module Simplevoc
+  module Open
+    # The ConfigurationMissingException is raised when no configuration options are provided
+    # to the client constructor, a config.yml is missing in the current directory or a global
+    # configuration can't be found in the home directory.
+    class ConfigurationMissingException < Exception; end
+  
+    # The EmptyKeyException is raised when an empty key was passed to the Client#insert, Client#insert_or_update,
+    # Client#update or Client#delete methods.
+    class EmptyKeyException < Exception; end
+  
+    # The EmptyValueException is raised when nil is passed into a Client#insert, Client#insert_or_update or 
+    # Client#update method.
+    class EmptyValueException < Exception; end
+  
+    # The ValueExistsException is raised when a value for an existing key is passed to the Client#insert method.
+    class ValueExistsException < Exception; end
+
+    # The ConnectionRefusedException is raised when the HTTP connection to the SimpleVOC server fails.
+    class ConnectionRefusedException < Exception; end
+  
+    # The KeyNotFoundException is raised when a key doesn't exist during a Client#get method call.
+    class KeyNotFoundException < Exception; end
+  
+    # The OperationFailedException is a general exception that is raised during a REST method call. Returns the error
+    # message from the SimpleVOC server.
+    class OperationFailedException < Exception; end
+  
+    # The EmptyPrefixException is raised when no prefix is passed to the Client#keys method.
+    class EmptyPrefixException < Exception; end
+  
+    # The PrefixNotFoundException is raised when the Client#keys method doesn't return a result for a given prefix.
+    class PrefixNotFoundException < Exception; end
+  
+    # The NoContentAtURLPathException can be raised by the Client#keys method when the given prefix can't be interpreted.
+    class NoContentAtURLPathException < Exception; end
+  end
+end

data/lib/simplevoc/open/hash.rb

@@ -0,0 +1,68 @@
+# Copyright:: 2011 triAGENS GmbH
+# Author:: Oliver Kiessler (mailto:kiessler@inceedo.com)
+module Simplevoc
+  module Open
+    # The Simplevoc Hash serves as a simple non-strict mode alternative to the regular client class.
+    #
+    # hash = Simplevoc::Open::Hash.new('host' => 'localhost', 'port' => 12345)
+    #
+    # === Examples:
+  	# hash["key"] = "value" (create or update)
+  	#
+  	# hash["key"] (get)
+  	#
+  	# hash.delete("key")
+  	#
+  	# hash.include?("key") (check for existence of a key in simplevoc)
+  	#
+  	# hash.values_at(["key", "key2"]) (get multiple values at once)
+  	#
+  	# returns: {"key" => "value", "key2" => "value2"}
+    class Hash < Client
+      # === Parameters
+      # * host = Hostname (required)
+      # * port = Port (required)
+      # * protocol = "http"/"https", defaults to "http"
+      # * strict_mode = true/false, defaults to false
+      # * log_level = defaults to LOGGER::INFO
+      def initialize(options = {})
+        super(options.merge('strict_mode' => false))
+      end
+
+      # Insert key-value pair.
+      def []=(key, value)
+        insert_or_update(key, value)
+      end
+      # Alias for Hash#[]=.
+      def store(key, value); self[key] = value; end
+
+      # Getter for key-value pair.
+      def [](key)
+        get(key, false)
+      end
+      # Alias for Hash#[].
+      def fetch(key); self[key]; end
+
+      # Checks for the existance of a key-value pair in SimpleVOC.
+      def has_key?(key)
+        not get(key, false).nil?
+      end
+      # Alias for Hash#has_key?.
+      def include?(key); self.has_key?(key); end
+      # Alias for Hash#has_key?.
+      def key?(key); self.has_key?(key); end
+      # Alias for Hash#has_key?.
+      def member?(key); self.has_key?(key); end
+
+      # Convenience method to fetch values for a given list of keys.
+      def values_at(keys = [])
+        return_values = {}
+        keys.each {|key| return_values[key] = get(key, false)}
+        return_values
+      end
+
+      # Alias for Client#flush.
+      def clear; flush; end
+    end
+  end
+end