From d0ad3aa4191049c59a80d8c3f2048b69ab3fa808 Mon Sep 17 00:00:00 2001
From: Jonathan de Jong <jonathan@automatia.nl>
Date: Tue, 22 Feb 2022 20:59:26 +0100
Subject: [PATCH] client-api: Refactor backup APIs to be more descriptive and
 accurate

---
 crates/ruma-client-api/src/backup.rs          | 22 +++++++++----------
 .../src/backup/add_backup_keys.rs             |  6 ++---
 ...essions.rs => add_backup_keys_for_room.rs} | 10 ++++-----
 ...sion.rs => add_backup_keys_for_session.rs} | 12 +++++-----
 ...ate_backup.rs => create_backup_version.rs} |  4 ++--
 .../src/backup/delete_backup_keys.rs          |  8 +++----
 ...ions.rs => delete_backup_keys_for_room.rs} | 10 ++++-----
 ...n.rs => delete_backup_keys_for_session.rs} | 12 +++++-----
 ...ete_backup.rs => delete_backup_version.rs} |  8 ++++---
 .../{get_backup.rs => get_backup_info.rs}     |  8 ++++---
 .../src/backup/get_backup_keys.rs             |  8 +++----
 ...essions.rs => get_backup_keys_for_room.rs} |  6 ++---
 ...sion.rs => get_backup_keys_for_session.rs} |  8 +++----
 ...st_backup.rs => get_latest_backup_info.rs} |  4 ++--
 ...ate_backup.rs => update_backup_version.rs} |  4 ++--
 15 files changed, 63 insertions(+), 67 deletions(-)
 rename crates/ruma-client-api/src/backup/{add_backup_key_sessions.rs => add_backup_keys_for_room.rs} (88%)
 rename crates/ruma-client-api/src/backup/{add_backup_key_session.rs => add_backup_keys_for_session.rs} (86%)
 rename crates/ruma-client-api/src/backup/{create_backup.rs => create_backup_version.rs} (92%)
 rename crates/ruma-client-api/src/backup/{delete_backup_key_sessions.rs => delete_backup_keys_for_room.rs} (85%)
 rename crates/ruma-client-api/src/backup/{delete_backup_key_session.rs => delete_backup_keys_for_session.rs} (84%)
 rename crates/ruma-client-api/src/backup/{delete_backup.rs => delete_backup_version.rs} (84%)
 rename crates/ruma-client-api/src/backup/{get_backup.rs => get_backup_info.rs} (94%)
 rename crates/ruma-client-api/src/backup/{get_backup_key_sessions.rs => get_backup_keys_for_room.rs} (92%)
 rename crates/ruma-client-api/src/backup/{get_backup_key_session.rs => get_backup_keys_for_session.rs} (90%)
 rename crates/ruma-client-api/src/backup/{get_latest_backup.rs => get_latest_backup_info.rs} (96%)
 rename crates/ruma-client-api/src/backup/{update_backup.rs => update_backup_version.rs} (95%)

diff --git a/crates/ruma-client-api/src/backup.rs b/crates/ruma-client-api/src/backup.rs
index ec266a42..b434a98f 100644
--- a/crates/ruma-client-api/src/backup.rs
+++ b/crates/ruma-client-api/src/backup.rs
@@ -1,19 +1,19 @@
 //! Endpoints for server-side key backups.
 
-pub mod add_backup_key_session;
-pub mod add_backup_key_sessions;
 pub mod add_backup_keys;
-pub mod create_backup;
-pub mod delete_backup;
-pub mod delete_backup_key_session;
-pub mod delete_backup_key_sessions;
+pub mod add_backup_keys_for_room;
+pub mod add_backup_keys_for_session;
+pub mod create_backup_version;
 pub mod delete_backup_keys;
-pub mod get_backup;
-pub mod get_backup_key_session;
-pub mod get_backup_key_sessions;
+pub mod delete_backup_keys_for_room;
+pub mod delete_backup_keys_for_session;
+pub mod delete_backup_version;
+pub mod get_backup_info;
 pub mod get_backup_keys;
