add http.* deprecation log (#16538)

- refactor deprecated alias to support obsoleted version
- add deprecation log for http.* config

logstash-core/lib/logstash/environment.rb

@@ -72,10 +72,10 @@ module Environment
            Setting::Boolean.new("enable-local-plugin-development", false),
             Setting::String.new("log.format", "plain", true, ["json", "plain"]),
            Setting::Boolean.new("log.format.json.fix_duplicate_message_fields", false),
-           Setting::Boolean.new("api.enabled", true).with_deprecated_alias("http.enabled"),
-            Setting::String.new("api.http.host", "127.0.0.1").with_deprecated_alias("http.host"),
-         Setting::PortRange.new("api.http.port", 9600..9700).with_deprecated_alias("http.port"),
-            Setting::String.new("api.environment", "production").with_deprecated_alias("http.environment"),
+           Setting::Boolean.new("api.enabled", true).with_deprecated_alias("http.enabled", "9"),
+            Setting::String.new("api.http.host", "127.0.0.1").with_deprecated_alias("http.host", "9"),
+         Setting::PortRange.new("api.http.port", 9600..9700).with_deprecated_alias("http.port", "9"),
+            Setting::String.new("api.environment", "production").with_deprecated_alias("http.environment", "9"),
             Setting::String.new("api.auth.type", "none", true, %w(none basic)),
             Setting::String.new("api.auth.basic.username", nil, false).nullable,
           Setting::Password.new("api.auth.basic.password", nil, false).nullable,

logstash-core/lib/logstash/runner.rb

@@ -253,15 +253,18 @@ class LogStash::Runner < Clamp::StrictCommand
 
   deprecated_option ["--http.enabled"], :flag,
     I18n.t("logstash.runner.flag.http_enabled"),
-    :new_flag => "api.enabled", :passthrough => true # use settings to disambiguate
+    :new_flag => "api.enabled", :passthrough => true, # use settings to disambiguate
+    :obsoleted_version => "9"
 
   deprecated_option ["--http.host"], "HTTP_HOST",
     I18n.t("logstash.runner.flag.http_host"),
-    :new_flag => "api.http.host", :passthrough => true # use settings to disambiguate
+    :new_flag => "api.http.host", :passthrough => true, # use settings to disambiguate
+    :obsoleted_version => "9"
 
   deprecated_option ["--http.port"], "HTTP_PORT",
     I18n.t("logstash.runner.flag.http_port"),
-    :new_flag => "api.http.port", :passthrough => true # use settings to disambiguate
+    :new_flag => "api.http.port", :passthrough => true, # use settings to disambiguate
+    :obsoleted_version => "9"
 
   # We configure the registry and load any plugin that can register hooks
   # with logstash, this needs to be done before any operation.

logstash-core/lib/logstash/settings.rb

@@ -334,8 +334,8 @@ def validate_value
       validate(value)
     end
 
-    def with_deprecated_alias(deprecated_alias_name)
-      SettingWithDeprecatedAlias.wrap(self, deprecated_alias_name)
+    def with_deprecated_alias(deprecated_alias_name, obsoleted_version=nil)
+      SettingWithDeprecatedAlias.wrap(self, deprecated_alias_name, obsoleted_version)
     end
 
     ##
@@ -847,10 +847,11 @@ def validate_value
     class DeprecatedAlias < SimpleDelegator
       # include LogStash::Util::Loggable
       alias_method :wrapped, :__getobj__
-      attr_reader :canonical_proxy
+      attr_reader :canonical_proxy, :obsoleted_version
 
-      def initialize(canonical_proxy, alias_name)
+      def initialize(canonical_proxy, alias_name, obsoleted_version)
         @canonical_proxy = canonical_proxy
+        @obsoleted_version = obsoleted_version
 
         clone = @canonical_proxy.canonical_setting.clone
         clone.update_wrapper(clone.wrapped_setting.deprecate(alias_name))
@@ -882,9 +883,15 @@ def observe_post_process
       private
 
       def do_log_setter_deprecation
-        deprecation_logger.deprecated(I18n.t("logstash.settings.deprecation.set",
-                                             :deprecated_alias => name,
-                                             :canonical_name => canonical_proxy.name))
+        deprecation_logger.deprecated(
+          I18n.t("logstash.settings.deprecation.set",
+                 :deprecated_alias => name,
+                 :canonical_name => canonical_proxy.name,
+                 :obsoleted_sentences =>
+                   @obsoleted_version.nil? ?
+                     I18n.t("logstash.settings.deprecation.obsoleted_future") :
+                     I18n.t("logstash.settings.deprecation.obsoleted_version", :obsoleted_version => @obsoleted_version))
+        )
       end
     end
 
@@ -901,21 +908,22 @@ class SettingWithDeprecatedAlias < SimpleDelegator
       # including the canonical setting and a deprecated alias.
       # @param canonical_setting [Setting]: the setting to wrap
       # @param deprecated_alias_name [String]: the name for the deprecated alias
+      # @param obsoleted_version [String]: the version of Logstash that deprecated alias will be removed
       #
       # @return [SettingWithDeprecatedAlias,DeprecatedSetting]
-      def self.wrap(canonical_setting, deprecated_alias_name)
-        setting_proxy = new(canonical_setting, deprecated_alias_name)
+      def self.wrap(canonical_setting, deprecated_alias_name, obsoleted_version=nil)
+        setting_proxy = new(canonical_setting, deprecated_alias_name, obsoleted_version)
 
         [setting_proxy, setting_proxy.deprecated_alias]
       end
 
       attr_reader :deprecated_alias
       alias_method :canonical_setting, :__getobj__
 
-      def initialize(canonical_setting, deprecated_alias_name)
+      def initialize(canonical_setting, deprecated_alias_name, obsoleted_version)
         super(canonical_setting)
 
-        @deprecated_alias = DeprecatedAlias.new(self, deprecated_alias_name)
+        @deprecated_alias = DeprecatedAlias.new(self, deprecated_alias_name, obsoleted_version)
       end
 
       def set(value)

logstash-core/locales/en.yml

@@ -451,7 +451,11 @@ en:
       deprecation:
         set: >-
           The setting `%{deprecated_alias}` is a deprecated alias for `%{canonical_name}`
-          and will be removed in a future release of Logstash. Please use %{canonical_name} instead
+          %{obsoleted_sentences} Please use `%{canonical_name}` instead
+        obsoleted_future: >-
+          and will be removed in a future release of Logstash.
+        obsoleted_version: >-
+          and will be removed in version %{obsoleted_version}.
         queried: >-
           The value of setting `%{canonical_name}` has been queried by its deprecated alias `%{deprecated_alias}`.
           Code should be updated to query `%{canonical_name}` instead

logstash-core/spec/logstash/settings/setting_with_deprecated_alias_spec.rb

@@ -105,6 +105,38 @@
         expect { settings.get_setting(canonical_setting_name).deprecated_alias.validate_value }.to_not raise_error
       end
     end
+
+    context 'obsoleted version' do
+      before(:each) do
+        settings.register(subject.with_deprecated_alias(deprecated_name, "9"))
+      end
+
+      describe "ruby string setting" do
+        let(:new_value) { "ironman" }
+        let(:old_value) { "iron man" }
+        let(:canonical_name) { "iron.setting" }
+        let(:deprecated_name) { "iron.oxide.setting" }
+        subject { LogStash::Setting::String.new(canonical_name, old_value, true) }
+
+        it 'logs a deprecation warning with target remove version' do
+          settings.set(deprecated_name, new_value)
+          expect(LogStash::Settings.deprecation_logger).to have_received(:deprecated)
+                                                             .with(a_string_including(deprecated_name))
+                                                             .with(a_string_including("version 9"))
+        end
+      end
+      describe "java boolean setting" do
+        let(:new_value) { false }
+        let(:old_value) { true }
+        let(:canonical_name) { "bool.setting" }
+        let(:deprecated_name) { "boo.setting" }
+        subject { LogStash::Setting::Boolean.new(canonical_name, old_value, true) }
+
+        it 'does not raise error' do
+          expect { settings.set(deprecated_name, new_value) }.to_not raise_error
+        end
+      end
+    end
   end
 
   context "when only the canonical setting is set" do

logstash-core/src/main/java/org/logstash/settings/BaseSetting.java

@@ -193,7 +193,10 @@ public void format(List<String> output) {
     }
 
     public List<Setting<T>> withDeprecatedAlias(String deprecatedAlias) {
-        return SettingWithDeprecatedAlias.wrap(this, deprecatedAlias);
+        return withDeprecatedAlias(deprecatedAlias, null);
+    }
+    public List<Setting<T>> withDeprecatedAlias(String deprecatedAlias, String obsoletedVersion) {
+        return SettingWithDeprecatedAlias.wrap(this, deprecatedAlias, obsoletedVersion);
     }
 
     public Setting<T> nullable() {

logstash-core/src/main/java/org/logstash/settings/DeprecatedAlias.java

@@ -33,19 +33,32 @@ public final class DeprecatedAlias<T> extends SettingDelegator<T> {
 
     private static final DeprecationLogger DEPRECATION_LOGGER = new DefaultDeprecationLogger(LOGGER);
 
-    private SettingWithDeprecatedAlias<T> canonicalProxy;
+    private final SettingWithDeprecatedAlias<T> canonicalProxy;
 
-    DeprecatedAlias(SettingWithDeprecatedAlias<T> canonicalProxy, String aliasName) {
+    private final String obsoletedVersion;
+
+    DeprecatedAlias(SettingWithDeprecatedAlias<T> canonicalProxy, String aliasName, String obsoletedVersion) {
         super(canonicalProxy.getCanonicalSetting().deprecate(aliasName));
         this.canonicalProxy = canonicalProxy;
+        this.obsoletedVersion = obsoletedVersion;
     }
 
     // Because loggers are configure after the Settings declaration, this method is intended for lazy-logging
     // check https://github.com/elastic/logstash/pull/16339
     public void observePostProcess() {
         if (isSet()) {
-            DEPRECATION_LOGGER.deprecated("The setting `{}` is a deprecated alias for `{}` and will be removed in a " +
-                    "future release of Logstash. Please use `{}` instead", getName(), canonicalProxy.getName(), canonicalProxy.getName());
+            StringBuilder sb = new StringBuilder();
+            sb.append("The setting `").append(getName()).append("` is a deprecated alias for `").append(canonicalProxy.getName()).append("`");
+
+            if (this.obsoletedVersion != null && !this.obsoletedVersion.isEmpty()) {
+                sb.append(" and will be removed in version ").append(this.obsoletedVersion).append(".");
+            } else {
+                sb.append(" and will be removed in a future release of Logstash.");
+            }
+
+            sb.append(" Please use `").append(canonicalProxy.getName()).append("` instead");
+
+            DEPRECATION_LOGGER.deprecated(sb.toString());
         }
     }
 

logstash-core/src/main/java/org/logstash/settings/SettingWithDeprecatedAlias.java

@@ -38,21 +38,22 @@ public class SettingWithDeprecatedAlias<T> extends SettingDelegator<T> {
      * including the canonical setting and a deprecated alias.
      * @param canonicalSetting the setting to wrap
      * @param deprecatedAliasName the name for the deprecated alias
+     * @param obsoletedVersion the version of Logstash that deprecated alias will be removed
      *
      * @return List of [SettingWithDeprecatedAlias, DeprecatedAlias]
      * */
-    static <T> List<Setting<T>> wrap(BaseSetting<T> canonicalSetting, String deprecatedAliasName) {
-        final SettingWithDeprecatedAlias<T> settingProxy = new SettingWithDeprecatedAlias<>(canonicalSetting, deprecatedAliasName);
+    static <T> List<Setting<T>> wrap(BaseSetting<T> canonicalSetting, String deprecatedAliasName, String obsoletedVersion) {
+        final SettingWithDeprecatedAlias<T> settingProxy = new SettingWithDeprecatedAlias<>(canonicalSetting, deprecatedAliasName, obsoletedVersion);
         return Arrays.asList(settingProxy, settingProxy.deprecatedAlias);
     }
 
     private DeprecatedAlias<T> deprecatedAlias;
 
     @SuppressWarnings("this-escape")
-    protected SettingWithDeprecatedAlias(BaseSetting<T> canonicalSetting, String deprecatedAliasName) {
+    protected SettingWithDeprecatedAlias(BaseSetting<T> canonicalSetting, String deprecatedAliasName, String obsoletedVersion) {
         super(canonicalSetting);
 
-        this.deprecatedAlias = new DeprecatedAlias<T>(this, deprecatedAliasName);
+        this.deprecatedAlias = new DeprecatedAlias<T>(this, deprecatedAliasName, obsoletedVersion);
     }
 
     BaseSetting<T> getCanonicalSetting() {