Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History
New Proposal Template
This page has been created from a template that uses "zones." To proceed:
  1. Edit the page
  2. Replace sample content within each zone-data tag with your own content
  3. Remove this notice
  4. Save the page
  5. When you are ready for community review, move this page to the Ready for Review section on the edit page.
    No placeholders allowed!
    Please do not create placeholders. Wait until you have sufficient content to replace all sample data in the proposal template before creating your proposal document.

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_CircuitBreaker Component Proposal

Proposed Component Name Zend_CircuitBreaker
Developer Notes
Proposers Artur Ejsmont
Zend Liaison TBD
Revision 1.0 - 20 November 2010: Initial Draft. (wiki revision: 10)

Table of Contents

1. Overview

Circuit Breaker is a component that helps discovering externals resources failures and adapting application behavior.

If my database is overloaded and times out after 30s or a web service is broken i do not want to waste time connecting to it. I prefer to use long lived cache or even show a user friendly message instead.

Circuit breaker helps by encapsulating this logic and allowing developers to simply ask "is my resource available?" before using it. CB manages statistical data to give the appropriate answer.

Statistical data is stored using persistence adapter as an internal data structure. This information is gathered after every request to the external service so that CB would know is the external service healthy or not. Storage and retrieval of the data has to be very fast (apc/memcached preferred).

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component will allow configuration of thresholds per service name.
  • This component will allow configuration via array/config object.
  • This component will allow replacement of persistence storage adapters.
  • This component will provide persistence storage adapters for zend cache, dummy and database.
  • This component will keep very simple API.
  • This component will be ported to ZF2 as soon as zend cache 2 is fully implemented.

4. Dependencies on Other Framework Components

  • Zend_Exception
  • Zend_Cache - optional, you can provide your own Zend_CircuitBreaker_Storage_Interface implementations.

5. Theory of Operation

This component should be used close to the service call implementation. To decrease code duplication and end user envolvment it would be beneficial to create decorators (or some extensions) to database and web service components. This way calls to Circuit breaker could be handed by Zend Framework. It is not required for a standalone use though.


  • User calls Circuit breaker to ask is service named 'ABC' available?
  • Circuit breaker responds true if service is available or false if its considered unavailable
  • User calls service based on the advice
  • After service call user reports back to circuit breaker to let it know was service call successful or not.

This way CB can set thresholds of amount of failed requests in period of time. If requests were failing lately CB can start advising that service is unavailable. Therefor user code can skip service call and branch execution straight to error handling. User can also decide to use long lived cache in this scenario or take other actions necessary.

Diagram of class dependencies can be seen below. Circuit breaker delegates persistence to selected adapter type. It can also use array decorator to group all service statistics into one array - to reduce persistence storage load/save calls.

Service back online discovery.

Circuit breaker comes with an important feature of probing for service avability. Once service is recognized as unavailable CB will allow single thread to try to use it based on configuration. This way you can configure retry to happen after 1,5,60 minutes or whatever value in seconds. CB will make sure just one thread will try to connect, if it succeeds it will allow rest of the threads to connect too. Otherwise it will keep service locked till next retry timeout.

6. Milestones / Tasks

Describe some intermediate state of this component in terms of design notes, additional material added to this page, and / code. Note any significant dependencies here, such as, "Milestone #3 can not be completed until feature Foo has been added to ZF component XYZ." Milestones will be required for acceptance of future proposals. They are not hard, and many times you will only need to think of the first three below.

  • Milestone 1: design notes will be published here
  • Milestone 2: Working prototype checked into the incubator supporting use cases #1, #2, ...
  • Milestone 3: Working prototype checked into the incubator supporting use cases #3 and #4.
  • Milestone 4: Unit tests exist, work, and are checked into SVN.
  • Milestone 5: Initial documentation exists.

If a milestone is already done, begin the description with "[DONE]", like this:

  • Milestone #: [DONE] Unit tests ...

7. Class Index

  • Zend_CircuitBreaker_Interface
  • Zend_CircuitBreaker
  • Zend_CircuitBreaker_Storage_Interface
  • Zend_CircuitBreaker_Storage_Exception
  • Zend_CircuitBreaker_Storage_Adapter_Dummy
  • Zend_CircuitBreaker_Storage_Adapter_ZendCacheBackend
  • Zend_CircuitBreaker_Storage_Decorator_Array
  • Zend_CircuitBreaker_Storage_Adapter_Apc (optionally for performance and simplicity)

8. Use Cases


... (see good use cases book)


9. Class Skeletons



Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.