logstash-mixin-ecs_compatibility_support 1.1.0-java → 1.2.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08a8069171fd7a69e9adec65ef751e693ef6a3979e7d9b6346773f880d07a753'
-  data.tar.gz: 7ff7dc6c1bbabc1db323e253dc2c7e99bd7e08b701b59ce3e69bda5dc2c3012d
+  metadata.gz: a6ff73bf503783cc17b6fbc2ebebcf23398d52ffa01cfc2a9d397566833f9706
+  data.tar.gz: 69d950da27ad60c8fdb09a08e72f7a4ffce9ede7e85cad0bfb130854cf40a07b
 SHA512:
-  metadata.gz: 732274d0877f02583087f9181e862c8ce47c4eb8a8c8aba42557b5e149e3d17cfdabb5b23c240107c38194f730511f107084fe4d5ba2bd376fb56b36382ba811
-  data.tar.gz: d80b1895da371395f72dab57cb2cb61f858f68d9a0a001416ab7406ebb94c4ba9fbe74efeab7adc9e22ae7be50a2c58f7b628aa1c3de7e1bcac823a0cbd74865
+  metadata.gz: 5334c125b5e9b24567500ae94546b3acd5260d7f83232eaa173439d68e8d974ca294f4a3f5b0c33d0d760ac4d843ea67bcb920b0713f480848e6d5044a43895b
+  data.tar.gz: 3b5bddca9732f6f03f79d4bf8ebf0dbeedb120dd7b23703f68c7e8410f5896e7124e343a2a843ce0346eeee6463c02bf738d1add11fed102f7c12e4147707e8f

data/CHANGELOG.md

@@ -1,3 +1,8 @@
-# 1.0.0
+# 1.2.0
+ - Added support for resolution aliases, allowing a plugin that uses `ecs_select` to support multiple ECS versions with a single declaration.
+
+# 1.1.0
+ - Added support for `ecs_select` helper, allowing plugins to declare mappings that are selected during plugin instantiation.
 
+# 1.0.0
  - Support Mixin for ensuring a plugin has an `ecs_compatibility` method that is configurable from an `ecs_compatibility` option that accepts the literal `disabled` or a v-prefixed integer representing a major ECS version (e.g., `v1`), using the implementation from Logstash core if available.

data/README.md

@@ -67,13 +67,13 @@ during initialization based on the instantiated plugin's effective
 mappings, because it allows those mappings to be side-by-side where they are
 unlikely to diverge and introduce bugs.
 
-1. Add version `~>1.1` of this gem as a runtime dependency of your Logstash plugin's `gemspec`:
+1. Add version `~>1.2` of this gem as a runtime dependency of your Logstash plugin's `gemspec`:
 
     ~~~ ruby
     Gem::Specification.new do |s|
       # ...
 
-      s.add_runtime_dependency 'logstash-mixin-ecs_compatibility_support', '~>1.1'
+      s.add_runtime_dependency 'logstash-mixin-ecs_compatibility_support', '~>1.2'
     end
     ~~~
 
@@ -95,6 +95,20 @@ unlikely to diverge and introduce bugs.
    whether that mode was explicitly defined for the plugin instance or implictly
    defined by the pipeline in which the plugin is run.
 
+   You can also optionally provide an alias mapping, for when your plugin supports
+   multiple versions of ECS that are largely identical to each other. This can be
+   especially helpful when using `ecs_select`.
+
+    ~~~ ruby
+    require 'logstash/plugin_mixins/ecs_compatibility_support'
+
+    class LogStash::Inputs::Foo < Logstash::Inputs::Base
+      include LogStash::PluginMixins::ECSCompatibilitySupport(:disabled,:v1,:v8 => :v1)
+
+      # ...
+    end
+    ~~~
+
 3. As in the simple usage example, you can use the `ecs_compatibility` method.
 
    But when supported versions are specified, you can also use the `ecs_select`
