logstash-mixin-deprecation_logger_support 1.0.0-java

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: bb9217b282d05dfe1f92c219fe1aa4b655501eb5211612a1f33d70961bcbb118
4
+ data.tar.gz: 3c468606779a355e6bf0760d7396e860cb9461dd2ee6f36ff93aed437962a828
5
+ SHA512:
6
+ metadata.gz: bf4c351c4317bddef463e5a7eb4758b5ba6c691d4aa41c01799f99c9838321da2e282f9986b1802ca5aa6154e60b08e10a605eeac14407f59868c8405a1fdd46
7
+ data.tar.gz: 428e3ff4b6ce2b1cc8be50424aa688b9a7643bc6b17c03f211b079867d2c6917aae39bb9cbb0c2c43490cb683bd2d20df8f5237fa0f0cfa9e0d989605442e663
@@ -0,0 +1,3 @@
1
+ # 1.0.0
2
+
3
+ - Implements the Deprecation Logger from Logstash 7.6 as a version-independent plugin mixin.
data/LICENSE ADDED
@@ -0,0 +1,13 @@
1
+ Copyright (c) 2019 Elastic N.V. <http://www.elastic.co>
2
+
3
+ Licensed under the Apache License, Version 2.0 (the "License");
4
+ you may not use this file except in compliance with the License.
5
+ You may obtain a copy of the License at
6
+
7
+ http://www.apache.org/licenses/LICENSE-2.0
8
+
9
+ Unless required by applicable law or agreed to in writing, software
10
+ distributed under the License is distributed on an "AS IS" BASIS,
11
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ See the License for the specific language governing permissions and
13
+ limitations under the License.
@@ -0,0 +1,46 @@
1
+ # Deprecation Logger Support Mixin
2
+
3
+ This gem provides an API-compatible implementation of the Logstash Deprecation
4
+ Logger introduced in Logstash v7.6. It can be added as a dependency of any
5
+ plugin that wishes to use the deprecation logger while still supporting older
6
+ Logstash versions.
7
+
8
+ ## Usage
9
+
10
+ 1. Add this gem as a runtime dependency of your plugin:
11
+
12
+ ~~~ ruby
13
+ Gem::Specification.new do |s|
14
+ # ...
15
+
16
+ s.add_runtime_dependency 'logstash-mixin-deprecation_logger_support', '~>1.0'
17
+ end
18
+ ~~~
19
+
20
+ 2. In your plugin code, require this library and include it into your class or
21
+ module that already inherits `LogStash::Util::Loggable`:
22
+
23
+ ~~~ ruby
24
+ require 'logstash/plugin_mixins/deprecation_logger_support'
25
+
26
+ class LogStash::Inputs::Foo < Logstash::Inputs::Base
27
+ include LogStash::PluginMixins::DeprecationLoggerSupport
28
+
29
+ # ...
30
+ end
31
+ ~~~
32
+
33
+ 3. Use the deprecation logger; your plugin does not need to know whether the
34
+ deprecation logger was provided by Logstash core or by this gem.
35
+
36
+ ~~~ ruby
37
+ def register
38
+ deprecation_logger.deprecate("your message")
39
+ end
40
+ ~~~
41
+
42
+ ## Development
43
+
44
+ This gem:
45
+ - *MUST* remain API-stable at 1.x
46
+ - *MUST NOT* introduce additional runtime dependencies
@@ -0,0 +1,60 @@
1
+ # encoding: utf-8
2
+
3
+ require 'logstash/version'
4
+ require 'logstash/namespace'
5
+
6
+ require 'logstash/plugin'
7
+
8
+ require_relative 'deprecation_logger_support/legacy_loggable_warn_adapter'
9
+ require_relative 'deprecation_logger_support/legacy_init_adapter'
10
+
11
+ module LogStash
12
+ module PluginMixins
13
+ ##
14
+ # This `DeprecationLoggerSupport` can be mixed into any `LogStash::Util::Loggable`,
15
+ # and will ensure that the result provides an API-compatible implementation of the
16
+ # deprecation logger introduced in Logstash 7.6.0
17
+ #
18
+ # This allows plugins to use the new deprecation logging API without
19
+ # imposing new version constraints on those plugins.
20
+ #
21
+ # When used in an older Logstash, the implementation provided by this
22
+ # mixin falls through to send a WARN-level message to the Logger provided
23
+ # by `Loggable#logger`.
24
+ module DeprecationLoggerSupport
25
+
26
+ NATIVE_SUPPORT_PROVIDED = LogStash::Util::Loggable.method_defined?(:deprecation_logger)
27
+
28
+ ##
29
+ # Including the `DeprecationLoggerSupport` into any module or class that
30
+ # is already a `LogStash::Util::Loggable` ensures that the result provides
31
+ # a `Loggable#deprecation_logger` that is API-compatible with the one
32
+ # introduced to `Loggable` in Logstash 7.6.
33
+ #
34
+ # @param base [Module]: a module or class that already includes the
35
+ # Logstash Loggable utility
36
+ def self.included(base)
37
+ fail(ArgumentError, "`#{base}` must be LogStash::Util::Loggable") unless base < LogStash::Util::Loggable
38
+
39
+ unless NATIVE_SUPPORT_PROVIDED
40
+ base.send(:include, LegacyLoggableWarnAdapter)
41
+ base.send(:include, LegacyInitAdapter) if base <= LogStash::Plugin
42
+ end
43
+ end
44
+
45
+ ##
46
+ # Extending the `DeprecationLoggerSupport` into any`LogStash::Util::Loggable`
47
+ # will ensure that it provides a `Loggable#deprecation_logger` that is
48
+ # API-compatible with the one introduced in `Loggable` in Logstash 7.6
49
+ #
50
+ # @param base [LogStash::Util::Loggable]: an object whose class already
51
+ # includes the Logstash Loggable
52
+ # utility
53
+ def self.extended(base)
54
+ fail(ArgumentError, "`#{base}` must be LogStash::Util::Loggable") unless base.kind_of?(LogStash::Util::Loggable)
55
+
56
+ base.extend(LegacyLoggableWarnAdapter) unless NATIVE_SUPPORT_PROVIDED
57
+ end
58
+ end
59
+ end
60
+ end
@@ -0,0 +1,25 @@
1
+ # encoding: utf-8
2
+
3
+ module LogStash
4
+ module PluginMixins
5
+ module DeprecationLoggerSupport
6
+
7
+ ##
8
+ # The `LegacyInitAdapter` is used to hook into the initialization of
9
+ # Logstash Plugins to ensure that a `@deprecation_logger` instance
10
+ # variable is initialized.
11
+ #
12
+ # @api internal (@see DeprecationLoggerSupport::included)
13
+ module LegacyInitAdapter
14
+ ##
15
+ # @api internal
16
+ # @since 1.0.0
17
+ def initialize(*args)
18
+ super if defined?(super)
19
+
20
+ @deprecation_logger ||= self.deprecation_logger
21
+ end
22
+ end
23
+ end
24
+ end
25
+ end
@@ -0,0 +1,61 @@
1
+ # encoding: utf-8
2
+
3
+ require 'thread' # Mutex
4
+
5
+ module LogStash
6
+ module PluginMixins
7
+ module DeprecationLoggerSupport
8
+
9
+ ##
10
+ # The `LegacyLoggableWarnAdapter` provides a `#deprecation_logger`
11
+ # returning a `DeprecationLogger` that is implemented via `Loggable#warn`.
12
+ # @api internal (@see DeprecationLoggerSupport::included)
13
+ module LegacyLoggableWarnAdapter
14
+ ##
15
+ # the `DeprecationLogger` is API-compatible with the one provided in
16
+ # Logstash 7.6
17
+ class DeprecationLogger
18
+ ##
19
+ # @api private
20
+ # @param base_logger [LogStash::Logger]
21
+ def initialize(base_logger)
22
+ @base_logger = base_logger
23
+ end
24
+
25
+ ##
26
+ # @overload deprecated(message)
27
+ # @since 1.0.0
28
+ # @param message [String]: a complete message string
29
+ # @return [void]
30
+ #
31
+ # @overload deprecated(template, replacement)
32
+ # @since 1.0.0
33
+ # @param template [String]: a template string contiaining exactly
34
+ # one `{}` placeholder
35
+ # @param replacement [Object]: an object to be stringified and
36
+ # inserted in place of the placeholder
37
+ # @return [void]
38
+ def deprecated(message, *args)
39
+ @base_logger.warn("DEPRECATED: #{message}", *args)
40
+ end
41
+ end
42
+ private_constant :DeprecationLogger
43
+
44
+ ##
45
+ # @api private
46
+ MEMOIZE_MUTEX = Mutex.new
47
+ private_constant :MEMOIZE_MUTEX
48
+
49
+ ##
50
+ # @return [DeprecationLogger]
51
+ def deprecation_logger
52
+ # threadsafe at-most-once memoize
53
+ # NOTE: the instance variable used here is _not_ a public part of the API.
54
+ @_deprecation_logger_legacy_adapter || MEMOIZE_MUTEX.synchronize do
55
+ @_deprecation_logger_legacy_adapter ||= DeprecationLogger.new(logger)
56
+ end
57
+ end
58
+ end
59
+ end
60
+ end
61
+ end
@@ -0,0 +1,126 @@
1
+ # encoding: utf-8
2
+
3
+ require "logstash-core"
4
+
5
+ require 'logstash/plugin_mixins/deprecation_logger_support'
6
+
7
+ ##
8
+ # @subject deprecation_logger
9
+ # @requires: instance
10
+ shared_examples_for 'DeprecationLogger' do
11
+
12
+ if !LogStash::PluginMixins::DeprecationLoggerSupport::NATIVE_SUPPORT_PROVIDED
13
+ before(:each) do
14
+ allow(instance.logger).to receive(:warn).with(any_args).and_return(nil)
15
+ end
16
+ end
17
+
18
+ it { is_expected.to respond_to :deprecated }
19
+
20
+ context '#deprecated' do
21
+ context 'when sent a single argument' do
22
+ it 'accepts a single string argument' do
23
+ deprecation_logger.deprecated('this is a TEST')
24
+ end
25
+
26
+ if !LogStash::PluginMixins::DeprecationLoggerSupport::NATIVE_SUPPORT_PROVIDED
27
+ it 'passes through to logger.warn' do
28
+ deprecation_logger.deprecated('this is a TEST')
29
+ expect(instance.logger).to have_received(:warn).with("DEPRECATED: this is a TEST")
30
+ end
31
+ end
32
+ end
33
+
34
+
35
+ context 'when sent two arguments' do
36
+ it 'accepts two arguments' do
37
+ deprecation_logger.deprecated('this is a {}', 'TEST')
38
+ end
39
+
40
+ if !LogStash::PluginMixins::DeprecationLoggerSupport::NATIVE_SUPPORT_PROVIDED
41
+ it 'passes both arguments to logger.warn' do
42
+ deprecation_logger.deprecated('this is a {}', 'TEST')
43
+ expect(instance.logger).to have_received(:warn).with("DEPRECATED: this is a {}", "TEST")
44
+ end
45
+ end
46
+ end
47
+ end
48
+ end
49
+
50
+ ##
51
+ # @subject: instance
52
+ # @param: method_name
53
+ # @varargs: params
54
+ shared_examples_for 'memoized method' do |method_name, *params|
55
+ it 'returns the same object from successive calls' do
56
+ first_return = instance.send(method_name, *params)
57
+ second_return = instance.send(method_name, *params)
58
+
59
+ expect(second_return).to eq(first_return)
60
+ end
61
+ end
62
+
63
+ describe LogStash::PluginMixins::DeprecationLoggerSupport do
64
+ let(:deprecation_logger_support) { LogStash::PluginMixins::DeprecationLoggerSupport }
65
+
66
+ let(:class_including_loggable) { Class.new { include LogStash::Util::Loggable } }
67
+ let(:class_not_including_loggable) { Class.new { } }
68
+
69
+ context 'included into a class' do
70
+ context 'that already includes Loggable' do
71
+ let(:class_with_deprecation_logger_support) do
72
+ Class.new(class_including_loggable) do
73
+ include LogStash::PluginMixins::DeprecationLoggerSupport
74
+ end
75
+ end
76
+ context 'when instantiated' do
77
+ subject(:instance) { class_with_deprecation_logger_support.new }
78
+ context '#deprecation_logger' do
79
+ it_behaves_like 'memoized method', :deprecation_logger
80
+ context 'the returned object' do
81
+ it_behaves_like 'DeprecationLogger' do
82
+ subject(:deprecation_logger) { instance.send(:deprecation_logger) }
83
+ end
84
+ end
85
+ end
86
+ context 'and class is a LogStash::Plugin' do
87
+ let(:class_including_loggable) { Class.new(LogStash::Plugin) }
88
+ subject(:instance) { class_with_deprecation_logger_support.new({}) }
89
+ context '@deprecation_logger' do
90
+ it_behaves_like 'DeprecationLogger' do
91
+ subject(:deprecation_logger) { instance.instance_variable_get(:@deprecation_logger) }
92
+ end
93
+ end
94
+ end
95
+ end
96
+ end
97
+ context 'that does not include Loggable' do
98
+ it 'errors helpfully' do
99
+ expect { class_not_including_loggable.send(:include, LogStash::PluginMixins::DeprecationLoggerSupport) }
100
+ .to raise_error(ArgumentError, /Loggable/)
101
+ end
102
+ end
103
+ end
104
+
105
+ context 'extended into an object' do
106
+ context 'that is Loggable' do
107
+ subject(:instance) { class_including_loggable.new }
108
+ before(:each) { instance.extend(LogStash::PluginMixins::DeprecationLoggerSupport)}
109
+ context '#deprecation_logger' do
110
+ it_behaves_like 'memoized method', :deprecation_logger
111
+ context 'the returned object' do
112
+ it_behaves_like 'DeprecationLogger' do
113
+ subject(:deprecation_logger) { instance.send(:deprecation_logger) }
114
+ end
115
+ end
116
+ end
117
+ end
118
+ context 'that is not Loggable' do
119
+ subject(:instance) { class_not_including_loggable.new }
120
+ it 'errors helpfully' do
121
+ expect { instance.extend(deprecation_logger_support) }
122
+ .to raise_error(ArgumentError, /Loggable/)
123
+ end
124
+ end
125
+ end
126
+ end
metadata ADDED
@@ -0,0 +1,84 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: logstash-mixin-deprecation_logger_support
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0
5
+ platform: java
6
+ authors:
7
+ - Elastic
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2020-01-14 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: 5.0.0
19
+ name: logstash-core
20
+ prerelease: false
21
+ type: :runtime
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - ">="
25
+ - !ruby/object:Gem::Version
26
+ version: 5.0.0
27
+ - !ruby/object:Gem::Dependency
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - "~>"
31
+ - !ruby/object:Gem::Version
32
+ version: '3.9'
33
+ name: rspec
34
+ prerelease: false
35
+ type: :development
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - "~>"
39
+ - !ruby/object:Gem::Version
40
+ version: '3.9'
41
+ description: This gem is meant to be a dependency of any Logstash plugin that wishes
42
+ to use the Deprecation Logger introduced in 7.6 while maintaining backward-compatibility
43
+ with earlier Logstashes. When used on older Logstash versions, it provides an implementation
44
+ of the deprecation logger that forwards deprecation messages to the normal logger
45
+ at WARN-level with a `DEPRECATED` prefix.
46
+ email: info@elastic.co
47
+ executables: []
48
+ extensions: []
49
+ extra_rdoc_files: []
50
+ files:
51
+ - CHANGELOG.md
52
+ - LICENSE
53
+ - README.md
54
+ - lib/logstash/plugin_mixins/deprecation_logger_support.rb
55
+ - lib/logstash/plugin_mixins/deprecation_logger_support/legacy_init_adapter.rb
56
+ - lib/logstash/plugin_mixins/deprecation_logger_support/legacy_loggable_warn_adapter.rb
57
+ - spec/logstash/plugin_mixins/deprecation_logger_support_spec.rb
58
+ homepage: https://github.com/logstash-plugins/logstash-mixin-deprecation_logger_support
59
+ licenses:
60
+ - Apache-2.0
61
+ metadata: {}
62
+ post_install_message:
63
+ rdoc_options: []
64
+ require_paths:
65
+ - lib
66
+ required_ruby_version: !ruby/object:Gem::Requirement
67
+ requirements:
68
+ - - ">="
69
+ - !ruby/object:Gem::Version
70
+ version: '0'
71
+ required_rubygems_version: !ruby/object:Gem::Requirement
72
+ requirements:
73
+ - - ">="
74
+ - !ruby/object:Gem::Version
75
+ version: '0'
76
+ requirements: []
77
+ rubyforge_project:
78
+ rubygems_version: 2.6.11
79
+ signing_key:
80
+ specification_version: 4
81
+ summary: Support for the Deprecation Logger introduced in Logstash 7.6, for plugins
82
+ wishing to use this API on older Logstashes
83
+ test_files:
84
+ - spec/logstash/plugin_mixins/deprecation_logger_support_spec.rb