ruma/ruma

Ruma – Your home in Matrix

If you want to build a Matrix client or bot, have a look at on docs

Ruma – Your home in Matrix.

A set of Rust crates (libraries) for interacting with the Matrix chat network.

website • chat • documentation (unstable)

Getting started

If you want to build a Matrix client or bot, have a look at matrix-rust-sdk. It builds on Ruma and includes handling of state storage, end-to-end encryption and many other useful things.

For homeservers, bridges and harder-to-categorize software that works with Matrix, you're at the right place. To get started, add ruma to your dependencies:

ruma re-exports all of the other crates, so you don't have to worry about them. Check out the documentation on docs.rs (or on docs.ruma.io if you use use the git dependency).

Status

As of 2022-01-31, we support all events and REST endpoints of the v1 version of the Matrix specification, with v1.1 and v1.2 coverage in progress.

Various changes from in-progress or finished MSCs are also implemented, gated behind the unstable-mscXXXX (where XXXX is the MSC number) Cargo features.

A few less formalized things are gated behind the unstable-pre-spec Cargo feature.

Contributing

See CONTRIBUTING.md.

Minimum Rust version

Ruma currently requires Rust 1.55. In general, we will never require beta or nightly for crates.io releases of our crates, and we will try to avoid releasing crates that depend on features that were only just stabilized.

ruma-signatures is an exception: It uses cryptographic libraries that often use relatively new features and that we don't want to use outdated versions of. It is guaranteed to work with whatever is the latest stable version though.

License

MIT

Issues

Collection of the latest Issues

Cokemonkey11

Cokemonkey11

effort/medium
Comment Icon0
jplatte

jplatte

effort/easy
Comment Icon1

Currently, this is a Vec<OwnedUserId>, but on the wire it's actually a map of user IDs to (currently empty) objects. We could introduce a #[non_exhaustive] struct IgnoredUser (or similar) and change the field type to BTreeMap<OwnedUserId, IgnoredUser>, for forwards compatibility with new fields inside that object.

Docs can point out that you would usually just want to call .keys() / .into_keys() on that field to get just the IDs as an interator.

wdyt @zecakeh?

zecakeh

zecakeh

effort/medium
Comment Icon0

We have methods to help create replies, so we should probably have one to create a replacement (MSC2676), which will be part of the spec in v1.4.

In general, it's only about providing a fallback representation in content and put the new content in m.new_content. The representation of a fallback is however not defined.

There is also a more complicated use case when it is the replacement of a reply, where we also need the reply fallback in the content of the event.

zecakeh

zecakeh

type/spec coverage
Comment Icon1

Here is the current unstable spec changelog to follow our progress, to be updated regularly until the next release.

To be sure we don't miss anything, ALL entries of the changelog should appear here in the same order and category. The ones that we have to implement should be linked to an issue and/or a PR or commit in this repository. If an extra step is necessary when the version is released (like moving it from an unstable feature flag), a subtask should be created. The ones that don't impact us should be struck.

1.1 Client-Server API

Removed Endpoints

  • 1196: Remove unused policy room sharing mechanism, as per MSC3844.

Backwards Compatible Changes

  • 1190: Add a .m.rule.room.server_acl push rule to match m.room.server_acl events, as per MSC3786. #1242
    • Move out of unstable-msc3786
  • 1197: Add Cross-Origin-Resource-Policy (CORP) headers to media repository, as per MSC3828. #1188
  • [x] 1198: Copy a room’s type when upgrading it, as per MSC3818.
  • 1199: Add room_types filter and room_type response to /publicRooms, as per MSC3827.
    • Move out of unstable-msc3827
  • 1201: Add a .m.rule.room.server_acl push rule to match m.room.server_acl events, as per MSC3786.
  • 1211: Add m.replace relations (event edits), as per MSC2676.
    • Move out of unstable-msc2676
  • 1216: Add m.read.private receipts, as per MSC2285. #1243
    • Move out of unstable-msc2285
  • 1216: Make m.fully_read optional on /read_markers, as per MSC2285. #1243
    • Move out of unstable-msc2285
  • 1216: Allow m.fully_read markers to be set from /receipts, as per MSC2285. #1243
    • Move out of unstable-msc2285