@@ -108,6 +122,9 @@ unlikely to diverge and introduce bugs.
       end
     ~~~
 
+   If you initialized the mixin with an alias mapping, missing values will
+   be resolved by their alias.
+
    NOTE: `ecs_select` should only be used during plugin initialization and
    not during event-by-event processing.
 

data/lib/logstash/plugin_mixins/ecs_compatibility_support.rb

@@ -101,6 +101,10 @@ module LogStash
       end
     end
 
+    ##
+    # @override ECSCompatibilitySupport(*supported_versions, alias_map={})
+    #   @param supported_versions [Array[Symbol]]: the supported ECS versions
+    #   @param alias_map [Hash{Symbol=>Symbol}]: an optional mapping of aliases (keys) to supported version (values)
     def self.ECSCompatibilitySupport(*supported_versions)
       return ECSCompatibilitySupport if supported_versions.empty?
 

data/lib/logstash/plugin_mixins/ecs_compatibility_support/selector.rb

@@ -26,14 +26,31 @@ module LogStash
           base.include(ECSCompatibilitySupport)
         end
 
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
         ##
         # @api private
         # @see ECSCompatibilitySupport()
         # @param ecs_modes_supported
-        def initialize(*ecs_modes_supported)
+        def initialize(*ecs_modes_and_optional_alias_map)
+          selector_module = self
+
+          alias_mapping = ecs_modes_and_optional_alias_map.last.kind_of?(Hash) ? ecs_modes_and_optional_alias_map.pop.dup.freeze : EMPTY_HASH
+          ecs_modes_supported = ecs_modes_and_optional_alias_map.dup
+
           fail(ArgumentError, "one or more ecs_modes_supported required") if ecs_modes_supported.empty?
           fail(ArgumentError, "ecs_modes_supported must only contain symbols") unless ecs_modes_supported.all? { |s| s.kind_of?(Symbol) }
 
+          fail(ArgumentError, "alias names must be symbols") unless alias_mapping.keys.all? { |v| v.kind_of?(Symbol) }
+          fail(ArgumentError, "alias targets must be symbols") unless alias_mapping.values.all? { |v| v.kind_of?(Symbol) }
+          fail(ArgumentError, "alias must not redefine") if alias_mapping.keys.any? {|v| ecs_modes_supported.include?(v) }
+          fail(ArgumentError, "alias map must not have circular references") if circular_references_present?(alias_mapping)
+
+          ecs_modes_supported |= alias_mapping.keys
+
+          fail(ArgumentError, "alias target doesn't exist") if alias_mapping.values.any? { |v| !ecs_modes_supported.include?(v) }
+
           ecs_modes_supported.freeze
 
           ##
@@ -49,7 +66,7 @@ module LogStash
                         "Supported modes are: #{ecs_modes_supported}"
               fail(LogStash::ConfigurationError, message)
             end
-            @_ecs_select = State.new(ecs_modes_supported, effective_ecs_mode)
+            @_ecs_select = selector_module.state_for(effective_ecs_mode)
           end
 
           ##
@@ -58,6 +75,13 @@ module LogStash
           define_method(:ecs_select) { @_ecs_select }
 
           define_singleton_method(:ecs_modes_supported) { ecs_modes_supported }
+
+          define_singleton_method(:state_for) do |selected_value|
+            unless ecs_modes_supported.include?(selected_value)
+              fail(NotImplementedError, "Unsupported state `#{selected_value}` (expected one of #{ecs_modes_supported})")
+            end
+            State.new(ecs_modes_supported, selected_value, alias_mapping)
+          end
         end
 
         ##
@@ -66,6 +90,21 @@ module LogStash
           "#{Selector}(#{ecs_modes_supported.join(',')})"
         end
 
