Merge pull request #7382 from chef/lcg/deprecate-shell-out-methods

deprecate old shell_out APIs

7 files changed, 234 insertions, 50 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 85181821c6..167e04fa3a 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,5 +1,31 @@
 This file holds "in progress" release notes for the current release under development and is intended for consumption by the Chef Documentation team. Please see <https://docs.chef.io/release_notes.html> for the official Chef release notes.
 
+## Simplification of `shell_out` APIs
+
+The following methods are deprecated:
+
+- `shell_out_with_systems_locale`
+- `shell_out_with_timeout`
+- `shell_out_compact`
+- `shell_out_compact_timeout`
+- `shell_out_with_systems_locale!`
+- `shell_out_with_timeout!`
+- `shell_out_compact!`
+- `shell_out_compact_timeout!`
+
+The functionality of `shell_out_with_systems_locale` has been implemented using the `default_env: false`
+option that removes the PATH and locale mangling that has been the default behavior of `shell_out`.
+
+The functionality of `shell_out_compact` has been folded into `shell_out`.  The `shell_out` API when called
+with varargs has its arguments flatted, compacted and coerced to strings.  This style of calling is encouraged
+over using strings and building up commands using `join(" ")` since it avoids shell interpolation and edge
+conditions in the construction of spaces between arguments.  The varargs form is still not supported on
+Windows.
+
+The functionality of `shell_out*timeout` has also been folded into `shell_out`.  Users writing Custom Resources
+should be explicit for Chef-14:  `shell_out!("whatever", timeout: new_resource.timeout)` which will become
+automatic in Chef-15.
+
 ## Silencing deprecation warnings
 
 While deprecation warnings have been great for the Chef community to ensure
diff --git a/lib/chef/deprecated.rb b/lib/chef/deprecated.rb
index d9a8df7b83..74c600bef9 100644
--- a/lib/chef/deprecated.rb
+++ b/lib/chef/deprecated.rb
@@ -1,5 +1,5 @@
 #--
-# Copyright:: Copyright 2016-2017, Chef Software Inc.
+# Copyright:: Copyright 2016-2018, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -217,6 +217,10 @@ class Chef
       end
     end
 
+    class ShellOut < Base
+      target 26
+    end
+
     class Generic < Base
       def url
         "https://docs.chef.io/chef_deprecations_client.html"
diff --git a/lib/chef/mixin/shell_out.rb b/lib/chef/mixin/shell_out.rb
index 2c67d34630..f38c6e262d 100644
--- a/lib/chef/mixin/shell_out.rb
+++ b/lib/chef/mixin/shell_out.rb
@@ -46,7 +46,8 @@ class Chef
       # a thousand unit tests.
       #
 
-      def shell_out_compact(*args, **options) # FIXME: deprecate
+      def shell_out_compact(*args, **options)
+        Chef.deprecated(:shell_out, "shell_out_compact should be replaced by shell_out")
         if options.empty?
           shell_out(*args)
         else
@@ -54,7 +55,8 @@ class Chef
         end
       end
 
-      def shell_out_compact!(*args, **options) # FIXME: deprecate
+      def shell_out_compact!(*args, **options)
+        Chef.deprecated(:shell_out, "shell_out_compact! should be replaced by shell_out!")
         if options.empty?
           shell_out!(*args)
         else
@@ -62,23 +64,26 @@ class Chef
         end
       end
 
-      def shell_out_compact_timeout(*args, **options) # FIXME: deprecate
+      def shell_out_compact_timeout(*args, **options)
+        Chef.deprecated(:shell_out, "shell_out_compact_timeout should be replaced by shell_out")
         if options.empty?
-          shell_out(*args)
+          shell_out(*args, argument_that_will_go_away_in_chef_15_so_do_not_use_it: true)
         else
-          shell_out(*args, **options)
+          shell_out(*args, argument_that_will_go_away_in_chef_15_so_do_not_use_it: true, **options)
         end
       end
 
