Send `x-amzn-query-mode` to inform a service with the `awsQueryCompatible` trait that SDK is operating in that mode

ysaito1001 commented 1 month ago

Motivation and Context

If a client SDK is generated from a service model that has the awsQueryCompatible 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, 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 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 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:

Client SDKs that understand the awsQuery protocol (this group can interpret custom error codes sent in responses from the service)
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.

github-actions[bot] commented 1 month ago

A new generated diff is ready to view.

AWS SDK (ignoring whitespace)
Client Test (ignoring whitespace)
No codegen difference in the Server Test
No codegen difference in the Server Test Python
No codegen difference in the Server Test Typescript

A new doc preview is ready to view.

github-actions[bot] commented 1 month ago

A new generated diff is ready to view.

AWS SDK (ignoring whitespace)
Client Test (ignoring whitespace)
No codegen difference in the Server Test
Server Test Python (ignoring whitespace)
No codegen difference in the Server Test Typescript

A new doc preview is ready to view.

github-actions[bot] commented 1 month ago

A new generated diff is ready to view.

No codegen difference in the AWS SDK
Client Test (ignoring whitespace)
No codegen difference in the Server Test
No codegen difference in the Server Test Python
No codegen difference in the Server Test Typescript

A new doc preview is ready to view.

smithy-lang / smithy-rs