+        private
+
+        def circular_references_present?(alias_candidates)
+          alias_candidates.each do |candidate, target|
+            current = target
+            (alias_candidates.size + 1).times do
+              return true if current == candidate
+              break unless alias_candidates.include?(current)
+              current = alias_candidates.fetch(current)
+            end
+          end
+
+          false
+        end
+
         ##
         # A `State` contains the active mode and a list of all supported modes.
         #
@@ -77,12 +116,15 @@ module LogStash
         # @api private
         class State
           ##
-          # @api private
+          # @api private -- Use Selector#state_for(current_value)
           # @param supported_modes [Array<Symbol>]
           # @param active_mode [Symbol]
-          def initialize(supported_modes, active_mode)
+          def initialize(supported_modes, active_mode, alias_map=EMPTY_HASH)
+            fail(ArgumentError, "invalid alias mapping") unless alias_map.flatten.all? {|v| supported_modes.include?(v) }
+
             @supported_modes = supported_modes
             @active_mode = active_mode
+            @alias_map = alias_map
           end
 
           attr_reader :active_mode
@@ -102,13 +144,20 @@ module LogStash
 
             fail(ArgumentError, "at least one choice must be defined") if defined_choices.empty?
 
-            missing = @supported_modes - defined_choices.keys
+            missing = @supported_modes - (defined_choices.keys + @alias_map.keys)
             fail(ArgumentError, "missing one or more required choice definition #{missing}") if missing.any?
 
             unknown = defined_choices.keys - @supported_modes
             fail(ArgumentError, "unknown choices #{unknown}; valid choices are #{@supported_modes}") if unknown.any?
 
-            defined_choices.fetch(@active_mode)
+            # resolve aliases of missing choices
+            effective_mode = @active_mode
+            @alias_map.size.times do # theoretical upper limit of alias chain
+              break if defined_choices.include?(effective_mode)
+              effective_mode = @alias_map.fetch(effective_mode)
+            end
+
+            defined_choices.fetch(effective_mode)
           end
           alias_method :[], :value_from
         end

data/lib/logstash/plugin_mixins/ecs_compatibility_support/spec_helper.rb

@@ -28,15 +28,13 @@ module LogStash
       # ~~~
       module SpecHelper
         def ecs_compatibility_matrix(*supported_modes,&block)
-          if supported_modes.empty? || supported_modes.any? { |mode| !mode.kind_of?(Symbol) }
-            fail(ArgumentError, "ecs_compatibility_matrix(*supported_modes) requires one or more symbol supported_modes")
-          end
+          ecs_selector = Selector.new(*supported_modes)
 
-          supported_modes.each do |active_mode|
+          ecs_selector.ecs_modes_supported.each do |active_mode|
             context "`ecs_compatibility => #{active_mode}`" do
               let(:ecs_compatibility) { active_mode }
 
-              ecs_select = Selector::State.new(supported_modes, active_mode)
+              ecs_select = ecs_selector.state_for(active_mode)
               instance_exec(ecs_select, &block)
             end
           end

data/spec/logstash/plugin_mixins/ecs_compatibility_support/selector_spec.rb

@@ -34,6 +34,27 @@ describe LogStash::PluginMixins::ECSCompatibilitySupport::Selector do
         expect(selector_mod.name).to include('v1')
       end
     end
+    it 'accepts an alias list' do
+      selector_mod = described_class.new(:disabled, :v1, :v8 => :v1)
+      aggregate_failures do
+        expect(selector_mod.ecs_modes_supported).to contain_exactly(:disabled, :v1, :v8)
+        expect(selector_mod.name).to include('disabled')
+        expect(selector_mod.name).to include('v1')
+        expect(selector_mod.name).to include('v8')
+      end
+    end
+    it 'rejects alias list that doesnt resolve' do
+      expect { described_class.new(:disabled, :v1, :v8 => :v2) }.to raise_error(ArgumentError, /alias target/)
+    end
+    it 'rejects tight circular aliases' do
+      expect { described_class.new(:disabled, :v1, :v8 => :v8) }.to raise_error(ArgumentError, /circular/)
+    end
+    it 'rejects loose circular aliases' do
+      expect { described_class.new(:disabled, :v1, :v8 => :v7, :v7 => :v6, :v6 => :v8) }.to raise_error(ArgumentError, /circular/)
+    end
+    it 'rejects alias that redefines concrete definition' do
+      expect { described_class.new(:disabled, :v1, :v1 => :disabled) }.to raise_error(ArgumentError, /redefine/)
+    end
   end
   context 'included into a class' do
     let(:ecs_compatibility_support) { LogStash::PluginMixins::ECSCompatibilitySupport }
