Skip to main content

ruma_client_api/delayed_events/
delayed_message_event.rs

1//! `PUT /_matrix/client/*/rooms/{roomId}/send/{eventType}/{txnId}`
2//!
3//! Send a delayed event (a scheduled message) to a room.
4//!
5//! This endpoint implements a previous iteration of MSC4140 at commit [`3ee73ab`], which adds an
6//! unstable query parameter to [`send_message_event`]. At the time of writing, this matches the
7//! current implementation of Synapse but the latest iteration of the MSC uses the
8//! [`send_delayed_event`] endpoint instead.
9//!
10//! [`3ee73ab`]: https://github.com/matrix-org/matrix-spec-proposals/blob/3ee73abe5f81252b00877cfb5db941ee9aa6c18d/proposals/4140-delayed-events-futures.md
11//! [`send_message_event`]: crate::message::send_message_event
12//! [`send_delayed_event`]: super::send_delayed_event
13
14pub mod msc4140 {
15    //! `/v3/` ([MSC])
16    //!
17    //! [MSC]: https://github.com/matrix-org/matrix-spec-proposals/pull/4140
18
19    use ruma_common::{
20        OwnedRoomId, OwnedTransactionId,
21        api::{auth_scheme::AccessToken, request, response},
22        metadata,
23        serde::Raw,
24    };
25    use ruma_events::{AnyMessageLikeEventContent, MessageLikeEventContent, MessageLikeEventType};
26    use serde_json::value::to_raw_value as to_raw_json_value;
27
28    use crate::delayed_events::DelayParameters;
29
30    metadata! {
31        method: PUT,
32        rate_limited: false,
33        authentication: AccessToken,
34        history: {
35            // We use the unstable prefix for the delay query parameter but the stable v3 endpoint.
36            unstable => "/_matrix/client/v3/rooms/{room_id}/send/{event_type}/{txn_id}",
37        }
38    }
39
40    /// Request type for the `delayed_message_event` endpoint.
41    #[request]
42    pub struct Request {
43        /// The room to send the event to.
44        #[ruma_api(path)]
45        pub room_id: OwnedRoomId,
46
47        /// The type of event to send.
48        #[ruma_api(path)]
49        pub event_type: MessageLikeEventType,
50
51        /// The transaction ID for this event.
52        ///
53        /// Clients should generate a unique ID across requests within the
54        /// same session. A session is identified by an access token, and
55        /// persists when the [access token is refreshed].
56        ///
57        /// It will be used by the server to ensure idempotency of requests.
58        ///
59        /// [access token is refreshed]: https://spec.matrix.org/v1.19/client-server-api/#refreshing-access-tokens
60        #[ruma_api(path)]
61        pub txn_id: OwnedTransactionId,
62
63        /// The timeout duration for this delayed event.
64        #[ruma_api(query_all)]
65        pub delay_parameters: DelayParameters,
66
67        /// The event content to send.
68        #[ruma_api(body)]
69        pub body: Raw<AnyMessageLikeEventContent>,
70    }
71
72    /// Response type for the `delayed_message_event` endpoint.
73    #[response]
74    pub struct Response {
75        /// The `delay_id` generated for this delayed event. Used to interact with delayed events.
76        pub delay_id: String,
77    }
78
79    impl Request {
80        /// Creates a new `Request` with the given room id, transaction id, `delay_parameters` and
81        /// event content.
82        ///
83        /// # Errors
84        ///
85        /// Since `Request` stores the request body in serialized form, this function can fail if
86        /// `T`s [`serde::Serialize`] implementation can fail.
87        pub fn new<T>(
88            room_id: OwnedRoomId,
89            txn_id: OwnedTransactionId,
90            delay_parameters: DelayParameters,
91            content: &T,
92        ) -> serde_json::Result<Self>
93        where
94            T: MessageLikeEventContent,
95        {
96            Ok(Self {
97                room_id,
98                txn_id,
99                event_type: content.event_type(),
100                delay_parameters,
101                body: Raw::from_json(to_raw_json_value(content)?),
102            })
103        }
104
105        /// Creates a new `Request` with the given room id, transaction id, event type,
106        /// `delay_parameters` and raw event content.
107        pub fn new_raw(
108            room_id: OwnedRoomId,
109            txn_id: OwnedTransactionId,
110            event_type: MessageLikeEventType,
111            delay_parameters: DelayParameters,
112            body: Raw<AnyMessageLikeEventContent>,
113        ) -> Self {
114            Self { room_id, event_type, txn_id, delay_parameters, body }
115        }
116    }
117
118    impl Response {
119        /// Creates a new `Response` with the token required to control the delayed event.
120        pub fn new(delay_id: String) -> Self {
121            Self { delay_id }
122        }
123    }
124
125    #[cfg(all(test, feature = "client"))]
126    mod tests {
127        use std::borrow::Cow;
128
129        use ruma_common::{
130            api::{
131                MatrixVersion, OutgoingRequestExt as _, SupportedVersions,
132                auth_scheme::SendAccessToken,
133            },
134            owned_room_id,
135        };
136        use ruma_events::room::message::RoomMessageEventContent;
137        use serde_json::{Value as JsonValue, json};
138        use web_time::Duration;
139
140        use super::{DelayParameters, Request};
141
142        #[test]
143        fn serialize_delayed_message_request() {
144            let room_id = owned_room_id!("!roomid:example.org");
145            let supported = SupportedVersions {
146                versions: [MatrixVersion::V1_1].into(),
147                features: Default::default(),
148            };
149
150            let req = Request::new(
151                room_id,
152                "1234".into(),
153                DelayParameters::Timeout { timeout: Duration::from_millis(103) },
154                &RoomMessageEventContent::text_plain("test"),
155            )
156            .unwrap();
157            let request: http::Request<Vec<u8>> = req
158                .try_into_http_request(
159                    "https://homeserver.tld",
160                    SendAccessToken::IfRequired("auth_tok"),
161                    Cow::Owned(supported),
162                )
163                .unwrap();
164            let (parts, body) = request.into_parts();
165            assert_eq!(
166                "https://homeserver.tld/_matrix/client/v3/rooms/!roomid:example.org/send/m.room.message/1234?org.matrix.msc4140.delay=103",
167                parts.uri
168            );
169            assert_eq!("PUT", parts.method);
170            assert_eq!(
171                json!({"msgtype":"m.text","body":"test"}),
172                serde_json::from_slice::<JsonValue>(&body).unwrap()
173            );
174        }
175    }
176}