Creating Backends
See Hammer.Backend.ETS
for a realistic example of a Hammer Backend module.
Backends for Hammer are expected to implement
the Hammer.Backend behaviour, under the name
Hammer.Backend.Foo
, and to provide a Supervisor module under the name
Hammer.Backend.Foo.Supervisor
.
The Hammer.Backend
behaviour
The expected backend api is as follows:
start_link(args)
args
: Keyword list of configuration.
The expiry_ms
and cleanup_interval_ms
keys are considered essential, as the
backend process should delete expired buckets somehow. Other keys are for the
backend developer to choose, but for example, if the backend were using a
database called FooDB
to store buckets, then an appropriate key would be
foodb_config
.
Example:
Hammer.Backend.Foo.start_link(expiry_ms: 60_000 * 60,
cleanup_interval_ms: 60_000 * 10,
foodb_config: [host: "localhost"])
count_hit(key, timestamp)
key
: The key of the current bucket, in the form of a tuple{bucket::integer, id::String}
.timestamp
: The current timestamp (integer)
This function should increment the count in the bucket by 1.
Returns: Either a Tuple of {:ok, count}
where count is the current count of the bucket,
or {:error, reason}
.
get_bucket(key)
key
: The key of the current bucket, in the form of a tuple{bucket::integer, id::String}
.
Returns: Either a tuple of {:ok, bucket}
, where bucket
is a tuple of
{key, count, created_at, updated_at}
, key is, as usual, a tuple of {bucket_number, id}
,
count
is the count of hits in the bucket, created_at
and updated_at
are integer timestamps,
or {:error, reason}
delete_buckets(id)
id
: rate-limit id (string) to delete
This should delete all existing buckets associated with the supplied id
.
Returns: Either {:ok, count}
, or {:error, reason}
The Supervisor
The supervisor module should implement a start_link/2
with the following signature:
start_link(config::Keyword.t, options::Keyword.t)
It should start and supervise whichever processes are required to make the backend work.
The config
parameter is the backend-specific keyword-list which is the second
element in the :backend
configuration tuple. The options
parameter is a
keyword-list of Supervisor options, and should generally be passed straight
through as the third argument to Supervisor.start_link
.
Again, the source-code for the Hammer.Backend.ETS
and
Hammer.Backend.ETS.Supervisor
modules are great examples of how to implement a
backend.