Fix idempotency issue around token refresh (#4730)

* Fix idempotency issue around token refresh

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Improve test

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

---------

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

src/http-api/fetch.ts

@@ -31,6 +31,7 @@ import {
 } from "./interface.ts";
 import { anySignal, parseErrorResponse, timeoutSignal } from "./utils.ts";
 import { type QueryDict } from "../utils.ts";
+import { singleAsyncExecution } from "../utils/decorators.ts";
 
 interface TypedResponse<T> extends Response {
     json(): Promise<T>;
@@ -106,6 +107,12 @@ export class FetchHttpApi<O extends IHttpOpts> {
         return this.requestOtherUrl(method, fullUri, body, opts);
     }
 
+    /**
+     * Promise used to block authenticated requests during a token refresh to avoid repeated expected errors.
+     * @private
+     */
+    private tokenRefreshPromise?: Promise<unknown>;
+
     /**
      * Perform an authorised request to the homeserver.
      * @param method - The HTTP method e.g. "GET".
@@ -162,13 +169,17 @@ export class FetchHttpApi<O extends IHttpOpts> {
         }
 
         try {
+            // Await any ongoing token refresh
+            await this.tokenRefreshPromise;
             const response = await this.request<T>(method, path, queryParams, body, opts);
             return response;
         } catch (error) {
             const err = error as MatrixError;
 
             if (err.errcode === "M_UNKNOWN_TOKEN" && !opts.doNotAttemptTokenRefresh) {
-                const shouldRetry = await this.tryRefreshToken();
+                const tokenRefreshPromise = this.tryRefreshToken();
+                this.tokenRefreshPromise = Promise.allSettled([tokenRefreshPromise]);
+                const shouldRetry = await tokenRefreshPromise;
                 // if we got a new token retry the request
                 if (shouldRetry) {
                     return this.authedRequest(method, path, queryParams, body, {
@@ -177,6 +188,7 @@ export class FetchHttpApi<O extends IHttpOpts> {
                     });
                 }
             }
+
             // otherwise continue with error handling
             if (err.errcode == "M_UNKNOWN_TOKEN" && !opts?.inhibitLogoutEmit) {
                 this.eventEmitter.emit(HttpApiEvent.SessionLoggedOut, err);
@@ -193,6 +205,7 @@ export class FetchHttpApi<O extends IHttpOpts> {
      * On success, sets new access and refresh tokens in opts.
      * @returns Promise that resolves to a boolean - true when token was refreshed successfully
      */
+    @singleAsyncExecution
     private async tryRefreshToken(): Promise<boolean> {
         if (!this.opts.refreshToken || !this.opts.tokenRefreshFunction) {
             return false;

src/utils/decorators.ts

@@ -0,0 +1,39 @@
+/*
+Copyright 2025 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.
+*/
+
+/**
+ * Method decorator to ensure that only one instance of the method is running at a time,
+ * and any concurrent calls will return the same promise as the original call.
+ * After execution is complete a new call will be able to run the method again.
+ */
+export function singleAsyncExecution<This, Args extends unknown[], Return>(
+    target: (this: This, ...args: Args) => Promise<Return>,
+): (this: This, ...args: Args) => Promise<Return> {
+    let promise: Promise<Return> | undefined;
+
+    async function replacementMethod(this: This, ...args: Args): Promise<Return> {
+        if (promise) return promise;
+        try {
+            promise = target.call(this, ...args);
+            await promise;
+            return promise;
+        } finally {
+            promise = undefined;
+        }
+    }
+
+    return replacementMethod;
+}