aws-s3-transfer 1.0.0

Transfer Manager for Amazon S3 - a high-performance data plane client for uploading and downloading objects and directories.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
/*
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

//! Machine-resource detection for runtime and memory-pool configuration.
//!
//! Detection is best-effort. Failure returns no value so each caller can apply
//! its documented fallback policy.

use std::path::{Path, PathBuf};

// Per-host connection cap for the managed-runtime connection pool, derived from
// the process descriptor limit and bounded by a fixed ceiling.

/// Fraction of the soft descriptor limit the connection pool may use. The
/// remainder is headroom for disk sinks, the directory walker, logging, and other
/// descriptors the process holds; bulk disk transfers can hold one open file per
/// in-flight connection.
const POOL_FD_BUDGET_FRACTION: f64 = 0.5;

/// Descriptors withheld from the connection budget for non-connection use.
///
/// That use (stdio, resolver sockets, logging, open transfer files) does not
/// scale with the soft limit, so below twice this value the reserve, not
/// [`POOL_FD_BUDGET_FRACTION`], bounds the budget.
const POOL_FD_RESERVE: usize = 64;

/// Ceiling on connections to one origin across all managed threads.
///
/// Above every concurrency target outside the largest accelerator families,
/// where the per-connection throughput assumed by the seed understates what a
/// connection delivers.
pub(crate) const MAX_CONNECTIONS_PER_HOST: usize = 4096;

/// Floor so a low descriptor limit does not cap the pool below a usable count.
const MIN_CONNECTIONS_PER_HOST: usize = 10;

/// The process's `RLIMIT_NOFILE`.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct DescriptorLimit {
    /// Soft limit, the one enforced on this process.
    pub(crate) soft: usize,
    /// Hard limit the soft limit can be raised to, or `None` when unlimited.
    pub(crate) hard: Option<usize>,
}

/// The per-host connection cap and the descriptor limit it was derived from.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct ConnectionCap {
    /// Maximum connections to one origin across all managed threads.
    pub(crate) max_per_host: usize,
    /// Descriptor limit detected at construction, if any.
    pub(crate) descriptors: Option<DescriptorLimit>,
}

impl ConnectionCap {
    /// Detect the descriptor limit and derive the cap from it.
    pub(crate) fn detect() -> Self {
        Self::from_descriptor_limit(descriptor_limit())
    }

    /// `clamp(min(soft × POOL_FD_BUDGET_FRACTION, soft - POOL_FD_RESERVE),
    /// MIN_CONNECTIONS_PER_HOST, MAX_CONNECTIONS_PER_HOST)`, or the ceiling when
    /// no limit is known. The floor applies even when the reserve exceeds the
    /// soft limit.
    pub(crate) fn from_descriptor_limit(descriptors: Option<DescriptorLimit>) -> Self {
        let max_per_host = descriptors
            .map_or(MAX_CONNECTIONS_PER_HOST, |limit| {
                descriptor_budget(limit.soft)
            })
            .clamp(MIN_CONNECTIONS_PER_HOST, MAX_CONNECTIONS_PER_HOST);
        Self {
            max_per_host,
            descriptors,
        }
    }

    /// Whether the descriptor budget, rather than the fixed ceiling, set the cap.
    pub(crate) fn limited_by_descriptors(&self) -> bool {
        self.max_per_host < MAX_CONNECTIONS_PER_HOST
    }
}

/// Connections the descriptor budget allows for a soft limit.
fn descriptor_budget(soft: usize) -> usize {
    let fraction = (soft as f64 * POOL_FD_BUDGET_FRACTION) as usize;
    fraction.min(soft.saturating_sub(POOL_FD_RESERVE))
}

/// `RLIMIT_NOFILE` on Unix; `None` where there is no descriptor limit or
/// detection fails.
///
/// Ref: getrlimit(2) <https://man7.org/linux/man-pages/man2/getrlimit.2.html>
#[cfg(unix)]
fn descriptor_limit() -> Option<DescriptorLimit> {
    use nix::sys::resource::{getrlimit, Resource};
    let (soft, hard) = getrlimit(Resource::RLIMIT_NOFILE).ok()?;
    parse_descriptor_limit(soft, hard, nix::sys::resource::RLIM_INFINITY)
}

#[cfg(not(unix))]
fn descriptor_limit() -> Option<DescriptorLimit> {
    None
}

/// Interpret raw `getrlimit` values. An infinite soft limit means no limit; an
/// infinite hard limit means the soft limit can be raised without bound.
///
/// Generic over the limit type because `rlim_t` is unsigned on most platforms
/// and signed on FreeBSD. Infinity is compared in that type before conversion.
#[cfg_attr(not(unix), allow(dead_code))]
fn parse_descriptor_limit<T>(soft: T, hard: T, infinity: T) -> Option<DescriptorLimit>
where
    T: Copy + PartialEq + TryInto<usize>,
{
    let finite = |limit: T| (limit != infinity).then(|| limit.try_into().unwrap_or(usize::MAX));
    let soft = finite(soft).filter(|&soft| soft > 0)?;
    Some(DescriptorLimit {
        soft,
        hard: finite(hard),
    })
}

/// Usable RAM from Linux-compatible procfs and cgroup interfaces.
///
/// Android exposes the same kernel interfaces even though its runtime page
/// size and userspace environment may differ from a conventional Linux host.
/// The smaller of physical memory and the process limit wins when both exist.
#[cfg(any(target_os = "android", target_os = "linux"))]
pub(crate) fn available_ram() -> Option<usize> {
    match (meminfo_total(), cgroup_mem_limit()) {
        (Some(total), Some(cgroup)) => Some(total.min(cgroup)),
        (total, None) => total,
        (None, cgroup) => cgroup,
    }
}

#[cfg(not(any(
    target_os = "android",
    target_os = "freebsd",
    target_os = "linux",
    target_os = "macos",
    target_os = "windows"
)))]
pub(crate) fn available_ram() -> Option<usize> {
    None
}

#[cfg(target_os = "freebsd")]
pub(crate) fn available_ram() -> Option<usize> {
    // hw.physmem is physical memory in bytes.
    // Ref: sysctlbyname(3)
    // <https://man.freebsd.org/cgi/man.cgi?query=sysctlbyname&sektion=3>
    let mut bytes: u64 = 0;
    let mut len = std::mem::size_of::<u64>();
    // SAFETY: `bytes` is writable for the input value of `len`; `hw.physmem`
    // is nul-terminated, and null `newp` with zero `newlen` performs a read.
    let result = unsafe {
        libc::sysctlbyname(
            c"hw.physmem".as_ptr(),
            (&mut bytes as *mut u64).cast(),
            &mut len,
            std::ptr::null_mut(),
            0,
        )
    };
    if result != 0 || len != std::mem::size_of::<u64>() || bytes == 0 {
        return None;
    }
    usize::try_from(bytes).ok()
}

#[cfg(target_os = "macos")]
pub(crate) fn available_ram() -> Option<usize> {
    // hw.memsize is total physical memory in bytes; macOS has no cgroup.
    // Ref: sysctl(3), hw.memsize key
    // <https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/sysctl.3.html>
    let mut bytes: u64 = 0;
    let mut len = std::mem::size_of::<u64>();
    // SAFETY: sysctlbyname writes a u64 into `bytes`; `len` holds its size. The
    // name is a valid nul-terminated string.
    let rc = unsafe {
        libc::sysctlbyname(
            c"hw.memsize".as_ptr(),
            (&mut bytes as *mut u64).cast(),
            &mut len,
            std::ptr::null_mut(),
            0,
        )
    };
    if rc == 0 && bytes > 0 {
        usize::try_from(bytes).ok()
    } else {
        None
    }
}

#[cfg(target_os = "windows")]
pub(crate) fn available_ram() -> Option<usize> {
    use windows_sys::Win32::System::SystemInformation::{GlobalMemoryStatusEx, MEMORYSTATUSEX};
    // ullTotalPhys is total physical memory in bytes.
    // Ref: GlobalMemoryStatusEx / MEMORYSTATUSEX
    // <https://learn.microsoft.com/windows/win32/api/sysinfoapi/nf-sysinfoapi-globalmemorystatusex>
    // SAFETY: a zeroed MEMORYSTATUSEX with dwLength set is the documented input;
    // GlobalMemoryStatusEx fills it and returns nonzero on success.
    let mut status: MEMORYSTATUSEX = unsafe { std::mem::zeroed() };
    status.dwLength = std::mem::size_of::<MEMORYSTATUSEX>() as u32;
    let ok = unsafe { GlobalMemoryStatusEx(&mut status) };
    if ok != 0 && status.ullTotalPhys > 0 {
        usize::try_from(status.ullTotalPhys).ok()
    } else {
        None
    }
}

#[cfg(any(target_os = "android", target_os = "linux"))]
fn meminfo_total() -> Option<usize> {
    parse_meminfo_total(&std::fs::read_to_string("/proc/meminfo").ok()?)
}

/// Effective cgroup memory limit for this process, container-aware: resolve the
/// process's cgroup path from /proc/self/cgroup, find the controller mount from
/// /proc/self/mountinfo, and take the min of `memory.max` (v2) /
/// `memory.limit_in_bytes` (v1) from the leaf cgroup up to the mount root (a
/// parent cgroup may impose a tighter limit). Tries v2, then v1 (hybrid). `None`
/// when no limit is set, then `available_ram` uses physical RAM.
///
/// Refs: cgroups(7) `/proc/<pid>/cgroup` <https://man7.org/linux/man-pages/man7/cgroups.7.html>;
/// cgroup v2 memory.max <https://docs.kernel.org/admin-guide/cgroup-v2.html>;
/// cgroup v1 memory.limit_in_bytes <https://docs.kernel.org/admin-guide/cgroup-v1/memory.html>
#[cfg(any(target_os = "android", target_os = "linux"))]
fn cgroup_mem_limit() -> Option<usize> {
    let proc_cgroup = std::fs::read_to_string("/proc/self/cgroup").ok()?;
    let mountinfo = std::fs::read_to_string("/proc/self/mountinfo").unwrap_or_default();
    min_limit(&cgroup_v2_files(&proc_cgroup, &mountinfo))
        .or_else(|| min_limit(&cgroup_v1_files(&proc_cgroup, &mountinfo)))
}

/// Read each candidate limit file and return the smallest real limit; "max" and
/// the v1 unlimited sentinel are ignored ("max" via `parse_cgroup_limit`, the
/// sentinel via `min` with physical RAM in `available_ram`).
#[cfg(any(target_os = "android", target_os = "linux"))]
fn min_limit(files: &[PathBuf]) -> Option<usize> {
    files
        .iter()
        .filter_map(|f| std::fs::read_to_string(f).ok())
        .filter_map(|s| parse_cgroup_limit(&s))
        .min()
}

/// Parse `MemTotal` (kB) from /proc/meminfo into bytes. The kernel always emits
/// this value in kB.
///
/// Ref: proc_meminfo(5) <https://man7.org/linux/man-pages/man5/proc_meminfo.5.html>
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn parse_meminfo_total(meminfo: &str) -> Option<usize> {
    let line = meminfo.lines().find(|l| l.starts_with("MemTotal:"))?;
    line.split_whitespace()
        .nth(1)?
        .parse::<usize>()
        .ok()?
        .checked_mul(1024)
}

/// Parse a cgroup memory-limit value into bytes. "max" (v2 unlimited) yields
/// `None`. The v1 unlimited sentinel is a huge number that `available_ram`
/// discards via `min` with physical RAM, so it needs no special case.
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn parse_cgroup_limit(raw: &str) -> Option<usize> {
    let raw = raw.trim();
    if raw == "max" {
        return None;
    }
    raw.parse().ok()
}

/// `memory.max` candidate paths for the cgroup v2 unified hierarchy, leaf-first.
/// Empty when this process has no v2 cgroup line.
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn cgroup_v2_files(proc_cgroup: &str, mountinfo: &str) -> Vec<PathBuf> {
    let Some(path) = cgroup_v2_path(proc_cgroup) else {
        return Vec::new();
    };
    let mount =
        mountinfo_mount(mountinfo, "cgroup2", None).unwrap_or_else(|| "/sys/fs/cgroup".to_string());
    walk_paths(&mount, &path, "memory.max")
}

/// `memory.limit_in_bytes` candidate paths for the cgroup v1 memory controller,
/// leaf-first. Empty when this process has no v1 memory cgroup line.
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn cgroup_v1_files(proc_cgroup: &str, mountinfo: &str) -> Vec<PathBuf> {
    let Some(path) = cgroup_v1_memory_path(proc_cgroup) else {
        return Vec::new();
    };
    let mount = mountinfo_mount(mountinfo, "cgroup", Some("memory"))
        .unwrap_or_else(|| "/sys/fs/cgroup/memory".to_string());
    walk_paths(&mount, &path, "memory.limit_in_bytes")
}

/// The cgroup path from a v2 unified line (`0::<path>`).
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn cgroup_v2_path(proc_cgroup: &str) -> Option<String> {
    proc_cgroup.lines().find_map(|line| {
        let mut fields = line.splitn(3, ':');
        match (fields.next(), fields.next(), fields.next()) {
            (Some("0"), Some(""), Some(path)) => Some(path.to_string()),
            _ => None,
        }
    })
}

/// The cgroup path from the v1 line whose controllers include `memory`
/// (`<id>:<controllers>:<path>`).
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn cgroup_v1_memory_path(proc_cgroup: &str) -> Option<String> {
    proc_cgroup.lines().find_map(|line| {
        let mut fields = line.splitn(3, ':');
        let (_id, controllers, path) = (fields.next()?, fields.next()?, fields.next()?);
        controllers
            .split(',')
            .any(|c| c == "memory")
            .then(|| path.to_string())
    })
}

/// Mount point of the first /proc/self/mountinfo entry matching `fstype` and, if
/// given, containing `super_opt` in its super options. mountinfo splits on " - "
/// into `<...> mountpoint options [optional]` and `<fstype> <source> <superopts>`.
///
/// Ref: proc_pid_mountinfo(5) <https://man7.org/linux/man-pages/man5/proc_pid_mountinfo.5.html>
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn mountinfo_mount(mountinfo: &str, fstype: &str, super_opt: Option<&str>) -> Option<String> {
    mountinfo.lines().find_map(|line| {
        let (left, right) = line.split_once(" - ")?;
        let mut right_fields = right.split_whitespace();
        if right_fields.next()? != fstype {
            return None;
        }
        if let Some(opt) = super_opt {
            let superopts = right_fields.nth(1).unwrap_or("");
            if !superopts.split(',').any(|o| o == opt) {
                return None;
            }
        }
        // mountpoint is the 5th field of the left part.
        left.split_whitespace().nth(4).map(str::to_string)
    })
}

/// Limit-file paths from `<mount><cgroup_path>` up to `<mount>`, leaf-first, so a
/// tighter parent limit is included.
#[cfg_attr(not(any(target_os = "android", target_os = "linux")), allow(dead_code))]
fn walk_paths(mount: &str, cgroup_path: &str, filename: &str) -> Vec<PathBuf> {
    let mount = Path::new(mount);
    let rel = cgroup_path.trim_start_matches('/');
    let mut dir = if rel.is_empty() {
        mount.to_path_buf()
    } else {
        mount.join(rel)
    };
    let mut out = Vec::new();
    loop {
        out.push(dir.join(filename));
        if dir == mount {
            break;
        }
        match dir.parent() {
            Some(parent) if parent.starts_with(mount) => dir = parent.to_path_buf(),
            _ => break,
        }
    }
    out
}

// ---------------------------------------------------------------------------
// Concurrency seeding
//
// Resolves `ConcurrencyMode::Auto` and a configured throughput target to a
// fixed in-flight request target. The target is derived from an estimate of the
// machine's network bandwidth: recognized EC2 instance families map to a
// per-vCPU Gbps rate (NIC bandwidth scales linearly with vCPU count within a
// family), and `target = ceil(gbps / GBPS_PER_CONN)`.
//
// `N` is target *in-flight work* (the scheduler's `poll_work` gate). The
// connection pool is capped separately, per host (`ConnectionCap`).
// ---------------------------------------------------------------------------

/// Floor on the concurrency seed derived from a throughput estimate.
const MIN_CONCURRENCY_SEED: usize = 10;

/// Ceiling on the concurrency seed.
const MAX_CONCURRENCY_SEED: usize = 10_000;

/// Assumed goodput per in-flight request, in Gbps. Matches CRT's per-connection
/// figure (`100 / 250`).
const GBPS_PER_CONN: f64 = 0.4;

/// In-flight requests per vCPU for the fallback seed, used when the instance
/// family is unknown (unrecognized type, or detection failed / off-EC2). Without
/// a NIC estimate the seed can't be bandwidth-derived, so it scales concurrency
/// directly by vCPU. In-flight requests are roughly connection-count, so the
/// slope is kept modest; the `[FALLBACK_MIN, MAX_CONCURRENCY_SEED]` clamp keeps a
/// small box off the floor and a large one bounded.
const FALLBACK_INFLIGHT_PER_VCPU: usize = 5;

/// Floor for the fallback seed. A small unknown box (2-6 vCPU) would otherwise
/// seed below common general-purpose defaults (CRT's 10 Gbps target resolves to
/// 25 connections). Floors the fallback so an unknown box gets a usable default,
/// while the recognized-family estimate keeps its own lower `MIN_CONCURRENCY_SEED` floor (a
/// genuinely small recognized box should seed low).
const FALLBACK_MIN: usize = 32;

/// Peak network bandwidth of each EC2 instance family, as the raw spec of its
/// largest member: `(family, max_nic_gbps, vcpus_at_that_size)`.
///
/// For multi-card families the figure is one card's bandwidth, since the
/// client uses one card unless network interfaces are configured.
///
/// There is no formula for a family's bandwidth — it is assigned per hardware
/// generation and read from the published EC2 network-performance spec (e.g.
/// c6gn tops out at 100 Gbps, c7gn at 200, same name stem). So this is a lookup
/// table, and each row is the spec verbatim: `("m6idn", 200.0, 128)` means
/// "m6idn's largest size delivers 200 Gbps on 128 vCPU." Storing the two source
/// numbers (rather than a pre-divided per-vCPU rate) keeps every row directly
/// checkable against the docs and avoids hand-computed quotients.
///
/// Within a family NIC bandwidth scales linearly with vCPU count, so the flagship
/// reproduces every smaller size: `gbps = max_gbps * (local_vcpus / vcpus_at_max)`
/// (see [`family_gbps_per_vcpu`]).
///
/// **Adding a family:** if a family's NIC is large enough that the seed matters,
/// add a row with its flagship's Gbps and vCPU count from the spec. Families left
/// out fall through to the vCPU-scaled fallback (fine — they are modest-NIC boxes
/// where the seed is low-stakes). Sustained figures only; burstable ("up to")
/// families are excluded so we never seed off a burst ceiling.
const FAMILY_NIC_GBPS: &[(&str, f64, u32)] = &[
    // Ultra-high (GPU / ML training / inference accelerators)
    // Multi-card: one card's bandwidth.
    ("p6-b300", 350.0, 192),
    ("p5", 400.0, 192),
    ("p5en", 100.0, 192),
    ("p5e", 100.0, 192),
    ("p6-b200", 200.0, 192),
    ("trn1n", 800.0, 128),
    ("p6e-gb200", 1700.0, 144),
    ("g7e", 1600.0, 192),
    ("trn1", 600.0, 128),
    ("dl1", 400.0, 96),
    ("p4d", 400.0, 96),
    ("p4de", 400.0, 96),
    ("g7", 700.0, 192),
    // Network-optimized (Graviton *gn, bandwidth-boost *gb)
    ("c7gn", 200.0, 64),
    ("c8gn", 600.0, 192),
    ("m8gn", 600.0, 192),
    ("r8gn", 600.0, 192),
    ("hpc7g", 200.0, 64),
    ("c8gb", 400.0, 192),
    ("m8gb", 400.0, 192),
    ("r8gb", 400.0, 192),
    ("m8azn", 200.0, 96),
    // Network-optimized *n / *dn / *idn (the S3-throughput workhorses)
    ("c6in", 200.0, 128),
    ("c8in", 600.0, 384),
    ("m6idn", 200.0, 128),
    ("m6in", 200.0, 128),
    ("m8idn", 600.0, 384),
    ("m8in", 600.0, 384),
    ("r6idn", 200.0, 128),
    ("r6in", 200.0, 128),
    ("r8idn", 600.0, 384),
    ("r8in", 600.0, 384),
    ("c6gn", 100.0, 64),
    ("im4gn", 100.0, 64),
    ("i8ge", 300.0, 192),
    ("c5n", 100.0, 72),
    // 100 Gbps-class general / storage / inference / *ib bandwidth-boost
    ("i3en", 100.0, 96),
    ("inf1", 100.0, 96),
    ("p3dn", 100.0, 96),
    ("c8ib", 400.0, 384),
    ("m8ib", 400.0, 384),
    ("m8idb", 400.0, 384),
    ("r8ib", 400.0, 384),
    ("r8idb", 400.0, 384),
    ("x2idn", 100.0, 128),
    ("x2iedn", 100.0, 128),
    ("i4i", 75.0, 128),
    ("f2", 100.0, 192),
    ("i7ie", 100.0, 192),
    ("inf2", 100.0, 192),
    // Above 1 Gbps per vCPU, which the vCPU fallback would under-seed.
    ("m5n", 100.0, 96),
    ("m5dn", 100.0, 96),
    ("r5n", 100.0, 96),
    ("r5dn", 100.0, 96),
    ("m5zn", 100.0, 48),
    ("x2iezn", 100.0, 48),
    ("d3en", 75.0, 48),
    ("is4gen", 50.0, 32),
    ("d3", 25.0, 32),
    ("c8ine", 75.0, 48),
    ("g4dn", 100.0, 96),
    ("g6e", 400.0, 192),
];

/// Machine facts detected once, off the client-construction hot path (in the
/// async config loader), and consumed when resolving auto-sized settings.
#[derive(Debug, Clone)]
pub(crate) struct MachineProfile {
    /// EC2 instance type (e.g. `"m6idn.16xlarge"`), from DMI or IMDS. `None`
    /// off-EC2 or when detection failed.
    pub(crate) instance_type: Option<String>,
    /// Usable vCPU count, honoring cgroup CPU quota and affinity.
    pub(crate) vcpus: usize,
    /// Usable RAM in bytes (cgroup-aware), or `None` when undetectable. Sizes the
    /// `Auto`/`Fraction` memory budget.
    pub(crate) ram_bytes: Option<usize>,
}

impl MachineProfile {
    /// Detect machine facts from local sources only: DMI instance type, vCPU
    /// count, and RAM. All are cheap pseudo-file reads (sysfs / procfs) or a
    /// syscall — no network — so this is safe to call synchronously on the
    /// `Client::new` path when no loader-detected profile is present.
    ///
    /// This does not attempt the IMDS instance-type fallback: IMDS is a network
    /// call and belongs to the async config loader, which assembles its own
    /// profile from these same primitives plus the IMDS step. A local DMI
    /// `NotEc2`/`Unknown` result therefore collapses to `instance_type: None`
    /// here — correct on the bypass path, where there is no IMDS to gate.
    pub(crate) fn detect_local() -> Self {
        let instance_type = match detect_instance_type_dmi() {
            DmiDetection::Instance(ty) => Some(ty),
            DmiDetection::NotEc2 | DmiDetection::Unknown => None,
        };
        Self {
            instance_type,
            vcpus: local_vcpus(),
            ram_bytes: available_ram(),
        }
    }
}

/// Usable vCPU count. `std::thread::available_parallelism` honors both the CPU
/// affinity mask and the cgroup CPU quota (CFS bandwidth) on Linux, so a
/// CPU-limited container reports its slice, not the host's core count. Falls
/// back to 1 if the count can't be determined.
pub(crate) fn local_vcpus() -> usize {
    std::thread::available_parallelism()
        .map(|n| n.get())
        .unwrap_or(1)
}

/// Outcome of local (DMI) instance-type detection. Distinguishes "known" and
/// "definitely not EC2" from "couldn't tell" so the caller can decide whether an
/// IMDS network fallback is worthwhile: a positive non-EC2 reading (readable DMI,
/// vendor is not Amazon) means IMDS would fail too, so it is skipped; only an
/// `Unknown` (unreadable DMI, e.g. a container or non-Linux) is worth an IMDS try.
// `Instance` and `NotEc2` are only constructed on Linux (the DMI-bearing
// target); the non-Linux stub returns `Unknown`. Allow dead code so non-Linux
// dev builds stay warning-clean without hiding real dead code on Linux.
#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum DmiDetection {
    /// Instance type read from DMI.
    Instance(String),
    /// DMI is readable and says this host is not EC2.
    NotEc2,
    /// DMI could not be read (container without DMI, non-Linux); inconclusive.
    Unknown,
}

/// Classify DMI reads into a [`DmiDetection`]. `vendor` is the `sys_vendor`
/// contents; `product` is `product_name`, `None` when that read failed. Split
/// from the file I/O so the three-state logic is testable without `/sys`.
///
/// A readable vendor that is not "Amazon EC2" is a definitive `NotEc2` (skip
/// IMDS). Vendor is EC2 but product is missing/empty ⇒ `Unknown` (let IMDS try).
#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
fn classify_dmi(vendor: &str, product: Option<&str>) -> DmiDetection {
    if !vendor.trim().eq_ignore_ascii_case("Amazon EC2") {
        return DmiDetection::NotEc2;
    }
    match product.map(str::trim) {
        Some(ty) if !ty.is_empty() => DmiDetection::Instance(ty.to_string()),
        _ => DmiDetection::Unknown,
    }
}

/// Detect the EC2 instance type from DMI, without any network call.
///
/// Reads `/sys/devices/virtual/dmi/id/sys_vendor` to confirm the host is EC2,
/// then `product_name` for the instance type. Mirrors the CRT S3 client's
/// primary detection path. Returns [`DmiDetection`] so the caller can gate the
/// IMDS fallback on `Unknown` vs `NotEc2`.
#[cfg(target_os = "linux")]
pub(crate) fn detect_instance_type_dmi() -> DmiDetection {
    let Ok(vendor) = std::fs::read_to_string("/sys/devices/virtual/dmi/id/sys_vendor") else {
        return DmiDetection::Unknown;
    };
    let product = std::fs::read_to_string("/sys/devices/virtual/dmi/id/product_name").ok();
    classify_dmi(&vendor, product.as_deref())
}

#[cfg(not(target_os = "linux"))]
pub(crate) fn detect_instance_type_dmi() -> DmiDetection {
    DmiDetection::Unknown
}

/// Per-vCPU Gbps for an instance type's family, or `None` if the family is not
/// in [`FAMILY_NIC_GBPS`]. The family is the substring before the first `.`
/// (`m6idn.16xlarge` -> `m6idn`); the rate is the flagship's
/// `max_nic_gbps / vcpus_at_max` (the linear within-family scale).
fn family_gbps_per_vcpu(instance_type: &str) -> Option<f64> {
    let family = instance_type.split('.').next()?;
    FAMILY_NIC_GBPS
        .iter()
        .find(|(name, _, _)| name.eq_ignore_ascii_case(family))
        .map(|(_, max_gbps, vcpus_at_max)| max_gbps / *vcpus_at_max as f64)
}

/// In-flight-request target from a throughput estimate: `ceil(gbps /
/// GBPS_PER_CONN)`, clamped to `[MIN_CONCURRENCY_SEED, MAX_CONCURRENCY_SEED]`.
pub(crate) fn seed_from_gbps(gbps: f64) -> usize {
    let n = (gbps / GBPS_PER_CONN).ceil();
    // f64 -> usize saturates negatives/NaN to 0; the clamp floor fixes that.
    (n as usize).clamp(MIN_CONCURRENCY_SEED, MAX_CONCURRENCY_SEED)
}

/// Source used to resolve [`ConcurrencyMode::Auto`].
///
/// [`ConcurrencyMode::Auto`]: crate::config::ConcurrencyMode::Auto
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum AutoConcurrencySource {
    /// The detected EC2 family supplied a network-bandwidth estimate.
    InstanceFamily,
    /// No family estimate was available, so the target scales with usable vCPUs.
    VcpuFallback,
}

/// Result of resolving automatic concurrency from one detected machine profile.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct ResolvedAutoConcurrency {
    /// Fixed in-flight work target installed in the scheduler.
    pub(crate) target: usize,
    /// Estimated network bandwidth when the instance family was recognized.
    pub(crate) estimated_gbps: Option<f64>,
    /// Machine signal from which the target was derived.
    pub(crate) source: AutoConcurrencySource,
}

/// Resolve automatic concurrency while retaining its diagnostic inputs.
pub(crate) fn resolve_auto_concurrency(
    instance_type: Option<&str>,
    vcpus: usize,
) -> ResolvedAutoConcurrency {
    match instance_type.and_then(family_gbps_per_vcpu) {
        Some(per_vcpu) => {
            let estimated_gbps = per_vcpu * vcpus as f64;
            ResolvedAutoConcurrency {
                target: seed_from_gbps(estimated_gbps),
                estimated_gbps: Some(estimated_gbps),
                source: AutoConcurrencySource::InstanceFamily,
            }
        }
        None => ResolvedAutoConcurrency {
            target: (FALLBACK_INFLIGHT_PER_VCPU * vcpus).clamp(FALLBACK_MIN, MAX_CONCURRENCY_SEED),
            estimated_gbps: None,
            source: AutoConcurrencySource::VcpuFallback,
        },
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn soft(soft: usize) -> Option<DescriptorLimit> {
        Some(DescriptorLimit { soft, hard: None })
    }

    #[test]
    fn test_cap_without_descriptor_limit_is_ceiling() {
        // No detection (non-Unix, getrlimit failed, or unlimited) -> the ceiling.
        let cap = ConnectionCap::from_descriptor_limit(None);
        assert_eq!(cap.max_per_host, MAX_CONNECTIONS_PER_HOST);
        assert!(!cap.limited_by_descriptors());
    }

    #[test]
    fn test_cap_low_descriptor_limit_is_floored() {
        // 8 descriptors: below the reserve, so the budget is zero and the floor
        // sets the cap.
        let cap = ConnectionCap::from_descriptor_limit(soft(8));
        assert_eq!(cap.max_per_host, MIN_CONNECTIONS_PER_HOST);
        assert!(cap.limited_by_descriptors());
    }

    #[test]
    fn test_cap_reserve_binds_below_twice_the_reserve() {
        // 100 descriptors: the fraction allows 50 and the reserve leaves 36.
        assert_eq!(
            ConnectionCap::from_descriptor_limit(soft(100)).max_per_host,
            36
        );
    }

    #[test]
    fn test_cap_reserve_does_not_bind_above_twice_the_reserve() {
        // 160 descriptors: the fraction allows 80 and the reserve leaves 96.
        assert_eq!(
            ConnectionCap::from_descriptor_limit(soft(160)).max_per_host,
            80
        );
    }

    #[test]
    fn test_cap_macos_default_limit() {
        // launchd's default soft limit of 256 -> 128 connections.
        assert_eq!(
            ConnectionCap::from_descriptor_limit(soft(256)).max_per_host,
            128
        );
    }

    #[test]
    fn test_cap_mid_descriptor_limit_is_fraction() {
        let cap = ConnectionCap::from_descriptor_limit(soft(1024));
        assert_eq!(cap.max_per_host, 512);
        assert!(cap.limited_by_descriptors());
    }

    #[test]
    fn test_cap_high_descriptor_limit_is_ceiling() {
        // 524288 descriptors -> 262144 by fraction -> the ceiling.
        let cap = ConnectionCap::from_descriptor_limit(soft(524_288));
        assert_eq!(cap.max_per_host, MAX_CONNECTIONS_PER_HOST);
        assert!(!cap.limited_by_descriptors());
    }

    #[test]
    fn test_cap_at_ceiling_boundary() {
        // Exactly 2 x ceiling descriptors reaches the ceiling, which is not
        // reported as descriptor-limited.
        let cap = ConnectionCap::from_descriptor_limit(soft(2 * MAX_CONNECTIONS_PER_HOST));
        assert_eq!(cap.max_per_host, MAX_CONNECTIONS_PER_HOST);
        assert!(!cap.limited_by_descriptors());
    }

    #[test]
    fn test_parse_descriptor_limit() {
        const INF: u64 = u64::MAX;
        assert_eq!(
            parse_descriptor_limit(1024, 524_288, INF),
            Some(DescriptorLimit {
                soft: 1024,
                hard: Some(524_288)
            })
        );
        // Infinite hard limit: soft can be raised without bound.
        assert_eq!(
            parse_descriptor_limit(1024, INF, INF),
            Some(DescriptorLimit {
                soft: 1024,
                hard: None
            })
        );
        // Infinite or zero soft limit: no usable limit.
        assert_eq!(parse_descriptor_limit(INF, INF, INF), None);
        assert_eq!(parse_descriptor_limit(0, 1024, INF), None);
    }

    #[test]
    fn test_parse_signed_descriptor_limit() {
        // FreeBSD's `rlim_t` is signed, with `RLIM_INFINITY == i64::MAX`.
        const INF: i64 = i64::MAX;
        assert_eq!(
            parse_descriptor_limit(1024, INF, INF),
            Some(DescriptorLimit {
                soft: 1024,
                hard: None
            })
        );
        assert_eq!(parse_descriptor_limit(INF, INF, INF), None);
    }

    #[test]
    #[cfg_attr(
        miri,
        ignore = "descriptor detection calls getrlimit, a syscall miri cannot emulate"
    )]
    fn test_detected_cap_within_bounds() {
        let cap = ConnectionCap::detect();
        assert!((MIN_CONNECTIONS_PER_HOST..=MAX_CONNECTIONS_PER_HOST).contains(&cap.max_per_host));
    }

    // The test value represents a 64 GiB host (65_536_000 kB × 1024), which
    // does not fit a 32-bit `usize`.
    #[cfg(target_pointer_width = "64")]
    #[test]
    fn test_parse_meminfo_total() {
        let s = "MemFree: 100 kB\nMemTotal:    65536000 kB\nBuffers: 5 kB\n";
        assert_eq!(parse_meminfo_total(s), Some(65536000 * 1024));
    }

    #[test]
    fn test_parse_meminfo_missing() {
        assert_eq!(parse_meminfo_total("Foo: 1 kB\n"), None);
    }

    #[test]
    fn test_parse_cgroup_max_is_none() {
        assert_eq!(parse_cgroup_limit("max\n"), None);
    }

    // 2^32 does not fit a 32-bit `usize`; the > u32 value is only meaningful
    // on 64-bit platforms.
    #[cfg(target_pointer_width = "64")]
    #[test]
    fn test_parse_cgroup_value() {
        assert_eq!(parse_cgroup_limit("4294967296\n"), Some(4_294_967_296));
    }

    #[test]
    fn test_cgroup_v2_path() {
        assert_eq!(
            cgroup_v2_path("0::/foo/bar\n"),
            Some("/foo/bar".to_string())
        );
        assert_eq!(cgroup_v2_path("0::/\n"), Some("/".to_string()));
        // A pure-v1 file has no "0::" line.
        assert_eq!(cgroup_v2_path("11:memory:/x\n"), None);
    }

    #[test]
    fn test_cgroup_v1_memory_path() {
        let f = "12:pids:/a\n4:cpu,cpuacct:/b\n3:memory:/foo/bar\n";
        assert_eq!(cgroup_v1_memory_path(f), Some("/foo/bar".to_string()));
        assert_eq!(cgroup_v1_memory_path("0::/unified\n"), None);
    }

    #[test]
    fn test_mountinfo_mount_v2() {
        let mi = "35 24 0:30 / /sys/fs/cgroup rw,nosuid - cgroup2 cgroup2 rw,nsdelegate\n";
        assert_eq!(
            mountinfo_mount(mi, "cgroup2", None),
            Some("/sys/fs/cgroup".to_string())
        );
    }

    #[test]
    fn test_mountinfo_mount_v1_memory() {
        let mi = "30 24 0:26 / /sys/fs/cgroup/cpu rw - cgroup cgroup rw,cpu\n\
                  31 24 0:27 / /sys/fs/cgroup/memory rw - cgroup cgroup rw,memory\n";
        assert_eq!(
            mountinfo_mount(mi, "cgroup", Some("memory")),
            Some("/sys/fs/cgroup/memory".to_string())
        );
        // The cpu controller is not the memory one.
        assert_eq!(mountinfo_mount(mi, "cgroup", Some("hugetlb")), None);
    }

    #[test]
    fn test_walk_paths_subcgroup() {
        assert_eq!(
            walk_paths("/sys/fs/cgroup", "/foo/bar", "memory.max"),
            vec![
                PathBuf::from("/sys/fs/cgroup/foo/bar/memory.max"),
                PathBuf::from("/sys/fs/cgroup/foo/memory.max"),
                PathBuf::from("/sys/fs/cgroup/memory.max"),
            ]
        );
    }

    #[test]
    fn test_walk_paths_root() {
        // A namespaced container sees its cgroup as "/": only the mount root.
        assert_eq!(
            walk_paths("/sys/fs/cgroup", "/", "memory.max"),
            vec![PathBuf::from("/sys/fs/cgroup/memory.max")]
        );
    }

    #[cfg(any(
        target_os = "freebsd",
        target_os = "linux",
        target_os = "macos",
        target_os = "windows"
    ))]
    #[test]
    #[cfg_attr(
        miri,
        ignore = "available_ram reads /proc and calls platform syscalls miri cannot emulate"
    )]
    fn test_available_ram_detected_on_supported_platforms() {
        const GIB: usize = 1024 * 1024 * 1024;

        // The detected machine has at least 1 GiB; guards the platform syscall.
        // On 32-bit, `parse_meminfo_total` returns `None` when the host has
        // more than ~4 GiB RAM because `MemTotal` kB × 1024 overflows
        // `usize`; `None` is only accepted there.
        match available_ram() {
            Some(bytes) => assert!(bytes >= GIB),
            None if cfg!(target_pointer_width = "32") => {}
            None => panic!("available_ram must detect RAM on a supported 64-bit platform"),
        }
    }

    // --- concurrency seeding ---

    fn auto_concurrency_seed(instance_type: Option<&str>, vcpus: usize) -> usize {
        resolve_auto_concurrency(instance_type, vcpus).target
    }

    #[test]
    fn test_family_lookup_parses_family_from_type() {
        // Family is the prefix before the first '.'; size-independent.
        assert_eq!(family_gbps_per_vcpu("m6idn.16xlarge"), Some(1.5625));
        assert_eq!(family_gbps_per_vcpu("m6idn.32xlarge"), Some(1.5625));
        assert_eq!(family_gbps_per_vcpu("m6idn.metal"), Some(1.5625));
        // Case-insensitive.
        assert_eq!(family_gbps_per_vcpu("C8GN.48XLARGE"), Some(3.125));
        // Unknown family and malformed strings miss.
        assert_eq!(family_gbps_per_vcpu("t3.large"), None);
        assert_eq!(family_gbps_per_vcpu("nonsense"), None);
    }

    #[test]
    fn test_seed_recognized_family_scales_with_vcpu() {
        // m6idn: 1.5625 Gbps/vCPU, GBPS_PER_CONN=0.4.
        // 16xlarge = 64 vCPU -> 100 Gbps -> ceil(100/0.4) = 250.
        assert_eq!(auto_concurrency_seed(Some("m6idn.16xlarge"), 64), 250);
        // 32xlarge = 128 vCPU -> 200 Gbps -> 500.
        assert_eq!(auto_concurrency_seed(Some("m6idn.32xlarge"), 128), 500);
        // c8gn: 3.125 Gbps/vCPU. 16xlarge = 64 vCPU -> 200 Gbps -> 500.
        assert_eq!(auto_concurrency_seed(Some("c8gn.16xlarge"), 64), 500);
    }

    #[test]
    fn test_auto_resolution_reports_family_estimate() {
        let resolved = resolve_auto_concurrency(Some("m6idn.16xlarge"), 64);
        assert_eq!(
            resolved,
            ResolvedAutoConcurrency {
                target: 250,
                estimated_gbps: Some(100.0),
                source: AutoConcurrencySource::InstanceFamily,
            }
        );
    }

    #[test]
    fn test_auto_resolution_reports_vcpu_fallback() {
        let resolved = resolve_auto_concurrency(Some("unknown.16xlarge"), 64);
        assert_eq!(
            resolved,
            ResolvedAutoConcurrency {
                target: 320,
                estimated_gbps: None,
                source: AutoConcurrencySource::VcpuFallback,
            }
        );
    }

    #[test]
    fn test_seed_uses_realized_vcpu_not_instance_size() {
        // A CPU-limited container on an m6idn.32xlarge reports its slice via
        // available_parallelism. Seed scales to the slice, not the host: a
        // 4-vCPU slice can't drive the box's 200 Gbps NIC. 4 * 1.5625 = 6.25
        // Gbps -> ceil(6.25/0.4) = 16.
        assert_eq!(auto_concurrency_seed(Some("m6idn.32xlarge"), 4), 16);
    }

    #[test]
    fn test_seed_recognizes_hyphenated_family() {
        // The family split is on '.', so a hyphenated family (`p6-b300`) must
        // still be recognized. Pick a vCPU count where the recognized result is
        // distinct from BOTH the clamp ceiling and the fallback, so the test
        // fails if the hyphenated key stops matching (falling through to
        // fallback) rather than passing via a coincident clamp.
        // p6-b300 = 350/192 Gbps/vCPU. At 24 vCPU: 43.75 Gbps ->
        // ceil(43.75/0.4) = 110. Fallback would be 5*24 = 120. Distinct.
        assert_eq!(auto_concurrency_seed(Some("p6-b300.6xlarge"), 24), 110);
        assert_ne!(
            auto_concurrency_seed(Some("p6-b300.6xlarge"), 24),
            FALLBACK_INFLIGHT_PER_VCPU * 24
        );
    }

    #[test]
    fn test_seed_fallback_scales_with_vcpu() {
        // Unknown family -> FALLBACK_INFLIGHT_PER_VCPU (5) * vcpus, above the
        // FALLBACK_MIN (32) floor.
        assert_eq!(auto_concurrency_seed(Some("t3.2xlarge"), 8), 40);
        assert_eq!(auto_concurrency_seed(Some("gcp-n2-standard-64"), 64), 320);
        // No detection at all falls through the same path.
        assert_eq!(auto_concurrency_seed(None, 16), 80);
    }

    #[test]
    fn test_seed_fallback_floored_for_small_box() {
        // A small unknown box would seed below the general-purpose default; the
        // FALLBACK_MIN floor (32) lifts it. 4 vCPU * 5 = 20 -> floored to 32.
        assert_eq!(auto_concurrency_seed(None, 4), FALLBACK_MIN);
        assert_eq!(
            auto_concurrency_seed(Some("gcp-n2-standard-4"), 4),
            FALLBACK_MIN
        );
        // The floor governs up to 6 vCPU (6 * 5 = 30 < 32); 7 vCPU crosses it.
        assert_eq!(auto_concurrency_seed(None, 6), FALLBACK_MIN);
        assert_eq!(auto_concurrency_seed(None, 7), 35);
    }

    #[test]
    fn test_seed_clamps_to_bounds() {
        // Tiny unknown machine: fallback floors to FALLBACK_MIN (32).
        assert_eq!(auto_concurrency_seed(None, 1), FALLBACK_MIN);
        assert_eq!(auto_concurrency_seed(Some("t3.micro"), 2), FALLBACK_MIN);
        // Recognized tiny estimate floors to the lower MIN_CONCURRENCY_SEED (a genuinely
        // small recognized box should seed low, unlike the unknown-box default).
        assert_eq!(
            auto_concurrency_seed(Some("i4i.large"), 2),
            MIN_CONCURRENCY_SEED
        );
        // Enormous estimate caps at MAX_CONCURRENCY_SEED.
        assert_eq!(
            auto_concurrency_seed(Some("p6-b300.48xlarge"), 100_000),
            MAX_CONCURRENCY_SEED
        );
    }

    #[test]
    fn test_seed_from_gbps_edges() {
        assert_eq!(seed_from_gbps(100.0), 250);
        assert_eq!(seed_from_gbps(0.0), MIN_CONCURRENCY_SEED); // floors, no underflow
        assert_eq!(seed_from_gbps(f64::NAN), MIN_CONCURRENCY_SEED); // NaN -> 0 -> floor
        assert_eq!(seed_from_gbps(1.0e9), MAX_CONCURRENCY_SEED); // caps
    }

    #[test]
    fn test_family_rate_is_flagship_gbps_over_vcpu() {
        // The per-vCPU rate is exactly the flagship spec divided out. Seeding at
        // the flagship vCPU count reproduces the family's headline NIC number.
        // m6idn flagship: 200 Gbps @ 128 vCPU -> ceil(200/0.4) = 500.
        assert_eq!(auto_concurrency_seed(Some("m6idn.metal"), 128), 500);
        // c8gn flagship: 600 Gbps @ 192 vCPU -> ceil(600/0.4) = 1500.
        assert_eq!(auto_concurrency_seed(Some("c8gn.48xlarge"), 192), 1500);
        // i4i flagship: 75 Gbps @ 128 vCPU -> ceil(75/0.4) = 188.
        assert_eq!(auto_concurrency_seed(Some("i4i.32xlarge"), 128), 188);
    }

    #[test]
    fn test_family_nic_table_is_well_formed() {
        use std::collections::HashSet;
        let mut seen = HashSet::new();
        for (family, gbps, vcpus) in FAMILY_NIC_GBPS {
            assert!(seen.insert(*family), "duplicate family entry: {family:?}");
            assert!(!family.is_empty(), "empty family name");
            assert!(
                !family.contains('.'),
                "family {family:?} must be a bare family, not an instance type"
            );
            assert_eq!(
                family.to_ascii_lowercase(),
                *family,
                "family {family:?} must be lowercase for case-insensitive lookup"
            );
            // Sanity bounds: sustained NIC figures are >0 and within EC2's range,
            // vCPU counts are plausible flagship sizes.
            assert!(*gbps > 0.0 && *gbps <= 6400.0, "{family}: gbps {gbps}");
            assert!(*vcpus > 0 && *vcpus <= 1024, "{family}: vcpus {vcpus}");
        }
    }

    #[test]
    fn test_local_vcpus_is_at_least_one() {
        assert!(local_vcpus() >= 1);
    }

    #[cfg_attr(
        miri,
        ignore = "detect_local reads /sys and /proc and calls platform syscalls miri cannot emulate"
    )]
    #[test]
    fn test_detect_local_fills_profile() {
        // Local-only detection: vCPU is always present; instance_type/ram are
        // environment-dependent (None off-EC2 / on read failure), so we only
        // assert the always-true invariant and that it does not panic.
        let p = MachineProfile::detect_local();
        assert!(p.vcpus >= 1);
        // No IMDS on this path: off-EC2, instance_type must be None (DMI-only).
        // On EC2 it may be Some; either is valid, so this is not asserted here.
    }

    #[cfg(not(target_os = "linux"))]
    #[test]
    fn test_dmi_detection_unknown_off_linux() {
        assert_eq!(detect_instance_type_dmi(), DmiDetection::Unknown);
    }

    #[test]
    fn test_classify_dmi_three_states() {
        // EC2 vendor + product -> Instance (trimmed, case-insensitive vendor).
        assert_eq!(
            classify_dmi("Amazon EC2\n", Some("m6idn.16xlarge\n")),
            DmiDetection::Instance("m6idn.16xlarge".to_string())
        );
        assert_eq!(
            classify_dmi("amazon ec2", Some("c7gn.16xlarge")),
            DmiDetection::Instance("c7gn.16xlarge".to_string())
        );
        // Readable non-EC2 vendor -> NotEc2 (the gate that skips IMDS).
        assert_eq!(
            classify_dmi("QEMU", Some("Standard PC")),
            DmiDetection::NotEc2
        );
        assert_eq!(classify_dmi("", Some("whatever")), DmiDetection::NotEc2);
        // EC2 vendor but missing/empty product -> Unknown (let IMDS try).
        assert_eq!(classify_dmi("Amazon EC2", None), DmiDetection::Unknown);
        assert_eq!(
            classify_dmi("Amazon EC2", Some("  ")),
            DmiDetection::Unknown
        );
    }
}