Capture HTTP error response headers & handle Retry-After header (MSC4041) (#4471)

* Include HTTP response headers in MatrixError

* Lint

* Support MSC4041 / Retry-After header

* Fix tests

* Remove redundant MatrixError parameter properties

They are inherited from HTTPError, so there is no need to mark them as
parameter properties.

* Comment that retry_after_ms is deprecated

* Properly handle colons in XHR header values

Also remove the negation in the if-condition for better readability

* Improve Retry-After parsing and docstring

* Revert ternary operator to if statements

for readability

* Reuse resolved Headers for Content-Type parsing

* Treat empty Content-Type differently from null

* Add MatrixError#isRateLimitError

This is separate from MatrixError#getRetryAfterMs because it's possible
for a rate-limit error to have no Retry-After time, and having separate
methods to check each makes that more clear.

* Ignore HTTP status code when getting Retry-After

because status codes other than 429 may have Retry-After

* Catch Retry-After parsing errors

* Add test coverage for HTTP error headers

* Update license years

* Move safe Retry-After lookup to global function

so it can more conveniently check if an error is a MatrixError

* Lint

* Inline Retry-After header value parsing

as it is only used in one place and doesn't need to be exported

* Update docstrings

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Use bare catch

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Give HTTPError methods for rate-limit checks

and make MatrixError inherit them

* Cover undefined errcode in rate-limit check

* Update safeGetRetryAfterMs docstring

Be explicit that errors that don't look like rate-limiting errors will
not pull a retry delay value from the error.

* Use rate-limit helper functions in more places

* Group the header tests

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

spec/unit/http-api/errors.spec.ts

@@ -0,0 +1,98 @@
+/*
+Copyright 2024 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { MatrixError } from "../../../src";
+
+type IErrorJson = MatrixError["data"];
+
+describe("MatrixError", () => {
+    let headers: Headers;
+
+    beforeEach(() => {
+        headers = new Headers({ "Content-Type": "application/json" });
+    });
+
+    function makeMatrixError(httpStatus: number, data: IErrorJson): MatrixError {
+        return new MatrixError(data, httpStatus, undefined, undefined, headers);
+    }
+
+    it("should accept absent retry time from rate-limit error", () => {
+        const err = makeMatrixError(429, { errcode: "M_LIMIT_EXCEEDED" });
+        expect(err.isRateLimitError()).toBe(true);
+        expect(err.getRetryAfterMs()).toEqual(null);
+    });
+
+    it("should retrieve retry_after_ms from rate-limit error", () => {
+        const err = makeMatrixError(429, { errcode: "M_LIMIT_EXCEEDED", retry_after_ms: 150000 });
+        expect(err.isRateLimitError()).toBe(true);
+        expect(err.getRetryAfterMs()).toEqual(150000);
+    });
+
+    it("should ignore retry_after_ms if errcode is not M_LIMIT_EXCEEDED", () => {
+        const err = makeMatrixError(429, { errcode: "M_UNKNOWN", retry_after_ms: 150000 });
+        expect(err.isRateLimitError()).toBe(true);
+        expect(err.getRetryAfterMs()).toEqual(null);
+    });
+
+    it("should retrieve numeric Retry-After header from rate-limit error", () => {
+        headers.set("Retry-After", "120");
+        const err = makeMatrixError(429, { errcode: "M_LIMIT_EXCEEDED", retry_after_ms: 150000 });
+        expect(err.isRateLimitError()).toBe(true);
+        // prefer Retry-After header over retry_after_ms
+        expect(err.getRetryAfterMs()).toEqual(120000);
+    });
+
+    it("should retrieve Date Retry-After header from rate-limit error", () => {
+        headers.set("Retry-After", `${new Date(160000).toUTCString()}`);
+        jest.spyOn(global.Date, "now").mockImplementationOnce(() => 100000);
+        const err = makeMatrixError(429, { errcode: "M_LIMIT_EXCEEDED", retry_after_ms: 150000 });
+        expect(err.isRateLimitError()).toBe(true);
+        // prefer Retry-After header over retry_after_ms
+        expect(err.getRetryAfterMs()).toEqual(60000);
+    });
+
+    it("should prefer M_FORBIDDEN errcode over HTTP status code 429", () => {
+        headers.set("Retry-After", "120");
+        const err = makeMatrixError(429, { errcode: "M_FORBIDDEN" });
+        expect(err.isRateLimitError()).toBe(false);
+        // retrieve Retry-After header even for non-M_LIMIT_EXCEEDED errors
+        expect(err.getRetryAfterMs()).toEqual(120000);
+    });
+
+    it("should prefer M_LIMIT_EXCEEDED errcode over HTTP status code 400", () => {
+        headers.set("Retry-After", "120");
+        const err = makeMatrixError(400, { errcode: "M_LIMIT_EXCEEDED" });
+        expect(err.isRateLimitError()).toBe(true);
+        // retrieve Retry-After header even for non-429 errors
+        expect(err.getRetryAfterMs()).toEqual(120000);
+    });
+
+    it("should reject invalid Retry-After header", () => {
+        for (const invalidValue of ["-1", "1.23", new Date(0).toString()]) {
+            headers.set("Retry-After", invalidValue);
+            const err = makeMatrixError(429, { errcode: "M_LIMIT_EXCEEDED" });
+            expect(() => err.getRetryAfterMs()).toThrow(
+                "value is not a valid HTTP-date or non-negative decimal integer",
+            );
+        }
+    });
+
+    it("should reject too-large Retry-After header", () => {
+        headers.set("Retry-After", "1" + Array(500).fill("0").join(""));
+        const err = makeMatrixError(429, { errcode: "M_LIMIT_EXCEEDED" });
+        expect(() => err.getRetryAfterMs()).toThrow("integer value is too large");
+    });
+});