semian 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaba2c88b92196d855605e58c4525a4a8b7c2bb0a4d0b865cab244e059750bb1
-  data.tar.gz: cbd8a6b46fb102b15e9ed3b3d212502013687bcf1e857d924d453086527848c7
+  metadata.gz: c46f4408d72d0fe86b9d1199429942007e48dc5a43dc75dc8f361d3d85e369c9
+  data.tar.gz: c297a18a78e2fc02e3c3823c6488413bc6170d8bd718acdcc8995c96bf68b070
 SHA512:
-  metadata.gz: 490119185621f843c028549cf213d806c2306bfaf0bb10ecf5a4de0134cd470dcde5c849b3119f3f1162fcde0b354045483ce929f3be180157abee76acfab350
-  data.tar.gz: 7afc74eaeb93dfd3f609801a44a4c8267134660172a1614de59747f0efe50371a8e817d40d4f4e97668853fbb30029fb8745da0f9c211f40d5906291bf56d86b
+  metadata.gz: 115fe761cbc5e3cf7bdaabb2e28ae04c1ac594d9bad3b69b8c63c996d9b52bf2306e6a3de6892a65b069ed4033f0f53ca09f215b19ebde54e4616059bbb6784d
+  data.tar.gz: 94b77f1de5c869ce44384dc4e6b5fb2acbde52f7074a786130b52b48185ff367cd19541da1ecc298828fda06c679f431fe6fd11c7eee9565b882a6fe1432cb7c

data/README.md

@@ -113,6 +113,10 @@ Semian.maximum_lru_size = 0
 
 # Minimum time in seconds a resource should be resident in the LRU cache (default: 300s)
 Semian.minimum_lru_time = 60
+
+# If true, raise exceptions in case of a validation / constraint failure
+# Otherwise, log in output
+Semian.default_force_config_validation = false
 ```
 
 Note: `minimum_lru_time` is a stronger guarantee than `maximum_lru_size`. That
@@ -120,6 +124,10 @@ is, if a resource has been updated more recently than `minimum_lru_time` it
 will not be garbage collected, even if it would cause the LRU cache to grow
 larger than `maximum_lru_size`.
 
+Note: `default_force_config_validation` set to `true` is a
+**_potentially breaking change_**. Misconfigured Semians will raise errors, so
+make sure that this is what you want. See more in [Configuration Validation](#configuration-validation).
+
 When instantiating a resource it now needs to be configured for Semian. This is
 done by passing `semian` as an argument when initializing the client. Examples
 built in adapters:
@@ -132,7 +140,8 @@ client = Mysql2::Client.new(host: "localhost", username: "root", semian: {
   tickets: 8, # See the Understanding Semian section on picking these values
   success_threshold: 2,
   error_threshold: 3,
-  error_timeout: 10
+  error_timeout: 10,
+  force_config_validation: false
 })
 
 # Redis client
@@ -145,6 +154,32 @@ client = Redis.new(semian: {
 })
 ```
 
+#### Configuration Validation
+
+Semian now provides a flag to specify log-based and exception-based configuration validation. To
+explicitly force the Semian to validate it's configurations, pass `force_config_validation: true`
+into your resource. This will raise an error in the case of a misconfigured or illegal Semian. Otherwise,
+if it is set to `false`, it will log misconfigured parameters verbosely in output.
+
+If not specified, it will use `Semian.default_force_config_validation` as
+the flag.
+
+##### Migration Strategy for Force Config Validation
+
+When migrating to use `force_config_validation: true`, follow these steps:
+
+1. **Deploy with it turned off**: Start with `force_config_validation: false` in your configuration
+2. **Look for logs with prefix**: Monitor your application logs for entries with the `[SEMIAN_CONFIG_WARNING]:` prefix. These logs will indicate misconfigured Semian resources
+3. **Iterate to fix**: Address each configuration issue identified in the logs by updating your Semian configurations
+4. **Enable**: Once all configuration issues are resolved, set `force_config_validation: true` to enable strict validation
+
+Example log entries to look for:
+```
+[SEMIAN_CONFIG_WARNING]: Missing required arguments for Semian: [:success_threshold, :error_threshold, :error_timeout]
+[SEMIAN_CONFIG_WARNING]: Both bulkhead and circuitbreaker cannot be disabled.
+[SEMIAN_CONFIG_WARNING]: Bulkhead configuration require either the :tickets or :quota parameter, you provided neither
+```
+
 #### Thread Safety
 
 Semian's circuit breaker implementation is thread-safe by default as of
