Added some documentation to OAuth2Client and IOAuth2Client

Author: Lyphion

projects/RabbitMQ.Client.OAuth2/IOAuth2Client.cs

@@ -36,7 +36,19 @@ namespace RabbitMQ.Client.OAuth2
 {
     public interface IOAuth2Client
     {
+        /// <summary>
+        /// Request a new AccessToken from the Token Endpoint.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for this request</param>
+        /// <returns>Token with Access and Refresh Token</returns>
         Task<IToken> RequestTokenAsync(CancellationToken cancellationToken = default);
+        
+        /// <summary>
+        /// Request a new AccessToken using the Refresh Token from the Token Endpoint.
+        /// </summary>
+        /// <param name="token">Token with the Refresh Token</param>
+        /// <param name="cancellationToken">Cancellation token for this request</param>
+        /// <returns>Token with Access and Refresh Token</returns>
         Task<IToken> RefreshTokenAsync(IToken token, CancellationToken cancellationToken = default);
     }
 }

projects/RabbitMQ.Client.OAuth2/OAuth2Client.cs

@@ -42,7 +42,9 @@ namespace RabbitMQ.Client.OAuth2
 {
     public class OAuth2ClientBuilder
     {
-        /// <summary>Discovery endpoint subpath for all OpenID Connect issuers.</summary>
+        /// <summary>
+        /// Discovery endpoint subpath for all OpenID Connect issuers.
+        /// </summary>
         const string DISCOVERY_ENDPOINT = ".well-known/openid-configuration";
 
         private readonly string _clientId;
@@ -56,30 +58,53 @@ public class OAuth2ClientBuilder
         private IDictionary<string, string>? _additionalRequestParameters;
         private HttpClientHandler? _httpClientHandler;
 
+        /// <summary>
+        /// Create a new builder for creating <see cref="OAuth2Client"/>s.
+        /// </summary>
+        /// <param name="clientId">Id of the client</param>
+        /// <param name="clientSecret">Secret of the client</param>
+        /// <param name="tokenEndpoint">Endpoint to receive the Access Token</param>
+        /// <param name="issuer">Issuer of the Access Token. Used to automaticly receive the Token Endpoint while building</param>
+        /// <remarks>
+        /// Either <paramref name="tokenEndpoint"/> or <paramref name="issuer"/> must be provided.
+        /// </remarks>
         public OAuth2ClientBuilder(string clientId, string clientSecret, Uri? tokenEndpoint = null, Uri? issuer = null)
         {
             _clientId = clientId ?? throw new ArgumentNullException(nameof(clientId));
             _clientSecret = clientSecret ?? throw new ArgumentNullException(nameof(clientSecret));
 
             if (tokenEndpoint is null && issuer is null)
-                throw new ArgumentException("Either token endpoint or issuer is required");
+                throw new ArgumentException("Either tokenEndpoint or issuer is required");
 
             _tokenEndpoint = tokenEndpoint;
             _issuer = issuer;
         }
 
+        /// <summary>
+        /// Set the requested scopes for the client.
+        /// </summary>
+        /// <param name="scope">OAuth scopes to request from the Issuer</param>
         public OAuth2ClientBuilder SetScope(string scope)
         {
             _scope = scope ?? throw new ArgumentNullException(nameof(scope));
             return this;
         }
 
+        /// <summary>
+        /// Set custom HTTP Client handler for requests of the OAuth2 client.
+        /// </summary>
+        /// <param name="handler">Custom handler for HTTP requests</param>
         public OAuth2ClientBuilder SetHttpClientHandler(HttpClientHandler handler)
         {
             _httpClientHandler = handler ?? throw new ArgumentNullException(nameof(handler));
             return this;
         }
 
+        /// <summary>
+        /// Add a additional request parameter to each HTTP request.
+        /// </summary>
+        /// <param name="param">Name of the parameter</param>
+        /// <param name="paramValue">Value of the parameter</param>
         public OAuth2ClientBuilder AddRequestParameter(string param, string paramValue)
         {
             if (param is null)
@@ -98,8 +123,13 @@ public OAuth2ClientBuilder AddRequestParameter(string param, string paramValue)
             return this;
         }
 
+        /// <summary>
+        /// Build the <see cref="OAuth2Client"/> with the provided properties of the builder.
+        /// </summary>
+        /// <returns>Configured OAuth2Client</returns>
         public IOAuth2Client Build()
         {
+            // Check if Token Endpoint is missing -> Use Issuer to receive Token Endpoint
             if (_tokenEndpoint is null)
             {
                 // Don't know how to better handle backwards compatibily
@@ -111,8 +141,14 @@ public IOAuth2Client Build()
                 _scope, _additionalRequestParameters, _httpClientHandler);
         }
 
+        /// <summary>
+        /// Build the <see cref="OAuth2Client"/> with the provided properties of the builder.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for this method</param>
+        /// <returns>Configured OAuth2Client</returns>
         public async ValueTask<IOAuth2Client> BuildAsync(CancellationToken cancellationToken = default)
         {
+            // Check if Token Endpoint is missing -> Use Issuer to receive Token Endpoint
             if (_tokenEndpoint is null)
             {
                 Uri tokenEndpoint = await GetTokenEndpointFromIssuerAsync(cancellationToken).ConfigureAwait(false);
@@ -124,6 +160,11 @@ public async ValueTask<IOAuth2Client> BuildAsync(CancellationToken cancellationT
                 _scope, _additionalRequestParameters, _httpClientHandler);
         }
 
+        /// <summary>
+        /// Receive Token Endpoint from discovery page of the Issuer.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for this request</param>
+        /// <returns>Uri of the Token Endpoint</returns>
         private async Task<Uri> GetTokenEndpointFromIssuerAsync(CancellationToken cancellationToken = default)
         {
             if (_issuer is null)
@@ -155,10 +196,8 @@ private async Task<Uri> GetTokenEndpointFromIssuerAsync(CancellationToken cancel
             {
                 throw new InvalidOperationException("No token endpoint was found");
             }
-            else
-            {
-                return new Uri(discovery.TokenEndpoint);
-            }
+
+            return new Uri(discovery.TokenEndpoint);
         }
     }
 
@@ -198,19 +237,15 @@ public OAuth2Client(string clientId, string clientSecret, Uri tokenEndpoint,
             _additionalRequestParameters = additionalRequestParameters ?? EMPTY;
             _tokenEndpoint = tokenEndpoint;
 
-            if (httpClientHandler is null)
-            {
-                _httpClient = new HttpClient();
-            }
-            else
-            {
-                _httpClient = new HttpClient(httpClientHandler, false);
-            }
+            _httpClient = httpClientHandler is null 
+                ? new HttpClient() 
+                : new HttpClient(httpClientHandler, false);
 
             _httpClient.DefaultRequestHeaders.Accept.Clear();
             _httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
         }
 
+        /// <inheritdoc />
         public async Task<IToken> RequestTokenAsync(CancellationToken cancellationToken = default)
         {
             using HttpRequestMessage req = new HttpRequestMessage(HttpMethod.Post, _tokenEndpoint);
@@ -229,12 +264,11 @@ public async Task<IToken> RequestTokenAsync(CancellationToken cancellationToken
                 // TODO specific exception?
                 throw new InvalidOperationException("token is null");
             }
-            else
-            {
-                return new Token(token);
-            }
+
+            return new Token(token);
         }
 
+        /// <inheritdoc />
         public async Task<IToken> RefreshTokenAsync(IToken token,
             CancellationToken cancellationToken = default)
         {
@@ -259,10 +293,8 @@ public async Task<IToken> RefreshTokenAsync(IToken token,
                 // TODO specific exception?
                 throw new InvalidOperationException("refreshed token is null");
             }
-            else
-            {
-                return new Token(refreshedToken);
-            }
+
+            return new Token(refreshedToken);
         }
 
         public void Dispose()
@@ -291,8 +323,7 @@ private Dictionary<string, string> BuildRequestParameters()
         private Dictionary<string, string> BuildRefreshParameters(IToken token)
         {
             Dictionary<string, string> dict = BuildRequestParameters();
-            dict.Remove(GRANT_TYPE);
-            dict.Add(GRANT_TYPE, REFRESH_TOKEN);
+            dict[GRANT_TYPE] = REFRESH_TOKEN;
 
             if (_scope != null)
             {
@@ -349,6 +380,9 @@ public long ExpiresIn
         }
     }
 
+    /// <summary>
+    /// Minimal version of the properties of the discovery endpoint.
+    /// </summary>
     internal class OpenIDConnectDiscovery
     {
         public OpenIDConnectDiscovery()