Current section
Files
Jump to
Current section
Files
src/glimit.erl
-module(glimit).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/glimit.gleam").
-export([new/0, per_second/2, per_second_fn/2, burst_limit/2, burst_limit_fn/2, on_limit_exceeded/2, identifier/2, build/1, apply_built/2, apply/2, apply2/2, apply3/2, apply4/2]).
-export_type([rate_limiter/3, rate_limiter_builder/3]).
-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.
?MODULEDOC(
" This module provides a distributed rate limiter that can be used to limit the\n"
" number of requests or function calls per second for a given identifier.\n"
"\n"
" A single actor is used to assign one rate limiter actor per identifier. The\n"
" rate limiter actor then uses a Token Bucket algorithm to determine if a\n"
" request or function call should be allowed to proceed. A separate process is\n"
" polling the rate limiters to remove full buckets to reduce unnecessary memory\n"
" usage.\n"
"\n"
" The rate limits are configured using the following two options:\n"
"\n"
" - `per_second`: The rate of new available tokens per second. Think of this\n"
" as the steady state rate limit.\n"
" - `burst_limit`: The maximum number of available tokens. Think of this as\n"
" the burst rate limit. The default value is the `per_second` rate limit.\n"
"\n"
" The rate limiter can be applied to a function or handler using the `apply`\n"
" function, which returns a new function that checks the rate limit before\n"
" calling the original function.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.per_second(10)\n"
" |> glimit.burst_limit(100)\n"
" |> glimit.identifier(fn(request) { request.ip })\n"
" |> glimit.on_limit_exceeded(fn(_request) { \"Rate limit reached\" })\n"
"\n"
" let handler =\n"
" fn(_request) { \"Hello, world!\" }\n"
" |> glimit.apply(limiter)\n"
" ```\n"
"\n"
" # Multi-argument functions\n"
"\n"
" `apply` wraps a single-argument function `fn(a) -> b`. To rate-limit a\n"
" function with multiple arguments, use `apply2`, `apply3`, or `apply4`:\n"
"\n"
" ```gleam\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.per_second(10)\n"
" |> glimit.identifier(fn(args: #(String, String)) { args.0 })\n"
" |> glimit.on_limit_exceeded(fn(_args) { too_many_requests() })\n"
"\n"
" let limited_handle =\n"
" handle\n"
" |> glimit.apply2(limiter)\n"
"\n"
" limited_handle(\"user_123\", \"upload\")\n"
" ```\n"
"\n"
).
-type rate_limiter(GAX, GAY, GAZ) :: {rate_limiter,
gleam@erlang@process:subject(glimit@registry:message(GAZ)),
fun((GAX) -> GAY),
fun((GAX) -> GAZ)}.
-type rate_limiter_builder(GBA, GBB, GBC) :: {rate_limiter_builder,
gleam@option:option(fun((GBC) -> integer())),
gleam@option:option(fun((GBC) -> integer())),
gleam@option:option(fun((GBA) -> GBC)),
gleam@option:option(fun((GBA) -> GBB))}.
-file("src/glimit.gleam", 86).
?DOC(" Create a new rate limiter builder.\n").
-spec new() -> rate_limiter_builder(any(), any(), any()).
new() ->
{rate_limiter_builder, none, none, none, none}.
-file("src/glimit.gleam", 114).
?DOC(
" Set the rate of new available tokens per second.\n"
"\n"
" Note that this is not the maximum number of requests that can be made in a single\n"
" second, but the rate at which tokens are added to the bucket. Think of this as the\n"
" steady state rate limit, while the `burst_limit` function sets the maximum number of\n"
" available tokens (or the burst rate limit).\n"
"\n"
" This value is also used as the default value for the `burst_limit` function.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.per_second(10)\n"
" ```\n"
).
-spec per_second(rate_limiter_builder(GBJ, GBK, GBL), integer()) -> rate_limiter_builder(GBJ, GBK, GBL).
per_second(Limiter, Limit) ->
{rate_limiter_builder,
{some, fun(_) -> Limit end},
erlang:element(3, Limiter),
erlang:element(4, Limiter),
erlang:element(5, Limiter)}.
-file("src/glimit.gleam", 136).
?DOC(
" Set the rate limit per second, based on the identifier.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.identifier(fn(request) { request.user_id })\n"
" |> glimit.per_second_fn(fn(user_id) {\n"
" db.get_rate_limit(user_id)\n"
" })\n"
" ```\n"
).
-spec per_second_fn(
rate_limiter_builder(GBS, GBT, GBU),
fun((GBU) -> integer())
) -> rate_limiter_builder(GBS, GBT, GBU).
per_second_fn(Limiter, Limit_fn) ->
{rate_limiter_builder,
{some, Limit_fn},
erlang:element(3, Limiter),
erlang:element(4, Limiter),
erlang:element(5, Limiter)}.
-file("src/glimit.gleam", 159).
?DOC(
" Set the maximum number of available tokens.\n"
"\n"
" The maximum number of available tokens is the maximum number of requests that can be\n"
" made in a single second. The default value is the same as the rate limit per second.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.per_second(10)\n"
" |> glimit.burst_limit(100)\n"
" ```\n"
).
-spec burst_limit(rate_limiter_builder(GCB, GCC, GCD), integer()) -> rate_limiter_builder(GCB, GCC, GCD).
burst_limit(Limiter, Burst_limit) ->
{rate_limiter_builder,
erlang:element(2, Limiter),
{some, fun(_) -> Burst_limit end},
erlang:element(4, Limiter),
erlang:element(5, Limiter)}.
-file("src/glimit.gleam", 182).
?DOC(
" Set the maximum number of available tokens, based on the identifier.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.identifier(fn(request) { request.user_id })\n"
" |> glimit.per_second(10)\n"
" |> glimit.burst_limit_fn(fn(user_id) {\n"
" db.get_burst_limit(user_id)\n"
" })\n"
" ```\n"
).
-spec burst_limit_fn(
rate_limiter_builder(GCK, GCL, GCM),
fun((GCM) -> integer())
) -> rate_limiter_builder(GCK, GCL, GCM).
burst_limit_fn(Limiter, Burst_limit_fn) ->
{rate_limiter_builder,
erlang:element(2, Limiter),
{some, Burst_limit_fn},
erlang:element(4, Limiter),
erlang:element(5, Limiter)}.
-file("src/glimit.gleam", 202).
?DOC(
" Set the handler to be called when the rate limit is reached.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.per_second(10)\n"
" |> glimit.on_limit_exceeded(fn(_request) { \"Rate limit reached\" })\n"
" ```\n"
).
-spec on_limit_exceeded(rate_limiter_builder(GCT, GCU, GCV), fun((GCT) -> GCU)) -> rate_limiter_builder(GCT, GCU, GCV).
on_limit_exceeded(Limiter, On_limit_exceeded) ->
{rate_limiter_builder,
erlang:element(2, Limiter),
erlang:element(3, Limiter),
erlang:element(4, Limiter),
{some, On_limit_exceeded}}.
-file("src/glimit.gleam", 221).
?DOC(
" Set the identifier function to be used to identify the rate limit.\n"
"\n"
" # Example\n"
"\n"
" ```gleam\n"
" import glimit\n"
"\n"
" let limiter =\n"
" glimit.new()\n"
" |> glimit.identifier(fn(request) { request.ip })\n"
" ```\n"
).
-spec identifier(rate_limiter_builder(GDC, GDD, GDE), fun((GDC) -> GDE)) -> rate_limiter_builder(GDC, GDD, GDE).
identifier(Limiter, Identifier) ->
{rate_limiter_builder,
erlang:element(2, Limiter),
erlang:element(3, Limiter),
{some, Identifier},
erlang:element(5, Limiter)}.
-file("src/glimit.gleam", 237).
?DOC(
" Build the rate limiter.\n"
"\n"
" Note that using `apply` will already build the rate limiter, so this function is\n"
" only useful if you want to build the rate limiter manually and apply it to multiple\n"
" functions.\n"
"\n"
" To apply the resulting rate limiter to a function or handler, use the `apply_built`\n"
" function.\n"
).
-spec build(rate_limiter_builder(GDL, GDM, GDN)) -> {ok,
rate_limiter(GDL, GDM, GDN)} |
{error, binary()}.
build(Config) ->
gleam@result:'try'(case erlang:element(2, Config) of
{some, Per_second} ->
{ok, Per_second};
none ->
{error, <<"`per_second` rate limit is required"/utf8>>}
end, fun(Per_second@1) ->
Burst_limit@1 = case erlang:element(3, Config) of
{some, Burst_limit} ->
Burst_limit;
none ->
Per_second@1
end,
gleam@result:'try'(
begin
_pipe = glimit@registry:new(Per_second@1, Burst_limit@1),
gleam@result:map_error(
_pipe,
fun(_) ->
<<"Failed to start rate limiter registry"/utf8>>
end
)
end,
fun(Rate_limiter_registry) ->
gleam@result:'try'(case erlang:element(4, Config) of
{some, Identifier} ->
{ok, Identifier};
none ->
{error,
<<"`identifier` function is required"/utf8>>}
end, fun(Identifier@1) ->
gleam@result:'try'(case erlang:element(5, Config) of
{some, On_limit_exceeded} ->
{ok, On_limit_exceeded};
none ->
{error,
<<"`on_limit_exceeded` function is required"/utf8>>}
end, fun(On_limit_exceeded@1) ->
{ok,
{rate_limiter,
Rate_limiter_registry,
On_limit_exceeded@1,
Identifier@1}}
end)
end)
end
)
end).
-file("src/glimit.gleam", 289).
?DOC(
" Apply the rate limiter to a request handler or function.\n"
"\n"
" This function is useful if you want to build the rate limiter manually using the\n"
" `build` function.\n"
).
-spec apply_built(fun((GEC) -> GED), rate_limiter(GEC, GED, any())) -> fun((GEC) -> GED).
apply_built(Func, Limiter) ->
fun(Input) ->
Identifier = (erlang:element(4, Limiter))(Input),
case begin
_pipe = erlang:element(2, Limiter),
glimit@registry:get_or_create(_pipe, Identifier)
end of
{ok, Rate_limiter} ->
case begin
_pipe@1 = Rate_limiter,
glimit@rate_limiter:hit(_pipe@1)
end of
{ok, nil} ->
Func(Input);
{error, rate_limited} ->
(erlang:element(3, Limiter))(Input);
{error, unavailable} ->
Func(Input)
end;
{error, _} ->
Func(Input)
end
end.
-file("src/glimit.gleam", 273).
?DOC(
" Apply the rate limiter to a request handler or function.\n"
"\n"
" Panics if the rate limiter registry cannot be started or if the `identifier`\n"
" function or `on_limit_exceeded` function is missing.\n"
).
-spec apply(fun((GDW) -> GDX), rate_limiter_builder(GDW, GDX, any())) -> fun((GDW) -> GDX).
apply(Func, Config) ->
Limiter@1 = case build(Config) of
{ok, Limiter} ->
Limiter;
{error, Message} ->
erlang:error(#{gleam_error => panic,
message => Message,
file => <<?FILEPATH/utf8>>,
module => <<"glimit"/utf8>>,
function => <<"apply"/utf8>>,
line => 279})
end,
apply_built(Func, Limiter@1).
-file("src/glimit.gleam", 313).
?DOC(
" Apply the rate limiter to a 2-argument function.\n"
"\n"
" The config's `identifier` and `on_limit_exceeded` receive a `#(a, b)` tuple.\n"
).
-spec apply2(
fun((GEI, GEJ) -> GEK),
rate_limiter_builder({GEI, GEJ}, GEK, any())
) -> fun((GEI, GEJ) -> GEK).
apply2(Func, Config) ->
Wrapped = begin
_pipe = fun(Args) ->
Func(erlang:element(1, Args), erlang:element(2, Args))
end,
apply(_pipe, Config)
end,
fun(A, B) -> Wrapped({A, B}) end.
-file("src/glimit.gleam", 327).
?DOC(
" Apply the rate limiter to a 3-argument function.\n"
"\n"
" The config's `identifier` and `on_limit_exceeded` receive a `#(a, b, c)` tuple.\n"
).
-spec apply3(
fun((GEP, GEQ, GER) -> GES),
rate_limiter_builder({GEP, GEQ, GER}, GES, any())
) -> fun((GEP, GEQ, GER) -> GES).
apply3(Func, Config) ->
Wrapped = begin
_pipe = fun(Args) ->
Func(
erlang:element(1, Args),
erlang:element(2, Args),
erlang:element(3, Args)
)
end,
apply(_pipe, Config)
end,
fun(A, B, C) -> Wrapped({A, B, C}) end.
-file("src/glimit.gleam", 341).
?DOC(
" Apply the rate limiter to a 4-argument function.\n"
"\n"
" The config's `identifier` and `on_limit_exceeded` receive a `#(a, b, c, d)` tuple.\n"
).
-spec apply4(
fun((GEX, GEY, GEZ, GFA) -> GFB),
rate_limiter_builder({GEX, GEY, GEZ, GFA}, GFB, any())
) -> fun((GEX, GEY, GEZ, GFA) -> GFB).
apply4(Func, Config) ->
Wrapped = begin
_pipe = fun(Args) ->
Func(
erlang:element(1, Args),
erlang:element(2, Args),
erlang:element(3, Args),
erlang:element(4, Args)
)
end,
apply(_pipe, Config)
end,
fun(A, B, C, D) -> Wrapped({A, B, C, D}) end.