chef-encrypted-attributes 0.3.0 → 0.4.0

data/lib/chef/encrypted_attribute/search_helper.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@onddo.com>)
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
@@ -21,124 +22,263 @@ require 'chef/encrypted_attribute/exceptions'
 
 class Chef
   class EncryptedAttribute
+    # Search Helpers to do normal or partial searches.
     module SearchHelper
       extend self
 
+      # Gets a Chef Search Query object.
+      #
+      # @return [Chef::Search::Query] search query object instance.
+      # @api private
       def query
         Chef::Search::Query.new
       end
 
+      # Escapes a search query string to be used in URLs.
+      #
+      # @param str [String] query to escape.
+      # @return [String] escaped query string.
+      # @api private
       def escape(str)
         URI.escape(str.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
       end
 
+      # Escapes a search query array.
+      #
+      # When multiple queries are provided, the result will be *OR*-ed.
+      #
+      # @param query [Array<String>, String] search query.
+      # @return [String] escaped query string.
       def escape_query(query)
-        query_s = if query.kind_of?(Array)
-          query.map do |item|
-            "( #{item} )"
-          end.compact.join(' OR ')
-        else
-          query.to_s
-        end
+        query_s =
+          if query.is_a?(Array)
+            query.map { |item| "( #{item} )" }.compact.join(' OR ')
+          else
+            query.to_s
+          end
         escape(query_s)
       end
 
+      # Checks if a Hash key from a search keys structure format is correct.
+      #
+      # @param k [Mixed] hash key to check.
+      # @return [Boolean] `true` if key is a `String` or a `Symbol`.
+      # @api private
+      def valid_search_keys_key?(k)
+        k.is_a?(String) || k.is_a?(Symbol)
+      end
+
+      # Checks if a Hash value from a search keys structure format is correct.
+      #
+      # @param v [Mixed] hash value to check.
+      # @return [Boolean] `true` if value is a `Array<String>`.
+      # @api private
+      def valid_search_keys_value?(v)
+        return false unless v.is_a?(Array)
+        v.reduce(true) { |a, e| a && e.is_a?(String) }
+      end
+
+      # Checks if a search keys structure format is correct.
+      #
+      # This is an example of a correct search structure:
+      #
+      # ```ruby
+      # {
+      #   ipaddress: %w(ipaddress),
+      #   mysql_version: %w(mysql version)
+      # }
+      # ```
+      #
+      # @param keys [Hash] search keys structure.
+      # @return [Boolean] `true` if search keys structure format is correct.
+      # @api private
       def valid_search_keys?(keys)
-        return false unless keys.kind_of?(Hash)
+        return false unless keys.is_a?(Hash)
         keys.reduce(true) do |r, (k, v)|
-          r && unless k.kind_of?(String) || k.kind_of?(Symbol) and v.kind_of?(Array)
-            false
-          else
-            v.reduce(true) do |r, x|
-              r and x.kind_of?(String)
-            end
-          end
+          r && valid_search_keys_key?(k) && valid_search_keys_value?(v)
         end
       end
 
+      # Assert that the search keys structure format is correct.
+      #
+      # @return void
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      # @api private
+      def assert_search_keys(keys)
+        return if valid_search_keys?(keys)
+        fail InvalidSearchKeys, "Invalid search keys: #{keys.inspect}"
+      end
+
+      # Check if search query is empty.
+      #
+      # @param query [Array<String>, String] search query.
+      # @return [Boolean] `true` if search query is empty.
+      # @api private
       def empty_search?(query)
-        query.kind_of?(String) && query.empty? or
-        query.kind_of?(Array) && query.count == 0
+        query.is_a?(String) && query.empty? ||
+          query.is_a?(Array) && query.count == 0
       end
 
-      def search(type, query, keys, rows=1000, partial_search=true)
+      # Does a search in the Chef Server.
+      #
+      # @param type [Symbol] search index to use. See [Chef Search Indexes]
+      #   (http://docs.getchef.com/chef_search.html#search-indexes).
+      # @param query [Array<String>, String] search query. For example:
+      #   `%w(admin:true)`. Results will be *OR*-ed when multiple string queries
+      #   are provided.
+      # @param keys [Hash] search keys structure. For example:
+      #   `{ipaddress: %w(ipaddress), mysql_version: %w(mysql version) }`.
+      # @param rows [Fixnum, String] maximum number of rows to return.
+      # @param partial_search [Boolean] whether to use partial search.
+      # @return [Array<Hash>] An array with the response, for example:
+      #   `[{ 'ipaddress' => '192.168.1.1' }]`
+      # @raise [SearchFailure] if there is a Chef search error.
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      def search(type, query, keys, rows = 1000, partial_search = true)
         return [] if empty_search?(query) # avoid empty searches
-        if partial_search
-          partial_search(type, query, keys, rows)
-        else
-          normal_search(type, query, keys, rows)
+        search_method = partial_search ? :partial_search : :normal_search
+        send(search_method, type, query, keys, rows)
+      rescue Net::HTTPServerException => e
+        unless e.response.is_a?(Net::HTTPResponse) && e.response.code == '404'
+          raise SearchFailure, "Search exception #{e.class}: #{e}"
         end
+        return []
+      rescue Net::HTTPFatalError => e
+        raise SearchFailure, "Search exception #{e.class}: #{e}"
       end
 
-      def normal_search(type, query, keys, rows=1000)
-        escaped_query = escape_query(query)
-        Chef::Log.info("Normal Search query: #{escaped_query}, keys: #{keys.inspect}")
-        unless valid_search_keys?(keys)
-          raise InvalidSearchKeys, "Invalid search keys: #{keys.inspect}"
-        end
+      # Assert that the normal (no partial) search response is correct.
+      #
+      # @param resp [Array] normal search result.
+      # @return void
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @api private
+      def assert_normal_search_response(resp)
+        return if resp.is_a?(Array)
+        fail SearchFatalError,
+             "Wrong response received from Normal Search: #{resp.inspect}"
+      end
 
-        begin
-          resp = self.query.search(type, escaped_query, nil, 0, rows)[0]
-        rescue Net::HTTPServerException => e
-          if e.response.kind_of?(Net::HTTPResponse) and e.response.code == '404' # Not Found
-            return []
-          else
-            raise SearchFailure, "Partial Search exception #{e.class.name}: #{e.to_s}"
+      # Parses a normal (no partial) search response row.
+      #
+      # @param row [Array] the normal search result row.
+      # @param attr_ary [Array<String>] key path as Array.
+      # @return [Hash] A hash with the response row, for example:
+      #   `[ 'ipaddress' => '192.168.1.1' }`
+      # @api private
+      def parse_normal_search_row_attribute(row, attr_ary)
+        attr_ary.reduce(row) do |r, attr|
+          if r.respond_to?(attr)
+            r.send(attr)
+          elsif r.respond_to?(:key?)
+            r[attr.to_s] if r.key?(attr.to_s)
           end
-        rescue Net::HTTPFatalError => e
-          raise SearchFailure, "Normal Search exception #{e.class.name}: #{e.to_s}"
-        end
-        unless resp.kind_of?(Array)
-          raise SearchFatalError, "Wrong response received from Normal Search: #{resp.inspect}"
         end
-        # TODO too complex, refactorize
+      end
+
+      # Parses a normal (no partial) full search search response.
+      #
+      # @param resp [Array] normal search result.
+      # @param keys [Hash] search keys structure. For example:
+      #   `{ipaddress: %w(ipaddress), mysql_version: %w(mysql version) }`.
+      # @return [Array<Hash>] An array with the response, for example:
+      #   `[{ 'ipaddress' => '192.168.1.1' }]`
+      # @api private
+      def parse_normal_search_response(resp, keys)
         resp.map do |row|
           Hash[keys.map do |key_name, attr_ary|
-            value = attr_ary.reduce(row) do |r, attr|
-              if r.respond_to?(attr.to_sym)
-                r.send(attr.to_sym)
-              elsif r.respond_to?(:has_key?)
-                if r.has_key?(attr.to_s)
-                  r[attr.to_s]
-                end
-              end
-            end
-            [ key_name, value ]
+            value = parse_normal_search_row_attribute(row, attr_ary)
+            [key_name, value]
           end]
         end
       end
 
-      def partial_search(type, query, keys, rows=1000)
-        escaped_query = "search/#{escape(type)}?q=#{escape_query(query)}&start=0&rows=#{rows}"
-        Chef::Log.info("Partial Search query: #{escaped_query}, keys: #{keys.inspect}")
-        unless valid_search_keys?(keys)
-          raise InvalidSearchKeys, "Invalid search keys: #{keys.inspect}"
-        end
+      # Does a normal (no partial) search in the Chef Server.
+      #
+      # @param type [Symbol] search index to use. See [Chef Search Indexes]
+      #   (http://docs.getchef.com/chef_search.html#search-indexes).
+      # @param query [String, Array<String>] search query. For example:
+      #   `%w(admin:true)`. Results will be *OR*-ed when multiple string queries
+      #   are provided.
+      # @param keys [Hash] search keys structure. For example:
+      #   `{ipaddress: %w(ipaddress), mysql_version: %w(mysql version) }`.
+      # @param rows [Fixnum, String] maximum number of rows to return.
+      # @return [Array<Hash>] An array with the response, for example:
+      #   `[{ 'ipaddress' => '192.168.1.1' }]`
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      def normal_search(type, query, keys, rows = 1000)
+        escaped_query = escape_query(query)
+        Chef::Log.info(
+          "Normal Search query: #{escaped_query}, keys: #{keys.inspect}"
+        )
+        assert_search_keys(keys)
 
-        rest = Chef::REST.new(Chef::Config[:chef_server_url])
-        begin
-          resp = rest.post_rest(escaped_query, keys)
-        rescue Net::HTTPServerException => e
-          if e.response.kind_of?(Net::HTTPResponse) and e.response.code == '404' # Not Found
-            return []
-          else
-            raise SearchFailure, "Partial Search exception #{e.class.name}: #{e.to_s}"
-          end
-        rescue Net::HTTPFatalError => e
-          raise SearchFailure, "Partial Search exception #{e.class.name}: #{e.to_s}"
-        end
-        unless resp.kind_of?(Hash) and resp.has_key?('rows') and resp['rows'].kind_of?(Array)
-          raise SearchFatalError, "Wrong response received from Partial Search: #{resp.inspect}"
-        end
+        resp = self.query.search(type, escaped_query, nil, 0, rows)[0]
+        assert_normal_search_response(resp)
+        parse_normal_search_response(resp, keys)
+      end
+
+      # Assert that the partial search response is correct.
+      #
+      # @param resp [Hash] partial search result. For example:
+      #   `{ 'rows' => [ 'data' => { 'ipaddress' => '192.168.1.1' } }] }`.
+      # @return void
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @api private
+      def assert_partial_search_response(resp)
+        return if resp.is_a?(Hash) && resp.key?('rows') &&
+                  resp['rows'].is_a?(Array)
+        fail SearchFatalError,
+             "Wrong response received from Partial Search: #{resp.inspect}"
+      end
+
+      # Parses a partial full search search response.
+      #
+      # @param resp [Hash] partial search result. For example:
+      #   `{ 'rows' => [ 'data' => { 'ipaddress' => '192.168.1.1' } }] }`.
+      # @return [Array<Hash>] An array with the response, for example:
+      #   `[{ 'ipaddress' => '192.168.1.1' }]`
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @api private
+      def parse_partial_search_response(resp)
         resp['rows'].map do |row|
-          if row.kind_of?(Hash) and row['data'].kind_of?(Hash)
+          if row.is_a?(Hash) && row['data'].is_a?(Hash)
             row['data']
           else
-            raise SearchFatalError, "Wrong row format received from Partial Search: #{row.inspect}"
+            fail SearchFatalError,
+                 "Wrong row format received from Partial Search: #{row.inspect}"
           end
         end.compact
       end
 
+      # Does a partial search in the Chef Server.
+      #
+      # @param type [Symbol] search index to use. See [Chef Search Indexes]
+      #   (http://docs.getchef.com/chef_search.html#search-indexes).
+      # @param query [String, Array<String>] search query. For example:
+      #   `%w(admin:true)`. Results will be *OR*-ed when multiple string queries
+      #   are provided.
+      # @param keys [Hash] search keys structure. For example:
+      #   `{ipaddress: %w(ipaddress), mysql_version: %w(mysql version) }`.
+      # @param rows [Fixnum, String] maximum number of rows to return.
+      # @return [Array<Hash>] An array with the response, for example:
+      #   `[{ 'ipaddress' => '192.168.1.1' }]`
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      def partial_search(type, query, keys, rows = 1000)
+        escaped_query =
+          "search/#{escape(type)}?q=#{escape_query(query)}&start=0&rows=#{rows}"
+        Chef::Log.info(
+          "Partial Search query: #{escaped_query}, keys: #{keys.inspect}"
+        )
+        assert_search_keys(keys)
+
+        rest = Chef::REST.new(Chef::Config[:chef_server_url])
+        resp = rest.post_rest(escaped_query, keys)
+        assert_partial_search_response(resp)
+        parse_partial_search_response(resp)
+      end
     end
   end
 end

data/lib/chef/encrypted_attribute/version.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@onddo.com>)
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
@@ -18,6 +19,7 @@
 
 class Chef
   class EncryptedAttribute
