Skip to main content

aws_s3_transfer/
client.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6use crate::config::{ConcurrencyMode, MemoryConfig, PartSize};
7#[cfg(not(target_family = "wasm"))]
8use crate::runtime::ManagedExecution;
9use crate::scheduler::{ConcurrencyController, FixedConcurrency, Scheduler};
10use crate::telemetry::Telemetry;
11use crate::types::ByteSize;
12use crate::Config;
13use std::sync::Arc;
14use std::time::Duration;
15
16use crate::memory::BufferPool;
17use crate::runtime::sizing::{self, ResourcePlan, Signals};
18use crate::runtime::ExecutionRuntime;
19
20/// Transfer manager client for Amazon Simple Storage Service.
21#[derive(Debug, Clone)]
22pub struct Client {
23    pub(crate) handle: Arc<Handle>,
24}
25
26/// Shared state backing every transfer operation: configuration, the S3 client,
27/// the scheduler, the execution runtime, the concurrency controller, telemetry,
28/// and the shared payload-memory pool.
29#[derive(Debug)]
30pub(crate) struct Handle {
31    pub(crate) config: crate::Config,
32    pub(crate) s3_client: aws_sdk_s3::Client,
33    pub(crate) scheduler: Scheduler,
34    pub(crate) runtime: Arc<dyn ExecutionRuntime>,
35    pub(crate) controller: Arc<dyn ConcurrencyController>,
36    pub(crate) telemetry: Arc<Telemetry>,
37    pub(crate) buffer_pool: BufferPool,
38    /// Resource plan resolved when the client was constructed.
39    pub(crate) plan: ResourcePlan,
40    /// Per-bucket retry token bucket, cached so all operations and retries to a
41    /// given bucket share one live token bucket. The SDK does not share a bucket
42    /// across custom retry partitions, and a partition built per operation would
43    /// start full every time, defeating the shared throttle budget and its refill.
44    /// Unbounded: a client targets few distinct buckets, and entries are cheap
45    /// (Arc-shared bucket + name). Invariant: an entry that operations may still be
46    /// retrying against must not be dropped — replacing a live draining bucket with
47    /// a fresh full one reintroduces the per-operation-fresh-bucket bug.
48    retry_partitions: std::sync::Mutex<
49        std::collections::HashMap<String, aws_sdk_s3::config::retry::RetryPartition>,
50    >,
51}
52
53impl Handle {
54    /// Reports newly registered scheduler work to client-owned subsystems.
55    ///
56    /// The callback runs while the scheduler holds its registry write lock.
57    /// Keeping the adaptation here lets the scheduler publish lifecycle events
58    /// without depending on the policy each client subsystem applies to them.
59    pub(crate) fn scheduler_work_registered(&self) {
60        self.buffer_pool.record_managed_activity();
61    }
62
63    /// Reports that the scheduler has no registered or dispatched work.
64    ///
65    /// The scheduler holds its registry read lock through this callback, so a
66    /// concurrent registration either precedes this event or invalidates it
67    /// through [`Self::scheduler_work_registered`].
68    pub(crate) fn scheduler_became_idle(&self) {
69        self.buffer_pool.record_global_idle();
70    }
71
72    /// Get the concrete minimum upload size in bytes to use to determine whether multipart uploads
73    /// are enabled for a given request.
74    pub(crate) fn mpu_threshold_bytes(&self) -> u64 {
75        match self.config.multipart_threshold() {
76            PartSize::Auto => ByteSize::mib(16).as_u64(),
77            PartSize::Target(explicit) => explicit.as_u64(),
78        }
79    }
80
81    /// Part size for uploads and downloads.
82    pub(crate) fn part_size_bytes(&self) -> u64 {
83        self.plan.part_size
84    }
85
86    /// Whether the user pinned an explicit part size (vs leaving it `Auto`).
87    /// When `Auto`, the transfer manager owns part sizing and may override it
88    /// (e.g. align download ranges to an object's stored part size for
89    /// validation); an explicit size is respected as set.
90    pub(crate) fn user_set_part_size(&self) -> bool {
91        matches!(self.config.part_size(), PartSize::Target(_))
92    }
93
94    /// Per-operation config override that keys the retry token bucket by bucket.
95    ///
96    /// Returns an empty override when no bucket is set, which merges as a no-op.
97    /// The partition is cached so all operations to the same bucket share one
98    /// live token bucket (and its refill): under a total outage the sustained
99    /// retry rate to S3 is `REFILL_RATE / throttling_retry_cost` (approx 2
100    /// retries/sec per bucket), independent of concurrency.
101    pub(crate) fn bucket_partition_override(
102        &self,
103        bucket: Option<&str>,
104    ) -> aws_sdk_s3::config::Builder {
105        let builder = aws_sdk_s3::config::Builder::default();
106        match bucket {
107            Some(b) => {
108                let partition = {
109                    let mut map = self.retry_partitions.lock().expect("lock poisoned");
110                    map.entry(b.to_owned())
111                        .or_insert_with(|| crate::retry::bucket_retry_partition(b))
112                        .clone()
113                };
114                builder.retry_partition(partition)
115            }
116            None => builder,
117        }
118    }
119
120    /// Per-operation config override for a transfer body (download GET or upload):
121    /// bucket retry partition plus the tightened stalled-stream grace.
122    fn transfer_override(&self, bucket: Option<&str>) -> aws_sdk_s3::config::Builder {
123        self.bucket_partition_override(bucket)
124            .stalled_stream_protection(crate::retry::tightened_ssp())
125    }
126
127    /// Per-operation config override for a download GET: bucket retry partition
128    /// plus the tightened stalled-stream grace on the response body. Intentionally
129    /// identical to [`upload_override`](Self::upload_override) (both delegate to
130    /// `transfer_override`); the two names document the call site's direction.
131    pub(crate) fn download_get_override(
132        &self,
133        bucket: Option<&str>,
134    ) -> aws_sdk_s3::config::Builder {
135        self.transfer_override(bucket)
136    }
137
138    /// Per-operation config override for an upload (UploadPart / PutObject):
139    /// bucket retry partition plus the tightened stalled-stream grace on the
140    /// request body. Intentionally identical to
141    /// [`download_get_override`](Self::download_get_override); the two names
142    /// document the call site's direction.
143    pub(crate) fn upload_override(&self, bucket: Option<&str>) -> aws_sdk_s3::config::Builder {
144        self.transfer_override(bucket)
145    }
146
147    /// Create a Handle for testing on the ambient tokio runtime with a fixed
148    /// concurrency target. The ergonomic common case; tests that need a custom
149    /// runtime or a controller they drive directly use
150    /// [`new_for_test_with_runtime`](Self::new_for_test_with_runtime).
151    #[cfg(test)]
152    pub(crate) fn new_for_test(config: crate::Config, concurrency: usize) -> Arc<Self> {
153        Self::new_for_test_with_runtime(
154            config,
155            Arc::new(crate::scheduler::FixedConcurrency::new(concurrency)),
156            |weak| Arc::new(crate::runtime::TokioMultiThreadRuntime::new(weak)),
157        )
158    }
159
160    /// Test handle using the ambient tokio runtime (no OS threads spawned).
161    ///
162    /// Use for: state machine logic, poll_work/execute correctness, mock SDK
163    /// interactions. Fast and deterministic.
164    ///
165    /// Does NOT exercise: managed thread dispatch, per-thread HTTP clients,
166    /// cross-runtime wake semantics.
167    #[cfg(test)]
168    pub(crate) fn test_handle_tokio(config: crate::Config) -> Arc<Self> {
169        Self::new_for_test(config, 128)
170    }
171
172    /// Test handle with up to four managed threads from detected topology.
173    ///
174    /// Use for: end-to-end dispatch/wake correctness, verifying behavior
175    /// under real thread scheduling. Catches bugs like missing `set_pending`
176    /// that only manifest when work is dispatched across thread boundaries.
177    ///
178    /// The outer test can use `#[tokio::test]` (single-thread) — managed
179    /// threads own their own runtimes independently.
180    #[cfg(test)]
181    pub(crate) fn test_handle_managed(config: crate::Config) -> Arc<Self> {
182        Self::new_for_test_with_runtime(
183            config,
184            Arc::new(crate::scheduler::FixedConcurrency::new(128)),
185            |weak| Arc::new(crate::runtime::ManagedExecution::for_test(weak, 4)),
186        )
187    }
188
189    /// Create a Handle for testing with a custom concurrency controller and
190    /// runtime factory. The controller is an axis because some tests drive its
191    /// target directly (e.g. an adjustable controller); most pass a
192    /// [`FixedConcurrency`](crate::scheduler::FixedConcurrency).
193    #[cfg(test)]
194    pub(crate) fn new_for_test_with_runtime(
195        mut config: crate::Config,
196        controller: Arc<dyn ConcurrencyController>,
197        runtime_factory: impl FnOnce(std::sync::Weak<Handle>) -> Arc<dyn ExecutionRuntime>,
198    ) -> Arc<Self> {
199        // Most client tests exercise scheduling rather than memory admission.
200        // Keep their automatic pool large enough not to become an incidental
201        // gate. 8 GiB fits in a 64-bit `usize`; on 32-bit the conversion
202        // saturates to `usize::MAX`.
203        const DEFAULT_TEST_MEMORY_BUDGET_BYTES: usize = {
204            let bytes = ByteSize::gib(8).as_u64();
205            if bytes > usize::MAX as u64 {
206                usize::MAX
207            } else {
208                bytes as usize
209            }
210        };
211
212        let memory_diagnostics = config.diagnostics().memory();
213        let buffer_pool = match config.memory() {
214            MemoryConfig::Auto => BufferPool::from_capacity(
215                crate::config::MemoryBudgetConfig::Limit(ByteSize::new(
216                    DEFAULT_TEST_MEMORY_BUDGET_BYTES as u64,
217                )),
218                None,
219                memory_diagnostics,
220            )
221            .expect("test buffer-pool configuration must be valid"),
222            MemoryConfig::Explicit(pool) => pool.clone(),
223        };
224        // Sized against this handle's own pool, so results do not depend on
225        // host memory.
226        let plan = sizing::resolve(Signals {
227            throughput_gbps: config.throughput_target_gbps(),
228            instance_type: None,
229            vcpus: 1,
230            ram_bytes: None,
231            connection_cap: crate::runtime::platform::ConnectionCap::from_descriptor_limit(None),
232            explicit_concurrency: Some(controller.target()),
233            explicit_part_size: match config.part_size() {
234                PartSize::Target(n) => Some(n.as_u64()),
235                PartSize::Auto => None,
236            },
237            ceiling_override_bytes: Some(
238                usize::try_from(buffer_pool.metrics().capacity_bytes()).unwrap_or(usize::MAX),
239            ),
240        });
241        Arc::new_cyclic(|weak| {
242            let scheduler = Scheduler::new(weak.clone());
243            let runtime = runtime_factory(weak.clone());
244            let s3_client = match config.take_s3_client_source() {
245                crate::config::S3ClientSource::Provided(client) => client,
246                crate::config::S3ClientSource::FromConfig(s3_config) => {
247                    aws_sdk_s3::Client::from_conf(s3_config.config)
248                }
249            };
250            Self {
251                config,
252                s3_client,
253                scheduler,
254                runtime,
255                controller,
256                telemetry: Arc::new(Telemetry::new(std::time::Duration::from_millis(500))),
257                buffer_pool,
258                plan,
259                retry_partitions: std::sync::Mutex::new(std::collections::HashMap::new()),
260            }
261        })
262    }
263}
264
265impl Drop for Handle {
266    fn drop(&mut self) {
267        self.runtime.shutdown();
268    }
269}
270
271impl Client {
272    /// Returns a non-owning observer of managed-runtime shutdown completion.
273    ///
274    /// Returns `Some` for automatically created and adopted managed runtimes,
275    /// and `None` for caller-owned Tokio execution. Retaining the observer does
276    /// not keep this client or its runtime owner alive. Waiting does not request
277    /// shutdown: release client clones and transfer ownership first.
278    pub fn shutdown_completion(&self) -> Option<crate::ShutdownCompletion> {
279        self.handle.runtime.shutdown_completion()
280    }
281
282    /// Creates a new client from a transfer manager config.
283    ///
284    /// # Panics
285    ///
286    /// Panics when a component the configuration selects cannot be constructed:
287    ///
288    /// - With the automatic memory configuration, the buffer pool cannot be
289    ///   sized for this machine: the OS page size is unavailable or produces an
290    ///   unsupported pool layout, or the detected memory is too small to hold
291    ///   one buffer. An explicitly configured [`BufferPool`] reports these
292    ///   conditions as errors from [`BufferPoolBuilder::build`] instead.
293    /// - With managed execution, the managed runtime cannot be started, for
294    ///   example because topology discovery fails or a managed thread cannot be
295    ///   created or initialized.
296    /// - With managed execution and no HTTP client configured on the S3
297    ///   configuration, the default HTTP transport cannot be constructed.
298    ///
299    /// [`BufferPoolBuilder::build`]: crate::memory::BufferPoolBuilder::build
300    pub fn new(mut config: Config) -> Client {
301        // Machine facts for auto-sizing: use the loader-detected profile if the
302        // config came through `ConfigLoader::load`, else detect locally (DMI +
303        // vCPU + RAM — cheap pseudo-file reads, no network). Detected once and
304        // shared by both the concurrency seed and the buffer pool.
305        let profile = config
306            .machine_profile()
307            .cloned()
308            .unwrap_or_else(crate::runtime::platform::MachineProfile::detect_local);
309
310        let client_features = crate::config::user_agent::client_features(&config, &profile);
311
312        let connection_cap = crate::runtime::platform::ConnectionCap::detect();
313        let explicit_pool_ceiling = match config.memory() {
314            MemoryConfig::Explicit(pool) => {
315                Some(usize::try_from(pool.metrics().capacity_bytes()).unwrap_or(usize::MAX))
316            }
317            MemoryConfig::Auto => None,
318        };
319        let plan = sizing::resolve(Signals {
320            throughput_gbps: config.throughput_target_gbps(),
321            instance_type: profile.instance_type.as_deref(),
322            vcpus: profile.vcpus,
323            ram_bytes: profile.ram_bytes,
324            connection_cap,
325            explicit_concurrency: match config.concurrency() {
326                ConcurrencyMode::Explicit(n) => Some(*n),
327                ConcurrencyMode::Auto | ConcurrencyMode::TargetThroughput(_) => None,
328            },
329            explicit_part_size: match config.part_size() {
330                PartSize::Target(n) => Some(n.as_u64()),
331                PartSize::Auto => None,
332            },
333            ceiling_override_bytes: explicit_pool_ceiling,
334        });
335
336        let (controller, telemetry): (Arc<dyn ConcurrencyController>, _) = (
337            Arc::new(FixedConcurrency::new(plan.concurrency)),
338            Arc::new(Telemetry::new(Duration::from_millis(500))),
339        );
340
341        // 2. Build Handle with Arc::new_cyclic so scheduler and runtime
342        //    can hold Weak<Handle> without creating a reference cycle.
343        let memory_diagnostics = config.diagnostics().memory();
344        let buffer_pool = match config.memory() {
345            MemoryConfig::Auto => BufferPool::from_capacity(
346                crate::config::MemoryBudgetConfig::Limit(ByteSize::new(plan.ceiling_bytes as u64)),
347                profile.ram_bytes,
348                memory_diagnostics,
349            )
350            .expect("memory configuration must resolve to supported pool geometry"),
351            MemoryConfig::Explicit(pool) => pool.clone(),
352        };
353        // Runtime HTTP is built only when it will be installed on an S3 client
354        // this transfer manager constructs.
355        let runtime_http = config.runtime_http(plan.connection_cap);
356        log_resource_sizing(&plan, &profile, &connection_cap, runtime_http.is_some());
357        // wasm targets have no managed execution; see `Managed`.
358        #[cfg(not(target_family = "wasm"))]
359        let managed = match config.managed_config_mut() {
360            Some(managed) => {
361                let owner = managed
362                    .build()
363                    .expect("failed to construct transfer manager execution");
364                let components = crate::runtime::prepare_components(&owner, runtime_http)
365                    .expect("failed to construct transfer manager HTTP transport");
366                Some((owner, components))
367            }
368            None => None,
369        };
370        let handle = Arc::new_cyclic(|weak_handle| {
371            let scheduler = Scheduler::new(weak_handle.clone());
372            #[cfg(not(target_family = "wasm"))]
373            let runtime: Arc<dyn ExecutionRuntime> = match managed {
374                Some((owner, components)) => Arc::new(ManagedExecution::new(
375                    weak_handle.clone(),
376                    owner,
377                    components,
378                )),
379                None => Arc::new(crate::runtime::TokioMultiThreadRuntime::new(
380                    weak_handle.clone(),
381                )),
382            };
383            #[cfg(target_family = "wasm")]
384            let runtime: Arc<dyn ExecutionRuntime> = Arc::new(
385                crate::runtime::TokioMultiThreadRuntime::new(weak_handle.clone()),
386            );
387
388            let s3_client = match config.take_s3_client_source() {
389                crate::config::S3ClientSource::Provided(client) => {
390                    crate::config::user_agent::install_on_client(client, client_features)
391                }
392                crate::config::S3ClientSource::FromConfig(s3_config) => {
393                    let mut builder = s3_config.config.to_builder();
394                    if let Some(http_client) = runtime.components().http_client() {
395                        builder = builder.http_client(http_client.clone());
396                    }
397                    crate::config::user_agent::install(&mut builder, client_features);
398                    aws_sdk_s3::Client::from_conf(builder.build())
399                }
400            };
401
402            Handle {
403                config,
404                s3_client,
405                scheduler,
406                runtime,
407                controller,
408                telemetry,
409                buffer_pool,
410                plan,
411                retry_partitions: std::sync::Mutex::new(std::collections::HashMap::new()),
412            }
413        });
414        Client { handle }
415    }
416
417    /// Returns the client's configuration
418    pub fn config(&self) -> &Config {
419        &self.handle.config
420    }
421
422    /// Returns point-in-time operational metrics for this client.
423    pub fn metrics(&self) -> crate::metrics::ClientMetrics {
424        crate::metrics::ClientMetrics::new(self.handle.buffer_pool.metrics())
425    }
426
427    /// Upload a single object to S3.
428    ///
429    /// Constructs a fluent builder for the
430    /// [`Upload`](crate::operation::upload::builders::UploadFluentBuilder) operation.
431    ///
432    /// # Examples
433    ///
434    /// ```no_run
435    /// use std::error::Error;
436    /// use std::path::Path;
437    /// use aws_s3_transfer::io::InputStream;
438    ///
439    /// async fn upload_file(
440    ///     client: &aws_s3_transfer::Client,
441    ///     path: impl AsRef<Path>
442    /// ) -> Result<(), Box<dyn Error>> {
443    ///     let stream = InputStream::from_path(path)?;
444    ///     let handle = client.upload()
445    ///         .bucket("my-bucket")
446    ///         .key("my-key")
447    ///         .body(stream)
448    ///         .initiate()?;
449    ///
450    ///     // initiate() will return before the transfer is complete.
451    ///     // Call the `join()` method on the returned handle to drive the transfer to completion.
452    ///     // The handle also reports status and metrics, adjusts scheduling, and aborts the transfer.
453    ///     let response = handle.join().await?;
454    ///     // ... do something with response
455    ///     Ok(())
456    /// }
457    ///
458    /// ```
459    pub fn upload(&self) -> crate::operation::upload::builders::UploadFluentBuilder {
460        crate::operation::upload::builders::UploadFluentBuilder::new(self.handle.clone())
461    }
462
463    /// Download a single object from S3.
464    ///
465    /// A single logical request may be split into many concurrent ranged `GetObject` requests
466    /// to improve throughput.
467    ///
468    /// Constructs a fluent builder for the
469    /// [`Download`](crate::operation::download::builders::DownloadFluentBuilder) operation.
470    ///
471    ///
472    /// # Examples
473    ///
474    /// ```no_run
475    /// use std::error::Error;
476    ///
477    /// async fn get_object(client: &aws_s3_transfer::Client) -> Result<(), Box<dyn Error>> {
478    ///
479    ///     let handle = client
480    ///         .download()
481    ///         .bucket("my-bucket")
482    ///         .key("my-key")
483    ///         .initiate()?;
484    ///
485    ///     // initiate() will return before the transfer is complete.
486    ///     // Call the `join()` method on the returned handle to drive the transfer to completion.
487    ///     // The handle also exposes the object metadata and body, reports status and metrics,
488    ///     // adjusts scheduling and read-ahead, and aborts the transfer.
489    ///     let response = handle.join().await?;
490    ///     // ... do something with response
491    ///     Ok(())
492    /// }
493    /// ```
494    pub fn download(&self) -> crate::operation::download::builders::DownloadFluentBuilder {
495        crate::operation::download::builders::DownloadFluentBuilder::new(self.handle.clone())
496    }
497
498    /// Download multiple objects from an Amazon S3 bucket to a local directory
499    ///
500    /// Each object is written at its full key under the destination directory.
501    /// The walker's prefix selects the objects and does not shorten their
502    /// paths. See [`DownloadObjectsInput`](crate::operation::download_objects::DownloadObjectsInput)
503    /// for how keys map to paths.
504    ///
505    /// Each object is written to a temporary file beside its destination path
506    /// and renamed into place when that object's download succeeds, replacing
507    /// any file already at that path. A successful `join` means the operating
508    /// system accepted every byte of each downloaded object and completed each
509    /// rename. The transfer manager does not call `sync_data` or `sync_all` on
510    /// the files, or synchronize any directory, including the directories it
511    /// creates, so success does not promise persistence across a system crash
512    /// or power loss.
513    ///
514    /// Constructs a fluent builder for the
515    /// [`DownloadObjects`](crate::operation::download_objects::builders::DownloadObjectsFluentBuilder) operation.
516    ///
517    /// # Examples
518    /// ```no_run
519    /// use std::path::PathBuf;
520    /// use aws_s3_transfer::error::Error;
521    /// use aws_s3_transfer::io::walk::S3Walker;
522    ///
523    /// async fn download_photos(
524    ///     client: &aws_s3_transfer::Client,
525    ///     dest: PathBuf
526    /// ) -> Result<(), Error> {
527    ///
528    ///     let handle = client
529    ///         .download_objects()
530    ///         .bucket("my-bucket")
531    ///         .walker(S3Walker::builder().prefix("photos/").build())
532    ///         .destination(dest)
533    ///         .initiate()?;
534    ///
535    ///     // wait for transfer to complete
536    ///     handle.join().await?;
537    ///
538    ///     Ok(())
539    /// }
540    ///
541    /// ```
542    pub fn download_objects(
543        &self,
544    ) -> crate::operation::download_objects::builders::DownloadObjectsFluentBuilder {
545        crate::operation::download_objects::builders::DownloadObjectsFluentBuilder::new(
546            self.handle.clone(),
547        )
548    }
549
550    /// Upload multiple objects from a local directory to an Amazon S3 bucket
551    ///
552    /// Constructs a fluent builder for the
553    /// [`UploadObjects`](crate::operation::upload_objects::builders::UploadObjectsFluentBuilder) operation.
554    ///
555    /// The default walk is not recursive: it uploads the regular files directly
556    /// inside the source directory and skips subdirectories. To upload a
557    /// directory tree, supply a walker built with
558    /// [`FsWalker::builder().recursive(true)`](crate::io::walk::FsWalkerBuilder::recursive),
559    /// as in the example below.
560    ///
561    /// Examples
562    /// ```no_run
563    /// use std::path::Path;
564    /// use aws_s3_transfer::error::Error;
565    /// use aws_s3_transfer::io::walk::FsWalker;
566    ///
567    /// async fn upload_directory(
568    ///     client: &aws_s3_transfer::Client,
569    ///     source: &Path,
570    /// ) -> Result<(), Error> {
571    ///
572    ///     let handle = client
573    ///         .upload_objects()
574    ///         .source(source)
575    ///         .bucket("my-bucket")
576    ///         .walker(FsWalker::builder().recursive(true).build())
577    ///         .initiate()?;
578    ///
579    ///     // wait for transfer to complete
580    ///     handle.join().await?;
581    ///
582    ///     Ok(())
583    /// }
584    ///
585    /// ```
586    pub fn upload_objects(
587        &self,
588    ) -> crate::operation::upload_objects::builders::UploadObjectsFluentBuilder {
589        crate::operation::upload_objects::builders::UploadObjectsFluentBuilder::new(
590            self.handle.clone(),
591        )
592    }
593}
594
595/// Logs the resolved sizing at `INFO`, a `WARN` when the part size exceeds the
596/// memory ceiling, and a `WARN` when the descriptor limit holds connections per
597/// host below the concurrency target.
598///
599/// `connection_cap_installed` is whether the cap is applied to a transport this
600/// client builds.
601fn log_resource_sizing(
602    plan: &ResourcePlan,
603    profile: &crate::runtime::platform::MachineProfile,
604    cap: &crate::runtime::platform::ConnectionCap,
605    connection_cap_installed: bool,
606) {
607    let soft = cap.descriptors.map(|limit| limit.soft);
608    let hard = cap.descriptors.and_then(|limit| limit.hard);
609    tracing::info!(
610        target: crate::telemetry::TARGET_CONCURRENCY,
611        concurrency_target = plan.concurrency,
612        source = plan.concurrency_source.as_str(),
613        throughput_gbps = ?plan.throughput_gbps,
614        instance_type = ?profile.instance_type,
615        vcpus = profile.vcpus,
616        memory_ceiling_bytes = plan.ceiling_bytes,
617        memory_detected = plan.memory_detected,
618        part_size_bytes = plan.part_size,
619        max_connections_per_host = plan.connection_cap,
620        connection_cap_installed,
621        soft_descriptor_limit = ?soft,
622        hard_descriptor_limit = ?hard,
623        "resolved resource sizing",
624    );
625
626    if plan.part_exceeds_ceiling {
627        tracing::warn!(
628            target: crate::telemetry::TARGET_CONCURRENCY,
629            part_size_bytes = plan.part_size,
630            memory_ceiling_bytes = plan.ceiling_bytes,
631            "part size exceeds the payload-memory ceiling, so transfers that use it fail; raise \
632             the memory ceiling or lower the part size",
633        );
634    }
635
636    if cap.limited_by_descriptors() && plan.concurrency > plan.connection_cap {
637        if connection_cap_installed {
638            tracing::warn!(
639                target: crate::telemetry::TARGET_CONCURRENCY,
640                max_connections_per_host = plan.connection_cap,
641                concurrency_target = plan.concurrency,
642                soft_descriptor_limit = ?soft,
643                hard_descriptor_limit = ?hard,
644                "the soft file-descriptor limit (RLIMIT_NOFILE) caps connections per host below \
645                 the concurrency target; requests beyond the cap wait for a connection. Raise the \
646                 soft limit to allow more connections",
647            );
648        } else {
649            tracing::warn!(
650                target: crate::telemetry::TARGET_CONCURRENCY,
651                max_connections_per_host = plan.connection_cap,
652                concurrency_target = plan.concurrency,
653                soft_descriptor_limit = ?soft,
654                hard_descriptor_limit = ?hard,
655                "the soft file-descriptor limit (RLIMIT_NOFILE) allows fewer connections per host \
656                 than the concurrency target; the supplied HTTP client is not capped by the \
657                 transfer manager and may fail to open connections past the limit. Raise the soft \
658                 limit or lower the concurrency target",
659            );
660        }
661    }
662}
663
664#[cfg(test)]
665mod tests {
666    use super::*;
667    use crate::config::RuntimeConfig;
668    use aws_smithy_runtime_api::client::http::SharedHttpClient;
669
670    fn test_config() -> crate::Config {
671        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
672        crate::Config::builder()
673            .sdk_client(s3_client)
674            .build()
675            .expect("valid config")
676    }
677
678    fn runtime_http_client(client: &Client) -> Option<&SharedHttpClient> {
679        client.handle.runtime.components().http_client()
680    }
681
682    /// A configured transport that polls file bodies on a plain thread,
683    /// retries the first PUT, and lets the test hold an active transfer.
684    #[derive(Debug)]
685    struct ThreadHttp {
686        started: Arc<tokio::sync::Semaphore>,
687        release: Arc<tokio::sync::Semaphore>,
688        bodies: Arc<std::sync::Mutex<Vec<Vec<u8>>>>,
689        execution: Option<aws_smithy_execution::ManagedRuntimeHandle>,
690        dispatches: Arc<std::sync::Mutex<Vec<aws_smithy_execution::RuntimePartitionId>>>,
691    }
692
693    impl aws_smithy_runtime_api::client::http::HttpConnector for ThreadHttp {
694        fn call(
695            &self,
696            request: aws_smithy_runtime_api::client::orchestrator::HttpRequest,
697        ) -> aws_smithy_runtime_api::client::http::HttpConnectorFuture {
698            use aws_smithy_runtime_api::client::orchestrator::HttpResponse;
699            use aws_smithy_types::body::SdkBody;
700            use http_body_1x::Body;
701            use std::pin::Pin;
702
703            assert_eq!(request.method(), "PUT");
704            if let Some(execution) = &self.execution {
705                let partition = execution
706                    .current_partition()
707                    .expect("transfer must execute on the adopted runtime");
708                self.dispatches.lock().unwrap().push(partition.id());
709            }
710            let started = self.started.clone();
711            let release = self.release.clone();
712            let bodies = self.bodies.clone();
713            let (completed, result) = tokio::sync::oneshot::channel();
714            std::thread::spawn(move || {
715                assert!(tokio::runtime::Handle::try_current().is_err());
716                let response = crate::runtime::test_util::block_on(async move {
717                    let first = bodies.lock().unwrap().is_empty();
718                    if first {
719                        started.add_permits(1);
720                        release.acquire().await.unwrap().forget();
721                    }
722                    let mut body = request.into_body();
723                    let mut bytes = Vec::new();
724                    while let Some(frame) =
725                        futures_util::future::poll_fn(|cx| Pin::new(&mut body).poll_frame(cx)).await
726                    {
727                        if let Ok(data) = frame.unwrap().into_data() {
728                            bytes.extend_from_slice(&data);
729                        }
730                    }
731                    bodies.lock().unwrap().push(bytes);
732                    HttpResponse::try_from(
733                        ::http::Response::builder()
734                            .status(if first { 500 } else { 200 })
735                            .header("etag", "\"test-etag\"")
736                            .body(SdkBody::empty())
737                            .unwrap(),
738                    )
739                    .unwrap()
740                });
741                let _ = completed.send(response);
742            });
743            aws_smithy_runtime_api::client::http::HttpConnectorFuture::new(async move {
744                Ok(result.await.unwrap())
745            })
746        }
747    }
748
749    // Real SDK requests, body replay, and owner retention are exercised together:
750    // the configured HTTP implementation polls outside managed execution.
751    #[cfg_attr(miri, ignore)]
752    #[test]
753    fn configured_sdk_http_uploads_files_and_retains_active_execution() {
754        use aws_sdk_s3::config::{Credentials, Region, SharedCredentialsProvider};
755        use aws_smithy_runtime_api::client::http::{http_client_fn, SharedHttpConnector};
756        use std::io::Write;
757
758        let caller = tokio::runtime::Builder::new_current_thread()
759            .enable_all()
760            .build()
761            .unwrap();
762        let mut file = tempfile::NamedTempFile::new().unwrap();
763        let payload = vec![0x5a; 128 * 1024];
764        file.write_all(&payload).unwrap();
765        let mut checksum = aws_smithy_checksums::ChecksumAlgorithm::Crc32.into_impl();
766        checksum.update(&payload);
767        let checksum = checksum.header_value().to_str().unwrap().to_owned();
768
769        let adopted: Option<(
770            RuntimeConfig,
771            bool,
772            Option<aws_smithy_execution::ManagedRuntimeHandle>,
773        )> = {
774            #[cfg(feature = "__unstable_ext")]
775            {
776                let owner = aws_smithy_execution::ManagedRuntime::builder()
777                    .topology(
778                        aws_smithy_execution::topology::Topology::detect()
779                            .unwrap()
780                            .with_max_placements(1),
781                    )
782                    .thread_name_prefix("adopted-upload")
783                    .pin_threads(false)
784                    .build()
785                    .unwrap();
786                let execution = owner.handle();
787                Some((
788                    RuntimeConfig::managed(crate::unstable::managed(owner)),
789                    true,
790                    Some(execution),
791                ))
792            }
793            #[cfg(not(feature = "__unstable_ext"))]
794            {
795                None
796            }
797        };
798        for (runtime, managed, adopted) in [
799            (RuntimeConfig::default(), true, None),
800            (RuntimeConfig::multi_thread_tokio(), false, None),
801        ]
802        .into_iter()
803        .chain(adopted)
804        {
805            caller.block_on(async {
806                let started = Arc::new(tokio::sync::Semaphore::new(0));
807                let release = Arc::new(tokio::sync::Semaphore::new(0));
808                let bodies = Arc::new(std::sync::Mutex::new(Vec::new()));
809                let dispatches = Arc::new(std::sync::Mutex::new(Vec::new()));
810                let owner_watch = adopted
811                    .as_ref()
812                    .map(|execution| execution.partitions()[0].spawn(std::future::pending::<()>()));
813                let connector = SharedHttpConnector::new(ThreadHttp {
814                    started: started.clone(),
815                    release: release.clone(),
816                    bodies: bodies.clone(),
817                    execution: adopted.clone(),
818                    dispatches: dispatches.clone(),
819                });
820                let sdk = aws_types::SdkConfig::builder()
821                    .http_client(http_client_fn(move |_, _| connector.clone()))
822                    .region(Region::new("us-west-2"))
823                    .credentials_provider(SharedCredentialsProvider::new(Credentials::new(
824                        "test", "test", None, None, "test",
825                    )))
826                    .behavior_version(aws_config::BehaviorVersion::latest())
827                    .build();
828                let client = Client::new(
829                    crate::Config::builder()
830                        .s3_config(&sdk)
831                        .runtime_config(runtime)
832                        .build()
833                        .expect("valid config"),
834                );
835                let components = client.handle.runtime.components();
836                assert!(
837                    components.http_client().is_none(),
838                    "unused managed HTTP must not be built"
839                );
840                assert_eq!(components.direct_io(), managed);
841                assert!(
842                    !components.direct_body_io(),
843                    "configured HTTP controls its polling thread"
844                );
845
846                let completion = client.shutdown_completion();
847                assert_eq!(completion.is_some(), managed);
848                let weak = Arc::downgrade(&client.handle);
849                let upload = client
850                    .upload()
851                    .bucket("test-bucket")
852                    .key("file")
853                    .checksum_strategy(
854                        crate::types::ChecksumStrategy::full_object(crate::types::checksum::Crc32)
855                            .with_expected_value(&checksum),
856                    )
857                    .body(crate::io::InputStream::from_path(file.path()).unwrap())
858                    .initiate()
859                    .unwrap();
860                tokio::time::timeout(Duration::from_secs(5), started.acquire())
861                    .await
862                    .unwrap()
863                    .unwrap()
864                    .forget();
865                drop(client);
866                assert!(
867                    weak.upgrade().is_some(),
868                    "active transfer retains execution owner"
869                );
870                release.add_permits(1);
871                let output = tokio::time::timeout(Duration::from_secs(10), upload.join())
872                    .await
873                    .unwrap()
874                    .unwrap();
875                assert!(
876                    output.upload_id().is_none(),
877                    "exercise single-PUT file body"
878                );
879                {
880                    let captured = bodies.lock().unwrap();
881                    assert_eq!(captured.len(), 2, "SDK retries the first PUT");
882                    assert!(
883                        captured.iter().all(|body| body == &payload),
884                        "both attempts replay the file"
885                    );
886                }
887                if let Some(execution) = &adopted {
888                    let observed = dispatches.lock().unwrap();
889                    assert_eq!(observed.len(), 2);
890                    assert!(observed.iter().all(|id| id.runtime_id() == execution.id()));
891                }
892                tokio::time::timeout(Duration::from_secs(5), async {
893                    // Terminal notification can precede the last work item's
894                    // retirement.
895                    while weak.upgrade().is_some() {
896                        tokio::task::yield_now().await;
897                    }
898                })
899                .await
900                .unwrap_or_else(|_| {
901                    panic!("finished transfer retains execution (managed={managed})")
902                });
903                if let Some(completion) = completion {
904                    tokio::time::timeout(Duration::from_secs(5), completion.wait())
905                        .await
906                        .unwrap()
907                        .unwrap();
908                }
909                if let Some(watch) = owner_watch {
910                    let error = tokio::time::timeout(Duration::from_secs(5), watch)
911                        .await
912                        .unwrap()
913                        .unwrap_err();
914                    assert!(
915                        error.is_cancelled(),
916                        "retained handles must not retain ownership"
917                    );
918                }
919            });
920        }
921    }
922
923    #[cfg(all(feature = "__unstable_ext", not(miri)))]
924    #[tokio::test]
925    async fn adopted_runtime_without_configured_http_uses_the_managed_preset() {
926        let owner = aws_smithy_execution::ManagedRuntime::builder()
927            .topology(
928                aws_smithy_execution::topology::Topology::detect()
929                    .unwrap()
930                    .with_max_placements(1),
931            )
932            .pin_threads(false)
933            .build()
934            .unwrap();
935        let execution = owner.handle();
936        let watch = execution.partitions()[0].spawn(std::future::pending::<()>());
937        let mut s3 = mock_s3_config().config.to_builder();
938        s3.set_http_client(None);
939        let client = Client::new(
940            crate::Config::builder()
941                .s3_config(crate::config::S3ClientConfig::from_sdk_builder(s3))
942                .runtime_config(RuntimeConfig::managed(crate::unstable::managed(owner)))
943                .build()
944                .expect("valid config"),
945        );
946        assert!(client
947            .handle
948            .config
949            .runtime_config()
950            .managed_config()
951            .is_some());
952        let components = client.handle.runtime.components();
953        assert!(components.http_client().is_some());
954        assert!(components.direct_io());
955        assert!(components.direct_body_io());
956        assert_eq!(
957            execution.partitions()[0].spawn(async { 42 }).await.unwrap(),
958            42,
959        );
960        drop(client);
961        assert!(tokio::time::timeout(Duration::from_secs(5), watch)
962            .await
963            .unwrap()
964            .unwrap_err()
965            .is_cancelled());
966    }
967
968    #[cfg(all(
969        feature = "__unstable_ext",
970        not(miri),
971        any(
972            target_os = "android",
973            target_os = "fuchsia",
974            target_os = "illumos",
975            target_os = "ios",
976            target_os = "linux",
977            target_os = "macos",
978            target_os = "solaris",
979            target_os = "tvos",
980            target_os = "visionos",
981            target_os = "watchos",
982        )
983    ))]
984    #[tokio::test]
985    async fn transport_construction_failure_drops_the_adopted_owner() {
986        let owner = aws_smithy_execution::ManagedRuntime::builder()
987            .topology(
988                aws_smithy_execution::topology::Topology::detect()
989                    .unwrap()
990                    .with_max_placements(1),
991            )
992            .pin_threads(false)
993            .build()
994            .unwrap();
995        let execution = owner.handle();
996        let watch = execution.partitions()[0].spawn(std::future::pending::<()>());
997        let mut s3 = mock_s3_config().config.to_builder();
998        s3.set_http_client(None);
999        let mut config = crate::Config::builder()
1000            .s3_config(crate::config::S3ClientConfig::from_sdk_builder(s3))
1001            .runtime_config(RuntimeConfig::managed(crate::unstable::managed(owner)))
1002            .build()
1003            .expect("valid config");
1004        // A NUL byte cannot be passed to the OS as an interface name, so building
1005        // the transport fails after the runtime owner has been adopted.
1006        config.network_interfaces = vec!["bad\0interface".to_owned()];
1007        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| Client::new(config)));
1008        assert!(result.is_err());
1009        assert!(tokio::time::timeout(Duration::from_secs(5), watch)
1010            .await
1011            .unwrap()
1012            .unwrap_err()
1013            .is_cancelled());
1014    }
1015
1016    #[cfg_attr(miri, ignore)]
1017    #[test]
1018    fn shared_tokio_without_configured_http_uses_sdk_defaults() {
1019        let mut s3 = mock_s3_config().config.to_builder();
1020        s3.set_http_client(None);
1021        let client = Client::new(
1022            crate::Config::builder()
1023                .s3_config(crate::config::S3ClientConfig::from_sdk_builder(s3))
1024                .runtime_config(RuntimeConfig::multi_thread_tokio())
1025                .build()
1026                .expect("valid config"),
1027        );
1028        let components = client.handle.runtime.components();
1029        assert!(components.http_client().is_none());
1030        assert!(!components.direct_io());
1031        assert!(!components.direct_body_io());
1032    }
1033
1034    fn mock_s3_config() -> crate::config::S3ClientConfig {
1035        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1036        crate::config::S3ClientConfig::from_sdk_builder(s3_client.config().to_builder())
1037    }
1038
1039    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1040    #[cfg_attr(miri, ignore)]
1041    #[test]
1042    fn managed_runtime_builds_http_for_s3_config() {
1043        let mut builder = mock_s3_config().config.to_builder();
1044        builder.set_http_client(None);
1045        let client = Client::new(
1046            crate::Config::builder()
1047                .s3_config(crate::config::S3ClientConfig::from_sdk_builder(builder))
1048                .build()
1049                .expect("valid config"),
1050        );
1051        assert!(runtime_http_client(&client).is_some());
1052        assert!(client.handle.runtime.components().direct_io());
1053        assert!(client.handle.runtime.components().direct_body_io());
1054    }
1055
1056    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1057    #[cfg_attr(miri, ignore)]
1058    #[test]
1059    fn managed_runtime_skips_http_for_provided_client() {
1060        let client = Client::new(test_config());
1061        assert!(runtime_http_client(&client).is_none());
1062    }
1063
1064    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1065    #[cfg_attr(miri, ignore)]
1066    #[test]
1067    fn managed_runtime_preserves_configured_http() {
1068        let config = crate::Config::builder()
1069            .s3_config(mock_s3_config())
1070            .build()
1071            .expect("valid config");
1072        let client = Client::new(config);
1073        assert!(runtime_http_client(&client).is_none());
1074    }
1075
1076    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1077    #[cfg_attr(miri, ignore)]
1078    #[test]
1079    fn handle_drop_shuts_down_runtime() {
1080        let handle = Handle::new_for_test(test_config(), 2);
1081        let weak = Arc::downgrade(&handle);
1082        drop(handle);
1083        assert!(weak.upgrade().is_none(), "Handle should be fully dropped");
1084    }
1085
1086    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1087    #[cfg_attr(miri, ignore)]
1088    #[test]
1089    fn client_clone_shares_handle() {
1090        let client = Client::new(test_config());
1091        let client2 = client.clone();
1092        assert!(Arc::ptr_eq(&client.handle, &client2.handle));
1093    }
1094
1095    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1096    #[cfg_attr(miri, ignore)]
1097    #[test]
1098    fn test_client_uses_the_explicit_buffer_pool() {
1099        let pool = BufferPool::from_capacity(
1100            crate::config::MemoryBudgetConfig::Limit(ByteSize::mib(16)),
1101            None,
1102            crate::config::MemoryDiagnosticsConfig::default(),
1103        )
1104        .unwrap();
1105        let carrier_size = pool.carrier_size();
1106        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1107        let config = crate::Config::builder()
1108            .sdk_client(s3_client)
1109            .memory(MemoryConfig::Explicit(pool.clone()))
1110            .build()
1111            .expect("valid config");
1112
1113        let client = Client::new(config);
1114        let reservation = pool
1115            .try_reserve(carrier_size)
1116            .unwrap()
1117            .expect("explicit pool reservation");
1118
1119        let client_metrics = client.metrics();
1120        let memory = client_metrics.memory();
1121        assert_eq!(memory.active_planned_demand_bytes(), carrier_size as u64);
1122        assert_eq!(memory.capacity_bytes(), pool.metrics().capacity_bytes());
1123        drop(reservation);
1124    }
1125
1126    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1127    #[cfg_attr(miri, ignore)]
1128    #[test]
1129    fn test_client_automatic_pool_starts_unprepared() {
1130        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1131        let config = crate::Config::builder()
1132            .sdk_client(s3_client)
1133            .machine_profile(Some(crate::runtime::platform::MachineProfile {
1134                instance_type: None,
1135                vcpus: 4,
1136                ram_bytes: Some(ByteSize::mib(512).as_usize()),
1137            }))
1138            .build()
1139            .expect("valid config");
1140        let client = Client::new(config);
1141        let client_metrics = client.metrics();
1142        let memory = client_metrics.memory();
1143
1144        assert!(memory.capacity_bytes() > 0);
1145        assert_eq!(memory.admitted_bytes(), 0);
1146        assert_eq!(memory.prepared_capacity_bytes(), 0);
1147    }
1148
1149    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1150    #[cfg_attr(miri, ignore)]
1151    #[test]
1152    fn test_handle_test_constructor_preserves_an_explicit_pool() {
1153        let pool = BufferPool::from_capacity(
1154            crate::config::MemoryBudgetConfig::Limit(ByteSize::mib(16)),
1155            None,
1156            crate::config::MemoryDiagnosticsConfig::default(),
1157        )
1158        .unwrap();
1159        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1160        let config = crate::Config::builder()
1161            .sdk_client(s3_client)
1162            .memory(MemoryConfig::Explicit(pool.clone()))
1163            .build()
1164            .expect("valid config");
1165
1166        let handle = Handle::new_for_test(config, 2);
1167        let reservation = pool
1168            .try_reserve(pool.carrier_size())
1169            .unwrap()
1170            .expect("explicit pool reservation");
1171
1172        assert_eq!(
1173            handle.buffer_pool.metrics().active_planned_demand_bytes(),
1174            pool.carrier_size() as u64
1175        );
1176        drop(reservation);
1177    }
1178
1179    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1180    #[cfg_attr(miri, ignore)]
1181    #[test]
1182    fn last_client_drop_releases_handle() {
1183        let client = Client::new(test_config());
1184        let weak = Arc::downgrade(&client.handle);
1185        let client2 = client.clone();
1186        drop(client);
1187        assert!(
1188            weak.upgrade().is_some(),
1189            "Handle alive while client2 exists"
1190        );
1191        drop(client2);
1192        assert!(weak.upgrade().is_none(), "Handle dropped after last client");
1193    }
1194
1195    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1196    #[cfg_attr(miri, ignore)]
1197    #[test]
1198    fn handle_drop_invalidates_weak_references() {
1199        let handle = Handle::new_for_test(test_config(), 2);
1200        let weak = Arc::downgrade(&handle);
1201        drop(handle);
1202        assert!(
1203            weak.upgrade().is_none(),
1204            "Weak should be invalid after Handle drop"
1205        );
1206    }
1207
1208    // --- concurrency resolution wiring ---
1209
1210    use crate::config::ConcurrencyMode;
1211    use crate::runtime::platform::{self, MachineProfile};
1212
1213    /// A profile with the given instance type and vCPU count, and no detected
1214    /// memory, so the ceiling is the no-detection fallback.
1215    fn profile(instance_type: Option<&str>, vcpus: usize) -> MachineProfile {
1216        MachineProfile {
1217            instance_type: instance_type.map(str::to_string),
1218            vcpus,
1219            ram_bytes: None,
1220        }
1221    }
1222
1223    fn config_with(mode: ConcurrencyMode, profile: Option<MachineProfile>) -> crate::Config {
1224        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1225        crate::config::Config::builder()
1226            .sdk_client(s3_client)
1227            .concurrency(mode)
1228            .machine_profile(profile)
1229            .build()
1230            .expect("valid config")
1231    }
1232
1233    // FIXME: crossbeam-epoch is incompatible with miri
1234    #[cfg_attr(miri, ignore)]
1235    #[test]
1236    fn client_new_wires_resolved_target_into_controller() {
1237        // The resolved target is the controller's target. Expected values come
1238        // from the pass because the descriptor cap depends on RLIMIT_NOFILE.
1239        let p = profile(Some("c8gn.16xlarge"), 64);
1240        let expected = sizing::resolve(Signals {
1241            throughput_gbps: None,
1242            instance_type: p.instance_type.as_deref(),
1243            vcpus: p.vcpus,
1244            ram_bytes: p.ram_bytes,
1245            connection_cap: platform::ConnectionCap::detect(),
1246            explicit_concurrency: None,
1247            explicit_part_size: None,
1248            ceiling_override_bytes: None,
1249        });
1250
1251        let client = Client::new(config_with(ConcurrencyMode::Auto, Some(p)));
1252
1253        assert_eq!(client.handle.controller.target(), expected.concurrency);
1254        assert_eq!(client.handle.part_size_bytes(), expected.part_size);
1255    }
1256
1257    // FIXME: crossbeam-epoch is incompatible with miri
1258    #[cfg_attr(miri, ignore)]
1259    #[test]
1260    fn client_new_sizes_an_automatic_pool_from_the_resolved_ceiling() {
1261        // `MemoryConfig::Auto` uses the resolved ceiling.
1262        let p = profile(None, 4);
1263        let config = crate::config::Config::builder()
1264            .sdk_client(aws_smithy_mocks::mock_client!(aws_sdk_s3, []))
1265            .machine_profile(Some(p))
1266            .build()
1267            .expect("valid config");
1268
1269        let client = Client::new(config);
1270        let configured = client.handle.buffer_pool.metrics().capacity_bytes();
1271
1272        // Carrier rounding can only round the ceiling down, never above it.
1273        assert!(configured <= client.handle.plan.ceiling_bytes as u64);
1274        assert!(configured > 0);
1275    }
1276
1277    // FIXME: crossbeam-epoch is incompatible with miri
1278    #[cfg_attr(miri, ignore)]
1279    #[test]
1280    fn configured_throughput_drives_the_resolved_target() {
1281        // A throughput target sets the controller's target.
1282        let client = Client::new(config_with(
1283            ConcurrencyMode::TargetThroughput(
1284                crate::config::TargetThroughput::gbps(100.0).unwrap(),
1285            ),
1286            Some(profile(None, 4)),
1287        ));
1288
1289        // Expected value from the pass, which seeds the target from 100 Gbps.
1290        let expected = sizing::resolve(Signals {
1291            throughput_gbps: Some(100.0),
1292            instance_type: None,
1293            vcpus: 4,
1294            ram_bytes: None,
1295            connection_cap: platform::ConnectionCap::detect(),
1296            explicit_concurrency: None,
1297            explicit_part_size: None,
1298            ceiling_override_bytes: None,
1299        });
1300        assert_eq!(client.handle.controller.target(), expected.concurrency);
1301        assert_eq!(client.handle.plan.throughput_gbps, Some(100.0));
1302    }
1303
1304    // FIXME: crossbeam-epoch is incompatible with miri
1305    #[cfg_attr(miri, ignore)]
1306    #[test]
1307    fn client_new_bypass_path_detects_locally() {
1308        // Without a profile on the config, Client::new detects locally. Off EC2
1309        // no instance type is detected, so the target is resolved from the
1310        // local vCPU count and memory, which the expected plan reads the same
1311        // way.
1312        let expected = sizing::resolve(Signals {
1313            throughput_gbps: None,
1314            instance_type: None,
1315            vcpus: platform::local_vcpus(),
1316            ram_bytes: platform::available_ram(),
1317            connection_cap: platform::ConnectionCap::detect(),
1318            explicit_concurrency: None,
1319            explicit_part_size: None,
1320            ceiling_override_bytes: None,
1321        });
1322        let client = Client::new(config_with(ConcurrencyMode::Auto, None));
1323        assert_eq!(client.handle.controller.target(), expected.concurrency);
1324    }
1325
1326    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1327    #[cfg_attr(miri, ignore)]
1328    #[test]
1329    fn retry_partition_is_cached_per_bucket() {
1330        // The retry partition (and its refilling token bucket) must be built once
1331        // per bucket and reused, not rebuilt per operation — a fresh partition
1332        // would carry a fresh full bucket, defeating the shared budget and refill.
1333        // The map is the observable of that reuse: repeated calls for one bucket
1334        // add exactly one entry, and distinct buckets each add their own. A
1335        // build-fresh-per-call regression never populates the map (stays empty).
1336        let handle = Handle::new_for_test(test_config(), 2);
1337
1338        // Same bucket, three calls: one cache entry, populated once.
1339        for _ in 0..3 {
1340            let _ = handle.bucket_partition_override(Some("bucket-a"));
1341        }
1342        assert_eq!(
1343            handle.retry_partitions.lock().unwrap().len(),
1344            1,
1345            "repeated calls for one bucket must reuse a single cached partition"
1346        );
1347
1348        // A second bucket adds its own entry; `None` adds nothing.
1349        let _ = handle.bucket_partition_override(Some("bucket-b"));
1350        let _ = handle.bucket_partition_override(None);
1351        let map = handle.retry_partitions.lock().unwrap();
1352        assert_eq!(map.len(), 2, "each distinct bucket caches one partition");
1353        assert!(map.contains_key("bucket-a") && map.contains_key("bucket-b"));
1354    }
1355
1356    // --- runtime mode selection ---
1357
1358    #[test]
1359    fn config_default_runtime_is_managed() {
1360        let config = config_with(ConcurrencyMode::Auto, None);
1361        assert!(config.runtime_config().managed_config().is_some());
1362    }
1363
1364    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1365    #[cfg_attr(miri, ignore)]
1366    #[test]
1367    fn client_new_with_managed_runtime() {
1368        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1369        let config = crate::Config::builder()
1370            .sdk_client(s3_client)
1371            .runtime_config(RuntimeConfig::default())
1372            .build()
1373            .expect("valid config");
1374        let _client = Client::new(config);
1375    }
1376
1377    // FIXME: crossbeam-epoch is incompatible with miri (https://github.com/crossbeam-rs/crossbeam/issues/1181)
1378    #[cfg_attr(miri, ignore)]
1379    #[tokio::test(flavor = "multi_thread")]
1380    async fn client_new_with_multi_thread_tokio_runtime() {
1381        let s3_client = aws_smithy_mocks::mock_client!(aws_sdk_s3, []);
1382        let config = crate::Config::builder()
1383            .sdk_client(s3_client)
1384            .runtime_config(RuntimeConfig::multi_thread_tokio())
1385            .build()
1386            .expect("valid config");
1387        let _client = Client::new(config);
1388    }
1389}