[httpapi] other algorithms and ratelimit headers

[Tony Finch <[e-mail]>]

I've been experimenting with the RateLimit header and a few different rate
limiting algorithms. The current spec seems reasonably adaptable, but I
had to read it in a creative manner to make it work with other algorithms.

There are a number of places in the draft that seem to exclude rate
limiting algorithms that incrementally adjust a quota or a measured rate.
This is most obvious in the "reset parameter" whose name doesn't make
sense for rate limit algorithms such as GCRA that do not reset quotas.
It's true there are also a number of places in the draft that say the
reset parameter doesn't necessarily behave as a reset time, but that seems
like an obtuse way to specify it.

I suggest rephrasing the semantics in terms of how the server is
asking the client to behave, in general terms.

In section 4, the term "reset time" implies far too much about how the
server might behave, and "remaining quota" implies the quota goes
down. (Some rate limit algorithms such as GCRA can gradually increase
`r` when the client's rate is below its limit.)

I suggest calling `r` and `t` the "available quota" and "effective
window", i.e. the quota and window that currently apply to this
client. This choice of words is supposed to imply that the `r` quota
and `t` window can be dynamically adjusted.

For instance, section 2 might be rephrased like:

  * Quota:

    A quota is an allocation of capacity that a server uses to limit
    client requests. That capacity is measured in quota units that clients
    can consume within a time window.

  * Service Limit:

    A service limit is the currently available quota under a specific
    quota policy and, if defined, the effective time window within
    which the client can use no more than the available quota

Some wording suggestions for section 4:

>   * r: This REQUIRED parameter value conveys the available quota for
>     the identified policy (Section 4.1.1).
>
>   * t: This OPTIONAL parameter value conveys the effective window
>     within which the client can use no more than the available quota
>     (Section 4.1.2).
>
> ...
>
> 4.1.1. Available Quota Parameter
>
> The "r" parameter indicates the quota units that are currently
> available to use.
>
> It is a non-negative Integer expressed in quota units. The server MAY
> arbitrarily alter the available quota parameter value between
> subsequent requests. Clients MUST NOT assume that a positive remaining
> value is a guarantee that further requests will be served. When the
> remaining parameter value is low, it indicates that the server may
> soon throttle the client (see Section 6).
>
> ...
>
> 4.1.2. Effective Window Parameter
>
> The "t" parameter indicates the number of seconds within which the
> client MUST NOT try to consume more than the available quota "r".
>
> ...
>
> The server MAY arbitrarily alter the available quota and effective
> window parameter values between subsequent requests; for example, in
> case of resource saturation or to implement sliding window policies.
>
> The client can expect that more quota units will be available at the
> end of the effective window, but MUST NOT assume that its full quota
> will be restored.

## server behaviour: retry-after

> If a response contains both the Retry-After and the RateLimit header
> fields, the Retry-After field value SHOULD NOT reference a point in
> time earlier than the reset parameter.

Is it guaranteed that a Retry-After header is caused by a RateLimit
policy violation? What about headers that indicate there's plenty of
ratelimit quota remaining but the server wants the client to try later
for some other reason?

        Retry-After: 30
        Ratelimit: "spqr";r=1000;t=100

It would make sense to me if Retry-After has to be at least as late as
the RateLimit t= effective window when the available quota r= is zero,
but can be anything when the available quota r > 0.

## server behaviour: ratelimit vs ratelimit-policy

> A service using RateLimit header fields MUST NOT convey values
> exposing an unwanted volume of requests

Would it make sense to be more specific here, e.g. recommending that
the RateLimit r=;t= values should be less than the RateLimit-Policy
q=w= values?


## miscellaneous nits


### introduction

The headers allow multiple policies, so I suggest pluralizing the
summaries like:

  * RateLimit-Policy: quota policies, defined by the server, that
    client HTTP requests will consume.

  * RateLimit: currently remaining quota available for specific
    policies.

### notational conventions

The list of terms from [SF] is missing Parameters, Byte Sequence, String


-- 
Tony Finch  <[e-mail]>  https://dotat.at/
Malin, Hebrides: Cyclonic 5 to 7, occasionally gale 8 later in Malin,
perhaps gale 8 later in Hebrides. Rough or very rough. Occasional
rain. Good, occasionally poor.