Lasier

A sync/async circuit breaker implementation

According to Nygard on your masterpiece book Release It!:

[...] circuit breakers protect overeager gadget hounds from burning their houses down. The principle is the same: detect excess usage, fail first, and open the circuit. More abstractly, the circuit breaker exists to allow one subsystem (an electrical circuit) to fail (excessive current draw, possibly from a short circuit) without destroying the entire system (the house). Furthermore, once the danger has passed, the circuit breaker can be reset to restore full function to the system.

Requirements

• Python >= 3.7

Instalation

Using pip:

pip install lasier

Usage

To use lasier circuit breaker you'll need a rule and a cache (the circuit state storage) instance

Rule

A Rule is the mechanism that define where circuit will open or close.

MaxFailuresRule

Rule to open circuit based on maximum number of failures

from lasier.circuit_breaker.rules import MaxFailuresRule

rule = MaxFailuresRule(
    max_failures=500,
    failure_cache_key='my_cb'
)

Arguments

| Argument | Definition | |----------|------------| | max_failures | Maximum number of errors | | failure_cache_key | Cache key where the number of errors is incremented |

PercentageFailuresRule

Rule to open circuit based on a percentage of failures

from lasier.circuit_breaker.rules import PercentageFailuresRule

rule = PercentageFailuresRule(
    max_failures_percentage=60,
    failure_cache_key='my_cb',
    min_accepted_requests=100,
    request_cache_key='my_cb_request'
)

Arguments

| Argument | Definition | |----------|------------| | max_failures_percentage | Maximum percentage of errors | | failure_cache_key | Cache key where the number of errors is incremented | | min_accepted_requests | Minimum number of requests accepted to not open circuit breaker | | request_cache_key | Cache key where the number of requests is incremented |

Circuit Breaker

You can use the Lasier circuit breaker with a context_manager f.ex:

from lasier.circuit_breaker.sync import CircuitBreaker

...

def some_protected_func():
    with CircuitBreaker(
        rule=rule,
        cache=cache,
        failure_exception=ValueError,
        catch_exceptions=(KeyError, TypeError)
    ):
        # some process

Or a decorator, f.ex:

from lasier.circuit_breaker.asyncio import circuit_breaker

...

@circuit_breaker(
    rule=rule,
    cache=cache,
    failure_exception=ValueError,
    catch_exceptions=(KeyError, TypeError)
)
async def some_protected_func():
    # some process

The sync and async implementations follow the same interface, so you only need to change the import path:

• lasier.circuit_breaker.sync: for sync implementataion
• lasier.circuit_breaker.asyncio: for async implementataion

Arguments

| Argument | Definition | |----------|------------| | rule | Instance of class rule. | | cache | Instance of the circuit breaker state storage. | | failure_exception | Exception to be raised when it exceeds the maximum number of errors and when the circuit is open. | | failure_timeout | This value is set on first error. It is used to validate the number of errors by time. (seconds, default 60) | | circuit_timeout | Time that the circuit will be open. (seconds, default 60) | | catch_exceptions | List of exceptions catched to increase the number of errors. |

WARNING: The args failure_timeout and circuit_timeout will be used on state storage commands so if you'll use libs that expects milliseconds instead of seconds on timeout arguments maybe you'll get yourself in trouble

Circuit state storage

Lasier works with a storage to register the current state of the circuit, number of failures, etc. That storage respects the follow interface:

from lasier.types import Timeout  # Timeout = Optional[Union[int, float]]


class Storage:

    def add(self, key: str, value: int, timeout: Timeout = None) -> None:
        pass

    def set(self, key: str, value: int, timeout: Timeout = None) -> None:
        pass

    def incr(self, key: str) -> int:
        pass

    def get(self, key: str) -> int:
        pass

    def expire(key: str, timeout: Timeout = None) -> None:
        pass

    def delete(self, key: str) -> None:
        pass

    def flushdb(self) -> None:
        pass

For async circuit breaker, lasier works with that same interface however with async syntax, f.ex: async def set(self, key=str, value=int, timeout=Optional[int])

So you can use any cache/storage that respects that interface.

Adapters

If you'll use Lasier with redis-py as cache, you can use lasier.adapters.caches.redis.RedisAdapter

from lasier.adapters.caches import RedisAdapter
from redis import Redis

cache = RedisAdapter(Redis(host='localhost', port=6479, db=0))

Implemented Adapters

| Lib | Adapter | |--------------------| --------------------------------------------- | | redis-py | lasier.adapters.caches.RedisAdapter | | django-cache | lasier.adapters.caches.DjangoAdapter | | django-cache-async | lasier.adapters.caches.DjangoAsyncAdapter | | aiocache | lasier.adapters.caches.AiocacheAdapter |