startback 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56aaefd008d296d55c857bf9c0e392efc13bc34e14d074a65e60b229cbaa1857
-  data.tar.gz: '028e0dcffa18cb2ae93c635198feb4633ba3dbdb3f3f95a56a925faea244eaf1'
+  metadata.gz: 2bcf837fdfb9024b8ba0da1bbb00919a7fef30f69b5145f93fa7d44cc8202989
+  data.tar.gz: 16916a1f6be864f19999e16c808499a91df7a425ce7855e14fbc7a6ff2e3710f
 SHA512:
-  metadata.gz: eb270f0d0061e112b7b783b102566c58a3f50a963029153d56be1c7219a84b82ec6fc2439ca32d2fe9c3a1c772b95a973265412d1c72dbef5bf03f4ea3c6d251
-  data.tar.gz: 8cb20a842aacaf22c1063192a269dfb053894bae994569e03332aec42a90d3e827f69b9b63f1e69bc647a91e0899cdf02cb124536bdd7737c18ac0a446f60204
+  metadata.gz: 2d7cf234140ce2e3f0ca7e3c6e4983e0a89d411067156da2f9c55334623de060c2abe2e8e26b1747b97b88ceb25fd8aeddcde98c156093f41f58032cb3eb3b2f
+  data.tar.gz: cde80e613c12e4db455e0f08b8c253c74eec1b0a2f5947b1d57dfa76bc6ce0152632d24b5a97150f9702d493411fe5194d9fe604fb9633df98d28424685e8c34

data/lib/startback/security/ext/operation.rb

@@ -0,0 +1,5 @@
+module Startback
+  class Operation
+    extend Security::RateLimit
+  end # class Operation
+end # module Startback

data/lib/startback/security/ext.rb

@@ -0,0 +1 @@
+require_relative 'ext/operation'

data/lib/startback/security/rate_limit.rb

@@ -0,0 +1,19 @@
+module Startback
+  module Security
+    module RateLimit
+
+      def rate_limit(options = {})
+        @rate_limit = options
+      end
+
+      def has_rate_limit?
+        !!@rate_limit
+      end
+
+      def rate_limit_options(defaults)
+        defaults.merge(@rate_limit || {})
+      end
+
+    end # module RateLimit
+  end # module Security
+end # module Startback

data/lib/startback/security/rate_limiter.rb

@@ -0,0 +1,117 @@
+require 'startback/audit'
+
+module Startback
+  module Security
+    #
+    # This class can be used as operation arounder to skip operation executions
+    # via a rate limiting process.
+    #
+    # Example:
+    #
+    #     RATE_LIMITER = Startback::Security::RateLimiter.new({
+    #       store: Startback::Caching::Store.new,  # use a redis cache store in practice
+    #       defaults: {
+    #         strategy: :silent_drop,              # simply ignore the call
+    #         detection: :input,                   # method to call on Operation instance to detect call duplicates via pure data
+    #         periodicity: 60,                     # periodicity of occurence count, in seconds
+    #         max_occurence: 3,                    # max number of occurences during the period
+    #       },
+    #     })
+    #
+    #     # in api.rb
+    #     around_run(RATE_LIMITER)
+    #
+    class RateLimiter
+      include Support::Robustness
+
+      DEFAULT_OPTIONS = {
+        max_occurences: 1
+      }
+
+      def initialize(options = {})
+        @options = DEFAULT_OPTIONS.merge(options)
+
+        configuration_error!("Missing store") unless @options[:store]
+      end
+
+      def call(runner, op, &then_block)
+        raise ArgumentError, "A block is required" unless then_block
+
+        if op.class.has_rate_limit?
+          limit_options = op.class.rate_limit_options(defaults || {})
+          key, authorized = authorize_call!(op, limit_options)
+          unless authorized
+            log_rate_limited(op, key, limit_options)
+            return nil
+          end
+        end
+
+        then_block.call
+      end
+
+    private
+
+      def authorize_call!(op, limit_options)
+        key = get_detection_key(op, limit_options)
+        count = get_detection_count(key)
+        authorize = (count < max_occurences_allowed(limit_options))
+        save_detection_count(key, count + 1, limit_options) if authorize
+        [key, authorize]
+      end
+
+      def get_detection_count(key)
+        value = store.get(key)
+        value.nil? ? 0 : value.to_i
+      end
+
+      def save_detection_count(key, count, limit_options)
+        store.set(key, count.to_s, ttl(limit_options))
+      end
+
+      def get_detection_key(op, limit_options)
+        value = case detection = limit_options[:detection]
+        when String
+          detection
+        when Symbol
+          op.send(detection)
+        else
+          configuration_error!("Unrecognized :detection `#{detection}`")
+        end
+        key = {
+          model: "Startback::Security::RateLimiter",
+          op_class: op.class.name.to_s,
+          value: value,
+        }
+        JSON.fast_generate(key)
+      end
+
+      def defaults
+        @defaults ||= @options[:defaults]
+      end
+
+      def store
+        @store ||= @options[:store]
+      end
+
+      def ttl(limit_options)
+        limit_options[:periodicity] || @options[:periodicity] || 60
+      end
+
+      def max_occurences_allowed(limit_options)
+        limit_options[:max_occurences] || @options[:max_occurences] || 1
+      end
+
+      def log_rate_limited(op, key, limit_options)
+        logger_for(op).warn({
+          op: self.class,
+          op_data: { key: key, options: limit_options },
+        })
+      end
+
+      def configuration_error!(msg)
+        raise Startback::Error, msg
+      end
+
+    end # class RateLimiter
+  end # module Audit
+end # module Startback