@@ -284,11 +319,11 @@ Semian::NetHTTP.semian_configuration = proc do |host, port|
   SEMIAN_PARAMETERS.merge(name: name)
 end
 
-# Two requests to example.com can use two different semian resources,
+# Two requests to shopify.com can use two different semian resources,
 # as long as `CurrentSemianSubResource.sub_name` is set accordingly:
-# CurrentSemianSubResource.set(sub_name: "sub_resource_1") { Net::HTTP.get_response(URI("http://example.com")) }
+# CurrentSemianSubResource.set(sub_name: "sub_resource_1") { Net::HTTP.get_response(URI("http://shopify.com")) }
 # and:
-# CurrentSemianSubResource.set(sub_name: "sub_resource_2") { Net::HTTP.get_response(URI("http://example.com")) }
+# CurrentSemianSubResource.set(sub_name: "sub_resource_2") { Net::HTTP.get_response(URI("http://shopify.com")) }
 ```
 
 For most purposes, `"#{host}_#{port}"` is a good default `name`. Custom `name` formats
@@ -903,6 +938,46 @@ Running Tests:
 
 - `$ bundle exec rake` Run with `SKIP_FLAKY_TESTS=true` to skip flaky tests (CI runs all tests)
 
+### Interactive Test Debugging
+
+To use the interactive debugger on vscode:
+- Open semian in vscode
+- Create an `.env` file (if it doesn't exist)
+- Set up a `DEBUG` ENV variable (ex; `DEBUG=true`)
+- Under the `.vscode/` subdirectory, create a `launch.json` file, and include the following:
+
+```json
+{
+  "configurations": [
+    {
+      "type": "rdbg",
+      "name": "Attach to Ruby rdbg",
+      "request": "attach",
+      "debugPort": "12345",
+    }
+  ]
+}
+```
+
+- For universal support, for any lines you would like to add breakpoints to in your `_test.rb` file (under `test/`), include the following snippet near the line of interest:
+
+```rb
+require "debug"
+binding.break if ENV["DEBUG"]
+```
+
+**Note:** unless you are using an vscode extension such as [Dev Container](https://code.visualstudio.com/docs/devcontainers/tutorial), **do not use the built-in vscode breakpoints -- they will not work!**
+
+- Start up the test container
+
+```shell
+$ docker-compose -f .devcontainer/docker-compose.yml --profile test up -d
+```
+
+- When the process indicates that it is waiting for the debugger connection, go to the `Run and Debug` tab, and execute the `Attach to Ruby rdbg` debugger
+
+- Use the vscode debugging tools (such as step in, step out, pause, resume) as normal
+
 ## Everything else
 
 Test semian in containers:
@@ -917,7 +992,7 @@ If you make any changes to `.devcontainer/` you'd need to recreate the container
 Run tests in containers:
 
 ```shell
