logstash-mixin-deprecation_logger_support 1.0.0-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb9217b282d05dfe1f92c219fe1aa4b655501eb5211612a1f33d70961bcbb118
+  data.tar.gz: 3c468606779a355e6bf0760d7396e860cb9461dd2ee6f36ff93aed437962a828
+SHA512:
+  metadata.gz: bf4c351c4317bddef463e5a7eb4758b5ba6c691d4aa41c01799f99c9838321da2e282f9986b1802ca5aa6154e60b08e10a605eeac14407f59868c8405a1fdd46
+  data.tar.gz: 428e3ff4b6ce2b1cc8be50424aa688b9a7643bc6b17c03f211b079867d2c6917aae39bb9cbb0c2c43490cb683bd2d20df8f5237fa0f0cfa9e0d989605442e663

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 1.0.0
+
+ - Implements the Deprecation Logger from Logstash 7.6 as a version-independent plugin mixin.

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2019 Elastic N.V. <http://www.elastic.co>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,46 @@
+# Deprecation Logger Support Mixin
+
+This gem provides an API-compatible implementation of the Logstash Deprecation
+Logger introduced in Logstash v7.6. It can be added as a dependency of any
+plugin that wishes to use the deprecation logger while still supporting older
+Logstash versions.
+
+## Usage
+
+1. Add this gem as a runtime dependency of your plugin:
+
+    ~~~ ruby
+    Gem::Specification.new do |s|
+      # ...
+
+      s.add_runtime_dependency 'logstash-mixin-deprecation_logger_support', '~>1.0'
+    end
+    ~~~
+
+2. In your plugin code, require this library and include it into your class or
+   module that already inherits `LogStash::Util::Loggable`:
+
+    ~~~ ruby
+    require 'logstash/plugin_mixins/deprecation_logger_support'
+
+    class LogStash::Inputs::Foo < Logstash::Inputs::Base
+      include LogStash::PluginMixins::DeprecationLoggerSupport
+
+      # ...
+    end
+    ~~~
+
+3. Use the deprecation logger; your plugin does not need to know whether the
+   deprecation logger was provided by Logstash core or by this gem.
+
+    ~~~ ruby
+      def register
+        deprecation_logger.deprecate("your message")
+      end
+    ~~~
+
+## Development
+
+This gem:
+ - *MUST* remain API-stable at 1.x
+ - *MUST NOT* introduce additional runtime dependencies

data/lib/logstash/plugin_mixins/deprecation_logger_support.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'logstash/version'
+require 'logstash/namespace'
+
+require 'logstash/plugin'
+
+require_relative 'deprecation_logger_support/legacy_loggable_warn_adapter'
+require_relative 'deprecation_logger_support/legacy_init_adapter'
+
+module LogStash
+  module PluginMixins
+    ##
+    # This `DeprecationLoggerSupport` can be mixed into any `LogStash::Util::Loggable`,
+    # and will ensure that the result provides an API-compatible implementation of the
+    # deprecation logger introduced in Logstash 7.6.0
+    #
+    # This allows plugins to use the new deprecation logging API without
+    # imposing new version constraints on those plugins.
+    #
+    # When used in an older Logstash, the implementation provided by this
+    # mixin falls through to send a WARN-level message to the Logger provided
+    # by `Loggable#logger`.
+    module DeprecationLoggerSupport
+
+      NATIVE_SUPPORT_PROVIDED = LogStash::Util::Loggable.method_defined?(:deprecation_logger)
+
+      ##
+      # Including the `DeprecationLoggerSupport` into any module or class that
+      # is already a `LogStash::Util::Loggable` ensures that the result provides
+      # a `Loggable#deprecation_logger` that is API-compatible with the one
+      # introduced to `Loggable` in Logstash 7.6.
+      #
+      # @param base [Module]: a module or class that already includes the
+      #                       Logstash Loggable utility
+      def self.included(base)
+        fail(ArgumentError, "`#{base}` must be LogStash::Util::Loggable") unless base < LogStash::Util::Loggable
+
+        unless NATIVE_SUPPORT_PROVIDED
+          base.send(:include, LegacyLoggableWarnAdapter)
+          base.send(:include, LegacyInitAdapter) if base <= LogStash::Plugin
+        end
+      end
+
+      ##
+      # Extending the `DeprecationLoggerSupport` into any`LogStash::Util::Loggable`
+      # will ensure that it provides a `Loggable#deprecation_logger` that is
+      # API-compatible with the one introduced in `Loggable` in Logstash 7.6
+      #
+      # @param base [LogStash::Util::Loggable]: an object whose class already
+      #                                         includes the Logstash Loggable
+      #                                         utility
+      def self.extended(base)
+        fail(ArgumentError, "`#{base}` must be LogStash::Util::Loggable") unless base.kind_of?(LogStash::Util::Loggable)
+
+        base.extend(LegacyLoggableWarnAdapter) unless NATIVE_SUPPORT_PROVIDED
+      end
+    end
+  end
+end

