From d7296172ace62ba980eb9f57560aa39c6dedb283 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 10 Dec 2024 21:30:31 +0000 Subject: [PATCH 1/2] Add another entrypoint using wasm-as-esm support Some environments support loading WASM modules directly as ESM, and that gives better results than the existing entry points. For example, Webpack is able to include it inside the same bundle as the rest of the sources. --- README.md | 23 ++++++++++++++++++++++- index-wasm-esm.mjs | 39 +++++++++++++++++++++++++++++++++++++++ index.mjs | 2 +- package.json | 4 ++++ 4 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 index-wasm-esm.mjs diff --git a/README.md b/README.md index 32bb906c4..493ed90c9 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,28 @@ Encryption](https://en.wikipedia.org/wiki/End-to-end_encryption)) for } ``` -## Building + See the [API documentation](https://matrix-org.github.io/matrix-rust-sdk-crypto-wasm/) for more information. + +3. Build your project. + + The packaging of this library aims to "just work" the same as any plain-javascript project would: it includes + separate entry points for Node.js-like environments (which read the WASM file via + [`fs.readFile()`](https://nodejs.org/api/fs.html#fsreadfilepath-options-callback)) and web-like environments (which + download the WASM file with [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)). There are + both CommonJS and ES Module entry points for each environment; an appropriate entrypoint should be selected + automatically. + + If your environment supports the experimental [ES Module Integration Proposal for WebAssembly](https://github.com/WebAssembly/esm-integration), + you can instead use that, by setting the `matrix-org:wasm-esm` custom [export condition](https://nodejs.org/api/packages.html#conditional-exports). + This is only supported when the library is imported as an ES Module. For example: + + - In Webpack, set [`experiments.asyncWebAssembly`](https://webpack.js.org/configuration/experiments/#experiments) + to `true` and [`resolve.conditionNames`](https://webpack.js.org/configuration/resolve/#resolveconditionnames) + to `["matrix-org:wasm-esm", "..."]` (the `"..."` preserves default condition names). + - In Node.js, invoke with commandline arguments [`--experimental-wasm-modules`](https://nodejs.org/api/esm.html#wasm-modules) + [`--conditions=wasm-esm`](https://nodejs.org/api/cli.html#-c-condition---conditionscondition). + +## Building matrix-sdk-crypto-wasm These WebAssembly bindings are written in [Rust]. To build them, you need to install the Rust compiler, see [the Install Rust diff --git a/index-wasm-esm.mjs b/index-wasm-esm.mjs new file mode 100644 index 000000000..8015d9b00 --- /dev/null +++ b/index-wasm-esm.mjs @@ -0,0 +1,39 @@ +// 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. + +// @ts-check + +/** + * This is the entry point for ESM environments which support the ES Module Integration Proposal for WebAssembly [1]. + * + * [1]: https://github.com/webassembly/esm-integration + */ + +import * as bindings from "./pkg/matrix_sdk_crypto_wasm_bg.js"; + +/** @type {typeof import("./pkg/matrix_sdk_crypto_wasm_bg.wasm.d.ts")} */ +// @ts-expect-error TSC can't find the definitions file, for some reason. +const wasm = await import("./pkg/matrix_sdk_crypto_wasm_bg.wasm"); +bindings.__wbg_set_wasm(wasm); +wasm.__wbindgen_start(); + +/** + * A no-op, for compatibility with other entry points. + * + * @returns {Promise} + */ +export async function initAsync() {} + +// Re-export everything from the generated javascript wrappers +export * from "./pkg/matrix_sdk_crypto_wasm_bg.js"; diff --git a/index.mjs b/index.mjs index bf8df6702..be247fe7d 100644 --- a/index.mjs +++ b/index.mjs @@ -15,7 +15,7 @@ // @ts-check /** - * This is the entrypoint on non-node ESM environments (such as Element Web). + * This is the entrypoint on non-node ESM environments. * `asyncLoad` will load the WASM module using a `fetch` call. */ diff --git a/package.json b/package.json index 09aecfed9..9b2d22b98 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,10 @@ ], "exports": { ".": { + "matrix-org:wasm-esm": { + "types": "./index.d.ts", + "default": "./index-wasm-esm.mjs" + }, "require": { "types": "./index.d.ts", "node": "./node.js", From 0978c3b45d6f637808c9c285921acbca15a298f7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 11 Dec 2024 11:52:59 +0000 Subject: [PATCH 2/2] address review comments --- index-wasm-esm.mjs | 52 +++++++++++++++++++++++++++++++++++++++------- index.mjs | 11 +++++++--- package.json | 1 + 3 files changed, 54 insertions(+), 10 deletions(-) diff --git a/index-wasm-esm.mjs b/index-wasm-esm.mjs index 8015d9b00..89db51798 100644 --- a/index-wasm-esm.mjs +++ b/index-wasm-esm.mjs @@ -22,18 +22,56 @@ import * as bindings from "./pkg/matrix_sdk_crypto_wasm_bg.js"; -/** @type {typeof import("./pkg/matrix_sdk_crypto_wasm_bg.wasm.d.ts")} */ -// @ts-expect-error TSC can't find the definitions file, for some reason. -const wasm = await import("./pkg/matrix_sdk_crypto_wasm_bg.wasm"); -bindings.__wbg_set_wasm(wasm); -wasm.__wbindgen_start(); +// Although we could simply instantiate the WASM at import time with a top-level `await`, +// we avoid that, to make it easier for callers to delay loading the WASM (and instead +// wait until `initAsync` is called). (Also, Safari 14 doesn't support top-level `await`.) +// +// However, having done so, there is no way to synchronously load the WASM if the user ends +// up using the bindings before calling `initAsync` (unlike under Node.js), so we just throw +// an error. +bindings.__wbg_set_wasm( + new Proxy( + {}, + { + get() { + throw new Error( + "@matrix-org/matrix-sdk-crypto-wasm was used before it was initialized. Call `initAsync` first.", + ); + }, + }, + ), +); + +/** + * Stores a promise of the `loadModuleAsync` call + * @type {Promise | null} + */ +let modPromise = null; + +/** + * Loads and instantiates the WASM module asynchronously + * + * @returns {Promise} + */ +async function loadModuleAsync() { + /** @type {typeof import("./pkg/matrix_sdk_crypto_wasm_bg.wasm.d.ts")} */ + // @ts-expect-error TSC can't find the definitions file, for some reason. + const wasm = await import("./pkg/matrix_sdk_crypto_wasm_bg.wasm"); + bindings.__wbg_set_wasm(wasm); + wasm.__wbindgen_start(); +} /** - * A no-op, for compatibility with other entry points. + * Load the WebAssembly module in the background, if it has not already been loaded. + * + * Returns a promise which will resolve once the other methods are ready. * * @returns {Promise} */ -export async function initAsync() {} +export async function initAsync() { + if (!modPromise) modPromise = loadModuleAsync(); + await modPromise; +} // Re-export everything from the generated javascript wrappers export * from "./pkg/matrix_sdk_crypto_wasm_bg.js"; diff --git a/index.mjs b/index.mjs index be247fe7d..b792f114f 100644 --- a/index.mjs +++ b/index.mjs @@ -23,8 +23,13 @@ import * as bindings from "./pkg/matrix_sdk_crypto_wasm_bg.js"; const moduleUrl = new URL("./pkg/matrix_sdk_crypto_wasm_bg.wasm", import.meta.url); -// We want to throw an error if the user tries to use the bindings before -// calling `initAsync`. +// Although we could simply instantiate the WASM at import time with a top-level `await`, +// we avoid that, to make it easier for callers to delay loading the WASM (and instead +// wait until `initAsync` is called). (Also, Safari 14 doesn't support top-level `await`.) +// +// However, having done so, there is no way to synchronously load the WASM if the user ends +// up using the bindings before calling `initAsync` (unlike under Node.js), so we just throw +// an error. bindings.__wbg_set_wasm( new Proxy( {}, @@ -39,7 +44,7 @@ bindings.__wbg_set_wasm( ); /** - * Stores a promise of the `loadModule` call + * Stores a promise of the `loadModuleAsync` call * @type {Promise | null} */ let modPromise = null; diff --git a/package.json b/package.json index 9b2d22b98..6f602e82f 100644 --- a/package.json +++ b/package.json @@ -39,6 +39,7 @@ "files": [ "index.mjs", "index.js", + "index-wasm-esm.mjs", "index.d.ts", "node.mjs", "node.js",