logstash-mixin-ecs_compatibility_support 1.0.0-java → 1.3.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba10e5399ac0d62b035fb98cbb351e9e3c2cc857a25fa541a18998072e40b20c
-  data.tar.gz: e303a40b0d20f12de4bf57639957c59f12ca30db8e568b99136863e2246e3480
+  metadata.gz: 8a64fc499677faca675d99eccc08d8d397f6d1330b6073ce31ab1570a0e750d1
+  data.tar.gz: 6a4c3df642e4dc252d545069b4a7b301ecf246c2655b893409f1898643507353
 SHA512:
-  metadata.gz: 65f069880870f66b57b018108fad026d440d665a8fc06fc49c14aeeca1f3e8c4c93e1abfbb2227e2bb87a61a85d8c6bdf220c4efb093e4781f398f5c4334a6da
-  data.tar.gz: 9281a716c7101934d7803baf628b165cfed31716517eeaa8043e585710cb8ade34799b47891ef5679cfaa1342bbc79c107a52187178edf1873c50b77f125624b
+  metadata.gz: b84794d3a79993ecb23464e8293ee9f44d2430f6901c5f92f5dfcaa46e45fe09b5ee6f353afe8a8b36afa976f1bcc8b4ee69e123d2b665e5cb2b1228c9aea445
+  data.tar.gz: bb9d04088b8dcdd81a1ffefeb9ef1e5eec02e4fd24491684630e5c7e5c9a007121604c5b3435433f6a971b8e42eb2b0e926b1355fc0021e22f53a8de899cd433

data/CHANGELOG.md

