feat: Make struct types non-exhaustive

This is better to avoid breaking changes when fields are added.

Author: zecakeh

CHANGELOG.md

@@ -8,6 +8,10 @@ Breaking changes:
 * `RoomSortOrder` and `RoomDirection` in `rooms::list_rooms::v1` are now non-
   exhaustive. Their `PartialOrd` and `Ord` implementations now use their string
   representation instead of the order in which they are defined in the enum.
+* `UserDetails`, `ExternalId`, `CurrentUpdate`, `ExperimentalFeatures`,
+  `RoomDetails` and `UserMinorDetails` are now non-exhaustive. To keep using
+  them as if they were exhaustive, use the `ruma_unstable_exhaustive_types`
+  compile-time `cfg` setting.
 
 Improvement:
 

Cargo.toml

@@ -43,7 +43,7 @@ dbg_macro = "warn"
 disallowed_types = "warn"
 empty_line_after_outer_attr = "warn"
 exhaustive_enums = "warn"
-# exhaustive_structs = "warn"
+exhaustive_structs = "warn"
 inefficient_to_string = "warn"
 macro_use_imports = "warn"
 map_flatten = "warn"

src/background_updates/status/v1.rs

@@ -28,7 +28,12 @@ pub struct Response {
     pub current_updates: HashMap<String, CurrentUpdate>,
 }
 
+/// Information about a current update.
+///
+/// To create an instance of this type, first create a `CurrentUpdateInit` and convert it via
+/// `CurrentUpdate::from` / `.into()`.
 #[derive(Serialize, Deserialize, PartialEq, Clone, Debug)]
