# ReqFuse
<object data="assets/logo.png" type="image/jpeg">
<img src="assets/fuse.png" alt="ReqFuse fuses" />
</object>
ReqFuse on Github https://github.com/carsdotcom/req_fuse
ReqFuse on Hex https://hex.pm/packages/req_fuse
ReqFuse on HexDocs https://hexdocs.pm/req_fuse
[![CI](https://github.com/carsdotcom/req_fuse/actions/workflows/elixir.yml/badge.svg)](https://github.com/carsdotcom/req_fuse/actions/workflows/elixir.yml)
<!-- MDOC -->
[Req](https://github.com/wojtekmach/req) plugin for [`:fuse`](https://github.com/jlouis/fuse)
ReqFuse provides circuit-breaker (or load-shedding) functionality for HTTP requests that use the Req library.
## Usage
After adding the dependencies, simply attach the ReqFuse step to your request ensuring
you are passing in the required and any optional fuse configuration.
```elixir
Mix.install([
{:req, "~> 0.3"},
{:req_fuse, "~> 0.2"}
])
req_fuse_opts = [fuse_name: My.Example.Fuse]
req = [url: "https://httpstat.us/500", retry: :never]
|> Req.new()
|> ReqFuse.attach(req_fuse_opts)
# Fire the request enough times to melt the fuse
Enum.each(0..10, fn _ -> Req.request(req) end)
=> :ok
Req.request(req)
=> 08:45:42.518 [warning] :fuse circuit breaker is open; fuse = Elixir.My.Example.Fuse
=> {:error, %RuntimeError{message: "circuit breaker is open"}}
```
## Installation
If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `req_fuse` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:req_fuse, ">= 0.2.0"}
]
end
```
<!-- MDOC -->
## Twiddling the Knobs
Attach the circuit-breaker :fuse step and configure the available options
### Fuse Options
- `:fuse_melt_func` - A 1-arity function to determine if response should melt the fuse
defaults to `ReqFuse.Steps.Fuse.melt?/1`
- `:fuse_mode` - how to query the fuse, which has two values:
- `:sync` - queries are serialized through the `:fuse_server` process (the default)
- `:async_dirty` - queries check the fuse state directly, but may not account for recent melts or resets
- `:fuse_name` - **REQUIRED** the name of the fuse to install
- `:fuse_opts` The fuse _strategy_ options (see [fuse docs](https://hexdocs.pm/fuse/fuse.html#types) for reference) (order matters)
See `ReqFuse.Steps.Fuse.defaults/0` for more information.
- `:fuse_verbose` - If false, suppress Log output
See https://github.com/jlouis/fuse#tutorial for more information about the supported fuse
strategies and their options.
See also the additional discussion on options in `ReqFuse.Steps.Fuse`
## License
See [LICENSE](https://github.com/carsdotcom/req_fuse/blob/main/LICENSE)
## Updates
See [CHANGELOG.md](https://github.com/carsdotcom/req_fuse/blob/main/CHANGELOG.md)
Updating the changelog. (Uses `auto-changelog`)
https://github.com/cookpete/auto-changelog
`auto-changelog --breaking-pattern "BREAKING CHANGE" --template keepachangelog --commit-limit false --unreleased`
### Tagging by version in mix.exs
```
git tag `grep -e '@version \"\d\.\d\.\d\".*' mix.exs | awk '{gsub(/"/, "", $2); print $2}'`
```