Skip to main content

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}