chris/ruwuma
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

client-api: Add relations querying endpoint

Browse Source 
According to MSC2675
This commit is contained in:
Kévin Commaille 2022-05-26 13:12:04 +02:00 committed by Kévin Commaille
parent 4f45b8f8ff
commit 70b3d1e55b
10 changed files with 400 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
crates/ruma-client-api/CHANGELOG.md
View File

@ -12,6 +12,11 @@ Improvements:
* Add `ErrorKind::{UnableToAuthorizeJoin, UnableToGrantJoin}` encountered for restricted rooms
* Add unstable support for timestamp massaging (MSC3316)
Improvements:
* Add unstable support for querying relating events (MSC2675)
* Move `filter::RelationType` to `ruma_common::events::relations`
# 0.14.1
Improvements:

1
crates/ruma-client-api/Cargo.toml
View File

@ -21,6 +21,7 @@ unstable-exhaustive-types = []
unstable-msc2246 = []
unstable-msc2448 = []
unstable-msc2654 = []
unstable-msc2675 = []
unstable-msc2676 = []
unstable-msc2677 = []
unstable-msc2918 = []

26
crates/ruma-client-api/src/filter.rs
View File

@ -7,6 +7,8 @@ mod lazy_load;
mod url;
use js_int::UInt;
#[cfg(feature = "unstable-msc3440")]
use ruma_common::events::relation::RelationType;
use ruma_common::{
serde::{Incoming, StringEnum},
OwnedRoomId, OwnedUserId,
@ -39,30 +41,6 @@ impl Default for EventFormat {
}
}
/// Relation types as defined in `rel_type` of an `m.relates_to` field.
#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
#[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
#[cfg(feature = "unstable-msc3440")]
#[non_exhaustive]
pub enum RelationType {
/// `m.annotation`, an annotation, principally used by reactions.
#[cfg(feature = "unstable-msc2677")]
#[ruma_enum(rename = "m.annotation")]
Annotation,
/// `m.replace`, a replacement.
#[cfg(feature = "unstable-msc2676")]
#[ruma_enum(rename = "m.replace")]
Replacement,
/// `m.thread`, a participant to a thread.
#[ruma_enum(rename = "io.element.thread", alias = "m.thread")]
Thread,
#[doc(hidden)]
_Custom(PrivOwnedStr),
}
/// Filters to be applied to room events.
#[derive(Clone, Debug, Default, Incoming, Serialize)]
#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]

2
crates/ruma-client-api/src/lib.rs
View File

@ -32,6 +32,8 @@ pub mod push;
pub mod read_marker;
pub mod receipt;
pub mod redact;
#[cfg(feature = "unstable-msc2675")]
pub mod relations;
pub mod room;
pub mod search;
pub mod server;

5
crates/ruma-client-api/src/relations.rs Normal file
View File

@ -0,0 +1,5 @@
//! Endpoints for querying relations
pub mod get_relating_events;
pub mod get_relating_events_with_rel_type;
pub mod get_relating_events_with_rel_type_and_event_type;

107
crates/ruma-client-api/src/relations/get_relating_events.rs Normal file
View File