-      def shell_out_compact_timeout!(*args, **options) # FIXME: deprecate
+      def shell_out_compact_timeout!(*args, **options)
+        Chef.deprecated(:shell_out, "shell_out_compact_timeout! should be replaced by shell_out!")
         if options.empty?
-          shell_out!(*args)
+          shell_out!(*args, argument_that_will_go_away_in_chef_15_so_do_not_use_it: true)
         else
-          shell_out!(*args, **options)
+          shell_out!(*args, argument_that_will_go_away_in_chef_15_so_do_not_use_it: true, **options)
         end
       end
 
-      def shell_out_with_systems_locale(*args, **options) # FIXME: deprecate
+      def shell_out_with_systems_locale(*args, **options)
+        Chef.deprecated(:shell_out, "shell_out_with_systems_locale should be replaced by shell_out with the default_env option set to false")
         if options.empty?
           shell_out(*args, default_env: false)
         else
@@ -86,7 +91,8 @@ class Chef
         end
       end
 
-      def shell_out_with_systems_locale!(*args, **options) # FIXME: deprecate
+      def shell_out_with_systems_locale!(*args, **options)
+        Chef.deprecated(:shell_out, "shell_out_with_systems_locale! should be replaced by shell_out! with the default_env option set to false")
         if options.empty?
           shell_out!(*args, default_env: false)
         else
@@ -94,9 +100,8 @@ class Chef
         end
       end
 
-      def a_to_s(*args) # FIXME: deprecate
-        # can't quite deprecate this yet
-        #Chef.deprecated(:package_misc, "a_to_s is deprecated use shell_out_compact or shell_out_compact_timeout instead")
+      def a_to_s(*args)
+        Chef.deprecated(:shell_out, "a_to_s is deprecated use shell_out with splat-args")
         args.flatten.reject { |i| i.nil? || i == "" }.map(&:to_s).join(" ")
       end
 
@@ -125,13 +130,21 @@ class Chef
       # module method to not pollute namespaces, but that means we need self injected as an arg
       # @api private
       def self.maybe_add_timeout(obj, options)
+        options = options.dup
+        force = options.delete(:argument_that_will_go_away_in_chef_15_so_do_not_use_it) # remove in Chef-15
+        # historically resources have not properly declared defaults on their timeouts, so a default default of 900s was enforced here
+        default_val = 900
+        if !force
+          return options if options.key?(:timeout) # leave this line in Chef-15, delete the rest of the conditional
+        else
+          default_val = options[:timeout] if options.key?(:timeout) # delete in Chef-15
+        end
         # note that we can't define an empty Chef::Resource::LWRPBase because that breaks descendants tracker, so we'd have to instead require the file here, which would pull in half
         # of chef, so instead convert to using strings.  once descendants tracker is gone, we can just declare the empty classes instead and use `is_a?` against the symbols.
         # (be nice if ruby supported strings in `is_a?` for looser coupling).
-        if obj.class.ancestors.map(&:to_s).include?("Chef::Provider") && !obj.class.ancestors.map(&:to_s).include?("Chef::Resource::LWRPBase") && obj.new_resource.respond_to?(:timeout) && !options.key?(:timeout)
-          options = options.dup
-          # historically resources have not properly declared defaults on their timeouts, so a default default of 900s was enforced here
-          options[:timeout] = obj.new_resource.timeout ? obj.new_resource.timeout.to_f : 900
+        # FIXME: just use `if obj.respond_to?(:new_resource) && obj.new_resource.respond_to?(:timeout) && !options.key?(:timeout)` in Chef 15
+        if obj.respond_to?(:new_resource) && ( force || ( obj.class.ancestors.map(&:name).include?("Chef::Provider") && !obj.class.ancestors.map(&:name).include?("Chef::Resource::LWRPBase") && !obj.class.ancestors.map(&:name).include?("Chef::Resource::ActionClass") && obj.new_resource.respond_to?(:timeout) && !options.key?(:timeout) ) )
+          options[:timeout] = obj.new_resource.timeout ? obj.new_resource.timeout.to_f : default_val
         end
         options
       end
