Rate limiting

This page explains how Behemoth limits repeated attempts, which limits exist by default, and how to change them or add your own. Read Routes and requests first.

Sign-in and sign-up are limited by default. Each client address gets 10 attempts a minute per method. Plugins add limits for their own flows, such as password reset and magic links. You do not need to configure anything to have them.

How a limit works #

A rate limit allows a number of attempts for each key in a time window. The key says what is counted per: a client address, an email address, or a user. The window opens with the first attempt, and the count starts again when the window has passed. This is a fixed window, the only algorithm Behemoth has.

When an attempt goes over the limit, Behemoth refuses it before the operation runs:

  • The response is 429 with the code rate_limited.
  • The Retry-After header says how many seconds are left in the window, rounded up.
  • The first refusal in a window is recorded as a ratelimit.exceeded audit event. Later refusals in the same window are counted in the behemoth.ratelimit.checks metric and not recorded again.

Behemoth counts an attempt before the operation runs, so an attempt that succeeds counts like one that fails.

Default limits #

Behemoth itself declares these rules:

RuleLimitsDefault
engine.RuleSignInAddressSign-ins per client address and method10 a minute
engine.RuleSignUpAddressSign-ups per client address and method10 a minute
engine.RuleSessionTokenAddressSession token requests per client address30 a minute

Plugins declare their own rules, and each plugin's reference page lists them. For example, the email and password plugin limits password reset requests per client address and per email address. Every rule has a name, which you use to change it.

Two kinds of rules #

A rule is attached either to an HTTP route or to a hook point. The kinds differ in what they limit:

Route ruleHook rule
LimitsRequests to an HTTP pathAn operation, whoever calls it: a route, a command-line tool, or a background job
Attached toA method and a path, relative to the base pathA before hook point, such as auth.signIn.before
Counts perWhat your function returns from the request and the client addressWhat your function returns from the operation's values and the caller
When several matchThe most specific rule appliesEvery rule on the point applies, and all must pass
Use it forA route that fires no hook point, such as a check that a username is freeEverything else

Prefer a hook rule when the operation has a before point. It holds when someone calls the flow from your own code, and not only over HTTP. A rule that counts per client address skips a call that has no address, such as one from a command-line tool.

Where counters live #

By default, Behemoth keeps its counters in the rate_limits table of your database. If you configured a key-value store in BootConfig.KV, such as Redis, the counters live there instead. Both are shared by every instance of your application, so a limit holds across replicas.

If the counter store is unreachable, RateLimitConfig.FailureMode decides what happens:

  • core.FailOpen (the default) lets the request through and logs a warning. Users keep signing in during an outage.
  • core.FailClosed refuses the request. Choose it if letting an attacker through is worse than turning users away.

Behemoth never removes old counters in the database by itself. Call Store.Purge from a scheduled job. See Remove old rows.

Change or turn off a limit #

Set BootConfig.RateLimit to change the limit of a rule by its name, or to turn the rule off:

go
ac, err := engine.Boot(
    ctx,
    app,
    db,
    engine.BootConfig{
        Crypto: cryptoCfg,
        RateLimit: core.RateLimitConfig{
            Limits: map[string]core.Limit{
                engine.RuleSignInAddress: {
                    Max:    20,
                    Window: time.Minute,
                },
            },
            Disabled: []string{
                magiclink.RuleRequestAddress,
            },
        },
    },
)
if err != nil {
    log.Fatal(err)
}

Only the numbers change. The key, the point, and the algorithm stay as declared. Boot fails on a name that no rule has, so a misspelled name shows up at startup. A disabled route rule leaves its routes without a limit.

Write your own rule #

A plugin declares its rules, so they take part in Prepare and can be changed by name like the others.

Limit an operation #

Declare a hook rule in the plugin's Declare method. The following rule allows five sign-in attempts a minute per email address:

go
func (p *Plugin) Declare(ic *core.PluginInitContext) error {
    return ic.RateLimits.DeclareHookRateLimitRule(
        core.HookRateLimitRule{
            Name:    "myplugin.signin.email",
            Point:   hooks.HookSignInBefore,
            KeyFunc: core.KeyByValues(hooks.HookValueEmail),
            Limit:   core.Limit{Max: 5, Window: time.Minute},
        },
    )
}

The key function receives the hook context. core.KeyByValues builds a key from values that the operation publishes before it runs, such as the email of a sign-in. core.KeyByClientIP keys on the caller's address. A rule whose key is missing, for example a sign-in without an email, does not apply to that call. The Hooks reference lists the values each point publishes.

A limit per account can lock the owner out

A limit keyed on the email lets anyone use up an account's attempts and keep its owner out for the window. That is why the built-in sign-in limit is per client address. Weigh the two before you key on an email or a user.

Limit a path #

For a route that fires no hook point, return route rules from the RouteRateLimitRules method of your plugin. The rule's path is relative to the base path and includes the plugin's mount path. A segment * matches one segment, and a last segment ** matches any number.

go
func (p *Plugin) RouteRateLimitRules() []httpapi.RouteRateLimitRule {
    return []httpapi.RouteRateLimitRule{
        {
            Name:   "myplugin.lookup.route",
            Method: http.MethodPost,
            Path:   "/myplugin/lookup",
            KeyFunc: func(_ *http.Request, ip string) string {
                return ip
            },
            Limit: core.Limit{Max: 30, Window: time.Minute},
        },
    }
}

Behind a proxy #

Most default limits count per client address. If your application runs behind a load balancer and you have not set RouterConfig.TrustedProxies, every client appears to come from the balancer. One client's failed attempts can then limit everyone. See The client's address.

Limits #

  • A fixed window is the only algorithm. A client can make a full set of attempts at the end of one window and another at the start of the next.
  • A rule can only refuse. A lockout that blocks a key for a longer time after a limit is not available. A rule that sets one is rejected when your application prepares.
  • Hook rules attach to before points only.

Next steps #

To go deeper, read the following pages: