semian 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b38abe4839593005920d41c13352540c219f93d7995f13ddf3f49cf7b51bdb8
-  data.tar.gz: 5f929e537cfb7f3a8b65c9fc3b43565d8891ad7f0cb30db1f72c633d89343cf1
+  metadata.gz: c46f4408d72d0fe86b9d1199429942007e48dc5a43dc75dc8f361d3d85e369c9
+  data.tar.gz: c297a18a78e2fc02e3c3823c6488413bc6170d8bd718acdcc8995c96bf68b070
 SHA512:
-  metadata.gz: '09901480b2863949adda640b361d9026988e77fb36656593569f54bcf46651dad00c793a1d201111479122adaa0f584e33606811ef2ec35ff924ba6fd518e395'
-  data.tar.gz: 4e8cd13ce2bb3844669befd3610893161f2e97652871856302e1661745f70a56bf6a43c77c96b3cd49024ec93cddbe504e5dfc64ccdf8d63c52eb86bb81ffd4a
+  metadata.gz: 115fe761cbc5e3cf7bdaabb2e28ae04c1ac594d9bad3b69b8c63c996d9b52bf2306e6a3de6892a65b069ed4033f0f53ca09f215b19ebde54e4616059bbb6784d
+  data.tar.gz: 94b77f1de5c869ce44384dc4e6b5fb2acbde52f7074a786130b52b48185ff367cd19541da1ecc298828fda06c679f431fe6fd11c7eee9565b882a6fe1432cb7c

data/README.md

@@ -15,15 +15,15 @@ allowing you to handle errors gracefully.** Semian does this by intercepting
 resource access through heuristic patterns inspired by [Hystrix][hystrix] and
 [Release It][release-it]:
 
