chore: rename bearerToken flow to refreshToken internally

Document public and internal APIs.

Author: bevzzz

src/main/java/io/weaviate/client6/v1/api/Authorization.java

@@ -10,24 +10,63 @@
 public interface Authorization {
   TokenProvider getTokenProvider(RestTransport transport);
 
+  /**
+   * Authorize using a static API key.
+   *
+   * @param apiKey Weaviate API key.
+   */
   public static Authorization apiKey(String apiKey) {
     return __ -> TokenProvider.staticToken(apiKey);
   }
 
+  /**
+   * Authorize using an existing access_token + refresh_token
+   * pair.
+   *
+   * @param accessToken  Access token.
+   * @param refreshToken Refresh token.
+   * @param expiresIn    Remaining token lifetime in seconds.
+   *
+   * @return Authorization provider.
+   * @throws WeaviateOAuthException if an error occurred at any point of the
+   *                                exchange process.
+   */
   public static Authorization bearerToken(String accessToken, String refreshToken, long expiresIn) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);
       return TokenProvider.bearerToken(oidc, accessToken, refreshToken, expiresIn);
     };
   }
 
+  /**
+   * Authorize using Resource Owner Password authorization grant.
+   *
+   * @param username Resource owner username.
+   * @param password Resource owner password.
+   * @param scopes   Client scopes.
+   *
+   * @return Authorization provider.
+   * @throws WeaviateOAuthException if an error occured at any point of the token
+   *                                exchange process.
+   */
   public static Authorization resourceOwnerPassword(String username, String password, List<String> scopes) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);
       return TokenProvider.resourceOwnerPassword(oidc, username, password);
     };
   }
 
+  /**
+   * Authorize using Client Credentials authorization grant.
+   *
+   * @param clientId     Client ID.
+   * @param clientSecret Client secret.
+   * @param scopes       Client scopes.
+   *
+   * @return Authorization provider.
+   * @throws WeaviateOAuthException if an error occured at any point while
+   *                                obtaining a new token.
+   */
   public static Authorization clientCredentials(String clientId, String clientSecret, List<String> scopes) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);

src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java

@@ -2,6 +2,21 @@
 
 import io.weaviate.client6.v1.internal.oidc.OidcConfig;
 
