# Valve

An Elixir Plug to rate-limit requests to your web app.

## Installation

Add `valve` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [{:valve, "~> 0.2.0"}]
end
```

Then plug it in your pipeline:

```elixir
defmodule MyApp.Router do
  use MyApp, :router

  # ...

  pipeline :api do
    plug Valve

    # ...
  end
```

The default behavior when reaching the maximum number of requests allowed is to return an [`HTTP 429 (Too Many Requests)`](https://httpstatuses.com/429) with a `Retry-After` header.
This can be overridden by passing an `on_flood` option to the plug:

```elixir
plug Valve, on_flood: fn (conn, retry_after) -> put_status(conn, 418) |> halt() end
```

## Configuration

Put this in your config:

```elixir
config :valve,
  rate: {10, 60}, # Give 10 tokens every 60 second
  max_tokens: 20, # Give at most 20 tokens (also give 20 tokens initially)
  pool_size: 8, # Number of Valve.Store processes (how many requests can be handled simultaneously)
  store: Valve.Store.ETS # The storage adapter used to store buckets (you'll need to recompile the library if you change this)
```


## Storage adapters

For now there's only an ETS backend (`Valve.Store.ETS`), contributions are welcome!

### ETS

```elixir
config :valve, Valve.Store.ETS,
  table: :my_table, # Defaults to `:valve`
  ttl: 48 * 3_600, # How much time (in seconds) before an entry should get swept (defaults to a day)
  sweep_interval: 7_200 * 1000 # How often (in milliseconds) should stale entries be cleaned (defaults to an hour)
```