feat: add support for Dgraph connection strings (#268)

matthewmcneely · web-flow · commit ad5391898f2b · 2025-04-04T22:47:46.000+05:30
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.0/),
 
+## [XX.X.X] - 2025-XX-XX
+
+**Added**
+
+- add support for Dgraph connection strings (#268)
+
 ## [24.1.1] - 2024-12-13
 
 **Added**
diff --git a/README.md b/README.md
@@ -169,6 +169,47 @@ client and use it to mutate or query dgraph. For the async client, more details
 
 ### Creating a Client
 
+#### Using a Connection String
+
+This library supports connecting to a Dgraph cluster using connection strings. Dgraph connections
+strings take the form `dgraph://{username:password@}host:port?args`.
+
+`username` and `password` are optional. If username is provided, a password must also be present. If
+supplied, these credentials are used to log into a Dgraph cluster through the ACL mechanism.
+
+Valid connection string args:
+
+| Arg         | Value                           | Description                                                                                                                                                   |
+| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| apikey      | \<key\>                         | a Dgraph Cloud API Key                                                                                                                                        |
+| bearertoken | \<token\>                       | an access token                                                                                                                                               |
+| sslmode     | disable \| require \| verify-ca | TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. |
+
+Note that using `sslmode=require` disables certificate validation and significantly reduces the
+security of TLS. This mode should only be used in non-production (e.g., testing or development)
+environments.
+
+Some example connection strings:
+
+| Value                                                                                                        | Explanation                                                                         |
+| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| dgraph://localhost:9080                                                                                      | Connect to localhost, no ACL, no TLS                                                |
+| dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca                                              | Connect to remote server, use ACL and require TLS and a valid certificate from a CA |
+| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\<your-api-connection-key\> | Connect to a Dgraph Cloud cluster                                                   |
+| dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=\<some access token\>                      | Connect to a Dgraph cluster protected by a secure gateway                           |
+
+Using the `DgraphClient.open` function with a connection string:
+
+```java
+// open a connection to an ACL-enabled, non-TLS cluster and login as groot
+DgraphClient client = DgraphClient.open("dgraph://groot:password@localhost:8090");
+
+// some time later...
+client.shutdown();
+```
+
+#### Using Managed Channels
+
 The following code snippet shows how to create a synchronous client using three connections.
 
 ```java
@@ -201,6 +242,8 @@ DgraphStub stub = DgraphClient.clientStubFromCloudEndpoint("https://your-instanc
 DgraphClient dgraphClient = new DgraphClient(stub);
 ```
 
+Note the `DgraphClient.open` method can be used if you have a Dgraph connection string (see above).
+
 ### Creating a Secure Client using TLS
 
 To setup a client using TLS, you could use the following code snippet. The server needs to be setup
diff --git a/src/main/java/io/dgraph/DgraphClient.java b/src/main/java/io/dgraph/DgraphClient.java
@@ -10,10 +10,20 @@
 import io.dgraph.DgraphProto.Version;
 import io.grpc.ManagedChannelBuilder;
 import io.grpc.Metadata;
+import io.grpc.netty.NettyChannelBuilder;
+import io.grpc.netty.GrpcSslContexts;
+import io.netty.handler.ssl.SslContext;
+import io.netty.handler.ssl.util.InsecureTrustManagerFactory;
 import io.grpc.stub.MetadataUtils;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.concurrent.Executor;
+import java.util.HashMap;
+import java.util.Map;
+import java.io.UnsupportedEncodingException;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+import javax.net.ssl.SSLException;
 
 /**
  * Implementation of a DgraphClient using grpc.
@@ -28,9 +38,301 @@
  */
 public class DgraphClient {
   private static final String gRPC_AUTHORIZATION_HEADER_NAME = "authorization";
+  private static final String DGRAPH_SCHEME = "dgraph";
+  private static final String SSLMODE_DISABLE = "disable";
+  private static final String SSLMODE_REQUIRE = "require";
+  private static final String SSLMODE_VERIFY_CA = "verify-ca";
 
   private final DgraphAsyncClient asyncClient;
 
+  /**
+   * Options for configuring a Dgraph client connection.
+   *
+   * <p>Example use:
+   * <pre>{@code
+   * DgraphClient client = DgraphClient.ClientOptions.forAddress("localhost", 9080)
+   *     .withACLCredentials("username", "password")
+   *     .withTLS()
+   *     .build();
+   * }</pre>
+   */
+  public static class ClientOptions {
+    private final ManagedChannelBuilder<?> channelBuilder;
+    private String username;
+    private String password;
+    private String authorizationToken;
+    private final String host;
+    private final int port;
+
+    private ClientOptions(String host, int port) {
+      this.host = host;
+      this.port = port;
+      this.channelBuilder = ManagedChannelBuilder.forAddress(host, port);
+      // Default to plaintext
+      this.channelBuilder.usePlaintext();
+    }
+
+    /**
+     * Creates a new ClientOptions instance for the given host and port.
+     *
+     * @param host The hostname of the Dgraph server.
+     * @param port The port of the Dgraph server.
+     * @return A new ClientOptions instance.
+     */
+    public static ClientOptions forAddress(String host, int port) {
+      return new ClientOptions(host, port);
+    }
+
+    /**
+     * Sets username and password for ACL authentication.
+     *
+     * @param username The username for ACL authentication.
+     * @param password The password for ACL authentication.
+     * @return This ClientOptions instance for chaining.
+     */
+    public ClientOptions withACLCredentials(String username, String password) {
+      this.username = username;
+      this.password = password;
+      return this;
+    }
+
+    /**
+     * Sets a Dgraph API key for authorization.
+     *
+     * @param apiKey The API key to use for authorization.
+     * @return This ClientOptions instance for chaining.
+     */
+    public ClientOptions withDgraphApiKey(String apiKey) {
+      this.authorizationToken = apiKey;
+      return this;
+    }
+
+    /**
+     * Sets a bearer token for authorization.
+     *
+     * @param token The bearer token to use for authorization.
+     * @return This ClientOptions instance for chaining.
+     */
+    public ClientOptions withBearerToken(String token) {
+      this.authorizationToken = "Bearer " + token;
+      return this;
+    }
+
+    /**
+     * Configures the client to use plaintext communication (no encryption).
+     *
+     * @return This ClientOptions instance for chaining.
+     */
+    public ClientOptions withPlaintext() {
+      this.channelBuilder.usePlaintext();
+      return this;
+    }
+
+    /**
+     * Configures the client to use TLS but skip certificate validation.
+     * Be aware this disables certificate validation and significantly reduces the
+     * security of TLS. This mode should only be used in non-production
+     * (e.g., testing or development) environments.
+     *
+     * @return A new ClientOptions instance with TLS but without certificate validation.
+     * @throws SSLException If there's an error configuring the SSL context.
+     */
+    public ClientOptions withTLSSkipVerify() throws SSLException {
+      SslContext sslContext = GrpcSslContexts.forClient()
+          .trustManager(InsecureTrustManagerFactory.INSTANCE)
+          .build();
+
+      // Create a new options object with the same credentials
+      ClientOptions newOptions = new ClientOptions(host, port) {
+        @Override
+        public DgraphGrpc.DgraphStub createStub() {
+          NettyChannelBuilder nettyBuilder = NettyChannelBuilder.forAddress(host, port);
+          nettyBuilder.sslContext(sslContext);
+          return DgraphGrpc.newStub(nettyBuilder.build());
+        }
+      };
+
+      // Copy over the auth settings
+      newOptions.username = this.username;
+      newOptions.password = this.password;
+      newOptions.authorizationToken = this.authorizationToken;
+      return newOptions;
+    }
+
+    /**
+     * Configures the client to use TLS with certificate validation.
+     *
+     * @return This ClientOptions instance for chaining.
+     */
+    public ClientOptions withTLS() {
+      this.channelBuilder.useTransportSecurity();
+      return this;
+    }
+
+    /**
+     * Creates the gRPC stub based on the channel builder.
+     * This method can be overridden by subclasses to customize stub creation.
+     */
+    protected DgraphGrpc.DgraphStub createStub() {
+      return DgraphGrpc.newStub(channelBuilder.build());
+    }
+
+    /**
+     * Creates a new DgraphClient with the configured options.
+     *
+     * @return A new DgraphClient instance.
+     */
+    public DgraphClient build() {
+      DgraphGrpc.DgraphStub stub = createStub();
+
+      if (authorizationToken != null) {
+        Metadata metadata = new Metadata();
+        metadata.put(
+            Metadata.Key.of(gRPC_AUTHORIZATION_HEADER_NAME, Metadata.ASCII_STRING_MARSHALLER),
+            authorizationToken);
+        stub = stub.withInterceptors(MetadataUtils.newAttachHeadersInterceptor(metadata));
+      }
+
+      DgraphClient client = new DgraphClient(stub);
+
+      if (username != null && password != null) {
+        client.login(username, password);
+      }
+
+      return client;
+    }
+  }
+
+  /**
+   * Parses query parameters from a URL.
+   *
+   * @param url The URL containing query parameters
+   * @return A map of parameter names to values
+   * @throws IllegalStateException If UTF-8 encoding is not supported by the JVM (should never happen)
+   */
+  private static Map<String, String> parseQueryParameters(URL url) {
+    Map<String, String> params = new HashMap<>();
+    if (url.getQuery() == null) {
+      return params;
+    }
+
+    String[] pairs = url.getQuery().split("&");
+    for (String pair : pairs) {
+      int idx = pair.indexOf("=");
+      if (idx > 0) {
+        try {
+          String key = URLDecoder.decode(pair.substring(0, idx), StandardCharsets.UTF_8.toString());
+          String value = URLDecoder.decode(pair.substring(idx + 1), StandardCharsets.UTF_8.toString());
+          params.put(key, value);
+        } catch (UnsupportedEncodingException e) {
+          throw new IllegalStateException("UTF-8 encoding not supported by the JVM", e);
+        }
+      }
+    }
+    return params;
+  }
+
+  /**
+   * Creates a new DgraphClient instance from a connection string.
+   *
+   * <p>This method attempts to authenticate via Dgraph's ACL mechanism if
+   * username and password are provided.
+   * <p>The connection string has the format: "dgraph://[username:password@]host:port[?params]"
+   * <p>Supported query parameters:
+   * <ul>
+   *   <li>sslmode - SSL connection mode. Supported values:
+   *     <ul>
+   *       <li>"disable" - No encryption, uses plaintext</li>
+   *       <li>"require" - Uses TLS encryption without certificate verification</li>
+   *       <li>"verify-ca" - Uses TLS encryption with certificate verification</li>
+   *     </ul>
+   *   </li>
+   *   <li>apikey - API key for authorization from Dgraph Cloud</li>
+   *   <li>bearertoken - Bearer token for authorization</li>
+   * </ul>
+   *
+   * @param connectionString The connection string to connect to Dgraph
+   * @return A new DgraphClient instance
+   * @throws IllegalArgumentException If the connection string is invalid
+   * @throws MalformedURLException If the connection string cannot be parsed as a URL
+   * @throws SSLException If there's an error configuring the SSL context for sslmode=require
+   * @throws IllegalStateException If UTF-8 encoding is not supported by the JVM (should never happen)
+   */
+  public static DgraphClient open(String connectionString)
+      throws IllegalArgumentException, MalformedURLException, SSLException, IllegalStateException {
+    if (connectionString == null || connectionString.isEmpty()) {
+      throw new IllegalArgumentException("Connection string cannot be null or empty");
+    }
+
+    // Connection string format: dgraph://[username:password@]host:port[?params]
+    if (!connectionString.startsWith(DGRAPH_SCHEME + "://")) {
+      throw new IllegalArgumentException("Invalid connection string: scheme must be '" + DGRAPH_SCHEME + "'");
+    }
+
+    URL url;
+    try {
+      // Replace dgraph:// with http:// for proper URL parsing
+      url = new URL(connectionString.replace(DGRAPH_SCHEME + "://", "http://"));
+    } catch (MalformedURLException e) {
+      throw new IllegalArgumentException("Failed to parse connection string: " + e.getMessage(), e);
+    }
+
+    String host = url.getHost();
+    int port = url.getPort();
+
+    if (host == null || host.isEmpty()) {
+      throw new IllegalArgumentException("Invalid connection string: hostname required");
+    }
+    if (port == -1) {
+      throw new IllegalArgumentException("Invalid connection string: port required");
+    }
+
+    ClientOptions options = ClientOptions.forAddress(host, port);
+
+    if (url.getUserInfo() != null) {
+      String[] userInfo = url.getUserInfo().split(":", 2);
+      String username = userInfo[0];
+      String password = null;
+      if (userInfo.length > 1) {
+        password = userInfo[1];
+      }
+      if (username != null && (password == null || password.isEmpty())) {
+        throw new IllegalArgumentException(
+            "Invalid connection string: password required when username is provided");
+      }
+      options.withACLCredentials(username, password);
+    }
+
+    Map<String, String> params = parseQueryParameters(url);
+
+    if (params.containsKey("sslmode")) {
+      String sslmode = params.get("sslmode");
+      if (SSLMODE_DISABLE.equals(sslmode)) {
+        options.withPlaintext();
+      } else if (SSLMODE_REQUIRE.equals(sslmode)) {
+        // This assignment is necessary to reassign the overridden createStub method
+        options = options.withTLSSkipVerify();
+      } else if (SSLMODE_VERIFY_CA.equals(sslmode)) {
+        options.withTLS();
+      } else {
+        throw new IllegalArgumentException("Invalid sslmode: " + sslmode);
+      }
+    }
+
+    if (params.containsKey("apikey") && params.containsKey("bearertoken")) {
+      throw new IllegalArgumentException(
+          "apikey and bearertoken cannot both be provided");
+    }
+
+    if (params.containsKey("apikey")) {
+      options.withDgraphApiKey(params.get("apikey"));
+    } else if (params.containsKey("bearertoken")) {
+      options.withBearerToken(params.get("bearertoken"));
+    }
+
+    return options.build();
+  }
+
   /**
    * Creates a gRPC stub that can be used to construct clients to connect with Slash GraphQL.
    *
diff --git a/src/test/java/io/dgraph/DgraphConnTest.java b/src/test/java/io/dgraph/DgraphConnTest.java