-pub mod get_latest_backup;
-pub mod update_backup;
+pub mod get_backup_keys_for_room;
+pub mod get_backup_keys_for_session;
+pub mod get_latest_backup_info;
+pub mod update_backup_version;
 
 use std::collections::BTreeMap;
 
diff --git a/crates/ruma-client-api/src/backup/add_backup_keys.rs b/crates/ruma-client-api/src/backup/add_backup_keys.rs
index 3dc910c0..c076a4e0 100644
--- a/crates/ruma-client-api/src/backup/add_backup_keys.rs
+++ b/crates/ruma-client-api/src/backup/add_backup_keys.rs
@@ -15,7 +15,7 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Store several keys in the backup.",
+            description: "Store keys in the backup.",
             method: PUT,
             name: "add_backup_keys",
             unstable_path: "/_matrix/client/unstable/room_keys/keys",
@@ -26,13 +26,13 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to add keys to.
             ///
             /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// A map from room IDs to session IDs to key data.
+            /// A map of room IDs to session IDs to key data to store.
             pub rooms: BTreeMap<Box<RoomId>, RoomKeyBackup>,
         }
 
diff --git a/crates/ruma-client-api/src/backup/add_backup_key_sessions.rs b/crates/ruma-client-api/src/backup/add_backup_keys_for_room.rs
similarity index 88%
rename from crates/ruma-client-api/src/backup/add_backup_key_sessions.rs
rename to crates/ruma-client-api/src/backup/add_backup_keys_for_room.rs
index c90c3afa..92e45f35 100644
--- a/crates/ruma-client-api/src/backup/add_backup_key_sessions.rs
+++ b/crates/ruma-client-api/src/backup/add_backup_keys_for_room.rs
@@ -16,9 +16,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Store several sessions in the backup.",
+            description: "Store keys in the backup for a room.",
             method: PUT,
-            name: "add_backup_key_sessions",
+            name: "add_backup_keys_for_room",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id",
@@ -28,17 +28,17 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to add keys to.
             ///
             /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to add keys to.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// A map from session IDs to key data.
+            /// A map of session IDs to key data to store.
             pub sessions: BTreeMap<String, Raw<KeyBackupData>>,
         }
 
diff --git a/crates/ruma-client-api/src/backup/add_backup_key_session.rs b/crates/ruma-client-api/src/backup/add_backup_keys_for_session.rs
similarity index 86%
rename from crates/ruma-client-api/src/backup/add_backup_key_session.rs
rename to crates/ruma-client-api/src/backup/add_backup_keys_for_session.rs
index f48f52e7..53b77ff4 100644
--- a/crates/ruma-client-api/src/backup/add_backup_key_session.rs
+++ b/crates/ruma-client-api/src/backup/add_backup_keys_for_session.rs
@@ -14,9 +14,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Store several keys in the backup.",
+            description: "Store keys in the backup for a session.",
             method: PUT,
-            name: "add_backup_key_session",
+            name: "add_backup_keys_for_session",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id/:session_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id/:session_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
@@ -26,21 +26,21 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to add keys to.
             ///
             /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to add keys to.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// The ID of the megolm session whose key is requested.
+            /// The ID of the megolm session to add keys to.
             #[ruma_api(path)]
             pub session_id: &'a str,
 
-            /// The key information to backup.
+            /// The key information to store.
             #[ruma_api(body)]
             pub session_data: Raw<KeyBackupData>,
         }
diff --git a/crates/ruma-client-api/src/backup/create_backup.rs b/crates/ruma-client-api/src/backup/create_backup_version.rs
similarity index 92%
rename from crates/ruma-client-api/src/backup/create_backup.rs
rename to crates/ruma-client-api/src/backup/create_backup_version.rs
index bcb6996b..2d1ce2da 100644
--- a/crates/ruma-client-api/src/backup/create_backup.rs
+++ b/crates/ruma-client-api/src/backup/create_backup_version.rs
@@ -12,9 +12,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Creates a new backup.",
+            description: "Create a new backup version.",
             method: POST,
