logstash-mixin-ecs_compatibility_support 1.0.0-java → 1.1.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba10e5399ac0d62b035fb98cbb351e9e3c2cc857a25fa541a18998072e40b20c
-  data.tar.gz: e303a40b0d20f12de4bf57639957c59f12ca30db8e568b99136863e2246e3480
+  metadata.gz: '08a8069171fd7a69e9adec65ef751e693ef6a3979e7d9b6346773f880d07a753'
+  data.tar.gz: 7ff7dc6c1bbabc1db323e253dc2c7e99bd7e08b701b59ce3e69bda5dc2c3012d
 SHA512:
-  metadata.gz: 65f069880870f66b57b018108fad026d440d665a8fc06fc49c14aeeca1f3e8c4c93e1abfbb2227e2bb87a61a85d8c6bdf220c4efb093e4781f398f5c4334a6da
-  data.tar.gz: 9281a716c7101934d7803baf628b165cfed31716517eeaa8043e585710cb8ade34799b47891ef5679cfaa1342bbc79c107a52187178edf1873c50b77f125624b
+  metadata.gz: 732274d0877f02583087f9181e862c8ce47c4eb8a8c8aba42557b5e149e3d17cfdabb5b23c240107c38194f730511f107084fe4d5ba2bd376fb56b36382ba811
+  data.tar.gz: d80b1895da371395f72dab57cb2cb61f858f68d9a0a001416ab7406ebb94c4ba9fbe74efeab7adc9e22ae7be50a2c58f7b628aa1c3de7e1bcac823a0cbd74865

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,62 @@ 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.1` 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'
+    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.
+
+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
+    ~~~
+
+   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.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,12 @@ module LogStash
         end
       end
     end
+
+    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/lib/logstash/plugin_mixins/ecs_compatibility_support/selector.rb

@@ -0,0 +1,118 @@
+# 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
+
+        ##
+        # @api private
+        # @see ECSCompatibilitySupport()
+        # @param ecs_modes_supported
+        def initialize(*ecs_modes_supported)
+          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) }
+
+          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 = State.new(ecs_modes_supported, effective_ecs_mode)
+          end
+
+          ##
+          # @method ecs_select
+          # @return [State]
+          define_method(:ecs_select) { @_ecs_select }
+
+          define_singleton_method(:ecs_modes_supported) { ecs_modes_supported }
+        end
+
+        ##
+        # @return [String]
+        def name
+          "#{Selector}(#{ecs_modes_supported.join(',')})"
+        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
+          # @param supported_modes [Array<Symbol>]
+          # @param active_mode [Symbol]
+          def initialize(supported_modes, active_mode)
+            @supported_modes = supported_modes
+            @active_mode = active_mode
+          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
+            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)
+          end
+          alias_method :[], :value_from
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# 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)
+          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
+
+          supported_modes.each do |active_mode|
+            context "`ecs_compatibility => #{active_mode}`" do
+              let(:ecs_compatibility) { active_mode }
+
+              ecs_select = Selector::State.new(supported_modes, 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/spec/logstash/plugin_mixins/ecs_compatibility_support/selector_spec.rb

@@ -0,0 +1,119 @@
+# 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
+  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
+          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) 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(:active_mode) { is_expected.to be ecs_compatibility }
+      end
+    end
+  end
+end

data/spec/logstash/plugin_mixins/ecs_compatibility_support_spec.rb

@@ -142,3 +142,18 @@ 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
+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.1.0
 platform: java
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-09 00:00:00.000000000 Z
+date: 2021-01-25 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,10 @@ 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
+- 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_spec.rb
 homepage: https://github.com/logstash-plugins/logstash-mixin-ecs_compatibility_support
 licenses:
@@ -101,10 +119,12 @@ 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_spec.rb