Polishing

Author: gthea

http-domain/README.md

@@ -1,5 +1,100 @@
 # HTTP Domain module
 
-This module contains public HTTP configuration contracts exposed to consumers of the Split SDK.
+Public contracts and configuration types for the HTTP client.
+These types are exposed to SDK consumers through the `:main` module's `api` dependency.
 
-Includes certificate pinning configuration, proxy settings, SSL configuration, and authenticator interfaces.
+## `HttpClientConfiguration`
+
+Bundles all HTTP client settings into a single object:
+
+```java
+HttpClientConfiguration config = HttpClientConfiguration.builder()
+        .connectionTimeout(15_000)
+        .readTimeout(15_000)
+        .proxy(proxy)
+        .proxyAuthenticator(authenticator)
+        .certificatePinningConfiguration(pinConfig)
+        .developmentSslConfig(devSsl)
+        .build();
+```
+
+## Proxy configuration
+
+### Basic auth
+
+```java
+HttpProxy proxy = HttpProxy.newBuilder("proxy.example.com", 8080)
+        .basicAuth("user", "pass")
+        .build();
+```
+
+### mTLS with custom CA
+
+```java
+HttpProxy proxy = HttpProxy.newBuilder("proxy.example.com", 8443)
+        .proxyCacert(caCertInputStream)
+        .mtls(clientCertInputStream, clientKeyInputStream)
+        .build();
+```
+
+### Custom credentials provider
+
+```java
+// Bearer token
+HttpProxy proxy = HttpProxy.newBuilder("proxy.example.com", 8080)
+        .credentialsProvider(() -> fetchBearerToken())
+        .build();
+
+// Basic credentials
+HttpProxy proxy = HttpProxy.newBuilder("proxy.example.com", 8080)
+        .credentialsProvider(new BasicCredentialsProvider() {
+            public String getUsername() { return "user"; }
+            public String getPassword() { return "pass"; }
+        })
+        .build();
+```
+
+## Custom proxy authenticator
+
+Implement `SplitAuthenticator` to handle proxy challenge/response flows:
+
+```java
+SplitAuthenticator authenticator = new SplitAuthenticator() {
+    @Override
+    public AuthenticatedRequest authenticate(@NonNull AuthenticatedRequest request) {
+        request.setHeader("Proxy-Authorization", "Bearer " + getToken());
+        return request;
+    }
+};
+```
+
+The `AuthenticatedRequest` gives access to existing headers and the request URL, so the authenticator can make decisions based on context.
+
+## Certificate pinning
+
+```java
+CertificatePinningConfiguration pinConfig = CertificatePinningConfiguration.builder()
+        // Pin by hash (sha256 or sha1)
+        .addPin("sdk.split.io", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
+        // Pin from a certificate file (derives hashes automatically)
+        .addPin("*.split.io", certInputStream)
+        // Optional: get notified on pin failures
+        .failureListener((host, certificateChain) -> {
+            Log.w("Split", "Pin failed for " + host
+                    + ", chain size: " + certificateChain.size());
+        })
+        .build();
+```
+
+Wildcard hosts are supported: `*.example.com` matches one subdomain, `**.example.com` matches any depth.
+
+## Development SSL overrides
+
+For test environments with self-signed certificates:
+
+```java
+DevelopmentSslConfig devSsl = new DevelopmentSslConfig(trustManager, hostnameVerifier);
+
+// Or, if you already have an SSLSocketFactory:
+DevelopmentSslConfig devSsl = new DevelopmentSslConfig(sslSocketFactory, trustManager, hostnameVerifier);
+```

http-domain/src/main/java/io/split/android/client/network/Algorithm.java

@@ -1,6 +1,6 @@
 package io.split.android.client.network;
 