+/**
+ * ExchangeTokenProvider obtains a new {@link Token} from "single-use"
+ * {@link TokenProvider}, usually one using an Resource Owner Password grant.
+ * It then creates a new internal TokenProvider to refresh the token each time
+ * {@link #getToken} is called.
+ *
+ * <p>
+ * Usage:
+ *
+ * <pre>{@code
+ * var initialGrant = TokenProvider.resourceOwnerPassword(oidc, username, password);
+ * var exchange = new ExchangeTokenProvider(oidc, initialGrant);
+ * var token = exchange.getToken();
+ * } </pre>
+ */
 class ExchangeTokenProvider implements TokenProvider {
   private final TokenProvider bearer;
 

src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java

@@ -5,6 +5,17 @@
 /**
  * ReuseTokenProvider returns the same token as long as its valid and obtains a
  * new token from a {@link TokenProvider} otherwise.
+ *
+ * <p>
+ * Usage:
+ *
+ * <pre>{@code
+ * // Create an TokenProvider that can rotate tokens as they expire.
+ * var myProvider = new MyTokenProvider();
+ *
+ * // Create a reusable TokenProvider.
+ * var tokenProvider = ReuseTokenProvider.wrap(myProvider);
+ * }</pre>
  */
 @ThreadSafe
 final class ReuseTokenProvider implements TokenProvider {

src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java

@@ -2,14 +2,21 @@
 
 import java.time.Instant;
 
+import io.weaviate.client6.v1.api.WeaviateOAuthException;
 import io.weaviate.client6.v1.internal.oidc.OidcConfig;
 import io.weaviate.client6.v1.internal.oidc.nimbus.NimbusTokenProvider;
 
+/** TokenProvider obtains authentication tokens. */
 @FunctionalInterface
 public interface TokenProvider {
   Token getToken();
 
+  /** Token represents an access_token + refresh_token pair. */
   public record Token(String accessToken, String refreshToken, Instant createdAt, long expiresIn) {
+    /**
+     * Returns {@code true} if remaining lifetime of the token is greater than 0.
+     * Tokens created with {@link #expireNever} are always valid.
+     */
     public boolean isValid() {
       if (expiresIn == -1) {
         return true;
@@ -18,17 +25,39 @@ public boolean isValid() {
       return Instant.now().isAfter(createdAt.plusSeconds(expiresIn));
     }
 
+    /**
+     * Create a token with an expiration and a refresh_token.
+     *
+     * @param accessToken  Access token.
+     * @param refreshToken Refresh token.
+     * @param expiresIn    Remaining token lifetime in seconds.
+     *
+     * @return A new Token.
+     */
     public static Token expireAfter(String accessToken, String refreshToken, long expiresIn) {
       return new Token(accessToken, refreshToken, Instant.now(), expiresIn);
     }
 
+    /**
+     * Create a token that does not have a refresh_token.
+     *
+     * @param accessToken Access token.
+     * @param expiresIn   Remaining token lifetime in seconds.
+     *
+     * @return A new Token.
+     */
     public static Token expireAfter(String accessToken, long expiresIn) {
       return expireAfter(accessToken, null, expiresIn);
     }
 
-    /** Create a token that never expires. */
+    /**
+     * Create a token that never expires.
+     *
+     * @param accessToken Access token.
+     * @return A new Token.
+     */
     public static Token expireNever(String accessToken) {
-      return Token.expireAfter(accessToken, "", -1);
+      return Token.expireAfter(accessToken, -1);
     }
   }
 
@@ -37,26 +66,68 @@ public static TokenProvider staticToken(String accessToken) {
     return () -> token;
   }
 
+  /**
+   * Create a TokenProvider that uses an existing access_token + refresh_token
+   * pair.
+   *
+   * @param oidc         OIDC config.
+   * @param accessToken  Access token.
+   * @param refreshToken Refresh token.
+   * @param expiresIn    Remaining token lifetime in seconds.
+   *
+   * @return Internal TokenProvider implementation.
+   * @throws WeaviateOAuthException if an error occurred at any point of the
+   *                                exchange process.
+   */
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
-    final var provider = NimbusTokenProvider.bearerToken(oidc, token);
+    final var provider = NimbusTokenProvider.refreshToken(oidc, token);
     return reuse(token, provider);
   }
 
+  /**
+   * Create a TokenProvider that uses Resource Owner Password authorization grant.
+   *
+   * @param oidc     OIDC config.
+   * @param username Resource owner username.
+   * @param password Resource owner password.
+   *
+   * @return Internal TokenProvider implementation.
+   * @throws WeaviateOAuthException if an error occured at any point of the token
+   *                                exchange process.
+   */
   public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
     final var passwordGrant = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
     return reuse(null, exchange(oidc, passwordGrant));
   }
 
+  /**
+   * Create a TokenProvider that uses Client Credentials authorization grant.
+   *
+   * @param oidc         OIDC config.
+   * @param clientId     Client ID.
+   * @param clientSecret Client secret.
+   *
+   * @return Internal TokenProvider implementation.
+   * @throws WeaviateOAuthException if an error occured at any point while
+   *                                obtaining a new token.
+   */
   public static TokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
     final var provider = NimbusTokenProvider.clientCredentials(oidc, clientId, clientSecret);
     return reuse(null, provider);
   }
 
+  /**
+   * Obtain a TokenProvider that exchanges an authorization grant for a new Token.
+   */
   static TokenProvider exchange(OidcConfig oidc, TokenProvider tp) {
     return new ExchangeTokenProvider(oidc, tp);
   }
 
+  /**
+   * Obtain a TokenProvider which reuses tokens obtained
+   * from another TokenProvider until they expire.
+   */
   static TokenProvider reuse(Token t, TokenProvider tp) {
     return ReuseTokenProvider.wrap(t, tp);
   }

src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java

@@ -18,8 +18,8 @@ default ClientAuthentication getClientAuthentication() {
     return null;
   }
 
-  static Flow bearerToken(Token t) {
-    return new BearerTokenFlow(t);
+  static Flow refreshToken(Token t) {
+    return new RefreshTokenFlow(t);
   }
 
   static Flow resourceOwnerPassword(String username, String password) {

src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java

@@ -26,14 +26,46 @@ public final class NimbusTokenProvider implements TokenProvider {
   private final String redirectUrl;
   private final Flow flow;
 
-  public static NimbusTokenProvider bearerToken(OidcConfig oidc, Token t) {
-    return new NimbusTokenProvider(oidc, Flow.bearerToken(t));
+  /**
+   * Create a TokenProvider that uses Refresh Token authorization grant.
+   *
+   * @param oidc OIDC config.
+   * @param t    Current token. Must not be null.
+   *
+   * @return A new instance of NimbusTokenProvider. Instances are never cached.
+   * @throws WeaviateOAuthException if an error occurred at any point of the
+   *                                exchange process.
+   */
+  public static NimbusTokenProvider refreshToken(OidcConfig oidc, Token t) {
+    return new NimbusTokenProvider(oidc, Flow.refreshToken(t));
   }
 
+  /**
+   * Create a TokenProvider that uses Resource Owner Password authorization grant.
+   *
+   * @param oidc     OIDC config.
+   * @param username Resource owner username.
+   * @param password Resource owner password.
+   *
+   * @return A new instance of NimbusTokenProvider. Instances are never cached.
+   * @throws WeaviateOAuthException if an error occured at any point of the
+   *                                exchange process.
+   */
   public static NimbusTokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
     return new NimbusTokenProvider(oidc, Flow.resourceOwnerPassword(username, password));
   }
 
+  /**
+   * Create a TokenProvider that uses Client Credentials authorization grant.
+   *
+   * @param oidc         OIDC config.
+   * @param clientId     Client ID.
+   * @param clientSecret Client secret.
+   *
+   * @return A new instance of NimbusTokenProvider. Instances are never cached.
+   * @throws WeaviateOAuthException if an error occured at any point of the
+   *                                exchange process.
+   */
   public static NimbusTokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
     return new NimbusTokenProvider(oidc, Flow.clientCredentials(clientId, clientSecret));
   }

…nternal/oidc/nimbus/BearerTokenFlow.java …ternal/oidc/nimbus/RefreshTokenFlow.javasrc/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java renamed to src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java renamed to src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java

@@ -8,11 +8,17 @@
 
 import io.weaviate.client6.v1.internal.TokenProvider.Token;
 
+/**
+ * RefreshTokenFlow provides {@link RefreshTokenGrant} with a refresh_token.
+ * Once the caller has obtained a new {@link Token} it must be updated using
+ * {@link #setToken} to ensure RefreshTokenFlow continues to return valid
+ * authorization grants.
+ */
 @NotThreadSafe
-final class BearerTokenFlow implements Flow {
+final class RefreshTokenFlow implements Flow {
   private Token t;
 
-  BearerTokenFlow(Token t) {
+  RefreshTokenFlow(Token t) {
     this.t = t;
   }