@@ -1,3 +1,11 @@
-# 1.0.0
+# 1.3.0
+ - Feat: introduce a target check helper [#6](https://github.com/logstash-plugins/logstash-mixin-ecs_compatibility_support/pull/6) 
+
+# 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

@@ -1,6 +1,6 @@
 # ECS Compatibility Support Mixin
 
-[![Build Status](https://travis-ci.org/logstash-plugins/logstash-mixin-ecs_compatibility_support.svg?branch=master)](https://travis-ci.org/logstash-plugins/logstash-mixin-ecs_compatibility_support)
+[![Build Status](https://travis-ci.com/logstash-plugins/logstash-mixin-ecs_compatibility_support.svg?branch=master)](https://travis-ci.com/logstash-plugins/logstash-mixin-ecs_compatibility_support)
 
 This gem provides an API-compatible implementation of ECS-compatiblity mode,
 allowing plugins to be explicitly configured with `ecs_compatibility` in a way
@@ -8,7 +8,7 @@ that respects pipeline- and process-level settings where they are available.
 It can be added as a dependency of any plugin that wishes to implement one or
 more ECS-compatibility modes while still supporting older Logstash versions.
 
-## Usage
+## Usage (simple)
 
 1. Add version `~>1.0` of this gem as a runtime dependency of your Logstash plugin's `gemspec`:
 
@@ -57,8 +57,79 @@ more ECS-compatibility modes while still supporting older Logstash versions.
       end
     ~~~
 
+## Usage (advanced)
+
+Release 1.1 of this support gem includes support for constraining a plugin
+to only operate in specified ECS-Compatibility modes, and advanced support for
+runtime selectors that provide developers a way to provide alternate _values_
+during initialization based on the instantiated plugin's effective
+`ecs_compatibility` mode. This is helpful in plugins that define large field
+mappings, because it allows those mappings to be side-by-side where they are
+unlikely to diverge and introduce bugs.
+
+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.2'
+    end
+    ~~~
+
+2. In your plugin code, require this library and include it into your plugin class
+   that already inherits `LogStash::Plugin`, but this time specify which versions
+   of ECS your plugin supports:
+
+    ~~~ ruby
+    require 'logstash/plugin_mixins/ecs_compatibility_support'
+
+    class LogStash::Inputs::Foo < Logstash::Inputs::Base
+      include LogStash::PluginMixins::ECSCompatibilitySupport(:disabled,:v1)
+
+      # ...
+    end
+    ~~~
+
+   This prevents the plugin from being instantiated with an unsupported mode,
+   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`
+   method to define alternates in-line. At runtime, the correct value will be
+   selected based on the current effective `ecs_compatibility` mode.
+
+    ~~~ ruby
+      def register
+        @field_hostname = ecs_select[disabled: "hostname", v1: "[host][name]"]
+        @field_hostip   = ecs_select[disabled: "ip",       v1: "[host][ip]"  ]
+      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.
+
 ## Development
 
 This gem:
  - *MUST* remain API-stable at 1.x
- - *MUST NOT* introduce additional runtime dependencies
+ - *MUST NOT* introduce additional runtime dependencies

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

@@ -0,0 +1,167 @@
+# encoding: utf-8
+
+require_relative '../ecs_compatibility_support'
+
+module LogStash
+  module PluginMixins
+    module ECSCompatibilitySupport
+      # A `ECSCompatibilitySupport::Selector` is a `Module` that can be included into any `LogStash::Plugin`
+      # to constrain instances to a specific set of supported `ecs_compatibility` modes.
+      #
+      # It also provides an `ecs_select` that allows plugin developers to specify ECS alternatives
+      # in-line with their existing code.
+      #
+      # @api private
+      # @see ECSCompatibilitySupport()
+      class Selector < Module
+
+        ##
+        # @api internal (use: `LogStash::Plugin::include`)
+        # @param base [Class]: a class that inherits `LogStash::Plugin`, typically one
+        #                      descending from one of the four plugin base classes
+        #                      (e.g., `LogStash::Inputs::Base`)
+        # @return [void]
+        def included(base)
+          fail(ArgumentError, "`#{base}` must inherit LogStash::Plugin") unless base < LogStash::Plugin
+          base.include(ECSCompatibilitySupport)
+        end
+
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
+        ##
+        # @api private
+        # @see ECSCompatibilitySupport()
+        # @param 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
+
+          ##
+          # Hooks initialization to throw a configuration error if plugin is initialized with
+          # an unsupported `ecs_compatibility` mode.
+          # @method initialize
+          define_method(:initialize) do |*args|
+            super(*args) # Plugin#initialize
+
+            effective_ecs_mode = ecs_compatibility
+            if !ecs_modes_supported.include?(effective_ecs_mode)
+              message = "#{config_name} #{@plugin_type} plugin does not support `ecs_compatibility => #{effective_ecs_mode}`. "+
+                        "Supported modes are: #{ecs_modes_supported}"
+              fail(LogStash::ConfigurationError, message)
+            end
+            @_ecs_select = selector_module.state_for(effective_ecs_mode)
+          end
+
+          ##
+          # @method ecs_select
+          # @return [State]
+          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
+
+        ##
+        # @return [String]
+        def name
+          "#{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.
+        #
+        # It allows a developer to safely define mappings of alternative values, exactly
+        # one of which will be selected based on the effective mode.
+        #
+        # It is _NOT_ designed for performance, but may be helpful during  instantiation.
+        #
+        # @api private
+        class State
+          ##
+          # @api private -- Use Selector#state_for(current_value)
+          # @param supported_modes [Array<Symbol>]
+          # @param active_mode [Symbol]
+          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
+          attr_reader :supported_modes
+
+          # With the active mode, select one of the provided options.
+          # @param defined_choices [Hash{Symbol=>Object}]: the options to chose between.
+          #                        it is an `ArgumentError` to provide a different set of
+          #                        options than those this `State` was initialized with.
+          #                        This ensures that all reachable code implements all
+          #                        supported options.
+          # @return [Object]
+          def value_from(defined_choices)
+            fail(ArgumentError, "defined_choices must be a Hash") unless defined_choices.kind_of?(Hash)
+            fail(ArgumentError, "defined_choices cannot be empty") if defined_choices.empty?
+            fail(ArgumentError, "defined_choices must have Symbol keys") unless defined_choices.keys.all? { |k| k.kind_of?(Symbol) }
+
+            fail(ArgumentError, "at least one choice must be defined") if defined_choices.empty?
+
+            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?
+
+            # 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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require_relative 'selector'
+
+module LogStash
+  module PluginMixins
+    module ECSCompatibilitySupport
+      # The `SpecHelper` is meant to be extended into an rspec context to provide it with
+      # tools for vaidating the ecs_compatibility matrix.
+      #
+      # It creates one sub-context per provided mode, and yields a Selector::State
+      # to the provided block primed with the list of supported supported_modes and the active mode.
+      #
+      # It also memoizes an `ecs_compatibility` set to the active mode. It is up to the user
+      # to plumb this into the initialization of your plugin.
+      #
+      # ~~~ ruby
+      # require 'logstash/plugin_mixins/ecs_compatibility_support/spec_helper'
+      #
+      # describe YourClass, :ecs_compatibility_support
+      #   ecs_compatibility_matrix(:disabled, :v1) do |ecs_select|
+      #     context "#description" do
+      #       subject(:result) { instance.description }
+      #       it { is_expected.to eq ecs_select[disabled: "legacy", v1: "novel"] }
+      #     end
+      #   end
+      # end
+      # ~~~
+      module SpecHelper
+        def ecs_compatibility_matrix(*supported_modes,&block)
+          ecs_selector = Selector.new(*supported_modes)
+
+          ecs_selector.ecs_modes_supported.each do |active_mode|
+            context "`ecs_compatibility => #{active_mode}`" do
+              let(:ecs_compatibility) { active_mode }
+
+              ecs_select = ecs_selector.state_for(active_mode)
+              instance_exec(ecs_select, &block)
+            end
+          end
+        end
+      end
+
+      ::RSpec.configure { |c| c.extend(SpecHelper, :ecs_compatibility_support) } if defined?(::RSpec)
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+require_relative '../ecs_compatibility_support'
+
+module LogStash
+  module PluginMixins
+    module ECSCompatibilitySupport
+      # A target option check that can be included into any `LogStash::Plugin`.
+      #
+      # @see ECSCompatibilitySupport()
+      module TargetCheck
+        ##
+        # @api internal (use: `LogStash::Plugin::include`)
+        # @param base [Class]: a class that inherits `LogStash::Plugin`, typically one
+        #                      descending from one of the four plugin base classes
+        #                      (e.g., `LogStash::Inputs::Base`)
+        # @return [void]
+        def self.included(base)
+          fail(ArgumentError, "`#{base}` must inherit LogStash::Plugin") unless base < LogStash::Plugin
+          fail(ArgumentError, "`#{base}` must include #{ECSCompatibilitySupport}") unless base < ECSCompatibilitySupport
+          base.prepend(RegisterDecorator)
+        end
+
+        TARGET_NOT_SET_MESSAGE = ("ECS compatibility is enabled but `target` option was not specified. " +
+            "This may cause fields to be set at the top-level of the event where they are likely to clash with the Elastic Common Schema. " +
+            "It is recommended to set the `target` option to avoid potential schema conflicts (if your data is ECS compliant " +
+            "or non-conflicting, feel free to ignore this message)").freeze
+
+        private
+
+        ##
+        # Check whether `target` is specified.
+        #
+        # @return [nil] if target is unspecified and ECS compatibility is disabled
+        # @return [true, false]
+        def target_set?
+          return true unless target.nil?
+          return nil if ecs_compatibility == :disabled
+          false # target isn't set
+        end
+
+        module RegisterDecorator
+
+          ##
+          # Logs an info message when ecs_compatibility is enabled but plugin has no `target` configuration specified.
+          # @override
+          def register
+            super.tap do
+              logger.info(TARGET_NOT_SET_MESSAGE) if target_set? == false
+            end
+          end
+
+        end
+        private_constant :RegisterDecorator
+      end
+    end
+  end
+end

data/lib/logstash/plugin_mixins/ecs_compatibility_support.rb

@@ -17,9 +17,9 @@ module LogStash
     module ECSCompatibilitySupport
       ##
       # @api internal (use: `LogStash::Plugin::include`)
-      # @param: a class that inherits `LogStash::Plugin`, typically one
-      #         descending from one of the four plugin base classes (e.g.,
-      #         `LogStash::Inputs::Base`)
+      # @param base [Class]: a class that inherits `LogStash::Plugin`, typically one
+      #                      descending from one of the four plugin base classes
+      #                      (e.g., `LogStash::Inputs::Base`)
       # @return [void]
       def self.included(base)
         fail(ArgumentError, "`#{base}` must inherit LogStash::Plugin") unless base < LogStash::Plugin
@@ -100,5 +100,16 @@ module LogStash
         end
       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?
+
+      require_relative "ecs_compatibility_support/selector"
+      ECSCompatibilitySupport::Selector.new(*supported_versions)
+    end
   end
 end

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

@@ -0,0 +1,153 @@
+# encoding: utf-8
+
+require 'rspec/its'
+
+require "logstash-core"
+
+require 'logstash/inputs/base'
+require 'logstash/filters/base'
+require 'logstash/codecs/base'
+require 'logstash/outputs/base'
+
+require "logstash/plugin_mixins/ecs_compatibility_support/selector"
+
+describe LogStash::PluginMixins::ECSCompatibilitySupport::Selector do
+  context 'initialize' do
+    it 'rejects zero arguments' do
+      expect { described_class.new }.to raise_error(ArgumentError, /one or more/)
+    end
+    it 'rejects non-symbol arguments' do
+      expect { described_class.new("v1") }.to raise_error(ArgumentError, /symbol/)
+    end
+    it 'accepts one symbol argument'do
+      selector_mod = described_class.new(:disabled)
+      aggregate_failures do
+        expect(selector_mod.ecs_modes_supported).to contain_exactly(:disabled)
+        expect(selector_mod.name).to include('disabled')
+      end
+    end
+    it 'accepts many symbol arguments'do
+      selector_mod = described_class.new(:disabled, :v1)
+      aggregate_failures do
+        expect(selector_mod.ecs_modes_supported).to contain_exactly(:disabled, :v1)
+        expect(selector_mod.name).to include('disabled')
+        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 }
+    let(:selector_module) { described_class.new(:disabled,:v1) }
+    context 'that does not inherit from LogStash::Plugin' do
+      let(:plugin_class) { Class.new }
+      it 'fails with an ArgumentError' do
+        expect do
+          plugin_class.send(:include, selector_module)
+        end.to raise_error(ArgumentError, /LogStash::Plugin/)
+      end
+    end
+
+    [
+      LogStash::Inputs::Base,
+      LogStash::Filters::Base,
+      LogStash::Codecs::Base,
+      LogStash::Outputs::Base
+    ].each do |base_class|
+      context "that inherits from `#{base_class}`" do
+        let(:ecs_supported_modes) { [:disabled, :v1] }
+        let(:selector_module) { described_class.new(*ecs_supported_modes) }
+        let(:plugin_base_class) { base_class }
+        subject(:plugin_class) do
+          klass = Class.new(plugin_base_class) do
+            config_name 'test'
+          end
+          klass.send(:include, selector_module)
+          klass
+        end
+        context 'the result' do
+          its(:ancestors) { is_expected.to include(ecs_compatibility_support) }
+          its(:instance_methods) { is_expected.to include(:ecs_select) }
+        end
+        context '#ecs_select' do
+          let(:plugin_options) { Hash.new }
+          let(:plugin_instance) { plugin_class.new(plugin_options) }
+          let(:ecs_effective_mode) { :v1 }
+
+          before(:each) do
+            # occurs during initialization, before we can get a reference to the instance.
+            # our plugin_class is generated per-spec and not reused.
+            allow_any_instance_of(plugin_class).to receive(:ecs_compatibility).and_return(ecs_effective_mode)
+          end
+
+          subject(:ecs_select) { plugin_instance.ecs_select }
+
+          it { is_expected.to be_a_kind_of described_class::State }
+          it { is_expected.to respond_to :[] }
+
+          context 'when effective ecs_compatibility is not supported' do
+            let(:ecs_supported_modes) { [:disabled,:v1,:v2] }
+            let(:ecs_effective_mode) { :v3 }
+            it 'raises a configuration error' do
+              expect { plugin_instance.ecs_select }.to raise_error(LogStash::ConfigurationError)
+            end
+          end
+
+          context '#[]' do
+            it 'rejects empty options' do
+              expect { ecs_select[{}] }.to raise_error(ArgumentError, /empty/)
+            end
+            it 'rejects unknown options' do
+              expect { ecs_select[disabled: "nope", v1: "no", bananas: "monkey"] }.to raise_error(ArgumentError, /unknown/)
+            end
+            it 'rejects missing options' do
+              expect { ecs_select[disabled: "nope"] }.to raise_error(ArgumentError, /missing/)
+            end
+            it 'rejects non-hash options' do
+              expect { ecs_select["bananas"] }.to raise_error(ArgumentError, /Hash/)
+            end
+            it 'requires symbol keys' do
+              expect { ecs_select["bananas"=>"apes"] }.to raise_error(ArgumentError, /Symbol keys/)
+            end
+            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
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+require 'rspec/its'
+
+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,: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,:v8) }
+        its(:active_mode) { is_expected.to be ecs_compatibility }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# encoding: utf-8
+
+require "logstash-core"
+
+require 'logstash/inputs/base'
+require 'logstash/filters/base'
+require 'logstash/codecs/base'
+require 'logstash/outputs/base'
+
+require "logstash/plugin_mixins/ecs_compatibility_support/target_check"
+
+describe LogStash::PluginMixins::ECSCompatibilitySupport::TargetCheck do
+
+  describe "check_target_set_in_ecs_mode" do
+
+    context 'with a plugin' do
+
+      subject(:plugin_class) do
+        Class.new(LogStash::Filters::Base) do
+          include LogStash::PluginMixins::ECSCompatibilitySupport
+          include LogStash::PluginMixins::ECSCompatibilitySupport::TargetCheck
+
+          config :target, :validate => :string
+
+          def register; 42 end
+
+        end
+      end
+
+      it 'skips check when ECS disabled' do
+        plugin = plugin_class.new('ecs_compatibility' => 'disabled')
+        allow( plugin.logger ).to receive(:info)
+        expect( plugin.register ).to eql 42
+        expect( plugin.logger ).to_not have_received(:info).with(a_string_including "`target` option")
+      end
+
+      it 'warns when target is not set in ECS mode' do
+        plugin = plugin_class.new('ecs_compatibility' => 'v1')
+        allow( plugin.logger ).to receive(:info)
+        expect( plugin.register ).to eql 42
+        expect( plugin.logger ).to have_received(:info).with(a_string_including "ECS compatibility is enabled but `target` option was not specified.")
+      end
+
+      it 'does not warn when target is set' do
+        plugin = plugin_class.new('ecs_compatibility' => 'v1', 'target' => 'foo')
+        allow( plugin.logger ).to receive(:info)
+        expect( plugin.register ).to eql 42
+        expect( plugin.logger ).to_not have_received(:info).with(a_string_including "`target` option")
+      end
+
+    end
+
+    it 'fails check when no target config' do
+      plugin_class = Class.new(LogStash::Filters::Base) do
+        include LogStash::PluginMixins::ECSCompatibilitySupport
+        include LogStash::PluginMixins::ECSCompatibilitySupport::TargetCheck
+
+        def register; end
+
+      end
+      plugin = plugin_class.new('ecs_compatibility' => 'v1')
+      expect { plugin.register }.to raise_error NameError, /\btarget\b/
+    end
+
+  end
+
+end

data/spec/logstash/plugin_mixins/ecs_compatibility_support_spec.rb

@@ -142,3 +142,25 @@ describe LogStash::PluginMixins::ECSCompatibilitySupport do
   end
 end
 
+describe 'LogStash::PluginMixins::ECSCompatibilitySupport()' do
+  context 'with no arguments' do
+    it 'returns LogStash::PluginMixins::ECSCompatibilitySupport' do
+      expect(LogStash::PluginMixins::ECSCompatibilitySupport()).to eq(LogStash::PluginMixins::ECSCompatibilitySupport)
+    end
+  end
+  context 'with symbol arguments' do
+    it 'returns a properly-configured LogStash::PluginMixins::ECSCompatibilitySupport::Selector' do
+      selector_module = LogStash::PluginMixins::ECSCompatibilitySupport(:disabled,:v1)
+      expect(selector_module).to be_a_kind_of(LogStash::PluginMixins::ECSCompatibilitySupport::Selector)
+      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,21 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: logstash-mixin-ecs_compatibility_support
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.3.0
 platform: java
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-09 00:00:00.000000000 Z
+date: 2021-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 6.0.0
   name: logstash-core
   prerelease: false
   type: :runtime
@@ -23,7 +23,21 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: logstash-devutils
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
     requirements:
@@ -80,6 +94,12 @@ files:
 - LICENSE
 - README.md
 - lib/logstash/plugin_mixins/ecs_compatibility_support.rb
+- lib/logstash/plugin_mixins/ecs_compatibility_support/selector.rb
+- lib/logstash/plugin_mixins/ecs_compatibility_support/spec_helper.rb
+- lib/logstash/plugin_mixins/ecs_compatibility_support/target_check.rb
+- spec/logstash/plugin_mixins/ecs_compatibility_support/selector_spec.rb
+- spec/logstash/plugin_mixins/ecs_compatibility_support/spec_helper_spec.rb
+- spec/logstash/plugin_mixins/ecs_compatibility_support/target_check_spec.rb
 - spec/logstash/plugin_mixins/ecs_compatibility_support_spec.rb
 homepage: https://github.com/logstash-plugins/logstash-mixin-ecs_compatibility_support
 licenses:
@@ -101,10 +121,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project:
-rubygems_version: 2.6.11
+rubygems_version: 2.6.13
 signing_key:
 specification_version: 4
 summary: Support for the ECS-Compatibility mode introduced in Logstash 7.x, for plugins
   wishing to use this API on older Logstashes
 test_files:
+- spec/logstash/plugin_mixins/ecs_compatibility_support/selector_spec.rb
+- spec/logstash/plugin_mixins/ecs_compatibility_support/spec_helper_spec.rb
+- spec/logstash/plugin_mixins/ecs_compatibility_support/target_check_spec.rb
 - spec/logstash/plugin_mixins/ecs_compatibility_support_spec.rb