startback 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56aaefd008d296d55c857bf9c0e392efc13bc34e14d074a65e60b229cbaa1857
-  data.tar.gz: '028e0dcffa18cb2ae93c635198feb4633ba3dbdb3f3f95a56a925faea244eaf1'
+  metadata.gz: 72d21c18d06f3f3c99a95b4ebe7573b9fc61021579f707501a2f00652007df03
+  data.tar.gz: 131a14bfcc89c7a04414f044c0ad02aacc6dbf95920add865eb14ee4ecb26e78
 SHA512:
-  metadata.gz: eb270f0d0061e112b7b783b102566c58a3f50a963029153d56be1c7219a84b82ec6fc2439ca32d2fe9c3a1c772b95a973265412d1c72dbef5bf03f4ea3c6d251
-  data.tar.gz: 8cb20a842aacaf22c1063192a269dfb053894bae994569e03332aec42a90d3e827f69b9b63f1e69bc647a91e0899cdf02cb124536bdd7737c18ac0a446f60204
+  metadata.gz: ceee786b3b488f7a3f0b5fcbe831ee5318cc017a19c2f2771252206ff8a3319dc6b2165f41f774f29b1ee32f50adcdc2e154436a4b640c294c12a1c1e3c84c1b
+  data.tar.gz: 567a6f507af84f76df13eb64fa333aeb51079fcd1efe2950bdda027ee8b3036b13b26fbba3fae8f104cff1e22ef56701dee25f773f96b0c1c957ad255a246524

data/lib/startback/errors.rb

@@ -94,6 +94,10 @@ module Startback
         status 428
       end
 
+      class TooManyRequestsError < BadRequestError
+        status 429
+      end
+
     class InternalServerError < Error
       status 500
       keep_error(true)

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,25 @@
+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(op, defaults)
+        case @rate_limit
+        when NilClass then defaults
+        when Hash then defaults.merge(@rate_limit)
+        when Symbol then defaults.merge(op.send(@rate_limit))
+        else
+          raise ArgumentError
+        end
+      end
+
+    end # module RateLimit
+  end # module Security
+end # module Startback

data/lib/startback/security/rate_limiter.rb

@@ -0,0 +1,143 @@
+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,
+    #         detection: :input,
+    #         periodicity: 60,
+    #         max_occurence: 3,
+    #       },
+    #     })
+    #
+    #     # in api.rb
+    #     around_run(RATE_LIMITER)
+    #
+    #     # in an operation.rb
+    #     class Op < Startback::Operation
+    #       rate_limit { max_occurences: 2 }   # Partial<Config>
+    #       rate_limit :dynamic_config         # Config obtained on op instance
+    #     end
+    #
+    # Reference:
+    #
+    #     strategy: Symbol => :silent_drop or :fail (429 status code)
+    #     detection: Symbol => method to call on Operation instance to detect call duplicates via pure data
+    #     periodicity: Integer => periodicity of occurence count, in seconds
+    #     max_occurences: Integer => max number of occurences during the period
+    #
+    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(op, 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)
+        strat = strategy(limit_options)
+        authorize = (count < max_occurences_allowed(limit_options))
+        if authorize
+          save_detection_count(key, count + 1, limit_options)
+          [key, authorize]
+        elsif strat === :silent_drop
+          [key, authorize]
+        elsif strat === :fail
+          raise Startback::Errors::TooManyRequestsError, op.class.name.to_s
+        else
+          [key, authorize]
+        end
+      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 strategy(limit_options)
+        limit_options[:strategy] || @options[:strategy] || :silent_drop
+      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,8 +1,8 @@
 module Startback
   module Version
     MAJOR = 1
-    MINOR = 1
-    TINY  = 0
+    MINOR = 2
+    TINY  = 1
   end
   VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"
 end

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,215 @@
+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 :fail with a constant' do
+        class FailingRateLimitedOp < RateLimitedOp
+          rate_limit({
+            strategy: :fail,
+            detection: "constant"
+          })
+        end
+
+        let (:op_class) {
+          FailingRateLimitedOp
+        }
+
+        it 'works when called once' do
+          call_it_once
+          expect(op_class.called_count).to eql(1)
+        end
+
+        it 'fails on second call' do
+          call_it_once
+          expect {
+            call_it_once
+          }.to raise_error(Startback::Errors::TooManyRequestsError)
+        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
+
+      context 'when using a dynamic configuration' do
+        class DynamicRateLimitedOp < RateLimitedOp
+          rate_limit :rate_limit_options
+
+          def rate_limit_options
+            {
+              strategy: :silent_drop,
+              detection: "constant",
+              max_occurences: input[:max],
+            }
+          end
+        end
+
+        let (:op_class) {
+          DynamicRateLimitedOp
+        }
+
+        it 'works when called three times in a row' do
+          call_it_once(max: 2)
+          call_it_once(max: 2)
+          call_it_once(max: 2)
+          expect(op_class.called_count).to eql(2)
+        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.1
 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