docs: fix removed opensearch.BuildRequest reference and sweep upgrade guides (#979)

* docs: fix removed opensearch.BuildRequest reference and sweep upgrade guides

The v4.7.0 migration section (and the raw-JSON usage guide) told readers to
forward a custom Request.GetRequest to opensearch.BuildRequest, but that helper
was removed in 4.7.0 -- the very release the section documents. Replace it with
a net/http-based before/after example (relative path; the transport prepends
the base URL).

A verification sweep of the remaining upgrade guides fixed:
- UPGRADING_V5.md: RawBody() comment wrongly listed error responses as nil.
- opensearchapi/UPGRADING_V4_TO_V5.md: SearchParams.Size is *int; the example
  used a bare int literal that would not compile.
- UPGRADING_V3.md: InsecureSkipVerify did not exist in v2.3.0/v3.0.0; error
  snippet had a variable-name mismatch and a missing return; Msearch/
  MsearchTemplate casing in the v2.3.0 before-column.
- opensearchapi/UPGRADING_V3_TO_V4.md: scoped the CausedBy addition to v4.6.0.

Reported in #977.

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

UPGRADING_V3.md

@@ -15,7 +15,6 @@ client, err := opensearch.NewDefaultClient()
 // with config
 client, err := opensearch.NewClient(
     opensearch.Config{
-	    InsecureSkipVerify: true,
 		Addresses: []string{"https://localhost:9200"},
 		Username:  "admin",
 		Password:  "admin",
@@ -33,7 +32,6 @@ client, err := opensearchapi.NewDefaultClient()
 client, err := opensearchapi.NewClient(
     opensearchapi.Config{
 		Client: opensearch.Config{
-			InsecureSkipVerify: true, // For testing only. Use certificate for validation.
 			Addresses:          []string{"https://localhost:9200"},
 			Username:           "admin", // For testing only. Don't store credentials in code.
 			Password:           "admin",
@@ -161,8 +159,8 @@ if err != nil {
 defer resp.Body.Close()
 
 // Check if the status code is >299
-if createIndexResp.IsError() {
-    fmt.Errorf("Opensearch returned an error. Status: %d", createIndexResp.StatusCode)
+if resp.IsError() {
+    return fmt.Errorf("Opensearch returned an error. Status: %d", resp.StatusCode)
 }
 ```
 
@@ -310,8 +308,8 @@ Version 3.0.0 reorganized APIs into logical sub-clients. The following tables co
 | `client.Count(...)`                      | `client.Indices.Count(ctx, req)`        |
 | `client.FieldCaps(...)`                  | `client.Indices.FieldCaps(ctx, req)`    |
 | `client.Mget(...)`                       | `client.MGet(ctx, req)`                 |
-| `client.MSearch(...)`                    | `client.MSearch(ctx, req)`              |
-| `client.MSearchTemplate(...)`            | `client.MSearchTemplate(ctx, req)`      |
+| `client.Msearch(...)`                    | `client.MSearch(ctx, req)`              |
+| `client.MsearchTemplate(...)`            | `client.MSearchTemplate(ctx, req)`      |
 | `client.Mtermvectors(...)`               | `client.MTermvectors(ctx, req)`         |
 | `client.Indices.AddBlock(...)`           | `client.Indices.Block(ctx, req)`        |
 | `client.Indices.ResolveIndex(...)`       | `client.Indices.Resolve(ctx, req)`      |

UPGRADING_V4.md

@@ -14,7 +14,35 @@ GetRequest() (*http.Request, error)
 GetRequest(method string) (*http.Request, error)
 ```
 
-This change is invisible to almost all callers: the typed `Req` structs that the client consumes (e.g. `opensearchapi.SearchReq`, `opensearchapi.IndexReq`) already implement the new signature. Only code that defines a custom type satisfying `opensearch.Request` is affected. If you maintain such a type, add a `method string` parameter and forward it to your underlying `http.NewRequest` call (or `opensearch.BuildRequest`).
+This change is invisible to almost all callers: the typed `Req` structs that the client consumes (e.g. `opensearchapi.SearchReq`, `opensearchapi.IndexReq`) already implement the new signature. Only code that defines a custom type satisfying `opensearch.Request` is affected.
+
+If you maintain such a type, add a `method string` parameter and forward it to your request builder. The `opensearch.BuildRequest` helper that earlier v4 releases exposed for this purpose was **removed in 4.7.0**; construct the request with `net/http` directly instead.
+
+```go
+// Before (<= 4.6.0): method stored on the struct, built via the removed
+// opensearch.BuildRequest helper (which set Content-Type for a non-nil body).
+func (r customReq) GetRequest() (*http.Request, error) {
+    return opensearch.BuildRequest(r.method, r.path, r.body, nil, nil)
+}
+
+// After (>= 4.7.0): method comes from the caller, built with net/http.
+func (r customReq) GetRequest(method string) (*http.Request, error) {
+    req, err := http.NewRequest(method, r.path, r.body)
+    if err != nil {
+        return nil, err
+    }
+    // BuildRequest set this automatically for a non-nil body; http.NewRequest
+    // does not, so set it here or OpenSearch may reject a JSON body with 400/415.
+    if r.body != nil {
+        req.Header.Set("Content-Type", "application/json")
+    }
+    return req, nil
+}
+```
+
+`opensearch.BuildRequest` also accepted `params map[string]string` and `headers http.Header` arguments. To preserve those, set them on the `*http.Request` after construction: encode params onto `req.URL.RawQuery` (via `url.Values`) and add headers to `req.Header`.
+
+> The path must begin with a leading slash (e.g. `r.path == "/_plugins/my_plugin/status"`). The transport builds the final URL by concatenating the base URL with the request path (`base + req.URL.Path` in `opensearchtransport.setReqURL`), not via `url.ResolveReference`, so a path without a leading slash produces a malformed URL.
 
 ### Path segment values are percent-encoded
 

UPGRADING_V5.md

@@ -214,7 +214,7 @@ body, err := io.ReadAll(resp.Body)
 For responses decoded by `opensearch.Execute`, the buffered bytes are also available without consuming the body reader via the `RawBody() []byte` method (useful for inspection or comparison testing):
 
 ```go
-raw := resp.RawBody() // nil for streamed or error responses; read resp.Body directly there
+raw := resp.RawBody() // nil for streamed responses (Client.Stream); read resp.Body directly there
 ```
 
 ## `signer/aws` removed in favor of `signer/awsv2`

guides/usage-json.md

@@ -52,14 +52,27 @@ When you need to call an API that `opensearchapi` doesn't cover -- plugin endpoi
 First, define a request type that satisfies `opensearch.Request`:
 
 ```go
-	// customReq wraps opensearch.BuildRequest to satisfy the opensearch.Request interface.
+	// customReq builds an *http.Request from a path with a leading slash (e.g.
+	// "/_plugins/my_plugin/status") to satisfy the opensearch.Request interface.
+	// The transport prepends the base URL. method is an HTTP method
+	// (e.g. http.MethodGet) forwarded by the caller.
 	type customReq struct {
 		path string
 		body io.Reader
 	}
 
 	func (r customReq) GetRequest(method string) (*http.Request, error) {
-		return opensearch.BuildRequest(method, r.path, r.body, nil, nil)
+		req, err := http.NewRequest(method, r.path, r.body)
+		if err != nil {
+			return nil, err
+		}
+		// opensearch.BuildRequest set this automatically for a non-nil body;
+		// http.NewRequest does not, so set it here or OpenSearch may reject a
+		// JSON body with 400/415.
+		if r.body != nil {
+			req.Header.Set("Content-Type", "application/json")
+		}
+		return req, nil
 	}
 ```
 

opensearchapi/UPGRADING_V3_TO_V4.md

@@ -29,15 +29,15 @@ Files behind custom build tags (`//go:build <tag>`) are loaded under the default
 
 In v3 the API error types lived in `opensearchapi` (`opensearchapi/error.go`). In v4 they moved to the root `opensearch` package and were redesigned. Update the imports and package qualifiers by hand:
 
-| v3                                              | v4                                                    |
-| ----------------------------------------------- | ----------------------------------------------------- |
-| `opensearchapi.Error` (`{Err Err; Status int}`) | `opensearch.StructError` (same shape)                 |
-| —                                               | `opensearch.Error` (new, simpler `{Err string}`)      |
-| `opensearchapi.Err`                             | `opensearch.Err` (adds optional `CausedBy *CausedBy`) |
-| `opensearchapi.RootCause`                       | `opensearch.RootCause`                                |
-| `opensearchapi.StringError`                     | `opensearch.StringError`                              |
-
-The v3 detailed-error type `opensearchapi.Error{Err Err; Status int}` is now `opensearch.StructError`; the v4 `opensearch.Error` is a different, simpler type. Re-point type switches and assertions that decoded the detailed error to `opensearch.StructError`. `opensearch.Err` gains an optional `CausedBy *CausedBy` field for nested causes; existing field access is unaffected.
+| v3                                              | v4                                                                      |
+| ----------------------------------------------- | ----------------------------------------------------------------------- |
+| `opensearchapi.Error` (`{Err Err; Status int}`) | `opensearch.StructError` (same shape)                                   |
+| —                                               | `opensearch.Error` (new, simpler `{Err string}`)                        |
+| `opensearchapi.Err`                             | `opensearch.Err` (later gains optional `CausedBy *CausedBy`, see below) |
+| `opensearchapi.RootCause`                       | `opensearch.RootCause`                                                  |
+| `opensearchapi.StringError`                     | `opensearch.StringError`                                                |
+
+The v3 detailed-error type `opensearchapi.Error{Err Err; Status int}` is now `opensearch.StructError`; the v4 `opensearch.Error` is a different, simpler type. Re-point type switches and assertions that decoded the detailed error to `opensearch.StructError`. In a later v4 release (`v4.6.0`), `opensearch.Err` gained an optional `CausedBy *CausedBy` field for nested causes; existing field access is unaffected.
 
 ## Response types no longer expose raw maps
 

opensearchapi/UPGRADING_V4_TO_V5.md

@@ -61,17 +61,19 @@ Within `opensearchapi/`, the bulk, NDJSON, and single-document write operations
 // v4
 client.Search(ctx, &opensearchapi.SearchReq{
     Indices: []string{"products"},
-    Params:  opensearchapi.SearchParams{Size: 20},
+    Params:  opensearchapi.SearchParams{Size: opensearch.ToPointer(20)},
 })
 
 // v5
 client.Search(ctx, &opensearchapi.SearchReq{
     Indices: []string{"products"},
-    Params:  &opensearchapi.SearchParams{Size: 20},
+    Params:  &opensearchapi.SearchParams{Size: opensearch.ToPointer(20)},
 })
 ```
 
-Pointer-typed `Params` lets callers pass `nil` when no parameters are needed and keeps the struct cheap to copy.
+Pointer-typed `Params` lets callers pass `nil` when no parameters are needed and keeps the struct cheap to copy. `Size` itself has been `*int` since v4.0.0 and is unchanged here -- only the surrounding `Params` value became a pointer.
+
+> On Go 1.26+ you can write `new(20)` in place of `opensearch.ToPointer(20)`; both produce a `*int`.
 
 ### Shared parameters move into embedded structs