jiebi/CodeConvo huggingface dataset:
Change:
It would be better to say that rate limiting information in what we used to call non-firsthand responses (basically, anything with an Age header) should be ignored.
Is the following text ok?
Looks good, just a few suggested tweaks:

Discussion:
5.2. <del> As is the ordinary case for HTTP caching (HTTP-CACHING), a response with RateLimit fields might be cached and re-used for subsequent requests.  A cached response containing RateLimit fields does not modify quota counters but could contain stale information.  Clients interested in determining the freshness of the RateLimit fields could rely on fields such as the Date header field and on the time window of a quota policy. </del> <ins> HTTP-CACHING defines how responses can be stored and reused for subsequent requests, including those with RateLimit fields.  Because the information in RateLimit fields on a cached response may not be current, they SHOULD be ignored on responses that come from cache (i.e., those with a positive current_age; see Section 4.2.3 of HTTP- CACHING). </ins> 6.
Change:
This should be specified without resorting to a metaphor that some may find confusing.
I'm ok to removing this line.

Discussion:
Clients MUST NOT assume that a positive RateLimit-Remaining field value is a guarantee that further requests will be served. <del> A low RateLimit-Remaining field value is like a yellow traffic-light for either the number of requests issued in the time window or the request throughput: the red light may arrive suddenly (see providing- ratelimit-fields). </del> <ins> When the value of RateLimit-Remaining is low, it indicates that the server may soon throttle the client (see providing-ratelimit-fields). </ins> For example:
Change:
Parameters are not allowed, and if they appear they MUST be ignored.
Why not just 'If Parameters appear they MUST be ignored'?
NAME we wanted to stress the fact that servers are not expected to provide parameters, otherwise some clients could just consider the whole field value malformed and ignore it.
The normal way to do that is something like:
Ok, I'll rebase this PR tomorrow :) Late night now in Italy. Thanks for all this support :)
In a few places, the specification says "Parameters are not allowed" but does not spell out what should happen if they appear.

Discussion:
exceeds that limit, it MAY not be served. The field is an Item and its value is a non-negative Integer referred <del> to as the "expiring-limit".  Parameters are not allowed. </del> <ins> to as the "expiring-limit".  This specification does not define Parameters for this field.  If they appear, they MUST be ignored. </ins> The expiring-limit MUST be set to the service limit that is closest to reaching its limit, and the associated time window MUST either be:

client. The field is an Item and its value is a non-negative Integer <del> expressed in service-limit.  Parameters are not allowed. </del> <ins> expressed in service-limit.  This specification does not define Parameters for this field.  If they appear, they MUST be ignored. </ins> This field can be sent in a trailer section.

it mitigates the risk related to thundering herd when too many clients are serviced with the same timestamp. <ins> This specification does not define Parameters for this field.  If they appear, they MUST be ignored. </ins> This field can be sent in a trailer section. An example of RateLimit-Reset field use is below.
Change:
clarify that we return only the values related to the quota policy identified by the expiring-limit
If there are multiple policies in effect, which is reflected in these fields? RateLimit-Limit has advice about this, but these do not.
Ok, we should clearly state that all the three basic fields return the values associated to the expiring-limit.

Discussion:
3.3. <del> The "RateLimit-Remaining" field response field indicates the remaining quota units defined in service-limit associated with the client. </del> <ins> The "RateLimit-Remaining" response field indicates the remaining quota units associated to the expiring-limit. </ins> The field is an Item and its value is a non-negative Integer expressed in service-limit.  This specification does not define

3.4. The "RateLimit-Reset" field response field indicates the number of <del> seconds until the quota resets. </del> <ins> seconds until the quota associated to the expiring-limit resets. </ins> The field is a non-negative Integer compatible with the delay-seconds rule, because:
Change:
NAME suggestion on server behavior. Thx! -
In section 4 it says, In section 4.1 it says, These statements seem contradictory. I do not see how we can declare as REQUIRED considering many APIs do not and will not implement these headers. It seems to me that if a client receives a header they can choose to either count the requests they make within the time window or they can monitor the . With neither of those values it would be difficult to do something useful. How would you feel about words like this:
NAME we are open to clarifications. The rationale for the current behavior is in URL I think RateLimit-Reset is always REQUIRED.
NAME In theory someone could use RateLimit-Limit to provide a limited number of "free" requests as a trial for their API. They may not choose to have a reset window and just require payment before allocating more calls. This is a bit of an edge case use of the headers, but might be just enough of a justification to limit constraints that we add. Having said this, I still don't understand how we can make any of these headers required considering there are so many existing APIs that don't return these headers today. How does a developer decide if they MUST return these headers for their API? Assuming the "free trial" scenario is not considered a valid scenario for this header, then how would you feel about these words?
SGTM.

