struct

KemalIdentity::Verdict

Whether an attempt may proceed, when to come back if not, and whether the limiter could answer at all.

Three states, because two of them are not the same "no"

A limiter over shared storage has a third thing to say: the store did not answer. Without a way to say it, an adapter whose Redis is down can only lie — report allow and turn rate limiting off under exactly the conditions an attacker can provoke, report deny and take the login endpoint down for everybody, or raise and become a 500. All three are decisions the adapter has no business making on the application's behalf (blueprints/0023-rate-limiter-store-failure.md).

Constructors

allow

Source

deny(retry_after : Time::Span) : self

Source

new(allowed : Bool, retry_after : Time::Span | Nil = nil, unavailable : Bool = false)

Source

unavailable

The store did not answer.

retry_after is deliberately absent: there is no honest number to give when the limiter does not know what has been spent.

Source

Instance methods

allowed?

Whether the attempt may proceed.

False when the store was unavailable. Code that only ever asks this question therefore fails closed on an outage rather than open, which is the safe direction for the one to forget. Ask #unavailable? to tell the two apart.

Source

retry_after

How long until the caller may try again. Set only on a denial.

Telling an honest client when to return is worth more than the little it reveals: the attacker already knows they are being throttled — that is what being throttled means — while a legitimate user staring at "try again later" has no idea whether to wait a second or an hour.

Source

unavailable?

Whether the limiter could not reach its storage, so this attempt was never counted.

Distinct from a denial: a denial says "you have had your share", this says "nobody knows what your share is". They call for opposite responses from an operator — one is working as designed, the other is an incident — and they are not the same event in an audit trail.

Source