aws_smithy_runtime_api/client/behavior_version.rs
1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6//! Behavior version of the client
7
8/// Behavior version of the client
9///
10/// Over time, new best-practice behaviors are introduced. However, these behaviors might not be
11/// backwards compatible. For example, a change which introduces new default timeouts or a new
12/// retry-mode for all operations might be the ideal behavior but could break existing applications.
13#[derive(Copy, Clone, PartialEq)]
14pub struct BehaviorVersion {
15 inner: Inner,
16}
17
18#[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq)]
19enum Inner {
20 // IMPORTANT: Order matters here for the `Ord` derive. Newer versions go to the bottom.
21 V2023_11_09,
22 V2024_03_28,
23 V2025_01_17,
24 V2025_08_07,
25 V2026_01_12,
26 V2026_11_10,
27 V2026_11_17,
28}
29
30impl BehaviorVersion {
31 /// This method will always return the latest major version.
32 ///
33 /// This is the recommend choice for customers who aren't reliant on extremely specific behavior
34 /// characteristics. For example, if you are writing a CLI app, the latest behavior major
35 /// version is probably the best setting for you.
36 ///
37 /// If, however, you're writing a service that is very latency sensitive, or that has written
38 /// code to tune Rust SDK behaviors, consider pinning to a specific major version.
39 ///
40 /// The latest version is currently [`BehaviorVersion::v2026_11_17`]
41 pub fn latest() -> Self {
42 Self::v2026_11_17()
43 }
44
45 /// Behavior version for November 17th, 2026.
46 ///
47 /// This version applies a default read timeout to AWS SDK clients. The read timeout bounds the
48 /// span from request dispatch until response headers arrive, which is where an unresponsive
49 /// peer would otherwise leave a request hanging until the operating system gives up.
50 ///
51 /// The value depends on the service: 5 minutes generally, 15 minutes for services that
52 /// legitimately hold a connection open before replying, and no timeout at all for services
53 /// where any bound would break normal usage — a large upload cannot produce response headers
54 /// until the whole body has been sent, for instance, so S3 applies none.
55 ///
56 /// This bounds only the wait for response headers. It does not bound a transfer that has
57 /// started and then stalls; stalled stream protection already covers that.
58 ///
59 /// A `read_timeout` you configure yourself always wins, whether it is longer, shorter, or
60 /// disabled, and whether you set it on the client or per operation. To keep the previous
61 /// behavior for every service, pin to an earlier behavior version.
62 ///
63 /// For more information about behavior versions and how they affect SDK behavior, see the
64 /// [AWS SDK for Rust Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/behavior-versions.html).
65 pub fn v2026_11_17() -> Self {
66 Self {
67 inner: Inner::V2026_11_17,
68 }
69 }
70
71 /// Behavior version for November 10th, 2026.
72 ///
73 /// This version updates retry behavior per the Retry Behavior 2.1 spec:
74 /// - Non-throttling errors use 50ms base backoff (previously 1s)
75 /// - Token bucket costs: 14 for non-throttling, 5 for throttling (previously 5/10)
76 /// - HTTP 5xx status codes no longer trigger connection poisoning
77 /// - `x-amz-retry-after` header bounded between exponential backoff and 5s above it
78 #[deprecated(
79 since = "1.22.0",
80 note = "Superseded by v2026_11_17, which applies a default read timeout to AWS SDK clients."
81 )]
82 pub fn v2026_11_10() -> Self {
83 Self {
84 inner: Inner::V2026_11_10,
85 }
86 }
87
88 /// Behavior version for January 12th, 2026.
89 ///
90 /// This version enables retries by default for AWS SDK clients. Generic Smithy clients
91 /// (non-AWS) do not have retries enabled by default.
92 ///
93 /// Additionally, this version sets a 3.1 second connect timeout for all clients.
94 ///
95 /// For more information about behavior versions and how they affect SDK behavior, see the
96 /// [AWS SDK for Rust Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/behavior-versions.html).
97 #[deprecated(
98 since = "1.20.0",
99 note = "Superseded by v2026_11_10, which updates retry behavior per the Retry Behavior 2.1 spec."
100 )]
101 pub fn v2026_01_12() -> Self {
102 Self {
103 inner: Inner::V2026_01_12,
104 }
105 }
106
107 /// Behavior version for August 7th, 2025.
108 ///
109 /// This version updates the default HTTPS client to support proxy environment variables
110 /// (e.g. `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) by default.
111 #[deprecated(
112 since = "1.10.0",
113 note = "Superseded by v2026_01_12, which enables retries by default for AWS SDK clients and sets a 3.1s connect timeout for all clients."
114 )]
115 pub fn v2025_08_07() -> Self {
116 Self {
117 inner: Inner::V2025_08_07,
118 }
119 }
120
121 /// Behavior version for January 17th, 2025
122 ///
123 /// This version updates the default HTTP client and TLS stack. SDKs shipped with
124 /// a pre 1.x version of hyper and rustls originally. This behavior version updates
125 /// the HTTP+TLS stack to maintained versions.
126 ///
127 /// <div class="warning">
128 /// NOTE: In a future release behavior versions prior to this will require enabling
129 /// feature flags manually to keep the legacy Hyper stack as the default. Specifically the
130 /// `aws-smithy-runtime/tls-rustls` feature flag combined with an older behavior version.
131 /// </div>
132 #[deprecated(
133 since = "1.9.0",
134 note = "Superseded by v2025_08_07, which enables automatic HTTP(S) proxy support from environment variables in the default HTTPS client."
135 )]
136 pub fn v2025_01_17() -> Self {
137 Self {
138 inner: Inner::V2025_01_17,
139 }
140 }
141
142 /// Behavior version for March 28th, 2024.
143 ///
144 /// This version enables stalled stream protection for uploads (request bodies) by default.
145 ///
146 /// When a new behavior major version is released, this method will be deprecated.
147 #[deprecated(
148 since = "1.8.0",
149 note = "Superseded by v2025_01_17, which updates the default HTTPS client stack."
150 )]
151 pub fn v2024_03_28() -> Self {
152 Self {
153 inner: Inner::V2024_03_28,
154 }
155 }
156
157 /// Behavior version for November 9th, 2023.
158 #[deprecated(
159 since = "1.4.0",
160 note = "Superseded by v2024_03_28, which enabled stalled stream protection for uploads (request bodies) by default."
161 )]
162 pub fn v2023_11_09() -> Self {
163 Self {
164 inner: Inner::V2023_11_09,
165 }
166 }
167
168 /// True if this version is newer or equal to the given `other` version.
169 pub fn is_at_least(&self, other: BehaviorVersion) -> bool {
170 self.inner >= other.inner
171 }
172}
173
174impl std::fmt::Debug for BehaviorVersion {
175 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
176 f.debug_tuple("BehaviorVersion").field(&self.inner).finish()
177 }
178}
179
180#[cfg(test)]
181mod tests {
182 use super::*;
183
184 #[test]
185 #[allow(deprecated)]
186 fn version_comparison() {
187 assert!(BehaviorVersion::latest() == BehaviorVersion::latest());
188 assert!(BehaviorVersion::v2023_11_09() == BehaviorVersion::v2023_11_09());
189 assert!(BehaviorVersion::v2024_03_28() != BehaviorVersion::v2023_11_09());
190 assert!(BehaviorVersion::v2025_01_17() != BehaviorVersion::v2024_03_28());
191 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::latest()));
192 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2023_11_09()));
193 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2024_03_28()));
194 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2025_01_17()));
195 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2025_08_07()));
196 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2026_01_12()));
197 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2026_11_10()));
198 assert!(BehaviorVersion::latest().is_at_least(BehaviorVersion::v2026_11_17()));
199 assert!(!BehaviorVersion::v2023_11_09().is_at_least(BehaviorVersion::v2024_03_28()));
200 assert!(!BehaviorVersion::v2026_11_10().is_at_least(BehaviorVersion::v2026_11_17()));
201 assert!(Inner::V2024_03_28 > Inner::V2023_11_09);
202 assert!(Inner::V2023_11_09 < Inner::V2024_03_28);
203 assert!(Inner::V2024_03_28 < Inner::V2025_01_17);
204 assert!(Inner::V2025_01_17 < Inner::V2025_08_07);
205 assert!(Inner::V2025_08_07 < Inner::V2026_01_12);
206 assert!(Inner::V2026_01_12 < Inner::V2026_11_10);
207 assert!(Inner::V2026_11_10 < Inner::V2026_11_17);
208 }
209}