Examples: Extending the client APIs

Author: karmi

_examples/README.md

@@ -25,6 +25,11 @@ The [**`fasthttp`**](./fasthttp) directory contains a demonstration of replacing
 
 The [**`instrumentation`**](./instrumentation) directory contains recipes for instrumenting the client with the OpenCensus and Elastic APM packages.
 
+## Extension
+
+The [**`extension`**](./extension) directory contains an example of extending the client APIs, for example
+to support custom endpoints installed by a plugin.
+
 ## Google Cloud Functions
 
 The [**`cloudfunction`**](./cloudfunction) directory contains a simple web service for checking Elasticsearch cluster status.

_examples/extension/Makefile

@@ -0,0 +1,6 @@
+GO_TEST_CMD = $(if $(shell which richgo),richgo test,go test)
+
+test:  ## Run tests
+	go run main.go
+
+.PHONY: test

_examples/extension/README.md

@@ -0,0 +1,17 @@
+# Example: Extending the Client
+
+This example demonstrates how to extend the client, in order to call custom APIs, for example added by a [plugin](https://github.com/elastic/elasticsearch/blob/master/plugins/examples/rest-handler/src/main/java/org/elasticsearch/example/resthandler/ExampleCatAction.java).
+
+The [`main.go`](main.go) example defines a custom type, which embeds the regular Elasticsearch client, and adds a `Custom` namespace with an `Example()` method.
+
+To run the example:
+
+```bash
+go run main.go
+
+#    GET http://localhost:9209/_cat/health 200 OK 25ms
+#        « 1555252476 14:34:36 go-elasticsearch green 1 1 0 0 0 0 0 0 - 100.0%
+#
+#    GET http://localhost:9209/_cat/example 200 OK 0s
+#        « Hello from Cat Example action
+```

_examples/extension/main.go

@@ -0,0 +1,98 @@
+// +build ignore
+
+// This examples demonstrates how extend the API of the client by embedding it inside a custom type.
+
+package main
+
+import (
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
+
+	"github.com/elastic/go-elasticsearch/v8"
+	"github.com/elastic/go-elasticsearch/v8/esapi"
+	"github.com/elastic/go-elasticsearch/v8/estransport"
+)
+
+const port = "9209"
+
+// ExtendedClient allows to call regular and custom APIs.
+//
+type ExtendedClient struct {
+	*elasticsearch.Client
+	Custom *ExtendedAPI
+}
+
+// ExtendedAPI contains custom APIs.
+//
+type ExtendedAPI struct {
+	*elasticsearch.Client
+}
+
+// Example calls a custom REST API, "/_cat/example".
+//
+func (c *ExtendedAPI) Example() (*esapi.Response, error) {
+	req, _ := http.NewRequest("GET", "/_cat/example", nil) // errcheck exclude
+
+	res, err := c.Perform(req)
+	if err != nil {
+		return nil, err
+	}
+
+	return &esapi.Response{StatusCode: res.StatusCode, Body: res.Body, Header: res.Header}, nil
+}
+
+func main() {
+	log.SetFlags(0)
+
+	started := make(chan bool)
+
+	// --> Start the proxy server
+	//
+	go startServer(started)
+
+	esclient, err := elasticsearch.NewClient(elasticsearch.Config{
+		Addresses: []string{"http://localhost:" + port},
+		Logger:    &estransport.ColorLogger{Output: os.Stdout, EnableRequestBody: true, EnableResponseBody: true},
+	})
+	if err != nil {
+		log.Fatalf("Error creating the client: %s", err)
+	}
+
+	es := ExtendedClient{Client: esclient, Custom: &ExtendedAPI{esclient}}
+	<-started
+
+	// --> Call a regular Elasticsearch API
+	//
+	es.Cat.Health()
+
+	// --> Call a custom API
+	//
+	es.Custom.Example()
+}
+
+func startServer(started chan<- bool) {
+	proxy := httputil.NewSingleHostReverseProxy(&url.URL{Scheme: "http", Host: "localhost:9200"})
+
+	// Respond with custom content on "GET /_cat/example", proxy to Elasticsearch for other requests
+	//
+	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == "GET" && r.URL.Path == "/_cat/example" {
+			io.WriteString(w, "Hello from Cat Example action")
+			return
+		}
+		proxy.ServeHTTP(w, r)
+	})
+
+	ln, err := net.Listen("tcp", "localhost:"+port)
+	if err != nil {
+		log.Fatalf("Unable to start server: %s", err)
+	}
+
+	go http.Serve(ln, nil)
+	started <- true
+}