@ -0,0 +1,107 @@
//! `GET /_matrix/client/*/rooms/{roomId}/relations/{eventId}`
//!
//! Retrieve all of the child events for a given parent event.
pub mod v1 {
//! `/unstable/` ([MSC2675])
//!
//! [MSC2675]: https://github.com/matrix-org/matrix-spec-proposals/pull/2675
use js_int::UInt;
use ruma_common::{api::ruma_api, events::AnyMessageLikeEvent, serde::Raw, EventId, RoomId};
ruma_api! {
metadata: {
description: "Get the child events for a given parent event.",
method: GET,
name: "get_relating_events",
unstable_path: "/_matrix/client/unstable/rooms/:room_id/relations/:event_id",
rate_limited: false,
authentication: AccessToken,
}
request: {
/// The ID of the room containing the parent event.
#[ruma_api(path)]
pub room_id: &'a RoomId,
/// The ID of the parent event whose child events are to be returned.
#[ruma_api(path)]
pub event_id: &'a EventId,
/// The pagination token to start returning results from.
///
/// If `None`, results start at the most recent topological event known to the server.
///
/// Can be a `next_batch` token from a previous call, or a returned `start` token from
/// `/messages` or a `next_batch` token from `/sync`.
///
/// Note that when paginating the `from` token should be "after" the `to` token in
/// terms of topological ordering, because it is only possible to paginate "backwards"
/// through events, starting at `from`.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub from: Option<&'a str>,
/// The pagination token to stop returning results at.
///
/// If `None`, results continue up to `limit` or until there are no more events.
///
/// Like `from`, this can be a previous token from a prior call to this endpoint
/// or from `/messages` or `/sync`.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub to: Option<&'a str>,
/// The maximum number of results to return in a single `chunk`.
///
/// The server can and should apply a maximum value to this parameter to avoid large
/// responses.
///
/// Similarly, the server should apply a default value when not supplied.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub limit: Option<UInt>,
}
response: {
/// The paginated child events which point to the parent.
///
/// The events returned are ordered topologically, most-recent first.
///
/// If no events are related to the parent or the pagination yields no results, an
/// empty `chunk` is returned.
pub chunk: Vec<Raw<AnyMessageLikeEvent>>,
/// An opaque string representing a pagination token.
///
/// If this is `None`, there are no more results to fetch and the client should stop
/// paginating.
#[serde(skip_serializing_if = "Option::is_none")]
pub next_batch: Option<String>,
/// An opaque string representing a pagination token.
///
/// If this is `None`, this is the start of the result set, i.e. this is the first
/// batch/page.
#[serde(skip_serializing_if = "Option::is_none")]
pub prev_batch: Option<String>,
}
error: crate::Error
}
impl<'a> Request<'a> {
/// Creates a new `Request` with the given room ID and parent event ID.
pub fn new(room_id: &'a RoomId, event_id: &'a EventId) -> Self {
Self { room_id, event_id, from: None, to: None, limit: None }
}
}
impl Response {
/// Creates a new `Response` with the given chunk.
pub fn new(chunk: Vec<Raw<AnyMessageLikeEvent>>) -> Self {
Self { chunk, next_batch: None, prev_batch: None }
}
}
}

118
crates/ruma-client-api/src/relations/get_relating_events_with_rel_type.rs Normal file
View File

