|
1 | 1 | # MSC4041: Use http header Retry-After to enable library-assisted retry handling
|
2 | 2 |
|
3 |
| -The current Matrix Client-Server API (v1.7) recommends that home servers should protect themselves from |
| 3 | +The current Matrix Client-Server API (v1.7) recommends that homeservers should protect themselves from |
4 | 4 | being overloaded by enforcing rate-limits to selected API calls.
|
5 |
| -If home servers limit access to an API they respond with an http error code 429 and a response body |
| 5 | +If homeservers limit access to an API they respond with an http error code 429 and a response body |
6 | 6 | that includes a property `retry_after_ms` to indicate how long a client has to wait before retrying.
|
7 | 7 |
|
8 | 8 | Some http libraries (like [Ky](https://github.com/sindresorhus/ky), [got](https://github.com/sindresorhus/got
|
9 | 9 | and [urllib3](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html#urllib3.util.Retry)) ease
|
10 |
| -the burden of handling retries by honoring the http header `Retry-After`. As explained in |
| 10 | +the burden of handling retries by honoring the http header `Retry-After`. As explained in |
11 | 11 | [RFC 9119 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after) this header is optional
|
12 | 12 | and contains either a (relative) value for the delay in seconds or an (absolute) date.
|
13 | 13 |
|
14 |
| -The current Matrix Client Server API specification does not take this header into account. This wastes the |
| 14 | +The current Matrix Client Server API specification does not take this header into account. This wastes the |
15 | 15 | potential that current http libraries offer in terms of automated retry handling.
|
16 | 16 |
|
17 | 17 | ## Proposal
|
18 | 18 |
|
19 | 19 | In order to allow developers to make use of the automated retry handling capabilities of http libraries
|
20 |
| -home servers shall use the http header `Retry-After` in case they respond with an http error 429. |
21 |
| -The value of `Retry-After` (in __seconds__) is meant to be a delay after receiving the response and must be |
| 20 | +homeservers shall use the http header `Retry-After` in case they respond with an http error 429. |
| 21 | +The value of `Retry-After` (in __seconds__) is meant to be a delay after receiving the response and must be |
22 | 22 | calculated in order to comply with the specification in [RFC 9119 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after).
|
23 | 23 |
|
24 | 24 | With the introduction of the http header `Retry-After` the usage of the existing `retry_after_ms` property in the response body becomes deprecated.
|
25 | 25 |
|
26 | 26 | ## Potential issues
|
27 | 27 |
|
28 |
| -In order to maintain backward compatibility with existing client libraries home servers shall use both the `Retry-After` header and the |
| 28 | +In order to maintain backward compatibility with existing client libraries homeservers shall use both the `Retry-After` header and the |
29 | 29 | `retry_after_ms` property in the response body.
|
30 | 30 |
|
31 | 31 | Client libraries shall use the values in this order:
|
|
0 commit comments