refactor(signer)!: remove signer/aws, standardize on signer/awsv2

Both signer packages signed with AWS SDK for Go v2 and exposed the same
constructor shape, so maintaining two was pure duplication. Standardize on
signer/awsv2, whose name mirrors AWS's own SDK-version nomenclature, and
remove signer/aws.

BREAKING CHANGE: the signer/aws package is removed. Callers migrate by
changing the import path from .../signer/aws to .../signer/awsv2;
NewSigner(cfg) and NewSignerWithService(cfg, service) keep the same
signatures (awsv2 additionally accepts optional SignerOptions).

Update USER_GUIDE.md to a single signer/awsv2 example, document the removal
in UPGRADING_V5.md, and record it in the CHANGELOG.

Co-authored-by: Ryan Yuan <ryan.yuan@crowdstrike.com>
Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -163,7 +163,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Changed
 
-- Reorganize the documentation. Split `UPGRADING.md` into a version-history index plus per-major-version guides (`UPGRADING_V5.md` through `UPGRADING_V2.md`) and rename `opensearchapi/MIGRATING.md` to `opensearchapi/UPGRADING_V4_TO_V5.md`. Group the `guides/` and `_samples/` files by subsystem (`transport-`, `indexing-`, `usage-`, `config-`) and add a `guides/README.md` index. Make `guides/usage-error_handling.md` the single source for partial-error handling and `guides/transport-retry_backoff.md` the single source for resurrection-timeout config, replacing the duplicated copies in `opensearchapi/README.md` and `guides/transport-routing.md` with links. Add package documentation (`doc.go`) for `opensearchapi`, `plugins`, `signer`, and `signer/awsv2`. No functional change; the `signer/awsv2` `doc.go` carries a `Deprecated:` directive (see Deprecated below)
+- Reorganize the documentation. Split `UPGRADING.md` into a version-history index plus per-major-version guides (`UPGRADING_V5.md` through `UPGRADING_V2.md`) and rename `opensearchapi/MIGRATING.md` to `opensearchapi/UPGRADING_V4_TO_V5.md`. Group the `guides/` and `_samples/` files by subsystem (`transport-`, `indexing-`, `usage-`, `config-`) and add a `guides/README.md` index. Make `guides/usage-error_handling.md` the single source for partial-error handling and `guides/transport-retry_backoff.md` the single source for resurrection-timeout config, replacing the duplicated copies in `opensearchapi/README.md` and `guides/transport-routing.md` with links. Add package documentation (`doc.go`) for `opensearchapi`, `plugins`, `signer`, and `signer/awsv2`.
 - Trim the CI compatibility matrix to the currently-patched OpenSearch set (2.19.x and 3.x) per the 12-month support policy; older lines (1.3.x - 2.18.x) are no longer part of the tested matrix and the 4.x client remains their supported path. No client code change ([#856](https://github.com/opensearch-project/opensearch-go/issues/856))
 - **BREAKING**: Module path is now `github.com/opensearch-project/opensearch-go/v5`. Update import paths from `/v4` to `/v5`; the in-source `opensearchapi.X` package qualifier is unchanged
 - **BREAKING**: The code-generated API package is now the canonical `opensearchapi/`, replacing the hand-written v4 package (formerly previewed at `v5preview/opensearchapi/`). Req/Resp/Params types are fully typed and generated from the OpenAPI spec. See [`opensearchapi/UPGRADING_V4_TO_V5.md`](opensearchapi/UPGRADING_V4_TO_V5.md) for the field-level delta (`DocumentID` -> `ID`, optional `Params` becoming `*Params`, shared parameters moving into embedded `TimeoutParams`/`DebugParams`, `BulkResp.Items` becoming `[]BulkItem`) ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
@@ -199,10 +199,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
   - Enables proper context propagation for timeouts, cancellation, and graceful shutdown
   - Role compatibility validation prevents conflicting role assignments (master+cluster_manager, warm+search)
   - OpenSearch 3.0+ searchable snapshots now use `warm` role instead of deprecated `search` role
-- **BREAKING**: Migrate `signer/aws` package from AWS SDK v1 to AWS SDK v2 due to AWS SDK v1 reaching end-of-support on July 31, 2025
-  - Constructor now takes `aws.Config` instead of `session.Options`
-  - See USER_GUIDE.md for details required to migrate
-  - Users who need access to the existing `signer/awsv2` API can still use it, however they are encouraged to migrate to `signer/aws`
+- **BREAKING**: Remove the `signer/aws` package. Use `signer/awsv2`, whose name mirrors AWS's own SDK-version nomenclature. For callers on released v4 this is a full AWS SDK v1 -> v2 signer migration: the constructor input changes from `session.Options` to `aws.Config`, the return type becomes the `signer.Signer` interface, and the removed `OpenSearchService`/`OpenSearchServerless` constants become the `"es"`/`"aoss"` literals. See UPGRADING_V5.md and USER_GUIDE.md.
 - **BREAKING**: Replace `[]json.RawMessage` with typed `[]BulkByScrollFailure` for `Failures` field in `DocumentDeleteByQueryResp`, `UpdateByQueryResp`, and `ReindexResp` ([#797](https://github.com/opensearch-project/opensearch-go/issues/797)). This is a compile-time change only -- callers that were not accessing `.Failures` are unaffected, and callers that were manually unmarshaling `json.RawMessage` can now access typed fields directly.
 - Replace inline `_shards` struct with `ResponseShards` in `IndexResp`, `DocumentCreateResp`, `DocumentDeleteResp`, `UpdateResp`, `IndicesRefreshResp`, and `IndicesCountResp` to expose shard `Failures` and `Skipped` fields ([#797](https://github.com/opensearch-project/opensearch-go/issues/797)). Code accessing `resp.Shards.Total`, `resp.Shards.Successful`, or `resp.Shards.Failed` compiles unchanged.
 - Add `omitempty` to all deprecated `_type` JSON tags so empty values are omitted during marshaling
@@ -211,7 +208,6 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Deprecated
 
-- Mark the `signer/awsv2` package deprecated via a godoc `Deprecated:` directive in favor of `signer/aws`, which provides the same AWS SDK for Go v2 SigV4 signing and enables credential caching by default. The package remains fully functional; the directive is tooling-visible (`staticcheck` SA1019, gopls) and will nudge downstream callers toward `signer/aws`
 - Mark `opensearchtransport.Transport.Perform` and the `opensearch.Client.Perform` passthrough as deprecated; both remain fully functional in v4 (still buffering the response body via `io.ReadAll` + `NopCloser`) and will be removed in a future major version. New code should call `opensearch.Do[T]` for typed, decoded results or `opensearchtransport.Transport.Stream` / `opensearch.Client.Stream` for raw byte forwarding.
 - 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
 - Mark `opensearch.ToPointer` as deprecated; it remains fully functional but will be removed in a future major version. Once the module's go directive moves to 1.26, callers can drop the helper entirely in favor of native `new(value)` literal syntax (e.g. `new(false)`)

UPGRADING_V5.md

@@ -140,3 +140,33 @@ For responses decoded by `Client.Do`, the buffered bytes are also available with
 ```go
 raw := resp.RawBody() // nil for streamed or error responses; read resp.Body directly there
 ```
+
+## `signer/aws` removed in favor of `signer/awsv2`
+
+The `signer/aws` package is removed. Use `signer/awsv2`, whose name mirrors AWS's own SDK-version nomenclature.
+
+For callers coming from released v4, this is a full AWS SDK v1 -> v2 signer migration, not just an import swap: v4's `signer/aws` was built on AWS SDK for Go v1, while `signer/awsv2` is SDK v2.
+
+```go
+// Before (v4 signer/aws, AWS SDK v1)
+import requestsigner "github.com/opensearch-project/opensearch-go/v4/signer/aws"
+
+opts := session.Options{ /* ... */ }
+signer, err := requestsigner.NewSignerWithService(opts, requestsigner.OpenSearchServerless)
+
+// After (v5 signer/awsv2, AWS SDK v2)
+import requestsigner "github.com/opensearch-project/opensearch-go/v5/signer/awsv2"
+
+cfg, err := config.LoadDefaultConfig(context.TODO())
+// ...
+signer, err := requestsigner.NewSignerWithService(cfg, "aoss")
+```
+
+What changes:
+
+- **Constructor input**: `session.Options` becomes `aws.Config` (built with `config.LoadDefaultConfig`).
+- **Return type**: `*signer/aws.Signer` becomes the `signer.Signer` interface.
+- **Service constants**: `signer/aws` exported `OpenSearchService` (`"es"`) and `OpenSearchServerless` (`"aoss"`); `signer/awsv2` does not, so pass the `"es"` / `"aoss"` literal directly.
+- **Optional `SignerOptions`**: `signer/awsv2` additionally accepts functional `SignerOptions` to customize the underlying SigV4 signer.
+
+See [USER_GUIDE.md](USER_GUIDE.md#amazon-opensearch-service) for a full example.

USER_GUIDE.md

@@ -2,7 +2,6 @@
   - [Example](#example)
   - [Amazon OpenSearch Service](#amazon-opensearch-service)
     - [AWS SDK (v2)](#aws-sdk-v2)
-    - [Alternative: Using signer/awsv2](#alternative-using-signerawsv2)
   - [Custom Transport](#custom-transport)
   - [Guides by Topic](#guides-by-topic)
 
@@ -230,89 +229,14 @@ Before starting, we strongly recommend reading the full AWS documentation regard
 >
 > See [Managed Domains signing-service requests.](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#managedomains-signing-service-requests)
 
-Depending on the version of AWS SDK used, import the request signer from `signer/aws` (recommended) or `signer/awsv2`. Both signers use AWS SDK v2 and provide AWS Signature Version 4 (SigV4).
-
-**BREAKING CHANGE**: As of this version, the main `signer/aws` package has been migrated from AWS SDK v1 to AWS SDK v2 due to AWS SDK v1 reaching end-of-support on July 31, 2025.
+Import the request signer from `signer/awsv2`. It signs each request with AWS Signature Version 4 (SigV4) using AWS SDK for Go v2 and automatically discovers AWS credentials from the `~/.aws` folder or environment variables.
 
 To read more about SigV4 see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
 
-Here are some Go samples that show how to sign each OpenSearch request and automatically search for AWS credentials from the ~/.aws folder or environment variables:
+The signer caches credentials so SigV4 signing does not call `Credentials.Retrieve` on every request, which matters most for STS-backed providers (assume-role, web identity, IRSA).
 
 ### AWS SDK (v2)
 
-**Migration Note**: If you were previously using `signer/aws` with AWS SDK v1, you need to update your imports and configuration as shown below.
-
-**Credential Caching**: The signer automatically enables credential caching for improved performance, especially when using STS credentials (assume role, web identity, etc.). This reduces API calls to AWS STS and improves signing performance.
-
-```go
-package main
-
-import (
-	"context"
-	"fmt"
-	"os"
-
-	"github.com/aws/aws-sdk-go-v2/aws"
-	"github.com/aws/aws-sdk-go-v2/config"
-	requestsigner "github.com/opensearch-project/opensearch-go/v5/signer/aws"
-
-	"github.com/opensearch-project/opensearch-go/v5"
-	"github.com/opensearch-project/opensearch-go/v5/opensearchapi"
-)
-
-const IndexName = "go-test-index1"
-
-func main() {
-	if err := example(); err != nil {
-		fmt.Printf("Error: %s\n", err)
-		os.Exit(1)
-	}
-}
-
-const endpoint = "" // e.g. https://opensearch-domain.region.com
-
-func example() error {
-	ctx := context.Background()
-
-	// Load AWS configuration
-	awsCfg, err := config.LoadDefaultConfig(ctx)
-	if err != nil {
-		return err
-	}
-
-	// Create an AWS request Signer
-	signer, err := requestsigner.NewSignerWithService(awsCfg, requestsigner.OpenSearchService)
-	// Use requestsigner.OpenSearchServerless for Amazon OpenSearch Serverless
-	if err != nil {
-		return err
-	}
-
-	// Create an opensearch client and use the request-signer
-	client, err := opensearchapi.NewClient(
-		opensearchapi.Config{
-			Client: opensearch.Config{
-				Addresses: []string{endpoint},
-				Signer:    signer,
-			},
-		},
-	)
-	if err != nil {
-		return err
-	}
-
-    ping, err := client.Ping(ctx, nil)
-    if err != nil {
-        return err
-    }
-
-	fmt.Println(ping)
-
-	return nil
-}
-```
-
-### Alternative: Using signer/awsv2
-
 Use the AWS SDK v2 for Go to authenticate with Amazon OpenSearch service.
 
 ```go