data/lib/startback/security.rb

@@ -0,0 +1,3 @@
+require_relative 'security/rate_limit'
+require_relative 'security/rate_limiter'
+require_relative 'security/ext'

data/lib/startback/support/env.rb

@@ -51,6 +51,11 @@ module Startback
       end
       module_function :development?
 
+      def test?
+        ENV['RACK_ENV'] =~ /^test/
+      end
+      module_function :test?
+
     end # module Env
   end # module Support
 end # module Startback

data/lib/startback/support/robustness.rb

@@ -45,7 +45,6 @@ module Startback
             l.formatter = LogFormatter.new
             l.warn(op: "#{self}", op_data: {
               msg: "Using default logger to STDOUT",
-              caller: caller
             })
             @@default_logger = l
           end
@@ -92,6 +91,11 @@ module Startback
 
       end # module Tools
 
+      # Returns the natural logger to use for a specific arg
+      def logger_for(arg)
+        Tools.logger_for(arg)
+      end
+
       # Logs a specific message with a given severity.
       #
       # Severity can be :debug, :info, :warn, :error or :fatal.

data/lib/startback/support/spy_logger.rb

@@ -0,0 +1,38 @@
+module Startback
+  module Support
+    #
+    # A Logger extension that spies message for inspection during integration
+    # testing
+    #
+    class SpyLogger < ::Logger
+
+      def initialize(*args, &bl)
+        super(*args, &bl)
+        reset_spy_state!
+      end
+
+      def reset_spy_state!
+        @state = Hash.new
+      end
+
+      def has?(severity, match = {})
+        @state[severity] && @state[severity].find{|x|
+          match.each_pair.all?{|(k,v)| x[k] == v }
+        }
+      end
+
+      def spy(severity, args)
+        @state[severity] ||= []
+        @state[severity] << args[0]
+      end
+
+      [ :info, :warn, :error, :fatal ].each {|meth|
+        define_method(meth) do |*args, &bl|
+          spy(meth, args)
+          super(*args, &bl)
+        end
+      }
+
+    end # class SpyLogger
+  end # module Support
+end # module Startback

data/lib/startback/support.rb

@@ -18,6 +18,7 @@ require_relative 'support/env'
 require_relative 'support/redactor'
 require_relative 'support/log_formatter'
 require_relative 'support/logger'
+require_relative 'support/spy_logger'
 require_relative 'support/robustness'
 require_relative 'support/hooks'
 require_relative 'support/operation_runner'

data/lib/startback/version.rb

@@ -1,7 +1,7 @@
 module Startback
   module Version
     MAJOR = 1
-    MINOR = 1
+    MINOR = 2
     TINY  = 0
   end
   VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"

data/lib/startback/web/auto_caching.rb

@@ -35,7 +35,7 @@ module Startback
       DEVELOPMENT_CACHE_CONTROL = ENV['STARTBACK_AUTOCACHING_DEVELOPMENT_CACHE_CONTROL'] || \
                                   "no-cache, no-store, max-age=0, must-revalidate"
 
-      # Cache-Control header to use in produdction mode
+      # Cache-Control header to use in production mode
       PRODUCTION_CACHE_CONTROL = ENV['STARTBACK_AUTOCACHING_PRODUCTION_CACHE_CONTROL'] ||\
                                  "public, must-revalidate, max-age=3600, s-max-age=3600"
 

data/spec/spec_helper.rb

@@ -1,7 +1,9 @@
 require 'startback'
+require 'startback/caching'
 require 'startback/event'
 require 'startback/support/fake_logger'
 require 'startback/audit'
+require 'startback/security'
 require 'rack/test'
 require 'ostruct'
 

data/spec/unit/security/test_rate_limiter.rb

