logstash-mixin-validator_support 1.0.1-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5e8b335df368ec737d61dcb43db27b9876979758c615b69ade06865a973e8b8
+  data.tar.gz: b8668657d6af8402ed487f959750d03d49156d22f52304b4c463a8a7e0d1214f
+SHA512:
+  metadata.gz: 48b38367a6d71c35ad0fa8d65c898e01f13ef54c8e018259c01d7b620b43398d421735b853699b813af40630f60730a1ad34fc83ba1b57ea2d277781e5a2056e
+  data.tar.gz: a6953c1504f89a087df7b9ffd890c8dc8db21cca1665eafed30c39d514c763315d77733637d0dc7a0fb710f25aec2c47da929c04e82f844588b6e9ceed8afc6d

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# v1.0.0
+
+ - Introduces plugin parameter validation adapters, including initial backport for `:field_reference` validator.

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,63 @@
+# Validator Support Mixin
+
+This gem provides back-ports of new validators that have been added to Logstash
+core. By using this support adapter, plugin developers can use newly-introduced
+validators without constraining the versions of Logstash on which their plugin
+can run.
+
+When a plugin using this adapter runs on a version of Logstash that does _not_
+provide the named validator, the back-ported validator provided by this adapter
+is used instead.
+
+## Usage
+
+1. Add this gem as a runtime dependency of your plugin. To avoid conflicts with
+   other plugins, you should always use the [pessimistic operator][] `~>` to
+   match the minimum `1.x` that provides the back-ports you intend to use:
+
+    ~~~ ruby
+    Gem::Specification.new do |s|
+      # ...
+
+      s.add_runtime_dependency 'logstash-mixin-validator_support', '~>1.0'
+    end
+    ~~~
+
+2. In your plugin code, require this library and extend one or more of the
+   provided validators into your plugin. For example, to use the
+   `:field_reference` validator introduced in Logstash 7.11:
+
+    ~~~ ruby
+    require 'logstash/plugin_mixins/validator_support/field_reference_validation_adapter'
+
+    class LogStash::Inputs::Foo < Logstash::Inputs::Base
+      extend LogStash::PluginMixins::ValidatorSupport::FieldReferenceValidationAdapter
+
+      # ...
+    end
+    ~~~
+
+3. Use the validator as normal when defining config options; your plugin does
+   not need to know whether the validator was provided by Logstash core or by
+   this gem.
+
+    ~~~ ruby
+      config :target, :validate => :field_reference
+    ~~~
+
+## Development
+
+This gem:
+ - *MUST* remain API-stable at 1.x
+ - *MUST NOT* introduce additional runtime dependencies
+
+When developing back-ports, sometimes it may not be possible to provide a
+verbatim validation. In these cases, developers should err on the side of the
+back-port accepting input that the core implementation may consider invalid.
+
+Each time a new validator is added, the runtime dependency of this library on
+Logstash core should be updated to require a minimium of the OLDEST supported
+release. This allows plugins using this adapter to supply patch-level fixes to
+any supported Logstash version without maintaining multiple branches.
+
+[pessimistic operator]: https://thoughtbot.com/blog/rubys-pessimistic-operator

data/lib/logstash/plugin_mixins/validator_support.rb