-public class Algorithm {
+class Algorithm {
 
     public static final String SHA256 = "sha256";
     public static final String SHA1 = "sha1";

http-domain/src/main/java/io/split/android/client/network/Base64Decoder.java

@@ -1,6 +1,6 @@
 package io.split.android.client.network;
 
-public interface Base64Decoder {
+interface Base64Decoder {
 
     byte[] decode(String base64);
 }

http-domain/src/main/java/io/split/android/client/network/CertificateCheckerHelper.java

@@ -15,7 +15,7 @@
 
 import io.split.android.client.utils.logger.Logger;
 
-public class CertificateCheckerHelper {
+class CertificateCheckerHelper {
 
     @Nullable
     public static Set<CertificatePin> getPinsForHost(String pattern, Map<String, Set<CertificatePin>> configuredPins) {

http-domain/src/main/java/io/split/android/client/network/DefaultBase64Decoder.java

@@ -4,7 +4,7 @@
 
 import io.split.android.client.utils.logger.Logger;
 
-public class DefaultBase64Decoder implements Base64Decoder {
+class DefaultBase64Decoder implements Base64Decoder {
 
     @Override
     public byte[] decode(String base64) {

http-domain/src/main/java/io/split/android/client/network/PinEncoder.java

@@ -2,7 +2,7 @@
 
 import androidx.annotation.NonNull;
 
-public interface PinEncoder {
+interface PinEncoder {
 
     @NonNull
     byte[] encodeCertPin(String algorithm, byte[] encodedPublicKey);

http-domain/src/main/java/io/split/android/client/network/PinEncoderImpl.java

@@ -7,7 +7,7 @@
 
 import io.split.android.client.utils.logger.Logger;
 
-public class PinEncoderImpl implements PinEncoder {
+class PinEncoderImpl implements PinEncoder {
 
     @Override
     @NonNull

http/README.md

@@ -1,30 +1,100 @@
 # HTTP module
 
-Internal HTTP client for the Split SDK. Not exposed to SDK consumers.
+HTTP client for the Split SDK.
 
 ## Building an `HttpClient`
 
-Use `HttpClientImpl.Builder` to create an instance:
+### Minimal
 
 ```java
 HttpClient client = new HttpClientImpl.Builder()
         .setConnectionTimeout(15_000)
         .setReadTimeout(15_000)
-        .setTlsUpdater(tlsUpdater)                       // optional – TlsUpdater SPI
-        .setProxy(httpProxy)                              // optional – proxy config from :http-domain
-        .setProxyAuthenticator(authenticator)              // optional – SplitAuthenticator from :http-domain
-        .setCertificatePinningConfiguration(pinConfig)     // optional – cert pins from :http-domain
-        .setDevelopmentSslConfig(devSslConfig)             // optional – dev/test SSL overrides
         .build();
 ```
 
+### With `HttpClientConfiguration` (preferred)
+
+Bundle all settings into a single config object from `:http-domain`:
+
+```java
+HttpClientConfiguration config = HttpClientConfiguration.builder()
+        .connectionTimeout(15_000)
+        .readTimeout(15_000)
+        .proxy(proxy)                                       // optional
+        .proxyAuthenticator(authenticator)                   // optional
+        .certificatePinningConfiguration(pinConfig)          // optional
+        .developmentSslConfig(devSsl)                        // optional
+        .build();
+
+HttpClient client = new HttpClientImpl.Builder()
+        .setConfiguration(config)
+        .setTlsUpdater(tlsUpdater)  // optional – TlsUpdater
+        .build();
+```
+
+Individual setter calls on the builder take precedence over the configuration object.
+
+### Proxy
+
+```java
+// Basic auth proxy
+HttpProxy proxy = HttpProxy.newBuilder("proxy.example.com", 8080)
+        .basicAuth("user", "pass")
+        .build();
+
+// mTLS proxy with custom CA
+HttpProxy mtlsProxy = HttpProxy.newBuilder("proxy.example.com", 8443)
+        .proxyCacert(caCertInputStream)
+        .mtls(clientCertInputStream, clientKeyInputStream)
+        .build();
+
+// With a credentials provider (e.g. bearer token)
+HttpProxy bearerProxy = HttpProxy.newBuilder("proxy.example.com", 8080)
+        .credentialsProvider(new BearerCredentialsProvider(tokenSupplier))
+        .build();
+```
+
+### Certificate pinning
+
+```java
+CertificatePinningConfiguration pinConfig = CertificatePinningConfiguration.builder()
+        .addPin("sdk.split.io", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
+        .addPin("*.split.io", certInputStream)   // derive pins from a certificate file
+        .failureListener(failedHost -> {
+            Log.w("Split", "Certificate pinning failed for " + failedHost);
+        })
+        .build();
+```
+
+### Development SSL overrides
+
+For test environments where the server uses a self-signed certificate:
+
+```java
+DevelopmentSslConfig devSsl = new DevelopmentSslConfig(trustManager, hostnameVerifier);
+```
+
+### TLS on older devices
+
+Implement the `TlsUpdater` SPI and pass it to the builder.
+The client calls `couldBeOld()` to decide whether to force TLS 1.2 via `Tls12OnlySocketFactory`.
+
+```java
+TlsUpdater tlsUpdater = new LegacyTlsUpdaterAdapter(context); // provided by :main
+```
+
 ## Making requests
 
 ```java
 // Simple GET
 HttpRequest req = client.request(uri, HttpMethod.GET);
 HttpResponse resp = req.execute();
 
+// POST with body
+HttpRequest post = client.request(uri, HttpMethod.POST, jsonBody);
+HttpResponse resp = post.execute();
+
 // POST with body and extra headers
 HttpRequest post = client.request(uri, HttpMethod.POST, jsonBody, extraHeaders);
 HttpResponse resp = post.execute();
@@ -42,17 +112,13 @@ client.addHeaders(commonHeaders);
 
 // Streaming-specific headers (only applied to streamRequest calls)
 client.setStreamingHeader("SplitSDKClientKey", clientKey);
+client.addStreamingHeaders(streamingHeaders);
 ```
 
-## TLS on older devices
-
-Implement the `TlsUpdater` SPI and pass it to the builder. The client calls `couldBeOld()` to decide whether to force TLS 1.2 via `Tls12OnlySocketFactory`.
-
 ## URI building
 
 ```java
-URI uri = new URIBuilder("https://sdk.split.io/api")
-        .addPath("splitChanges")
+URI uri = new URIBuilder(new URI("https://sdk.split.io/api"), "splitChanges")
         .addParameter("since", "-1")
         .build();
 ```

http/src/main/java/io/split/android/client/network/HttpClientImpl.java

@@ -202,6 +202,8 @@ public static class Builder {
         private CertificatePinningConfiguration mCertificatePinningConfiguration;
         private CertificateChecker mCertificateChecker;
         private Base64Decoder mBase64Decoder = new DefaultBase64Decoder();
+        @Nullable
+        private HttpClientConfiguration mConfiguration;
 
         public Builder setTlsUpdater(@Nullable TlsUpdater tlsUpdater) {
             mTlsUpdater = tlsUpdater;
@@ -263,7 +265,16 @@ Builder setBase64Decoder(Base64Decoder base64Decoder) {
             return this;
         }
 
+        public Builder setConfiguration(@NonNull HttpClientConfiguration configuration) {
+            mConfiguration = configuration;
+            return this;
+        }
+
         public HttpClient build() {
+            if (mConfiguration != null) {
+                applyConfiguration(mConfiguration);
+            }
+
             if (mDevelopmentSslConfig == null) {
                 if (mTlsUpdater != null && mTlsUpdater.couldBeOld()) {
                     mTlsUpdater.update();
@@ -310,6 +321,27 @@ public HttpClient build() {
                     certificateChecker);
         }
 
+        private void applyConfiguration(@NonNull HttpClientConfiguration configuration) {
+            if (mConnectionTimeout == -1) {
+                setConnectionTimeout(configuration.getConnectionTimeout());
+            }
+            if (mReadTimeout == -1) {
+                setReadTimeout(configuration.getReadTimeout());
+            }
+            if (mProxy == null && configuration.getProxy() != null) {
+                setProxy(configuration.getProxy());
+            }
+            if (mCertificatePinningConfiguration == null && configuration.getCertificatePinningConfiguration() != null) {
+                setCertificatePinningConfiguration(configuration.getCertificatePinningConfiguration());
+            }
+            if (mDevelopmentSslConfig == null) {
+                setDevelopmentSslConfig(configuration.getDevelopmentSslConfig());
+            }
+            if (mProxyAuthenticator == null) {
+                setProxyAuthenticator(configuration.getProxyAuthenticator());
+            }
+        }
+
         private SSLSocketFactory createSslSocketFactoryFromProxy(HttpProxy proxyParams) {
             ProxySslSocketFactoryProviderImpl factoryProvider = new ProxySslSocketFactoryProviderImpl(mBase64Decoder);
             try {

http/src/main/java/io/split/android/client/network/HttpRequestImpl.java

@@ -31,7 +31,7 @@
 
 import io.split.android.client.utils.logger.Logger;
 
-public class HttpRequestImpl implements HttpRequest {
+class HttpRequestImpl implements HttpRequest {
 
     public static final String CONTENT_TYPE = "Content-Type";
     public static final String APPLICATION_JSON_CHARSET_UTF_8 = "application/json; charset=utf-8";