Skip to content

Commit 87de4d2

Browse files
duc2hduc2h
authored
docs(UPGRADING): move StringError section to 4.0.0 and fix table of contents (opensearch-project#785)
The "*opensearch.StringError for unknown JSON responses" change actually shipped in v4.0.0 (commit 17956a2, "Move error structs from opensearchapi to opensearch to be reused by plugins"), not 5.0.0. The section was authored when 4.0.0 was the unreleased target and it kept the wrong version label after v5.0.0 added its own legitimate upgrade notes for partial-failure errors, default Router injection, etc. Move the entire StringError subsection from "## Upgrading to >= 5.0.0" into "## Upgrading to >= 4.0.0", placing it between "Error Types" and "AWS Signer" alongside the related v4 error-handling change. Update all "5.0.0" references inside the moved subsection to "4.0.0". Also fix two unrelated regressions in the table of contents: - Restore the outer "Upgrading OpenSearch Go Client" wrapper that was dropped, so the ToC has a top-level link to the document heading. - Remove duplicate "Import path", "Error types", and "AWS signer" entries from the 4.0.0 ToC block. Co-authored-by: duc2h <hoangduc02.01.1998@gmail.com> Signed-off-by: duc2h <hoangduc02.01.1998@gmail.com> Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>
1 parent 0a67033 commit 87de4d2

1 file changed

Lines changed: 69 additions & 71 deletions

File tree

‎UPGRADING.md‎

Lines changed: 69 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,30 @@
1-
- [Upgrading to >= 5.0.0](#upgrading-to->=-5.0.0)
2-
- [Partial failure errors (Config.Errors)](#partial-failure-errors-configerrors)
3-
- [Default Router Injection in v5preview](#default-router-injection-in-v5preview)
4-
- [DiscoverNodes() blocking semantics](#discovernodes-blocking-semantics)
5-
- [opensearchtransport.Route interface gained OpID()](#opensearchtransportroute-interface-gained-opid)
6-
- [StringError for unknown JSON responses](#stringerror-for-unknown-json-responses)
7-
- [Response.Body becomes a method](#responsebody-becomes-a-method)
8-
- [Upgrading to >= 4.7.0](#upgrading-to->=-4.7.0)
9-
- [opensearch.Request interface signature change](#opensearchrequest-interface-signature-change)
10-
- [Path segment values are percent-encoded](#path-segment-values-are-percent-encoded)
11-
- [v5preview/opensearchapi/ package - v5 preview API surface](#v5previewopensearchapi-package---v5-preview-api-surface)
12-
- [Upgrading to >= 4.0.0](#upgrading-to->=-4.0.0)
13-
- [Import path](#import-path)
14-
- [Error types](#error-types)
15-
- [AWS signer](#aws-signer)
16-
- [Typed failure arrays in by-query and reindex responses](#typed-failure-arrays-in-by-query-and-reindex-responses)
17-
- [Inline `_shards` structs replaced with ResponseShards](#inline-_shards-structs-replaced-with-responseshards)
18-
- [`_type` field tags now include omitempty](#_type-field-tags-now-include-omitempty)
19-
- [Import path](#import-path)
20-
- [Error types](#error-types)
21-
- [AWS signer](#aws-signer)
22-
- [Upgrading to >= 3.0.0](#upgrading-to->=-3.0.0)
23-
- [Client creation](#client-creation)
24-
- [Requests](#requests)
25-
- [Responses](#responses)
26-
- [Error handling](#error-handling)
27-
- [API reorganization](#api-reorganization)
28-
- [Upgrading to >= 2.3.0](#upgrading-to->=-2.3.0)
29-
- [Snapshot delete](#snapshot-delete)
1+
- [Upgrading OpenSearch Go Client](#upgrading-opensearch-go-client)
2+
- [Upgrading to >= 5.0.0](#upgrading-to->=-5.0.0)
3+
- [Partial failure errors (Config.Errors)](#partial-failure-errors-configerrors)
4+
- [Default Router Injection in v5preview](#default-router-injection-in-v5preview)
5+
- [DiscoverNodes() blocking semantics](#discovernodes-blocking-semantics)
6+
- [opensearchtransport.Route interface gained OpID()](#opensearchtransportroute-interface-gained-opid)
7+
- [Response.Body becomes a method](#responsebody-becomes-a-method)
8+
- [Upgrading to >= 4.7.0](#upgrading-to->=-4.7.0)
9+
- [opensearch.Request interface signature change](#opensearchrequest-interface-signature-change)
10+
- [Path segment values are percent-encoded](#path-segment-values-are-percent-encoded)
11+
- [v5preview/opensearchapi/ package - v5 preview API surface](#v5previewopensearchapi-package---v5-preview-api-surface)
12+
- [Upgrading to >= 4.0.0](#upgrading-to->=-4.0.0)
13+
- [Import path](#import-path)
14+
- [Error types](#error-types)
15+
- [StringError for unknown JSON responses](#stringerror-for-unknown-json-responses)
16+
- [AWS signer](#aws-signer)
17+
- [Typed failure arrays in by-query and reindex responses](#typed-failure-arrays-in-by-query-and-reindex-responses)
18+
- [Inline `_shards` structs replaced with ResponseShards](#inline-_shards-structs-replaced-with-responseshards)
19+
- [`_type` field tags now include omitempty](#_type-field-tags-now-include-omitempty)
20+
- [Upgrading to >= 3.0.0](#upgrading-to->=-3.0.0)
21+
- [Client creation](#client-creation)
22+
- [Requests](#requests)
23+
- [Responses](#responses)
24+
- [Error handling](#error-handling)
25+
- [API reorganization](#api-reorganization)
26+
- [Upgrading to >= 2.3.0](#upgrading-to->=-2.3.0)
27+
- [Snapshot delete](#snapshot-delete)
3028

3129
# Upgrading OpenSearch Go Client
3230

@@ -137,48 +135,6 @@ type Route interface {
137135

138136
External code that implements `Route` (custom routing policies) must add an `OpID() OperationID` method returning the [`OperationID`](https://pkg.go.dev/github.com/opensearch-project/opensearch-go/v4/opensearchtransport#OperationID) for the route -- typically the `Op*` constant matching the route's HTTP method+path. Built-in routes built via `NewRouteMux` are populated automatically; only hand-written `Route` implementations are affected.
139137

140-
### StringError for Unknown JSON Responses
141-
142-
Version 5.0.0 returns `*opensearch.StringError` error type instead of `*fmt.wrapError` when response received from the server is an unknown JSON. For example, consider delete document API which returns an unknown JSON body when document is not found.
143-
144-
Before 5.0.0:
145-
146-
```go
147-
docDelResp, err = client.Document.Delete(ctx, opensearchapi.DocumentDeleteReq{Index: "movies", DocumentID: "3"})
148-
if err != nil {
149-
fmt.Println(err)
150-
151-
if !errors.Is(err, opensearch.ErrJSONUnmarshalBody) && docDelResp != nil {
152-
resp := docDelResp.Inspect().Response
153-
// get http status
154-
fmt.Println(resp.StatusCode)
155-
body := strings.TrimPrefix(err.Error(), "opensearch error response could not be parsed as error: ")
156-
errResp := opensearchapi.DocumentDeleteResp{}
157-
json.Unmarshal([]byte(body), &errResp)
158-
// extract result field from the body
159-
fmt.Println(errResp.Result)
160-
}
161-
}
162-
```
163-
164-
After 5.0.0:
165-
166-
```go
167-
docDelResp, err = client.Document.Delete(ctx, opensearchapi.DocumentDeleteReq{Index: "movies", DocumentID: "3"})
168-
if err != nil {
169-
// parse into *opensearch.StringError
170-
var myStringErr *opensearch.StringError
171-
if errors.As(err, &myStringErr) {
172-
// get http status
173-
fmt.Println(myStringErr.Status)
174-
errResp := opensearchapi.DocumentDeleteResp{}
175-
json.Unmarshal([]byte(myStringErr.Err), &errResp)
176-
// extract result field from the body
177-
fmt.Println(errResp.Result)
178-
}
179-
}
180-
```
181-
182138
### `Response.Body` becomes a method
183139

184140
`Response.Body` changes from a public `io.ReadCloser` field to a `Body()` method. The new `RawBody() []byte` method (available since v4) provides access to the buffered response bytes without consuming the body reader.
@@ -317,6 +273,48 @@ if errors.As(err, &opensearchError) {
317273
}
318274
```
319275

276+
### StringError for Unknown JSON Responses
277+
278+
Version 4.0.0 returns `*opensearch.StringError` error type instead of `*fmt.wrapError` when response received from the server is an unknown JSON. For example, consider delete document API which returns an unknown JSON body when document is not found.
279+
280+
Before 4.0.0:
281+
282+
```go
283+
docDelResp, err = client.Document.Delete(ctx, opensearchapi.DocumentDeleteReq{Index: "movies", DocumentID: "3"})
284+
if err != nil {
285+
fmt.Println(err)
286+
287+
if !errors.Is(err, opensearch.ErrJSONUnmarshalBody) && docDelResp != nil {
288+
resp := docDelResp.Inspect().Response
289+
// get http status
290+
fmt.Println(resp.StatusCode)
291+
body := strings.TrimPrefix(err.Error(), "opensearch error response could not be parsed as error: ")
292+
errResp := opensearchapi.DocumentDeleteResp{}
293+
json.Unmarshal([]byte(body), &errResp)
294+
// extract result field from the body
295+
fmt.Println(errResp.Result)
296+
}
297+
}
298+
```
299+
300+
After 4.0.0:
301+
302+
```go
303+
docDelResp, err = client.Document.Delete(ctx, opensearchapi.DocumentDeleteReq{Index: "movies", DocumentID: "3"})
304+
if err != nil {
305+
// parse into *opensearch.StringError
306+
var myStringErr *opensearch.StringError
307+
if errors.As(err, &myStringErr) {
308+
// get http status
309+
fmt.Println(myStringErr.Status)
310+
errResp := opensearchapi.DocumentDeleteResp{}
311+
json.Unmarshal([]byte(myStringErr.Err), &errResp)
312+
// extract result field from the body
313+
fmt.Println(errResp.Result)
314+
}
315+
}
316+
```
317+
320318
### AWS Signer
321319

322320
The `signer/aws` package now uses AWS SDK v2 instead of AWS SDK v1. AWS SDK v1 reached end-of-support on July 31, 2025.

0 commit comments

Comments
 (0)