v5.2.0

Stoplight v5.2.0 Release Notes

We're excited to announce Stoplight v5.2.0, a significant release that introduces pluggable traffic control strategies, performance improvements, and enhanced recovery mechanisms. This release makes Stoplight more flexible for high-traffic environments.

🚦 New Feature: Traffic Control Strategies

Stoplight now supports pluggable traffic control strategies, moving beyond the traditional consecutive failure counting to support modern, percentage-based circuit-breaking patterns.

Two Built-in Strategies

Consecutive Errors (Default - Fully Backward Compatible)

The familiar behavior you know and love, now explicitly configurable:

# Existing code continues to work unchanged
light = Stoplight("API", threshold: 5)

# Or be explicit about the strategy
light = Stoplight("API", traffic_control: :consecutive_errors, threshold: 5)

Error Rate (New)

Perfect for high-traffic services and SLA-based monitoring:

# Trip when error rate exceeds 50% within a 5-minute window
light = Stoplight("Payment API", 
  traffic_control: :error_rate,
  window_size: 300,      # 5-minute sliding window
  threshold: 0.5         # 50% error rate
)

# Fine-tune with minimum request thresholds

light = Stoplight("Payment API",
  traffic_control: { error_rate: { min_requests: 100 } },
  window_size: 600,
  threshold: 0.6
)

When to use each strategy:

• Consecutive Errors: Low-medium traffic, simple behavior, occasional spikes expected
• Error Rate: High traffic, percentage-based SLAs, variable traffic patterns

🔄 Better Recovery: Consecutive Successes Strategy

The new Consecutive Successes recovery strategy replaces the previous single-success approach, providing more stable recovery behavior.

Configurable Recovery Thresholds

# Require 3 consecutive successful probes before resuming traffic
light = Stoplight("Payment API", recovery_threshold: 3)

# Default behavior (maintains backward compatibility)
light = Stoplight("Payment API")  # recovery_threshold: 1

Benefits

• 🔒 Prevents Flapping: No more rapid red → yellow → red cycles during unstable recovery periods
• ⚡ Still Fast: Healthy services pass multiple probes quickly
• ⚙️ Tunable: Balance stability vs. speed per service
• 🔄 Backward Compatible: Existing code uses recovery_threshold: 1

⚡ Performance Improvements

2.26x Faster Light Creation

We've completely refactored the configuration system, eliminating the ConfigProvider layer and implementing a direct, prototype-based approach:

• Before: 398k light creations/second
• After: 900k light creations/second
• Improvement: 2.26x faster ⚡

🔧 Configuration Enhancements

Self-Validating Configuration

Stoplight now validates configuration compatibility automatically:

# This will raise a helpful error
Stoplight("API", 
  traffic_control: :error_rate,
  threshold: 0.5
  # Missing required window_size!
)

fails with:

Stoplight::TrafficControl::ErrorRate strategy is incompatible with the Stoplight configuration: `window_size` should be set (Stoplight::Error::ConfigurationError)

🔄 Migration Guide

Fully Backward Compatible

No changes required! All existing Stoplight code continues to work exactly as before. The new features are opt-in.

Recommended Upgrades for High-Traffic Services

If you're running high-traffic services, consider migrating to error rate control:

# Before
light = Stoplight("API", threshold: 10, window_size: 300)

# After - error rate approach
light = Stoplight("API", 
  traffic_control: :error_rate,
  window_size: 300,
  threshold: 0.05,  # 5% - set this 2-3x above your normal error rate
  recovery_threshold: 3
)

This will turn Stoplight red when the error rate reaches 5% and will recover after 3 consecutive successful recovery probes.

To choose your threshold: Monitor your service's typical error rate over a few days, then set the threshold 2-3x higher. For example, if your service normally sees 1-2% errors, set the threshold around 0.05 (5%).

---

Upgrade today to take advantage of more intelligent circuit breaking, better performance, and improved reliability!

What's Changed

• Add Public Interface for Traffic Control Strategies Support by @bolshakov in #349
• Simplify Configuration System and Improve Light Creation Performance by @bolshakov in #374
• Add Configurable Consecutive Successes Recovery Strategy by @bolshakov in #375

Full Changelog: v5.1.0...v5.2.0