Add remove_resource function

Author: alexjfisher

REFERENCE.md

@@ -30,6 +30,7 @@ Thus making it directly usable with the values from facter.
 * [`extlib::read_url`](#extlib--read_url): Fetch a string from a URL (should only be used with 'small' remote files).  This function should only be used with trusted/internal sources. 
 * [`extlib::remote_pql_query`](#extlib--remote_pql_query): Perform a PuppetDB query on an arbitrary PuppetDB server.
 * [`extlib::remove_blank_lines`](#extlib--remove_blank_lines): Remove blank lines from a string
+* [`extlib::remove_resource`](#extlib--remove_resource): Removes a Resource or an Array of Resources from the catalog.
 * [`extlib::resources_deep_merge`](#extlib--resources_deep_merge): Deeply merge a "defaults" hash into a "resources" hash like the ones expected by `create_resources()`.
 * [`extlib::sort_by_version`](#extlib--sort_by_version): A function that sorts an array of version numbers.
 * [`extlib::to_ini`](#extlib--to_ini): This converts a puppet hash to an INI string.
@@ -1071,6 +1072,57 @@ Data type: `String[1]`
 
 The content to remove blank lines from
 
+### <a name="extlib--remove_resource"></a>`extlib::remove_resource`
+
+Type: Ruby 4.x API
+
+This function provides a mechanism for removing a resource from the catalog
+that has already been added. You should only consider using this function as
+a last resort. If you are able to not add the resource in the first place, do
+that!  If a third party module that you have no control over and don't want
+to fork, unconditionally adds a resource you don't want, then _maybe_ this
+function can help you out.
+
+It can only remove resources that have already been added at the time the
+function is called.  ie. It is Puppet manifest evaluation order dependent on
+whether it removes what you want it to!
+
+#### `extlib::remove_resource(Type[Resource] $resource, Optional[Boolean] $soft_fail)`
+
+The extlib::remove_resource function.
+
+Returns: `Undef` Returns nothing.
+
+##### `resource`
+
+Data type: `Type[Resource]`
+
+The Resource to remove
+
+##### `soft_fail`
+
+Data type: `Optional[Boolean]`
+
+When set to true, only a warning will be omitted if the resource can't be found. By default an error will be raised.
+
+#### `extlib::remove_resource(Array[Type[Resource]] $resources, Optional[Boolean] $soft_fail)`
+
+The extlib::remove_resource function.
+
+Returns: `Undef` Returns nothing.
+
+##### `resources`
+
+Data type: `Array[Type[Resource]]`
+
+The Resources to remove
+
+##### `soft_fail`
+
+Data type: `Optional[Boolean]`
+
+When set to true, only a warning will be omitted if the resource can't be found. By default an error will be raised.
+
 ### <a name="extlib--resources_deep_merge"></a>`extlib::resources_deep_merge`
 
 Type: Ruby 4.x API

lib/puppet/functions/extlib/remove_resource.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# @summary Removes a Resource or an Array of Resources from the catalog.
+#
+# This function provides a mechanism for removing a resource from the catalog
+# that has already been added. You should only consider using this function as
+# a last resort. If you are able to not add the resource in the first place, do
+# that!  If a third party module that you have no control over and don't want
+# to fork, unconditionally adds a resource you don't want, then _maybe_ this
+# function can help you out.
+#
+# It can only remove resources that have already been added at the time the
+# function is called.  ie. It is Puppet manifest evaluation order dependent on
+# whether it removes what you want it to!
+Puppet::Functions.create_function(:'extlib::remove_resource', Puppet::Functions::InternalFunction) do
+  # @param resource The Resource to remove
+  # @param soft_fail When set to true, only a warning will be omitted if the resource can't be found. By default an error will be raised.
+  # @return [Undef] Returns nothing.
+  dispatch :remove_resource do
+    scope_param
+    param 'Type[Resource]', :resource
+    optional_param 'Boolean', :soft_fail
+    return_type 'Undef'
+  end
+
+  # @param resources The Resources to remove
+  # @param soft_fail When set to true, only a warning will be omitted if the resource can't be found. By default an error will be raised.
+  # @return [Undef] Returns nothing.
+  dispatch :remove_resources do
+    scope_param
+    param 'Array[Type[Resource]]', :resources
+    optional_param 'Boolean', :soft_fail
+    return_type 'Undef'
+  end
+
+  def remove_resources(scope, resources, soft_fail = nil)
+    resources.each { |resource| remove_resource(scope, resource, soft_fail) }
+
+    nil
+  end
+
+  def remove_resource(scope, resource, soft_fail = nil)
+    catalog_resource = scope.catalog.resource(resource.type_name, resource.title)
+
+    if catalog_resource
+      # To remove the resource, we reverse the actions from compiler.add_resource
+      # See https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/parser/compiler.rb#L77-L80
+      scope.catalog.remove_resource(catalog_resource)
+      scope.compiler.resources.delete(catalog_resource)
+    else
+      msg = "`remove_resource` couldn't remove resource #{resource.type_name}['#{resource.title}'] from the catalog as it wasn't found when `remove_resource` was called."
+
+      raise Puppet::ParseError, msg unless soft_fail
+
+      Puppet.warning msg
+    end
+
+    nil
+  end
+end

spec/functions/extlib/remove_resource_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'extlib::remove_resource' do
+  let(:user_foo) { Puppet::Pops::Types::PResourceType.new('User', 'foo') }
+  let(:user_baz) { Puppet::Pops::Types::PResourceType.new('User', 'baz') }
+
+  it { is_expected.not_to be_nil }
+
+  context "when resource doesn't exist" do
+    it { is_expected.to run.with_params(user_foo).and_raise_error(Puppet::ParseError, %r{`remove_resource` couldn't remove resource User\['foo'\] from the catalog}) }
+
+    context 'when soft_fail is true' do
+      it { is_expected.to run.with_params(user_foo, true) }
+
+      it 'logs a warning' do
+        msg = "`remove_resource` couldn't remove resource User['foo'] from the catalog as it wasn't found when `remove_resource` was called."
+        allow(Puppet).to receive(:warning)
+        subject.execute(user_foo, true)
+        expect(Puppet).to have_received(:warning).with(msg)
+      end
+    end
+  end
+
+  context 'when resource is in catalog' do
+    let(:pre_condition) do
+      <<~MANIFEST
+        user { ['foo', 'bar', 'baz']: ensure => present }
+      MANIFEST
+    end
+
+    it 'removes the resource' do
+      expect(subject).to run.with_params(user_foo)
+      expect(catalogue.resource('User[foo]')).to be_nil
+      expect(catalogue.resource('User[bar]')).not_to be_nil
+      expect(catalogue.resource('User[baz]')).not_to be_nil
+    end
+
+    context 'when called with Array of resources' do
+      it 'removes only those resources' do
+        expect(subject).to run.with_params([user_foo, user_baz])
+        expect(catalogue.resource('User[foo]')).to be_nil
+        expect(catalogue.resource('User[bar]')).not_to be_nil
+        expect(catalogue.resource('User[baz]')).to be_nil
+      end
+    end
+  end
+end