Send `x-amzn-query-mode` to inform a service with the `awsQueryCompatible`...
Send `x-amzn-query-mode` to inform a service with the `awsQueryCompatible` trait that SDK is operating in that mode (#3883) ## Motivation and Context If a client SDK is generated from a service model that has the [`awsQueryCompatible`](https://smithy.io/2.0/aws/protocols/aws-query-protocol.html#aws-protocols-awsquerycompatible-trait) trait, the SDK now sends `x-amzn-query-mode` in the request header for the service. ## Description The change in the PR itself is pretty simple, as said in the title. It's more important to understand why we are making these changes. The rest of the description will focus on the reason driving this change. The `awsQueryCompatible` trait, added by a service, is specifically for deserializing errors. It allows for deserializing errors in a backward compatible manner when the service migrates away from the AWS Query protocol. With [the awsQueryError trait](https://smithy.io/2.0/aws/protocols/aws-query-protocol.html#aws-protocols-awsqueryerror-trait), the AWS Query supports customizing error codes that is not supported in any other AWS protocol, e.g. ``` @awsQueryError( code: "AWS.SimpleQueueService.NonExistentQueue", httpResponseCode: 400 ) @error("client") structure QueueDoesNotExistException { message: String } ``` In short, the `awsQueryCompatible` trait makes it possible to continue using the custom error codes even when the service drops support for the AWS Query protocol and switches to other protocols such as `awsJson1_0` and `rpcv2Cbor` (see [example snippet](https://smithy.io/2.0/aws/protocols/aws-query-protocol.html#aws-protocols-awsquerycompatible-trait) in the Smithy documentation) The changes in this PR would be unnecessary if a service had originally supported only `@awsQuery` and had _atomically_ updated its Smithy model to replace `@awsQuery` with `@awsQueryCompatible` and `@awsJson1_0` in lockstep. However, that's not always the case in practice. Consider a service whose Smithy model supports two protocols: `@awsQuery` and `@awsJson1_0`. While the Rust SDK maintains [an ordered map of protocols](https://github.com/smithy-lang/smithy-rs/blob/de4bc4547df15e2472b9bca91c89f963ffad0b03/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/protocols/ClientProtocolLoader.kt#L38-L47) to determine which one to use, it’s possible for two groups of client SDKs to be generated over time, depending on which protocol was added first to the service: 1. Client SDKs that understand the `awsQuery` protocol (this group can interpret custom error codes sent in responses from the service) 2. Client SDKs that understand the `awsJson1_0` protocol (this group does not interpret custom error codes) Now, imagine if the service updated its Smithy model to remove `@awsQuery` and add `@awsQueryCompatible` (likely it would add the `awsQueryError` trait to an error structure somewhere as well). The supported protocols would then be `@awsJson1_0` and `@awsQueryCompatible`. Group 1 remains unaffected, as they can continue deserializing responses with custom error codes. However, group 2 would now be broken, as they would begin receiving custom error codes in responses due to the `awsQueryCompatible` trait. To prevent the issue for group 2 above, the `x-amzn-query-mode` header in this PR informs the service that it should only send back custom error codes if the client SDK is built with the `awsQueryCompatible` trait. With this update, client SDKs built only with the `awsJson1_0` will remain unaffected, as they do not send the `x-amzn-query-mode` header to the service and, therefore, will not receive custom error codes in response. ## Testing - Added a Kotlin test to check for the `x-amzn-query-mode` header - Added `x-amzn-query-mode` as a required header to a protocol test for the `awsQueryCompatible` ## Checklist - [x] For changes to the AWS SDK, generated SDK code, or SDK runtime crates, I have created a changelog entry Markdown file in the `.changelog` directory, specifying "aws-sdk-rust" in the `applies_to` key. ---- _By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._
Loading
Please register or sign in to comment