feat: Rename OlmMachine.share_group_session to OlmMachine.share_room_key.

As discussed with @poljar, the Matrix event we are creating is
`m.room.key`, so it's preferable to rename the function
`share_room_key`. Note: Olm calls the things an inbound group session,
that's where the name comes from, but it's not aligned with the
specification.

benchmarks/benches/crypto_bench.rs

@@ -163,7 +163,7 @@ pub fn room_key_sharing(c: &mut Criterion) {
     group.bench_function(BenchmarkId::new("memory store", &name), |b| {
         b.to_async(&runtime).iter(|| async {
             let requests = machine
-                .share_group_session(
+                .share_room_key(
                     room_id,
                     users.iter().map(Deref::deref),
                     EncryptionSettings::default(),
@@ -191,7 +191,7 @@ pub fn room_key_sharing(c: &mut Criterion) {
     group.bench_function(BenchmarkId::new("sled store", &name), |b| {
         b.to_async(&runtime).iter(|| async {
             let requests = machine
-                .share_group_session(
+                .share_room_key(
                     room_id,
                     users.iter().map(Deref::deref),
                     EncryptionSettings::default(),

crates/matrix-sdk-base/src/client.rs

@@ -996,9 +996,9 @@ impl BaseClient {
         }
     }
 
-    /// Get a to-device request that will share a group session for a room.
+    /// Get a to-device request that will share a room key with users in a room.
     #[cfg(feature = "e2e-encryption")]
-    pub async fn share_group_session(&self, room_id: &RoomId) -> Result<Vec<Arc<ToDeviceRequest>>> {
+    pub async fn share_room_key(&self, room_id: &RoomId) -> Result<Vec<Arc<ToDeviceRequest>>> {
         match self.olm_machine() {
             Some(o) => {
                 let (history_visibility, settings) = self
@@ -1020,7 +1020,7 @@ impl BaseClient {
                 let settings = settings.ok_or(MegolmError::EncryptionNotEnabled)?;
                 let settings = EncryptionSettings::new(settings, history_visibility);
 
-                Ok(o.share_group_session(room_id, members.map(Deref::deref), settings).await?)
+                Ok(o.share_room_key(room_id, members.map(Deref::deref), settings).await?)
             }
             None => panic!("Olm machine wasn't started"),
         }

crates/matrix-sdk-crypto-ffi/src/machine.rs

@@ -425,7 +425,7 @@ impl OlmMachine {
     /// [mark_request_as_sent()](#method.mark_request_as_sent) method.
     ///
     /// This method should be called every time before a call to
-    /// [`share_group_session()`](#method.share_group_session) is made.
+    /// [`share_room_key()`](#method.share_room_key) is made.
     ///
     /// # Arguments
     ///
@@ -470,7 +470,7 @@ impl OlmMachine {
             users.into_iter().filter_map(|u| UserId::parse(u).ok()).collect();
 
         let room_id = RoomId::parse(room_id)?;
-        let requests = self.runtime.block_on(self.inner.share_group_session(
+        let requests = self.runtime.block_on(self.inner.share_room_key(
             &room_id,
             users.iter().map(Deref::deref),
             EncryptionSettings::default(),
@@ -494,7 +494,7 @@ impl OlmMachine {
     ///    method. This method call should be locked per call.
     ///
     /// 2. Share a room key with all the room members using the
-    ///    [`share_group_session()`](#method.share_group_session). This method
+    ///    [`share_room_key()`](#method.share_room_key). This method
     ///    call should be locked per room.
     ///
     /// 3. Encrypt the event using this method.

crates/matrix-sdk-crypto-js/src/machine.rs

@@ -231,8 +231,8 @@ impl OlmMachine {
 
     /// Encrypt a room message for the given room.
     ///
-    /// Beware that a group session needs to be shared before this
-    /// method can be called using the `share_group_session` method.
+    /// Beware that a room key needs to be shared before this
+    /// method can be called using the `share_room_key` method.
     ///
     /// `room_id` is the ID of the room for which the message should
     /// be encrypted. `event_type` is the type of the event. `content`
@@ -274,13 +274,13 @@ impl OlmMachine {
         future_to_promise(async move { Ok(me.invalidate_group_session(&room_id).await?) })
     }
 
-    /// Get to-device requests to share a group session with users in a room.
+    /// Get to-device requests to share a room key with users in a room.
     ///
     /// `room_id` is the room ID. `users` is an array of `UserId`
     /// objects. `encryption_settings` are an `EncryptionSettings`
     /// object.
-    #[wasm_bindgen(js_name = "shareGroupSession")]
-    pub fn share_group_session(
+    #[wasm_bindgen(js_name = "shareRoomKey")]
+    pub fn share_room_key(
         &self,
         room_id: &identifiers::RoomId,
         users: &Array,
@@ -298,12 +298,8 @@ impl OlmMachine {
 
         Ok(future_to_promise(async move {
             Ok(serde_json::to_string(
-                &me.share_group_session(
-                    &room_id,
-                    users.iter().map(AsRef::as_ref),
-                    encryption_settings,
-                )
-                .await?,
+                &me.share_room_key(&room_id, users.iter().map(AsRef::as_ref), encryption_settings)
+                    .await?,
             )?)
         }))
     }

crates/matrix-sdk-crypto/src/machine.rs

@@ -634,8 +634,8 @@ impl OlmMachine {
 
     /// Encrypt a room message for the given room.
     ///
-    /// Beware that a group session needs to be shared before this method can be
-    /// called using the [`OlmMachine::share_group_session`] method.
+    /// Beware that a room key needs to be shared before this method
+    /// can be called using the [`OlmMachine::share_room_key`] method.
     ///
     /// # Arguments
     ///
@@ -647,9 +647,7 @@ impl OlmMachine {
     ///
     /// # Panics
     ///
-    /// Panics if a group session for the given room wasn't shared beforehand.
-    ///
-    /// [`share_group_session`]: Self::share_group_session
+    /// Panics if a room key for the given room wasn't shared beforehand.
     pub async fn encrypt_room_event(
         &self,
         room_id: &RoomId,
@@ -697,21 +695,21 @@ impl OlmMachine {
         self.group_session_manager.invalidate_group_session(room_id).await
     }
 
-    /// Get to-device requests to share a group session with users in a room.
+    /// Get to-device requests to share a room key with users in a room.
     ///
     /// # Arguments
     ///
-    /// `room_id` - The room id of the room where the group session will be
+    /// `room_id` - The room id of the room where the room key will be
     /// used.
     ///
-    /// `users` - The list of users that should receive the group session.
-    pub async fn share_group_session(
+    /// `users` - The list of users that should receive the room key.
+    pub async fn share_room_key(
         &self,
         room_id: &RoomId,
         users: impl Iterator<Item = &UserId>,
         encryption_settings: impl Into<EncryptionSettings>,
     ) -> OlmResult<Vec<Arc<ToDeviceRequest>>> {
-        self.group_session_manager.share_group_session(room_id, users, encryption_settings).await
+        self.group_session_manager.share_room_key(room_id, users, encryption_settings).await
     }
 
     /// Receive an unencrypted verification event.
@@ -1891,7 +1889,7 @@ pub(crate) mod tests {
         let room_id = room_id!("!test:example.org");
 
         let to_device_requests = alice
-            .share_group_session(room_id, iter::once(bob.user_id()), EncryptionSettings::default())
+            .share_room_key(room_id, iter::once(bob.user_id()), EncryptionSettings::default())
             .await
             .unwrap();
 
@@ -1937,7 +1935,7 @@ pub(crate) mod tests {
         let room_id = room_id!("!test:example.org");
 
         let to_device_requests = alice
-            .share_group_session(room_id, iter::once(bob.user_id()), EncryptionSettings::default())
+            .share_room_key(room_id, iter::once(bob.user_id()), EncryptionSettings::default())
             .await
             .unwrap();
 

crates/matrix-sdk-crypto/src/olm/group_sessions/outbound.rs

@@ -258,13 +258,8 @@ impl OutboundGroupSession {
 
     /// Encrypt a room message for the given room.
     ///
-    /// Beware that a group session needs to be shared before this method can be
-    /// called using the `share_group_session()` method.
-    ///
-    /// Since group sessions can expire or become invalid if the room membership
-    /// changes client authors should check with the
-    /// `should_share_group_session()` method if a new group session needs to
-    /// be shared.
+    /// Beware that a room key needs to be shared before this method
+    /// can be called using the `share_room_key()` method.
     ///
     /// # Arguments
     ///

crates/matrix-sdk-crypto/src/session_manager/group_sessions.rs

@@ -429,18 +429,17 @@ impl GroupSessionManager {
         self.sessions.clone()
     }
 
-    /// Get to-device requests to share a group session with users in a room.
+    /// Get to-device requests to share a room key with users in a room.
     ///
     /// # Arguments
     ///
-    /// `room_id` - The room id of the room where the group session will be
-    /// used.
+    /// `room_id` - The room id of the room where the room key will be used.
     ///
-    /// `users` - The list of users that should receive the group session.
+    /// `users` - The list of users that should receive the room key.
     ///
-    /// `encryption_settings` - The settings that should be used for the group
-    /// session.
-    pub async fn share_group_session(
+    /// `encryption_settings` - The settings that should be used for
+    /// the room key.
+    pub async fn share_room_key(
         &self,
         room_id: &RoomId,
         users: impl Iterator<Item = &UserId>,
@@ -650,10 +649,8 @@ mod tests {
 
         let users = keys_claim.one_time_keys.keys().map(Deref::deref);
 
-        let requests = machine
-            .share_group_session(room_id, users, EncryptionSettings::default())
-            .await
-            .unwrap();
+        let requests =
+            machine.share_room_key(room_id, users, EncryptionSettings::default()).await.unwrap();
 
         let event_count: usize = requests.iter().map(|r| r.message_count()).sum();
 

crates/matrix-sdk/src/room/joined.rs

@@ -310,14 +310,14 @@ impl Joined {
         Ok(())
     }
 
-    /// Share a group session for the given room.
+    /// Share a room key with users in the given room.
     ///
     /// This will create Olm sessions with all the users/device pairs in the
-    /// room if necessary and share a group session with them.
+    /// room if necessary and share a room key that can be shared with them.
     ///
-    /// Does nothing if no group session needs to be shared.
+    /// Does nothing if no room key needs to be shared.
     #[cfg(feature = "e2e-encryption")]
-    async fn preshare_group_session(&self) -> Result<()> {
+    async fn preshare_room_key(&self) -> Result<()> {
         // TODO expose this publicly so people can pre-share a group session if
         // e.g. a user starts to type a message for a room.
         if let Some(mutex) =
@@ -345,7 +345,7 @@ impl Joined {
                 self.client.claim_one_time_keys(members).await?;
             };
 
-            let response = self.share_group_session().await;
+            let response = self.share_room_key().await;
 
             self.client.inner.group_session_locks.remove(self.inner.room_id());
 
@@ -368,8 +368,8 @@ impl Joined {
     /// Panics if the client isn't logged in.
     #[instrument]
     #[cfg(feature = "e2e-encryption")]
-    async fn share_group_session(&self) -> Result<()> {
-        let requests = self.client.base_client().share_group_session(self.inner.room_id()).await?;
+    async fn share_room_key(&self) -> Result<()> {
+        let requests = self.client.base_client().share_room_key(self.inner.room_id()).await?;
 
         for request in requests {
             let response = self.client.send_to_device(&request).await?;
@@ -570,7 +570,7 @@ impl Joined {
                     // TODO query keys here?
                 }
 
-                self.preshare_group_session().await?;
+                self.preshare_room_key().await?;
 
                 let olm = self.client.olm_machine().expect("Olm machine wasn't started");