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}