ruma_client_api/state/
send_state_event.rs

Help
1//! `PUT /_matrix/client/*/rooms/{roomId}/state/{eventType}/{stateKey}`
2//!
3//! Send a state event to a room associated with a given state key.
4
5pub mod v3 {
6    //! `/v3/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey
9
10    use std::borrow::Borrow;
11
12    use ruma_common::{
13        api::{response, Metadata},
14        metadata,
15        serde::Raw,
16        MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedRoomId,
17    };
18    use ruma_events::{AnyStateEventContent, StateEventContent, StateEventType};
19    use serde_json::value::to_raw_value as to_raw_json_value;
20
21    const METADATA: Metadata = metadata! {
22        method: PUT,
23        rate_limited: false,
24        authentication: AccessToken,
25        history: {
26            1.0 => "/_matrix/client/r0/rooms/:room_id/state/:event_type/:state_key",
27            1.1 => "/_matrix/client/v3/rooms/:room_id/state/:event_type/:state_key",
28        }
29    };
30
31    /// Request type for the `send_state_event` endpoint.
32    #[derive(Clone, Debug)]
33    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
34    pub struct Request {
35        /// The room to set the state in.
36        pub room_id: OwnedRoomId,
37
38        /// The type of event to send.
39        pub event_type: StateEventType,
40
41        /// The state_key for the state to send.
42        pub state_key: String,
43
44        /// The event content to send.
45        pub body: Raw<AnyStateEventContent>,
46
47        /// Timestamp to use for the `origin_server_ts` of the event.
48        ///
49        /// This is called [timestamp massaging] and can only be used by Appservices.
50        ///
51        /// Note that this does not change the position of the event in the timeline.
52        ///
53        /// [timestamp massaging]: https://spec.matrix.org/latest/application-service-api/#timestamp-massaging
54        pub timestamp: Option<MilliSecondsSinceUnixEpoch>,
55    }
56
57    impl Request {
58        /// Creates a new `Request` with the given room id, state key and event content.
59        ///
60        /// # Errors
61        ///
62        /// Since `Request` stores the request body in serialized form, this function can fail if
63        /// `T`s [`Serialize`][serde::Serialize] implementation can fail.
64        pub fn new<T, K>(
65            room_id: OwnedRoomId,
66            state_key: &K,
67            content: &T,
68        ) -> serde_json::Result<Self>
69        where
70            T: StateEventContent,
71            T::StateKey: Borrow<K>,
72            K: AsRef<str> + ?Sized,
73        {
74            Ok(Self {
75                room_id,
76                state_key: state_key.as_ref().to_owned(),
77                event_type: content.event_type(),
78                body: Raw::from_json(to_raw_json_value(content)?),
79                timestamp: None,
80            })
81        }
82
83        /// Creates a new `Request` with the given room id, event type, state key and raw event
84        /// content.
85        pub fn new_raw(
86            room_id: OwnedRoomId,
87            event_type: StateEventType,
88            state_key: String,
89            body: Raw<AnyStateEventContent>,
90        ) -> Self {
91            Self { room_id, event_type, state_key, body, timestamp: None }
92        }
93    }
94
95    /// Response type for the `send_state_event` endpoint.
96    #[response(error = crate::Error)]
97    pub struct Response {
98        /// A unique identifier for the event.
99        pub event_id: OwnedEventId,
100    }
101
102    impl Response {
103        /// Creates a new `Response` with the given event id.
104        pub fn new(event_id: OwnedEventId) -> Self {
105            Self { event_id }
106        }
107    }
108
109    #[cfg(feature = "client")]
110    impl ruma_common::api::OutgoingRequest for Request {
111        type EndpointError = crate::Error;
112        type IncomingResponse = Response;
113
114        const METADATA: Metadata = METADATA;
115
116        fn try_into_http_request<T: Default + bytes::BufMut>(
117            self,
118            base_url: &str,
119            access_token: ruma_common::api::SendAccessToken<'_>,
120            considering_versions: &'_ [ruma_common::api::MatrixVersion],
121        ) -> Result<http::Request<T>, ruma_common::api::error::IntoHttpError> {
122            use http::header::{self, HeaderValue};
123
124            let query_string =
125                serde_html_form::to_string(RequestQuery { timestamp: self.timestamp })?;
126
127            let http_request = http::Request::builder()
128                .method(http::Method::PUT)
129                .uri(METADATA.make_endpoint_url(
130                    considering_versions,
131                    base_url,
132                    &[&self.room_id, &self.event_type, &self.state_key],
133                    &query_string,
134                )?)
135                .header(header::CONTENT_TYPE, "application/json")
136                .header(
137                    header::AUTHORIZATION,
138                    HeaderValue::from_str(&format!(
139                        "Bearer {}",
140                        access_token
141                            .get_required_for_endpoint()
142                            .ok_or(ruma_common::api::error::IntoHttpError::NeedsAuthentication)?
143                    ))?,
144                )
145                .body(ruma_common::serde::json_to_buf(&self.body)?)?;
146
147            Ok(http_request)
148        }
149    }
150
151    #[cfg(feature = "server")]
152    impl ruma_common::api::IncomingRequest for Request {
153        type EndpointError = crate::Error;
154        type OutgoingResponse = Response;
155
156        const METADATA: Metadata = METADATA;
157
158        fn try_from_http_request<B, S>(
159            request: http::Request<B>,
160            path_args: &[S],
161        ) -> Result<Self, ruma_common::api::error::FromHttpRequestError>
162        where
163            B: AsRef<[u8]>,
164            S: AsRef<str>,
165        {
166            // FIXME: find a way to make this if-else collapse with serde recognizing trailing
167            // Option
168            let (room_id, event_type, state_key): (OwnedRoomId, StateEventType, String) =
169                if path_args.len() == 3 {
170                    serde::Deserialize::deserialize(serde::de::value::SeqDeserializer::<
171                        _,
172                        serde::de::value::Error,
173                    >::new(
174                        path_args.iter().map(::std::convert::AsRef::as_ref),
175                    ))?
176                } else {
177                    let (a, b) =
178                        serde::Deserialize::deserialize(serde::de::value::SeqDeserializer::<
179                            _,
180                            serde::de::value::Error,
181                        >::new(
182                            path_args.iter().map(::std::convert::AsRef::as_ref),
183                        ))?;
184
185                    (a, b, "".into())
186                };
187
188            let request_query: RequestQuery =
189                serde_html_form::from_str(request.uri().query().unwrap_or(""))?;
190
191            let body = serde_json::from_slice(request.body().as_ref())?;
192
193            Ok(Self { room_id, event_type, state_key, body, timestamp: request_query.timestamp })
194        }
195    }
196
197    /// Data in the request's query string.
198    #[derive(Debug)]
199    #[cfg_attr(feature = "client", derive(serde::Serialize))]
200    #[cfg_attr(feature = "server", derive(serde::Deserialize))]
201    struct RequestQuery {
202        /// Timestamp to use for the `origin_server_ts` of the event.
203        #[serde(rename = "ts", skip_serializing_if = "Option::is_none")]
204        timestamp: Option<MilliSecondsSinceUnixEpoch>,
205    }
206
207    #[cfg(feature = "client")]
208    #[test]
209    fn serialize() {
210        use ruma_common::{
211            api::{MatrixVersion, OutgoingRequest as _, SendAccessToken},
212            owned_room_id,
213        };
214        use ruma_events::{room::name::RoomNameEventContent, EmptyStateKey};
215
216        // This used to panic in make_endpoint_url because of a mismatch in the path parameter count
217        let req = Request::new(
218            owned_room_id!("!room:server.tld"),
219            &EmptyStateKey,
220            &RoomNameEventContent::new("Test room".to_owned()),
221        )
222        .unwrap()
223        .try_into_http_request::<Vec<u8>>(
224            "https://server.tld",
225            SendAccessToken::IfRequired("access_token"),
226            &[MatrixVersion::V1_1],
227        )
228        .unwrap();
229
230        assert_eq!(
231            req.uri(),
232            "https://server.tld/_matrix/client/v3/rooms/!room:server.tld/state/m.room.name/"
233        );
234    }
235}
ruma_client_api/state/send_state_event.rs

ruma_client_api/state/
send_state_event.rs