@@ -0,0 +1,165 @@
+require 'spec_helper'
+module Startback
+  module Security
+    describe RateLimiter do
+      let(:limiter) do
+        RateLimiter.new(options)
+      end
+
+      let(:store) {
+        Caching::Store.new
+      }
+
+      let(:options) {
+        {
+          store: store,
+          defaults: {
+            strategy: :silent_drop,
+            detection: 'any',
+          },
+        }
+      }
+
+      before(:each) do
+        op_class.reset
+      end
+
+      class RateLimitedOp < Startback::Operation
+        def initialize(input)
+          @input = input
+        end
+        attr_reader :input
+
+        def self.reset
+          @called = 0
+        end
+
+        def self.called
+          @called = @called + 1
+        end
+
+        def self.called_count
+          @called
+        end
+
+        def call
+          self.class.called
+        end
+      end
+
+      def call_it_once(input = {})
+        op = op_class.new(input)
+        limiter.call(nil, op){ op.call }
+      end
+
+      context 'when silent_drop with a constant' do
+        class ConstantRateLimitedOp < RateLimitedOp
+          rate_limit({
+            strategy: :silent_drop,
+            detection: "constant"
+          })
+        end
+
+        let (:op_class) {
+          ConstantRateLimitedOp
+        }
+
+        it 'works when called once' do
+          call_it_once
+          expect(op_class.called_count).to eql(1)
+        end
+
+        it 'silently ignores second call' do
+          call_it_once
+          call_it_once
+          expect(op_class.called_count).to eql(1)
+        end
+      end
+
+      context 'when silent_drop with a symbol' do
+        class InputRateLimitedOp < RateLimitedOp
+          rate_limit({
+            strategy: :silent_drop,
+            detection: :input
+          })
+        end
+
+        let (:op_class) {
+          InputRateLimitedOp
+        }
+
+        context 'when called with the same input' do
+          it 'works when called once' do
+            call_it_once({ hello: 'foo' })
+            expect(op_class.called_count).to eql(1)
+          end
+
+          it 'silently ignores second call' do
+            call_it_once({ hello: 'foo' })
+            call_it_once({ hello: 'foo' })
+            expect(op_class.called_count).to eql(1)
+          end
+        end
+
+        context 'when called with different inputs' do
+          it 'accepts every call' do
+            call_it_once({ hello: 'foo' })
+            call_it_once({ hello: 'bar' })
+            expect(op_class.called_count).to eql(2)
+          end
+        end
+      end
+
+      context "when the defaults options are used" do
+        class DefaultsRateLimitedOp < RateLimitedOp
+          rate_limit
+        end
+
+        let (:op_class) {
+          DefaultsRateLimitedOp
+        }
+
+        it 'works when called once' do
+          call_it_once
+          expect(op_class.called_count).to eql(1)
+        end
+
+        it 'silently ignores second call' do
+          call_it_once
+          call_it_once
+          expect(op_class.called_count).to eql(1)
+        end
+      end
+
+      context 'when using the occurence option to allow more than 1 execution' do
+        class OccurencesRateLimitedOp < RateLimitedOp
+          rate_limit({
+            strategy: :silent_drop,
+            detection: "constant",
+            max_occurences: 3,
+          })
+        end
+
+        let (:op_class) {
+          OccurencesRateLimitedOp
+        }
+
+        it 'works when called three times in a row' do
+          call_it_once
+          call_it_once
+          call_it_once
+          expect(op_class.called_count).to eql(3)
+        end
+
+        it 'silently ignores further calls' do
+          call_it_once
+          call_it_once
+          call_it_once
+          call_it_once
+          call_it_once
+          expect(op_class.called_count).to eql(3)
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: startback
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Bernard Lambeau
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-09 00:00:00.000000000 Z
+date: 2025-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -56,20 +56,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.26.0
+        version: 0.27.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.27'
+        version: '0.28'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.26.0
+        version: 0.27.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.27'
+        version: '0.28'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -421,6 +421,11 @@ files:
 - lib/startback/operation.rb
 - lib/startback/operation/error_operation.rb
 - lib/startback/operation/multi_operation.rb
+- lib/startback/security.rb
+- lib/startback/security/ext.rb
+- lib/startback/security/ext/operation.rb
+- lib/startback/security/rate_limit.rb
+- lib/startback/security/rate_limiter.rb
 - lib/startback/services.rb
 - lib/startback/support.rb
 - lib/startback/support/data_object.rb
@@ -432,6 +437,7 @@ files:
 - lib/startback/support/operation_runner.rb
 - lib/startback/support/redactor.rb
 - lib/startback/support/robustness.rb
+- lib/startback/support/spy_logger.rb
 - lib/startback/support/transaction_manager.rb
 - lib/startback/support/transaction_policy.rb
 - lib/startback/support/world.rb
@@ -460,6 +466,7 @@ files:
 - spec/unit/context/test_world.rb
 - spec/unit/event/bus/memory/test_async.rb
 - spec/unit/event/bus/memory/test_sync.rb
+- spec/unit/security/test_rate_limiter.rb
 - spec/unit/support/hooks/test_after_hook.rb
 - spec/unit/support/hooks/test_before_hook.rb
 - spec/unit/support/operation_runner/test_around_run.rb