Spec Clarifications

  • 1084: Mention that the /rooms/{roomId}/invite endpoint will return a 200 response if the user is already invited to the room.
  • 1135: Fix various typos throughout the specification.
  • 1155: Describe return codes for account data endpoints, and clarify that per-room data does not inherit from the global data.
  • 1161: Fix various typos throughout the specification.
  • 1164: Fix various typos throughout the specification.
  • 1165: Clarify that policy rule globs work like ACL globs. Contributed by Nico. #1277
  • 1166: Clarify the format of some structures in the End-to-end encryption module.
  • 1170: Fix various typos throughout the specification.
  • 1174: Add HTML anchors for object definitions in the formatted specification.
  • 1179: Tweak the styling of <code> snippets in tables rendered from OpenAPI definitions.
  • 1180: Fix various typos throughout the specification.
  • 1185: Update “API Standards” section to clarify how JSON is used.
  • 1210: Clarify that the “device_id”, “user_id” and “access_token” fields are required in the response body of POST /_matrix/client/v3/login.
  • 1215: Fix various typos throughout the specification.
  • 1240: Clarify enum values by separating possible values with commas.
  • 1243: Fix various typos throughout the specification.

1.2 Server-Server API

Spec Clarifications

  • 1174: Add HTML anchors for object definitions in the formatted specification.
  • 1179: Tweak the styling of <code> snippets in tables rendered from OpenAPI definitions.
  • 1185: Update “API Standards” section to clarify how JSON is used.

1.3 Application Service API

Breaking Changes

  • 1200: Replace homeserver authorization approach with an Authorization header instead of access_token when talking to the application service, as per MSC2832. #1248

Spec Clarifications

  • 1174: Add HTML anchors for object definitions in the formatted specification.

1. 4 Identity Service API

Spec Clarifications

  • 1174: Add HTML anchors for object definitions in the formatted specification.
  • 1185: Update “API Standards” section to clarify how JSON is used.

1.5 Push Gateway API

Spec Clarifications

  • 1174: Add HTML anchors for object definitions in the formatted specification.

1.6 Room Versions

Spec Clarifications

  • 1137: For room versions 1 through 10, clarify that events with rejected auth_events must be rejected.
  • 1158: For room versions 2–10: correct a mistaken clarification to the state resolution algorithm.
  • 1175: For room versions 7 through 10: Clarify that invite->knock is actually a legal transition.

1.7 Appendices

1.8 Internal Changes/Tooling

Backwards Compatible Changes

  • 1194: Add internal changes changelog section.

Spec Clarifications

  • 1191: Render HTML anchors for object definition tables.
  • 1195: Give rendered-data sections a background and some padding.
  • 1205: Fix rendering of shortcodes within the client-server API.
  • 1230: Fix the spacing of mapping types generated from the OpenAPI spec.
github-actions[bot]

github-actions[bot]

blocked
Comment Icon1

ansi_term is Unmaintained

Details
Status unmaintained
Package ansi_term
Version 0.12.1
URL https://github.com/ogham/rust-ansi-term/issues/72
Date 2021-08-18

The maintainer has adviced this crate is deprecated and will not receive any maintenance.

The crate does not seem to have much dependencies and may or may not be ok to use as-is.

Last release seems to have been three years ago.

Possible Alternative(s)

The below list has not been vetted in any way and may or may not contain alternatives;

See advisory page for additional details.

zecakeh

zecakeh

effort/hard
Comment Icon4

Context in the ruma-dev room

Lazy clients might send fields with both the stable and unstable prefix and let the homeserver deal with it. It makes serde choke on the JSON because it considers that the same key is present twice.

Since the rule in general of Matrix events is "ignore fields you don't care about", if we find the stable prefix we should ignore the unstable one. It means that the serde alias attribute is probably not suited for our needs.

Solving this would probably involve some macro code.

jplatte

jplatte

area/events
Comment Icon0

We should have a combined struct with all attribute values instead of Vec<MetaAttrs> to represent the combined #[ruma_event] attribute values. That way, things like multiple occurrences of the same attribute key can be caught at parsing time rather than later.

ShadowJonathan

ShadowJonathan

effort/hard
Comment Icon1

Background and Context

With areweoidcyet.com, the Matrix Foundation has (imo) displayed enough commitment to the pushing ahead of the likes of MSC3861 (and related MSCs)