-* [**Circuit breaker**](#circuit-breaker). A pattern for limiting the
+- [**Circuit breaker**](#circuit-breaker). A pattern for limiting the
   amount of requests to a dependency that is having issues.
-* [**Bulkheading**](#bulkheading). Controlling the concurrent access to
+- [**Bulkheading**](#bulkheading). Controlling the concurrent access to
   a single resource, access is coordinated server-wide with [SysV
   semaphores][sysv].
 
 Resource drivers are monkey-patched to be aware of Semian, these are called
 [Semian Adapters](#adapters). Thus, every time resource access is requested
-Semian is queried for status on the resource first.  If Semian, through the
+Semian is queried for status on the resource first. If Semian, through the
 patterns above, deems the resource to be unavailable it will raise an exception.
 **The ultimate outcome of Semian is always an exception that can then be rescued
 for a graceful fallback**. Instead of waiting for the timeout, Semian raises
@@ -60,7 +60,7 @@ section](#configuration) on how to configure adapters.
 
 Semian works by intercepting resource access. Every time access is requested,
 Semian is queried, and it will raise an exception if the resource is unavailable
-according to the circuit breaker or bulkheads.  This is done by monkey-patching
+according to the circuit breaker or bulkheads. This is done by monkey-patching
 the resource driver. **The exception raised by the driver always inherits from
 the Base exception class of the driver**, meaning you can always simply rescue
 the base class and catch both Semian and driver errors in the same rescue for
@@ -69,11 +69,11 @@ fallbacks.
 The following adapters are in Semian and tested heavily in production, the
 version is the version of the public gem with the same name:
 
-* [`semian/mysql2`][mysql-semian-adapter] (~> 0.3.16)
-* [`semian/redis`][redis-semian-adapter] (~> 3.2.1)
-* [`semian/net_http`][nethttp-semian-adapter]
-* [`semian/activerecord_trilogy_adapter`][activerecord-trilogy-semian-adapter]
-* [`semian-postgres`][postgres-semian-adapter]
+- [`semian/mysql2`][mysql-semian-adapter] (~> 0.3.16)
+- [`semian/redis`][redis-semian-adapter] (~> 3.2.1)
+- [`semian/net_http`][nethttp-semian-adapter]
+- [`semian/activerecord_trilogy_adapter`][activerecord-trilogy-semian-adapter]
+- [`semian-postgres`][postgres-semian-adapter]
 
 ### Creating Adapters
 
@@ -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
@@ -158,27 +193,27 @@ should be adequate in most environments with reasonably low timeouts.
 
 Internally, semian uses `SEM_UNDO` for several sysv semaphore operations:
 
-* Acquire
-* Worker registration
-* Semaphore metadata state lock
+- Acquire
+- Worker registration
+- Semaphore metadata state lock
 
 The intention behind `SEM_UNDO` is that a semaphore operation is automatically undone when the process exits. This
 is true even if the process exits abnormally - crashes, receives a `SIG_KILL`, etc, because it is handled by
 the operating system and not the process itself.
 
 If, however, a thread performs a semop, the `SEM_UNDO` is on its parent process. This means that the operation
-*will not* be undone when the thread exits. This can result in the following unfavorable behavior when using
+_will not_ be undone when the thread exits. This can result in the following unfavorable behavior when using
 threads:
 
-* Threads acquire a resource, but are killed and the resource ticket is never released. For a process, the
-ticket would be released by `SEM_UNDO`, but since it's a thread there is the potential for ticket starvation.
-This can result in deadlock on the resource.
-* Threads that register workers on a resource but are killed and never unregistered. For a process, the worker
-count would be automatically decremented by `SEM_UNDO`, but for threads the worker count will continue to increment,
-only being undone when the parent process dies. This can cause the number of tickets to dramatically exceed the quota.
-* If a thread acquires the semaphore metadata lock and dies before releasing it, semian will deadlock on anything
-attempting to acquire the metadata lock until the thread's parent process exits. This can prevent the ticket count
-from being updated.
+- Threads acquire a resource, but are killed and the resource ticket is never released. For a process, the
+  ticket would be released by `SEM_UNDO`, but since it's a thread there is the potential for ticket starvation.
+  This can result in deadlock on the resource.
+- Threads that register workers on a resource but are killed and never unregistered. For a process, the worker
+  count would be automatically decremented by `SEM_UNDO`, but for threads the worker count will continue to increment,
+  only being undone when the parent process dies. This can cause the number of tickets to dramatically exceed the quota.
+- If a thread acquires the semaphore metadata lock and dies before releasing it, semian will deadlock on anything
+  attempting to acquire the metadata lock until the thread's parent process exits. This can prevent the ticket count
+  from being updated.
 
 Moreover, a strategy that utilizes `SEM_UNDO` is not compatible with a strategy that attempts to the semaphores tickets manually.
 In order to support threads, operations that currently use `SEM_UNDO` would need to use no semaphore flag, and the calling process
@@ -214,17 +249,19 @@ calculate and adjust ticket counts.
 
 - You must pass **exactly** one of options: `tickets` or `quota`.
 - Tickets available will be the ceiling of the quota ratio to the number of workers
- - So, with one worker, there will always be a minimum of 1 ticket
+- So, with one worker, there will always be a minimum of 1 ticket
 - Workers in different processes will automatically unregister when the process exits.
 - If you have a small number of workers (exactly 2) it's possible that the bulkhead will be too sensitive using quotas.
 - If you use a forking web server (like unicorn) you should call `Semian.unregister_all_resources` before/after forking.
 
 #### Net::HTTP
+
 For the `Net::HTTP` specific Semian adapter, since many external libraries may create
 HTTP connections on the user's behalf, the parameters are instead provided
 by associating callback functions with `Semian::NetHTTP`, perhaps in an initialization file.
 
 ##### Naming and Options
+
 To give Semian parameters, assign a `proc` to `Semian::NetHTTP.semian_configuration`
 that takes a two parameters, `host` and `port` like `127.0.0.1`,`443` or `github_com`,`80`,
 and returns a `Hash` with configuration parameters as follows. The `proc` is used as a
@@ -282,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
@@ -300,6 +337,7 @@ behavior can be changed to blacklisting or even be completely disabled by varyin
 the use of returning `nil` in the assigned closure.
 
 ##### Additional Exceptions
+
 Since we envision this particular adapter can be used in combination with many
 external libraries, that can raise additional exceptions, we added functionality to
 expand the Exceptions that can be tracked as part of Semian's circuit breaker.
@@ -513,22 +551,23 @@ all workers on a server.
 
 There are four configuration parameters for circuit breakers in Semian:
 
-* **circuit_breaker**. Enable or Disable Circuit Breaker. Defaults to `true` if not set.
-* **error_threshold**. The amount of errors a worker encounters within `error_threshold_timeout`
+- **circuit_breaker**. Enable or Disable Circuit Breaker. Defaults to `true` if not set.
+- **error_threshold**. The amount of errors a worker encounters within `error_threshold_timeout`
   amount of time before opening the circuit,
   that is to start rejecting requests instantly.
-* **error_threshold_timeout**. The amount of time in seconds that `error_threshold`
+- **error_threshold_timeout**. The amount of time in seconds that `error_threshold`
   errors must occur to open the circuit.
   Defaults to `error_timeout` seconds if not set.
-* **error_timeout**. The amount of time in seconds until trying to query the resource
+- **error_timeout**. The amount of time in seconds until trying to query the resource
   again.
-* **error_threshold_timeout_enabled**. If set to false it will disable
+- **error_threshold_timeout_enabled**. If set to false it will disable
   the time window for evicting old exceptions. `error_timeout` is still used and
   will reset the circuit. Defaults to `true` if not set.
-* **success_threshold**. The amount of successes on the circuit until closing it
+- **success_threshold**. The amount of successes on the circuit until closing it
   again, that is to start accepting all requests to the circuit.
-* **half_open_resource_timeout**. Timeout for the resource in seconds when
+- **half_open_resource_timeout**. Timeout for the resource in seconds when
   the circuit is half-open (supported for MySQL, Net::HTTP and Redis).
+- **lumping_interval**. If provided, errors within this timeframe (in seconds) will be lumped and recorded as one.
 
 It is possible to disable Circuit Breaker with environment variable
 `SEMIAN_CIRCUIT_BREAKER_DISABLED=1`.
@@ -587,13 +626,13 @@ graph TD;
     ReleaseTicket[Release Ticket]
     FailRequest[Fail Request]
     OpenCircuit[Open Circuit Breaker]
-    
+
     Start --> CheckConnection
     CheckConnection -->|Ticket Available| AllocateTicket
     AllocateTicket --> AccessResource
     AccessResource --> ReleaseTicket
     ReleaseTicket --> CheckConnection
-    
+
     CheckConnection -->|No Ticket Available| BlockTimeout
     BlockTimeout -->|Timeout| FailRequest
     BlockTimeout -->|Ticket Available| AccessResource
@@ -614,9 +653,9 @@ still experimenting with ways to figure out optimal ticket numbers. Generally
 something below half the number of workers on the server for endpoints that are
 queried frequently has worked well for us.
 
-* **bulkhead**. Enable or Disable Bulkhead. Defaults to `true` if not set.
-* **tickets**. Number of workers that can concurrently access a resource.
-* **timeout**. Time to wait in seconds to acquire a ticket if there are no tickets left.
+- **bulkhead**. Enable or Disable Bulkhead. Defaults to `true` if not set.
+- **tickets**. Number of workers that can concurrently access a resource.
+- **timeout**. Time to wait in seconds to acquire a ticket if there are no tickets left.
   We recommend this to be `0` unless you have very few workers running (i.e.
   less than ~5).
 
@@ -626,11 +665,11 @@ It is possible to disable Bulkhead with environment variable
 Note that there are system-wide limitations on how many tickets can be allocated
 on a system. `cat /proc/sys/kernel/sem` will tell you.
 
-> System-wide limit on the number of semaphore sets.  On Linux
-  systems before version 3.19, the default value for this limit
-  was 128.  Since Linux 3.19, the default value is 32,000.  On
-  Linux, this limit can be read and modified via the fourth
-  field of `/proc/sys/kernel/sem`.
+> System-wide limit on the number of semaphore sets. On Linux
+> systems before version 3.19, the default value for this limit
+> was 128. Since Linux 3.19, the default value is 32,000. On
+> Linux, this limit can be read and modified via the fourth
+> field of `/proc/sys/kernel/sem`.
 
 #### Bulkhead debugging on linux
 
@@ -668,10 +707,10 @@ semnum     value      ncount     zcount     pid
 In the above example, we can see each of the semaphores. Looking at the enum code
 in `ext/semian/sysv_semaphores.h` we can see that:
 
-* 0: is the semian meta lock (mutex) protecting updates to the other resources. It's currently free
-* 1: is the number of available tickets - currently no tickets are in use because it's the same as 2
-* 2: is the configured (maximum) number of tickets
-* 3: is the number of registered workers (processes) that would be considered if using the quota strategy.
+- 0: is the semian meta lock (mutex) protecting updates to the other resources. It's currently free
+- 1: is the number of available tickets - currently no tickets are in use because it's the same as 2
+- 2: is the configured (maximum) number of tickets
+- 3: is the number of registered workers (processes) that would be considered if using the quota strategy.
 
 ## Defense line
 
@@ -884,45 +923,87 @@ $ cd semian
 ```
 
 ## Visual Studio Code
-  - Open semian in vscode
-  - Install recommended extensions (one off requirement)
-  - Click `reopen in container` (first boot might take about a minute)
 
-  See https://code.visualstudio.com/docs/remote/containers for more details
+- Open semian in vscode
+- Install recommended extensions (one off requirement)
+- Click `reopen in container` (first boot might take about a minute)
+
+See https://code.visualstudio.com/docs/remote/containers for more details
+
+If you make any changes to `.devcontainer/` you'd need to recreate the containers:
 
+- Select `Rebuild Container` from the command palette
 
-  If you make any changes to `.devcontainer/` you'd need to recreate the containers:
+Running Tests:
 
-  - Select `Rebuild Container` from the command palette
+- `$ bundle exec rake` Run with `SKIP_FLAKY_TESTS=true` to skip flaky tests (CI runs all tests)
 
+### Interactive Test Debugging
 
-  Running Tests:
-  - `$ bundle exec rake` Run with `SKIP_FLAKY_TESTS=true` to skip flaky tests (CI runs all tests)
+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:
-  - `$ docker-compose -f .devcontainer/docker-compose.yml up -d`
-  - `$ docker exec -it semian bash`
+Test semian in containers:
 
-  If you make any changes to `.devcontainer/` you'd need to recreate the containers:
+- `$ docker-compose -f .devcontainer/docker-compose.yml up -d`
+- `$ docker exec -it semian bash`
 
-  - `$ docker-compose -f .devcontainer/docker-compose.yml up -d --force-recreate`
+If you make any changes to `.devcontainer/` you'd need to recreate the containers:
 
-  Run tests in containers:
+- `$ docker-compose -f .devcontainer/docker-compose.yml up -d --force-recreate`
+
+Run tests in containers:
+
+```shell
+$ docker-compose -f ./.devcontainer/docker-compose.yml --profile test run --rm test
+```
 
-  ```shell
-  $ docker-compose -f ./.devcontainer/docker-compose.yml run --rm test
-  ```
+Running Tests:
 
-  Running Tests:
-  - `$ bundle exec rake` Run with `SKIP_FLAKY_TESTS=true` to skip flaky tests (CI runs all tests)
+- `$ bundle exec rake` Run with `SKIP_FLAKY_TESTS=true` to skip flaky tests (CI runs all tests)
 
 ### Running tests in batches
 
-* *TEST_WORKERS* - Total number of workers or batches.
-  It uses to identify a total number of batches, that would be run in parallel. *Default: 1*
-* *TEST_WORKER_NUM* - Specify which batch to run. The value is between 1 and *TEST_WORKERS*. *Default: 1*
+- _TEST_WORKERS_ - Total number of workers or batches.
+  It uses to identify a total number of batches, that would be run in parallel. _Default: 1_
+- _TEST_WORKER_NUM_ - Specify which batch to run. The value is between 1 and _TEST_WORKERS_. _Default: 1_
 
 ```shell
 $ bundle exec rake test:parallel TEST_WORKERS=5 TEST_WORKER_NUM=1

data/lib/semian/circuit_breaker.rb

@@ -17,7 +17,8 @@ module Semian
 
     def initialize(name, exceptions:, success_threshold:, error_threshold:,
       error_timeout:, implementation:, half_open_resource_timeout: nil,
-      error_threshold_timeout: nil, error_threshold_timeout_enabled: true)
+      error_threshold_timeout: nil, error_threshold_timeout_enabled: true,
+      lumping_interval: 0)
       @name = name.to_sym
       @success_count_threshold = success_threshold
       @error_count_threshold = error_threshold
@@ -26,6 +27,7 @@ module Semian
       @error_timeout = error_timeout
       @exceptions = exceptions
       @half_open_resource_timeout = half_open_resource_timeout
+      @lumping_interval = lumping_interval
 
       @errors = implementation::SlidingWindow.new(max_size: @error_count_threshold)
       @successes = implementation::Integer.new
@@ -63,7 +65,6 @@ module Semian
 
     def mark_failed(error)
       push_error(error)
-      push_time
       if closed?
         transition_to_open if error_threshold_reached?
       elsif half_open?
@@ -132,16 +133,16 @@ module Semian
     end
 
     def push_error(error)
-      @last_error = error
-    end
-
-    def push_time
       time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
       if error_threshold_timeout_enabled
         @errors.reject! { |err_time| err_time + @error_threshold_timeout < time }
       end
 
-      @errors << time
+      if @errors.empty? || @errors.last <= time - @lumping_interval
+        @last_error = error
+        @errors << time
+      end
     end
 
     def log_state_transition(new_state)

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.23.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,
@@ -310,6 +309,11 @@ module Semian
                                        else
                                          options[:error_threshold_timeout_enabled]
                                        end,
+      lumping_interval: if options[:lumping_interval].nil?
+                          0
+                        else
+                          options[:lumping_interval]
+                        end,
       exceptions: Array(exceptions) + [::Semian::BaseError],
       half_open_resource_timeout: options[:half_open_resource_timeout],
       implementation: implementation(**options),
@@ -346,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.23.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.8
+rubygems_version: 3.7.1
 specification_version: 4
 summary: Bulkheading for Ruby with SysV semaphores
 test_files: []