@textrp/briij-js-sdk 41.0.0

package/src/http-api/interface.ts

@@ -0,0 +1,229 @@
+/*
+Copyright 2022 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 { type BriijError } from "./errors.ts";
+import { type Logger } from "../logger.ts";
+import { type QueryDict } from "../utils.ts";
+
+export type Body = Record<string, any> | BodyInit;
+
+/**
+ * @experimental
+ * Unencrypted access and (optional) refresh token
+ */
+export type AccessTokens = {
+    /**
+     * The new access token to use for authenticated requests
+     */
+    accessToken: string;
+    /**
+     * The new refresh token to use for refreshing tokens, optional
+     */
+    refreshToken?: string;
+    /**
+     * Approximate date when the access token will expire, optional
+     */
+    expiry?: Date;
+};
+
+/**
+ * @experimental
+ * Function that performs token refresh using the given refreshToken.
+ * Returns a promise that resolves to the refreshed access and (optional) refresh tokens.
+ *
+ * Can be passed to HttpApi instance as {@link IHttpOpts.tokenRefreshFunction} during client creation {@link ICreateClientOpts}
+ */
+export type TokenRefreshFunction = (refreshToken: string) => Promise<AccessTokens>;
+
+/** Options object for `FetchHttpApi` and {@link BriijHttpApi}. */
+export interface IHttpOpts {
+    fetchFn?: typeof globalThis.fetch;
+
+    baseUrl: string;
+    idBaseUrl?: string;
+    prefix: string;
+    extraParams?: QueryDict;
+
+    accessToken?: string;
+    /**
+     * Used in conjunction with tokenRefreshFunction to attempt token refresh
+     */
+    refreshToken?: string;
+    /**
+     * Function to attempt token refresh when a possibly expired token is encountered
+     * Optional, only called when a refreshToken is present
+     */
+    tokenRefreshFunction?: TokenRefreshFunction;
+
+    /**
+     * Whether to use the HTTP Authorization header over the `access_token` query parameter
+     * @deprecated as of v1.11 in https://spec.matrix.org/v1.17/client-server-api/#using-access-tokens
+     */
+    useAuthorizationHeader?: boolean; // defaults to true
+
+    /** For historical reasons, must be set to `true`. Will eventually be removed. */
+    onlyData?: boolean;
+
+    localTimeoutMs?: number;
+
+    /** Optional logger instance. If provided, requests and responses will be logged. */
+    logger?: Logger;
+}
+
+/** Options object for `FetchHttpApi.requestOtherUrl`. */
+export interface BaseRequestOpts extends Pick<RequestInit, "priority"> {
+    /**
+     * map of additional request headers
+     */
+    headers?: Record<string, string>;
+    abortSignal?: AbortSignal;
+    /**
+     * The maximum amount of time to wait before
+     * timing out the request. If not specified, there is no timeout.
+     */
+    localTimeoutMs?: number;
+    keepAlive?: boolean; // defaults to false
+
+    /**
+     * By default, we will:
+     *
+     *  *  If the `body` is an object, JSON-encode it and set `Content-Type: application/json` in the
+     *     request headers (unless overridden by {@link headers}).
+     *
+     *  * Set `Accept: application/json` in the request headers (again, unless overridden by {@link headers}).
+     *
+     *  * Parse the response as JSON and return the parsed response.
+     *
+     * Setting this to `false` inhibits all three behaviors, and the response is instead parsed as a UTF-8 string. It
+     * defaults to `true`, unless {@link rawResponseBody} is set.
+     *
+     * @deprecated Instead of setting this to `false`, set {@link rawResponseBody} to `true`.
+     */
+    json?: boolean;
+
+    /**
+     * Setting this to `true` does two things:
+     *
+     *  * Inhibits the automatic addition of `Accept: application/json` in the request headers.
+     *
+     *  * Causes the raw response to be returned as a {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob}
+     *    instead of parsing it as JSON.
+     */
+    rawResponseBody?: boolean;
+}
+
+export interface IRequestOpts extends BaseRequestOpts {
+    /**
+     * The alternative base url to use.
+     * If not specified, uses this.opts.baseUrl
+     */
+    baseUrl?: string;
+    /**
+     * The full prefix to use e.g.
+     * "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
+     */
+    prefix?: string;
+
+    // Set to true to prevent the request function from emitting a Session.logged_out event.
+    // This is intended for use on endpoints where M_UNKNOWN_TOKEN is a valid/notable error response,
+    // such as with token refreshes.
+    inhibitLogoutEmit?: boolean;
+}
+
+export interface IContentUri {
+    base: string;
+    path: string;
+    params: {
+        // eslint-disable-next-line camelcase
+        access_token: string;
+    };
+}
+
+export enum HttpApiEvent {
+    SessionLoggedOut = "Session.logged_out",
+    NoConsent = "no_consent",
+}
+
+export type HttpApiEventHandlerMap = {
+    /**
+     * Fires whenever the login session the JS SDK is using is no
+     * longer valid and the user must log in again.
+     * NB. This only fires when action is required from the user, not
+     * when then login session can be renewed by using a refresh token.
+     * @example
+     * ```
+     * matrixClient.on("Session.logged_out", function(errorObj){
+     *   // show the login screen
+     * });
+     * ```
+     */
+    [HttpApiEvent.SessionLoggedOut]: (err: BriijError) => void;
+    /**
+     * Fires when the JS SDK receives a M_CONSENT_NOT_GIVEN error in response
+     * to a HTTP request.
+     * @example
+     * ```
+     * matrixClient.on("no_consent", function(message, contentUri) {
+     *     console.info(message + ' Go to ' + contentUri);
+     * });
+     * ```
+     */
+    [HttpApiEvent.NoConsent]: (message: string, consentUri: string) => void;
+};
+
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+}
+
+export interface UploadOpts {
+    /**
+     * Name to give the file on the server. Defaults to <tt>file.name</tt>.
+     */
+    name?: string;
+    /**
+     * Content-type for the upload. Defaults to
+     *   <tt>file.type</tt>, or <tt>applicaton/octet-stream</tt>.
+     */
+    type?: string;
+    /**
+     * if false will not send the filename,
+     *   e.g for encrypted file uploads where filename leaks are undesirable.
+     *   Defaults to true.
+     */
+    includeFilename?: boolean;
+    /**
+     * Optional. Called when a chunk of
+     *    data has been uploaded, with an object containing the fields `loaded`
+     *    (number of bytes transferred) and `total` (total size, if known).
+     */
+    progressHandler?(progress: UploadProgress): void;
+    abortController?: AbortController;
+}
+
+export interface Upload {
+    loaded: number;
+    total: number;
+    promise: Promise<UploadResponse>;
+    abortController: AbortController;
+}
+
+export interface UploadResponse {
+    // eslint-disable-next-line camelcase
+    content_uri: string;
+}
+
+export type FileType = XMLHttpRequestBodyInit;

package/src/http-api/method.ts

@@ -0,0 +1,25 @@
+/*
+Copyright 2022 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.
+*/
+
+export enum Method {
+    Get = "GET",
+    Put = "PUT",
+    Post = "POST",
+    Delete = "DELETE",
+    Options = "OPTIONS",
+    Head = "HEAD",
+    Patch = "PATCH",
+}

package/src/http-api/prefix.ts

@@ -0,0 +1,48 @@
+/*
+Copyright 2022 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.
+*/
+
+export enum ClientPrefix {
+    /**
+     * A constant representing the URI path for Client-Server API endpoints versioned at v1.
+     */
+    V1 = "/_matrix/client/v1",
+    /**
+     * A constant representing the URI path for Client-Server API endpoints versioned at v3.
+     */
+    V3 = "/_matrix/client/v3",
+    /**
+     * A constant representing the URI path for as-yet unspecified Client-Server HTTP APIs.
+     */
+    Unstable = "/_matrix/client/unstable",
+}
+
+export enum IdentityPrefix {
+    /**
+     * URI path for the v2 identity API
+     */
+    V2 = "/_matrix/identity/v2",
+}
+
+export enum MediaPrefix {
+    /**
+     * A constant representing the URI path for Client-Server API Media endpoints versioned at v1.
+     */
+    V1 = "/_matrix/media/v1",
+    /**
+     * A constant representing the URI path for Client-Server API Media endpoints versioned at v3.
+     */
+    V3 = "/_matrix/media/v3",
+}

package/src/http-api/refresh.ts

@@ -0,0 +1,167 @@
+/*
+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.
+*/
+
+import { BriijError, TokenRefreshLogoutError } from "./errors.ts";
+import { type IHttpOpts } from "./interface.ts";
+import { sleep } from "../utils.ts";
+
+/**
+ * This is an internal module. See {@link BriijHttpApi} for the public class.
+ */
+
+export const enum TokenRefreshOutcome {
+    Success = "success",
+    Failure = "failure",
+    Logout = "logout",
+}
+
+interface Snapshot {
+    accessToken: string;
+    refreshToken?: string;
+    expiry?: Date;
+}
+
+// If the token expires in less than this time amount of time, we will eagerly refresh it before making the intended request.
+const REFRESH_IF_TOKEN_EXPIRES_WITHIN_MS = 500;
+// If we get an unknown token error and the token expires in less than this time amount of time, we will refresh it before making the intended request.
+// Otherwise, we will error as the token should not have expired yet and we need to avoid retrying indefinitely.
+const REFRESH_ON_ERROR_IF_TOKEN_EXPIRES_WITHIN_MS = 60 * 1000;
+
+type Opts = Pick<IHttpOpts, "tokenRefreshFunction" | "logger" | "refreshToken" | "accessToken">;
+
+/**
+ * This class is responsible for managing the access token and refresh token for authenticated requests.
+ * It will automatically refresh the access token when it is about to expire, and will handle unknown token errors.
+ */
+export class TokenRefresher {
+    public constructor(private readonly opts: Opts) {}
+
+    /**
+     * Promise used to block authenticated requests during a token refresh to avoid repeated expected errors.
+     * @private
+     */
+    private tokenRefreshPromise?: Promise<TokenRefreshOutcome>;
+
+    private latestTokenRefreshExpiry?: Date;
+
+    /**
+     * This function is called before every request to ensure that the access token is valid.
+     * @returns a snapshot containing the access token and other properties which must be passed to the handleUnknownToken
+     *     handler if an M_UNKNOWN_TOKEN error is encountered.
+     */
+    public async prepareForRequest(): Promise<Snapshot> {
+        // Ensure our token is refreshed before we build the headers/params
+        await this.refreshIfNeeded();
+
+        return {
+            accessToken: this.opts.accessToken!,
+            refreshToken: this.opts.refreshToken,
+            expiry: this.latestTokenRefreshExpiry,
+        };
+    }
+
+    private async refreshIfNeeded(): Promise<unknown> {
+        if (this.tokenRefreshPromise) {
+            return this.tokenRefreshPromise;
+        }
+        // If we don't know the token expiry, we can't eagerly refresh
+        if (!this.latestTokenRefreshExpiry) return;
+
+        const expiresIn = this.latestTokenRefreshExpiry.getTime() - Date.now();
+        if (expiresIn <= REFRESH_IF_TOKEN_EXPIRES_WITHIN_MS) {
+            await this._handleUnknownToken();
+        }
+    }
+
+    /**
+     * This function is called when an M_UNKNOWN_TOKEN error is encountered.
+     * It will attempt to refresh the access token if it is unknown, and will return a TokenRefreshOutcome.
+     * @param snapshot - the snapshot returned by prepareForRequest
+     * @param attempt - the number of attempts made for this request so far
+     * @returns a TokenRefreshOutcome indicating the result of the refresh attempt
+     */
+    public async handleUnknownToken(snapshot: Snapshot, attempt: number): Promise<TokenRefreshOutcome> {
+        return this._handleUnknownToken(snapshot, attempt);
+    }
+
+    /* eslint-disable @typescript-eslint/naming-convention */
+    private async _handleUnknownToken(): Promise<TokenRefreshOutcome>;
+    private async _handleUnknownToken(snapshot: Snapshot, attempt: number): Promise<TokenRefreshOutcome>;
+    private async _handleUnknownToken(snapshot?: Snapshot, attempt?: number): Promise<TokenRefreshOutcome> {
+        if (snapshot?.expiry) {
+            // If our token is unknown, but it should not have expired yet, then we should not refresh
+            const expiresIn = snapshot.expiry.getTime() - Date.now();
+            // If it still has plenty of time left on the clock, we assume something else must be wrong and
+            // do not refresh. Otherwise if it's expired, or will soon, we try refreshing.
+            if (expiresIn >= REFRESH_ON_ERROR_IF_TOKEN_EXPIRES_WITHIN_MS) {
+                return TokenRefreshOutcome.Logout;
+            }
+        }
+
+        if (!snapshot || snapshot?.accessToken === this.opts.accessToken) {
+            // If we have a snapshot, but the access token is the same as the current one then a refresh
+            // did not happen behind us but one may be ongoing anyway
+            this.tokenRefreshPromise ??= this.doTokenRefresh(attempt);
+
+            try {
+                return await this.tokenRefreshPromise;
+            } finally {
+                this.tokenRefreshPromise = undefined;
+            }
+        }
+
+        // We may end up here if the token was refreshed in the background due to another request
+        return TokenRefreshOutcome.Success;
+    }
+
+    /**
+     * Attempt to refresh access tokens.
+     * On success, sets new access and refresh tokens in opts.
+     * @returns Promise that resolves to a boolean - true when token was refreshed successfully
+     */
+    private async doTokenRefresh(attempt?: number): Promise<TokenRefreshOutcome> {
+        if (!this.opts.refreshToken || !this.opts.tokenRefreshFunction) {
+            this.opts.logger?.error("Unable to refresh token - no refresh token or refresh function");
+            return TokenRefreshOutcome.Logout;
+        }
+
+        if (attempt && attempt > 1) {
+            // Exponential backoff to ensure we don't trash the server, up to 2^5 seconds
+            await sleep(1000 * Math.min(32, 2 ** attempt));
+        }
+
+        try {
+            this.opts.logger?.debug("Attempting to refresh token");
+            const { accessToken, refreshToken, expiry } = await this.opts.tokenRefreshFunction(this.opts.refreshToken);
+            this.opts.accessToken = accessToken;
+            this.opts.refreshToken = refreshToken;
+            this.latestTokenRefreshExpiry = expiry;
+            this.opts.logger?.debug("... token refresh complete, new token expiry:", expiry);
+
+            // successfully got new tokens
+            return TokenRefreshOutcome.Success;
+        } catch (error) {
+            // If we get a TokenError or BriijError, we should log out, otherwise assume transient
+            if (error instanceof TokenRefreshLogoutError || error instanceof BriijError) {
+                this.opts.logger?.error("Failed to refresh token", error);
+                return TokenRefreshOutcome.Logout;
+            }
+
+            this.opts.logger?.warn("Failed to refresh token", error);
+            return TokenRefreshOutcome.Failure;
+        }
+    }
+}

package/src/http-api/utils.ts

@@ -0,0 +1,217 @@
+/*
+Copyright 2022 - 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 { parse as parseContentType, type ParsedMediaType } from "content-type";
+
+import { logger } from "../logger.ts";
+import { sleep } from "../utils.ts";
+import {
+    ConnectionError,
+    HTTPError,
+    BriijError,
+    BriijSafetyError,
+    BriijSafetyErrorCode,
+    safeGetRetryAfterMs,
+} from "./errors.ts";
+
+// Ponyfill for https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout
+export function timeoutSignal(ms: number): AbortSignal {
+    const controller = new AbortController();
+    setTimeout(() => {
+        controller.abort();
+    }, ms);
+
+    return controller.signal;
+}
+
+export function anySignal(signals: AbortSignal[]): {
+    signal: AbortSignal;
+    cleanup(): void;
+} {
+    const controller = new AbortController();
+
+    function cleanup(): void {
+        for (const signal of signals) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+
+    function onAbort(): void {
+        controller.abort();
+        cleanup();
+    }
+
+    for (const signal of signals) {
+        if (signal.aborted) {
+            onAbort();
+            break;
+        }
+        signal.addEventListener("abort", onAbort);
+    }
+
+    return {
+        signal: controller.signal,
+        cleanup,
+    };
+}
+
+/**
+ * Attempt to turn an HTTP error response into a Javascript Error.
+ *
+ * If it is a JSON response, we will parse it into a BriijError. Otherwise
+ * we return a generic Error.
+ *
+ * @param response - response object
+ * @param body - raw body of the response
+ * @returns
+ */
+export function parseErrorResponse(response: XMLHttpRequest | Response, body?: string): Error {
+    const httpHeaders = isXhr(response)
+        ? new Headers(
+              response
+                  .getAllResponseHeaders()
+                  .trim()
+                  .split(/[\r\n]+/)
+                  .map((header): [string, string] => {
+                      const colonIdx = header.indexOf(":");
+                      return [header.substring(0, colonIdx), header.substring(colonIdx + 1)];
+                  }),
+          )
+        : response.headers;
+
+    let contentType: ParsedMediaType | null;
+    try {
+        contentType = getResponseContentType(httpHeaders);
+    } catch (e) {
+        return <Error>e;
+    }
+    if (contentType?.type === "application/json" && body) {
+        const errorBody = JSON.parse(body);
+        if (errorBody.errcode && BriijSafetyErrorCode.matches(errorBody.errcode)) {
+            return new BriijSafetyError(
+                errorBody,
+                response.status,
+                isXhr(response) ? response.responseURL : response.url,
+                undefined,
+                httpHeaders,
+            );
+        }
+        return new BriijError(
+            errorBody,
+            response.status,
+            isXhr(response) ? response.responseURL : response.url,
+            undefined,
+            httpHeaders,
+        );
+    }
+    if (contentType?.type === "text/plain") {
+        return new HTTPError(`Server returned ${response.status} error: ${body}`, response.status, httpHeaders);
+    }
+    return new HTTPError(`Server returned ${response.status} error`, response.status, httpHeaders);
+}
+
+function isXhr(response: XMLHttpRequest | Response): response is XMLHttpRequest {
+    return "getResponseHeader" in response;
+}
+
+/**
+ * extract the Content-Type header from response headers, and
+ * parse it to a `{type, parameters}` object.
+ *
+ * returns null if no content-type header could be found.
+ *
+ * @param response - response object
+ * @returns parsed content-type header, or null if not found
+ */
+function getResponseContentType(headers: Headers): ParsedMediaType | null {
+    const contentType = headers.get("Content-Type");
+    if (contentType === null) return null;
+
+    try {
+        return parseContentType(contentType);
+    } catch (e) {
+        throw new Error(`Error parsing Content-Type '${contentType}': ${e}`);
+    }
+}
+
+/**
+ * Retries a network operation run in a callback.
+ * @param maxAttempts - maximum attempts to try
+ * @param callback - callback that returns a promise of the network operation. If rejected with ConnectionError, it will be retried by calling the callback again.
+ * @returns the result of the network operation
+ * @throws {@link ConnectionError} If after maxAttempts the callback still throws ConnectionError
+ */
+export async function retryNetworkOperation<T>(maxAttempts: number, callback: () => Promise<T>): Promise<T> {
+    let attempts = 0;
+    let lastConnectionError: ConnectionError | null = null;
+    while (attempts < maxAttempts) {
+        try {
+            if (attempts > 0) {
+                const timeout = 1000 * Math.pow(2, attempts);
+                logger.log(`network operation failed ${attempts} times, retrying in ${timeout}ms...`);
+                await sleep(timeout);
+            }
+            return await callback();
+        } catch (err) {
+            if (err instanceof ConnectionError) {
+                attempts += 1;
+                lastConnectionError = err;
+            } else {
+                throw err;
+            }
+        }
+    }
+    throw lastConnectionError;
+}
+
+/**
+ * Calculate the backoff time for a request retry attempt.
+ * This produces wait times of 2, 4, 8, and 16 seconds (30s total) after which we give up. If the
+ * failure was due to a rate limited request, the time specified in the error is returned.
+ *
+ * Returns -1 if the error is not retryable, or if we reach the maximum number of attempts.
+ *
+ * @param err - The error thrown by the http call
+ * @param attempts - The number of attempts made so far, including the one that just failed.
+ * @param retryConnectionError - Whether to retry on {@link ConnectionError} (CORS, connection is down, etc.)
+ */
+export function calculateRetryBackoff(err: any, attempts: number, retryConnectionError: boolean): number {
+    if (attempts > 4) {
+        return -1; // give up
+    }
+
+    if (err instanceof ConnectionError && !retryConnectionError) {
+        return -1;
+    }
+
+    if (err.httpStatus && Math.floor(err.httpStatus / 100) === 4 && err.httpStatus !== 429) {
+        // client error; no amount of retrying will save you now (except for rate limiting which is handled below)
+        return -1;
+    }
+
+    if (err.name === "AbortError") {
+        // this is a client timeout, that is already very high 60s/80s
+        // we don't want to retry, as it could do it for very long
+        return -1;
+    }
+
+    // If we are trying to send an event (or similar) that is too large in any way, then retrying won't help
+    if (err.name === "M_TOO_LARGE") {
+        return -1;
+    }
+
+    return safeGetRetryAfterMs(err, 1000 * Math.pow(2, attempts));
+}