Welcome to the [Node.js] binding for the Rust [`matrix-sdk-crypto`] library! This binding is part of the [`matrix-rust-sdk`] project, which is a library implementation of a [Matrix] client-server.
npm install @matrix-org/matrix-sdk-crypto-nodejsmatrix-sdk-crypto-nodejsWelcome to the [Node.js] binding for the Rust [matrix-sdk-crypto]
library! This binding is part of the [matrix-rust-sdk] project,
which is a library implementation of a [Matrix] client-server.
matrix-sdk-crypto-nodejs is a no-network-IO implementation of a
state machine, named OlmMachine, that handles E2EE (End-to-End
Encryption) for
[Matrix] clients.
Just add the latest release to your package.json:
``sh`
$ npm install --save @matrix-org/matrix-sdk-crypto-nodejs
When installing, NPM will download the corresponding prebuilt Rust library for your current host system. The following are supported:
| Platform | Architecture | Triple | Prebuilt available |
|---|---|---|---|
| Linux | aarch | aarch64-unknown-linux-gnu | ✅ |
arm-unknown-linux-gnueabihf | ✅ | ||
amd | x86_64-unknown-linux-gnu | ✅ | |
x86_64-unknown-linux-musl | ✅ | ||
i686-unknown-linux-gnu | ✅ | ||
s390x | s390x-unknown-linux-gnu | ✅ | |
| macOS | aarch | arch64-apple-darwin | ✅ |
amd | x86_64-apple-darwin | ✅ | |
| Windows | aarch | aarch64-pc-windows-msvc | ✅ |
amd | x86_64-pc-windows-msvc | ✅ | |
i686-pc-windows-msvc | ✅ |
This Node.js binding is written in [Rust]. To build this binding, you
need to install the Rust compiler, see the Install Rust
Page. Then, the workflow is
pretty classical by using [npm], see the Downloading and installing
Node.js and npm
Page.
The binding is compatible with, and tested against, the Node.js
versions that are in “current” or “active” states,
according to the Node.js Releases
Page, _and_ which are
compatible with NAPI v6 (Node.js
API). It
means that this binding will work with the following versions:
22.0.0 and 24.0.0.
Once the Rust compiler, Node.js and npm are installed, you can run the
following commands:
`sh`
$ npm install --ignore-scripts
$ npm run build
$ npm run test
An index.js, index.d.ts and a *.node files should be
generated. At the same level of those files, you can edit a file and
try this:
`javascript
const { OlmMachine } = require("./index.js");
// Let's see what we can do.
`
The OlmMachine state machine works in a push/pull manner:
- You push state changes and events retrieved from a Matrix homeserver
/sync response, into the state machine,
- You pull requests that you will need to send back to the homeserver
out of the state machine.
`javascript
const { OlmMachine, UserId, DeviceId, RoomId, DeviceLists } = require("./index.js");
async function main() {
// Define a user ID.
const alice = new UserId("@alice:example.org");
// Define a device ID.
const device = new DeviceId("DEVICEID");
// Let's create the OlmMachine state machine.
const machine = await OlmMachine.initialize(alice, device);
// Let's pretend we have received changes and events from a
// /sync endpoint of a Matrix homeserver, …
const toDeviceEvents = "[]"; // JSON-encoded list of events
const changedDevices = new DeviceLists();
const oneTimeKeyCounts = {};
const unusedFallbackKeys = [];
// … and push them into the state machine.
const decryptedToDevice = await machine.receiveSyncChanges(
toDeviceEvents,
changedDevices,
oneTimeKeyCounts,
unusedFallbackKeys,
);
// Now, let's pull requests that we need to send out to the Matrix
// homeserver.
const outgoingRequests = await machine.outgoingRequests();
// To complete the workflow, send the requests here out and call
// machine.markRequestAsSent.
}
main();
`
If you want to enable tracing, i.e. to get the
logs, you should re-compile the extension with the tracing feature
turned on:
`sh`
$ npm run build -- --features tracing
Now, you can use the MATRIX_LOG environment variable to tweak the log filtering, such as:
`sh`
$ MATRIX_LOG=debug npm run test
See
tracing-subscriber
to learn more about the RUST_LOG/MATRIX_LOG environment variable.
#### Using tracing in dependent projects
To enable tracing in client applications that import these bindings, here's how to do it in
a local development environment:
- In this directory, run npm link to make your local build of the bindings available tonpm link @matrix-org/matrix-sdk-crypto-nodejs
other Node projects on your system
- In your client app's source directory, run initTracing
to make it use your trace-enabled local build of the bindings
- In your client app's source code, add a call to near startup timeMATRIX_LOG
- Run your app with the environment variable set to the desired log level
Either npm link command may be substituted with yarn link.
The documentation can be found
online.
To generate the documentation locally, please run the following
command:
`sh`
$ npm run doc
The documentation is generated in the ./docs directory.
[Node.js]: https://nodejs.org/
[matrix-sdk-crypto]: https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-cryptomatrix-rust-sdk`]: https://github.com/matrix-org/matrix-rust-sdk
[
[Matrix]: https://matrix.org/
[Rust]: https://www.rust-lang.org/
[npm]: https://www.npmjs.com/