Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: moves quota - policies from RateLimit - Limit -RateLimit - Policyrequires WG discussion - 
 Given this hint from  I think it 's fine to merge this PR ( separate  from Limit ) since there seems to be agreement to use different fields at least in this case . 
 Perhaps best to continue discussion in that issue before merging this ? While the change will happen in a similar vein , we might want to wait to flesh out further details . 
 This seems quite arbitrary for a MUST ; what is " too far in the future " and " too high " ? 
  , this is an tricky point . I think an implementation : MUST define internal threeshold of allowed values ; MUST validate ratelimit fields according to those thresholds . I think we could borrow some text from Signature . See 
 OK , but RFC2119 language is for interoperability , and this does n't provide any ; different implementations ( or deployments ) are going to have different values , and that may cause issues . It 'd be better to defines precise limits if you think this is important enough to merit a MUST . Personally , I 'd remove the 2119 language and just give guidelines about what implementations should consider when they 're looking for abuse . 
 Ok , great ! 
 Addressed in 
 The draft today suggests putting quota policies , a list , into the header . But that 's a sort of breaking change , because that header 's equivalent is strictly a number ( not a list ) in most existing implementations . Could be kept as a plain number ( like and ) , and instead a new header like or some such can contain supplementary information ? That way , the story for upgrading to this draft is simpler . Sorry if this is asked and answered . 
 iirc we considered this but we initially had some requests of conflating as much as possible in fewer fields . Probably it 's a more interoperable choice . I am open in re - considering the idea , provided we get in touch with the current implementers including 3scale , kong and envoy cc : 3scale : , kong : , envoyproxy : 
 There 's no inherent problem in using a specific header for policies , and no issue in moving to use them from the 3scale side . The only downside is we 're adding yet another header for rate limiting , currently 4 of them , which might raise a few eyebrows . 
 thanks :) do you think that splitting is a more interoperable choice wrt to the parsing implementation / usability ? Do you see other practical drawbacks ? if we do n't get feedback on this issue , can you ping the other implementers you know ? 
 Yes , it 's easier for people to pick up a new header for this to apply a policy , since as it stands they might break when seeing extra stuff in the limit one by expecting a single value rather than multiple , as mentions above . No , just dealing with people ( maybe ) opposing too - many - headers - I do n't know if this is something that we can predictably foresee happening in the HTTPAPI WG or in the HTTP WG , but my intuition says " likely " given how we were asked to " condense " this information , so I think we might want to spend some time making a good case out of it . other than potential breakages in pre - existing implementations , is there any additional point we could make to justify the additional header ? I think they are all currently listed - that being said I think porting to a new header should be an easy task , so hopefully not a problem . 
 if almost everyone is implementing just the minimal specification , probably this could even simplify the addition of ... 
 The primary motivation is breakage , as you suggest , The secondary motivation is ease of " upgrading " to adoption of quota policies , as suggests . The flipside of " easy to adopt , easy to upgrade " is that the spec would also make it easy to never upgrade at all . This is a good thing , supposing that most services can operate perfectly fine without quota policies . A third , much weaker argument , is that the current approach of putting the " limit " and " quota policy " in the same header is that it 's confusing . I would need more time to really state this argument more clearly , but what rubs me the wrong way here is that the current design basically puts two different kinds of data in the same list . As it stands , is a list of a numbers , but the first number ( the " limit " ) is not like the rest of the numbers ( the policy ) . The first number can not have SFV parameters , but the others can ( and typically will ) . It 's an accident of SFV 's syntax that this is even conceivable as an approach . For implementors , this means that does not simply deserialize as some sort of . It deserializes into a list , where the first element is an and the tail is a . I fear this will at minimum confuse folks , and perhaps even lead to incorrect implementations , such as people not realizing the first element of the list is not a quota policy at all . 
 Given it seems there 's some consensus in providing quota policy in a separate field .
Paragraph (version A):
This was partially addressed by the "Retry-After" header field
defined in SEMANTICS to be returned in "429 Too Many Requests" (see
STATUS429) or "503 Service Unavailable" responses.
Paragraph (version B):
This was partially addressed by the "Retry-After" header field
defined in SEMANTICS to be returned in 429 (Too Many Request) (see
STATUS429) or 503 (Service Unavailable) responses.
Paragraph (version A):
"RateLimit-Reset": containing the time remaining in the current
window, specified in seconds.
Paragraph (version B):
"RateLimit-Policy": containing the quota policy information.
Paragraph (version A):
This specification uses Structured Fields SF to specify syntax.
Paragraph (version A):
The terms sf-list, sf-item, sf-string, sf-token, sf-integer, bare-
item and key refer to the structured types defined therein.
Paragraph (version B):
This document uses the following terminology from Section 3 of SF to
specify syntax and parsing: List, Item, String, Token and Integer
together with the concept of bare item.
Paragraph (version A):
Where "delay-seconds" is a non-negative sf-integer compatible with
the "delay-seconds" rule defined in Section 10.2.3 of SEMANTICS.
Paragraph (version B):
Where "delay-seconds" is a non-negative Integer compatible with the
"delay-seconds" rule defined in Section 10.2.3 of SEMANTICS.
Paragraph (version A):
where "quota-units" is a non-negative sf-integer.
Paragraph (version B):
where "quota-units" is a non-negative Integer.
Paragraph (version A):
To ease the migration from existing rate limit headers, a server
SHOULD be able to provide the "RateLimit-Limit" field even without
the optional "quota-policy" section.
Paragraph (version A):
Implementers concerned with response fields' size, might take into
account their ratio with respect to the payload data, or use header-
compression http features such as HPACK.
Paragraph (version B):
Implementers concerned with response fields' size, might take into
account their ratio with respect to the content length, or use
header-compression HTTP features such as HPACK.
Paragraph (version A):
The "quota-policy" values and comments provided in "RateLimit-Limit"
are informative and MAY be ignored.
Paragraph (version B):
The details provided in "RateLimit-Policy" are informative and MAY be
ignored.
Paragraph (version A):
The "expiring-limit" value MUST be set to the "service-limit" that is
closer to reach its limit.
Paragraph (version A):
The "quota-policy" is defined in quota-policy, and its values are
informative.
Paragraph (version B):
The field is a non-negative Integer.  Its value is named "expiring-
limit".
Paragraph (version B):
The "RateLimit-Policy" field (see ratelimit-policy-field), might
contain information on the associated "time-window".
Paragraph (version B):
The "RateLimit-Policy" response field indicates the "quota"
associated to the client and its value is informative.
Paragraph (version B):
The field is a non-empty List of quota policies (see quota-policy).
Paragraph (version B):
A "time-window" associated to "expiring-limit" can be communicated
via "RateLimit-Policy", like shown in the following example.
Paragraph (version B):
The field is a non-negative Integer expressed in "quota-units".
Paragraph (version A):
the number of seconds until the quota resets.
Paragraph (version B):
The "RateLimit-Reset" response field indicates the number of seconds
until the quota resets.
Paragraph (version B):
The field is a non-negative Integer.