2.0-upgrade.md

Circuitbox 2.0 Upgrade Guide

Requirements

Circuitbox 2.0 is tested against Ruby 2.6 through 3.2. Since ruby 2.6 and 2.7 are EOL it's likely we'll drop support for those versions in future releases.

Changes

• The timeout_seconds option when initializing a circuit has been removed.
  • Circuitbox does not wrap the block to run with Ruby's Timeout anymore.
    • If you would like to use Ruby's Timeout you would need to do this yourself.
• A CircuitBreaker's run method has been changed and the run! method has been removed.
  • Calling run is now like calling run! in circuitbox 1.x.
  • If you were using run in circuitbox 1.x you can call run(exception: false) to have the same behavior.
• The logger option when initializing a circuit has been removed.
  • If you would like to use a logger you can either
    • If using the ActiveSupport notifier subscribe to it's notifications to add your own logger
    • Implement your own notifier using the same interface, see the ActiveSupport or Null notifier.
• The exceptions option when initializing a circuit must be an array.
• The exceptions option when initializing a circuit does not default to [Timeout::Error] when the array is empty.
• The cache option when initializing a circuit as been renamed to circuit_store.
• A circuits defaults sleep_window has changed from 300 seconds to 90 seconds.
• The partition option when running a circuit has been removed.
• attr_accessor's on CircuitBreaker have been changed to attr_reader, or in some cases removed.
  • partition has been removed
  • logger has been removed (see above about logger option)
  • time_class has been added
• The class level reset method on Circuitbox has been removed.
  • If you need to reset circuits before/after running a test you can reconfigure circuitbox

        Circuitbox.configure do |config|
          # Reset persisted state in the memory store so it doesn't leak between tests
          # if using a store through moneta and want to reset it between tests you may need to do something else
          config.default_circuit_store = Circuitbox::MemoryStore.new
        end

• The class level reset method on Circuitbox::CircuitBreaker has been removed.
  • This method would call reset on Circuitbox, see above about Circuitbox.reset.
• Circuitbox.circuit does not parse a host name out of a uri and use that as the circuit's service_name.
  • If you rely on this functionality parse the host from the uri before calling Circuitbox.circuit
• Accessing/creating a circuit through Circuitbox[:circuit_identifier] has been removed.
• Circuitbox's notifications sent through ActiveSupport::Notifications have had their names changed.
  • circuit_open changes to open.circuitbox
  • circuit_close changes to close.circuitbox
  • circuit_success changes to success.circuitbox
  • circuit_failure changes to failure.circuitbox
  • circuit_skipped changes to skipped.circuitbox
  • circuit_gauge removed
  • circuit_warning changes to warning.circuitbox
  • add run.circuitbox to track runtime of the block the circuit is running
• Circuit's don't emit their error rate, success counts, failure counts through ActiveSupport::Notifications anymore.
  • The methods error_rate, success_count, failure_count on a circuit instance can be used to obtain this information.
• During circuit initialization if sleep_window is less than time_window it is not set to time_window.
  • Circuitbox warns about, and only checks this during circuit initialization
• Circuitbox's default circuit store has changed from Moneta's memory store to Circuitbox::MemoryStore.
  • Circuitbox::MemoryStore periodically removes expired keys from the store, allowing Ruby to reclaim memory
  • When Circuitbox::MemoryStore is used a circuits time class is Circuitbox::TimeHelper::Monotonic
• If using Moneta as a circuit store, only adapters that support bulk read functionality are supported.