diff --git a/lib/chef/provider/package.rb b/lib/chef/provider/package.rb
index ddd2fa5dd6..0af4f87d7f 100644
--- a/lib/chef/provider/package.rb
+++ b/lib/chef/provider/package.rb
@@ -668,27 +668,12 @@ class Chef
         end
       end
 
-      def shell_out_with_timeout(*command_args) # FIXME: deprecated
-        shell_out(*add_timeout_option(command_args))
+      def shell_out_with_timeout(*command_args)
+        shell_out_compact_timeout(*command_args)
       end
 
-      def shell_out_with_timeout!(*command_args) # FIXME: deprecated
-        shell_out!(*add_timeout_option(command_args))
-      end
-
-      def add_timeout_option(command_args)
-        # this is deprecated but its not quite done yet
-        #Chef.deprecated(:package_misc, "shell_out_with_timeout and add_timeout_option are deprecated methods, use shell_out instead")
-        args = command_args.dup
-        if args.last.is_a?(Hash)
-          options = args.pop.dup
-          options[:timeout] = new_resource.timeout if new_resource.timeout
-          options[:timeout] = 900 unless options.key?(:timeout)
-          args << options
-        else
-          args << { timeout: new_resource.timeout ? new_resource.timeout : 900 }
-        end
-        args
+      def shell_out_with_timeout!(*command_args)
+        shell_out_compact_timeout!(*command_args)
       end
     end
   end
diff --git a/spec/functional/mixin/shell_out_spec.rb b/spec/functional/mixin/shell_out_spec.rb
index f0d1eb7cbc..48a34762c6 100644
--- a/spec/functional/mixin/shell_out_spec.rb
+++ b/spec/functional/mixin/shell_out_spec.rb
@@ -21,6 +21,10 @@ describe Chef::Mixin::ShellOut do
   include Chef::Mixin::ShellOut
 
   describe "shell_out_with_systems_locale" do
+    before do
+      Chef::Config[:treat_deprecation_warnings_as_errors] = false
+    end
+
     describe "when environment['LC_ALL'] is not set" do
       it "should use the default shell_out setting" do
         cmd = if windows?
diff --git a/spec/unit/mixin/shell_out_spec.rb b/spec/unit/mixin/shell_out_spec.rb
index df35960cc9..2fef051b29 100644
--- a/spec/unit/mixin/shell_out_spec.rb
+++ b/spec/unit/mixin/shell_out_spec.rb
@@ -53,6 +53,9 @@ describe Chef::Mixin::ShellOut do
 
     [ :shell_out, :shell_out_compact, :shell_out_compact_timeout, :shell_out!, :shell_out_compact!, :shell_out_compact_timeout! ].each do |method|
       describe "##{method}" do
+        before do
+          Chef::Config[:treat_deprecation_warnings_as_errors] = false
+        end
 
         describe "when the last argument is a Hash" do
           describe "and environment is an option" do
@@ -157,24 +160,27 @@ describe Chef::Mixin::ShellOut do
             end
           end
         end
-      end
 
-      describe "when the last argument is not a Hash" do
-        it "should set environment language settings to the configured internal locale" do
-          expect(Chef::Mixin::ShellOut).to receive(:shell_out_command).with(cmd, {
-            :environment => {
-              "LC_ALL"   => Chef::Config[:internal_locale],
-              "LANG"     => Chef::Config[:internal_locale],
-              "LANGUAGE" => Chef::Config[:internal_locale],
-              env_path   => sanitized_path,
-            },
-          }).and_return(retobj)
-          shell_out_obj.send(method, cmd)
+        describe "when the last argument is not a Hash" do
+          it "should set environment language settings to the configured internal locale" do
+            expect(Chef::Mixin::ShellOut).to receive(:shell_out_command).with(cmd, {
+              :environment => {
+                "LC_ALL"   => Chef::Config[:internal_locale],
+                "LANG"     => Chef::Config[:internal_locale],
+                "LANGUAGE" => Chef::Config[:internal_locale],
+                env_path   => sanitized_path,
+              },
+            }).and_return(retobj)
+            shell_out_obj.send(method, cmd)
+          end
         end
       end
     end
 
     describe "#shell_out_with_systems_locale" do
