Crate ruma

Types and traits for working with the Matrix protocol.

This crate re-exports things from all of the other ruma crates so you don’t have to manually keep all the versions in sync.

Which crates are re-exported can be configured through cargo features.

⚠ Some details might be missing because rustdoc has trouble with re-exports so you may need to refer to other crates’ documentations.

🛈 For internal consistency, Ruma uses American spelling for variable names. Names may differ in the serialized representation, as the Matrix specification has a mix of British and American English.

API features

Depending on which parts of Matrix are relevant to you, activate the following features:

• appservice-api – Application Service API.
• client-api – Client-Server API.
• federation-api – Server-Server (Federation) API.
• identity-service-api – Identity Service API.
• push-gateway-api – Push Gateway API.

These features have client- and server-optimized variants that are enabled respectively with the -c and -s suffixes. For example:

• client-api-c – The Client-Server API optimized for the client side.
• client-api-s – The Client-Server API optimized for the server side.

Compatibility feature

• compat increases compatibility with other parts of the Matrix ecosystem, at the expense of deviating from the specification.

Convenience features

These features are only useful if you want to use a method that requires it:

• rand – Generate random identifiers.
• markdown – Parse markdown to construct messages.
• html – Parse HTML to sanitize it or navigate its tree.
  • html-matrix – Enables the matrix feature of ruma-html to parse HTML elements data to typed data as suggested by the Matrix Specification.

Unstable features

By using these features, you opt out of all semver guarantees Ruma otherwise provides:

• unstable-mscXXXX, where XXXX is the MSC number – Upcoming Matrix features that may be subject to change or removal.
• unstable-unspecified – Undocumented Matrix features that may be subject to change or removal.

Common features

These submodules are usually activated by the API features when needed:

• api
• events
• signatures

ruma-client features

The client feature activates [ruma::client][client], and client-ext-client-api activates ruma-clients client-api feature. All other client-* features activate the same feature without the client- prefix on ruma-client. See the crate’s documentation for the effect of these features.

If you are viewing this on docs.rs, you can have a look at the feature dependencies by clicking Feature flags in the toolbar at the top.

Compile-time cfg settings

These settings are accepted at compile time to configure the generated code. They can be set as --cfg={key}={value} using RUSTFLAGS or .cargo/config.toml (under [build] -> rustflags = ["..."]). They can also be configured using an environment variable at compile time, which has the benefit of not requiring to re-compile the whole dependency chain when their value is changed.

• ruma_identifiers_storage – Choose the inner representation of Owned* wrapper types for identifiers. By default they use Box, setting the value to Arc makes them use Arc. This can also be configured by setting the RUMA_IDENTIFIERS_STORAGE environment variable.
• ruma_unstable_exhaustive_types – Most types in Ruma are marked as non-exhaustive to avoid breaking changes when new fields are added in the specification. This setting compiles all types as exhaustive. By enabling this feature you opt out of all semver guarantees Ruma otherwise provides. This can also be configured by setting the RUMA_UNSTABLE_EXHAUSTIVE_TYPES environment variable.

Modules

• api
  (De)serializable types for various Matrix APIs requests and responses and abstractions for them.
• events
  (De)serializable types for the events in the Matrix specification. These types are used by other Ruma crates.
• html
  Opinionated HTML parsing and manipulating library.
• time
  Description

Macros

• assign
  Mutate a struct value in a declarative style.
• base64_public_key
  Compile-time checked Base64PublicKey construction.
• device_id
  Shorthand for <&DeviceId>::from.
• event_id
  Compile-time checked EventId construction.
• int
  Creates an Int from a numeric literal.
• metadata
  Convenient constructor for Metadata constants.
• mxc_uri
  Compile-time checked MxcUri construction.
• owned_base64_public_key
  Compile-time checked OwnedBase64PublicKey construction.
• owned_device_id
  Shorthand for OwnedDeviceId::from.
• owned_event_id
  Compile-time checked OwnedEventId construction.
• owned_mxc_uri
  Compile-time checked OwnedMxcUri construction.
• owned_room_alias_id
  Compile-time checked OwnedRoomAliasId construction.
• owned_room_id
  Compile-time checked OwnedRoomId construction.
• owned_server_name
  Compile-time checked OwnedServerName construction.
• owned_server_signing_key_version
  Compile-time checked OwnedServerSigningKeyVersion construction.
• owned_session_id
  Compile-time checked OwnedSessionId construction.
• owned_user_id
  Compile-time checked OwnedUserId construction.
• room_alias_id
  Compile-time checked RoomAliasId construction.
• room_id
  Compile-time checked RoomId construction.
• room_version_id
  Compile-time checked RoomVersionId construction.
• server_name
  Compile-time checked ServerName construction.
• server_signing_key_version
  Compile-time checked ServerSigningKeyVersion construction.
• session_id
  Compile-time checked SessionId construction.
• uint
  Creates a UInt from a numeric literal.
• user_id
  Compile-time checked UserId construction.

Structs

• Base64PublicKey
  A public key encoded using unpadded base64, used as an identifier for cross-signing keys.
• Base64PublicKeyOrDeviceId
  A Matrix ID that can be either a DeviceId or a Base64PublicKey.
• ClientSecret
  A client secret.
• DeviceId
  A Matrix device ID.
• EventId
  A Matrix event ID.
