riak-client 0.9.8 → 1.0.0.beta

data/lib/riak/json.rb

@@ -1,11 +1,6 @@
-# Load JSON
-unless defined? JSON
-  begin
-    require 'yajl/json_gem'
-  rescue LoadError
-    require 'json'
-  end
-end
+require 'multi_json'
+MultiJson.engine # Force loading of an engine
+require 'riak/core_ext/json'
 
 module Riak
   class << self
@@ -14,4 +9,20 @@ module Riak
     attr_accessor :json_options
   end
   self.json_options = {:max_nesting => 20}
+
+  # JSON module for internal use inside riak-client
+  module JSON
+    class << self
+      # Parse a JSON string
+      def parse(str)
+        MultiJson.decode(str, Riak.json_options)
+      end
+
+      # Generate a JSON string
+      def encode(obj)
+        MultiJson.encode(obj)
+      end
+      alias :dump :encode
+    end
+  end
 end

data/lib/riak/link.rb

@@ -1,16 +1,3 @@
-# Copyright 2010 Sean Cribbs, Sonian Inc., 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.
 
 require 'riak/util/translation'
 require 'riak/util/escape'
@@ -34,7 +21,10 @@ module Riak
     attr_accessor :key
 
     %w{bucket key}.each do |m|
-      class_eval %{ def #{m}=(value); @url = nil; @#{m} = value; end }
+      define_method("#{m}=") { |value|
+        @url = nil
+        instance_variable_set("@#{m}", value)
+      }
     end
 
     # @param [String] header_string the string value of the Link: HTTP header from a Riak response
@@ -62,20 +52,28 @@ module Riak
     end
 
     # @return [String] the URL (relative or absolute) of the related resource
-    def url
-      @url ||= "/riak/#{escape(bucket)}" + (key.blank? ? "" : "/#{escape(key)}")
+    def url(new_scheme=false)
+      if @bucket
+        if new_scheme
+          "/buckets/#{escape(bucket)}" + (key.blank? ? "" : "/keys/#{escape(key)}")
+        else
+          "/riak/#{escape(bucket)}" + (key.blank? ? "" : "/#{escape(key)}")
+        end
+      else
+        @url
+      end
     end
 
     def url=(value)
       @url = value
-      @bucket = unescape($1) if value =~ %r{^/[^/]+/([^/]+)/?}
-      @key = unescape($1) if value =~ %r{^/[^/]+/[^/]+/([^/]+)/?}
+      @bucket = unescape($1) if value =~ %r{^/buckets/([^/]+)/?} || value =~ %r{^/[^/]+/([^/]+)/?}
+      @key = unescape($1) if value =~ %r{^/buckets/[^/]+/keys/([^/]+)/?} || value =~ %r{^/[^/]+/[^/]+/([^/]+)/?}
     end
 
     def inspect; to_s; end
 
-    def to_s
-      %Q[<#{url}>; riaktag="#{tag}"]
+    def to_s(new_scheme=false)
+      %Q[<#{url(new_scheme)}>; riaktag="#{tag}"]
     end
 
     def hash

data/lib/riak/locale/en.yml

@@ -1,27 +1,18 @@
-# Copyright 2010 Sean Cribbs, Sonian Inc., 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.
 en:
   riak:
+    backwards_clock: "System clock moved backwards, ID generation will fail for %{delay} more milliseconds."
     bucket_link_conversion: "Can't convert a bucket link to a walk spec"
     client_type: "invalid argument %{client} is not a Riak::Client"
+    conflict_resolver_invalid: "The given resolver (%{resolver}) did not respond to :call"
     content_type_undefined: "content_type is not defined!"
     deprecated:
       port: "DEPRECATION: Riak::Client#port has been deprecated, use #http_port or #pb_port for the appropriate protocol.\n%{backtrace}"
+      search: "DEPRECATION: Riak Search features are included in the main client, you no longer need to require 'riak/search'.\n%{backtrace}"
     empty_map_reduce_query: "Specify one or more query phases to your MapReduce."
     failed_request: "Client request failed."
     filter_needs_block: "Filter %{filter} expects a block."
     filter_arity_mismatch: "Filter %{filter} expects %{expected} arguments but %{received} were given."
+    full_bucket_mapred: "Full-bucket MapReduce, including key filters, invokes list-keys which is an expensive operation that should not be used in production.\n    %{backtrace}"
     hash_type: "invalid argument %{hash} is not a Hash"
     http_configuration: "The %{backend} HTTP backend cannot be used. Please check its requirements."
     http_failed_request: "Expected %{expected} from Riak but received %{code}. %{body}"
@@ -29,23 +20,29 @@ en:
     protocol_invalid: "'%{invalid}' is not a valid protocol, valid values are %{valid}"
     invalid_basic_auth: "basic auth must be set using 'user:pass'"
     invalid_client_id: "Invalid client ID, must be a string or between 0 and %{max_id}"
+    invalid_io_object: "Invalid IO-like object assigned to RObject#data.  It should be assigned to raw_data instead."
     invalid_function_value: "invalid value for function: %{value}"
     invalid_options: "Invalid configuration options given."
     invalid_phase_type: "type must be :map, :reduce, or :link"
-    invalid_response: "Expected %{expected} but received %{received} from Riak %{extra}"
     invalid_ssl_verify_mode: "%{invalid} is not a valid :verify_mode option for SSL. Valid options are 'peer' and 'none'."
+    invalid_index_query: "%{value} is not a valid index query term, only Strings, Integers, and Ranges of those are allowed."
+    indexes_unsupported: "Riak server does not support secondary indexes."
     loading_bucket: "while loading bucket '%{name}'"    
+    list_buckets: "Riak::Client#buckets is an expensive operation that should not be used in production.\n    %{backtrace}"
+    list_keys: "Riak::Bucket#keys is an expensive operation that should not be used in production.\n    %{backtrace}"
     missing_block: "A block must be given."
     missing_host_and_port: "You must specify a host and port, or use the defaults of 127.0.0.1:8098"
     module_function_pair_required: "function must have two elements when an array"
     not_found: "The requested object was not found."
-    path_and_body_required: "You must supply both a resource path and a body."
+    no_pipes: "Could not find or open pipes for Riak console in %{path}."
     port_invalid: "port must be an integer between 0 and 65535"
     protobuffs_failed_request: "Expected success from Riak but received %{code}. %{body}"
     request_body_type: "Request body must be a String or respond to :read."
-    resource_path_short: "Resource path too short"
+    search_unsupported: "Riak server does not support search."
     search_docs_require_id: "Search index documents must include the 'id' field."
     search_remove_requires_id_or_query: "Search index documents to be removed must have 'id' or 'query' keys."
+    serializer_not_implemented: "No serializer has been registered for content type %{content_type}"
+    source_and_root_required: "Riak::Node configuration must include :source and :root keys."
     stale_write_prevented: "Stale write prevented by client."
     stored_function_invalid: "function must have :bucket and :key when a hash"
     string_type: "invalid_argument %{string} is not a String"

data/lib/riak/map_reduce.rb

@@ -1,17 +1,3 @@
-# Copyright 2010 Sean Cribbs, Sonian Inc., 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.
-
 require 'riak/util/translation'
 require 'riak/util/escape'
 require 'riak/json'
@@ -81,20 +67,23 @@ module Riak
         p = params.first
         case p
         when Bucket
-          @inputs = escape(p.name)
+          warn(t('full_bucket_mapred', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
+          @inputs = maybe_escape(p.name)
         when RObject
-          @inputs << [escape(p.bucket.name), escape(p.key)]
+          @inputs << [maybe_escape(p.bucket.name), maybe_escape(p.key)]
         when String
-          @inputs = escape(p)
+          warn(t('full_bucket_mapred', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
+          @inputs = maybe_escape(p)
         end
       when 2..3
         bucket = params.shift
         bucket = bucket.name if Bucket === bucket
         if Array === params.first
-          @inputs = {:bucket => escape(bucket), :key_filters => params.first }
+          warn(t('full_bucket_mapred', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
+          @inputs = {:bucket => maybe_escape(bucket), :key_filters => params.first }
         else
           key = params.shift
-          @inputs << params.unshift(escape(key)).unshift(escape(bucket))
+          @inputs << params.unshift(maybe_escape(key)).unshift(maybe_escape(bucket))
         end
       end
       self
@@ -112,6 +101,37 @@ module Riak
       add(bucket, FilterBuilder.new(&block).to_a)
     end
 
+    # (Riak Search) Use a search query to start a map/reduce job.
+    # @param [String, Bucket] bucket the bucket/index to search
+    # @param [String] query the query to run
+    # @return [MapReduce] self
+    def search(bucket, query)
+      bucket = bucket.name if bucket.respond_to?(:name)
+      @inputs = {:module => "riak_search", :function => "mapred_search", :arg => [bucket, query]}
+      self
+    end
+
+    # (Secondary Indexes) Use a secondary index query to start a
+    # map/reduce job.
+    # @param [String, Bucket] bucket the bucket whose index to query
+    # @param [String] index the index to query
+    # @param [String, Integer, Range] query the value of the index, or
+    #   a range of values (of Strings or Integers)
+    # @return [MapReduce] self
+    def index(bucket, index, query)
+      bucket = bucket.name if bucket.respond_to?(:name)
+      case query
+      when String, Fixnum
+        @inputs = {:bucket => maybe_escape(bucket), :index => index, :key => query}
+      when Range
+        raise ArgumentError, t('invalid_index_query', :value => query.inspect) unless String === query.begin || Integer === query.begin
+        @inputs = {:bucket => maybe_escape(bucket), :index => index, :start => query.begin, :end => query.end}
+      else
+        raise ArgumentError, t('invalid_index_query', :value => query.inspect)
+      end
+      self
+    end
+
     # Add a map phase to the job.
     # @overload map(function)
     #   @param [String, Array] function a Javascript function that represents the phase, or an Erlang [module,function] pair
@@ -194,7 +214,7 @@ module Riak
     #   @return [nil] nothing
     def run(&block)
       raise MapReduceError.new(t("empty_map_reduce_query")) if @query.empty?
-      @client.backend.mapred(self, &block)
+      @client.mapred(self, &block)
     rescue FailedRequest => fr
       if fr.server_error? && fr.is_json?
         raise MapReduceError.new(fr.body)

data/lib/riak/map_reduce/filter_builder.rb

@@ -1,16 +1,3 @@
-# Copyright 2010 Sean Cribbs, Sonian Inc., 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.
 
 require 'riak/util/translation'
 
@@ -66,15 +53,24 @@ module Riak
       LOGICAL_OPERATIONS = %w{and or not}
 
       FILTERS.each do |f,arity|
-        class_eval <<-CODE
-          def #{f}(*args)
-            raise ArgumentError.new(t("filter_arity_mismatch", :filter => :#{f}, :expected => #{arity.inspect}, :received => args.size)) unless #{arity.inspect} == -1 || Array(#{arity.inspect}).include?(args.size)
-            @filters << ([:#{f}] + args)
+        arities = [arity].flatten
+
+        define_method(f) { |*args|
+          unless arities.include?(-1) or arities.include?(args.size)
+            raise ArgumentError.new t("filter_arity_mismatch",
+              :filter => f,
+              :expected => arities,
+              :received => args.size
+            )
           end
-        CODE
+
+          @filters << [f, *args]
+        }
       end
 
       LOGICAL_OPERATIONS.each do |op|
+        # NB: string eval is needed here because in ruby 1.8, blocks can't yield to
+        # other blocks
         class_eval <<-CODE
           def _#{op}(&block)
             raise ArgumentError.new(t('filter_needs_block', :filter => '#{op}')) unless block_given?

data/lib/riak/map_reduce/phase.rb

@@ -1,16 +1,3 @@
-# Copyright 2010 Sean Cribbs, Sonian Inc., 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.
 
 require 'riak/json'
 require 'riak/util/translation'

data/lib/riak/map_reduce_error.rb

@@ -1,16 +1,3 @@
-# Copyright 2010 Sean Cribbs, Sonian Inc., 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.
 require 'riak/util/translation'
 
 module Riak

data/lib/riak/node.rb

@@ -0,0 +1,38 @@
+require 'riak/util/translation'
+require 'riak/node/defaults'
+require 'riak/node/configuration'
+require 'riak/node/generation'
+require 'riak/node/control'
+require 'riak/node/version'
+require 'riak/node/log'
+
+module Riak
+  # A Node encapsulates the generation and management of standalone
+  # Riak nodes. It is used by the {TestServer} to start and manage an
+  # in-memory node for supporting integration test suites.
+  class Node
+    include Util::Translation
+
+    # Creates a new Riak node. Unlike {#new}, this will also generate
+    # the node if it does not exist on disk.  Equivalent to {::new}
+    # followed by {#create}.
+    # @see #new
+    def self.create(configuration={})
+      new(configuration).tap do |node|
+        node.create
+      end
+    end
+
+    # Creates the template for a Riak node. To generate the node after
+    # initialization, use {#create}.
+    def initialize(configuration={})
+      set_defaults
+      configure configuration
+    end
+
+    protected
+    def debug(msg)
+      $stderr.puts msg if ENV["DEBUG_RIAK_NODE"]
+    end
+  end
+end

data/lib/riak/node/configuration.rb

@@ -0,0 +1,286 @@
+require 'pathname'
+require 'yaml'
+
+module Riak
+  class Node
+    # The directories (and accessor methods) that will be created
+    # under the generated node.
+    NODE_DIRECTORIES = [:bin, :etc, :log, :data, :ring, :pipe]
+
+    NODE_DIRECTORIES.each do |dir|
+      # Makes accessor methods for all the node directories that
+      # return Pathname objects.
+      class_eval %Q{
+        def #{dir}
+          root + '#{dir}'
+        end
+      }
+    end
+
+    # @return [Hash] the contents of the Erlang environment, which will
+    #   be created into the app.config file.
+    attr_reader :env
+
+    # @return [Hash] the command-line switches for the Erlang virtual
+    #   machine, which will be created into the vm.args file
+    attr_reader :vm
+
+    # @return [Hash] the configuration that was passed to the Node
+    #   when initialized
+    attr_reader :configuration
+
+    # @return [Array<Pathname>] where user Erlang code will be loaded from
+    def erlang_sources
+      env[:riak_kv][:add_paths].map {|p| Pathname.new(p) }
+    end
+
+    # @return [Pathname] where user Javascript code will be loaded from
+    def javascript_source
+      Pathname.new(env[:riak_kv][:js_source_dir])
+    end
+
+    # @return [Fixnum] the size of the ring, i.e. number of partitions
+    def ring_size
+      env[:riak_core][:ring_creation_size]
+    end
+
+    # @return [Fixnum] The port used for handing off data to other nodes.
+    def handoff_port
+      env[:riak_core][:handoff_port]
+    end
+
+    # @return [Fixnum] The port to which the HTTP API is connected.
+    def http_port
+      # We'll only support 0.14 and later, which uses http rather than web_ip/web_port
+      env[:riak_core][:http][0][1]
+    end
+
+    # @return [Fixnum] the port to which the Protocol Buffers API is connected.
+    def pb_port
+      env[:riak_kv][:pb_port]
+    end
+
+    # @return [String] the interface to which the HTTP API is connected
+    def http_ip
+      env[:riak_core][:http][0][0]
+    end
+
+    # @return [String] the interface to which the Protocol Buffers API is connected
+    def pb_ip
+      env[:riak_kv][:pb_ip]
+    end
+
+    # @return [Symbol] the storage backend for Riak Search.
+    def search_backend
+      env[:riak_search][:search_backend]
+    end
+
+    # @return [Symbol] the storage backend for Riak KV.
+    def kv_backend
+      env[:riak_kv][:storage_backend]
+    end
+
+    # @return [String] the name of the Riak node as seen by distributed Erlang
+    #   communication. AKA "-name" in vm.args.
+    def name
+      vm['-name']
+    end
+
+    # @return [String] the cookie/shared secret used for connecting
+    #    a cluster
+    def cookie
+      vm['-setcookie']
+    end
+
+    # The source of the Riak installation from where the {Node} will
+    # be generated. This should point to the directory that contains
+    # the 'riak[search]' and 'riak[search]-admin' scripts.
+    # @return [Pathname] the source Riak installation
+    attr_reader :source
+
+    # The root directory of the {Node}, where all files are placed
+    # after generation.
+    # @return [Pathname] the root directory of the node
+    attr_reader :root
+
+    # The script for starting, stopping and pinging the Node.
+    # @return [Pathname] the path to the control script
+    def control_script
+      @control_script ||= root + 'bin' + control_script_name
+    end
+
+    # The name of the 'riak' or 'riaksearch' control script.
+    # @return [String] 'riak' or 'riaksearch'
+    def control_script_name
+      @control_script_name ||= (source + 'riaksearch').exist? ? 'riaksearch' : 'riak'
+    end
+
+    # The script for controlling non-lifecycle features of Riak like
+    # joining, leaving, status, ringready, etc.
+    # @return [Pathname] the path to the administrative script
+    def admin_script
+      @admin_script ||= root + 'bin' + "#{control_script_name}-admin"
+    end
+
+    # The "manifest" file where the node configuration will be
+    # written.
+    # @return [Pathname] the path to the manifest
+    def manifest
+      root + '.node.yml'
+    end
+
+    protected
+    # Populates the proper node configuration from the input config.
+    def configure(hash)
+      raise ArgumentError, t('source_and_root_required') unless hash[:source] && hash[:root]
+      @configuration = hash
+      configure_paths
+      configure_manifest
+      configure_settings
+      configure_logging
+      configure_data
+      configure_ports(hash[:interface], hash[:min_port])
+      configure_name(hash[:interface])
+    end
+
+    # Reads the manifest if it exists, overrides the passed configuration.
+    def configure_manifest
+      @configuration = YAML.load_file(manifest.to_s) if exist?
+    end
+
+    # Sets the data directories for the various on-disk backends and
+    # the ring state.
+    def configure_data
+      [:bitcask, :eleveldb, :merge_index].each {|k| env[k] ||= {} }
+      env[:bitcask][:data_root] ||= (data + 'bitcask').expand_path.to_s
+      env[:eleveldb][:data_root] ||= (data + 'leveldb').expand_path.to_s
+      env[:merge_index][:data_root] ||= (data + 'merge_index').expand_path.to_s
+      env[:riak_core][:ring_state_dir] ||= ring.expand_path.to_s
+      NODE_DIRECTORIES.each do |dir|
+        next if [:ring, :pipe].include?(dir)
+        env[:riak_core][:"platform_#{dir}_dir"] ||= send(dir).to_s
+      end
+    end
+
+    # Sets directories and handlers for logging.
+    def configure_logging
+      if env[:lager]
+        env[:lager][:handlers] = {
+          :lager_file_backend => [
+                                  Tuple[(log+"error.log").expand_path.to_s, :error],
+                                  Tuple[(log+"console.log").expand_path.to_s, :info]
+                                 ]
+        }
+        env[:lager][:crash_log] = (log+"crash.log").to_s
+      else
+        # TODO: Need a better way to detect this, the defaults point
+        # to 1.0-style configs. Maybe there should be some kind of
+        # detection routine.
+        # Use sasl error logger for 0.14.
+        env[:riak_err] ||= {
+          :term_max_size => 65536,
+          :fmt_max_bytes => 65536
+        }
+        env[:sasl] = {
+          :sasl_error_logger => Tuple[:file, (log+"sasl-error.log").expand_path.to_s],
+          :errlog_type => :error,
+          :error_logger_mf_dir => (log+"sasl").expand_path.to_s,
+          :error_logger_mf_maxbytes => 10485760,
+          :error_logger_mf_maxfiles => 5
+        }
+      end
+      vm['-env ERL_CRASH_DUMP'] =  (log + 'erl_crash.dump').to_s
+    end
+
+    # Sets the node name and cookie for distributed Erlang.
+    def configure_name(interface)
+      interface ||= "127.0.0.1"
+      vm["-name"] ||= configuration[:name] || "riak#{rand(1000000).to_s}@#{interface}"
+      vm["-setcookie"] ||= configuration[:cookie] || "#{rand(100000).to_s}_#{rand(1000000).to_s}"
+    end
+
+    # Merges input configuration with the defaults.
+    def configure_settings
+      @env = deep_merge(env.dup, configuration[:env]) if configuration[:env]
+      @vm = vm.merge(configuration[:vm]) if configuration[:vm]
+    end
+
+    # Sets the source directory and root directory of the generated node.
+    def configure_paths
+      @source = Pathname.new(configuration[:source]).expand_path
+      @root = Pathname.new(configuration[:root]).expand_path
+    end
+
+    # Sets ports and interfaces for http, protocol buffers, and handoff.
+    def configure_ports(interface, min_port)
+      interface ||= "127.0.0.1"
+      min_port ||= 8080
+      unless env[:riak_core][:http]
+        env[:riak_core][:http] = [Tuple[interface, min_port]]
+        min_port += 1
+      end
+      env[:riak_core][:http] = env[:riak_core][:http].map {|pair| Tuple[*pair] }
+      env[:riak_kv][:pb_ip] = interface unless env[:riak_kv][:pb_ip]
+      unless env[:riak_kv][:pb_port]
+        env[:riak_kv][:pb_port] = min_port
+        min_port += 1
+      end
+      unless env[:riak_core][:handoff_port]
+        env[:riak_core][:handoff_port] = min_port
+        min_port += 1
+      end
+    end
+
+    # Implements a deep-merge of two {Hash} instances.
+    # @param [Hash] source the original hash
+    # @param [Hash] target the new hash
+    # @return [Hash] a {Hash} whose {Hash} values have also been merged
+    def deep_merge(source, target)
+      source.merge(target) do |key, old_val, new_val|
+        if Hash === old_val && Hash === new_val
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+
+    # This class lets us specify that some settings should be emitted
+    # as Erlang tuples, even though the first element is not
+    # necessarily a Symbol.
+    class Tuple < Array; end
+
+    # Recursively converts a {Hash} into an Erlang configuration
+    # string that is appropriate for the app.config file.
+    # @param [Hash] hash a collection of configuration values
+    # @param [Fixnum] depth the current nesting level of
+    #    generation/indentation
+    # @return [String] Erlang proplists in a String for use in
+    #   app.config
+    def to_erlang_config(hash, depth = 1)
+      padding = '    ' * depth
+      parent_padding = '    ' * (depth-1)
+      values = hash.map do |k,v|
+        "{#{k}, #{value_to_erlang(v, depth)}}"
+      end.join(",\n#{padding}")
+      "[\n#{padding}#{values}\n#{parent_padding}]"
+    end
+
+    # Converts a value to an Erlang term. Mutually recursive with
+    # {#to_erlang_config}.
+    def value_to_erlang(v, depth=1)
+      case v
+      when Hash
+        to_erlang_config(v, depth+1)
+      when String
+        "\"#{v}\""
+      when Tuple
+        "{" << v.map {|i| value_to_erlang(i, depth+1) }.join(", ") << "}"
+      when Array
+        "[" << v.map {|i| value_to_erlang(i, depth+1) }.join(", ") << "]"
+      else
+        v.to_s
+      end
+    end
+  end
+end