data/lib/logstash/plugin_mixins/deprecation_logger_support/legacy_init_adapter.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+module LogStash
+  module PluginMixins
+    module DeprecationLoggerSupport
+
+      ##
+      # The `LegacyInitAdapter` is used to hook into the initialization of
+      # Logstash Plugins to ensure that a `@deprecation_logger` instance
+      # variable is initialized.
+      #
+      # @api internal (@see DeprecationLoggerSupport::included)
+      module LegacyInitAdapter
+        ##
+        # @api internal
+        # @since 1.0.0
+        def initialize(*args)
+          super if defined?(super)
+
+          @deprecation_logger ||= self.deprecation_logger
+        end
+      end
+    end
+  end
+end

data/lib/logstash/plugin_mixins/deprecation_logger_support/legacy_loggable_warn_adapter.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+require 'thread' # Mutex
+
+module LogStash
+  module PluginMixins
+    module DeprecationLoggerSupport
+
+      ##
+      # The `LegacyLoggableWarnAdapter` provides a `#deprecation_logger`
+      # returning a `DeprecationLogger` that is implemented via `Loggable#warn`.
+      # @api internal (@see DeprecationLoggerSupport::included)
+      module LegacyLoggableWarnAdapter
+        ##
+        # the `DeprecationLogger` is API-compatible with the one provided in
+        # Logstash 7.6
+        class DeprecationLogger
+          ##
+          # @api private
+          # @param base_logger [LogStash::Logger]
+          def initialize(base_logger)
+            @base_logger = base_logger
+          end
+
+          ##
+          # @overload deprecated(message)
+          #   @since 1.0.0
+          #   @param message [String]: a complete message string
+          #   @return [void]
+          #
+          # @overload deprecated(template, replacement)
+          #   @since 1.0.0
+          #   @param template [String]: a template string contiaining exactly
+          #                             one `{}` placeholder
+          #   @param replacement [Object]: an object to be stringified and
+          #                                inserted in place of the placeholder
+          #   @return [void]
+          def deprecated(message, *args)
+            @base_logger.warn("DEPRECATED: #{message}", *args)
+          end
+        end
+        private_constant :DeprecationLogger
+
+        ##
+        # @api private
+        MEMOIZE_MUTEX = Mutex.new
+        private_constant :MEMOIZE_MUTEX
+
+        ##
+        # @return [DeprecationLogger]
+        def deprecation_logger
+          # threadsafe at-most-once memoize
+          # NOTE: the instance variable used here is _not_ a public part of the API.
+          @_deprecation_logger_legacy_adapter || MEMOIZE_MUTEX.synchronize do
+            @_deprecation_logger_legacy_adapter ||= DeprecationLogger.new(logger)
+          end
+        end
+      end
+    end
+  end
+end