@ -0,0 +1,118 @@
//! `GET /_matrix/client/*/rooms/{roomId}/relations/{eventId}/{relType}`
//!
//! Retrieve all of the child events for a given parent event which relate to the parent
//! using the given `rel_type`.
pub mod v1 {
//! `/unstable/` ([MSC2675])
//!
//! [MSC2675]: https://github.com/matrix-org/matrix-spec-proposals/pull/2675
use js_int::UInt;
use ruma_common::{
api::ruma_api,
events::{relation::RelationType, AnyMessageLikeEvent},
serde::Raw,
EventId, RoomId,
};
ruma_api! {
metadata: {
description: "Get the child events for a given parent event, with a given `relType`.",
method: GET,
name: "get_relating_events_with_rel_type",
unstable_path: "/_matrix/client/unstable/rooms/:room_id/relations/:event_id/:rel_type",
rate_limited: false,
authentication: AccessToken,
}
request: {
/// The ID of the room containing the parent event.
#[ruma_api(path)]
pub room_id: &'a RoomId,
/// The ID of the parent event whose child events are to be returned.
#[ruma_api(path)]
pub event_id: &'a EventId,
/// The relationship type to search for.
#[ruma_api(path)]
pub rel_type: RelationType,
/// The pagination token to start returning results from.
///
/// If `None`, results start at the most recent topological event known to the server.
///
/// Can be a `next_batch` token from a previous call, or a returned `start` token from
/// `/messages` or a `next_batch` token from `/sync`.
///
/// Note that when paginating the `from` token should be "after" the `to` token in
/// terms of topological ordering, because it is only possible to paginate "backwards"
/// through events, starting at `from`.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub from: Option<&'a str>,
/// The pagination token to stop returning results at.
///
/// If `None`, results continue up to `limit` or until there are no more events.
///
/// Like `from`, this can be a previous token from a prior call to this endpoint
/// or from `/messages` or `/sync`.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub to: Option<&'a str>,
/// The maximum number of results to return in a single `chunk`.
///
/// The server can and should apply a maximum value to this parameter to avoid large
/// responses.
///
/// Similarly, the server should apply a default value when not supplied.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub limit: Option<UInt>,
}
response: {
/// The paginated child events which point to the parent.
///
/// The events returned will match the `rel_type` supplied in the URL and are ordered
/// topologically, most-recent first.
///
/// If no events are related to the parent or the pagination yields no results, an
/// empty `chunk` is returned.
pub chunk: Vec<Raw<AnyMessageLikeEvent>>,
/// An opaque string representing a pagination token.
///
/// If this is `None`, there are no more results to fetch and the client should stop
/// paginating.
#[serde(skip_serializing_if = "Option::is_none")]
pub next_batch: Option<String>,
/// An opaque string representing a pagination token.
///
/// If this is `None`, this is the start of the result set, i.e. this is the first
/// batch/page.
#[serde(skip_serializing_if = "Option::is_none")]
pub prev_batch: Option<String>,
}
error: crate::Error
}
impl<'a> Request<'a> {
/// Creates a new `Request` with the given room ID, parent event ID and relationship type.
pub fn new(room_id: &'a RoomId, event_id: &'a EventId, rel_type: RelationType) -> Self {
Self { room_id, event_id, rel_type, from: None, to: None, limit: None }
}
}
impl Response {
/// Creates a new `Response` with the given chunk.
pub fn new(chunk: Vec<Raw<AnyMessageLikeEvent>>) -> Self {
Self { chunk, next_batch: None, prev_batch: None }
}
}
}

131
crates/ruma-client-api/src/relations/get_relating_events_with_rel_type_and_event_type.rs Normal file
View File