-    VERSION = '0.3.0'
+    # `chef-encrypted-attributes` gem version.
+    VERSION = '0.4.0'
   end
 end

data/lib/chef/encrypted_attributes.rb

@@ -0,0 +1,20 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@onddo.com>)
+# Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
+# License:: Apache License, Version 2.0
+#
+# 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 'chef/encrypted_attribute'

data/lib/chef/knife/core/config.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@onddo.com>)
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
@@ -16,4 +17,6 @@
 # limitations under the License.
 #
 
-Chef::Config[:knife][:encrypted_attributes] = Mash.new unless Chef::Config[:knife][:encrypted_attributes].kind_of?(Hash)
+unless Chef::Config[:knife][:encrypted_attributes].is_a?(Hash)
+  Chef::Config[:knife][:encrypted_attributes] = Mash.new
+end

data/lib/chef/knife/core/encrypted_attribute_base.rb

@@ -0,0 +1,179 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@onddo.com>)
+# Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
+# License:: Apache License, Version 2.0
+#
+# 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 'chef/knife'
+
+class Chef
+  class Knife
+    module Core
+      # knife encrypted attribute commands base class.
+      #
+      # All encrypted attribute knife commands inherit some common method from
+      # this class.
+      class EncryptedAttributeBase < Knife
+        # Prints a fatal error and exits without success.
+        #
+        # @param msg [String] message to print.
+        # @return void
+        def die(msg)
+          ui.fatal(msg)
+          exit 1
+        end
+
+        # Asserts that the option value is not `nil`.
+        #
+        # Shows usage and exists if `nil`.
+        #
+        # @param option [Mixed] value to check.
+        # @param msg [String] error message to print in case value is `nil`.
+        # @return void
+        def option_assert(option, msg)
+          return unless option.nil?
+          show_usage
+          die(msg)
+        end
+
+        # Asserts that an encrypted attribute exists.
+        #
+        # Exits with error if the attribute does no exist.
+        #
+        # @param node_name [String] Chef node name.
+        # @param attr_ary [Array<String>] node attribute path as Array.
+        # @return void
+        # @raise [ArgumentError] if the attribute path format is wrong.
+        def assert_attribute_exists(node_name, attr_ary)
+          return if Chef::EncryptedAttribute.exist_on_node?(node_name, attr_ary)
+          die('Encrypted attribute not found')
+        end
+
+        # Asserts that an encrypted attribute does not exist.
+        #
+        # Exits with error if the attribute exist.
+        #
+        # @param node_name [String] Chef node name.
+        # @param attr_ary [Array<String>] node attribute path as Array.
+        # @return void
+        # @raise [ArgumentError] if the attribute path format is wrong.
+        def assert_attribute_does_not_exist(node_name, attr_ary)
+          return unless
+            Chef::EncryptedAttribute.exist_on_node?(node_name, attr_ary)
+          die('Encrypted attribute already exists')
+        end
+
+        # Parses knife arguments.
+        #
+        # Exits with error if the arguments are wrong.
+        #
+        # @return void
+        # @see #assert_valid_args
+        def parse_args
+          @node_name = @name_args[0]
+          @attr_path = @name_args[1]
+          option_assert(@node_name, 'You must specify a node name')
+          option_assert(
+            @attr_path, 'You must specify an encrypted attribute name'
+          )
+          @attr_ary = attribute_path_to_ary(@attr_path)
+
+          assert_valid_args
+        end
+
+        # Asserts that the arguments are valid.
+        #
+        # Exits with error if arguments are wrong.
+        #
+        # @return void
+        def assert_valid_args
+          # nop
+        end
+
+        # Asserts that I can decrypt an encrypted attribute from a remote node.
+        #
+        # Exists with an error if the attribute cannot be decrypted.
+        #
+        # @param node_name [String] Chef node name.
+        # @param attr_ary [Array<String>] node attribute path as Array.
+        # @return void
+        # @raise [ArgumentError] if the attribute path format is wrong.
+        # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+        #   format is wrong.
+        # @raise [UnsupportedEncryptedAttributeFormat] if encrypted attribute
+        #   format is not supported or unknown.
+        # @raise [SearchFailure] if there is a Chef search error.
+        # @raise [SearchFatalError] if the Chef search response is wrong.
+        # @raise [InvalidSearchKeys] if search keys structure is wrong.
+        def assert_attribute_readable(node_name, attr_ary)
+          # try to read the attribute
+          Chef::EncryptedAttribute.load_from_node(node_name, attr_ary)
+        end
+
+        # Parses the escape character from an array path string.
+        #
+        # @param str [String] the full string to parse.
+        # @param i [String] string position that contains the escape character.
+        # @param delim [String] delimiter used for string notation.
+        # @return [String] the character unscaped.
+        # see #attribute_path_to_ary
+        # @api private
+        def attribute_path_to_ary_read_escape(str, i, delim)
+          if str[i + 1] == delim
+            str[i + 1]
+          else
+            str[i] + (str[i + 1].nil? ? '' : str[i + 1])
+          end
+        end
+
+        # Parses an array path in or escaped string notation.
+        #
+        # Literal delimiter values can be escaped using the escape character.
+        #
+        # Uses dot notation by default, using `'.'` as delimiter and `'\'` as
+        # escape character.
+        #
+        # For example, for `'encrypted.attr\.ibute'` will return
+        # `%w(encrypted attr.ibute)`.
+        #
+        # @param str [String] array path in dot notation.
+        # @param delim [String] delimiter used for string notation.
+        # @param escape [String] escape character to use.
+        # @return [Array<String>] attribute path as array.
+        def attribute_path_to_ary(str, delim = '.', escape = '\\')
+          # cool, but doesn't work for some edge cases
+          # return str.scan(/(?:[^.\\]|\\.)+/).map {|x| x.gsub('\\.', '.') }
+          result = []
+          current = ''
+          i = 0
+          until str[i].nil?
+            if str[i] == escape
+              current << attribute_path_to_ary_read_escape(str, i, delim)
+              i += 1 # skip the next char
+            elsif str[i] == delim
+              result << current
+              current = ''
+            else
+              current << str[i]
+            end
+            i += 1
+          end
+          result << current
+        end
+      end
+    end
+  end
+end