-$ docker-compose -f ./.devcontainer/docker-compose.yml run --rm test
+$ docker-compose -f ./.devcontainer/docker-compose.yml --profile test run --rm test
 ```
 
 Running Tests:

data/lib/semian/circuit_breaker.rb

@@ -29,10 +29,6 @@ module Semian
       @half_open_resource_timeout = half_open_resource_timeout
       @lumping_interval = lumping_interval
 
-      if @lumping_interval > @error_threshold_timeout
-        raise ArgumentError, "lumping_interval (#{@lumping_interval}) must be less than error_threshold_timeout (#{@error_threshold_timeout})"
-      end
-
       @errors = implementation::SlidingWindow.new(max_size: @error_count_threshold)
       @successes = implementation::Integer.new
       @state = implementation::State.new

data/lib/semian/configuration_validator.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Semian
+  class ConfigurationValidator
+    def initialize(name, configuration)
+      @name = name
+      @configuration = configuration
+      @adapter = configuration[:adapter]
+      @force_config_validation = force_config_validation?
+
+      unless @force_config_validation
+        Semian.logger.warn(
+          "Semian is running in log-mode for configuration validation. This means that Semian will not raise an error if the configuration is invalid. This is not recommended for production environments.\n\n[IMPORTANT] IN FUTURE RELEASES, STRICT CONFIGURATION VALIDATION WILL BE THE DEFAULT BEHAVIOR. PLEASE UPDATE YOUR CONFIGURATION TO USE `force_config_validation: true` TO ENABLE STRICT CONFIGURATION VALIDATION. ALLOWING MISCONFIGURATIONS IN FUTURE RELEASES WILL BREAK YOUR SEMIAN.\n---\n",
+        )
+      end
+    end
+
+    def validate!
+      validate_circuit_breaker_or_bulkhead!
+      validate_bulkhead_configuration!
+      validate_circuit_breaker_configuration!
+      validate_resource_name!
+    end
+
+    private
+
+    def hint_format(message)
+      "\n\nHINT: #{message}\n---"
+    end
+
+    def raise_or_log_validation_required!(message)
+      if @force_config_validation
+        raise ArgumentError, message
+      else
+        Semian.logger.warn("[SEMIAN_CONFIG_WARNING]: #{message}")
+      end
+    end
+
+    def require_keys!(required, options)
+      diff = required - options.keys
+      unless diff.empty?
+        raise_or_log_validation_required!("Missing required arguments for Semian: #{diff}")
+      end
+    end
+
+    def validate_circuit_breaker_or_bulkhead!
+      if (@configuration[:circuit_breaker] == false || ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")) && (@configuration[:bulkhead] == false || ENV.key?("SEMIAN_BULKHEAD_DISABLED"))
+        raise_or_log_validation_required!("Both bulkhead and circuitbreaker cannot be disabled.")
+      end
+    end
+
+    def validate_bulkhead_configuration!
+      return if ENV.key?("SEMIAN_BULKHEAD_DISABLED")
+      return unless @configuration.fetch(:bulkhead, true)
+
+      tickets = @configuration[:tickets]
+      quota = @configuration[:quota]
+
+      if tickets.nil? && quota.nil?
+        raise_or_log_validation_required!("Bulkhead configuration require either the :tickets or :quota parameter, you provided neither")
+      end
+
+      if tickets && quota
+        raise_or_log_validation_required!("Bulkhead configuration require either the :tickets or :quota parameter, you provided both")
+      end
+
+      validate_quota!(quota) if quota
+      validate_tickets!(tickets) if tickets
+    end
+
+    def validate_circuit_breaker_configuration!
+      return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
+      return unless @configuration.fetch(:circuit_breaker, true)
+
+      require_keys!([:success_threshold, :error_threshold, :error_timeout], @configuration)
+      validate_thresholds!
+      validate_timeouts!
+    end
+
+    def validate_thresholds!
+      success_threshold = @configuration[:success_threshold]
+      error_threshold = @configuration[:error_threshold]
+
+      unless success_threshold.is_a?(Integer) && success_threshold > 0
+        err = "success_threshold must be a positive integer, got #{success_threshold}"
+
+        if success_threshold == 0
+          err += hint_format("Are you sure that this is what you want? This will close the circuit breaker immediately after `error_timeout` seconds without checking the resource!")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+
+      unless error_threshold.is_a?(Integer) && error_threshold > 0
+        err = "error_threshold must be a positive integer, got #{error_threshold}"
+
+        if error_threshold == 0
+          err += hint_format("Are you sure that this is what you want? This can result in the circuit opening up at unpredictable times!")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+    end
+
+    def validate_timeouts!
+      error_timeout = @configuration[:error_timeout]
+      error_threshold_timeout_enabled = @configuration[:error_threshold_timeout_enabled].nil? ? true : @configuration[:error_threshold_timeout_enabled]
+      error_threshold = @configuration[:error_threshold]
+      lumping_interval = @configuration[:lumping_interval]
+      half_open_resource_timeout = @configuration[:half_open_resource_timeout]
+
+      unless error_timeout.is_a?(Numeric) && error_timeout > 0
+        err = "error_timeout must be a positive number, got #{error_timeout}"
+
+        if error_timeout == 0
+          err += hint_format("Are you sure that this is what you want? This will close the circuit breaker immediately after opening it!")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+
+      # This state checks for contradictions between error_threshold_timeout_enabled and error_threshold_timeout.
+      unless error_threshold_timeout_enabled || !@configuration[:error_threshold_timeout]
+        err = "error_threshold_timeout_enabled and error_threshold_timeout must not contradict each other, got error_threshold_timeout_enabled: #{error_threshold_timeout_enabled}, error_threshold_timeout: #{@configuration[:error_threshold_timeout]}"
+        err += hint_format("Are you sure this is what you want? This will set error_threshold_timeout_enabled to #{error_threshold_timeout_enabled} while error_threshold_timeout is #{@configuration[:error_threshold_timeout] ? "truthy" : "falsy"}")
+
+        raise_or_log_validation_required!(err)
+      end
+
+      # Only set this after we have checked the error_threshold_timeout_enabled condition
+      error_threshold_timeout = @configuration[:error_threshold_timeout] || error_timeout
+      unless error_threshold_timeout.is_a?(Numeric) && error_threshold_timeout > 0
+        err = "error_threshold_timeout must be a positive number, got #{error_threshold_timeout}"
+
+        if error_threshold_timeout == 0
+          err += hint_format("Are you sure that this is what you want? This will almost never open the circuit breaker since the time interval to catch errors is 0!")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+
+      unless half_open_resource_timeout.nil? || (half_open_resource_timeout.is_a?(Numeric) && half_open_resource_timeout > 0)
+        err = "half_open_resource_timeout must be a positive number, got #{half_open_resource_timeout}"
+
+        if half_open_resource_timeout == 0
+          err += hint_format("Are you sure that this is what you want? This will never half-open the circuit breaker! If that's what you want, you can omit the option instead")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+
+      unless lumping_interval.nil? || (lumping_interval.is_a?(Numeric) && lumping_interval > 0)
+        err = "lumping_interval must be a positive number, got #{lumping_interval}"
+
+        if lumping_interval == 0
+          err += hint_format("Are you sure that this is what you want? This will never lump errors! If that's what you want, you can omit the option instead")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+
+      # You might be wondering why not check just check lumping_interval * error_threshold <= error_threshold_timeout
+      # The reason being is that since the lumping_interval starts at the first error, we count the first error
+      # at second 0. So we need to subtract 1 from the error_threshold to get the correct minimum time to reach the
+      # error threshold. error_threshold_timeout cannot be less than this minimum time.
+      #
+      # For example,
+      #
+      # error_threshold = 3
+      # error_threshold_timeout = 10
+      # lumping_interval = 4
+      #
+      # The first error could be counted at second 0, the second error could be counted at second 4, and the third
+      # error could be counted at second 8. So this is a valid configuration.
+
+      unless lumping_interval.nil? || error_threshold_timeout.nil? || lumping_interval * (error_threshold - 1) <= error_threshold_timeout
+        err = "constraint violated, this circuit breaker can never open! lumping_interval * (error_threshold - 1) should be <= error_threshold_timeout, got lumping_interval: #{lumping_interval}, error_threshold: #{error_threshold}, error_threshold_timeout: #{error_threshold_timeout}"
+        err += hint_format("lumping_interval starts from the first error and not in a fixed window. So you can fit n errors in n-1 seconds, since error 0 starts at 0 seconds. Ensure that you can fit `error_threshold` errors lumped in `lumping_interval` seconds within `error_threshold_timeout` seconds.")
+
+        raise_or_log_validation_required!(err)
+      end
+    end
+
+    def validate_quota!(quota)
+      unless quota.is_a?(Numeric) && quota > 0 && quota < 1
+        err = "quota must be a decimal between 0 and 1, got #{quota}"
+
+        if quota == 0
+          err += hint_format("Are you sure that this is what you want? This is the same as assigning no workers to the resource, disabling the resource!")
+        elsif quota == 1
+          err += hint_format("Are you sure that this is what you want? This is the same as assigning all workers to the resource, disabling the bulkhead!")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+    end
+
+    def validate_tickets!(tickets)
+      unless tickets.is_a?(Integer) && tickets > 0 && tickets < Semian::MAX_TICKETS
+        err = "ticket count must be a positive integer and less than #{Semian::MAX_TICKETS}, got #{tickets}"
+
+        if tickets == 0
+          err += hint_format("Are you sure that this is what you want? This is the same as assigning no workers to the resource, disabling the resource!")
+        elsif tickets == Semian::MAX_TICKETS
+          err += hint_format("Are you sure that this is what you want? This is the same as assigning all workers to the resource, disabling the bulkhead!")
+        end
+
+        raise_or_log_validation_required!(err)
+      end
+    end
+
+    def validate_resource_name!
+      unless @name.is_a?(String) || @name.is_a?(Symbol)
+        raise_or_log_validation_required!("name must be a symbol or string, got #{@name}")
+      end
+
+      if Semian.resources[@name]
+        err = "Resource with name #{@name} is already registered"
+        err += hint_format("Are you sure that this is what you want? This will override an existing resource with the same name!")
+
+        raise_or_log_validation_required!(err)
+      end
+    end
+
+    def force_config_validation?
+      if @configuration[:force_config_validation].nil?
+        Semian.default_force_config_validation
+      else
+        @configuration[:force_config_validation]
+      end
+    end
+  end
+end

data/lib/semian/lru_hash.rb

@@ -14,11 +14,11 @@ class LRUHash
       yield
     end
 
-    def try_lock
+    def try_lock # rubocop:disable Naming/PredicateMethod
       true
     end
 
-    def unlock
+    def unlock # rubocop:disable Naming/PredicateMethod
       true
     end
 

data/lib/semian/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Semian
-  VERSION = "0.24.0"
+  VERSION = "0.25.0"
 end

data/lib/semian.rb

@@ -16,6 +16,7 @@ require "semian/simple_sliding_window"
 require "semian/simple_integer"
 require "semian/simple_state"
 require "semian/lru_hash"
+require "semian/configuration_validator"
 
 #
 # === Overview
@@ -102,11 +103,12 @@ module Semian
   OpenCircuitError = Class.new(BaseError)
   SemaphoreMissingError = Class.new(BaseError)
 
-  attr_accessor :maximum_lru_size, :minimum_lru_time, :default_permissions, :namespace
+  attr_accessor :maximum_lru_size, :minimum_lru_time, :default_permissions, :namespace, :default_force_config_validation
 
   self.maximum_lru_size = 500
   self.minimum_lru_time = 300 # 300 seconds / 5 minutes
   self.default_permissions = 0660
+  self.default_force_config_validation = false
 
   def issue_disabled_semaphores_warning
     return if defined?(@warning_issued)
@@ -184,13 +186,12 @@ module Semian
   def register(name, **options)
     return UnprotectedResource.new(name) if ENV.key?("SEMIAN_DISABLED")
 
+    # Validate configuration before proceeding
+    ConfigurationValidator.new(name, options).validate!
+
     circuit_breaker = create_circuit_breaker(name, **options)
     bulkhead = create_bulkhead(name, **options)
 
-    if circuit_breaker.nil? && bulkhead.nil?
-      raise ArgumentError, "Both bulkhead and circuitbreaker cannot be disabled."
-    end
-
     resources[name] = ProtectedResource.new(name, bulkhead, circuit_breaker)
   end
 
@@ -296,8 +297,6 @@ module Semian
     return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
     return unless options.fetch(:circuit_breaker, true)
 
-    require_keys!([:success_threshold, :error_threshold, :error_timeout], options)
-
     exceptions = options[:exceptions] || []
     CircuitBreaker.new(
       name,
@@ -351,13 +350,6 @@ module Semian
       timeout: timeout,
     )
   end
-
-  def require_keys!(required, options)
-    diff = required - options.keys
-    unless diff.empty?
-      raise ArgumentError, "Missing required arguments for Semian: #{diff}"
-    end
-  end
 end
 
 if Semian.semaphores_enabled?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semian
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Scott Francis
@@ -36,6 +36,7 @@ files:
 - lib/semian/activerecord_trilogy_adapter.rb
 - lib/semian/adapter.rb
 - lib/semian/circuit_breaker.rb
+- lib/semian/configuration_validator.rb
 - lib/semian/grpc.rb
 - lib/semian/instrumentable.rb
 - lib/semian/lru_hash.rb
@@ -77,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: Bulkheading for Ruby with SysV semaphores
 test_files: []