client-api: Stabilize the mutual_rooms endpoint (MSC2666).

Move the mutual_rooms module from `unstable` to `v1`, add the required
`count` field, and retain the unstable endpoint sharing the v1 types. Add
`MatrixVersion::V1_19` for the stable endpoint's history.

Signed-off-by: Jason Volk <jason@zemos.net>

Author: jevolk

crates/ruma-client-api/CHANGELOG.md

@@ -14,6 +14,11 @@ Improvements:
   field on `discovery::get_supported_versions::Response` carries the
   homeserver implementation name and version, mirroring the federation
   `/version` payload.
+- Stabilize the `GET /_matrix/client/v1/mutual_rooms` endpoint (MSC2666),
+  adding the required `count` field. The `mutual_rooms` module moves from
+  `unstable` to `v1`, and the retained unstable endpoint shares the v1
+  request and response types; the response fields are now `joined`, `count`
+  and `next_batch`.
 
 [MSC4383]: https://github.com/matrix-org/matrix-spec-proposals/pull/4383
 

crates/ruma-client-api/src/membership/mutual_rooms.rs

@@ -1,12 +1,13 @@
-//! `GET /_matrix/client/*/user/mutual_rooms/{user_id}`
+//! `GET /_matrix/client/*/mutual_rooms`
 //!
-//! Get mutual rooms with another user.
+//! Get the list of rooms a user shares with another user.
 
-pub mod unstable {
-    //! `/unstable/` ([spec])
+pub mod v1 {
+    //! `/v1/` ([spec])
     //!
-    //! [spec]: https://github.com/matrix-org/matrix-spec-proposals/blob/hs/shared-rooms/proposals/2666-get-rooms-in-common.md
+    //! [spec]: https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1mutual_rooms
 
+    use js_int::UInt;
     use ruma_common::{
         OwnedRoomId, OwnedUserId,
         api::{auth_scheme::AccessToken, request, response},
@@ -19,6 +20,7 @@ pub mod unstable {
         authentication: AccessToken,
         history: {
             unstable("uk.half-shot.msc2666.query_mutual_rooms") => "/_matrix/client/unstable/uk.half-shot.msc2666/user/mutual_rooms",
+            1.19 => "/_matrix/client/v1/mutual_rooms",
         }
     }
 
@@ -29,15 +31,14 @@ pub mod unstable {
         #[ruma_api(query)]
         pub user_id: OwnedUserId,
 
-        /// The `next_batch_token` returned from a previous response, to get the next batch of
-        /// rooms.
+        /// The pagination token from a previous response, to get the next batch of rooms.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat-empty-string-null",
             serde(default, deserialize_with = "ruma_common::serde::empty_string_as_none")
         )]
         #[ruma_api(query)]
-        pub batch_token: Option<String>,
+        pub from: Option<String>,
     }
 
     /// Response type for the `mutual_rooms` endpoint.
@@ -46,32 +47,35 @@ pub mod unstable {
         /// A list of rooms the user is in together with the authenticated user.
         pub joined: Vec<OwnedRoomId>,
 
-        /// An opaque string, returned when the server paginates this response.
+        /// The total number of shared rooms, even when this response is batched.
+        pub count: UInt,
+
+        /// An opaque token, returned when the server paginates this response.
         #[serde(skip_serializing_if = "Option::is_none")]
-        pub next_batch_token: Option<String>,
+        pub next_batch: Option<String>,
     }
 
     impl Request {
         /// Creates a new `Request` with the given user id.
         pub fn new(user_id: OwnedUserId) -> Self {
-            Self { user_id, batch_token: None }
+            Self { user_id, from: None }
         }
 
-        /// Creates a new `Request` with the given user id, together with a batch token.
-        pub fn with_token(user_id: OwnedUserId, token: String) -> Self {
-            Self { user_id, batch_token: Some(token) }
+        /// Creates a new `Request` with the given user id, together with a pagination token.
+        pub fn with_token(user_id: OwnedUserId, from: String) -> Self {
+            Self { user_id, from: Some(from) }
         }
     }
 
     impl Response {
-        /// Creates a `Response` with the given room ids.
-        pub fn new(joined: Vec<OwnedRoomId>) -> Self {
-            Self { joined, next_batch_token: None }
+        /// Creates a `Response` with the given room ids and total count.
+        pub fn new(joined: Vec<OwnedRoomId>, count: UInt) -> Self {
+            Self { joined, count, next_batch: None }
         }
 
-        /// Creates a `Response` with the given room ids, together with a batch token.
-        pub fn with_token(joined: Vec<OwnedRoomId>, token: String) -> Self {
-            Self { joined, next_batch_token: Some(token) }
+        /// Creates a `Response` with the given room ids, total count and pagination token.
+        pub fn with_token(joined: Vec<OwnedRoomId>, count: UInt, next_batch: String) -> Self {
+            Self { joined, count, next_batch: Some(next_batch) }
         }
     }
 }

crates/ruma-common/src/api/metadata.rs

@@ -388,6 +388,11 @@ pub enum MatrixVersion {
     ///
     /// See <https://spec.matrix.org/v1.18/>.
     V1_18,
+
+    /// Version 1.19 of the Matrix specification, released in Q2 2026.
+    ///
+    /// See <https://spec.matrix.org/v1.19/>.
+    V1_19,
 }
 
 impl TryFrom<&str> for MatrixVersion {
@@ -420,6 +425,7 @@ impl TryFrom<&str> for MatrixVersion {
             "v1.16" => V1_16,
             "v1.17" => V1_17,
             "v1.18" => V1_18,
+            "v1.19" => V1_19,
             _ => return Err(UnknownVersionError),
         })
     }
@@ -474,6 +480,7 @@ impl MatrixVersion {
             MatrixVersion::V1_16 => "v1.16",
             MatrixVersion::V1_17 => "v1.17",
             MatrixVersion::V1_18 => "v1.18",
+            MatrixVersion::V1_19 => "v1.19",
         };
 
         Some(string)
@@ -501,6 +508,7 @@ impl MatrixVersion {
             MatrixVersion::V1_16 => (1, 16),
             MatrixVersion::V1_17 => (1, 17),
             MatrixVersion::V1_18 => (1, 18),
+            MatrixVersion::V1_19 => (1, 19),
         }
     }
 
@@ -526,6 +534,7 @@ impl MatrixVersion {
             (1, 16) => Ok(MatrixVersion::V1_16),
             (1, 17) => Ok(MatrixVersion::V1_17),
             (1, 18) => Ok(MatrixVersion::V1_18),
+            (1, 19) => Ok(MatrixVersion::V1_19),
             _ => Err(UnknownVersionError),
         }
     }
@@ -620,7 +629,9 @@ impl MatrixVersion {
             // <https://spec.matrix.org/v1.17/rooms/#complete-list-of-room-versions>
             | MatrixVersion::V1_17
             // <https://spec.matrix.org/v1.18/rooms/#complete-list-of-room-versions>
-            | MatrixVersion::V1_18 => RoomVersionId::V12,
+            | MatrixVersion::V1_18
+            // <https://spec.matrix.org/v1.19/rooms/#complete-list-of-room-versions>
+            | MatrixVersion::V1_19 => RoomVersionId::V12,
         }
     }
 }