config_param options to specify deprecated/obsoleted parameters

lib/fluent/config/configure_proxy.rb

@@ -216,15 +216,15 @@ def parameter_configuration(name, type = nil, **kwargs, &block)
         opts.merge!(kwargs)
 
         if block && type
-          raise ArgumentError, "#{self.name}: both of block and type cannot be specified"
+          raise ArgumentError, "#{name}: both of block and type cannot be specified"
         end
 
         begin
           type = :string if type.nil?
           block ||= @type_lookup.call(type)
         rescue ConfigError
           # override error message
-          raise ArgumentError, "#{self.name}: unknown config_argument type `#{type}'"
+          raise ArgumentError, "#{name}: unknown config_argument type `#{type}'"
         end
 
         if opts.has_key?(:default)
@@ -235,6 +235,10 @@ def parameter_configuration(name, type = nil, **kwargs, &block)
           config_set_desc(name, opts[:desc])
         end
 
+        if opts[:deprecated] && opts[:obsoleted]
+          raise ArgumentError, "#{name}: both of deprecated and obsoleted cannot be specified at once"
+        end
+
         [name, block, opts]
       end
 
@@ -296,7 +300,7 @@ def desc(description)
 
       def config_section(name, **kwargs, &block)
         unless block_given?
-          raise ArgumentError, "#{self.name}: config_section requires block parameter"
+          raise ArgumentError, "#{name}: config_section requires block parameter"
         end
         name = name.to_sym
 
@@ -305,10 +309,10 @@ def config_section(name, **kwargs, &block)
 
         if sub_proxy.init?
           if sub_proxy.argument && !sub_proxy.defaults.has_key?(sub_proxy.argument.first)
-            raise ArgumentError, "#{self.name}: init is specified, but default value of argument is missing"
+            raise ArgumentError, "#{name}: init is specified, but default value of argument is missing"
           end
           if sub_proxy.params.keys.any?{|param_name| !sub_proxy.defaults.has_key?(param_name)}
-            raise ArgumentError, "#{self.name}: init is specified, but there're parameters without default values"
+            raise ArgumentError, "#{name}: init is specified, but there're parameters without default values"
           end
         end
 

lib/fluent/config/error.rb

@@ -20,4 +20,7 @@ class ConfigError < StandardError
 
   class ConfigParseError < ConfigError
   end
+
+  class ObsoletedParameterError < ConfigError
+  end
 end

lib/fluent/config/section.rb

@@ -126,6 +126,7 @@ def self.generate(proxy, conf, logger, plugin_class, stack = [])
             logger.error "config error in:\n#{conf}" if logger # logger should exist, but somethimes it's nil (e.g, in tests)
             raise ConfigError, "'<#{proxy.name} ARG>' section requires argument" + section_stack
           end
+          # argument should NOT be deprecated... (argument always has a value: '')
         end
 
         proxy.params.each_pair do |name, defval|
@@ -138,6 +139,20 @@ def self.generate(proxy, conf, logger, plugin_class, stack = [])
                     conf[opts[:alias].to_s]
                   end
             section_params[varname] = self.instance_exec(val, opts, name, &block)
+
+            # Source of definitions of deprecated/obsoleted:
+            # https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features
+            #
+            # Deprecated: These deprecated features can still be used, but should be used with caution
+            #             because they are expected to be removed entirely sometime in the future.
+            # Obsoleted: These obsolete features have been entirely removed from JavaScript and can no longer be used.
+            if opts[:deprecated]
+              logger.warn "'#{name}' paramenter isn't recommended to use now."
+            end
+            if opts[:obsoleted]
+              logger.error "config error in:\n#{conf}" if logger
+              raise ObsoletedParameterError, "'#{name}' parameter is already removed. Don't use it." + section_stack
+            end
           end
           unless section_params.has_key?(varname)
             logger.error "config error in:\n#{conf}" if logger

lib/fluent/plugin/out_forward.rb

@@ -89,23 +89,12 @@ def initialize
 
     attr_reader :nodes
 
-    # backward compatibility
-    config_param :port, :integer, default: LISTEN_PORT
-    config_param :host, :string, default: nil
+    config_param :port, :integer, default: LISTEN_PORT, obsoleted: true
+    config_param :host, :string, default: nil, obsoleted: true
 
     def configure(conf)
       super
 
-      # backward compatibility
-      if host = conf['host']
-        log.warn "'host' option in forward output is obsoleted. Use '<server> host xxx </server>' instead."
-        port = conf['port']
-        port = port ? port.to_i : LISTEN_PORT
-        element = conf.add_element('server')
-        element['host'] = host
-        element['port'] = port.to_s
-      end
-
       recover_sample_size = @recover_wait / @heartbeat_interval
 
       if @dns_round_robin

test/config/test_configurable.rb

@@ -342,6 +342,12 @@ class BufferChild
       config_param :size_of_something, :size, default: 128
     end
   end
+  class UnRecommended
+    include Fluent::Configurable
+    attr_accessor :log
+    config_param :key1, :string, default: 'deprecated', deprecated: true
+    config_param :key2, :string, default: 'obsoleted', obsoleted: true
+  end
 end
 
 module Fluent::Config
@@ -1102,5 +1108,39 @@ def assert_secret_param(key, value)
         end
       end
     end
+    # class UnRecommended
+    #   include Fluent::Configurable
+    #   config_param :key1, :string, default: 'deprecated', deprecated: true
+    #   config_param :key2, :string, default: 'obsoleted', obsoleted: true
+    # end
+    sub_test_case 'deprecated/obsoleted parameters' do
+      test 'both cannot be specified at once' do
+        assert_raise ArgumentError.new("param1: both of deprecated and obsoleted cannot be specified at once") do
+          class Buggy1
+            include Fluent::Configurable
+            config_param :param1, :string, default: '', deprecated: true, obsoleted: true
+          end
+        end
+      end
+
+      test 'warned if deprecated parameter is configured' do
+        obj = ConfigurableSpec::UnRecommended.new
+        obj.log = Fluent::Test::TestLogger.new
+        obj.configure(config_element('ROOT', '', {'key1' => 'yay'}, []))
+
+        assert_equal 'yay', obj.key1
+        first_log = obj.log.logs.first
+        assert{ first_log && first_log.include?("[warn]") && first_log.include?("'key1' paramenter isn't recommended to use now.") }
+      end
+
+      test 'error raised if obsoleted parameter is configured' do
+        obj = ConfigurableSpec::UnRecommended.new
+        obj.log = Fluent::Test::TestLogger.new
+
+        assert_raise Fluent::ObsoletedParameterError.new("'key2' parameter is already removed. Don't use it.") do
+          obj.configure(config_element('ROOT', '', {'key2' => 'yay'}, []))
+        end
+      end
+    end
   end
 end