Discussion:
4. A server uses the RateLimit header fields to communicate its quota <del> policies.  Sending the RateLimit-Limit and RateLimit-Reset header fields is REQUIRED; sending RateLimit-Remaining header field is RECOMMENDED. </del> <ins> policies.  A response that includes the RateLimit-Limit header field MUST also include the RateLimit-Reset.  It MAY also include a RateLimit-Remaining header field. </ins> A server MAY return RateLimit header fields independently of the response status code.  This includes on throttled responses.  This
Change:
clarify that quota policies are unique in policy.
If server defines two policies, e.g. and the response header contains, How do I know if I can make 2 more requests, or download 2 more bytes? Is having multiple policies with different quota units not allowed?
Good catch! The list items MUST be unique. I will specify this for now. WDYT about switching Policy to a Dictionary? This requires some tweak though e.g. prefixing the units with . cc: NAME
I'd use a short name for the policy, so that it could be referred to separately; e.g.,

Discussion:
informative. The field is a non-empty List of Items.  Each item is a quota-policy. <ins> Two quota policies MUST NOT be associated with the same quota units value. </ins> This field can convey the time window associated with the expiring- limit, as shown in this example: These examples show multiple policies being returned: <ins> An example of invalid header field value with two policies associated with the same quota units: </ins> This field cannot appear in a trailer section. 3.3.
Change:
servers are not forced to always return ratelimit fields clients must not assume the presence of ratelimit fields performance hints for providers
Waiting for NAME then :)
NAME PTAL :)
Looks great to me. The intent is nice and clear.
The spec to define header inter-dependencies and returning policies [x] Limit -> Reset [x] Limit, Remaining, Reset Do I have to always return all headers? No Do I have to expose all headers or I can only expose a subset? Limit,Reset are REQUIRED, Remaining is OPTIONAL Do we need to add some considerations on client implementation? Already present.
clarifies that clients MUST NOT assume a server always returns fields
Comment by Erik. In https://ietf-wg-URL You state ‘A server MAY use one or more "RateLimit" response fields defined in this document to communicate its quota policies.’ but it does not clearly define how they would be used in isolation or how a client should respond to a limited set of headers (other than discussed earlier above) My feeling is RateLimit-Limit can be optional and RateLimit-Remaining and RateLimit-Reset can be used as a pair. RateLimit-Reset would only have value in isolation if sent with a 429 response code, on other responses it would be meaningless.
It could also make sense to return Reset with other status codes such as and , so I think we don't really want to mandate a specific relation other than, at most, saying that unsuccessful requests (for a broad definition of those, possibly including and at a minimum) with this field are expected to be unsuccessful until that time elapses.
After a couple of years of adoption, my experience is the following: implementations use all 3 fields. Though theoretically one could just return and , I never found an implementation doing this :heavycheckmark: implementations don't know Remaining, and just return Limit and Reset with a fixed window (eg. 1 second). We can then recommend the following: Limit, Reset: MUST Remaining: SHOULD Since https://ietf-wg-URL I now think that we shouldn't mess with status codes. NAME if this sounds reasonable to you, I can provide a PR
Yes, it sounds good, thank you!
Looks good!

Discussion:
available in that moment.  Nonetheless servers MAY decide to send the "RateLimit" fields in a trailer section. <ins> 4.1. Servers are not required to return "RateLimit" fields in every response, and clients need to take this into account.  For example, an implementer concerned with performance might provide "RateLimit" fields only when a given quota is going to expire. 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. </ins> 5. This section documents the considerations advised in Section 16.3.3

with the expected ones.  This includes a "RateLimit-Reset" moment too far in the future or a "service-limit" too high. <ins> A client receiving "RateLimit" fields MUST NOT assume that subsequent responses contain the same "RateLimit" fields, or any "RateLimit" fields at all. </ins> Malformed "RateLimit" fields MAY be ignored. A client SHOULD NOT exceed the "quota-units" expressed in "RateLimit-
Change:
specific throttling behavior is out of scope FAQ 8 integrated in RateLimit-Remaining and Receiving Ratelimit fields
We used the Limit and Remain values in one of our client applications that was migrated from a legacy SOAP service to our REST based API in order to ensure we never get a 429 response (this is because the legacy code could not gracefully retry requests without major refactoring). When we get to 80% of quota (20% Remain) we start respecting the value in the Reset header. In section 7 you touched on a concept ‘A client SHOULD NOT exceed the "quota-units" expressed in "RateLimit-Remaining" before the "time-window" expressed in "RateLimit-Reset".’ We don't want to mandate a strict behavior on client, but we can surely add this sentence as an example behavior. The current spec allows comments, so you can already do it. The spec allows to address this use-case transparently, by artificially lowering the values provided in the fields.
We should probably integrate and remove since it's already in the spec.
This is something I quickly commented on URL but the alternative of dynamically modifying the values as the rate saturates is fairly reasonable, so those informational parameters might as well be part of an extension document.

