Introduction

This is a specification that delineates how an arbitrary HTTP client should communicate with a circuit breaker so that it can know when to retry requests while the circuit breaker is in an OPEN (i.e. full-open & half-open) state and when the circuit breaker transitions to a CLOSED state. Remember, the circuit breaker is a reverse proxy that forwards requests to a target server/service in such a way that does not require the HTTP client to blindly send retry requests.

There are 2 ways in which the circuit breaker (reverse proxy) can communicate with the target service as follows:

1. Request-Response: This includes either using HTTP with a JSON data exchange format or using GRPC with a PROTOBUF data exchange format over TCP.
2. Producer-Consumer: This includes using a message queue (e.g. Kafka, ZMQ or RabbitMQ) with a AMQP/MQTT/STOMP data exchange format over TCP/UDP.

Request Headers

• X-Relay-Ready-For: This header is used to specify the service name of the circuit breaker server in the CLOSED state which the HTTP client is communicating to.
• X-Relay-Mode: This header is used in conjunction with the X-Relay-Ready-For to communicate the mode the circuit breaker in the CLOSE state MUST utilise to relay requests to the target server/service.
• X-Retry-Ready-For: This header is used to specify the service name of the circuit breaker server possibly in the OPEN state which the HTTP client is communicating to.
• X-Retry-Mode: This header is used in conjunction with the X-Retry-Ready-For to show the mode the circuit breaker server possibly in the OPEN state MUST utilise to retry requests to the target server/service.

The X-Relay-Mode HTTP request header has 2 valid values: r-r and p-c. The r-r value stands for request-response and the p-c value stands for producer-consumer.

The X-Retry-Mode HTTP request header has only 1 valid value: r-r. The r-r value stands for request-response also.

Response Headers

• X-Retry-Later-For: This header is used to specify the service name of the circuit breaker server that is in a CLOSED state.
• X-Retry-Delay: This header is used optionally in conjunction with the X-Retry-Later-For header to specify how long since the last HTTP response from the circuit breaker server that the HTTP client is to wait before it can make a fresh request to check the state of the same circuit breaker service.
• X-Retry-Status: This header is used in conjunction with the X-Retry-Delay header to specify what the status of the retry effort on the circuit breaker server is based on the state of the circuit breaker server.
• X-Relay-Status: This header is used in response to a http request containing the X-Relay-Ready-For and X-Relay-For headers received by the circuit breaker server in the CLOSED state to communicate the status of a relay to the target server/service.

The X-Retry-Status HTTP response header has 2 valid values: ok and not-ok. When the value is ok, the X-Relay-Delay is not a required HTTP response header in the same response. The ok value stands for okay and the not-ok value stands for not-okay.

The X-Relay-Status HTTP response header has 3 valid values: rejected, accepted and declined.