Enable clippy lints on a workspace level

This enables a lot more lints than before in some crates, so this fixed a lot of warnings as well.

crates/data-model/src/compat/device.rs

@@ -40,7 +40,11 @@ impl Device {
     #[must_use]
     pub fn to_scope_token(&self) -> ScopeToken {
         // SAFETY: the inner id should only have valid scope characters
-        format!("{DEVICE_SCOPE_PREFIX}{}", self.id).parse().unwrap()
+        let Ok(scope_token) = format!("{DEVICE_SCOPE_PREFIX}{}", self.id).parse() else {
+            unreachable!()
+        };
+
+        scope_token
     }
 
     /// Get the corresponding [`Device`] from a [`ScopeToken`]

crates/data-model/src/compat/mod.rs

@@ -72,6 +72,11 @@ impl CompatRefreshTokenState {
         matches!(self, Self::Consumed { .. })
     }
 
+    /// Consume the refresh token, returning a new state.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the refresh token is already consumed.
     pub fn consume(self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         match self {
             Self::Valid => Ok(Self::Consumed { consumed_at }),
@@ -99,6 +104,11 @@ impl std::ops::Deref for CompatRefreshToken {
 }
 
 impl CompatRefreshToken {
+    /// Consume the refresh token and return the consumed token.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the refresh token is already consumed.
     pub fn consume(mut self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         self.state = self.state.consume(consumed_at)?;
         Ok(self)

crates/data-model/src/compat/sso_login.rs

@@ -36,7 +36,7 @@ pub enum CompatSsoLoginState {
 }
 
 impl CompatSsoLoginState {
-    /// Returns `true` if the compat sso login state is [`Pending`].
+    /// Returns `true` if the compat SSO login state is [`Pending`].
     ///
     /// [`Pending`]: CompatSsoLoginState::Pending
     #[must_use]
@@ -44,7 +44,7 @@ impl CompatSsoLoginState {
         matches!(self, Self::Pending)
     }
 
-    /// Returns `true` if the compat sso login state is [`Fulfilled`].
+    /// Returns `true` if the compat SSO login state is [`Fulfilled`].
     ///
     /// [`Fulfilled`]: CompatSsoLoginState::Fulfilled
     #[must_use]
@@ -52,7 +52,7 @@ impl CompatSsoLoginState {
         matches!(self, Self::Fulfilled { .. })
     }
 
-    /// Returns `true` if the compat sso login state is [`Exchanged`].
+    /// Returns `true` if the compat SSO login state is [`Exchanged`].
     ///
     /// [`Exchanged`]: CompatSsoLoginState::Exchanged
     #[must_use]
@@ -60,6 +60,11 @@ impl CompatSsoLoginState {
         matches!(self, Self::Exchanged { .. })
     }
 
+    /// Get the time at which the login was fulfilled.
+    ///
+    /// Returns `None` if the compat SSO login state is [`Pending`].
+    ///
+    /// [`Pending`]: CompatSsoLoginState::Pending
     #[must_use]
     pub fn fulfilled_at(&self) -> Option<DateTime<Utc>> {
         match self {
@@ -70,6 +75,11 @@ impl CompatSsoLoginState {
         }
     }
 
+    /// Get the time at which the login was exchanged.
+    ///
+    /// Returns `None` if the compat SSO login state is not [`Exchanged`].
+    ///
+    /// [`Exchanged`]: CompatSsoLoginState::Exchanged
     #[must_use]
     pub fn exchanged_at(&self) -> Option<DateTime<Utc>> {
         match self {
@@ -78,6 +88,11 @@ impl CompatSsoLoginState {
         }
     }
 
+    /// Get the session ID associated with the login.
+    ///
+    /// Returns `None` if the compat SSO login state is [`Pending`].
+    ///
+    /// [`Pending`]: CompatSsoLoginState::Pending
     #[must_use]
     pub fn session_id(&self) -> Option<Ulid> {
         match self {
@@ -88,6 +103,14 @@ impl CompatSsoLoginState {
         }
     }
 
+    /// Transition the compat SSO login state from [`Pending`] to [`Fulfilled`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the compat SSO login state is not [`Pending`].
+    ///
+    /// [`Pending`]: CompatSsoLoginState::Pending
+    /// [`Fulfilled`]: CompatSsoLoginState::Fulfilled
     pub fn fulfill(
         self,
         fulfilled_at: DateTime<Utc>,
@@ -102,6 +125,15 @@ impl CompatSsoLoginState {
         }
     }
 
+    /// Transition the compat SSO login state from [`Fulfilled`] to
+    /// [`Exchanged`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the compat SSO login state is not [`Fulfilled`].
+    ///
+    /// [`Fulfilled`]: CompatSsoLoginState::Fulfilled
+    /// [`Exchanged`]: CompatSsoLoginState::Exchanged
     pub fn exchange(self, exchanged_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         match self {
             Self::Fulfilled {
@@ -135,6 +167,15 @@ impl std::ops::Deref for CompatSsoLogin {
 }
 
 impl CompatSsoLogin {
+    /// Transition the compat SSO login from a [`Pending`] state to
+    /// [`Fulfilled`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the compat SSO login state is not [`Pending`].
+    ///
+    /// [`Pending`]: CompatSsoLoginState::Pending
+    /// [`Fulfilled`]: CompatSsoLoginState::Fulfilled
     pub fn fulfill(
         mut self,
         fulfilled_at: DateTime<Utc>,
@@ -144,6 +185,15 @@ impl CompatSsoLogin {
         Ok(self)
     }
 
+    /// Transition the compat SSO login from a [`Fulfilled`] state to
+    /// [`Exchanged`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the compat SSO login state is not [`Fulfilled`].
+    ///
+    /// [`Fulfilled`]: CompatSsoLoginState::Fulfilled
+    /// [`Exchanged`]: CompatSsoLoginState::Exchanged
     pub fn exchange(mut self, exchanged_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         self.state = self.state.exchange(exchanged_at)?;
         Ok(self)

crates/data-model/src/lib.rs

@@ -12,14 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#![forbid(unsafe_code)]
-#![deny(clippy::all, clippy::str_to_string, rustdoc::broken_intra_doc_links)]
-#![warn(clippy::pedantic)]
-#![allow(
-    clippy::module_name_repetitions,
-    clippy::missing_panics_doc,
-    clippy::missing_errors_doc
-)]
+#![allow(clippy::module_name_repetitions)]
 
 use thiserror::Error;
 
@@ -29,6 +22,7 @@ pub(crate) mod tokens;
 pub(crate) mod upstream_oauth2;
 pub(crate) mod users;
 
+/// Error when an invalid state transition is attempted.
 #[derive(Debug, Error)]
 #[error("invalid state transition")]
 pub struct InvalidTransitionError;

crates/data-model/src/oauth2/authorization_grant.rs

@@ -39,6 +39,7 @@ pub struct Pkce {
 }
 
 impl Pkce {
+    /// Create a new PKCE challenge, with the given method and challenge.
     #[must_use]
     pub fn new(challenge_method: PkceCodeChallengeMethod, challenge: String) -> Self {
         Pkce {
@@ -47,6 +48,11 @@ impl Pkce {
         }
     }
 
+    /// Verify the PKCE challenge.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the verifier is invalid.
     pub fn verify(&self, verifier: &str) -> Result<(), CodeChallengeError> {
         self.challenge_method.verify(&self.challenge, verifier)
     }
@@ -176,11 +182,25 @@ impl AuthorizationGrant {
         self.created_at - Duration::seconds(max_age.unwrap_or(3600 * 24 * 365))
     }
 
+    /// Mark the authorization grant as exchanged.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the authorization grant is not [`Fulfilled`].
+    ///
+    /// [`Fulfilled`]: AuthorizationGrantStage::Fulfilled
     pub fn exchange(mut self, exchanged_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         self.stage = self.stage.exchange(exchanged_at)?;
         Ok(self)
     }
 
+    /// Mark the authorization grant as fulfilled.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the authorization grant is not [`Pending`].
+    ///
+    /// [`Pending`]: AuthorizationGrantStage::Pending
     pub fn fulfill(
         mut self,
         fulfilled_at: DateTime<Utc>,
@@ -190,12 +210,23 @@ impl AuthorizationGrant {
         Ok(self)
     }
 
-    // TODO: this is not used?
+    /// Mark the authorization grant as cancelled.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the authorization grant is not [`Pending`].
+    ///
+    /// [`Pending`]: AuthorizationGrantStage::Pending
+    ///
+    /// # TODO
+    ///
+    /// This appears to be unused
     pub fn cancel(mut self, canceld_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         self.stage = self.stage.cancel(canceld_at)?;
         Ok(self)
     }
 
+    #[doc(hidden)]
     pub fn sample(now: DateTime<Utc>, rng: &mut impl RngCore) -> Self {
         Self {
             id: Ulid::from_datetime_with_source(now.into(), rng),

crates/data-model/src/oauth2/client.rs

@@ -112,6 +112,15 @@ pub enum InvalidRedirectUriError {
 }
 
 impl Client {
+    /// Determine which redirect URI to use for the given request.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    ///  - no URL was given but multiple redirect URIs are registered,
+    ///  - no URL was registered, or
+    ///  - the given URL is not registered
     pub fn resolve_redirect_uri<'a>(
         &'a self,
         redirect_uri: &'a Option<Url>,
@@ -125,6 +134,7 @@ impl Client {
         }
     }
 
+    #[doc(hidden)]
     pub fn samples(now: DateTime<Utc>, rng: &mut impl RngCore) -> Vec<Client> {
         vec![
             // A client with all the URIs set

crates/data-model/src/tokens.rs

@@ -121,6 +121,11 @@ pub enum RefreshTokenState {
 }
 
 impl RefreshTokenState {
+    /// Consume the refresh token, returning a new state.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the refresh token is already consumed.
     fn consume(self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         match self {
             Self::Valid => Ok(Self::Consumed { consumed_at }),
@@ -169,6 +174,11 @@ impl RefreshToken {
         self.id.to_string()
     }
 
+    /// Consumes the refresh token and returns the consumed token.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the refresh token is already consumed.
     pub fn consume(mut self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         self.state = self.state.consume(consumed_at)?;
         Ok(self)
@@ -266,6 +276,10 @@ impl TokenType {
     ///     Ok(TokenType::CompatAccessToken)
     /// );
     /// ```
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the token is not valid
     pub fn check(token: &str) -> Result<TokenType, TokenFormatError> {
         // these are legacy tokens imported from Synapse
         // we don't do any validation on them and continue as is

crates/data-model/src/upstream_oauth2/session.rs

@@ -37,6 +37,14 @@ pub enum UpstreamOAuthAuthorizationSessionState {
 }
 
 impl UpstreamOAuthAuthorizationSessionState {
+    /// Mark the upstream OAuth 2.0 authorization session as completed.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the upstream OAuth 2.0 authorization session state
+    /// is not [`Pending`].
+    ///
+    /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
     pub fn complete(
         self,
         completed_at: DateTime<Utc>,
@@ -53,6 +61,14 @@ impl UpstreamOAuthAuthorizationSessionState {
         }
     }
 
+    /// Mark the upstream OAuth 2.0 authorization session as consumed.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the upstream OAuth 2.0 authorization session state
+    /// is not [`Completed`].
+    ///
+    /// [`Completed`]: UpstreamOAuthAuthorizationSessionState::Completed
     pub fn consume(self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         match self {
             Self::Completed {
@@ -69,6 +85,12 @@ impl UpstreamOAuthAuthorizationSessionState {
         }
     }
 
+    /// Get the link ID for the upstream OAuth 2.0 authorization session.
+    ///
+    /// Returns `None` if the upstream OAuth 2.0 authorization session state is
+    /// [`Pending`].
+    ///
+    /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
     #[must_use]
     pub fn link_id(&self) -> Option<Ulid> {
         match self {
@@ -77,6 +99,13 @@ impl UpstreamOAuthAuthorizationSessionState {
         }
     }
 
+    /// Get the time at which the upstream OAuth 2.0 authorization session was
+    /// completed.
+    ///
+    /// Returns `None` if the upstream OAuth 2.0 authorization session state is
+    /// [`Pending`].
+    ///
+    /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
     #[must_use]
     pub fn completed_at(&self) -> Option<DateTime<Utc>> {
         match self {
@@ -87,6 +116,12 @@ impl UpstreamOAuthAuthorizationSessionState {
         }
     }
 
+    /// Get the ID token for the upstream OAuth 2.0 authorization session.
+    ///
+    /// Returns `None` if the upstream OAuth 2.0 authorization session state is
+    /// [`Pending`].
+    ///
+    /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
     #[must_use]
     pub fn id_token(&self) -> Option<&str> {
         match self {
@@ -97,6 +132,13 @@ impl UpstreamOAuthAuthorizationSessionState {
         }
     }
 
+    /// Get the time at which the upstream OAuth 2.0 authorization session was
+    /// consumed.
+    ///
+    /// Returns `None` if the upstream OAuth 2.0 authorization session state is
+    /// not [`Consumed`].
+    ///
+    /// [`Consumed`]: UpstreamOAuthAuthorizationSessionState::Consumed
     #[must_use]
     pub fn consumed_at(&self) -> Option<DateTime<Utc>> {
         match self {
@@ -105,7 +147,7 @@ impl UpstreamOAuthAuthorizationSessionState {
         }
     }
 
-    /// Returns `true` if the upstream oauth authorization session state is
+    /// Returns `true` if the upstream OAuth 2.0 authorization session state is
     /// [`Pending`].
     ///
     /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
@@ -114,7 +156,7 @@ impl UpstreamOAuthAuthorizationSessionState {
         matches!(self, Self::Pending)
     }
 
-    /// Returns `true` if the upstream oauth authorization session state is
+    /// Returns `true` if the upstream OAuth 2.0 authorization session state is
     /// [`Completed`].
     ///
     /// [`Completed`]: UpstreamOAuthAuthorizationSessionState::Completed
@@ -123,7 +165,7 @@ impl UpstreamOAuthAuthorizationSessionState {
         matches!(self, Self::Completed { .. })
     }
 
-    /// Returns `true` if the upstream oauth authorization session state is
+    /// Returns `true` if the upstream OAuth 2.0 authorization session state is
     /// [`Consumed`].
     ///
     /// [`Consumed`]: UpstreamOAuthAuthorizationSessionState::Consumed
@@ -153,6 +195,15 @@ impl std::ops::Deref for UpstreamOAuthAuthorizationSession {
 }
 
 impl UpstreamOAuthAuthorizationSession {
+    /// Mark the upstream OAuth 2.0 authorization session as completed. Returns
+    /// the updated session.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the upstream OAuth 2.0 authorization session state
+    /// is not [`Pending`].
+    ///
+    /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
     pub fn complete(
         mut self,
         completed_at: DateTime<Utc>,
@@ -163,6 +214,15 @@ impl UpstreamOAuthAuthorizationSession {
         Ok(self)
     }
 
+    /// Mark the upstream OAuth 2.0 authorization session as consumed. Returns
+    /// the updated session.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the upstream OAuth 2.0 authorization session state
+    /// is not [`Completed`].
+    ///
+    /// [`Completed`]: UpstreamOAuthAuthorizationSessionState::Completed
     pub fn consume(mut self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
         self.state = self.state.consume(consumed_at)?;
         Ok(self)

crates/data-model/src/users.rs

@@ -39,6 +39,7 @@ impl User {
 }
 
 impl User {
+    #[doc(hidden)]
     #[must_use]
     pub fn samples(now: chrono::DateTime<Utc>, rng: &mut impl Rng) -> Vec<Self> {
         vec![User {
@@ -175,6 +176,7 @@ impl Deref for UserEmailVerification {
 }
 
 impl UserEmailVerification {
+    #[doc(hidden)]
     #[must_use]
     pub fn samples(now: chrono::DateTime<Utc>, rng: &mut impl Rng) -> Vec<Self> {
         let states = [