Module: Stoplight::Domain::_StateStore

Included in:
Infrastructure::FailSafe::Storage::State, Infrastructure::Memory::Storage::State, Infrastructure::Redis::Storage::State, Infrastructure::Storage::CompatibilityState
Defined in:
sig/_private/stoplight/domain/ports/state_store.rbs

Overview

Encapsulates circuit breaker state storage.

State management handles the current operational mode of a circuit breaker:

  • Color (GREEN/YELLOW/RED) - whether the circuit is open or closed
  • Lock state (LOCKED_GREEN/LOCKED_RED/UNLOCKED) - manual overrides
  • State transitions - tracking color changes for notifications #

State requires stronger consistency than metrics because:

  • Multiple instances must agree on circuit color
  • Race conditions during transitions must be handled
  • Lock states must be immediately visible across instances

Instance Method Summary collapse

Instance Method Details

#clear ⇒ void

Note:

This does NOT clear metrics. If you want to fully

This method returns an undefined value.

Clears all state data for this circuit.

This removes the circuit from storage entirely, resetting it to default (unlocked, green) state. The next invocation will start with fresh state.

reset a circuit, clear both state and metrics stores.



76
 
# File 'sig/_private/stoplight/domain/ports/state_store.rbs', line 76

def clear: () -> void

#set_state ⇒ Object

Sets the lock state of the circuit.

Locks allow manual override of circuit behavior:

  • LOCKED_GREEN: Force circuit closed (allow all traffic)
  • LOCKED_RED: Force circuit open (block all traffic)
  • UNLOCKED: Follow normal circuit breaker rules

Lock states take precedence over color states. A locked circuit ignores failure thresholds and stays in the locked state until explicitly unlocked.

Use Cases:

  • Emergency traffic control during incidents
  • Maintenance windows (lock RED to prevent traffic)
  • Gradual rollout (lock GREEN during testing)

Parameters:

  • state —

    The new state to set.

  • (state)

Returns:

  • The state that was set.



44
 
# File 'sig/_private/stoplight/domain/ports/state_store.rbs', line 44

def set_state: (state) -> state

#state_snapshot ⇒ StateSnapshot

Retrieves current state snapshot for decision-making.

The snapshot is an immutable view of the circuit's current state, including its color and lock status. This method is called on every circuit breaker invocation to determine whether to allow traffic.

This is called on every request, so implementations should be fast.

Returns:



24
 
# File 'sig/_private/stoplight/domain/ports/state_store.rbs', line 24

def state_snapshot: () -> StateSnapshot

#transition_to_color ⇒ Object

Note:

In distributed environments with multiple instances, race conditions can occur when instances attempt conflicting transitions simultaneously (e.g., one instance tries to transition from YELLOW to GREEN while another tries YELLOW to RED). The implementation handles this, but be aware that the last operation may determine the final color of the light.

Transitions the Stoplight to the specified color.

This method performs a color transition operation that works across distributed instances of the light. It ensures that in a multi-instance environment, only one instance is considered the "first" to perform the transition (and therefore responsible for triggering notifications).

Parameters:

  • color —

    The target color/state to transition to. Should be one of Stoplight::Color::GREEN, Stoplight::Color::YELLOW, or Stoplight::Color::RED.

  • (color)

Returns:

  • Returns true if this instance was the first to perform this specific transition (and should therefore trigger notifications). Returns false if another instance already initiated this transition.



65
 
# File 'sig/_private/stoplight/domain/ports/state_store.rbs', line 65

def transition_to_color: (color) -> bool