add docs

Author: kanat

src/main/java/io/getstream/chat/java/services/framework/UserCall.java

@@ -5,45 +5,104 @@
 
 import java.io.IOException;
 
+/**
+ * Wrapper for Retrofit {@code Call} objects that injects user authentication tokens.
+ * <p>
+ * This class delegates all {@code Call} operations to an underlying call while ensuring
+ * that the {@link UserToken} is attached to the request as a typed tag. The token can
+ * then be retrieved by OkHttp interceptors for adding authorization headers.
+ * </p>
+ *
+ * @param <T> the response body type
+ * @see UserToken
+ * @see UserTokenCallRewriter
+ */
 class UserCall<T> implements retrofit2.Call<T> {
   private final retrofit2.Call<T> delegate;
   private final UserToken token;
 
+  /**
+   * Constructs a new UserCall that wraps the provided call with token injection.
+   *
+   * @param delegate the underlying Retrofit call
+   * @param token the user token to inject
+   */
   UserCall(retrofit2.Call<T> delegate, UserToken token) {
     this.delegate = delegate;
     this.token = token;
   }
 
+  /**
+   * Executes the HTTP request synchronously.
+   *
+   * @return the response
+   * @throws IOException if the request fails
+   */
   @Override
   public @NotNull retrofit2.Response<T> execute() throws IOException {
     return delegate.execute();
   }
 
+  /**
+   * Asynchronously sends the request and notifies the callback of its response.
+   *
+   * @param callback the callback to notify when the response arrives
+   */
   @Override
   public void enqueue(@NotNull retrofit2.Callback<T> callback) {
     delegate.enqueue(callback);
   }
 
+  /**
+   * Returns true if this call has been executed.
+   *
+   * @return true if executed, false otherwise
+   */
   @Override
   public boolean isExecuted() {
     return delegate.isExecuted();
   }
 
+  /**
+   * Cancels the request, if possible.
+   */
   @Override
   public void cancel() {
     delegate.cancel();
   }
 
+  /**
+   * Returns true if this call has been canceled.
+   *
+   * @return true if canceled, false otherwise
+   */
   @Override
   public boolean isCanceled() {
     return delegate.isCanceled();
   }
 
+  /**
+   * Creates a new, identical call that can be executed independently.
+   * <p>
+   * The cloned call will also have the user token injected.
+   * </p>
+   *
+   * @return a new call instance
+   */
   @Override
   public @NotNull retrofit2.Call<T> clone() {
     return new UserCall<>(delegate.clone(), token);
   }
 
+  /**
+   * Returns the original HTTP request with the user token attached as a typed tag.
+   * <p>
+   * The token is stored using {@link Request#tag(Class, Object)} and can be retrieved
+   * by interceptors using {@code request.tag(UserToken.class)}.
+   * </p>
+   *
+   * @return the request with the user token tag
+   */
   @Override
   public @NotNull Request request() {
     Request original = delegate.request();
@@ -52,6 +111,11 @@ public boolean isCanceled() {
         .build();
   }
 
+  /**
+   * Returns the timeout for this call.
+   *
+   * @return the timeout
+   */
   @Override
   public @NotNull okio.Timeout timeout() {
     return delegate.timeout();

src/main/java/io/getstream/chat/java/services/framework/UserClient.java

@@ -4,31 +4,70 @@
 
 import java.time.Duration;
 
+/**
+ * Client implementation for user-scoped API operations.
+ * <p>
+ * This client wraps a base {@link Client} and automatically injects a user-specific
+ * authentication token into all service calls. It's designed for scenarios where
+ * different users need to make authenticated API calls without creating separate
+ * client instances per user.
+ * </p>
+ *
+ * @see Client
+ */
 public final class UserClient implements Client {
 
     private final Client delegate;
     private final String userToken;
 
+    /**
+     * Constructs a new UserClient that wraps the provided client with user authentication.
+     *
+     * @param delegate the base client to delegate calls to
+     * @param userToken the user-specific authentication token to inject into requests
+     */
     public UserClient(Client delegate, String userToken) {
         this.delegate = delegate;
         this.userToken = userToken;
     }
 
+    /**
+     * Creates a service proxy that automatically injects the user token into all requests.
+     *
+     * @param svcClass the service interface class
+     * @param <TService> the service type
+     * @return a proxy instance of the service with user token injection
+     */
     @Override
     public <TService> @NotNull TService create(Class<TService> svcClass) {
         return delegate.create(svcClass, userToken);
     }
 
+    /**
+     * Returns the API key from the underlying client.
+     *
+     * @return the API key
+     */
     @Override
     public @NotNull String getApiKey() {
         return delegate.getApiKey();
     }
 
+    /**
+     * Returns the API secret from the underlying client.
+     *
+     * @return the API secret
+     */
     @Override
     public @NotNull String getApiSecret() {
         return delegate.getApiSecret();
     }
 
+    /**
+     * Sets the request timeout duration on the underlying client.
+     *
+     * @param timeoutDuration the timeout duration to set
+     */
     @Override
     public void setTimeout(@NotNull Duration timeoutDuration) {
         delegate.setTimeout(timeoutDuration);

src/main/java/io/getstream/chat/java/services/framework/UserServiceFactory.java

@@ -1,7 +1,29 @@
 package io.getstream.chat.java.services.framework;
 
+/**
+ * Factory interface for creating service instances with user-specific authentication.
+ * <p>
+ * Implementations of this interface are responsible for creating Retrofit service
+ * proxies that inject the provided {@link UserToken} into API requests. This enables
+ * per-user authentication without requiring separate HTTP client instances.
+ * </p>
+ * <p>
+ * Package-private to control instantiation within the framework.
+ * </p>
+ *
+ * @see UserToken
+ * @see UserTokenCallRewriter
+ */
 interface UserServiceFactory {
 
+  /**
+   * Creates a service instance that injects the specified user token into all requests.
+   *
+   * @param svcClass the service interface class to create
+   * @param userToken the user token to inject into requests
+   * @param <TService> the service interface type
+   * @return a proxy instance of the service with token injection capabilities
+   */
   <TService> TService create(Class<TService> svcClass, UserToken userToken);
 
 }

src/main/java/io/getstream/chat/java/services/framework/UserServiceFactoryProxy.java

@@ -12,15 +12,6 @@
  * <p>
  * <b>Mechanism:</b> Uses Java reflection {@link java.lang.reflect.Proxy} to wrap the service
  * interface and inject user tokens at method invocation time.
- * <p>
- * <b>Trade-offs:</b>
- * <ul>
- *   <li>Pros: Reuses single Retrofit instance, flexible interception point</li>
- *   <li>Cons: Reflection overhead on every method call, slightly more complex debugging</li>
- * </ul>
- * <p>
- * <b>Thread-safety:</b> Immutable and thread-safe once constructed. The underlying proxy
- * delegation is also thread-safe.
  *
  * @see UserTokenCallRewriter
  */

src/main/java/io/getstream/chat/java/services/framework/UserServiceFactorySelector.java

@@ -5,20 +5,9 @@
 
 /**
  * Smart user-aware service factory with automatic fallback mechanism.
- * <p>
+ * 
  * This implementation attempts to use {@link UserServiceFactoryProxy} (more efficient)
- * and automatically falls back to {@link UserServiceFactoryTagging} if reflection fails
- * or the Retrofit API has changed.
- * <p>
- * <b>Fallback Strategy:</b>
- * <ol>
- *   <li>First attempt: Use proxy-based approach (reuses Retrofit instance)</li>
- *   <li>On failure: Switch to tagging-based approach (more compatible)</li>
- *   <li>Once switched: All subsequent calls use the fallback implementation</li>
- * </ol>
- * <p>
- * <b>Thread-safety:</b> Thread-safe. Uses atomic reference for fallback state tracking.
- * Multiple threads may attempt fallback simultaneously, but only one will win.
+ * and automatically falls back to {@link UserServiceFactoryTagging} if the proxy approach fails.
  */
 final class UserServiceFactorySelector implements UserServiceFactory {
 

src/main/java/io/getstream/chat/java/services/framework/UserServiceFactoryTagging.java

@@ -8,17 +8,11 @@
  * <p>
  * This implementation wraps the OkHttp call factory to automatically attach a {@link UserToken}
  * as a request tag. The token can then be retrieved by interceptors for authentication purposes.
+ * </p>
  * <p>
  * <b>Mechanism:</b> Creates a new Retrofit instance with a custom call factory that tags
  * each request before delegating to the underlying call factory.
- * <p>
- * <b>Trade-offs:</b>
- * <ul>
- *   <li>Pros: Clean, type-safe, works with any Retrofit service, no reflection overhead</li>
- *   <li>Cons: Creates a new Retrofit instance per service call (minor memory overhead)</li>
- * </ul>
- * <p>
- * <b>Thread-safety:</b> Immutable and thread-safe once constructed.
+ * </p>
  */
 final class UserServiceFactoryTagging implements UserServiceFactory {
 

src/main/java/io/getstream/chat/java/services/framework/UserToken.java

@@ -1,12 +1,33 @@
 package io.getstream.chat.java.services.framework;
 
+/**
+ * Immutable wrapper for a user authentication token.
+ * <p>
+ * This class encapsulates a user token string that is injected into HTTP requests
+ * for per-user authentication in multi-tenant scenarios. The token is stored as a
+ * request tag and retrieved by interceptors for adding authorization headers.
+ * </p>
+ * <p>
+ * Package-private to prevent direct instantiation outside the framework.
+ * </p>
+ */
 final class UserToken {
   private final String value;
 
+  /**
+   * Constructs a new UserToken with the specified value.
+   *
+   * @param value the token string value
+   */
   UserToken(String value) {
     this.value = value;
   }
 
+  /**
+   * Returns the token string value.
+   *
+   * @return the token string
+   */
   String value() {
     return value;
   }

src/main/java/io/getstream/chat/java/services/framework/UserTokenCallRewriter.java

@@ -9,25 +9,57 @@
 import java.lang.reflect.Method;
 
 /**
- * Dynamic proxy that intercepts Retrofit service calls and injects UserToken
- * into the request by modifying the internal rawCall field via reflection.
- * 
- * This approach allows per-call authentication without creating multiple OkHttpClient
- * instances, making it suitable for multi-tenant systems with thousands of users.
+ * Dynamic proxy that intercepts Retrofit service calls and injects {@link UserToken}
+ * into requests for per-user authentication.
+ * <p>
+ * This class uses Java reflection to modify Retrofit's internal {@code Call} objects,
+ * injecting a {@link UserToken} as a request tag. The token is then retrieved by
+ * OkHttp interceptors to add authentication headers.
+ * </p>
+ *
+ * @param <TService> the service interface type being proxied
+ * @see UserToken
+ * @see UserServiceFactory
  */
 class UserTokenCallRewriter<TService> implements InvocationHandler {
+  /**
+   * Cached reference to Retrofit's internal rawCall field.
+   * Uses double-checked locking for thread-safe lazy initialization.
+   */
   private static volatile Field rawCallField;
 
   private final Call.Factory callFactory;
   private final TService delegate;
   private final UserToken token;
 
+  /**
+   * Constructs a new call rewriter that injects the specified token.
+   *
+   * @param callFactory the OkHttp call factory for creating modified calls
+   * @param delegate the original service implementation to proxy
+   * @param token the user token to inject into requests
+   */
   UserTokenCallRewriter(@NotNull Call.Factory callFactory, @NotNull TService delegate, @NotNull UserToken token) {
     this.callFactory = callFactory;
     this.delegate = delegate;
     this.token = token;
   }
 
+  /**
+   * Intercepts service method invocations to inject the user token.
+   * <p>
+   * This method ensures that all service methods return {@code retrofit2.Call<?>}
+   * objects. If a method returns a different type, a {@link TokenInjectionException}
+   * is thrown.
+   * </p>
+   *
+   * @param proxy the proxy instance
+   * @param method the method being invoked
+   * @param args the method arguments
+   * @return the modified Call with token injection
+   * @throws Throwable if the underlying method throws an exception
+   * @throws TokenInjectionException if the method doesn't return retrofit2.Call<?>
+   */
   @Override
   public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
     Object result = method.invoke(delegate, args);
@@ -43,6 +75,17 @@ public Object invoke(Object proxy, Method method, Object[] args) throws Throwabl
       " did not return retrofit2.Call<?>. User token injection requires all service methods to return Call<?>.");
   }
 
+  /**
+   * Injects the user token into a Retrofit call by modifying its internal OkHttp call.
+   * <p>
+   * The token is added as a request tag of type {@link UserToken}, which can be
+   * retrieved by OkHttp interceptors for authentication purposes.
+   * </p>
+   *
+   * @param originalCall the original Retrofit call
+   * @return a cloned call with the user token injected
+   * @throws TokenInjectionException if reflection fails or Retrofit's structure has changed
+   */
   private retrofit2.Call<?> injectTokenIntoCall(retrofit2.Call<?> originalCall) throws TokenInjectionException {
     retrofit2.Call<?> clonedCall = originalCall.clone();