logstash-mixin-event_support 1.0.0-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 233ecb7e5843d824206f80593bbf24a22e21a8d5975eef777db50b3ebfddc498
+  data.tar.gz: 932f4b6b548e0e60e2fa73afcf9997f1dba7670444cbd7f25b05917ca6798fa8
+SHA512:
+  metadata.gz: a4656f34606801300aad4e2b28c57c1765c841dd93b896402e5dc423007801f9725a520a1bce4d90a8c43b1a4b5cd0aa33c72d7304a9f8a5140e96d3f8201e9e
+  data.tar.gz: 8fbae0b280cd5913e9316e4bbf0f90301f808666c3b44dc373d972e1d66d3b0f08e3ede83856c166ecc14b8e95094e57d49adece3e56cf96c7c30def745260b8

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2020 Elastic N.V. <http://www.elastic.co>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,45 @@
+# Event Support Mixin
+
+[![Build Status](https://travis-ci.com/logstash-plugins/logstash-mixin-event_support.svg?branch=master)](https://travis-ci.com/logstash-plugins/logstash-mixin-event_support)
+
+
+## Usage
+
+1. Add this gem as a runtime dependency of your Logstash plugin's `gemspec`:
+
+    ~~~ ruby
+    Gem::Specification.new do |s|
+      # ...
+
+      s.add_runtime_dependency 'logstash-mixin-event_support'
+    end
+    ~~~
+
+2. In your plugin code, require this library and include it into your plugin class
+   that already inherits `LogStash::Plugin`:
+
+    ~~~ ruby
+    require 'logstash/plugin_mixins/event_support/event_factory_adapter'
+
+    class LogStash::Codecs::Bar < Logstash::Codecs::Base
+
+      include LogStash::PluginMixins::EventSupport::EventFactoryAdapter
+   
+      # an optional mixin to provide `events_from_json` using the factory :
+      #include LogStash::PluginMixins::EventSupport::FromJsonHelper
+   
+      def decode(data, &block)
+        payload = extract_bar(data) # ...
+        yield event_factory.new_event(payload)
+      end
+   
+      # def extract_bar(data) ...
+   
+    end
+    ~~~
+
+## Development
+
+This gem:
+ - *MUST* remain API-stable at 1.x
+ - *MUST NOT* introduce additional runtime dependencies

data/lib/logstash/plugin_mixins/event_support.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+
+require 'logstash/namespace'
+require 'logstash/plugin'
+
+module LogStash
+  module PluginMixins
+    module EventSupport
+      # @see LogStash::PluginMixins::EventSupport::EventFactoryAdapter
+    end
+  end
+end

data/lib/logstash/plugin_mixins/event_support/event_factory_adapter.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'logstash/plugin_mixins/event_support'
+
+require 'logstash-core'
+require 'logstash/plugin'
+
+module LogStash
+  module PluginMixins
+    module EventSupport
+      module EventFactoryAdapter
+
+        ##
+        # @api internal
+        # @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`)
+        # @raise [ArgumentError]
+        # @return [void]
+        def self.included(base)
+          fail(ArgumentError, "`#{base}` must inherit LogStash::Plugin") unless base < LogStash::Plugin
+
+          if defined? LogStash::Plugins::EventFactorySupport
+            core_event_support = LogStash::Plugins::EventFactorySupport
+            fail(ArgumentError, "`#{base}` should include #{core_event_support}") unless base < core_event_support
+          else
+            unless const_defined?(:FallbackImpl)
+              require_relative 'event_factory_adapter/fallback_impl'
+              private_constant :FallbackImpl
+            end
+            base.send(:include, FallbackImpl)
+          end
+        end
+
+        ##
+        # @api private
+        #
+        # @param base [Object]
+        # @raise [ArgumentError]
+        def self.extended(base)
+          fail(ArgumentError, "`#{self}` cannot be extended into an existing object (#{base.inspect})")
+        end
+
+      end
+    end
+  end
+end

data/lib/logstash/plugin_mixins/event_support/event_factory_adapter/fallback_impl.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+module LogStash::PluginMixins::EventSupport::EventFactoryAdapter::FallbackImpl
+
+  # The event_factory method is effectively final and should not be re-defined by plugins.
+  #
+  # @return an event factory object with a `new_event(Hash)` API
+  def event_factory
+    @_event_factory ||= BasicEventFactory::INSTANCE
+  end
+
+  # The `targeted_event_factory` method is effectively final and should not be re-defined.
+  # If the plugin defines a `target => ...` option than this method will return a factory
+  # that respects the set target, otherwise (no target) returns {#event_factory}.
+  #
+  # @return an event factory object with a `new_event(Hash)` API
+  def targeted_event_factory
+    @_targeted_event_factory ||= begin # not synchronized - fine to initialize twice
+                                   raise ArgumentError.new('config(:target) not present') unless respond_to?(:target)
+                                   target.nil? ? event_factory : TargetedEventFactory.new(event_factory, target)
+                                 end
+  end
+
+  private
+
+  class BasicEventFactory
+    INSTANCE = new
+
+    # @param payload [Hash]
+    # @return [LogStash::Event]
+    def new_event(payload = {})
+      LogStash::Event.new(payload)
+    end
+
+  end
+  private_constant :BasicEventFactory
+
+  class TargetedEventFactory
+
+    def initialize(inner, target)
+      @delegate = inner
+      @target = target # TODO validate
+    end
+
+    # @param payload [Hash]
+    # @return [LogStash::Event]
+    def new_event(payload = {})
+      event = @delegate.new_event
+      event.set(@target, payload)
+      event
+    end
+
+  end
+  private_constant :TargetedEventFactory
+
+end

data/lib/logstash/plugin_mixins/event_support/from_json_helper.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'logstash/plugin_mixins/event_support'
+require 'logstash/plugin_mixins/event_support/event_factory_adapter'
+
+require 'logstash-core'
+require 'logstash/event'
+
+module LogStash
+  module PluginMixins
+    module EventSupport
+      module FromJsonHelper
+
+        def self.included(base)
+          if defined? LogStash::Plugins::EventFactorySupport # native support from LS core
+            base.send(:include, NativeImpl)
+          else
+            require 'logstash/json'
+            base.send(:include, FallbackImpl)
+          end
+        end
+
+        module NativeImpl
+
+          def events_from_json(json, event_factory)
+            LogStash::Event.from_json(json) { |data| event_factory.new_event(data) }
+          end
+
+        end
+        private_constant :NativeImpl
+
+        module FallbackImpl
+
+          def events_from_json(json, event_factory)
+            decoded = LogStash::Json.load(json)
+            case decoded
+            when Array then decoded.map { |data| event_factory.new_event(data) }
+            when Hash  then [ event_factory.new_event(decoded) ]
+            else raise LogStash::Json::ParserError.new("JSON must contain array or hash, got #{decoded.class}")
+            end
+          end
+
+        end
+        private_constant :FallbackImpl
+
+      end
+    end
+  end
+end

data/spec/logstash/plugin_mixins/event_support/event_factory_adapter_spec.rb

@@ -0,0 +1,140 @@
+require_relative '../../spec_helper'
+
+require "logstash/plugin_mixins/event_support/event_factory_adapter"
+
+require 'logstash/inputs/base'
+require 'logstash/filters/base'
+require 'logstash/codecs/base'
+require 'logstash/outputs/base'
+
+describe LogStash::PluginMixins::EventSupport::EventFactoryAdapter do
+  let(:event_factory_adapter) { described_class }
+
+  context 'included into a class' do
+
+    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, described_class)
+        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
+
+        # native_event_factory_support = base_class.method_defined?(:event_factory)
+
+        let(:plugin_base_class) { base_class }
+
+        subject(:plugin_class) do
+          Class.new(plugin_base_class) do
+            config_name 'sample'
+          end
+        end
+
+        describe 'the result' do
+
+          before(:each) do
+            plugin_class.send(:include, described_class)
+          end
+
+          it 'defines an `event_factory` method' do
+            expect(plugin_class.method_defined?(:event_factory)).to be true
+          end
+
+          it 'defines an `targeted_event_factory` method' do
+            expect(plugin_class.method_defined?(:targeted_event_factory)).to be true
+          end
+
+          let(:options) { Hash.new }
+          let(:plugin) { plugin_class.new(options) }
+
+          shared_examples 'an event factory' do
+
+            it 'returns an event' do
+              expect( event_factory.new_event ).to be_a LogStash::Event
+              expect( event = event_factory.new_event('foo' => 'bar') ).to be_a LogStash::Event
+              expect( event.get('foo') ).to eql 'bar'
+            end
+
+          end
+
+          describe 'event_factory' do
+
+            subject(:event_factory) { plugin.send(:event_factory) }
+
+            it_behaves_like 'an event factory'
+
+            it 'memoizes the factory instance' do
+              expect( event_factory ).to be plugin.send(:event_factory)
+            end
+
+          end
+
+          describe 'targeted_event_factory (no config :target option)' do
+
+            it 'raises an error' do
+              expect { plugin.send(:targeted_event_factory) }.to raise_error(ArgumentError, /target/)
+            end
+
+          end
+
+          describe 'targeted_event_factory' do
+
+            subject(:plugin_class) do
+              Class.new(plugin_base_class) do
+                config_name 'sample'
+                config :target, :validate => :string
+              end
+            end
+
+            subject(:targeted_event_factory) { plugin.send(:targeted_event_factory) }
+
+            it_behaves_like 'an event factory' do
+              subject(:event_factory) { targeted_event_factory }
+            end
+
+            it 'memoizes the factory instance' do
+              expect( targeted_event_factory ).to be plugin.send(:targeted_event_factory)
+            end
+
+            it 'uses the basic event factory (no target specified)' do
+              expect( targeted_event_factory ).to be plugin.send(:event_factory)
+            end
+
+            context 'with target' do
+
+              let(:options) { super().merge('target' => '[the][baz]') }
+
+              it 'returns an event' do
+                expect( targeted_event_factory.new_event ).to be_a LogStash::Event
+                expect( event = targeted_event_factory.new_event('foo' => 'bar') ).to be_a LogStash::Event
+                expect( event.include?('foo') ).to be false
+                expect( event.get('[the][baz][foo]') ).to eql 'bar'
+              end
+
+              it 'memoizes the factory instance' do
+                expect( targeted_event_factory ).to be plugin.send(:targeted_event_factory)
+              end
+
+              it 'uses a different factory from the basic one' do
+                expect( targeted_event_factory ).not_to be plugin.send(:event_factory)
+              end
+
+            end
+          end
+
+        end
+      end
+    end
+
+  end
+end

data/spec/logstash/plugin_mixins/event_support/from_json_helper_spec.rb

@@ -0,0 +1,70 @@
+require_relative '../../spec_helper'
+
+require "logstash/plugin_mixins/event_support/from_json_helper"
+
+require 'logstash/inputs/base'
+require 'logstash/filters/base'
+require 'logstash/codecs/base'
+require 'logstash/outputs/base'
+
+describe LogStash::PluginMixins::EventSupport::FromJsonHelper do
+
+  context 'included into a class' do
+
+    [
+        LogStash::Inputs::Base,
+        LogStash::Filters::Base,
+        LogStash::Codecs::Base,
+
+    ].each do |base_class|
+
+      context "that inherits from `#{base_class}`" do
+
+        subject(:plugin_class) do
+          Class.new(base_class) do
+            config_name 'sample'
+
+            include LogStash::PluginMixins::EventSupport::FromJsonHelper
+          end
+        end
+
+        let(:options) { Hash.new }
+        let(:plugin) { plugin_class.new(options) }
+
+        let(:event_factory) { double('event_factory') }
+
+        it 'parses valid json' do
+          expect( event_factory ).to receive(:new_event) { |data| LogStash::Event.new('test' => data) }
+
+          events = plugin.events_from_json('{ "foo": "bar" }', event_factory)
+          expect( events.size ).to eql 1
+          expect( event = events.first ).to be_a LogStash::Event
+          expect( event.get('[test]') ).to eql 'foo' => 'bar'
+        end
+
+        it 'parses multi json' do
+          expect( event_factory ).to receive(:new_event) { |data| LogStash::Event.new('test' => data) }.twice
+
+          events = plugin.events_from_json('[ {"foo": "bar"}, { "baz": 42.0 } ]', event_factory)
+          expect( events.size ).to eql 2
+          expect( events[0].get('[test]') ).to eql 'foo' => 'bar'
+          expect( events[1].get('[test]') ).to eql 'baz' => 42.0
+        end
+
+        it 'raises on unexpected json' do
+          expect { plugin.events_from_json(' "42" ', event_factory) }.to raise_error(LogStash::Json::ParserError)
+        end
+
+        it 'raises on invalid json' do
+          expect { plugin.events_from_json('{ "" }', event_factory) }.to raise_error(LogStash::Json::ParserError)
+        end
+        
+        it 'raises on incomplete json' do
+          expect { plugin.events_from_json('{"answer":"42"', event_factory) }.to raise_error(LogStash::Json::ParserError)
+        end
+
+      end
+
+    end
+  end
+end

data/spec/logstash/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rspec'
+
+require "logstash-core"

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: logstash-mixin-event_support
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: java
+authors:
+- Elastic
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.8'
+  name: logstash-core
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.8'
+- !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:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: logstash-codec-plain
+  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:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  name: rspec
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+description:
+email: info@elastic.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/logstash/plugin_mixins/event_support.rb
+- lib/logstash/plugin_mixins/event_support/event_factory_adapter.rb
+- lib/logstash/plugin_mixins/event_support/event_factory_adapter/fallback_impl.rb
+- lib/logstash/plugin_mixins/event_support/from_json_helper.rb
+- spec/logstash/plugin_mixins/event_support/event_factory_adapter_spec.rb
+- spec/logstash/plugin_mixins/event_support/from_json_helper_spec.rb
+- spec/logstash/spec_helper.rb
+homepage: https://github.com/logstash-plugins/logstash-mixin-event_support
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.6.13
+signing_key:
+specification_version: 4
+summary: Event support for Logstash plugins
+test_files:
+- spec/logstash/plugin_mixins/event_support/event_factory_adapter_spec.rb
+- spec/logstash/plugin_mixins/event_support/from_json_helper_spec.rb
+- spec/logstash/spec_helper.rb