storage: document all the repository traits and methods

crates/storage/src/upstream_oauth2/link.rs

@@ -19,14 +19,39 @@ use ulid::Ulid;
 
 use crate::{pagination::Page, repository_impl, Clock, Pagination};
 
+/// An [`UpstreamOAuthLinkRepository`] helps interacting with
+/// [`UpstreamOAuthLink`] with the storage backend
 #[async_trait]
 pub trait UpstreamOAuthLinkRepository: Send + Sync {
+    /// The error type returned by the repository
     type Error;
 
     /// Lookup an upstream OAuth link by its ID
+    ///
+    /// Returns `None` if the link does not exist
+    ///
+    /// # Parameters
+    ///
+    /// * `id`: The ID of the upstream OAuth link to lookup
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn lookup(&mut self, id: Ulid) -> Result<Option<UpstreamOAuthLink>, Self::Error>;
 
     /// Find an upstream OAuth link for a provider by its subject
+    ///
+    /// Returns `None` if no matching upstream OAuth link was found
+    ///
+    /// # Parameters
+    ///
+    /// * `upstream_oauth_provider`: The upstream OAuth provider on which to
+    ///   find the link
+    /// * `subject`: The subject of the upstream OAuth link to find
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn find_by_subject(
         &mut self,
         upstream_oauth_provider: &UpstreamOAuthProvider,
@@ -34,6 +59,20 @@ pub trait UpstreamOAuthLinkRepository: Send + Sync {
     ) -> Result<Option<UpstreamOAuthLink>, Self::Error>;
 
     /// Add a new upstream OAuth link
+    ///
+    /// Returns the newly created upstream OAuth link
+    ///
+    /// # Parameters
+    ///
+    /// * `rng`: The random number generator to use
+    /// * `clock`: The clock used to generate timestamps
+    /// * `upsream_oauth_provider`: The upstream OAuth provider for which to
+    ///   create the link
+    /// * `subject`: The subject of the upstream OAuth link to create
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn add(
         &mut self,
         rng: &mut (dyn RngCore + Send),
@@ -43,6 +82,17 @@ pub trait UpstreamOAuthLinkRepository: Send + Sync {
     ) -> Result<UpstreamOAuthLink, Self::Error>;
 
     /// Associate an upstream OAuth link to a user
+    ///
+    /// Returns the updated upstream OAuth link
+    ///
+    /// # Parameters
+    ///
+    /// * `upstream_oauth_link`: The upstream OAuth link to update
+    /// * `user`: The user to associate to the upstream OAuth link
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn associate_to_user(
         &mut self,
         upstream_oauth_link: &UpstreamOAuthLink,
@@ -50,6 +100,15 @@ pub trait UpstreamOAuthLinkRepository: Send + Sync {
     ) -> Result<(), Self::Error>;
 
     /// Get a paginated list of upstream OAuth links on a user
+    ///
+    /// # Parameters
+    ///
+    /// * `user`: The user for which to get the upstream OAuth links
+    /// * `pagination`: The pagination parameters
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn list_paginated(
         &mut self,
         user: &User,

crates/storage/src/upstream_oauth2/mod.rs

@@ -12,6 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Repositories to interact with entities related to the upstream OAuth 2.0
+//! providers
+
 mod link;
 mod provider;
 mod session;

crates/storage/src/upstream_oauth2/provider.rs

@@ -21,14 +21,47 @@ use ulid::Ulid;
 
 use crate::{pagination::Page, repository_impl, Clock, Pagination};
 
+/// An [`UpstreamOAuthProviderRepository`] helps interacting with
+/// [`UpstreamOAuthProvider`] saved in the storage backend
 #[async_trait]
 pub trait UpstreamOAuthProviderRepository: Send + Sync {
+    /// The error type returned by the repository
     type Error;
 
     /// Lookup an upstream OAuth provider by its ID
+    ///
+    /// Returns `None` if the provider was not found
+    ///
+    /// # Parameters
+    ///
+    /// * `id`: The ID of the provider to lookup
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn lookup(&mut self, id: Ulid) -> Result<Option<UpstreamOAuthProvider>, Self::Error>;
 
     /// Add a new upstream OAuth provider
+    ///
+    /// Returns the newly created provider
+    ///
+    /// # Parameters
+    ///
+    /// * `rng`: A random number generator
+    /// * `clock`: The clock used to generate timestamps
+    /// * `issuer`: The OIDC issuer of the provider
+    /// * `scope`: The scope to request during the authorization flow
+    /// * `token_endpoint_auth_method`: The token endpoint authentication method
+    /// * `token_endpoint_auth_signing_alg`: The JWT signing algorithm to use
+    ///   when then `client_secret_jwt` or `private_key_jwt` authentication
+    ///   methods are used
+    /// * `client_id`: The client ID to use when authenticating to the upstream
+    /// * `encrypted_client_secret`: The encrypted client secret to use when
+    ///   authenticating to the upstream
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     #[allow(clippy::too_many_arguments)]
     async fn add(
         &mut self,
@@ -43,12 +76,24 @@ pub trait UpstreamOAuthProviderRepository: Send + Sync {
     ) -> Result<UpstreamOAuthProvider, Self::Error>;
 
     /// Get a paginated list of upstream OAuth providers
+    ///
+    /// # Parameters
+    ///
+    /// * `pagination`: The pagination parameters
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn list_paginated(
         &mut self,
         pagination: Pagination,
     ) -> Result<Page<UpstreamOAuthProvider>, Self::Error>;
 
     /// Get all upstream OAuth providers
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn all(&mut self) -> Result<Vec<UpstreamOAuthProvider>, Self::Error>;
 }
 

crates/storage/src/upstream_oauth2/session.rs

@@ -19,17 +19,48 @@ use ulid::Ulid;
 
 use crate::{repository_impl, Clock};
 
+/// An [`UpstreamOAuthSessionRepository`] helps interacting with
+/// [`UpstreamOAuthAuthorizationSession`] saved in the storage backend
 #[async_trait]
 pub trait UpstreamOAuthSessionRepository: Send + Sync {
+    /// The error type returned by the repository
     type Error;
 
     /// Lookup a session by its ID
+    ///
+    /// Returns `None` if the session does not exist
+    ///
+    /// # Parameters
+    ///
+    /// * `id`: the ID of the session to lookup
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn lookup(
         &mut self,
         id: Ulid,
     ) -> Result<Option<UpstreamOAuthAuthorizationSession>, Self::Error>;
 
     /// Add a session to the database
+    ///
+    /// Returns the newly created session
+    ///
+    /// # Parameters
+    ///
+    /// * `rng`: the random number generator to use
+    /// * `clock`: the clock source
+    /// * `upstream_oauth_provider`: the upstream OAuth provider for which to
+    ///   create the session
+    /// * `state`: the authorization grant `state` parameter sent to the
+    ///   upstream OAuth provider
+    /// * `code_challenge_verifier`: the code challenge verifier used in this
+    ///   session, if PKCE is being used
+    /// * `nonce`: the `nonce` used in this session
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn add(
         &mut self,
         rng: &mut (dyn RngCore + Send),
@@ -41,6 +72,20 @@ pub trait UpstreamOAuthSessionRepository: Send + Sync {
     ) -> Result<UpstreamOAuthAuthorizationSession, Self::Error>;
 
     /// Mark a session as completed and associate the given link
+    ///
+    /// Returns the updated session
+    ///
+    /// # Parameters
+    ///
+    /// * `clock`: the clock source
+    /// * `upstream_oauth_authorization_session`: the session to update
+    /// * `upstream_oauth_link`: the link to associate with the session
+    /// * `id_token`: the ID token returned by the upstream OAuth provider, if
+    ///   present
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn complete_with_link(
         &mut self,
         clock: &dyn Clock,
@@ -50,6 +95,17 @@ pub trait UpstreamOAuthSessionRepository: Send + Sync {
     ) -> Result<UpstreamOAuthAuthorizationSession, Self::Error>;
 
     /// Mark a session as consumed
+    ///
+    /// Returns the updated session
+    ///
+    /// # Parameters
+    ///
+    /// * `clock`: the clock source
+    /// * `upstream_oauth_authorization_session`: the session to consume
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Self::Error`] if the underlying repository fails
     async fn consume(
         &mut self,
         clock: &dyn Clock,