Crate ruma

Expand description

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 features

By default, the ruma crates are only able to handle strictly spec-compliant data and behaviour. However, due to the fact that Matrix is federated, that it is used by various implementations that might have different bugs, and that much of its data is immutable, they need to be able to interoperate with data that might differ slightly from the specification.

This is the role of the compat-* cargo features. They allow the crates be more tolerant of external data and incoming requests for known and reasonable deviations from the spec, usually for historical reasons. They however do not permit the ruma crates to generate data that is not spec-compliant.

Each cargo feature is documented briefly in the cargo manifest of the crate, and more thoroughly where the feature applies.

§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.

§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, 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.

Re-exports§

pub use assign::assign;
pub use js_int::int;
pub use js_int::uint;
pub use js_int::Int;
pub use js_int::UInt;
pub use js_option::JsOption;
pub use web_time as time;

Modules§

apiapi: (De)serializable types for various Matrix APIs requests and responses and abstractions for them.
authentication: Common types for authentication.
canonical_jsoncanonical-json: Canonical JSON types and related functions.
clientclient: A minimal Matrix client library.
directory: Common types for room directory endpoints.
encryption: Common types for encryption related tasks.
eventsevents: (De)serializable types for the events in the Matrix specification. These types are used by other Ruma crates.
htmlhtml: Opinionated HTML parsing and manipulating library.
http_headers: Helpers for HTTP headers.
matrix_uri: Matrix URIs.
media: Common types and functions for the content repository.
power_levels: Common types for the m.room.power_levels event.
presence: Common types for the presence module.
push: Common types for the push notifications module.
room: Common types for rooms.
serde: (De)serialization helpers for other Ruma crates.
server_utilserver-util: Collection of helpers for implementing Matrix homeservers using Ruma.
signaturessignatures: Digital signatures according to the Matrix specification.
space: Common types for spaces.
state_resstate-res
thirdparty: Common types for the third party networks module.
to_device: Common types for the Send-To-Device Messaging
user_id: Matrix user identifiers.

Macros§

base64_public_key: Compile-time checked Base64PublicKey construction.
device_id: Shorthand for <&DeviceId>::from.
event_id: Compile-time checked EventId construction.
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.
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.
Clientclient-ext-client-api: A client for the Matrix client-server API.
ClientSecret: A client secret.
DeviceId: A Matrix device ID.
EventId: A Matrix event ID.
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.
UserId: A Matrix user ID.
VoipId: A VoIP identifier.

Enums§

CanonicalJsonErrorcanonical-json: The set of possible errors when serializing to canonical JSON.
CanonicalJsonValuecanonical-json: 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.
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§

CanonicalJsonObjectcanonical-json: 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.

Crate rumaCopy item path