Initial merge

Signed-off-by: Lamont Granquist <lamont@scriptkiddie.org>

8 files changed, 674 insertions, 0 deletions

diff --git a/lib/chef/dsl/rest_resource.rb b/lib/chef/dsl/rest_resource.rb
new file mode 100644
index 0000000000..d324d85ed4
--- /dev/null
+++ b/lib/chef/dsl/rest_resource.rb
@@ -0,0 +1,63 @@
+class Chef
+  module DSL
+    module RestResource
+      module ClassMethods
+        def rest_property_map(rest_property_map = "NOT_PASSED")
+          if rest_property_map != "NOT_PASSED"
+            rest_property_map = rest_property_map.to_h { |k| [k.to_sym, k] } if rest_property_map.is_a? Array
+
+            @rest_property_map = rest_property_map
+          end
+          @rest_property_map
+        end
+
+        # URL to collection
+        def rest_api_collection(rest_api_collection = "NOT_PASSED")
+          @rest_api_collection = rest_api_collection if rest_api_collection != "NOT_PASSED"
+          @rest_api_collection
+        end
+
+        # RFC6570-Templated URL to document
+        def rest_api_document(rest_api_document = "NOT_PASSED", first_element_only: false)
+          if rest_api_document != "NOT_PASSED"
+            @rest_api_document = rest_api_document
+            @rest_api_document_first_element_only = first_element_only
+          end
+          @rest_api_document
+        end
+
+        # Explicit REST document identity mapping
+        def rest_identity_map(rest_identity_map = "NOT_PASSED")
+          @rest_identity_map = rest_identity_map if rest_identity_map != "NOT_PASSED"
+          @rest_identity_map
+        end
+
+        # Mark up properties for POST only, not PATCH/PUT
+        def rest_post_only_properties(rest_post_only_properties = "NOT_PASSED")
+          if rest_post_only_properties != "NOT_PASSED"
+            @rest_post_only_properties = Array(rest_post_only_properties).map(&:to_sym)
+          end
+          @rest_post_only_properties || []
+        end
+
+        def rest_api_document_first_element_only(rest_api_document_first_element_only = "NOT_PASSED")
+          if rest_api_document_first_element_only != "NOT_PASSED"
+            @rest_api_document_first_element_only = rest_api_document_first_element_only
+          end
+          @rest_api_document_first_element_only
+        end
+
+        # "What if this was built into Chef Infra Core?" demo only
+        def resource_type(resource_type = "NOT_PASSED"); end
+
+        def included(other)
+          other.extend ClassMethods
+        end
+      end
+
+      def self.included(other)
+        other.extend ClassMethods
+      end
+    end
+  end
+end
diff --git a/lib/chef/exceptions.rb b/lib/chef/exceptions.rb
index ffdbdcbaba..c60b7fc888 100644
--- a/lib/chef/exceptions.rb
+++ b/lib/chef/exceptions.rb
@@ -561,5 +561,13 @@ class Chef
         super "before subscription from #{notification.resource} resource cannot be setup to #{notification.notifying_resource} resource, which has already fired while in unified mode"
       end
     end
+
+    class RestError < RuntimeError; end
+
+    class RestTargetError < RestError; end
+
+    class RestTimeout < RestError; end
+
+    class RestOperationFailed < RestError; end
   end
 end