Discussion:
section. Clients MUST NOT assume that a positive "RateLimit-Remaining" value <del> is a guarantee of being served. </del> <ins> is a guarantee that further requests will be served. </ins> <del> A low "RateLimit-Remaining" value is like a yellow traffic-light: the red light may arrive suddenly. </del> <ins> A low "RateLimit-Remaining" value is like a yellow traffic-light for either the number of requests issued in the "time-window" or the request throughput: the red light may arrive suddenly (see providing- ratelimit-fields). </ins> One example of "RateLimit-Remaining" use is below.

fields, "Retry-After" MUST take precedence and "RateLimit-Reset" MAY be ignored. <ins> This specification does not mandate a specific throttling behavior and implementers can adopt their preferred policies, including: slowing down or preemptively backoff their request rate when approaching quota limits; consuming all the quota according to the exposed limits and then wait. </ins> 8. 8.1.
Change:
Hi The link to the mailing archive (URL) is 404. I assume the correct link is: URL
Hi NAME thanks for the report, should be fixed soon.

Discussion:
Discussion of this draft takes place on the HTTP working group mailing list (httpapi@ietf.org), which is archived at <del> https://lists.w3.org/Archives/Public/ietf-httpapi-wg/ [1]. </del> <ins> https://mailarchive.ietf.org/arch/browse/httpapi/ [1]. </ins> The source code and issues list for this draft can be found at https://github.com/ietf-wg-httpapi/ratelimit-headers [2].

11.1.  URIs <del> [1] https://lists.w3.org/Archives/Public/ietf-httpapi-wg/ </del> <ins> [1] https://mailarchive.ietf.org/arch/browse/httpapi/ </ins> [2] https://github.com/ietf-wg-httpapi/ratelimit-headers
Change:
reformats goals
to reorganize Goals section with a single type of list
Single type of list as in using the same list styling for goals and non-goals? Or leaving just the list of goals and use prose for non-goals?

Discussion:
10 requests per second; <del> limited to 60 request per minute; </del> <ins> limited to 60 requests per minute; </ins> <del> limited to 1000 request per hour. </del> <ins> limited to 1000 requests per hour. </ins> Moreover system metrics, statistics and heuristics can be used to implement more complex policies, where the number of acceptable <del> request and the time window are computed dynamically. </del> <ins> requests and the time window are computed dynamically. </ins> 1.2.

The goals of this proposal are: <del> Standardizing the names and semantics of rate-limit headers to ease their enforcement and adoption; </del> <ins> Standardization of the names and semantics of rate-limit headers to ease their enforcement and adoption; </ins> Improve resiliency of HTTP infrastructure by providing clients with information useful to throttle their requests and prevent 4xx
Change:
consistent use of in document name cc: NAME NAME
Consistently use "fields" instead of "headers" since can be used in trailers.

Discussion:
<del> RateLimit Header Fields for HTTP </del> <ins> RateLimit Fields for HTTP </ins> draft-ietf-httpapi-ratelimit-headers-latest Abstract

or 5xx responses; Simplify API documentation by eliminating the need to include <del> detailed quota limits and related header fields in API documentation. </del> <ins> detailed quota limits and related fields in API documentation. </ins> The goals do not include:
Change:
clarify that quota-policy examples are not field values.
To clarify that examples in service-quota are not field-values

Discussion:
The "service-limit" is expressed in "quota-units" and has the following syntax: <del> where quota-units is a non-negative sf-integer. </del> <ins> where "quota-units" is a non-negative sf-integer. </ins> The "service-limit" SHOULD match the maximum number of acceptable requests.

distribution of quota-units over time.  Such service specific details can be conveyed as parameters. <del> Two examples of providing further details via custom parameters </del> <ins> Two policy examples containing further details via custom parameters </ins> 3.
Change:
Clarifies that Without w a quota-policy is meaningless, so it's just a clarification.
Oops, this should have been explicit since day 1! Good catch!

Discussion:
The following parameters are defined: <del> The "w" parameter specifies a time window.  Its syntax is a "time- window" defined in time-window. </del> <ins> The REQUIRED "w" parameter specifies a time window.  Its syntax is a "time-window" defined in time-window. </ins> Other parameters are allowed and can be regarded as comments.  They ought to be registered within the "Hypertext Transfer Protocol (HTTP)
Change:
Text changes after it seems that empty 2.05+Content-Format observed representations work. Example updated because it seems fitting for the RD to announce that capability. (Not that the indication changes anything about the possibility, but clients might not even try otherwise). Closes: URL NAME would this shortened text still satisfy your concerns?
For the example "obs" on rd-lookup/res is sufficient.
Hi Chris, thanks for all the work. We are making progress. I commented on 2 of the pull requests (typo and suggestion). Text is suggested for the commit on identification; I did not like the "debugging" annotation at all. Once everything is committed, I hope to go through it all again with today's knowledge. NAME I think Chris's text is terse but correct; can you close the issue, or suggest small changes? Thanks, peter chrysn schreef op 2018-01-31 19:25:
ad "obs in /rd-lookup/res only": I don't see why the server should, but it works just as well, so why argue, updated.
It is an example. It shows that not all needs to be observed. chrysn schreef op 2018-02-01 12:21:

