Add examples for load balanced connection creation in V2 (#538)

Author: jwierzbo

v2/connection/endpoints_maglev_hash.go

@@ -33,7 +33,9 @@ import (
 // RequestHashValueExtractor accepts request method and full request path and must return a value which will be used for hash calculation
 type RequestHashValueExtractor func(requestMethod, requestPath string) (string, error)
 
-// NewMaglevHashEndpoints returns Endpoint manager which runs round-robin
+// NewMaglevHashEndpoints returns Endpoint manager which consistently returns the same endpoint based on value
+// extracted from request using provided RequestHashValueExtractor
+// e.g. if you want to use DB name from URL for hashing you can use RequestDBNameValueExtractor
 func NewMaglevHashEndpoints(eps []string, extractor RequestHashValueExtractor) (Endpoint, error) {
 	// order of endpoints affects hashing result
 	sort.Strings(eps)

v2/examples/example_client_async_test.go

@@ -30,9 +30,12 @@ import (
 	"github.com/arangodb/go-driver/v2/connection"
 )
 
+// ExampleNewConnectionAsyncWrapper shows how to create a connection wrapper for async requests
+// It lets use async requests on demand
 func ExampleNewConnectionAsyncWrapper() {
 	// Create an HTTP connection to the database
-	conn := connection.NewHttpConnection(exampleJSONHTTPConnectionConfig())
+	endpoint := connection.NewRoundRobinEndpoints([]string{"http://localhost:8529"})
+	conn := connection.NewHttpConnection(exampleJSONHTTPConnectionConfig(endpoint))
 
 	// Create ASYNC wrapper for the connection
 	conn = connection.NewConnectionAsyncWrapper(conn)

v2/examples/example_client_test.go renamed to v2/examples/example_client_basic_test.go

@@ -32,9 +32,11 @@ import (
 	"github.com/arangodb/go-driver/v2/connection"
 )
 
+// ExampleNewClient shows how to create the simple client with a single endpoint
 func ExampleNewClient() {
 	// Create an HTTP connection to the database
-	conn := connection.NewHttpConnection(exampleJSONHTTPConnectionConfig())
+	endpoint := connection.NewRoundRobinEndpoints([]string{"http://localhost:8529"})
+	conn := connection.NewHttpConnection(exampleJSONHTTPConnectionConfig(endpoint))
 
 	// Create a client
 	client := arangodb.NewClient(conn)
@@ -48,9 +50,9 @@ func ExampleNewClient() {
 	}
 }
 
-func exampleJSONHTTPConnectionConfig() connection.HttpConfiguration {
+func exampleJSONHTTPConnectionConfig(endpoint connection.Endpoint) connection.HttpConfiguration {
 	return connection.HttpConfiguration{
-		Endpoint:    connection.NewEndpoints("http://localhost:8529"),
+		Endpoint:    endpoint,
 		ContentType: connection.ApplicationJSON,
 		Transport: &http.Transport{
 			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},

v2/examples/example_client_maglev_test.go

@@ -0,0 +1,55 @@
+//
+// DISCLAIMER
+//
+// Copyright 2023 ArangoDB GmbH, Cologne, Germany
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Copyright holder is ArangoDB GmbH, Cologne, Germany
+//
+
+package examples
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/arangodb/go-driver/v2/arangodb"
+	"github.com/arangodb/go-driver/v2/connection"
+)
+
+// ExampleNewMaglevHashEndpoints shows how to create a new MaglevHashEndpoints
+// It lets use different endpoints for different databases by using a RequestDBNameValueExtractor function.
+// E.g.:
+// - all requests to _db/<db-name-1> will use endpoint 1
+// - all requests to _db/<db-name-2> will use endpoint 2
+func ExampleNewMaglevHashEndpoints() {
+	// Create an HTTP connection to the database
+	endpoints, err := connection.NewMaglevHashEndpoints(
+		[]string{"https://a:8529", "https://a:8539", "https://b:8529"},
+		connection.RequestDBNameValueExtractor,
+	)
+
+	conn := connection.NewHttpConnection(exampleJSONHTTPConnectionConfig(endpoints))
+
+	// Create a client
+	client := arangodb.NewClient(conn)
+
+	// Ask the version of the server
+	versionInfo, err := client.Version(context.Background())
+	if err != nil {
+		fmt.Printf("Failed to get version info: %v", err)
+	} else {
+		fmt.Printf("Database has version '%s' and license '%s'\n", versionInfo.Version, versionInfo.License)
+	}
+}

v2/examples/example_client_roundrobin_test.go

@@ -0,0 +1,47 @@
+//
+// DISCLAIMER
+//
+// Copyright 2023 ArangoDB GmbH, Cologne, Germany
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Copyright holder is ArangoDB GmbH, Cologne, Germany
+//
+
+package examples
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/arangodb/go-driver/v2/arangodb"
+	"github.com/arangodb/go-driver/v2/connection"
+)
+
+// ExampleNewRoundRobinEndpoints shows how to create a client with round-robin endpoint list
+func ExampleNewRoundRobinEndpoints() {
+	// Create an HTTP connection to the database
+	endpoints := connection.NewRoundRobinEndpoints([]string{"https://a:8529", "https://a:8539", "https://b:8529"})
+	conn := connection.NewHttpConnection(exampleJSONHTTPConnectionConfig(endpoints))
+
+	// Create a client
+	client := arangodb.NewClient(conn)
+
+	// Ask the version of the server
+	versionInfo, err := client.Version(context.Background())
+	if err != nil {
+		fmt.Printf("Failed to get version info: %v", err)
+	} else {
+		fmt.Printf("Database has version '%s' and license '%s'\n", versionInfo.Version, versionInfo.License)
+	}
+}

v2/tests/run_wrap_test.go

@@ -232,7 +232,7 @@ func waitForConnection(t testing.TB, client arangodb.Client) arangodb.Client {
 
 				// pick the first one endpoint which is always the leader in AF mode
 				// also for Cluster mode we only need one endpoint to avoid the problem with the data propagation in tests
-				endpoint := connection.NewEndpoints(connection.FixupEndpointURLScheme(cer.Endpoints[nextEndpoint].Endpoint))
+				endpoint := connection.NewRoundRobinEndpoints([]string{connection.FixupEndpointURLScheme(cer.Endpoints[nextEndpoint].Endpoint)})
 				err = client.Connection().SetEndpoint(endpoint)
 				if err != nil {
 					log.Warn().Err(err).Msgf("Unable to set endpoints")
@@ -282,7 +282,6 @@ func connectionJsonHttp(t testing.TB) connection.Connection {
 			DialContext: (&net.Dialer{
 				Timeout:   30 * time.Second,
 				KeepAlive: 90 * time.Second,
-				DualStack: true,
 			}).DialContext,
 			MaxIdleConns:          100,
 			IdleConnTimeout:       90 * time.Second,
@@ -308,7 +307,6 @@ func connectionVPACKHttp(t testing.TB) connection.Connection {
 			DialContext: (&net.Dialer{
 				Timeout:   30 * time.Second,
 				KeepAlive: 90 * time.Second,
-				DualStack: true,
 			}).DialContext,
 			MaxIdleConns:          100,
 			IdleConnTimeout:       90 * time.Second,