@@ -0,0 +1,100 @@
+# encoding: utf-8
+
+require 'logstash/version'
+require 'logstash/namespace'
+
+module LogStash
+  module PluginMixins
+    module ValidatorSupport
+
+      ##
+      # @api internal
+      #
+      # @param base [#validate_value]
+      # @param validator_name [Symbol]
+      def self.native?(base, validator_name)
+        native_is_valid, native_coerced_or_error = base.validate_value(nil, validator_name)
+
+        native_is_valid || !native_coerced_or_error.start_with?('Unknown validator')
+      end
+
+      ##
+      # A NamedValidationAdapter is a module that can be mixed into a Logstash
+      # plugin to ensure the named validator is present and available, whether
+      # provided by Logstash core or approximated with the provided backport
+      # implementation.
+      #
+      # @api internal
+      #
+      class NamedValidationAdapter < Module
+        ##
+        # Create a new named validation adapter, to approximate the implementation
+        # of a named validation that exists in Logstash Core.
+        #
+        # @api private
+        #
+        # @param validator_name [Symbol]
+        # @yieldparam value [Hash,Array]
+        # @yieldreturn [true, Object]:  validation success returns true with coerced value (see: ValidationResult#success)
+        # @yieldreturn [false, String]: validation failure returns false with error message (see: ValidationResult#failure)
+        def initialize(validator_name, &validator_implementation)
+          fail(ArgumentError, '`validator_name` must be a Symbol')         unless validator_name.kind_of?(Symbol)
+          fail(ArgumentError, '`validator_implementation` block required') unless validator_implementation
+
+          define_singleton_method(:validate, &validator_implementation)
+          define_singleton_method(:name) { "#{NamedValidationAdapter}(#{validator_name})" }
+
+          define_singleton_method(:extended) do |base|
+            # Only include the interceptor if support is not natively provided.
+            unless ValidatorSupport.native?(base, validator_name)
+              interceptor = NamedValidationInterceptor.new(validator_name, self)
+              base.extend(interceptor)
+            end
+          end
+        end
+      end
+
+      ##
+      # A NamedValidationInterceptor intercepts requests to validate input with the given
+      # name and instead substitutes its own implementation. This implementation will
+      # override Logstash core functionality.
+      #
+      # @api private
+      #
+      class NamedValidationInterceptor < Module
+        ##
+        # @param validator_name [Symbol]
+        # @param validator [#validate]
+        def initialize(validator_name, validator)
+          fail(ArgumentError, '`validator_name` must be a Symbol')          unless validator_name.kind_of?(Symbol)
+          fail(ArgumentError, '`validator` must respond to `\#{validate}`') unless validator.respond_to?(:validate)
+
+          define_method(:validate_value) do |value, required_validator|
+            if required_validator != validator_name
+              super(value, required_validator)
+            else
+              value = deep_replace(value)
+              value = hash_or_array(value)
+
+              validator.validate(value)
+            end
+          end
+
+          define_singleton_method(:name) { "#{NamedValidationInterceptor}(#{validator_name})" }
+        end
+      end
+
+      ##
+      # Helper functions for returning success and failure tuples
+      module ValidationResult
+        def self.success(coerced_value)
+          [true, coerced_value]
+        end
+
+        def self.failure(error_message)
+          [false, error_message]
+        end
+      end
+    end
+  end
+end

