Migrate to v5 API (#867)

Update `opensearch-go` to use `v5`-native APIs and deprecate v4 primitives.
The previously-previewed generated client is promoted to the canonical
`opensearchapi/` package, the module path moves to `/v5`, and intelligent
request routing plus partial-failure error reporting become the defaults.

### Breaking changes

- **Module path** is now `github.com/opensearch-project/opensearch-go/v5`.
  Update import paths from `/v4` to `/v5`; the in-source `opensearchapi.X`
  qualifier is unchanged.
- **Canonical `opensearchapi/` is code-generated** by `cmd/osgen` from the
  OpenSearch API specification, replacing the hand-written v4 package
  (formerly previewed at `v5preview/opensearchapi/`). Field-level deltas
  (`DocumentID` -> `ID`, optional `Params` becoming `*Params`, shared params
  moving into embedded `TimeoutParams`/`DebugParams`, `BulkResp.Items` becoming
  `[]BulkItem`) are documented in `opensearchapi/MIGRATING.md`.
- **Plugin import paths** move to `github.com/opensearch-project/opensearch-go/v5/plugins/<name>`;
  generated clients cover all 25 plugins.
- **Default Router is on** unless `OPENSEARCH_GO_ROUTER=false`. In v4 the router
  was opt-in.
- **Partial-failure errors are reported by default** (`Config.Errors == nil`
  resolves to `errmask.Empty`). Set `errmask.New(errmask.All)` or
  `OPENSEARCH_GO_ERROR_MASK` to restore v4-style masking.

### Highlights

- Group document operations under `client.Doc` and point-in-time operations
  under `client.PIT`; `client.Document`/`client.PointInTime` remain as aliases.
  The indices sub-client is `client.Index` (with `client.Indices`/`Indexes`
  aliases). Thin v4-compat forwarders keep top-level `client.Bulk`/`MGet`/`Update`
  working.
- Generate query parameters whose value `0` is meaningful (`if_seq_no`/
  `if_primary_term` on `delete`/`index`/`update` and the plugin policy writes,
  plus `size` on `search`) as `*int` so a deliberate `0` reaches the wire.
- Treat OpenSearch plugin acronyms (ISM/KNN/LTR/ML/PPL/SM/UBI/WLM) as
  initialisms so generated identifiers are all-uppercase per Go convention.
- Transport/signer correctness from #859: close error-response bodies, classify
  `Perform` body-read errors via a sentinel, drain bodies on raw `RoundTrip`
  paths, and close request bodies on signer read errors. `Client.Do` buffers
  response payloads into `rawBody` and `Response.String()` is non-consuming.
- Add a `build-samples` Makefile target and CI job so `_samples/*.go` (excluded
  from `go build ./...`) can no longer break silently.

### Docs

Migration guidance in `opensearchapi/MIGRATING.md`, `UPGRADING.md`, and the
`guides/` tree; a copy-paste least-privilege cluster role for routing and
discovery in `guides/security.md`.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check [here](https://github.com/opensearch-project/OpenSearch/blob/main/CONTRIBUTING.md#developer-certificate-of-origin).

Author: sean-

.codecov.yml

@@ -29,11 +29,6 @@ coverage:
       opensearchapi:
         paths:
           - "opensearchapi/"
-        target: 14%
-        threshold: 2%
-      opensearchapiv5:
-        paths:
-          - "v5preview/opensearchapi/"
         target: 25%
         threshold: 5%
     patch: off

.github/workflows/check-gen.yml

@@ -17,7 +17,7 @@ jobs:
         run: make -j gen
       - name: Check for diff
         run: |
-          if ! git diff --exit-code internal/path/builders_gen.go internal/path/builders_gen_test.go v5preview/opensearchapi/; then
+          if ! git diff --exit-code internal/path/builders_gen.go internal/path/builders_gen_test.go opensearchapi/ plugins/; then
             echo "::warning::Generated code is out of date. Run 'make gen' and commit the result."
             exit 1
           fi

.github/workflows/test-compatibility.yml

@@ -8,48 +8,28 @@ env:
 jobs:
   integ-test-compat:
     runs-on: ubuntu-latest
-    continue-on-error: ${{ matrix.entry.opensearch_version == 'latest' }}
+    continue-on-error: ${{ matrix.opensearch_version == 'latest' }}
     strategy:
       fail-fast: false
-      # OpenSearch <=2.17.x carries a node-join/node-left race condition
-      # (fixed in 2.18 via opensearch-project/OpenSearch#15521, backported
-      # via opensearch-project/OpenSearch#16118) that leaves a node in
-      # cluster state but disconnected at the transport layer, breaking
-      # NodesStats RPC fan-out indefinitely and hanging /_cat/nodes-based
-      # readiness gates. Single-node clusters cannot hit the race, so
-      # affected versions run with OPENSEARCH_NODE_COUNT=1 below.
+      # The supported set tracks the OpenSearch releases still receiving patches
+      # within the last 12 months at each opensearch-go release: every release of
+      # the current major plus the latest release of the previous major. Today
+      # that is 2.19.x and all of 3.x. See opensearch-project/opensearch-go#856.
+      # Re-evaluate this list at each release. All supported lines run as 3-node
+      # clusters.
       matrix:
         secured: ["true", "false"]
-        entry:
-          - { opensearch_version: 1.3.20, node_count: 1 }
-          - { opensearch_version: 2.0.1, node_count: 1 }
-          - { opensearch_version: 2.1.0, node_count: 1 }
-          - { opensearch_version: 2.2.1, node_count: 1 }
-          - { opensearch_version: 2.3.0, node_count: 1 }
-          - { opensearch_version: 2.4.1, node_count: 1 }
-          - { opensearch_version: 2.5.0, node_count: 1 }
-          - { opensearch_version: 2.6.0, node_count: 1 }
-          - { opensearch_version: 2.7.0, node_count: 1 }
-          - { opensearch_version: 2.8.0, node_count: 1 }
-          - { opensearch_version: 2.9.0, node_count: 1 }
-          - { opensearch_version: 2.10.0, node_count: 1 }
-          - { opensearch_version: 2.11.1, node_count: 1 }
-          - { opensearch_version: 2.12.0, node_count: 1 }
-          - { opensearch_version: 2.13.0, node_count: 1 }
-          - { opensearch_version: 2.14.0, node_count: 1 }
-          - { opensearch_version: 2.15.0, node_count: 1 }
-          - { opensearch_version: 2.16.0, node_count: 1 }
-          - { opensearch_version: 2.17.1, node_count: 1 }
-          - { opensearch_version: 2.18.0, node_count: 3 }
-          - { opensearch_version: 2.19.5, node_count: 3 }
-          - { opensearch_version: 3.0.0, node_count: 3 }
-          - { opensearch_version: 3.1.0, node_count: 3 }
-          - { opensearch_version: 3.2.0, node_count: 3 }
-          - { opensearch_version: 3.3.2, node_count: 3 }
-          - { opensearch_version: 3.4.0, node_count: 3 }
-          - { opensearch_version: 3.5.0, node_count: 3 }
-          - { opensearch_version: 3.6.0, node_count: 3 }
-          - { opensearch_version: latest, node_count: 3 }
+        opensearch_version:
+          - 2.19.5
+          - 3.0.0
+          - 3.1.0
+          - 3.2.0
+          - 3.3.2
+          - 3.4.0
+          - 3.5.0
+          - 3.6.0
+          - 3.7.0
+          - latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
@@ -67,19 +47,13 @@ jobs:
 
       - name: Launch OpenSearch cluster
         run: |
-          export OPENSEARCH_VERSION=${{ matrix.entry.opensearch_version }}
+          export OPENSEARCH_VERSION=${{ matrix.opensearch_version }}
           export SECURE_INTEGRATION=${{ matrix.secured }}
-          export OPENSEARCH_NODE_COUNT=${{ matrix.entry.node_count }}
+          export OPENSEARCH_NODE_COUNT=3
           make cluster.clean cluster.build cluster.start
           if [ "${SECURE_INTEGRATION}" = "true" ]; then
             CURL_URL="https://localhost:9200"
-            # Password changed in OpenSearch 2.12.0
-            function version { echo "$@" | awk -F. '{ printf("%d%03d%03d%03d\n", $1,$2,$3,$4); }'; }
-            if [ $(version ${OPENSEARCH_VERSION}) -ge $(version "2.12.0") ] || [ "${OPENSEARCH_VERSION}" = "latest" ]; then
-              CURL_OPTS="-sfku admin:myStrongPassword123!"
-            else
-              CURL_OPTS="-sfku admin:admin"
-            fi
+            CURL_OPTS="-sfku admin:myStrongPassword123!"
           else
             CURL_URL="http://localhost:9200"
             CURL_OPTS="-sf"
@@ -113,9 +87,9 @@ jobs:
 
       - name: Integration test
         run: |
-          export OPENSEARCH_VERSION=${{ matrix.entry.opensearch_version }}
+          export OPENSEARCH_VERSION=${{ matrix.opensearch_version }}
           export SECURE_INTEGRATION=${{ matrix.secured }}
-          export OPENSEARCH_NODE_COUNT=${{ matrix.entry.node_count }}
+          export OPENSEARCH_NODE_COUNT=3
           make cluster.get-cert test-integ-core test-integ-plugins race=true
 
       - name: Stop the OpenSearch cluster

.github/workflows/test-integration.yml

@@ -4,7 +4,7 @@ on: [push, pull_request]
 
 env:
   GITHUB_ACTIONS: true
-  OPENSEARCH_VERSION: 3.6.0
+  OPENSEARCH_VERSION: 3.7.0
   OPENSEARCH_NODE_COUNT: 3
   SECURE_INTEGRATION: true
   CONTAINER_RUNTIME: docker

.github/workflows/test-unit.yml

@@ -38,3 +38,14 @@ jobs:
         with: { go-version-file: 'go.mod' }
       - run: go version
       - run: make test-bench
+
+  samples:
+    name: Build samples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with: { go-version-file: 'go.mod' }
+      - run: go version
+      - run: make build-samples
+

.golangci.yml

@@ -162,13 +162,13 @@ linters:
         path: opensearchtransport/opensearchtransport.go
       - linters:
           - dupl
-        path: (-params\.go|api_indices|api_dangling\.go|api_point_in_time\.go|rethrottle\.go|api_cat-.*\.go|plugins/security/api_\w+.go|plugins/security/api_.*-patch.go|_gen\.go)
+        path: (-params\.go|api_indices|api_dangling\.go|api_point_in_time\.go|rethrottle\.go|api_cat-.*\.go|_gen\.go)
       # Generated code emits long lines from upstream spec descriptions, table
       # rows, and inline struct literals that lose readability if wrapped at the
       # template level.
       - linters:
           - lll
-        path: _integ_gen_test\.go|internal/path/builders_gen(_test)?\.go|v5preview/opensearchapi/.*_gen\.go
+        path: _integ_gen_test\.go|internal/path/builders_gen(_test)?\.go|opensearchapi/.*_gen\.go
     paths:
       - third_party$
       - builtin$