diff --git a/lib/chef/provider/rest_resource.rb b/lib/chef/provider/rest_resource.rb
new file mode 100644
index 0000000000..72500d6965
--- /dev/null
+++ b/lib/chef/provider/rest_resource.rb
@@ -0,0 +1,354 @@
+require_relative "../provider"
+
+class Chef
+  class Provider
+    class RestResource < Chef::Provider
+      attr_writer :current_resource
+
+      def load_current_resource
+        @current_resource = new_resource.class.new(new_resource.name)
+
+        required_properties.each do |name|
+          requested = new_resource.send(name)
+          current_resource.send(name, requested)
+        end
+
+        return @current_resource if rest_get_all.empty?
+
+        resource_data = rest_get
+        return @current_resource if resource_data.nil? || resource_data.empty?
+
+        @resource_exists = true
+
+        # Map JSON contents to defined properties
+        current_resource.class.rest_property_map.each do |property, match_instruction|
+          property_value = json_to_property(match_instruction, property, resource_data)
+
+          current_resource.send(property, property_value) unless property_value.nil?
+        end
+
+        current_resource
+      end
+
+      def action_configure
+        converge_if_changed do
+          data = {}
+
+          new_resource.class.rest_property_map.each do |property, match_instruction|
+            # Skip "creation-only" properties on modifications
+            next if resource_exists? && new_resource.class.rest_post_only_properties.include?(property)
+
+            deep_merge! data, property_to_json(property, match_instruction)
+          end
+
+          deep_compact!(data)
+
+          @resource_exists ? rest_patch(data) : rest_post(data)
+        end
+      end
+
+      def action_delete
+        if resource_exists?
+          rest_delete
+        else
+          logger.debug format("REST resource %<name>s of type %<type>s does not exist. Skipping.",
+                              type: new_resource.name, name: id_property)
+        end
+      end
+
+      protected
+
+      def resource_exists?
+        @resource_exists
+      end
+
+      def required_properties
+        current_resource.class.properties.select { |_, v| v.required? }.except(:name).keys
+      end
+
+      # Return changed value or nil for delta current->new
+      def changed_value(property)
+        new_value = new_resource.send(property)
+        return new_value if current_resource.nil?
+
+        current_value = current_resource.send(property)
+
+        return current_value if required_properties.include? property
+
+        new_value == current_value ? nil : new_value
+      end
+
+      def id_property
+        current_resource.class.identity_attr
+      end
+
+      # Map properties to their current values
+      def property_map
+        map = {}
+
+        current_resource.class.state_properties.each do |property|
+          name = property.options[:name]
+
+          map[name] = current_resource.send(name)
+        end
+
+        map[id_property] = current_resource.send(id_property)
+
+        map
+      end
+
+      # Map part of a JSON (Hash) to resource property via JMESPath or user-supplied function
+      def json_to_property(match_instruction, property, resource_data)
+        case match_instruction
+        when String
+          JMESPath.search(match_instruction, resource_data)
+        when Symbol
+          function = "#{property}_from_json".to_sym
+          raise "#{new_resource.name} missing #{function} method" unless self.class.protected_method_defined?(function)
+
+          send(function, resource_data) || {}
+        else
+          raise TypeError, "Did not expect match type #{match_instruction.class}"
+        end
+      end
+
+      # Map resource contents into a JSON (Hash) via JMESPath-like syntax or user-supplied function
+      def property_to_json(property, match_instruction)
+        case match_instruction
+        when String
+          bury(match_instruction, changed_value(property))
+        when Symbol
+          function = "#{property}_to_json".to_sym
+          raise "#{new_resource.name} missing #{function} method" unless self.class.protected_method_defined?(function)
+
+          value = new_resource.send(property)
+          changed_value(property).nil? ? {} : send(function, value)
+        else
+          raise TypeError, "Did not expect match type #{match_instruction.class}"
+        end
+      end
+
+      def rest_url_collection
+        current_resource.class.rest_api_collection
+      end
+
+      # Resource document URL after RFC 6570 template evaluation via properties substitution
+      def rest_url_document
+        template = ::Addressable::Template.new(current_resource.class.rest_api_document)
+        template.expand(property_map).to_s
+      end
+
+      # Convenience method for conditional requires
+      def conditionally_require_on_setting(property, dependent_properties)
+        dependent_properties = Array(dependent_properties)
+
+        requirements.assert(:configure) do |a|
+          a.assertion do
+            # Needs to be set and truthy to require dependent properties
+            if new_resource.send(property)
+              dependent_properties.all? { |dep_prop| new_resource.property_is_set?(dep_prop) }
+            else
+              true
+            end
+          end
+
+          message = format("Setting property :%<property>s requires properties :%<properties>s to be set as well on resource %<resource_name>s",
+                           property: property,
+                           properties: dependent_properties.join(", :"),
+                           resource_name: current_resource.to_s)
+
+          a.failure_message message
+        end
+      end
+
+      # Generic REST helpers
+
+      def rest_get_all
+        response = api_connection.get(rest_url_collection)
+
+        rest_postprocess(response)
+      rescue RestClient::Exception => e
+        rest_errorhandler(e)
+      end
+
+      def rest_get
+        response = api_connection.get(rest_url_document)
+
+        response = rest_postprocess(response)
+
+        first_only = current_resource.class.rest_api_document_first_element_only
+        first_only && response.is_a?(Array) ? response.first : response
+      rescue RestClient::Exception => e
+        rest_errorhandler(e)
+      end
+
+      def rest_post(data)
+        data.merge! rest_identity_values
+
+        response = api_connection.post(rest_url_collection, data: data)
+
+        rest_postprocess(response)
+      rescue RestClient::Exception => e
+        rest_errorhandler(e)
+      end
+
+      def rest_put(data)
+        data.merge! rest_identity_values
+
+        response = api_connection.put(rest_url_collection, data: data)
+
+        rest_postprocess(response)
+      rescue RestClient::Exception => e
+        rest_errorhandler(e)
+      end
+
+      def rest_patch(data)
+        response = api_connection.patch(rest_url_document, data: data)
+
+        rest_postprocess(response)
+      rescue RestClient::Exception => e
+        rest_errorhandler(e)
+      end
+
+      def rest_delete
+        response = api_connection.delete(rest_url_document)
+
+        rest_postprocess(response)
+      rescue RestClient::Exception => e
+        rest_errorhandler(e)
+      end
+
+      # REST parameter mapping
+
+      # Return number of parameters needed to identify a resource (pre- and post-creation)
+      def rest_arity
+        rest_identity_map.keys.count
+      end
+
+      # Return mapping of template placeholders to property value of identity parameters
+      def rest_identity_values
+        data = {}
+
+        rest_identity_map.each do |rfc_template, property|
+          property_value = new_resource.send(property)
+          data.merge! bury(rfc_template, property_value)
+        end
+
+        data
+      end
+
+      def rest_identity_map
+        rest_identity_explicit || rest_identity_implicit
+      end
+
+      # Accept direct mapping like { "svm.name" => :name } for specifying the x-ary identity of a resource
+      def rest_identity_explicit
+        current_resource.class.rest_identity_map
+      end
+
+      # Parse document URL for RFC 6570 templates and map them to resource properties.
+      #
+      # Examples:
+      #   Query based: "/api/protocols/san/igroups?name={name}&svm.name={svm}": { "name" => :name, "svm.name" => :svm }
+      #   Path based:  "/api/v1/{address}": { "address" => :address }
+      #
+      def rest_identity_implicit
+        template_url = current_resource.class.rest_api_document
+
+        rfc_template = ::Addressable::Template.new(template_url)
+        rfc_template_vars = rfc_template.variables
+
+        # Shortcut for 0-ary resources
+        return {} if rfc_template_vars.empty?
+
+        if query_based_selection?
+          uri_query = URI.parse(template_url).query
+
+          if CGI.parse(uri_query).values.any?(&:empty?)
+            raise "Need explicit identity mapping, as URL does not contain query parameters for all templates"
+          end
+
+          path_variables = CGI.parse(uri_query).keys
+        elsif path_based_selection?
+          path_variables = rfc_template_vars
+        else
+          # There is also
+          raise "Unknown type of resource selection. Document URL does not seem to be path- or query-based?"
+        end
+
+        identity_map = {}
+        path_variables.each_with_index do |v, i|
+          next if rfc_template_vars[i].nil? # Not mapped to property, assume metaparameter
+
+          identity_map[v] = rfc_template_vars[i].to_sym
+        end
+
+        identity_map
+      end
+
+      def query_based_selection?
+        template_url = current_resource.class.rest_api_document
+
+        # Will throw exception on presence of RFC 6570 templates
+        URI.parse(template_url)
+        true
+      rescue URI::InvalidURIError => _e
+        false
+      end
+
+      def path_based_selection?
+        !query_based_selection?
+      end
+
+      def api_connection
+        Chef.run_context.transport.connection
+      end
+
+      # Override this for postprocessing device-specifics (paging, data conversion)
+      def rest_postprocess(response)
+        response
+      end
+
+      # Override this for error handling of device-specifics (readable error messages)
+      def rest_errorhandler(error_obj)
+        error_obj
+      end
+
+      # Remove all empty keys (recusively) from Hash.
+      # @see https://stackoverflow.com/questions/56457020/#answer-56458673
+      def deep_compact!(hsh)
+        raise TypeError unless hsh.is_a? Hash
+
+        hsh.each do |_, v|
+          deep_compact!(v) if v.is_a? Hash
+        end.reject! { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+      end
+
+      # Deep merge two hashes
+      # @see https://stackoverflow.com/questions/41109599#answer-41109737
+      def deep_merge!(hsh1, hsh2)
+        raise TypeError unless hsh1.is_a?(Hash) && hsh2.is_a?(Hash)
+
+        hsh1.merge!(hsh2) { |_, v1, v2| deep_merge!(v1, v2) }
+      end
+
+      # Create nested hashes from JMESPath syntax.
+      def bury(path, value)
+        raise TypeError unless path.is_a?(String)
+
+        arr = path.split(".")
+        ret = {}
+
+        if arr.count == 1
+          ret[arr.first] = value
+
+          ret
+        else
+          partial_path = arr[0..-2].join(".")
+
+          bury(partial_path, bury(arr.last, value))
+        end
+      end
+    end
+  end
+end
diff --git a/lib/chef/providers.rb b/lib/chef/providers.rb
index e713383190..09a1380760 100644
--- a/lib/chef/providers.rb
+++ b/lib/chef/providers.rb
@@ -38,6 +38,7 @@ require_relative "provider/package"
 require_relative "provider/powershell_script"
 require_relative "provider/remote_directory"
 require_relative "provider/remote_file"
+require_relative "provider/rest_resource"
 require_relative "provider/route"
 require_relative "provider/ruby_block"
 require_relative "provider/script"
diff --git a/lib/chef/resource/rest_resource.rb b/lib/chef/resource/rest_resource.rb
new file mode 100644
index 0000000000..1993d12ce8
--- /dev/null
+++ b/lib/chef/resource/rest_resource.rb
@@ -0,0 +1,22 @@
+require_relative "../resource"
+require_relative "../dsl/rest_resource"
+
+class Chef
+  class Resource
+    class RestResource < Chef::Resource
+      unified_mode true
+
+      # This is an abstract resource meant to be subclassed; thus no 'provides'
+
+      skip_docs true
+      preview_resource true
+
+      description "Generic superclass for all REST API resources"
+
+      default_action :configure
+      allowed_actions :configure, :delete
+
+      include Chef::DSL::RestResource
+    end
+  end
+end
diff --git a/lib/chef/resources.rb b/lib/chef/resources.rb
index ac5ec5d8e0..cc18b60c9f 100644
--- a/lib/chef/resources.rb
+++ b/lib/chef/resources.rb
@@ -112,6 +112,7 @@ require_relative "resource/reboot"
 require_relative "resource/registry_key"
 require_relative "resource/remote_directory"
 require_relative "resource/remote_file"
+require_relative "resource/rest_resource"
 require_relative "resource/rhsm_errata_level"
 require_relative "resource/rhsm_errata"
 require_relative "resource/rhsm_register"
diff --git a/spec/unit/provider/rest_resource_spec.rb b/spec/unit/provider/rest_resource_spec.rb
new file mode 100644
index 0000000000..7f43f70c35
--- /dev/null
+++ b/spec/unit/provider/rest_resource_spec.rb
@@ -0,0 +1,190 @@
+require "spec_helper"
+
+class RestResourceByQuery < Chef::Resource::RestResource
+  property :address, String, required: true
+  property :prefix, Integer, required: true
+  property :gateway, String
+
+  rest_api_collection "/api/v1/addresses"
+  rest_api_document   "/api/v1/address/?ip={address}"
+end
+
+class RestResourceByPath < RestResourceByQuery
+  rest_api_document   "/api/v1/address/{address}"
+end
+
+describe "rest_resource using query-based addressing" do
+  before(:each) do
+    @cookbook_collection = Chef::CookbookCollection.new([])
+    @node = Chef::Node.new
+    @node.name "node1"
+    @events = Chef::EventDispatch::Dispatcher.new
+    @run_context = Chef::RunContext.new(@node, @cookbook_collection, @events)
+
+    @resource = RestResourceByQuery.new("set_address", @run_context)
+    @resource.address = "192.0.2.1"
+    @resource.prefix = 24
+
+    @provider = Chef::Provider::RestResource.new(@resource, @run_context)
+    @provider.current_resource = @resource
+  end
+
+  it "should include :configure action" do
+    expect(@provider).to respond_to(:action_configure)
+  end
+
+  it "should include :delete action" do
+    expect(@provider).to respond_to(:action_delete)
+  end
+
+  it "should include :nothing action" do
+    expect(@provider).to respond_to(:action_nothing)
+  end
+
+  describe "#rest_postprocess" do
+    before do
+      @provider.singleton_class.send(:public, :rest_postprocess)
+    end
+    it "should have a default rest_postprocess implementation" do
+      expect(@provider).to respond_to(:rest_postprocess)
+    end
+
+    it "should have a non-mutating rest_postprocess implementation" do
+      response = "{ data: nil }"
+
+      expect(@provider.rest_postprocess(response.dup)).to eq(response)
+    end
+  end
+
+  describe "#rest_errorhandler" do
+    before do
+      @provider.singleton_class.send(:public, :rest_errorhandler)
+    end
+
+    it "should have a default rest_errorhandler implementation" do
+      expect(@provider).to respond_to(:rest_errorhandler)
+    end
+
+    it "should have a non-mutating rest_errorhandler implementation" do
+      error_obj = StandardError.new
+
+      expect(@provider.rest_errorhandler(error_obj.dup)).to eq(error_obj)
+    end
+  end
+
+  describe "#required_properties" do
+    before do
+      @provider.singleton_class.send(:public, :required_properties)
+    end
+
+    it "should include required properties only" do
+      expect(@provider.required_properties).to contain_exactly(:address, :prefix)
+    end
+  end
+
+  describe "#property_map" do
+    before do
+      @provider.singleton_class.send(:public, :property_map)
+    end
+
+    it "should map resource properties to values properly" do
+      expect(@provider.property_map).to eq({
+                                             address: "192.0.2.1",
+                                             prefix: 24,
+                                             gateway: nil,
+                                             name: "set_address",
+                                           })
+    end
+  end
+
+  describe "#rest_url_collection" do
+    before do
+      @provider.singleton_class.send(:public, :rest_url_collection)
+    end
+
+    it "should return collection URLs properly" do
+      expect(@provider.rest_url_collection).to eq("/api/v1/addresses")
+    end
+  end
+
+  describe "#rest_url_document" do
+    before do
+      @provider.singleton_class.send(:public, :rest_url_document)
+    end
+
+    it "should apply URI templates to document URLs using query syntax properly" do
+      expect(@provider.rest_url_document).to eq("/api/v1/address/?ip=192.0.2.1")
+    end
+  end
+
+  # TODO: Test with path-style URLs
+  describe "#rest_identity_implicit" do
+    before do
+      @provider.singleton_class.send(:public, :rest_identity_implicit)
+    end
+
+    it "should return implicit identity properties properly" do
+      expect(@provider.rest_identity_implicit).to eq({ "ip" => :address })
+    end
+  end
+
+  describe "#rest_identity_values" do
+    before do
+      @provider.singleton_class.send(:public, :rest_identity_values)
+    end
+
+    it "should return implicit identity properties and values properly" do
+      expect(@provider.rest_identity_values).to eq({ "ip" => "192.0.2.1" })
+    end
+  end
+
+  # TODO: changed_value
+  # TODO: load_current_value
+end
+
+describe "rest_resource using path-based addressing" do
+  before(:each) do
+    @cookbook_collection = Chef::CookbookCollection.new([])
+    @node = Chef::Node.new
+    @node.name "node1"
+    @events = Chef::EventDispatch::Dispatcher.new
+    @run_context = Chef::RunContext.new(@node, @cookbook_collection, @events)
+
+    @resource = RestResourceByPath.new("set_address", @run_context)
+    @resource.address = "192.0.2.1"
+    @resource.prefix = 24
+
+    @provider = Chef::Provider::RestResource.new(@resource, @run_context)
+    @provider.current_resource = @resource
+  end
+
+  describe "#rest_url_document" do
+    before do
+      @provider.singleton_class.send(:public, :rest_url_document)
+    end
+
+    it "should apply URI templates to document URLs using path syntax properly" do
+      expect(@provider.rest_url_document).to eq("/api/v1/address/192.0.2.1")
+    end
+  end
+
+  describe "#rest_identity_implicit" do
+    before do
+      @provider.singleton_class.send(:public, :rest_identity_implicit)
+    end
+
+    it "should return implicit identity properties properly" do
+      expect(@provider.rest_identity_implicit).to eq({ "address" => :address })
+    end
+  end
+
+  describe "#rest_identity_values" do
+    before do
+      @provider.singleton_class.send(:public, :rest_identity_values)
+    end
+
+    it "should return implicit identity properties and values properly" do
+      expect(@provider.rest_identity_values).to eq({ "address" => "192.0.2.1" })
+    end
+  end
+end
diff --git a/spec/unit/resource/rest_resource_spec.rb b/spec/unit/resource/rest_resource_spec.rb
new file mode 100644
index 0000000000..f21b43f357
--- /dev/null
+++ b/spec/unit/resource/rest_resource_spec.rb
@@ -0,0 +1,35 @@
+
+require "spec_helper"
+
+describe Chef::Resource::RestResource do
+  let(:resource_instance_name) { "some_name" }
+  let(:resource_name) { :rest_resource }
+
+  let(:resource) do
+    run_context = Chef::RunContext.new(Chef::Node.new, nil, nil)
+
+    Chef::Resource::RestResource.new(resource_instance_name, run_context)
+  end
+
+  it "is a subclass of Chef::Resource" do
+    expect(resource).to be_a_kind_of(Chef::Resource)
+  end
+
+  it "sets the default action as :configure" do
+    expect(resource.action).to eql([:configure])
+  end
+
+  it "supports :configure action" do
+    expect { resource.action :configure }.not_to raise_error
+  end
+
+  it "supports :delete action" do
+    expect { resource.action :delete }.not_to raise_error
+  end
+
+  it "should mixin RestResourceDSL" do
+    expect(resource.class.included_modules).to include(Chef::DSL::RestResource)
+  end
+
+  # TODO: how to test for target_mode support?
+end