Address HTTPDIR review feedback and add structured partition keys#166
Open
darrelmiller wants to merge 6 commits into
Open
Address HTTPDIR review feedback and add structured partition keys#166darrelmiller wants to merge 6 commits into
darrelmiller wants to merge 6 commits into
Conversation
The r= parameter is REQUIRED, so an example that omits it is incorrect. The example's description also doesn't clearly illustrate a valid use case. Cherry-picked from PR #163 by fanf2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Resolved 7 conflicts by combining httpdir-review editorial improvements with PR #164's available-quota/effective-window terminology. Also updated one remaining instance of old terminology in server behavior section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Structural Changes: - Merge Notational Conventions and Terminology into single section - Move Problem Types section after Client Behavior, before Caching - Incorporate Appendix A key content into Introduction New Features: - Add RateLimit-Partition header field declaring partition dimensions (e.g. "api";user_id;method) with fixed-value filtering support - Define partition key construction rule using 0x1F separator - Add cost parameter (c) on RateLimit field for request quota cost - Rename wire parameters: r to a (available), t to w (effective window) IANA Registries: - RateLimit-Policy Parameters (q, qu, w, pk) - RateLimit Parameters (a, w, pk, c) - RateLimit-Partition Parameters - RateLimit Partition Key Dimensions (user_id, client_id, method) Editorial (HTTPDIR review items): - Remove dead Origin import - Fix SF reference style to STRUCTURED-FIELDS - Add missing SF terms: Token, Boolean - Pluralize intro summaries - Replace "resource server" with "server" - Upgrade "should be careful" to "SHOULD avoid" for redirects - Relax intermediary text to "a different quota policy" - Replace unenforceable MUST NOT with advisory SHOULD - Rewrite Quota Partitions with motivation-first prose - Replace vendor-prefix guidance with parameter registries Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ioggstream
reviewed
Apr 22, 2026
|
|
||
| Documentation: | ||
| : Simplify API documentation by eliminating the need to include detailed quota limits and related fields in API documentation. | ||
| These fields enable servers to communicate complex rate limiting policies, including using multiple and variable time windows and dynamic quotas, and implementing concurrency limits. This information helps improve the resiliency of HTTP infrastructure by providing clients with the information needed to throttle their requests and avoid 4xx or 5xx responses. |
Collaborator
There was a problem hiding this comment.
Suggested change
| These fields enable servers to communicate complex rate limiting policies, including using multiple and variable time windows and dynamic quotas, and implementing concurrency limits. This information helps improve the resiliency of HTTP infrastructure by providing clients with the information needed to throttle their requests and avoid 4xx or 5xx responses. | |
| These fields enable servers to communicate complex rate limiting policies, including using multiple and variable time windows and dynamic quotas, and implementing concurrency limits. This information helps improve the resiliency of HTTP infrastructures by providing clients with the information needed to throttle their requests and avoid 4xx or 5xx responses. |
ioggstream
reviewed
Apr 22, 2026
| : A quota is an allocation of capacity used by a server to limit client requests. That capacity is measured in quota units that the client may consume within a time window. | ||
|
|
||
| Quota Unit: | ||
| : A quota unit is the unit of measurement used to measure the activity of a client. |
Collaborator
There was a problem hiding this comment.
Suggested change
| : A quota unit is the unit of measurement used to measure the activity of a client. | |
| : A quota unit is the unit of measurement for the activity of a client. |
ioggstream
reviewed
Apr 22, 2026
| This field MUST NOT appear in a trailer section. | ||
|
|
||
| Lists of Quota Policy Items ({{quotapolicy-item}}) can be split over multiple "RateLimit-Policy" fields in the same HTTP response as described in {{Section 3.1 of SF}}. | ||
| The "RateLimit-Policy" field enables clients to pace their requests based on policy information provided by the server. The field value SHOULD remain consistent over a sequence of HTTP responses, as policy information is not expected to change frequently. Situations where throttling constraints are highly dynamic are better served using the RateLimit field ({{ratelimit-field}}) that communicates the latest service information a client can react to. Both fields can be communicated by the server when appropriate. |
Collaborator
There was a problem hiding this comment.
- explain the reason for consistency :)
Suggested change
| The "RateLimit-Policy" field enables clients to pace their requests based on policy information provided by the server. The field value SHOULD remain consistent over a sequence of HTTP responses, as policy information is not expected to change frequently. Situations where throttling constraints are highly dynamic are better served using the RateLimit field ({{ratelimit-field}}) that communicates the latest service information a client can react to. Both fields can be communicated by the server when appropriate. | |
| The "RateLimit-Policy" field enables clients to pace their requests based on policy information provided by the server. The field value SHOULD remain consistent over a sequence of HTTP responses, changes would prevent clients from correctly following the communicated policy. Situations where throttling constraints are highly dynamic are better served using the RateLimit field ({{ratelimit-field}}) that communicates the latest service information a client can react to. Both fields can be communicated by the server when appropriate. |
ioggstream
reviewed
Apr 22, 2026
| A server MAY return RateLimit header fields independently of the response status code. This includes throttled responses. This document does not mandate any correlation between the RateLimit header field values and the returned status code. | ||
|
|
||
| Servers should be careful when returning RateLimit header fields in redirection responses (i.e., responses with 3xx status codes) because a low available quota could prevent the client from issuing requests. For example, given the RateLimit header fields below, a client could decide to wait 10 seconds before following the "Location" header field (see {{Section 10.2.2 of HTTP}}), because the available quota is 0. | ||
| Servers SHOULD avoid returning RateLimit header fields in redirection responses (i.e., responses with 3xx status codes) because a low available quota could prevent the client from following the redirect. For example, given the RateLimit header fields below, a client could decide to wait 10 seconds before following the "Location" header field (see {{Section 10.2.2 of HTTP}}), because the available quota is 0. |
Collaborator
There was a problem hiding this comment.
Maybe going full normative.
Suggested change
| Servers SHOULD avoid returning RateLimit header fields in redirection responses (i.e., responses with 3xx status codes) because a low available quota could prevent the client from following the redirect. For example, given the RateLimit header fields below, a client could decide to wait 10 seconds before following the "Location" header field (see {{Section 10.2.2 of HTTP}}), because the available quota is 0. | |
| Servers SHOULD NOT return RateLimit header fields in redirection responses (i.e., responses with 3xx status codes) because a low available quota could prevent the client from following the redirect. For example, given the RateLimit header fields below, a client could decide to wait 10 seconds before following the "Location" header field (see {{Section 10.2.2 of HTTP}}), because the available quota is 0. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR addresses feedback from Lucas Pardue's HTTPDIR early review and introduces structured partition keys.
Key Changes
New Features
IANA Registries (5 new)
Structural
Editorial (29 of 37 HTTPDIR comments addressed)
Remaining items for follow-up
Remaininginformation. #37)Resolves #161, #162. Incorporates #163, #164.