data/spec/logstash/plugin_mixins/deprecation_logger_support_spec.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+
+require "logstash-core"
+
+require 'logstash/plugin_mixins/deprecation_logger_support'
+
+##
+# @subject deprecation_logger
+# @requires: instance
+shared_examples_for 'DeprecationLogger' do
+
+  if !LogStash::PluginMixins::DeprecationLoggerSupport::NATIVE_SUPPORT_PROVIDED
+    before(:each) do
+      allow(instance.logger).to receive(:warn).with(any_args).and_return(nil)
+    end
+  end
+
+  it { is_expected.to respond_to :deprecated }
+
+  context '#deprecated' do
+    context 'when sent a single argument' do
+      it 'accepts a single string argument' do
+        deprecation_logger.deprecated('this is a TEST')
+      end
+
+      if !LogStash::PluginMixins::DeprecationLoggerSupport::NATIVE_SUPPORT_PROVIDED
+        it 'passes through to logger.warn' do
+          deprecation_logger.deprecated('this is a TEST')
+          expect(instance.logger).to have_received(:warn).with("DEPRECATED: this is a TEST")  
+        end
+      end
+    end
+
+
+    context 'when sent two arguments' do
+      it 'accepts two arguments' do
+        deprecation_logger.deprecated('this is a {}', 'TEST')
+      end
+
+      if !LogStash::PluginMixins::DeprecationLoggerSupport::NATIVE_SUPPORT_PROVIDED
+        it 'passes both arguments to logger.warn' do
+          deprecation_logger.deprecated('this is a {}', 'TEST')
+          expect(instance.logger).to have_received(:warn).with("DEPRECATED: this is a {}", "TEST")  
+        end
+      end
+    end
+  end
+end
+
+##
+# @subject: instance
+# @param: method_name
+# @varargs: params
+shared_examples_for 'memoized method' do |method_name, *params|
+  it 'returns the same object from successive calls' do
+    first_return = instance.send(method_name, *params)
+    second_return = instance.send(method_name, *params)
+
+    expect(second_return).to eq(first_return)
+  end
+end
+
+describe LogStash::PluginMixins::DeprecationLoggerSupport do
+  let(:deprecation_logger_support) { LogStash::PluginMixins::DeprecationLoggerSupport }
+
+  let(:class_including_loggable) { Class.new { include LogStash::Util::Loggable } }
+  let(:class_not_including_loggable) { Class.new { } }
+
+  context 'included into a class' do
+    context 'that already includes Loggable' do
+      let(:class_with_deprecation_logger_support) do
+        Class.new(class_including_loggable) do
+          include LogStash::PluginMixins::DeprecationLoggerSupport
+        end
+      end
+      context 'when instantiated' do
+        subject(:instance) { class_with_deprecation_logger_support.new }
+        context '#deprecation_logger' do
+          it_behaves_like 'memoized method', :deprecation_logger
+          context 'the returned object' do
+            it_behaves_like 'DeprecationLogger' do
+              subject(:deprecation_logger) { instance.send(:deprecation_logger) }
+            end
+          end
+        end
+        context 'and class is a LogStash::Plugin' do
+          let(:class_including_loggable) { Class.new(LogStash::Plugin) }
+          subject(:instance) { class_with_deprecation_logger_support.new({}) }
+          context '@deprecation_logger' do
+            it_behaves_like 'DeprecationLogger' do
+              subject(:deprecation_logger) { instance.instance_variable_get(:@deprecation_logger) }
+            end
+          end
+        end
+      end
+    end
+    context 'that does not include Loggable' do
+      it 'errors helpfully' do
+        expect { class_not_including_loggable.send(:include, LogStash::PluginMixins::DeprecationLoggerSupport) }
+          .to raise_error(ArgumentError, /Loggable/)
+      end
+    end
+  end
+
+  context 'extended into an object' do
+    context 'that is Loggable' do
+      subject(:instance) { class_including_loggable.new }
+      before(:each) { instance.extend(LogStash::PluginMixins::DeprecationLoggerSupport)}
+      context '#deprecation_logger' do
+        it_behaves_like 'memoized method', :deprecation_logger
+        context 'the returned object' do
+          it_behaves_like 'DeprecationLogger' do
+            subject(:deprecation_logger) { instance.send(:deprecation_logger) }
+          end
+        end
+      end
+    end
+    context 'that is not Loggable' do
+      subject(:instance) { class_not_including_loggable.new }
+      it 'errors helpfully' do
+        expect { instance.extend(deprecation_logger_support) }
+          .to raise_error(ArgumentError, /Loggable/)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: logstash-mixin-deprecation_logger_support
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: java
+authors:
+- Elastic
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-01-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  name: logstash-core
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  name: rspec
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+description: This gem is meant to be a dependency of any Logstash plugin that wishes
+  to use the Deprecation Logger introduced in 7.6 while maintaining backward-compatibility
+  with earlier Logstashes. When used on older Logstash versions, it provides an implementation
+  of the deprecation logger that forwards deprecation messages to the normal logger
+  at WARN-level with a `DEPRECATED` prefix.
+email: info@elastic.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/logstash/plugin_mixins/deprecation_logger_support.rb
+- lib/logstash/plugin_mixins/deprecation_logger_support/legacy_init_adapter.rb
+- lib/logstash/plugin_mixins/deprecation_logger_support/legacy_loggable_warn_adapter.rb
+- spec/logstash/plugin_mixins/deprecation_logger_support_spec.rb
+homepage: https://github.com/logstash-plugins/logstash-mixin-deprecation_logger_support
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.6.11
+signing_key:
+specification_version: 4
+summary: Support for the Deprecation Logger introduced in Logstash 7.6, for plugins
+  wishing to use this API on older Logstashes
+test_files:
+- spec/logstash/plugin_mixins/deprecation_logger_support_spec.rb