seki (seki v0.4.3)

View Source

Main API for Seki resilience primitives.

Provides rate limiting with four algorithms (token bucket, sliding window, GCRA, leaky bucket), circuit breaking with configurable failure/slow-call thresholds, and a combined execute/3 that checks rate limits before calling through a breaker.

Erlang

seki:new_limiter(my_api, #{algorithm => sliding_window, limit => 100, window => 60000}).
seki:check(my_api, UserId).

Elixir

:seki.new_limiter(:my_api, %{algorithm: :sliding_window, limit: 100, window: 60_000})
:seki.check(:my_api, user_id)

Summary

Types

algorithm()
breaker_name()
breaker_opts()
call_result()
check_result()
key()
limiter_name()
limiter_opts()

Functions

call(Name, Fun)

Execute a function through a circuit breaker.

call(Name, Fun, CallOpts)

Execute a function through a circuit breaker with options.

check(Name, Key)

Check if a request is allowed for the given key (cost = 1).

check(Name, Key, Cost)

Check if a request with a custom cost is allowed for the given key.

delete_adaptive(Name)

Stop and remove a supervised adaptive concurrency limiter.

delete_breaker(Name)

Delete a circuit breaker and stop its process.

delete_bulkhead(Name)

Stop and remove a supervised bulkhead.

delete_health(Name)

Stop and remove a supervised health checker.

delete_limiter(Name)

Delete a rate limiter and clean up its backend state.

delete_shed(Name)

Stop and remove a supervised load shedder.

execute(Breaker, Limiter, Fun)

Check rate limit then execute through circuit breaker. Returns {error, {rate_limited, Info}} if denied.

inspect(Name, Key)

Non-destructive check — read current state without consuming tokens.

inspect(Name, Key, Cost)

Non-destructive check with a custom cost.

new_adaptive(Name, Opts)

Start a supervised adaptive concurrency limiter.

new_breaker(Name, Opts)

Create a new circuit breaker with the given options.

new_bulkhead(Name, Opts)

Start a supervised bulkhead.

new_health(Name, Opts)

Start a supervised health checker.

new_limiter(Name, Opts)

Create a new rate limiter with the given algorithm and options.

new_shed(Name, Opts)

Start a supervised load shedder.

reset(Name, Key)

Reset the rate limit state for a key.

reset_breaker(Name)

Reset a circuit breaker to closed state.

state(Name)

Get the current state of a circuit breaker.

Types

algorithm()

-type algorithm() :: token_bucket | sliding_window | gcra | leaky_bucket.

breaker_name()

-type breaker_name() :: atom().

breaker_opts()

-type breaker_opts() ::
          #{window_type => count | time,
            window_size => pos_integer(),
            failure_threshold => 1..100,
            slow_call_threshold => 1..100,
            slow_call_duration => pos_integer(),
            wait_duration => pos_integer(),
            half_open_requests => pos_integer(),
            error_classifier => fun((term()) -> boolean())}.

call_result()

-type call_result() :: {ok, term()} | {error, circuit_open} | {error, term()}.

check_result()

-type check_result() ::
          {allow, #{remaining := non_neg_integer(), reset := non_neg_integer()}} |
          {deny, #{retry_after := non_neg_integer()}}.

key()

-type key() :: term().

limiter_name()

-type limiter_name() :: atom().

limiter_opts()

-type limiter_opts() ::
          #{algorithm := algorithm(),
            limit := pos_integer(),
            window := pos_integer(),
            burst => pos_integer(),
            backend => module(),
            backend_opts => map()}.

Functions

call(Name, Fun)

-spec call(breaker_name(), fun(() -> term())) -> call_result().

Execute a function through a circuit breaker.

call(Name, Fun, CallOpts)

-spec call(breaker_name(), fun(() -> term()), map()) -> call_result().

Execute a function through a circuit breaker with options.

check(Name, Key)

-spec check(limiter_name(), key()) -> check_result().

Check if a request is allowed for the given key (cost = 1).

check(Name, Key, Cost)

-spec check(limiter_name(), key(), pos_integer()) -> check_result().

Check if a request with a custom cost is allowed for the given key.

delete_adaptive(Name)

-spec delete_adaptive(atom()) -> ok | {error, term()}.

Stop and remove a supervised adaptive concurrency limiter.

delete_breaker(Name)

-spec delete_breaker(breaker_name()) -> ok | {error, term()}.

Delete a circuit breaker and stop its process.

delete_bulkhead(Name)

-spec delete_bulkhead(atom()) -> ok | {error, term()}.

Stop and remove a supervised bulkhead.

delete_health(Name)

-spec delete_health(atom()) -> ok | {error, term()}.

Stop and remove a supervised health checker.

delete_limiter(Name)

-spec delete_limiter(limiter_name()) -> ok.

Delete a rate limiter and clean up its backend state.

delete_shed(Name)

-spec delete_shed(atom()) -> ok | {error, term()}.

Stop and remove a supervised load shedder.

execute(Breaker, Limiter, Fun)

-spec execute(breaker_name(), limiter_name(), fun(() -> term())) ->
                 call_result() | {error, rate_limited}.

Check rate limit then execute through circuit breaker. Returns {error, {rate_limited, Info}} if denied.

inspect(Name, Key)

-spec inspect(limiter_name(), key()) -> check_result().

Non-destructive check — read current state without consuming tokens.

inspect(Name, Key, Cost)

-spec inspect(limiter_name(), key(), pos_integer()) -> check_result().

Non-destructive check with a custom cost.

new_adaptive(Name, Opts)

-spec new_adaptive(atom(), map()) -> {ok, pid()} | {error, term()}.

Start a supervised adaptive concurrency limiter.

new_breaker(Name, Opts)

-spec new_breaker(breaker_name(), breaker_opts()) -> {ok, pid()} | {error, term()}.

Create a new circuit breaker with the given options.

new_bulkhead(Name, Opts)

-spec new_bulkhead(atom(), map()) -> {ok, pid()} | {error, term()}.

Start a supervised bulkhead.

new_health(Name, Opts)

-spec new_health(atom(), map()) -> {ok, pid()} | {error, term()}.

Start a supervised health checker.

new_limiter(Name, Opts)

-spec new_limiter(limiter_name(), limiter_opts()) -> ok | {error, term()}.

Create a new rate limiter with the given algorithm and options.

new_shed(Name, Opts)

-spec new_shed(atom(), map()) -> {ok, pid()} | {error, term()}.

Start a supervised load shedder.

reset(Name, Key)

-spec reset(limiter_name(), key()) -> ok.

Reset the rate limit state for a key.

reset_breaker(Name)

-spec reset_breaker(breaker_name()) -> ok.

Reset a circuit breaker to closed state.

state(Name)

-spec state(breaker_name()) -> closed | open | half_open.

Get the current state of a circuit breaker.