For Ruma, this effectively means a deprecation of the old UIA and access_token (or not? unsure) method of authenticating users, or at the very least, that we support the new method for both server(s) and clients.

This is needed for conduit to support OIDC (if it ever will, with its scope goals), but most importantly, this'll be needed for rust-sdk, which is, or is poised to, downstream to a lot of important projects for element.io.


This issue is meant to track and discuss the large-scale implementation of OIDC in Ruma.

Related issues:

  • (TBD)
jplatte

jplatte

effort/medium
Comment Icon0

Rendered MSC. We don't currently support the query parameter based access token (#314), and now that this MSC has been merged, maybe we shouldn't.

Regardless of whether we support the old way, we should have an unstable feature where AS requests get the same treatment as CS requests.

ShadowJonathan

ShadowJonathan

type/bug
Comment Icon0

Apparently this causes some compatibility issues with those servers when they try to download stuff from a conduit server.

Context here, in the conduit room.

For this we probably need #1118 to nicely add it, I don't want to add another field like r0_path specifically for this.

jplatte

jplatte

effort/medium
Comment Icon1

The shortcoming you see

Currently, ruma-client never retries failed requests. Implementing retries on top of ruma-client means re-serializing requests, which is not ideal.

The improvement

Make it easier to do request retries w/o serializing the same request again, in one of these ways:

  1. Direct support
    • pro: Makes it easy to use ruma-client in a more robust way
    • con: Larger API surface
  2. Callback API
    • pro: Smaller API surface
    • con: Kind of ugly API?
  3. Enhancing ruma-client's Error type (making the serialized request accessible from it)
    • pro: Maximally flexible
    • con: Also somewhat ugly?

I'm currently leaning towards option 3, but I'm not really certain.

edit: Option 3 also allows adding option 1 on top later.

ShadowJonathan

ShadowJonathan

Comment Icon5

I really don't like all of this stuff being defined on ASCII, it degrades the experience for non-English usage (especially where the language used doesn't use a variation of the latin alphabet).

But that's what the spec says and just deviating from it w/o trying to change it is also pretty bad and would be against existing policy.

Originally posted by @jplatte in https://github.com/ruma/ruma/pull/1224#pullrequestreview-1018485587


I'm noting this in a separate issue, to keep these thoughts organised, to address them at a later date.

jplatte

jplatte

effort/medium
Comment Icon0

Redaction should probably be a separate variant after #1195, and the scope of ParseError vs Error is also rather unclear IMO.

Additionally, JsonError::NotMultiplesOfType seems a bit weird, and in general the type mismatch errors should probably include the actual type as well (plus the "target" is too fuzzy to be useful).

ShadowJonathan

ShadowJonathan

area/identifiers
Comment Icon0

Using https://crates.io/crates/compact_str (https://github.com/ParkMyCar/compact_str), a string of up to 24 bytes can be stored on-stack before it is deferred to the stack (becoming String)

This might be very useful for crawlers, who could see a performance boost compared to Box if the identifier is small enough, and then only lives on the stack.

This storage type would be very useful for short-lived non-passed-around string types, cloning still has a penalty, there may also be regressions to Box performance if the identifiers get long enough.

ShadowJonathan

ShadowJonathan

effort/hard
Comment Icon7

This came up while discussing https://github.com/ruma/ruma/pull/1161; ammonia might not be flexible enough to match what the spec wants for HTML sanatization.

Out of that issue, I questioned how much code and work it would be to create a parser/sanitizer ourselves.

Then, i thought of the crate ruma-html, which might just be able to serve other uses;

  • Parse message HTML into a tree.
  • Build message HTML.
  • Sanitize/parse the HTML according to the spec's opinion.

Client authors will be able to simply call and use ruma for the purposes of getting a programmatic representation of message HTML, instead of requiring to handle it themselves via html5ever and other libraries.

This could help a lot with small clients, who will then have "batteries included" to deal with matrix's HTML, and in my opinion, it'd help with the "but matrix is HTML, so its opinionated to web browsers" latent opinion i've seen floating around, as now ruma (and rust-sdk) would have methods to peek into that HTML, be able to work with it, without requiring (much) work on the client's side.

zecakeh

zecakeh

effort/easy
Comment Icon1

For now this is a suggestion open to discussion

Discussion from the matrix room:

