client-api: Add support to get an event by timestamp

According to MSC3030

crates/ruma-client-api/CHANGELOG.md

@@ -27,6 +27,7 @@ Improvements:
 * Add support for notifications for threads (MSC3773 / Matrix 1.4)
 * Send CORP headers by default for media responses (MSC3828 / Matrix 1.4)
 * Add support for read receipts for threads (MSC3771 / Matrix 1.4)
+* Add unstable support to get an event by timestamp (MSC3030)
 
 # 0.15.3
 

crates/ruma-client-api/Cargo.toml

@@ -25,6 +25,7 @@ unstable-msc2654 = []
 unstable-msc2677 = []
 unstable-msc2965 = []
 unstable-msc2967 = []
+unstable-msc3030 = []
 unstable-msc3488 = []
 unstable-msc3575 = []
 client = []

crates/ruma-client-api/src/room.rs

@@ -2,6 +2,8 @@
 
 pub mod aliases;
 pub mod create_room;
+#[cfg(feature = "unstable-msc3030")]
+pub mod get_event_by_timestamp;
 pub mod get_room_event;
 pub mod report_content;
 pub mod upgrade_room;

crates/ruma-client-api/src/room/get_event_by_timestamp.rs

@@ -0,0 +1,81 @@
+//! `GET /_matrix/client/*/rooms/{roomId}/timestamp_to_event`
+//!
+//! Get the ID of the event closest to the given timestamp.
+
+pub mod unstable {
+    //! `/unstable/` ([MSC3030])
+    //!
+    //! [MSC3030]: https://github.com/matrix-org/matrix-spec-proposals/pull/3030
+
+    use ruma_common::{
+        api::{request, response, Metadata},
+        metadata, MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedRoomId,
+    };
+
+    use crate::Direction;
+
+    const METADATA: Metadata = metadata! {
+        method: GET,
+        rate_limited: true,
+        authentication: AccessToken,
+        history: {
+            unstable => "/_matrix/client/unstable/org.matrix.msc3030/rooms/:room_id/timestamp_to_event",
+        }
+    };
+
+    /// Request type for the `get_event_for_timestamp` endpoint.
+    #[request(error = crate::Error)]
+    pub struct Request {
+        /// The ID of the room the event is in.
+        #[ruma_api(path)]
+        pub room_id: OwnedRoomId,
+
+        /// The timestamp to search from, inclusively.
+        #[ruma_api(query)]
+        pub ts: MilliSecondsSinceUnixEpoch,
+
+        /// The direction in which to search.
+        #[ruma_api(query)]
+        pub dir: Direction,
+    }
+
+    /// Response type for the `get_room_event` endpoint.
+    #[response(error = crate::Error)]
+    pub struct Response {
+        /// The ID of the event found.
+        pub event_id: OwnedEventId,
+
+        /// The event's timestamp.
+        pub origin_server_ts: MilliSecondsSinceUnixEpoch,
+    }
+
+    impl Request {
+        /// Creates a new `Request` with the given room ID, timestamp and direction.
+        pub fn new(room_id: OwnedRoomId, ts: MilliSecondsSinceUnixEpoch, dir: Direction) -> Self {
+            Self { room_id, ts, dir }
+        }
+
+        /// Creates a new `Request` with the given room ID and timestamp, and the direction set to
+        /// `Backward`.
+        ///
+        /// Allows to have the latest event before or including the given timestamp.
+        pub fn until(room_id: OwnedRoomId, ts: MilliSecondsSinceUnixEpoch) -> Self {
+            Self::new(room_id, ts, Direction::Backward)
+        }
+
+        /// Creates a new `Request` with the given room ID and timestamp, and the direction set to
+        /// `Forward`.
+        ///
+        /// Allows to have the earliest event including or after the given timestamp.
+        pub fn since(room_id: OwnedRoomId, ts: MilliSecondsSinceUnixEpoch) -> Self {
+            Self::new(room_id, ts, Direction::Forward)
+        }
+    }
+
+    impl Response {
+        /// Creates a new `Response` with the given event ID and timestamp.
+        pub fn new(event_id: OwnedEventId, origin_server_ts: MilliSecondsSinceUnixEpoch) -> Self {
+            Self { event_id, origin_server_ts }
+        }
+    }
+}

crates/ruma/Cargo.toml

@@ -135,6 +135,7 @@ unstable-msc2746 = ["ruma-common/unstable-msc2746"]
 unstable-msc2870 = ["ruma-common/unstable-msc2870"]
 unstable-msc2965 = ["ruma-client-api?/unstable-msc2965"]
 unstable-msc2967 = ["ruma-client-api?/unstable-msc2967"]
+unstable-msc3030 = ["ruma-client-api?/unstable-msc3030"]
 unstable-msc3202 = ["ruma-appservice-api?/unstable-msc3202"]
 unstable-msc3245 = ["ruma-common/unstable-msc3245"]
 unstable-msc3246 = ["ruma-common/unstable-msc3246"]
@@ -175,6 +176,7 @@ __ci = [
     "unstable-msc2870",
     "unstable-msc2965",
     "unstable-msc2967",
+    "unstable-msc3030",
     "unstable-msc3202",
     "unstable-msc3245",
     "unstable-msc3246",