From 8d798e6b7bd5850354724c76c457859e2970712b Mon Sep 17 00:00:00 2001
From: Alexander Korolev <alexander.korolev.germany@gmail.com>
Date: Thu, 5 Sep 2024 23:33:58 +0200
Subject: [PATCH] review: docs, fmt and error type fix

---
 src/client.rs | 55 +++++++++++++++++++++++++++++++++++----------------
 1 file changed, 38 insertions(+), 17 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index ee405e7..347583d 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -1,7 +1,10 @@
 use crate::{
     bearer::TemporalBearerGuard,
     discovered,
-    error::{ClientError, Decode, Error, Introspection as ErrorIntrospection, Jose, Userinfo as ErrorUserinfo},
+    error::{
+        ClientError, Decode, Error, Introspection as ErrorIntrospection, Jose,
+        Userinfo as ErrorUserinfo,
+    },
     standard_claims_subject::StandardClaimsSubject,
     validation::{
         validate_token_aud, validate_token_exp, validate_token_issuer, validate_token_nonce,
@@ -434,7 +437,23 @@ impl<C: CompactJson + Claims, P: Provider + Configurable> Client<P, C> {
         }
     }
 
-    pub async fn request_token_introspection<I>(&self, token: &Token<C>) -> Result<TokenIntrospection<I>, Error>
+    /// Get a token introspection json document for a given token at the provider's token introspection endpoint.
+    /// Returns [Token Introspection Response](https://datatracker.ietf.org/doc/html/rfc7662#section-2.2)
+    /// as [TokenIntrospection] struct.
+    ///
+    /// # Errors
+    ///
+    /// - [Error::Http] if something goes wrong getting the document
+    /// - [Error::Insecure] if the token introspection url is not https
+    /// - [Error::Json] if the response is not a valid TokenIntrospection document
+    /// - [ErrorIntrospection::MissingContentType] if content-type header is missing
+    /// - [ErrorIntrospection::NoUrl] if this provider doesn't have a token introspection endpoint
+    /// - [ErrorIntrospection::ParseContentType] if content-type header is not parsable
+    /// - [ErrorIntrospection::WrongContentType] if content-type header is not accepted
+    pub async fn request_token_introspection<I>(
+        &self,
+        token: &Token<C>,
+    ) -> Result<TokenIntrospection<I>, Error>
     where
         I: CompactJson,
     {
@@ -474,22 +493,24 @@ impl<C: CompactJson + Claims, P: Provider + Configurable> Client<P, C> {
                     })?,
                 };
 
-                let info: TokenIntrospection<I> = match (mime_type.type_(), mime_type.subtype().as_str()) {
-                    (mime::APPLICATION, "json") => {
-                        let info_value: Value = response.json().await?;
-                        if info_value.get("error").is_some() {
-                            let oauth2_error: OAuth2Error = serde_json::from_value(info_value)?;
-                            return Err(Error::ClientError(oauth2_error.into()));
+                let info: TokenIntrospection<I> =
+                    match (mime_type.type_(), mime_type.subtype().as_str()) {
+                        (mime::APPLICATION, "json") => {
+                            let info_value: Value = response.json().await?;
+                            if info_value.get("error").is_some() {
+                                let oauth2_error: OAuth2Error = serde_json::from_value(info_value)?;
+                                return Err(Error::ClientError(oauth2_error.into()));
+                            }
+                            serde_json::from_value(info_value)?
                         }
-                        serde_json::from_value(info_value)?
-                    }
-                    _ => {
-                        return Err(ErrorUserinfo::WrongContentType {
-                            content_type: content_type.to_string(),
-                            body: response.bytes().await?.to_vec(),
-                        }.into())
-                    }
-                };
+                        _ => {
+                            return Err(ErrorIntrospection::WrongContentType {
+                                content_type: content_type.to_string(),
+                                body: response.bytes().await?.to_vec(),
+                            }
+                            .into())
+                        }
+                    };
 
                 Ok(info)
             }