-            name: "create_backup",
+            name: "create_backup_version",
             unstable_path: "/_matrix/client/unstable/room_keys/version",
             stable_path: "/_matrix/client/v3/room_keys/version",
             rate_limited: true,
diff --git a/crates/ruma-client-api/src/backup/delete_backup_keys.rs b/crates/ruma-client-api/src/backup/delete_backup_keys.rs
index 7051141b..8e415022 100644
--- a/crates/ruma-client-api/src/backup/delete_backup_keys.rs
+++ b/crates/ruma-client-api/src/backup/delete_backup_keys.rs
@@ -4,13 +4,15 @@ pub mod v3 {
     //! `/v3/` ([spec])
     //!
     //! [spec]: https://spec.matrix.org/v1.2/client-server-api/#delete_matrixclientv3room_keyskeys
+    //!
+    //! This deletes keys from a backup version, but not the version itself.
 
     use js_int::UInt;
     use ruma_api::ruma_api;
 
     ruma_api! {
         metadata: {
-            description: "Delete all keys in a backup.",
+            description: "Delete all keys from a backup.",
             method: DELETE,
             name: "delete_backup_keys",
             unstable_path: "/_matrix/client/unstable/room_keys/keys",
@@ -22,9 +24,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
-            ///
-            /// Must be the current backup.
+            /// The backup version from which to delete keys.
             #[ruma_api(query)]
             pub version: &'a str,
         }
diff --git a/crates/ruma-client-api/src/backup/delete_backup_key_sessions.rs b/crates/ruma-client-api/src/backup/delete_backup_keys_for_room.rs
similarity index 85%
rename from crates/ruma-client-api/src/backup/delete_backup_key_sessions.rs
rename to crates/ruma-client-api/src/backup/delete_backup_keys_for_room.rs
index d82a0455..f4bcc4d9 100644
--- a/crates/ruma-client-api/src/backup/delete_backup_key_sessions.rs
+++ b/crates/ruma-client-api/src/backup/delete_backup_keys_for_room.rs
@@ -11,9 +11,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Delete keys from the backup for a given room.",
+            description: "Delete keys from a backup for a given room.",
             method: DELETE,
-            name: "delete_backup_key_sessions",
+            name: "delete_backup_keys_for_room",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id",
@@ -23,13 +23,11 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
-            ///
-            /// Must be the current backup.
+            /// The backup version from which to delete keys.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to delete keys from.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
         }
diff --git a/crates/ruma-client-api/src/backup/delete_backup_key_session.rs b/crates/ruma-client-api/src/backup/delete_backup_keys_for_session.rs
similarity index 84%
rename from crates/ruma-client-api/src/backup/delete_backup_key_session.rs
rename to crates/ruma-client-api/src/backup/delete_backup_keys_for_session.rs
index 3c83e7a7..83967776 100644
--- a/crates/ruma-client-api/src/backup/delete_backup_key_session.rs
+++ b/crates/ruma-client-api/src/backup/delete_backup_keys_for_session.rs
@@ -11,9 +11,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Delete a key from the backup",
+            description: "Delete keys from a backup for a given session.",
             method: DELETE,
-            name: "delete_backup_key_session",
+            name: "delete_backup_keys_for_session",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id/:session_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id/:session_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
@@ -23,17 +23,15 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
-            ///
-            /// Must be the current backup.
+            /// The backup version from which to delete keys.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to delete keys from.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// The ID of the megolm session whose key is requested.
+            /// The ID of the megolm session to delete keys from.
             #[ruma_api(path)]
             pub session_id: &'a str,
         }