@@ -111,6 +132,19 @@ describe LogStash::PluginMixins::ECSCompatibilitySupport::Selector do
             it 'selects the correct effective value' do
               expect(ecs_select[disabled: "nope", v1: "winner"]).to eq("winner")
             end
+            context 'when aliases are given' do
+              let(:ecs_supported_modes) { [:disabled, :v1, :v8 => :v2, :v2 => :v1 ] }
+              let(:ecs_effective_mode) { :v8 }
+              it 'selects a given value' do
+                expect(ecs_select[disabled: "nope", v1: "nah", v8: "hooray"]).to eq("hooray")
+              end
+              it 'resolves the deepest alias of a missing value' do
+                expect(ecs_select[disabled: "sad-trombone", v1: "wahoo"]).to eq("wahoo")
+              end
+              it 'resolves the intermediate alias of a missing value' do
+                expect(ecs_select[disabled: "sad-trombone", v1: "oh-no", v2: "nice"]).to eq("nice")
+              end
+            end
           end
         end
       end

data/spec/logstash/plugin_mixins/ecs_compatibility_support/spec_helper_spec.rb

@@ -6,14 +6,14 @@ require "logstash/plugin_mixins/ecs_compatibility_support/spec_helper"
 
 describe LogStash::PluginMixins::ECSCompatibilitySupport::SpecHelper, :ecs_compatibility_support do
   context '::ecs_compatibility_matrix(*modes)' do
-    ecs_compatibility_matrix(:disabled,:v1) do |ecs_select|
+    ecs_compatibility_matrix(:disabled,:v1,:v8 => :v1) do |ecs_select|
       it("sets `ecs_compatibility` with the current active mode `#{ecs_select.active_mode}`") do
         expect(ecs_compatibility).to eq(ecs_select.active_mode)
       end
       context 'the yielded value' do
         subject { ecs_select }
         it { is_expected.to be_a_kind_of LogStash::PluginMixins::ECSCompatibilitySupport::Selector::State }
-        its(:supported_modes) { is_expected.to contain_exactly(:disabled,:v1) }
+        its(:supported_modes) { is_expected.to contain_exactly(:disabled,:v1,:v8) }
         its(:active_mode) { is_expected.to be ecs_compatibility }
       end
     end

data/spec/logstash/plugin_mixins/ecs_compatibility_support_spec.rb

@@ -155,5 +155,12 @@ describe 'LogStash::PluginMixins::ECSCompatibilitySupport()' do
       expect(selector_module.ecs_modes_supported).to contain_exactly(:disabled,:v1)
     end
   end
+  context 'with symbol arguments and alias mapping' do
+    it 'returns a properly-configured LogStash::PluginMixins::ECSCompatibilitySupport::Selector' do
+      selector_module = LogStash::PluginMixins::ECSCompatibilitySupport(:disabled,:v1,:v8 => :v1)
+      expect(selector_module).to be_a_kind_of(LogStash::PluginMixins::ECSCompatibilitySupport::Selector)
+      expect(selector_module.ecs_modes_supported).to contain_exactly(:disabled,:v1,:v8)
+    end
+  end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-mixin-ecs_compatibility_support
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: java
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-25 00:00:00.000000000 Z
+date: 2021-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement