(De)serialize error response details

Allow client widget drivers to serialize Matrix API error responses into
JSON to be received by the requesting widget.

Author: AndrewFerr

src/ClientWidgetApi.ts

@@ -22,7 +22,7 @@ import { WidgetApiDirection } from "./interfaces/WidgetApiDirection";
 import { IWidgetApiRequest, IWidgetApiRequestEmptyData } from "./interfaces/IWidgetApiRequest";
 import { IContentLoadedActionRequest } from "./interfaces/ContentLoadedAction";
 import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./interfaces/WidgetApiAction";
-import { IWidgetApiErrorResponseData, isMatrixError } from "./interfaces/IWidgetApiErrorResponse";
+import { IWidgetApiErrorResponseData } from "./interfaces/IWidgetApiErrorResponse";
 import { Capability, MatrixCapabilities } from "./interfaces/Capabilities";
 import { IOpenIDUpdate, ISendEventDetails, ISendDelayedEventDetails, WidgetDriver } from "./driver/WidgetDriver";
 import {
@@ -330,15 +330,13 @@ export class ClientWidgetApi extends EventEmitter {
             });
         }
 
-        const onErr = (e: any) => {
+        const onErr = (e: unknown) => {
             console.error("[ClientWidgetApi] Failed to handle navigation: ", e);
-            return this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {message: "Error handling navigation"},
-            });
+            this.handleDriverError(e, request, "Error handling navigation");
         };
 
         try {
-            this.driver.navigate(request.data.uri.toString()).catch(e => onErr(e)).then(() => {
+            this.driver.navigate(request.data.uri.toString()).catch((e: unknown) => onErr(e)).then(() => {
                 return this.transport.reply<IWidgetApiAcknowledgeResponseData>(request, {});
             });
         } catch (e) {
@@ -556,12 +554,7 @@ export class ClientWidgetApi extends EventEmitter {
             });
         }).catch((e: unknown) => {
             console.error("error sending event: ", e);
-            return this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {
-                    message: "Error sending event",
-                    ...(isMatrixError(e) && e),
-                },
-            });
+            this.handleDriverError(e, request, "Error sending event");
         });
     }
 
@@ -586,12 +579,7 @@ export class ClientWidgetApi extends EventEmitter {
                     return this.transport.reply<IWidgetApiAcknowledgeResponseData>(request, {});
                 }).catch((e: unknown) => {
                     console.error("error updating delayed event: ", e);
-                    return this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                        error: {
-                            message: "Error updating delayed event",
-                            ...(isMatrixError(e) && e),
-                        },
-                    });
+                    this.handleDriverError(e, request, "Error updating delayed event");
                 });
                 break;
             default:
@@ -624,9 +612,7 @@ export class ClientWidgetApi extends EventEmitter {
                 await this.transport.reply<ISendToDeviceFromWidgetResponseData>(request, {});
             } catch (e) {
                 console.error("error sending to-device event", e);
-                await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                    error: {message: "Error sending event"},
-                });
+                this.handleDriverError(e, request, "Error sending event");
             }
         }
     }
@@ -741,12 +727,7 @@ export class ClientWidgetApi extends EventEmitter {
             );
         } catch (e) {
             console.error("error getting the relations", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {
-                    message: "Unexpected error while reading relations",
-                    ...(isMatrixError(e) && e),
-                },
-            });
+            this.handleDriverError(e, request, "Unexpected error while reading relations");
         }
     }
 
@@ -787,12 +768,7 @@ export class ClientWidgetApi extends EventEmitter {
             );
         } catch (e) {
             console.error("error searching in the user directory", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {
-                    message: "Unexpected error while searching in the user directory",
-                    ...(isMatrixError(e) && e),
-                },
-            });
+            this.handleDriverError(e, request, "Unexpected error while searching in the user directory");
         }
     }
 
@@ -812,12 +788,7 @@ export class ClientWidgetApi extends EventEmitter {
             );
         } catch (e) {
             console.error("error while getting the media configuration", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {
-                    message: "Unexpected error while getting the media configuration",
-                    ...(isMatrixError(e) && e),
-                },
-            });
+            this.handleDriverError(e, request, "Unexpected error while getting the media configuration");
         }
     }
 
@@ -837,12 +808,7 @@ export class ClientWidgetApi extends EventEmitter {
             );
         } catch (e) {
             console.error("error while uploading a file", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {
-                    message: "Unexpected error while uploading a file",
-                    ...(isMatrixError(e) && e),
-                },
-            });
+            this.handleDriverError(e, request, "Unexpected error while uploading a file");
         }
     }
 
@@ -862,12 +828,20 @@ export class ClientWidgetApi extends EventEmitter {
             );
         } catch (e) {
             console.error("error while downloading a file", e);
-            this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: { message: "Unexpected error while downloading a file" },
-            });
+            this.handleDriverError(e, request, "Unexpected error while downloading a file");
         }
     }
 
+    private handleDriverError(e: unknown, request: IWidgetApiRequest, message: string) {
+        const matrixApiError = this.driver.processError(e);
+        this.transport.reply<IWidgetApiErrorResponseData>(request, {
+            error: {
+                message,
+                ...(matrixApiError && { matrix_api_error: { ...matrixApiError } }),
+            },
+        });
+    }
+
     private handleMessage(ev: CustomEvent<IWidgetApiRequest>) {
         if (this.isStopped) return;
         const actionEv = new CustomEvent(`action:${ev.detail.action}`, {

src/WidgetApi.ts

@@ -33,7 +33,7 @@ import {
 import { ITransport } from "./transport/ITransport";
 import { PostmessageTransport } from "./transport/PostmessageTransport";
 import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./interfaces/WidgetApiAction";
-import { IWidgetApiErrorResponseData } from "./interfaces/IWidgetApiErrorResponse";
+import { IWidgetApiErrorResponseData, IWidgetApiErrorResponseDataDetails } from "./interfaces/IWidgetApiErrorResponse";
 import { IStickerActionRequestData } from "./interfaces/StickerAction";
 import { IStickyActionRequestData, IStickyActionResponseData } from "./interfaces/StickyAction";
 import {
@@ -95,6 +95,15 @@ import {
     UpdateDelayedEventAction,
 } from "./interfaces/UpdateDelayedEventAction";
 
+export class WidgetApiResponseError extends Error {
+    public constructor(
+        message: string,
+        public readonly data: IWidgetApiErrorResponseDataDetails,
+    ) {
+        super(message);
+    }
+}
+
 /**
  * API handler for widgets. This raises events for each action
  * received as `action:${action}` (eg: "action:screenshot").

src/driver/WidgetDriver.ts

@@ -19,6 +19,7 @@ import {
     IOpenIDCredentials,
     OpenIDRequestState,
     SimpleObservable,
+    IMatrixApiError,
     IRoomEvent,
     IRoomAccountData,
     ITurnServer,
@@ -358,4 +359,15 @@ export abstract class WidgetDriver {
     ): Promise<{ file: XMLHttpRequestBodyInit }> {
         throw new Error("Download file is not implemented");
     }
+
+    /**
+     * Expresses an error thrown by a Matrix API request made by this driver
+     * in a format compatible with the Widget API.
+     * @param error The error to handle.
+     * @returns The error expressed as a {@link IMatrixApiError},
+     * or undefined if it cannot be expressed as one.
+     */
+    public processError(error: unknown): IMatrixApiError | undefined {
+        return undefined;
+    }
 }

src/interfaces/IWidgetApiErrorResponse.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 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.
@@ -16,34 +16,42 @@
 
 import { IWidgetApiResponse, IWidgetApiResponseData } from "./IWidgetApiResponse";
 
-interface IWidgetApiErrorData {
-    message: string;
+/**
+ * The format of errors returned by Matrix API requests
+ * made by a WidgetDriver.
+ */
+export interface IMatrixApiError {
+    /** The HTTP status code of the associated request. */
+    http_status: number;  // eslint-disable-line camelcase
+    /** Any HTTP response headers that are relevant to the error. */
+    http_headers: {[name: string]: string};  // eslint-disable-line camelcase
+    /** The URL of the failed request. */
+    url: string;
+    /** @see {@link https://spec.matrix.org/latest/client-server-api/#standard-error-response} */
+    response: {
+        errcode: string;
+        error: string;
+    } & IWidgetApiResponseData; // extensible
 }
 
-interface IMatrixErrorData {
-    httpStatus?: number;
-    errcode?: string;
+export interface IWidgetApiErrorResponseDataDetails extends IWidgetApiResponseData {
+    /** Set if the error came from a Matrix API request made by a widget driver */
+    matrix_api_error?: IMatrixApiError;  // eslint-disable-line camelcase
 }
 
 export interface IWidgetApiErrorResponseData extends IWidgetApiResponseData {
-    error: IWidgetApiErrorData & IMatrixErrorData;
-}
-
-export function isMatrixError(err: unknown): err is IMatrixErrorData {
-    return typeof err === "object" && err !== null && (
-        "httpStatus" in err && typeof err.httpStatus === "number" ||
-        "errcode" in err && typeof err.errcode === "string"
-    );
+    error: {
+        /** A user-friendly string describing the error */
+        message: string;
+    } & IWidgetApiErrorResponseDataDetails;
 }
 
 export interface IWidgetApiErrorResponse extends IWidgetApiResponse {
     response: IWidgetApiErrorResponseData;
 }
 
-export function isErrorResponse(responseData: IWidgetApiResponseData): boolean {
-    if ("error" in responseData) {
-        const err = <IWidgetApiErrorResponseData>responseData;
-        return !!err.error.message;
-    }
-    return false;
+export function isErrorResponse(responseData: IWidgetApiResponseData): responseData is IWidgetApiErrorResponseData {
+    const error = responseData.error;
+    return typeof error === "object" && error !== null &&
+        "message" in error && typeof error.message === "string";
 }

src/transport/ITransport.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 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.
@@ -71,11 +71,12 @@ export interface ITransport extends EventEmitter {
 
     /**
      * Sends a request to the remote end.
-     * @param {WidgetApiAction} action The action to send.
-     * @param {IWidgetApiRequestData} data The request data.
-     * @returns {Promise<IWidgetApiResponseData>} A promise which resolves
-     * to the remote end's response, or throws with an Error if the request
-     * failed.
+     * @param action The action to send.
+     * @param data The request data.
+     * @returns A promise which resolves to the remote end's response.
+     * @throws {Error} if the request failed with a generic error.
+     * @throws {WidgetApiResponseError} if the request failed with error details
+     * that can be communicated to the Widget API.
      */
     send<T extends IWidgetApiRequestData, R extends IWidgetApiResponseData = IWidgetApiAcknowledgeResponseData>(
         action: WidgetApiAction,
@@ -88,9 +89,10 @@ export interface ITransport extends EventEmitter {
      * data.
      * @param {WidgetApiAction} action The action to send.
      * @param {IWidgetApiRequestData} data The request data.
-     * @returns {Promise<IWidgetApiResponseData>} A promise which resolves
-     * to the remote end's response, or throws with an Error if the request
-     * failed.
+     * @returns {Promise<IWidgetApiResponseData>} A promise which resolves to the remote end's response
+     * @throws {Error} if the request failed with a generic error.
+     * @throws {WidgetApiResponseError} if the request failed with error details
+     * that can be communicated to the Widget API.
      */
     sendComplete<T extends IWidgetApiRequestData, R extends IWidgetApiResponse>(action: WidgetApiAction, data: T)
         : Promise<R>;

src/transport/PostmessageTransport.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 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.
@@ -19,11 +19,11 @@ import { ITransport } from "./ITransport";
 import {
     invertedDirection,
     isErrorResponse,
-    IWidgetApiErrorResponseData,
     IWidgetApiRequest,
     IWidgetApiRequestData,
     IWidgetApiResponse,
     IWidgetApiResponseData,
+    WidgetApiResponseError,
     WidgetApiAction,
     WidgetApiDirection,
     WidgetApiToWidgetAction,
@@ -35,16 +35,6 @@ interface IOutboundRequest {
     reject: (err: Error) => void;
 }
 
-class MatrixError extends Error {
-    public constructor(
-        msg: string,
-        public readonly httpStatus?: number,
-        public readonly errcode?: string,
-    ) {
-        super(msg);
-    }
-}
-
 /**
  * Transport for the Widget API over postMessage.
  */
@@ -204,12 +194,8 @@ export class PostmessageTransport extends EventEmitter implements ITransport {
         if (!req) return; // response to an unknown request
 
         if (isErrorResponse(response.response)) {
-            const err = <IWidgetApiErrorResponseData>response.response;
-            req.reject(
-                err.error.httpStatus !== undefined || err.error.errcode !== undefined
-                    ? new MatrixError(err.error.message, err.error.httpStatus, err.error.errcode)
-                    : new Error(err.error.message),
-            );
+            const {message, ...data} = response.response.error;
+            req.reject(new WidgetApiResponseError(message, data));
         } else {
             req.resolve(response);
         }