feat: check connection to cluster when creating a new client

1) Ping /live endpoint once we have the RestTransport
but before the client is fully initialized. If the
instance is not reachable, close the existing resouces
and throw a WeaviateConnectException.

The user can catch that earlier in their application,
e.g. at startup, not when they send the first request.

2) Renamed connection helper methods:
- local -> connectToLocal
- wcd -> connectToWeaviateCloud
- custom -> connectToCustom

Author: bevzzz

src/it/java/io/weaviate/containers/Weaviate.java

@@ -78,7 +78,7 @@ public WeaviateClient getNewClient(Function<Config.Custom, ObjectBuilder<Config>
             .grpcHost(host)
             .httpPort(getMappedPort(8080))
             .grpcPort(getMappedPort(50051)));
-    return WeaviateClient.custom(customFn);
+    return WeaviateClient.connectToCustom(customFn);
   }
 
   public static Weaviate createDefault() {

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

@@ -1,9 +1,9 @@
 package io.weaviate.client6.v1.api;
 
 /**
- * Exception class thrown by client API message when the request's reached the
- * server, but the operation did not complete successfully either either due to
- * a bad request or a server error.
+ * Exception class thrown by client when the request had reached the
+ * server, but the operation did not complete successfully either
+ * due to a bad request or a server error.
  */
 public class WeaviateApiException extends WeaviateException {
   private final String errorMessage;

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

@@ -32,8 +32,6 @@ public class WeaviateClient implements AutoCloseable {
   public final WeaviateAliasClient alias;
 
   public WeaviateClient(Config config) {
-    this.config = config;
-
     RestTransportOptions restOpt;
     GrpcChannelOptions grpcOpt;
     if (config.authentication() == null) {
@@ -52,11 +50,33 @@ public WeaviateClient(Config config) {
       grpcOpt = config.grpcTransportOptions(tokenProvider);
     }
 
-    this.restTransport = new DefaultRestTransport(restOpt);
-    this.grpcTransport = new DefaultGrpcTransport(grpcOpt);
+    // Initialize REST transport to a temporary variable to dispose of
+    // the associated resources in case we have to throw an exception.
+    // Assign to this.restTransport only once we're in the clear to
+    // avoid publishing the object before it's fully initialized.
+    var _restTransport = new DefaultRestTransport(restOpt);
+    boolean isLive = false;
+    try {
+      isLive = _restTransport.performRequest(null, IsLiveRequest._ENDPOINT);
+    } catch (IOException e) {
+      throw new WeaviateConnectException(e);
+    }
+
+    if (!isLive) {
+      var ex = new WeaviateConnectException("Weaviate not available at " + restOpt.baseUrl());
+      try {
+        _restTransport.close();
+      } catch (Exception e) {
+        ex.addSuppressed(e);
+      }
+      throw ex;
+    }
 
+    this.restTransport = _restTransport;
+    this.grpcTransport = new DefaultGrpcTransport(grpcOpt);
     this.alias = new WeaviateAliasClient(restTransport);
     this.collections = new WeaviateCollectionsClient(restTransport, grpcTransport);
+    this.config = config;
   }
 
   /**
@@ -77,7 +97,7 @@ public WeaviateClient(Config config) {
    * Example:
    *
    * <pre>{@code
-   * var client = WeaviateClient.local();
+   * var client = WeaviateClient.connectToLocal();
    *
    * // Need to make the next request non-blocking
    * try (final var async = client.async()) {
@@ -92,9 +112,9 @@ public WeaviateClient(Config config) {
    * If you only intend to use {@link WeaviateClientAsync}, prefer creating it
    * directly via one of its static factories:
    * <ul>
-   * <li>{@link WeaviateClientAsync#local}
-   * <li>{@link WeaviateClientAsync#wcd}
-   * <li>{@link WeaviateClientAsync#custom}
+   * <li>{@link WeaviateClientAsync#connectToLocal}
+   * <li>{@link WeaviateClientAsync#connectToWeaviateCloud}
+   * <li>{@link WeaviateClientAsync#connectToCustom}
    * </ul>
    *
    * Otherwise the client wastes time initializing resources it will never use.
@@ -104,29 +124,29 @@ public WeaviateClientAsync async() {
   }
 
   /** Connect to a local Weaviate instance. */
-  public static WeaviateClient local() {
-    return local(ObjectBuilder.identity());
+  public static WeaviateClient connectToLocal() {
+    return connectToLocal(ObjectBuilder.identity());
   }
 
   /** Connect to a local Weaviate instance. */
-  public static WeaviateClient local(Function<Config.Local, ObjectBuilder<Config>> fn) {
+  public static WeaviateClient connectToLocal(Function<Config.Local, ObjectBuilder<Config>> fn) {
     return new WeaviateClient(fn.apply(new Config.Local()).build());
   }
 
   /** Connect to a Weaviate Cloud instance. */
-  public static WeaviateClient wcd(String httpHost, String apiKey) {
-    return wcd(httpHost, apiKey, ObjectBuilder.identity());
+  public static WeaviateClient connectToWeaviateCloud(String httpHost, String apiKey) {
+    return connectToWeaviateCloud(httpHost, apiKey, ObjectBuilder.identity());
   }
 
   /** Connect to a Weaviate Cloud instance. */
-  public static WeaviateClient wcd(String httpHost, String apiKey,
+  public static WeaviateClient connectToWeaviateCloud(String httpHost, String apiKey,
       Function<Config.WeaviateCloud, ObjectBuilder<Config>> fn) {
     var config = new Config.WeaviateCloud(httpHost, Authentication.apiKey(apiKey));
     return new WeaviateClient(fn.apply(config).build());
   }
 
   /** Connect to a Weaviate instance with custom configuration. */
-  public static WeaviateClient custom(Function<Config.Custom, ObjectBuilder<Config>> fn) {
+  public static WeaviateClient connectToCustom(Function<Config.Custom, ObjectBuilder<Config>> fn) {
     return new WeaviateClient(fn.apply(new Config.Custom()).build());
   }
 

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

@@ -45,17 +45,38 @@ public WeaviateClientAsync(Config config) {
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
         tokenProvider = config.authentication().getTokenProvider(noAuthRest);
       } catch (Exception e) {
-        // Generally IOExceptions are caught in TokenProvider internals.
+        // Generally exceptions are caught in TokenProvider internals.
         // This one may be thrown when noAuthRest transport is auto-closed.
         throw new WeaviateOAuthException(e);
       }
       restOpt = config.restTransportOptions(tokenProvider);
       grpcOpt = config.grpcTransportOptions(tokenProvider);
     }
 
-    this.restTransport = new DefaultRestTransport(restOpt);
-    this.grpcTransport = new DefaultGrpcTransport(grpcOpt);
+    // Initialize REST transport to a temporary variable to dispose of
+    // the associated resources in case we have to throw an exception.
+    // Assign to this.restTransport only once we're in the clear to
+    // avoid publishing the object before it's fully initialized.
+    var _restTransport = new DefaultRestTransport(restOpt);
+    boolean isLive = false;
+    try {
+      isLive = _restTransport.performRequest(null, IsLiveRequest._ENDPOINT);
+    } catch (IOException e) {
+      throw new WeaviateConnectException(e);
+    }
 
+    if (!isLive) {
+      var ex = new WeaviateConnectException("Weaviate not available at " + restOpt.baseUrl());
+      try {
+        _restTransport.close();
+      } catch (Exception e) {
+        ex.addSuppressed(e);
+      }
+      throw ex;
+    }
+
+    this.restTransport = _restTransport;
+    this.grpcTransport = new DefaultGrpcTransport(grpcOpt);
     this.alias = new WeaviateAliasClientAsync(restTransport);
     this.collections = new WeaviateCollectionsClientAsync(restTransport, grpcTransport);
   }
@@ -67,8 +88,8 @@ public WeaviateClientAsync(Config config) {
    * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
-  public static WeaviateClientAsync local() {
-    return local(ObjectBuilder.identity());
+  public static WeaviateClientAsync connectToLocal() {
+    return connectToLocal(ObjectBuilder.identity());
   }
 
   /**
@@ -78,7 +99,7 @@ public static WeaviateClientAsync local() {
    * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
-  public static WeaviateClientAsync local(Function<Config.Local, ObjectBuilder<Config>> fn) {
+  public static WeaviateClientAsync connectToLocal(Function<Config.Local, ObjectBuilder<Config>> fn) {
     return new WeaviateClientAsync(fn.apply(new Config.Local()).build());
   }
 
@@ -89,8 +110,8 @@ public static WeaviateClientAsync local(Function<Config.Local, ObjectBuilder<Con
    * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
-  public static WeaviateClientAsync wcd(String httpHost, String apiKey) {
-    return wcd(httpHost, apiKey, ObjectBuilder.identity());
+  public static WeaviateClientAsync connectToWeaviateCloud(String httpHost, String apiKey) {
+    return connectToWeaviateCloud(httpHost, apiKey, ObjectBuilder.identity());
   }
 
   /**
@@ -100,7 +121,7 @@ public static WeaviateClientAsync wcd(String httpHost, String apiKey) {
    * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
-  public static WeaviateClientAsync wcd(String httpHost, String apiKey,
+  public static WeaviateClientAsync connectToWeaviateCloud(String httpHost, String apiKey,
       Function<Config.WeaviateCloud, ObjectBuilder<Config>> fn) {
     var config = new Config.WeaviateCloud(httpHost, Authentication.apiKey(apiKey));
     return new WeaviateClientAsync(fn.apply(config).build());
@@ -113,7 +134,7 @@ public static WeaviateClientAsync wcd(String httpHost, String apiKey,
    * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
-  public static WeaviateClientAsync custom(Function<Config.Custom, ObjectBuilder<Config>> fn) {
+  public static WeaviateClientAsync connectToCustom(Function<Config.Custom, ObjectBuilder<Config>> fn) {
     return new WeaviateClientAsync(Config.of(fn));
   }
 

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

@@ -0,0 +1,16 @@
+package io.weaviate.client6.v1.api;
+
+/** Exception thrown if the Weaviate instance appears to be offline. */
+public class WeaviateConnectException extends WeaviateException {
+  public WeaviateConnectException(String message) {
+    super(message);
+  }
+
+  public WeaviateConnectException(String message, Throwable cause) {
+    super(message, cause);
+  }
+
+  public WeaviateConnectException(Throwable cause) {
+    super(cause);
+  }
+}

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

@@ -1,9 +1,8 @@
 package io.weaviate.client6.v1.api;
 
 /**
- * Exception class thrown by client API message when the request's reached the
- * server, but the operation did not complete successfully either either due to
- * a bad request or a server error.
+ * Exception throws by the authentication layer if it encountered another
+ * exception at any point of obtaining the new token or rotating one.
  */
 public class WeaviateOAuthException extends WeaviateException {
   public WeaviateOAuthException(String message) {

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

@@ -0,0 +1,16 @@
+package io.weaviate.client6.v1.api;
+
+/** Exception thrown by the internal transport layer. Usually not retryable. */
+public class WeaviateTransportException extends WeaviateException {
+  public WeaviateTransportException(String message) {
+    super(message);
+  }
+
+  public WeaviateTransportException(String message, Throwable cause) {
+    super(message, cause);
+  }
+
+  public WeaviateTransportException(Throwable cause) {
+    super(cause);
+  }
+}

src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java

@@ -28,6 +28,7 @@
 import org.apache.hc.core5.io.CloseMode;
 
 import io.weaviate.client6.v1.api.WeaviateApiException;
+import io.weaviate.client6.v1.api.WeaviateTransportException;
 
 public class DefaultRestTransport implements RestTransport {
   private final CloseableHttpClient httpClient;
@@ -53,8 +54,7 @@ public DefaultRestTransport(RestTransportOptions transportOptions) {
         sslCtx.init(null, transportOptions.trustManagerFactory().getTrustManagers(), null);
         tlsStrategy = new DefaultClientTlsStrategy(sslCtx);
       } catch (NoSuchAlgorithmException | KeyManagementException e) {
-        // todo: throw WeaviateConnectionException
-        throw new RuntimeException("connect to Weaviate", e);
+        throw new WeaviateTransportException("init custom SSL context", e);
       }
 
       PoolingHttpClientConnectionManager syncManager = PoolingHttpClientConnectionManagerBuilder.create()
@@ -96,7 +96,6 @@ private <RequestT, ResponseT> ClassicHttpRequest prepareClassicRequest(RequestT
     var method = endpoint.method(request);
     var uri = uri(endpoint, request);
 
-    // TODO: apply options;
     var req = ClassicRequestBuilder.create(method).setUri(uri);
     var body = endpoint.body(request);
     if (body != null) {
@@ -180,8 +179,7 @@ private <ResponseT> ResponseT _handleResponse(Endpoint<?, ResponseT> endpoint, S
       return (ResponseT) ((Boolean) bool.getResult(statusCode));
     }
 
-    // TODO: make it a WeaviateTransportException
-    throw new RuntimeException("Unhandled endpoint type " + endpoint.getClass().getSimpleName());
+    throw new WeaviateTransportException("Unhandled endpoint type " + endpoint.getClass().getSimpleName());
   }
 
   @Override

src/test/java/io/weaviate/client6/v1/api/WeaviateClientAsyncTest.java

@@ -0,0 +1,29 @@
+package io.weaviate.client6.v1.api;
+
+import org.junit.Test;
+
+public class WeaviateClientAsyncTest {
+
+  @SuppressWarnings("resource")
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection() {
+    var config = new Config.Local();
+    config.host("localhost").port(1234);
+    new WeaviateClientAsync(config.build());
+  }
+
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection_Local() {
+    WeaviateClientAsync.connectToLocal();
+  }
+
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection_WeaviateCloud() {
+    WeaviateClientAsync.connectToWeaviateCloud("no-cluster.io", "no-key");
+  }
+
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection_Custom() {
+    WeaviateClient.connectToCustom(conn -> conn.httpHost("localhost").httpPort(1234));
+  }
+}

src/test/java/io/weaviate/client6/v1/api/WeaviateClientTest.java

@@ -0,0 +1,29 @@
+package io.weaviate.client6.v1.api;
+
+import org.junit.Test;
+
+public class WeaviateClientTest {
+
+  @SuppressWarnings("resource")
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection() {
+    var config = new Config.Local();
+    config.host("localhost").port(1234);
+    new WeaviateClient(config.build());
+  }
+
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection_Local() {
+    WeaviateClient.connectToLocal();
+  }
+
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection_WeaviateCloud() {
+    WeaviateClient.connectToWeaviateCloud("no-cluster.io", "no-key");
+  }
+
+  @Test(expected = WeaviateConnectException.class)
+  public void testFailedConnection_Custom() {
+    WeaviateClient.connectToCustom(conn -> conn.httpHost("localhost").httpPort(1234));
+  }
+}