Discussion:
the CBOR and JSON representation of link format.  The RD resource paths /rd, /rd-lookup, and /rd-group are example values.  The server in this example also indicates that it is capable of providing <del> observation on lookup results. </del> <ins> observation on resource lookups. </ins> [ The RFC editor is asked to replace these and later occurrences of TBD64 and TBD504 with the numeric ID values assigned by IANA to
Change:
See the linked issues. Contributes-To: URL Closes: URL
Reduced (to the point where the PR's title is no longer really accurate), amended by oversights and split up into individual commits. NAME does this look better to you now? (The paragraph on the intention of the interaction templates is not in here yet, that'll be a separate PR.)
A con= value on a simple registration may be unintuitive to implementors (they'd expect to do role reversal when fetching the .well-known/core). We could disallow it, and would just need to state its implications (namely that endpoints that do virtual hosting or that register via CoAP-over-TCP can not use simple registration). The current patch for (b26dd6678e66e68ddb3850949f398bcf3c550416) already has this effect (but not yet the caveats wording). (Brought up during plug test, see )
8 Is there supposed to be a way for simple registration to return an error message? As written this is not necessarily done. Specifically, the response to the post can be executed before the query to /.well-known/core is done and the registration is attempted. I see what you mean: also the return of 2.04 shows in the example but not in the specification. This warrants additional text to specify the simple registration text. will add the simple registration template to the text.
Added template in section 5.3.1. simple registration
Ad "GET /.well-known/core": Our templates are already verbose, redundant with CoAP ("4.00 Bad Request and 400 Bad Request: Malformed request.", surprise) and at the same time not exhaustive (see ); I've come to accept that. But the GET section on the endpoint's .well-known/core is the very functionality that is described in RFC6690 Section 4. What is gained by duplicating that specification and selectively picking some possible error codes? I suggest we remove that part. Ad simple registration interface: Any particular reason you picked precisely ep and d to be eligible? lt definitely makes sense, and so do extra-attrs (they are our extension point, and not having them would exclude simple registration from extensibility). A pull request to that respect is pending (see link below) together with .
I think that's in a good state now with , , and the separator paragraph before the GET operation in #simple. I might have missed the point of this issue though, so not closing right away; NAME please close if you think this issue is done. Hi Christian, thanks for this very useful work Some questions/ remarks below. certainly not; it beats the purpose. We may add text in RD to address the TCP part. to what purpose? It states explicitly that it is a scheme//authority string, no query parameters possible; The simplicity helps to specify an already complex subject to be filled into the github, I hope. >

Discussion:
NO <ins> For the second interaction triggered by the above, the endpoint takes the role of a server: </ins> RD -> EP GET
Change:
This is easier to to satisfy with a "once per day" update, a nice round number, and still over 9000. Closes: URL
I think that the default value of lt should be modified so that it is slightly greater than one day. If it is one day then a cron job which starts at midnight everyday could potentially end up not acting in time to renew rather than re-register an item. Given that a post to the resource adds the value of lt to the current time, there would be no drift in the expiration time.

Discussion:
Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included in the <del> initial registration, a default value of 86400 (24 hours) </del> <ins> initial registration, a default value of 90000 (25 hours) </ins> SHOULD be assumed. Context (optional).  This parameter sets the Default Base URI

Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included, the previous last lifetime set on a previous update or the original <del> registration (falling back to 86400) SHOULD be used. </del> <ins> registration (falling back to 90000) SHOULD be used. </ins> Context (optional).  This parameter updates the context established in the original registration to a new value.  If
Change:
With the formal introduction of Target in 68bd92a9, this seems even more important to point out. Next steps: merge unless someone protests.

Discussion:
authority information about an Endpoint.  The Context of an Endpoint is provided at registration time, and is used by the Resource Directory to resolve relative references inside the <del> registration into absolute URIs. </del> <ins> registration into absolute URIs.  This is a distinct concept from the "link context" defined in RFC8288. </ins> The target of a link is the destination address (URI) of the link. It is sometimes identified with "href=", or displayed as "<target>".  Relative targets need resolving with respect to the <del> Base URI (section 5.2 of RFC3986. </del> <ins> Base URI (section 5.2 of RFC3986.  This use of the term Target is consistent with RFC8288's use of the term. </ins> A resource in the Resource Directory (RD) containing registration