Skip to content

Address HTTPDIR review feedback and add structured partition keys#166

Open
darrelmiller wants to merge 6 commits into
mainfrom
httpdir-review
Open

Address HTTPDIR review feedback and add structured partition keys#166
darrelmiller wants to merge 6 commits into
mainfrom
httpdir-review

Conversation

@darrelmiller

Copy link
Copy Markdown
Contributor

This PR addresses feedback from Lucas Pardue's HTTPDIR early review and introduces structured partition keys.

Key Changes

New Features

  • RateLimit-Partition header field - declares partition dimensions as parameters on policy identifiers, with fixed-value filtering support
  • Partition key construction rule - dimensions sorted alphabetically, UTF-8 values concatenated with 0x1F (Unit Separator)
  • Cost parameter (c) on RateLimit field - reports quota units consumed by the request
  • Wire parameter rename: r to a (available quota), t to w (effective window)

IANA Registries (5 new)

  • 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)
  • RateLimit Quota Units (pre-existing, formalized)

Structural

  • Merge Notational Conventions + Terminology into single section
  • Move Problem Types after Client Behavior
  • Rewrite Quota Partitions section with motivation-first prose

Editorial (29 of 37 HTTPDIR comments addressed)

  • Remove dead Origin import, fix SF reference style, add missing SF terms
  • Pluralize intro summaries, replace resource server with server
  • Upgrade should be careful to SHOULD avoid for redirects
  • Relax intermediary text, replace unenforceable MUST NOT
  • Replace vendor-prefix guidance with parameter registries

Remaining items for follow-up

Resolves #161, #162. Incorporates #163, #164.

darrelmiller and others added 6 commits February 22, 2026 16:07
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>

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

: 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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.

@ioggstream ioggstream Apr 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. 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.

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants