Add generic Do[T] function for compile-time pointer enforcement

Add opensearch.Do[T]() that enforces pointer response types at compile
time, preventing a class of bugs where non-pointer values silently fail
JSON unmarshaling at runtime. Mark Client.Do() as deprecated in favor
of the generic alternative.

Ref: opensearch-project#809
Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -7,6 +7,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Added
 
 - Add `primary_terms_map` and `split_shards_metadata` fields to ClusterState index metadata for OpenSearch >=3.6.0 compatibility
+- Add generic `opensearch.Do[T]()` function for compile-time pointer enforcement on response types, preventing a class of bugs where non-pointer values are silently passed to `Client.Do()` and fail at runtime during JSON unmarshaling
 - Add `InsecureSkipVerify` config option to disable TLS certificate verification without constructing a custom `http.Transport`, preserving `DefaultTransport` connection pooling, HTTP/2, and timeout defaults ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
 - Add `DisableResponseBuffering` config option to skip eager `io.ReadAll` buffering of response bodies in `Perform()`, reducing per-request allocations and TTFB for proxy and streaming use cases ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
 - Add per-attempt `RequestTimeout` to bound individual HTTP round-trips, preventing indefinite hangs on stalled connections ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
@@ -148,6 +149,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Deprecated
 
+- Mark `Client.Do()` with a `Deprecated` doc annotation in favor of `opensearch.Do[T]()` for compile-time pointer safety; `Client.Do()` remains fully functional and will not be removed, but `staticcheck` SA1019 will nudge cross-package callers toward the safer generic alternative
+
 ### Removed
 
 ### Fixed

USER_GUIDE.md

@@ -517,6 +517,7 @@ All `OPENSEARCH_GO_*` environment variables are evaluated once at client initial
 - [Advanced Index Actions](guides/advanced_index_actions.md)
 - [Index Templates](guides/index_template.md)
 - [Data Streams](guides/data_streams.md)
+- [Making Raw JSON REST Requests](guides/json.md)
 - [Request Routing](guides/routing.md)
 - [Cluster Health Checking](guides/cluster_health_checking.md)
 - [Node Discovery and Role Management](guides/node_discovery_and_roles.md)

error_test.go

@@ -318,11 +318,11 @@ func TestError(t *testing.T) {
 
 		// Parse the error
 		err := opensearch.ParseError(resp)
-		require.NotNil(t, err)
+		require.Error(t, err)
 
 		// Verify the body is still readable after ParseError
 		body, readErr := io.ReadAll(resp.Body)
-		require.Nil(t, readErr, "body should be readable after ParseError")
+		require.NoError(t, readErr, "body should be readable after ParseError")
 		require.NotEmpty(t, body, "body should not be empty after ParseError")
 
 		// Verify the body content matches the original

guides/json.md

@@ -1,5 +1,6 @@
 - [Making Raw JSON REST Requests](#making-raw-json-rest-requests)
   - [Setup](#setup)
+  - [Using Do for Typed Responses](#using-do-for-typed-responses)
   - [GET](#get)
   - [PUT](#put)
   - [POST](#post)
@@ -17,12 +18,14 @@ Let's create a client instance:
 package main
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
 	"strings"
 
+	"github.com/opensearch-project/opensearch-go/v4"
 	"github.com/opensearch-project/opensearch-go/v4/opensearchapi"
 )
 
@@ -40,6 +43,63 @@ func example() error {
 	}
 ```
 
+## Using Do for Typed Responses
+
+When you need to call an API that `opensearchapi` doesn't cover — plugin endpoints, newly released server APIs, or internal custom endpoints — use `opensearch.Do()` to execute a request and automatically unmarshal the JSON response into a struct.
+
+The `Client.Do()` method accepts `any` for its response parameter, which means passing a non-pointer compiles but fails at runtime during JSON unmarshaling. The generic `opensearch.Do[T]()` function catches this mistake at compile time. `Client.Do()` is marked with a `Deprecated` doc annotation to steer callers toward the safer alternative — it remains fully functional and will not be removed, but `staticcheck` SA1019 will flag cross-package usage as a nudge.
+
+First, define a request type that satisfies `opensearch.Request`:
+
+```go
+	// customReq wraps opensearch.BuildRequest to satisfy the opensearch.Request interface.
+	type customReq struct {
+		method string
+		path   string
+		body   io.Reader
+	}
+
+	func (r customReq) GetRequest() (*http.Request, error) {
+		return opensearch.BuildRequest(r.method, r.path, r.body, nil, nil)
+	}
+```
+
+Then use `opensearch.Do` to call the endpoint with a typed response:
+
+```go
+	type PluginStatusResp struct {
+		Status  string `json:"status"`
+		Version string `json:"version"`
+	}
+
+	ctx := context.Background()
+
+	// Preferred: opensearch.Do[T] enforces *T at compile time.
+	var pluginStatus PluginStatusResp
+	req := customReq{method: http.MethodGet, path: "/_plugins/my_plugin/status"}
+	resp, err := opensearch.Do(ctx, client.Client, req, &pluginStatus)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("plugin status: %s (v%s), http: %d\n", pluginStatus.Status, pluginStatus.Version, resp.StatusCode)
+```
+
+If you pass a non-pointer value to `opensearch.Do`, the compiler rejects it:
+
+```go
+	// Compile error: cannot use pluginStatus (variable of type PluginStatusResp)
+	// as *PluginStatusResp value in argument to opensearch.Do
+	resp, err := opensearch.Do(ctx, client.Client, req, pluginStatus)
+```
+
+The three levels of the client API, from lowest to highest:
+
+| Level | Function                                                           | Response handling                                         | When to use                                                |
+| ----- | ------------------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------- |
+| Low   | `client.Perform(req)`                                              | Raw `*http.Response`; caller reads and closes body        | Proxying, streaming, full control needed                   |
+| Mid   | `opensearch.Do(ctx, client, req, &resp)`                           | Automatic JSON unmarshal with compile-time pointer safety | Plugin APIs, unsupported endpoints, custom `Request` types |
+| High  | `client.Search(ctx, req)` / `client.Indices.Create(ctx, req)` etc. | Fully typed request and response                          | Standard OpenSearch APIs                                   |
+
 ## GET
 
 The following example returns the server version information via `GET /`.

opensearch.go

@@ -381,7 +381,12 @@ func (c *Client) Perform(req *http.Request) (*http.Response, error) {
 	return c.Transport.Perform(req)
 }
 
-// Do gets and performs the request. It also tries to parse the response into the dataPointer
+// Do gets and performs the request. It also tries to parse the response into the dataPointer.
+//
+// Deprecated: Use [Do] instead, which enforces that dataPointer is a pointer at compile time.
+// Client.Do accepts any, so passing a non-pointer compiles but fails at runtime during JSON
+// unmarshaling. The method remains fully functional and will not be removed; this annotation
+// exists to steer callers toward the safer generic alternative.
 func (c *Client) Do(ctx context.Context, req Request, dataPointer any) (*Response, error) {
 	httpReq, err := req.GetRequest()
 	if err != nil {
@@ -420,6 +425,12 @@ func (c *Client) Do(ctx context.Context, req Request, dataPointer any) (*Respons
 	return response, nil
 }
 
+// Do is a generic version of [Client.Do] that enforces dataPointer as a pointer at compile time.
+// It delegates to [Client.Do] after the type system has guaranteed *T.
+func Do[T any](ctx context.Context, c *Client, req Request, dataPointer *T) (*Response, error) {
+	return c.Do(ctx, req, dataPointer)
+}
+
 // Metrics returns the client metrics.
 func (c *Client) Metrics() (opensearchtransport.Metrics, error) {
 	if mt, ok := c.Transport.(opensearchtransport.Measurable); ok {

opensearch_internal_test.go

@@ -218,6 +218,35 @@ func TestClientInterfe(t *testing.T) {
 		assert.NotNil(t, resp)
 	})
 
+	t.Run("Generic Do()", func(t *testing.T) {
+		c, err := NewClient(Config{Transport: mockhttp.NewRoundTripFunc(t, defaultRoundTripFunc)})
+		require.NoError(t, err)
+
+		type versionInfo struct {
+			Number       string `json:"number"`
+			Distribution string `json:"distribution"`
+		}
+		type rootResp struct {
+			Version versionInfo `json:"version"`
+		}
+
+		var got rootResp
+		resp, err := Do(context.TODO(), c, testReq{Path: "/"}, &got)
+		require.NoError(t, err)
+		require.NotNil(t, resp)
+		require.Equal(t, "1.0.0", got.Version.Number)
+		require.Equal(t, "opensearch", got.Version.Distribution)
+	})
+
+	t.Run("Generic Do() nil pointer", func(t *testing.T) {
+		c, err := NewClient(Config{Transport: mockhttp.NewRoundTripFunc(t, defaultRoundTripFunc)})
+		require.NoError(t, err)
+
+		resp, err := Do[struct{}](context.TODO(), c, testReq{}, nil)
+		require.NoError(t, err)
+		require.NotNil(t, resp)
+	})
+
 	t.Run("Do() GetRequest error", func(t *testing.T) {
 		c, err := NewClient(Config{Transport: mockhttp.NewRoundTripFunc(t, defaultRoundTripFunc)})
 		require.NoError(t, err)

opensearchapi/api_aliases.go

@@ -20,7 +20,7 @@ func (c Client) Aliases(ctx context.Context, req AliasesReq) (*AliasesResp, erro
 		data AliasesResp
 		err  error
 	)
-	if data.response, err = c.do(ctx, req, &data); err != nil {
+	if data.response, err = do(ctx, &c, req, &data); err != nil {
 		return &data, err
 	}
 

opensearchapi/api_bulk.go

@@ -20,7 +20,7 @@ func (c Client) Bulk(ctx context.Context, req BulkReq) (*BulkResp, error) {
 		data BulkResp
 		err  error
 	)
-	if data.response, err = c.do(ctx, req, &data); err != nil {
+	if data.response, err = do(ctx, &c, req, &data); err != nil {
 		return &data, err
 	}
 

opensearchapi/api_cat.go

@@ -24,7 +24,7 @@ func (c catClient) Aliases(ctx context.Context, req *CatAliasesReq) (*CatAliases
 		data CatAliasesResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Aliases); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Aliases); err != nil {
 		return &data, err
 	}
 
@@ -41,7 +41,7 @@ func (c catClient) Allocation(ctx context.Context, req *CatAllocationReq) (*CatA
 		data CatAllocationsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Allocations); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Allocations); err != nil {
 		return &data, err
 	}
 
@@ -58,7 +58,7 @@ func (c catClient) ClusterManager(ctx context.Context, req *CatClusterManagerReq
 		data CatClusterManagersResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.ClusterManagers); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.ClusterManagers); err != nil {
 		return &data, err
 	}
 
@@ -75,7 +75,7 @@ func (c catClient) Count(ctx context.Context, req *CatCountReq) (*CatCountsResp,
 		data CatCountsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Counts); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Counts); err != nil {
 		return &data, err
 	}
 
@@ -92,7 +92,7 @@ func (c catClient) FieldData(ctx context.Context, req *CatFieldDataReq) (*CatFie
 		data CatFieldDataResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.FieldData); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.FieldData); err != nil {
 		return &data, err
 	}
 
@@ -109,7 +109,7 @@ func (c catClient) Health(ctx context.Context, req *CatHealthReq) (*CatHealthRes
 		data CatHealthResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Health); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Health); err != nil {
 		return &data, err
 	}
 
@@ -126,7 +126,7 @@ func (c catClient) Indices(ctx context.Context, req *CatIndicesReq) (*CatIndices
 		data CatIndicesResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Indices); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Indices); err != nil {
 		return &data, err
 	}
 
@@ -143,7 +143,7 @@ func (c catClient) Master(ctx context.Context, req *CatMasterReq) (*CatMasterRes
 		data CatMasterResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Master); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Master); err != nil {
 		return &data, err
 	}
 
@@ -160,7 +160,7 @@ func (c catClient) NodeAttrs(ctx context.Context, req *CatNodeAttrsReq) (*CatNod
 		data CatNodeAttrsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.NodeAttrs); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.NodeAttrs); err != nil {
 		return &data, err
 	}
 
@@ -177,7 +177,7 @@ func (c catClient) Nodes(ctx context.Context, req *CatNodesReq) (*CatNodesResp,
 		data CatNodesResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Nodes); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Nodes); err != nil {
 		return &data, err
 	}
 
@@ -194,7 +194,7 @@ func (c catClient) PendingTasks(ctx context.Context, req *CatPendingTasksReq) (*
 		data CatPendingTasksResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.PendingTasks); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.PendingTasks); err != nil {
 		return &data, err
 	}
 
@@ -211,7 +211,7 @@ func (c catClient) Plugins(ctx context.Context, req *CatPluginsReq) (*CatPlugins
 		data CatPluginsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Plugins); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Plugins); err != nil {
 		return &data, err
 	}
 
@@ -228,7 +228,7 @@ func (c catClient) Recovery(ctx context.Context, req *CatRecoveryReq) (*CatRecov
 		data CatRecoveryResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Recovery); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Recovery); err != nil {
 		return &data, err
 	}
 
@@ -245,7 +245,7 @@ func (c catClient) Repositories(ctx context.Context, req *CatRepositoriesReq) (*
 		data CatRepositoriesResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Repositories); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Repositories); err != nil {
 		return &data, err
 	}
 
@@ -262,7 +262,7 @@ func (c catClient) Segments(ctx context.Context, req *CatSegmentsReq) (*CatSegme
 		data CatSegmentsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Segments); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Segments); err != nil {
 		return &data, err
 	}
 
@@ -279,7 +279,7 @@ func (c catClient) Shards(ctx context.Context, req *CatShardsReq) (*CatShardsRes
 		data CatShardsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Shards); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Shards); err != nil {
 		return &data, err
 	}
 
@@ -292,7 +292,7 @@ func (c catClient) Snapshots(ctx context.Context, req CatSnapshotsReq) (*CatSnap
 		data CatSnapshotsResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Snapshots); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Snapshots); err != nil {
 		return &data, err
 	}
 
@@ -309,7 +309,7 @@ func (c catClient) Tasks(ctx context.Context, req *CatTasksReq) (*CatTasksResp,
 		data CatTasksResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Tasks); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Tasks); err != nil {
 		return &data, err
 	}
 
@@ -326,7 +326,7 @@ func (c catClient) Templates(ctx context.Context, req *CatTemplatesReq) (*CatTem
 		data CatTemplatesResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.Templates); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.Templates); err != nil {
 		return &data, err
 	}
 
@@ -343,7 +343,7 @@ func (c catClient) ThreadPool(ctx context.Context, req *CatThreadPoolReq) (*CatT
 		data CatThreadPoolResp
 		err  error
 	)
-	if data.response, err = c.apiClient.do(ctx, req, &data.ThreadPool); err != nil {
+	if data.response, err = do(ctx, c.apiClient, req, &data.ThreadPool); err != nil {
 		return &data, err
 	}