diff --git a/crates/ruma-client-api/src/backup/delete_backup.rs b/crates/ruma-client-api/src/backup/delete_backup_version.rs
similarity index 84%
rename from crates/ruma-client-api/src/backup/delete_backup.rs
rename to crates/ruma-client-api/src/backup/delete_backup_version.rs
index bdb9d816..2dc2e335 100644
--- a/crates/ruma-client-api/src/backup/delete_backup.rs
+++ b/crates/ruma-client-api/src/backup/delete_backup_version.rs
@@ -4,14 +4,16 @@ pub mod v3 {
     //! `/v3/` ([spec])
     //!
     //! [spec]: https://spec.matrix.org/v1.2/client-server-api/#delete_matrixclientv3room_keysversionversion
+    //!
+    //! This deletes a backup version and its room keys.
 
     use ruma_api::ruma_api;
 
     ruma_api! {
         metadata: {
-            description: "Delete an existing backup.",
+            description: "Delete a backup version.",
             method: DELETE,
-            name: "delete_backup",
+            name: "delete_backup_version",
             unstable_path: "/_matrix/client/unstable/room_keys/version/:version",
             r0_path: "/_matrix/client/r0/room_keys/version/:version",
             stable_path: "/_matrix/client/v3/room_keys/version/:version",
@@ -21,7 +23,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to delete.
             #[ruma_api(path)]
             pub version: &'a str,
         }
diff --git a/crates/ruma-client-api/src/backup/get_backup.rs b/crates/ruma-client-api/src/backup/get_backup_info.rs
similarity index 94%
rename from crates/ruma-client-api/src/backup/get_backup.rs
rename to crates/ruma-client-api/src/backup/get_backup_info.rs
index 6e0bc1f4..0815f915 100644
--- a/crates/ruma-client-api/src/backup/get_backup.rs
+++ b/crates/ruma-client-api/src/backup/get_backup_info.rs
@@ -1,4 +1,6 @@
 //! `GET /_matrix/client/*/room_keys/version/{version}`
+//!
+//! Get information about a specific backup.
 
 pub mod v3 {
     //! `/v3/` ([spec])
@@ -15,9 +17,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Get information about an existing backup.",
+            description: "Get information about a specific backup.",
             method: GET,
-            name: "get_backup",
+            name: "get_backup_info",
             unstable_path: "/_matrix/client/unstable/room_keys/version/:version",
             stable_path: "/_matrix/client/v3/room_keys/version/:version",
             rate_limited: true,
@@ -26,7 +28,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to retrieve info from.
             #[ruma_api(path)]
             pub version: &'a str,
         }
diff --git a/crates/ruma-client-api/src/backup/get_backup_keys.rs b/crates/ruma-client-api/src/backup/get_backup_keys.rs
index c8d9a6d5..05da049a 100644
--- a/crates/ruma-client-api/src/backup/get_backup_keys.rs
+++ b/crates/ruma-client-api/src/backup/get_backup_keys.rs
@@ -1,4 +1,6 @@
 //! `GET /_matrix/client/*/room_keys/keys`
+//!
+//! Retrieve all keys from a backup version.
 
 pub mod v3 {
     //! `/v3/` ([spec])
@@ -14,7 +16,7 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Retrieve all keys from a backup.",
+            description: "Retrieve all keys from a backup version.",
             method: GET,
             name: "get_backup_keys",
             unstable_path: "/_matrix/client/unstable/room_keys/keys",
@@ -26,9 +28,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
-            ///
-            /// Must be the current backup.
+            /// The backup version to retrieve keys from.
             #[ruma_api(query)]
             pub version: &'a str,
         }
diff --git a/crates/ruma-client-api/src/backup/get_backup_key_sessions.rs b/crates/ruma-client-api/src/backup/get_backup_keys_for_room.rs
similarity index 92%
rename from crates/ruma-client-api/src/backup/get_backup_key_sessions.rs
rename to crates/ruma-client-api/src/backup/get_backup_keys_for_room.rs
index 42824ea1..792b4b77 100644
--- a/crates/ruma-client-api/src/backup/get_backup_key_sessions.rs
+++ b/crates/ruma-client-api/src/backup/get_backup_keys_for_room.rs
@@ -17,7 +17,7 @@ pub mod v3 {
         metadata: {
             description: "Retrieve sessions from the backup for a given room.",
             method: GET,
-            name: "get_backup_key_sessions",
+            name: "get_backup_keys_for_room",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id",
@@ -27,9 +27,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version
-            ///
-            /// Must be the current backup.
+            /// The backup version to retrieve keys from.
             #[ruma_api(query)]
             pub version: &'a str,
 
diff --git a/crates/ruma-client-api/src/backup/get_backup_key_session.rs b/crates/ruma-client-api/src/backup/get_backup_keys_for_session.rs
similarity index 90%
rename from crates/ruma-client-api/src/backup/get_backup_key_session.rs
rename to crates/ruma-client-api/src/backup/get_backup_keys_for_session.rs
index 81de9671..829bf5cf 100644
--- a/crates/ruma-client-api/src/backup/get_backup_key_session.rs
+++ b/crates/ruma-client-api/src/backup/get_backup_keys_for_session.rs
@@ -13,9 +13,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Retrieve a key from the backup",
+            description: "Retrieve a key from the backup for a given session.",
             method: GET,
-            name: "get_backup_key_session",
+            name: "get_backup_keys_for_session",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id/:session_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id/:session_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
@@ -25,9 +25,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
-            ///
-            /// Must be the current backup.
+            /// The backup version to retrieve keys from.
             #[ruma_api(query)]
             pub version: &'a str,
 
diff --git a/crates/ruma-client-api/src/backup/get_latest_backup.rs b/crates/ruma-client-api/src/backup/get_latest_backup_info.rs
similarity index 96%
rename from crates/ruma-client-api/src/backup/get_latest_backup.rs
rename to crates/ruma-client-api/src/backup/get_latest_backup_info.rs
index 8db9e4b2..0ae49b34 100644
--- a/crates/ruma-client-api/src/backup/get_latest_backup.rs
+++ b/crates/ruma-client-api/src/backup/get_latest_backup_info.rs
@@ -12,7 +12,7 @@ pub mod v3 {
     use serde_json::value::to_raw_value as to_raw_json_value;
 
     use crate::backup::{
-        get_backup::v3::{AlgorithmWithData, RefResponseBodyRepr, ResponseBodyRepr},
+        get_backup_info::v3::{AlgorithmWithData, RefResponseBodyRepr, ResponseBodyRepr},
         BackupAlgorithm,
     };
 
@@ -20,7 +20,7 @@ pub mod v3 {
         metadata: {
             description: "Get information about the latest backup.",
             method: GET,
-            name: "get_latest_backup",
+            name: "get_latest_backup_info",
             unstable_path: "/_matrix/client/unstable/room_keys/version",
             r0_path: "/_matrix/client/r0/room_keys/version",
             stable_path: "/_matrix/client/v3/room_keys/version",
diff --git a/crates/ruma-client-api/src/backup/update_backup.rs b/crates/ruma-client-api/src/backup/update_backup_version.rs
similarity index 95%
rename from crates/ruma-client-api/src/backup/update_backup.rs
rename to crates/ruma-client-api/src/backup/update_backup_version.rs
index 1f10fc5a..d2d751fb 100644
--- a/crates/ruma-client-api/src/backup/update_backup.rs
+++ b/crates/ruma-client-api/src/backup/update_backup_version.rs
@@ -14,12 +14,12 @@ pub mod v3 {
         metadata: {
             description: "Update information about an existing backup.",
             method: PUT,
-            name: "update_backup",
+            name: "update_backup_version",
             unstable_path: "/_matrix/client/unstable/room_keys/version/:version",
             stable_path: "/_matrix/client/v3/room_keys/version/:version",
             rate_limited: true,
             authentication: AccessToken,
-            added: 1.1,
+            added: 1.0,
         }
 
         request: {