+#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
 pub struct CurrentUpdate {
     /// Name of the update.
     pub name: String,
@@ -43,6 +48,33 @@ pub struct CurrentUpdate {
     pub average_items_per_ms: f64,
 }
 
+/// Initial set of fields of [`CurrentUpdate`].
+///
+/// This struct will not be updated even if additional fields are added to `CurrentUpdate`.
+#[derive(Debug)]
+#[allow(clippy::exhaustive_structs)]
+pub struct CurrentUpdateInit {
+    /// Name of the update.
+    pub name: String,
+
+    /// Total number of processed "items".
+    pub total_item_count: u64,
+
+    /// Runtime of background process, not including sleeping time.
+    pub total_duration_ms: f64,
+
+    /// Items processed per millisecond based on an exponential average.
+    pub average_items_per_ms: f64,
+}
+
+impl From<CurrentUpdateInit> for CurrentUpdate {
+    fn from(value: CurrentUpdateInit) -> Self {
+        let CurrentUpdateInit { name, total_item_count, total_duration_ms, average_items_per_ms } =
+            value;
+        Self { name, total_item_count, total_duration_ms, average_items_per_ms }
+    }
+}
+
 impl Request {
     /// Creates an empty `Request`.
     pub fn new() -> Self {

src/experimental_features/enable_features/v1.rs

@@ -26,6 +26,7 @@ pub struct Request {
 }
 
 #[derive(Serialize, Deserialize, Clone, PartialEq, Debug, Default)]
+#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
 pub struct ExperimentalFeatures {
     /// Whether busy presence state is enabled.
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -38,6 +39,13 @@ pub struct ExperimentalFeatures {
     pub msc3967: Option<bool>,
 }
 
+impl ExperimentalFeatures {
+    /// Construct an empty `ExperimentalFeatures`.
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
 #[response]
 #[derive(Default)]
 pub struct Response {}

src/lib.rs

@@ -1,6 +1,20 @@
 //! Serializable types for the requests and responses for each endpoint in the
 //! [synapse admin API][api].
 //!
+//! # Compile-time `cfg` settings
+//!
+//! These settings are accepted at compile time to configure the generated code. They can be set as
+//! `--cfg={key}={value}` using `RUSTFLAGS` or `.cargo/config.toml` (under `[build]` -> `rustflags =
+//! ["..."]`).
+//!
+//! * `ruma_identifiers_storage` -- Choose the inner representation of `Owned*` wrapper types for
+//!   identifiers. By default they use [`Box`], setting the value to `Arc` makes them use
+//!   [`Arc`](std::sync::Arc).
+//! * `ruma_unstable_exhaustive_types` -- Most types in synapse-admin-api are marked as
+//!   non-exhaustive to avoid breaking changes when new fields are added in the API. This setting
+//!   compiles all types as exhaustive. By enabling this feature you opt out of all semver
+//!   guarantees synapse-admin-api otherwise provides.
+//!
 //! [api]: https://github.com/matrix-org/synapse/tree/master/docs/admin_api
 
 // FIXME: don't allow dead code, warn on missing docs

src/rooms/list_rooms/v1.rs

@@ -5,7 +5,7 @@ use ruma::{
     room::RoomType,
     serde::{OrdAsRefStr, PartialEqAsRefStr, PartialOrdAsRefStr, StringEnum},
     space::SpaceRoomJoinRule,
-    OwnedRoomAliasId, OwnedRoomId, OwnedUserId, UInt,
+    uint, OwnedRoomAliasId, OwnedRoomId, OwnedUserId, UInt,
 };
 use serde::{Deserialize, Serialize};
 
@@ -147,6 +147,7 @@ pub enum SortDirection {
 
 /// Structure for all the room details.
 #[derive(Serialize, Deserialize, Clone, Debug)]
+#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
 pub struct RoomDetails {
     /// Room ID
     pub room_id: OwnedRoomId,
@@ -196,3 +197,27 @@ pub struct RoomDetails {
     /// Room type of the room.
     pub room_type: Option<RoomType>,
 }
+
+impl RoomDetails {
+    /// Construct `RoomDetails` with the given room ID and all the other fields at their default
+    /// value.
+    pub fn new(room_id: OwnedRoomId) -> Self {
+        Self {
+            room_id,
+            name: None,
+            canonical_alias: None,
+            joined_members: uint!(0),
+            joined_local_members: uint!(0),
+            version: None,
+            creator: None,
+            encryption: None,
+            federatable: false,
+            public: false,
+            join_rules: None,
+            guest_access: None,
+            history_visibility: None,
+            state_events: uint!(0),
+            room_type: None,
+        }
+    }
+}

src/users.rs

@@ -12,6 +12,7 @@ use serde::{Deserialize, Serialize};
 
 /// User details
 #[derive(Serialize, Deserialize, Clone, Debug)]
+#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
 pub struct UserDetails {
     /// The user's name.
     pub name: String,
@@ -71,12 +72,44 @@ pub struct UserDetails {
     pub locked: bool,
 }
 
+impl UserDetails {
+    /// Construct a `UserDetails` with the given user name and all the other fields set to their
+    /// default value.
+    pub fn new(name: String) -> Self {
+        Self {
+            name,
+            password_hash: None,
+            is_guest: false,
+            admin: false,
+            consent_version: None,
+            consent_server_notice_sent: None,
+            appservice_id: None,
+            creation_ts: None,
+            user_type: None,
+            deactivated: false,
+            displayname: String::new(),
+            avatar_url: None,
+            threepids: Vec::new(),
+            external_ids: Vec::new(),
+            locked: false,
+        }
+    }
+}
+
 /// An external ID associated with a user
 #[derive(Clone, Debug, Deserialize, Serialize)]
+#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
 pub struct ExternalId {
     /// The authentication provider to which the user is associated.
     pub auth_provider: String,
 
     /// The ID known to the auth provider associated with this user.
     pub external_id: String,
 }
+
+impl ExternalId {
+    /// Construct an `ExternalId` with the given authentication provider and ID.
+    pub fn new(auth_provider: String, external_id: String) -> Self {
+        Self { auth_provider, external_id }
+    }
+}

src/users/list_users/v2.rs

@@ -97,6 +97,7 @@ impl Response {
 
 /// A minor set of user details.
 #[derive(Serialize, Deserialize, Clone, Debug)]
+#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
 pub struct UserMinorDetails {
     /// The user's name.
     pub name: String,
@@ -128,3 +129,20 @@ pub struct UserMinorDetails {
     #[serde(default, deserialize_with = "crate::serde::bool_or_uint")]
     pub locked: bool,
 }
+
+impl UserMinorDetails {
+    /// Construct a `UserMinorDetails` with the given user name and all the other fields set to
+    /// their default value.
+    pub fn new(name: String) -> Self {
+        Self {
+            name,
+            is_guest: false,
+            admin: false,
+            user_type: None,
+            deactivated: false,
+            displayname: String::new(),
+            avatar_url: None,
+            locked: false,
+        }
+    }
+}