+      before do
+        Chef::Config[:treat_deprecation_warnings_as_errors] = false
+      end
 
       describe "when the last argument is a Hash" do
         describe "and environment is an option" do
@@ -294,5 +300,151 @@ describe Chef::Mixin::ShellOut do
       end
     end
 
+    describe "deprecations" do
+      [ :shell_out_with_systems_locale, :shell_out_compact, :shell_out_compact_timeout, :shell_out_with_systems_locale!, :shell_out_compact!, :shell_out_compact_timeout! ].each do |method|
+        it "should not respond to #{method} in Chef-15", chef: ">= 15" do
+          expect(shell_out_obj.respond_to?(method)).to be false
+        end
+      end
+
+      it "removed shell_out_with_timeout from Chef::Provider::Package", chef: ">= 15" do
+        expect(Chef::Provider::Package.instance_methods + Chef::Provider::Package.private_instance_methods).not_to include(:shell_out_with_timeout)
+      end
+
+      it "removed shell_out_with_timeout! from Chef::Provider::Package", chef: ">= 15" do
+        expect(Chef::Provider::Package.instance_methods + Chef::Provider::Package.private_instance_methods).not_to include(:shell_out_with_timeout!)
+      end
+    end
+
+    describe "Custom Resource timeouts" do
+      class CustomResource < Chef::Resource
+        provides :whatever
+
+        property :timeout, Numeric
+
+        action :install do
+        end
+      end
+
+      let(:new_resource) { CustomResource.new("foo") }
+      let(:provider) { new_resource.provider_for_action(:install) }
+
+      describe "on Chef-14", chef: "< 15" do
+        it "doesn't add timeout for shell_out" do
+          expect(provider).to receive(:shell_out_compacted).with("foo")
+          provider.shell_out("foo")
+        end
+        it "doesn't add timeout for shell_out!" do
+          expect(provider).to receive(:shell_out_compacted!).with("foo")
+          provider.shell_out!("foo")
+        end
+      end
+
+      describe "on Chef-15", chef: ">= 15" do
+        [ :shell_out, :shell_out! ].each do |method|
+          stubbed_method = (method == :shell_out) ? :shell_out_compacted : :shell_out_compacted!
+          it "#{method} defaults to 900 seconds" do
+            expect(provider).to receive(stubbed_method).with("foo", timeout: 900)
+            provider.send(method, "foo")
+          end
+          it "#{method} overrides the default timeout with its options" do
+            expect(provider).to receive(stubbed_method).with("foo", timeout: 1)
+            provider.send(method, "foo", timeout: 1)
+          end
+          it "#{method} overrides the new_resource.timeout with the timeout option" do
+            new_resource.timeout(99)
+            expect(provider).to receive(stubbed_method).with("foo", timeout: 1)
+            provider.send(method, "foo", timeout: 1)
+          end
+          it "#{method} defaults to 900 seconds and preserves options" do
+            expect(provider).to receive(stubbed_method).with("foo", env: nil, timeout: 900)
+            provider.send(method, "foo", env: nil)
+          end
+          it "#{method} overrides the default timeout with its options and preserves options" do
+            expect(provider).to receive(stubbed_method).with("foo", timeout: 1, env: nil)
+            provider.send(method, "foo", timeout: 1, env: nil)
+          end
+          it "#{method} overrides the new_resource.timeout with the timeout option and preseves options" do
+            new_resource.timeout(99)
+            expect(provider).to receive(stubbed_method).with("foo", timeout: 1, env: nil)
+            provider.send(method, "foo", timeout: 1, env: nil)
+          end
+        end
+      end
+    end
+
+    describe "timeouts" do
+      let(:new_resource) { Chef::Resource::Package.new("foo") }
+      let(:provider) { new_resource.provider_for_action(:install) }
+
+      [ :shell_out, :shell_out! ].each do |method|
+        stubbed_method = (method == :shell_out) ? :shell_out_compacted : :shell_out_compacted!
+        it "#{method} defaults to 900 seconds" do
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 900)
+          provider.send(method, "foo")
+        end
+        it "#{method} overrides the default timeout with its options" do
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 1)
+          provider.send(method, "foo", timeout: 1)
+        end
+        it "#{method} overrides the new_resource.timeout with the timeout option" do
+          new_resource.timeout(99)
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 1)
+          provider.send(method, "foo", timeout: 1)
+        end
+        it "#{method} defaults to 900 seconds and preserves options" do
+          expect(provider).to receive(stubbed_method).with("foo", env: nil, timeout: 900)
+          provider.send(method, "foo", env: nil)
+        end
+        it "#{method} overrides the default timeout with its options and preserves options" do
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 1, env: nil)
+          provider.send(method, "foo", timeout: 1, env: nil)
+        end
+        it "#{method} overrides the new_resource.timeout with the timeout option and preseves options" do
+          new_resource.timeout(99)
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 1, env: nil)
+          provider.send(method, "foo", timeout: 1, env: nil)
+        end
+      end
+    end
+
+    describe "deprecated timeouts" do # Chef 15: delete me
+      let(:new_resource) { Chef::Resource::Package.new("foo") }
+      let(:provider) { new_resource.provider_for_action(:install) }
+
+      before(:each) do
+        Chef::Config[:treat_deprecation_warnings_as_errors] = false
+      end
+
+      [ :shell_out_compact_timeout, :shell_out_compact_timeout! ].each do |method|
+        stubbed_method = (method == :shell_out_compact_timeout) ? :shell_out_compacted : :shell_out_compacted!
+        it "#{method} defaults to 900 seconds" do
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 900)
+          provider.send(method, "foo")
+        end
+        it "#{method} overrides the default timeout with its options" do
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 1)
+          provider.send(method, "foo", timeout: 1)
+        end
+        it "#{method} overrides the new_resource.timeout with the timeout option" do
+          new_resource.timeout(99)
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 99)
+          provider.send(method, "foo", timeout: 1)
+        end
+        it "#{method} defaults to 900 seconds and preserves options" do
+          expect(provider).to receive(stubbed_method).with("foo", env: nil, timeout: 900)
+          provider.send(method, "foo", env: nil)
+        end
+        it "#{method} overrides the default timeout with its options and preserves options" do
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 1, env: nil)
+          provider.send(method, "foo", timeout: 1, env: nil)
+        end
+        it "#{method} overrides the new_resource.timeout with the timeout option and preseves options" do
+          new_resource.timeout(99)
+          expect(provider).to receive(stubbed_method).with("foo", timeout: 99, env: nil)
+          provider.send(method, "foo", timeout: 1, env: nil)
+        end
+      end
+    end
   end
 end
diff --git a/spec/unit/provider/package_spec.rb b/spec/unit/provider/package_spec.rb
index 2eb7cf63e1..904e339e47 100644
--- a/spec/unit/provider/package_spec.rb
+++ b/spec/unit/provider/package_spec.rb
@@ -942,7 +942,7 @@ describe "Chef::Provider::Package - Multi" do
     end
 
     [ :shell_out_with_timeout, :shell_out_with_timeout! ].each do |method|
-      stubbed_method = method == :shell_out_with_timeout! ? :shell_out! : :shell_out
+      stubbed_method = method == :shell_out_with_timeout! ? :shell_out_compacted! : :shell_out_compacted
       [ %w{command arg1 arg2}, "command arg1 arg2" ].each do |command|
         it "#{method} defaults to 900 seconds" do
           expect(provider).to receive(stubbed_method).with(*command, timeout: 900)