• Int
  An integer limited to the range of integers that can be represented exactly by an f64.
• KeyId
  A key algorithm and key name delimited by a colon.
• MatrixToUri
  The matrix.to URI representation of a user, room or event.
• MatrixUri
  The matrix: URI representation of a user, room or event.
• MilliSecondsSinceUnixEpoch
  A timestamp represented as the number of milliseconds since the unix epoch.
• MxcUri
  A URI that should be a Matrix-spec compliant MXC URI.
• OneTimeKeyName
  The name of a one-time or fallback key.
• OwnedBase64PublicKey
  Owned variant of Base64PublicKey
• OwnedBase64PublicKeyOrDeviceId
  Owned variant of Base64PublicKeyOrDeviceId
• OwnedClientSecret
  Owned variant of ClientSecret
• OwnedDeviceId
  Owned variant of DeviceId
• OwnedEventId
  Owned variant of EventId
• OwnedKeyId
  Owned variant of KeyId
• OwnedMxcUri
  Owned variant of MxcUri
• OwnedOneTimeKeyName
  Owned variant of OneTimeKeyName
• OwnedRoomAliasId
  Owned variant of RoomAliasId
• OwnedRoomId
  Owned variant of RoomId
• OwnedRoomOrAliasId
  Owned variant of RoomOrAliasId
• OwnedServerName
  Owned variant of ServerName
• OwnedServerSigningKeyVersion
  Owned variant of ServerSigningKeyVersion
• OwnedSessionId
  Owned variant of SessionId
• OwnedTransactionId
  Owned variant of TransactionId
• OwnedUserId
  Owned variant of UserId
• OwnedVoipId
  Owned variant of VoipId
• RoomAliasId
  A Matrix room alias ID.
• RoomId
  A Matrix room ID.
• RoomOrAliasId
  A Matrix room ID or a Matrix room alias ID.
• SecondsSinceUnixEpoch
  A timestamp represented as the number of seconds since the unix epoch.
• ServerName
  A Matrix-spec compliant server name.
• ServerSigningKeyVersion
  The version of a homeserver signing key.
• SessionId
  A session ID.
• Signatures
  Map of all signatures, grouped by entity.
• TransactionId
  A Matrix transaction ID.
• UInt
  An integer limited to the range of non-negative integers that can be represented exactly by an f64.
• UserId
  A Matrix user ID.
• VoipId
  A VoIP identifier.

Enums

• CanonicalJsonError
  The set of possible errors when serializing to canonical JSON.
• CanonicalJsonValue
  Represents a canonical JSON value as per the Matrix specification.
• DeviceKeyAlgorithm
  The algorithms for the device keys defined in the Matrix spec.
• EventEncryptionAlgorithm
  An encryption algorithm to be used to encrypt messages sent to a room.
• IdParseError
  An error encountered when trying to parse an invalid ID string.
• JsOption
  An Option-like type with two data-less variants in addition to Some: Null and Undefined.
• KeyDerivationAlgorithm
  A key algorithm to be used to generate a key from a passphrase.
• MatrixIdError
  An error occurred while validating a MatrixId.
• MatrixToError
  An error occurred while validating a matrix.to URI.
• MatrixUriError
  An error occurred while validating a MatrixURI.
• MxcUriError
  An error occurred while validating an MXC URI.
• OneTimeKeyAlgorithm
  The algorithms for one-time and fallback keys defined in the Matrix spec.
• RoomVersionId
  A Matrix room version ID.
• SigningKeyAlgorithm
  The signing key algorithms defined in the Matrix spec.
• VoipVersionId
  A Matrix VoIP version ID.
• VoipVersionIdError
  An error occurred while validating a VoipVersionId.

Traits

• KeyAlgorithm
  The algorithm of a key.
• KeyName
  Helper trait to validate the name of a key.

Type Aliases

• CanonicalJsonObject
  The inner type of CanonicalJsonValue::Object.
• CrossSigningKeyId
  Algorithm + key name for cross-signing keys.
• CrossSigningOrDeviceSignatures
  Map of cross-signing or device signatures, grouped by user.
• CrossSigningOrDeviceSigningKeyId
  Algorithm + key name for cross-signing or device signing keys.
• DeviceKeyId
  Algorithm + key name for device keys.
• DeviceSignatures
  Map of device signatures, grouped by user.
• DeviceSigningKeyId
  Algorithm + key name for device signing keys.
• EntitySignatures
  Map of key identifier to signature values.
• OneTimeKeyId
  Algorithm + key name for one-time and fallback keys.
• OwnedCrossSigningKeyId
  Algorithm + key name for cross-signing keys.
• OwnedCrossSigningOrDeviceSigningKeyId
  Algorithm + key name for cross-signing or device signing keys.
• OwnedDeviceKeyId
  Algorithm + key name for device keys.
• OwnedDeviceSigningKeyId
  Algorithm + key name for [device signing] keys.
• OwnedOneTimeKeyId
  Algorithm + key name for one-time and fallback keys.
• OwnedServerSigningKeyId
  Algorithm + key name for homeserver signing keys.
• OwnedSigningKeyId
  Algorithm + key name for signing keys.
• ServerSignatures
  Map of server signatures, grouped by server.
• ServerSigningKeyId
  Algorithm + key name for homeserver signing keys.
• SigningKeyId
  Algorithm + key name for signing keys.