Kévin Commaille I was thinking of moving events::room::message::Relation and associated types into `events::relation, as part of #1025. wdyt?

Jonas Platte But we have different relation types? Not just the ones in message, also in encrypted, and reaction

Kévin Commaille Well there are a lot of duplicated types:

  • Relation in reaction should actually be Annotation as in room::encrypted,
  • Most of the relation types in room::message should be also used in room::encrypted (except for Replacement and of course Relation).
  • room::message::Relation is also used by extensible events, and will also be used on stickers, which is not really important right now, but it would have the advantage of already being there when they become stable.

Jonas Platte Maybe we should have EncryptedRelation and MessageRelation?

ShadowJonathan

ShadowJonathan

effort/hard
Comment Icon2

(Distillation from talk in #ruma-dev)

Related to https://github.com/ruma/ruma/issues/1039


I'd like to refactor the stable, unstable, r0_path, etc. macro bits again to something more idiomatic;

In essence, this'd clarify the version history of a particular endpoint at a glance, and allows us to do the following;


Work;

jplatte

jplatte

effort/easy
Comment Icon0

All that seems to be required for this in Ruma is adding a shared_history field (initially renamed to org.matrix.msc3061.shared_history) in a few structs:

  • the content structs for m.room_key and m.forwarded_room_key
  • ruma_client_api::backup::SessionData
  • SessionData of key backups? we don't seem to have this
jplatte

jplatte

effort/medium
Comment Icon0

Enum struct variants don't seem to be picked up by Clippy's exhaustiveness lints? We have BackupAlgorithm which should probably have tuple / newtype variants with an inner struct instead of struct variants. #1047 introduces another one of these, but I don't want to block it on this.

I can try to write some instructions if somebody wants to work on this but is unclear on what is to do exactly.

Versions

Find the latest versions by id

ruma-client-api-0.15.1 - Sep 21, 2022

Improvements:

  • DeviceLists has moved from sync::sync_events::v3 to sync::sync_events
    • It is still available under the old location for backwards compatibility

ruma-0.7.4 - Sep 21, 2022

Improvements:

  • Fix missing re-exports from ruma-common
  • Upgrade ruma-client-api minimum version to 0.15.1

ruma-common-0.10.3 - Sep 16, 2022

Bug fixes:

  • Fix ruma-common not compiling with the Cargo features events and unstable-msc2677 active, and unstable-msc2676 inactive

ruma-common-0.10.2 - Sep 16, 2022

Improvements:

  • Add relations accessors to event enum types:
    • AnyMessageLikeEvent and AnySyncMessageLikeEvent
    • AnyStateEvent and AnySyncStateEvent
    • AnyTimelineEvent and AnySyncTimelineEvent

ruma-0.7.3 - Sep 16, 2022

Upgrades ruma-common minimum version to 0.10.3.

ruma-0.7.2 - Sep 16, 2022

Upgrades ruma-common minimum version to 0.10.2.

ruma-common-0.10.1 - Sep 14, 2022

Improvements:

  • Add RoomMessageEventContent::make_reply_to
    • Deprecate reply constructors in favor of the new method

ruma-0.7.1 - Sep 14, 2022

Upgrades ruma-common minimum version to 0.10.1.

ruma-state-res-0.8.0 - Sep 12, 2022

Bug fixes:

Improvements:

ruma-signatures-0.12.0 - Sep 12, 2022

Breaking changes:

  • Remove pointless PartialEq implementation for Ed25519Verifier

ruma-push-gateway-api-0.6.0 - Sep 12, 2022

Breaking changes:

  • Remove PartialEq implementation for NotificationCounts

ruma-identity-service-api-0.6.0 - Sep 12, 2022

Breaking changes:

  • Upgrade dependencies

ruma-federation-api-0.6.0 - Sep 12, 2022

Breaking changes:

  • Upgrade dependencies

ruma-common-0.10.0 - Sep 12, 2022

Bug fixes:

Breaking changes:

  • Add user_id field to PushConditionRoomCtx
  • Remove PartialEq implementation on NotificationPowerLevels
  • Remove PartialEq implementation for events::call::SessionDescription
  • Use new events::call::AnswerSessionDescription for CallAnswerEventContent and OfferSessionDescription for CallInviteEventContent
  • Use new VoipVersionId and VoipId types for events::call events
  • Remove RoomName / OwnedRoomName and replace usages with str / String
  • Remove RoomMessageFeedbackEvent and associated types and variants according to MSC3582
  • Move CanonicalJson, CanonicalJsonObject and CanonicalJsonError out of the serde module and behind the cargo feature flag canonical-json
  • Make identifiers matrix URI constructors generic over owned parameters
    • Split RoomId matrix URI constructors between methods with and without routing
  • Allow to add routing servers to RoomId::matrix_to_event_uri()
  • Move receipt::ReceiptType to events::receipt
  • Make Clone as supertrait of api::OutgoingRequest
  • Rename Any[Sync]RoomEvent to Any[Sync]TimelineEvent
  • RoomMemberEvent and related types now have a custom unsigned type including the invite_room_state field, instead of the StateUnsigned type used by other state events

Improvements:

  • All push rules are now considered to not apply to events sent by the user themselves
  • Change events::relation::BundledAnnotation to a struct instead of an enum
    • Remove BundledReaction
  • Add unstable support for polls (MSC3381)
  • Add unstable support for Improved Signalling for 1:1 VoIP (MSC2746)
  • Add support for knocking in events::room::member::MembershipChange
  • Add MatrixVersion::V1_3
  • Deprecate the sender_key and device_id fields for encrypted events (MSC3700)
  • Move the relations field of events::unsigned types out of unstable-msc2675
  • Deserialize stringified integers for power levels without the compat feature
  • Add JoinRule::KnockRestricted (MSC3787)
  • Add MatrixVersionId::V10 (MSC3604)
  • Add methods to sanitize messages according to the spec behind the unstable-sanitize feature
    • Can also remove rich reply fallbacks
  • Implement From<Owned*Id> for identifiers::matrix_uri::MatrixId
  • Add unstable default push rule to ignore room server ACLs events (MSC3786)
  • Add unstable support for private read receipts (MSC2285)
  • Add unstable support for filtering public rooms by room type (MSC3827)

ruma-client-api-0.15.0 - Sep 12, 2022

Breaking changes:

  • Export nothing from the crate if neither the client nor the server feature is active
    • This may partially be reverted in subsequent releases
  • UnreadNotificationsCount has moved from sync::sync_events::v3 to sync::sync_events
  • Remove PartialEq implementations for a number of types
    • If the lack of such an impl causes problems, please open a GitHub issue
  • Split uiaa::UserIdentifier::ThirdParty into two separate variants
  • Remove the from parameter from message::get_message_events::v3::Request's constructors
    • This affects new, backward and forward
    • Since backward and forward are equivalent to from_end and from_start, those are removed
    • A new method .from() was added to easily set this field after initial construction
  • receipt::create_receipt uses its own ReceiptType
  • Reorder parameters in {set_global_account_data, set_room_account_data}::Request::{new, new_raw}

Improvements:

  • Add support for refresh tokens (MSC2918)
  • Add ErrorKind::{UnableToAuthorizeJoin, UnableToGrantJoin} encountered for restricted rooms
  • Add support for timestamp massaging (MSC3316)
  • Add support for querying relating events (MSC2675)
  • Move filter::RelationType to ruma_common::events::relations
  • Add unstable support for discovering an OpenID Connect server (MSC2965)
  • Add SpaceRoomJoinRule::KnockRestricted (MSC3787)
  • Add unstable support for private read receipts (MSC2285)
  • Add unstable support for API scope restriction (MSC2967)

ruma-client-0.10.0 - Sep 12, 2022

Breaking changes:

  • Upgrade dependencies

ruma-appservice-api-0.7.0 - Sep 12, 2022

Breaking changes:

  • Remove PartialEq implementation for Namespace
  • Remove push_events::v1::IncomingRequest::try_into_sync_response and the helper Cargo feature that was gating it
    • This API is no longer being used by the only known consumer
    • If you were using it, please let us know!

ruma-0.7.0 - Sep 12, 2022

Breaking changes:

  • The receipt module is no longer exported.
    • ReceiptType has been split into two types under events and api::client.

ruma-common-0.9.3 - Jun 01, 2022

Bug fixes:

  • Fix rich reply fallback generated by the convenience methods of RoomMessageEventContent
    • Fixes an incompatibility with Element Web

ruma-0.6.4 - Jun 01, 2022

Bug fixes:

  • Fix rich reply fallback generated by the convenience methods of RoomMessageEventContent
    • Fixes an incompatibility with Element Web

ruma-client-api-0.14.1 - May 12, 2022

Improvements:

  • Add From<&UserId> and From<&OwnedUserId> implementations for UserIdentifier
  • Add UserIdentifier::email constructor

ruma-0.6.3 - May 12, 2022

Bug fixes:

  • Fix serialization and deserialization of events with a dynamic event_type

Improvements:

  • Add From<&UserId> and From<&OwnedUserId> implementations for UserIdentifier
  • Add UserIdentifier::email constructor

ruma-common-0.9.2 - May 09, 2022

Bug fixes:

  • Fix serialization and deserialization of events with a dynamic event_type

ruma-common-0.9.1 - May 06, 2022

Improvements:

  • Add StrippedPowerLevelsEvent::power_levels
  • Add (Sync)RoomMemberEvent::membership
  • Export events::room::member::Change
    • Prior to this, you couldn't actually do anything with the membership_change functions on various member event types

ruma-0.6.2 - May 06, 2022

Improvements:

  • Add StrippedPowerLevelsEvent::power_levels
  • Add (Sync)RoomMemberEvent::membership
  • Export events::room::member::Change
    • Prior to this, you couldn't actually do anything with the membership_change functions on various member event types

ruma-0.6.1 - Apr 29, 2022

Improvements:

  • Re-export ruma-commons js Cargo feature

ruma-state-res-0.7.0 - Apr 28, 2022

Breaking changes:

  • auth_check does not require prev_event parameter. It was only required on some specific cases. Previous event is now calculated on demand only when it's required.

ruma-signatures-0.11.0 - Apr 28, 2022

Breaking changes:

  • Upgrade dependencies

ruma-push-gateway-api-0.5.0 - Apr 28, 2022

Breaking changes:

  • Upgrade dependencies

ruma-identity-service-api-0.5.0 - Apr 28, 2022

Breaking changes:

  • Rename status to discovery

Improvements:

  • Add room_type to store_invitation::Request according to MSC3288
  • Add discovery::get_supported_versions according to MSC2320

Information - Updated Sep 25, 2022

Stars: 414
Forks: 92
Issues: 102

Repositories & Extras

Rust library for Self Organising Maps (SOM)

Add rusticsom as a dependency in Cargo

Rust library for Self Organising Maps (SOM)

Rust library for parsing configuration files

The 'option' can be any string with no whitespace

Rust library for parsing configuration files

Rust library for the Pimoroni Four Letter pHAT

This library aims to port ht16k33 (or rather a fork, as of right now) so credit goes to ht16k33-diet

Rust library for the Pimoroni Four Letter pHAT

Rust library for emulating 32-bit RISC-V

This library can execute instructions against any memory and register file that implements

Rust library for emulating 32-bit RISC-V

Rust library for connecting to the IPFS HTTP API using Hyper/Actix

You can use actix-web as a backend instead of hyper

Rust library for connecting to the IPFS HTTP API using Hyper/Actix

Rust library to manipulate file system access control lists (ACL) on macOS, Linux, and FreeBSD

This module provides two high level functions, getfacl and setfacl

Rust library to manipulate file system access control lists (ACL) on macOS, Linux, and FreeBSD

Rust library translation (rust-src/rust-std/stdlib/rustlib translation)

This is the place to translate Having a documentation in your native language is essential if you don't speak English, and still enjoyable even if...

Rust library translation (rust-src/rust-std/stdlib/rustlib translation)

Rust library for using Infrared hardware decoders (For example a Vishay TSOP* decoder),

enabling remote control support for embedded project

Rust library for using Infrared hardware decoders (For example a Vishay TSOP* decoder),

Rust library for interaction with the OriginTrail Decentralized Knowledge Graph

open up an issue on this repository and let us know

Rust library for interaction with the OriginTrail Decentralized Knowledge Graph

Rust library for parsing COLLADA files

Notice: This library is built around files exported from Blender 2

Rust library for parsing COLLADA files

web-library-rust

A basic CRUD application that represents books in a library

web-library-rust
Facebook Instagram Twitter GitHub Dribbble
Privacy