feat: circuit breaker implementation

[SkArchon]

Motivation and Context

This will add circuit breakers to the router. Circuit breakers are off by default, including metrics that are off by default.
We group subgraphs not by the name/id, but instead the routing url, and we create a circuit breaker per every single unique routing url. We use the full url, this means that

subgraph1: host.com/url1
subgraph2: host.com/url1
subgraph3: host.com/url2

would result in two circuit breakers, since we consider the entire url.

User's can however force subgraph1 and subgraph2 to use two separate circuit breakers by specifying circuit breaker configurations at the per subgraph level.

Example configuration

Global config only

traffic_shaping: 
  all: 
    circuit_breaker:
      enabled: true
      num_buckets: 100
      ...

Subgraph disable for subgraph 5

traffic_shaping:
  all:
    circuit_breaker:
      enabled: true
      ...
  subgraphs:
    subgraph5:
      circuit_breaker:
        enabled: false

Subgraph overrides
Even when the routing url is the same, this will result in separate circuit breakers being created

traffic_shaping:
  all:
    circuit_breaker:
      enabled: true
  subgraphs:
    subgraph1:
      circuit_breaker:
        enabled: true
    subgraph2:
      circuit_breaker:
        enabled: true

Options Included

This PR includes a configurable circuit breaker with the following configurations

• error_threshold_percentage: The error threshold that needs to be reached to trip / open the circuit breaker.
• request_threshold: How many requests are needed in minimum TO START deciding if the circuit breaker should be opened or not.
• sleep_window: The window after the circuit breaker tripped that it definitely does not accept any requests
• half_open_attempts: How many failed attempts are allowed after the sleep window before preventing any requests
• required_successful: How many successful attempts are required to change the circuit breaker from half open to required successful
• rolling_duration: The duration of the sliding window
• num_buckets: How many buckets are allocated for the sliding window duration, requests are put into each bucket, which will be evicted eventually as the window rolls forward
• execution_timeout: Execution timeout, how long the circuit breaker should wait before timing out, these are counted as errors
• max_concurrent_requests: The maximum number of concurrent requests that are allowed on the circuit breaker, -1 results in disabling this

In addition to this the PR introduces the following metrics

• router.circuit_breaker.state: This shows the state of the circuit breaker, sliced by feature-flag and subgraph.
• router.circuit_breaker.short_circuits: This indicates the number of requests that were not even executed because of the open circuit breaker, sliced by feature-flag and subgraph

Docs PR: https://github.com/wundergraph/cosmo-docs/pull/104/files

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/cosmo-docs.
• I have read the Contributors Guide.

Summary by CodeRabbit

Summary by CodeRabbit

• New Features

  • Introduced configurable circuit breaker support for subgraph requests, allowing granular control over error thresholds, request limits, and recovery behavior.
  • Added metrics and observability for circuit breaker state and short-circuit events, with support for OpenTelemetry and Prometheus.
  • Enabled per-subgraph circuit breaker configuration via new configuration options and schema.
  • Integrated circuit breaker logic into the request pipeline and HTTP transport for improved resilience.
  • Added circuit breaker management supporting grouping by routing URLs and feature flag scoping.

• Tests

  • Added comprehensive integration tests to validate circuit breaker behavior, state transitions, feature flag handling, and metrics emission.
  • Added configuration schema validation tests for circuit breaker settings.
  • Added unit tests for circuit breaker manager and routing URL grouping logic.

• Documentation

  • Updated configuration schema and example files to illustrate new circuit breaker settings.

[github-actions]

Router image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-5e078dde203921be1aa911275854af04b735409b

[SkArchon]

@coderabbitai resolve

[coderabbitai]

✅ Actions performed

Comments resolved.