data/lib/logstash/plugin_mixins/validator_support/field_reference_validation_adapter.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+require 'logstash/plugin_mixins/validator_support'
+
+module LogStash
+  module PluginMixins
+    module ValidatorSupport
+      field_name = /[^\[\]]+/                                     # anything but brackets
+      path_fragment = /\[#{field_name}\]/                         # bracket-wrapped field name
+      field_reference_literal = /#{path_fragment}+/               # one or more path fragments
+      embedded_field_reference = /\[#{field_reference_literal}\]/ # bracket-wrapped field reference literal
+      composite_field_reference = /#{Regexp.union(path_fragment, embedded_field_reference)}+/
+
+      # anchored pattern matching either a stand-alone field name, or a composite field reference
+      field_reference_pattern = /\A#{Regexp.union(field_name,composite_field_reference)}\z/
+
+      FieldReferenceValidationAdapter = NamedValidationAdapter.new(:field_reference) do |value|
+        break ValidationResult.failure("Expected exactly one field reference, got `#{value.inspect}`") unless value.kind_of?(Array) && value.size <= 1
+        break ValidationResult.success(nil) if value.empty? || value.first.nil?
+
+        candidate = value.first
+
+        break ValidationResult.failure("Expected a valid field reference, got `#{candidate.inspect}`") unless field_reference_pattern =~ candidate
+
+        break ValidationResult.success(candidate)
+      end
+    end
+  end
+end

data/spec/logstash/plugin_mixins/validator_support/field_reference_validation_adapter_spec.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+require 'logstash/plugin_mixins/validator_support/field_reference_validation_adapter'
+
+describe LogStash::PluginMixins::ValidatorSupport::FieldReferenceValidationAdapter do
+  it 'is an instance of NamedValidationAdapter' do
+    expect(described_class).to be_a_kind_of LogStash::PluginMixins::ValidatorSupport::NamedValidationAdapter
+  end
+
+  context '#validate' do
+    [
+      ['@timestamp'],
+      ['[@timestamp]'],
+      ['[@metadata][ssl]'],
+      ['[link][0]'],
+      ['one'],
+      ['[fruit][[bananas][oranges]]'],
+      [],
+      [nil]
+    ].each do |candidate|
+      context "valid input `#{candidate.inspect}`" do
+        it 'correctly reports the value as valid', :aggregate_failures do
+          is_valid_result, coerced_or_error = described_class.validate(candidate)
+
+          expect(is_valid_result).to be true
+          expect(coerced_or_error).to eq candidate.first
+        end
+      end
+    end
+
+    [
+      ['link[0]'],
+      ['][N\\//\\L][D'],
+      ["one","two"],
+      {"this" => "that"},
+      ['[fruit][bananas[oranges]]'],
+    ].each do |candidate|
+      let(:candidate) { candidate }
+
+      context "invalid input `#{candidate.inspect}`" do
+        it 'correctly reports the value as invalid', :aggregate_failures do
+          is_valid_result, coerced_or_error = described_class.validate(candidate)
+
+          expect(is_valid_result).to be false
+          expect(coerced_or_error).to be_a_kind_of String
+          expect(coerced_or_error).to_not include('Unknown validator')
+          expect(coerced_or_error).to include('field reference')
+        end
+      end
+    end
+  end
+end

data/spec/logstash/plugin_mixins/validator_support_spec.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+require "logstash/devutils/rspec/spec_helper"
+
+require 'logstash/plugin_mixins/validator_support'
+
+require 'securerandom'
+
+describe LogStash::PluginMixins::ValidatorSupport::NamedValidationAdapter do
+  context 'an adapter re-defining a named validator that exists in Logstash core' do
+    let(:adapter) { described_class.new(:string) { |value| [false, 'intentional failure'] } }
+    let(:plugin_class) { Class.new(LogStash::Plugin) }
+    before(:each) { plugin_class.extend(adapter) }
+    context '#validate_value' do
+      it 'does not intercept validation' do
+        expect(adapter).to_not receive(:validate)
+
+        result = plugin_class.validate_value("banana", :string)
+
+        expect(result).to be_a_kind_of(Array)
+        expect(result.size).to eq(2)
+
+        expect(result[0]).to eq true
+        expect(result[1]).to eq 'banana'
+      end
+    end
+  end
+
+  context 'an adapter defining a named validator that does not exist in Logstash core' do
+    let(:validator_name) { "some_custom_validator_name_#{SecureRandom.hex(10)}".to_sym }
+    let(:adapter) { described_class.new(validator_name) { |value| [false, 'intentional failure'] } }
+    let(:plugin_class) { Class.new(LogStash::Plugin) }
+    before(:each) { plugin_class.extend(adapter) }
+    
+    context '#validate_value' do
+      it 'intercepts validation' do
+        expect(plugin_class).to receive(:hash_or_array).and_call_original
+        expect(plugin_class).to receive(:deep_replace).and_call_original
+
+        expect(adapter).to receive(:validate).with(["banana"]).and_call_original
+
+        result = plugin_class.validate_value("banana", validator_name)
+
+        expect(result).to be_a_kind_of(Array)
+        expect(result.size).to eq(2)
+
+        expect(result[0]).to eq false
+        expect(result[1]).to eq 'intentional failure'
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: logstash-mixin-validator_support
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: java
+authors:
+- Elastic
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-12-15 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: '3.9'
+  name: rspec
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !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'
+description: This gem is meant to be a dependency of any Logstash plugin that wishes
+  to use validators introduced in recent versions of Logstash while maintaining backward-compatibility
+  with earlier Logstashes. When used on older Logstash versions, it provides back-ports
+  of the new validators.
+email: info@elastic.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/logstash/plugin_mixins/validator_support.rb
+- lib/logstash/plugin_mixins/validator_support/field_reference_validation_adapter.rb
+- spec/logstash/plugin_mixins/validator_support/field_reference_validation_adapter_spec.rb
+- spec/logstash/plugin_mixins/validator_support_spec.rb
+homepage: https://github.com/logstash-plugins/logstash-mixin-validator_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.11
+signing_key:
+specification_version: 4
+summary: Support for the plugin parameter validations introduced in recent releases
+  of Logstash, for plugins wishing to use them on older Logstashes
+test_files:
+- spec/logstash/plugin_mixins/validator_support/field_reference_validation_adapter_spec.rb
+- spec/logstash/plugin_mixins/validator_support_spec.rb