@ -0,0 +1,131 @@
//! `GET /_matrix/client/*/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}`
//!
//! Retrieve all of the child events for a given parent event which relate to the parent
//! using the given `rel_type` and having the given `event_type`.
pub mod v1 {
//! `/unstable/` ([MSC2675])
//!
//! [MSC2675]: https://github.com/matrix-org/matrix-spec-proposals/pull/2675
use js_int::UInt;
use ruma_common::{
api::ruma_api,
events::{relation::RelationType, AnyMessageLikeEvent, RoomEventType},
serde::Raw,
EventId, RoomId,
};
ruma_api! {
metadata: {
description: "Get the child events for a given parent event, with a given `relType` and `eventType`.",
method: GET,
name: "get_relating_events_with_rel_type_and_event_type",
unstable_path: "/_matrix/client/unstable/rooms/:room_id/relations/:event_id/:rel_type/:event_type",
rate_limited: false,
authentication: AccessToken,
}
request: {
/// The ID of the room containing the parent event.
#[ruma_api(path)]
pub room_id: &'a RoomId,
/// The ID of the parent event whose child events are to be returned.
#[ruma_api(path)]
pub event_id: &'a EventId,
/// The relationship type to search for.
#[ruma_api(path)]
pub rel_type: RelationType,
/// The event type of child events to search for.
///
/// Note that in encrypted rooms this will typically always be `m.room.encrypted`
/// regardless of the event type contained within the encrypted payload.
#[ruma_api(path)]
pub event_type: RoomEventType,
/// The pagination token to start returning results from.
///
/// If `None`, results start at the most recent topological event known to the server.
///
/// Can be a `next_batch` token from a previous call, or a returned `start` token from
/// `/messages` or a `next_batch` token from `/sync`.
///
/// Note that when paginating the `from` token should be "after" the `to` token in
/// terms of topological ordering, because it is only possible to paginate "backwards"
/// through events, starting at `from`.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub from: Option<&'a str>,
/// The pagination token to stop returning results at.
///
/// If `None`, results continue up to `limit` or until there are no more events.
///
/// Like `from`, this can be a previous token from a prior call to this endpoint
/// or from `/messages` or `/sync`.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub to: Option<&'a str>,
/// The maximum number of results to return in a single `chunk`.
///
/// The server can and should apply a maximum value to this parameter to avoid large
/// responses.
///
/// Similarly, the server should apply a default value when not supplied.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub limit: Option<UInt>,
}
response: {
/// The paginated child events which point to the parent.
///
/// The events returned will match the `rel_type` and `even_type` supplied in the URL
/// and are ordered topologically, most-recent first.
///
/// If no events are related to the parent or the pagination yields no results, an
/// empty `chunk` is returned.
pub chunk: Vec<Raw<AnyMessageLikeEvent>>,
/// An opaque string representing a pagination token.
///
/// If this is `None`, there are no more results to fetch and the client should stop
/// paginating.
#[serde(skip_serializing_if = "Option::is_none")]
pub next_batch: Option<String>,
/// An opaque string representing a pagination token.
///
/// If this is `None`, this is the start of the result set, i.e. this is the first
/// batch/page.
#[serde(skip_serializing_if = "Option::is_none")]
pub prev_batch: Option<String>,
}
error: crate::Error
}
impl<'a> Request<'a> {
/// Creates a new `Request` with the given room ID, parent event ID, relationship type and
/// event type.
pub fn new(
room_id: &'a RoomId,
event_id: &'a EventId,
rel_type: RelationType,
event_type: RoomEventType,
) -> Self {
Self { room_id, event_id, rel_type, event_type, from: None, to: None, limit: None }
}
}
impl Response {
/// Creates a new `Response` with the given chunk.
pub fn new(chunk: Vec<Raw<AnyMessageLikeEvent>>) -> Self {
Self { chunk, next_batch: None, prev_batch: None }
}
}
}

25
crates/ruma-common/src/events/relation.rs
View File

@ -156,3 +156,28 @@ impl Relations {
Self::default()
}
}
/// Relation types as defined in `rel_type` of an `m.relates_to` field.
#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
#[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
#[cfg(any(feature = "unstable-msc3440", feature = "unstable-msc2675"))]
#[non_exhaustive]
pub enum RelationType {
/// `m.annotation`, an annotation, principally used by reactions.
#[cfg(feature = "unstable-msc2677")]
#[ruma_enum(rename = "m.annotation")]
Annotation,
/// `m.replace`, a replacement.
#[cfg(feature = "unstable-msc2676")]
#[ruma_enum(rename = "m.replace")]
Replacement,
/// `m.thread`, a participant to a thread.
#[cfg(feature = "unstable-msc3440")]
#[ruma_enum(rename = "io.element.thread", alias = "m.thread")]
Thread,
#[doc(hidden)]
_Custom(PrivOwnedStr),
}

5
crates/ruma/Cargo.toml
View File

@ -124,7 +124,10 @@ unstable-msc2448 = [
"ruma-federation-api?/unstable-msc2448"
]
unstable-msc2654 = ["ruma-client-api?/unstable-msc2654"]
unstable-msc2675 = ["ruma-common/unstable-msc2675"]
unstable-msc2675 = [
"ruma-client-api?/unstable-msc2675",
"ruma-common/unstable-msc2675",
]
unstable-msc2676 = [
"ruma-client-api?/unstable-msc2676",
"ruma-common/unstable-msc2676",