Feat: introduce a target check helper

CHANGELOG.md

@@ -1,3 +1,6 @@
+# 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.
 

lib/logstash/plugin_mixins/ecs_compatibility_support/target_check.rb

@@ -0,0 +1,46 @@
+# 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.method_defined?(:ecs_compatibility)
+        end
+
+        TARGET_NOT_SET_MESSAGE = ("ECS compatibility is enabled but no `target` option was specified, " +
+            "it is recommended to set the option to avoid potential schema conflicts (if your data is ECS compliant " +
+            "or non-conflicting feel free to ignore this message)").freeze
+
+        private
+
+        ##
+        # Logs an info message when ecs_compatibility is enabled but plugin has no `target` configuration specified.
+        # @note This method assumes a common plugin convention of using the target option.
+        # @return [nil] if ECS compatibility is disabled or no target option exists
+        # @return [true, false]
+        def check_target_set_in_ecs_mode
+          return if ecs_compatibility == :disabled || !respond_to?(:target)
+          if target.nil?
+            logger.info(TARGET_NOT_SET_MESSAGE)
+            return false
+          end
+          true
+        end
+
+      end
+    end
+  end
+end

logstash-mixin-ecs_compatibility_support.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'logstash-mixin-ecs_compatibility_support'
-  s.version       = '1.2.0'
+  s.version       = '1.3.0'
   s.licenses      = %w(Apache-2.0)
   s.summary       = "Support for the ECS-Compatibility mode introduced in Logstash 7.x, for plugins wishing to use this API on older Logstashes"
   s.description   = "This gem is meant to be a dependency of any Logstash plugin that wishes to use the ECS-Compatibility mode introduced in Logstash 7.x while maintaining backward-compatibility with earlier Logstash releases. When used on older Logstash versions, this adapter provides an implementation of ECS-Compatibility mode that can be controlled at the plugin instance level."

spec/logstash/plugin_mixins/ecs_compatibility_support/target_check_spec.rb

@@ -0,0 +1,62 @@
+# 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
+            check_target_set_in_ecs_mode
+          end
+        end
+      end
+
+      it 'skips check when ECS disabled' do
+        plugin = plugin_class.new('ecs_compatibility' => 'disabled')
+        expect( plugin.register ).to be nil
+      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 be false
+        expect( plugin.logger ).to have_received(:info).with(/ECS compatibility is enabled but no `target` option was 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 be true
+        expect( plugin.logger ).to_not have_received(:info)
+      end
+
+    end
+
+    it 'skips check when no target config' do
+      plugin_class = Class.new(LogStash::Filters::Base) do
+        include LogStash::PluginMixins::ECSCompatibilitySupport
+        include LogStash::PluginMixins::ECSCompatibilitySupport::TargetCheck
+      end
+      expect( plugin_class.new({}).send(:check_target_set_in_ecs_mode) ).to be nil
+    end
+
+  end
+
+end