Skip to main content

aws_s3_transfer/
types.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6use std::fmt::{self, Display};
7use std::ops;
8use std::str::FromStr;
9use std::time::Duration;
10
11pub mod checksum;
12mod checksum_strategy;
13pub use checksum_strategy::ChecksumStrategy;
14
15pub use crate::model::builders;
16pub use crate::model::{
17    ArchiveStatus, ChecksumAlgorithm, ChecksumMode, ChecksumType, ChunkMetadata, DownloadInput,
18    Object, ObjectCannedAcl, ObjectLockLegalHoldStatus, ObjectLockMode, ObjectMetadata,
19    ObjectStorageClass, Owner, ReplicationStatus, RequestCharged, RequestPayer, RestoreStatus,
20    ServerSideEncryption, StorageClass, UploadInput, UploadOutput,
21};
22
23/// Policy for how to handle a failed multipart upload
24///
25/// Default is to abort the upload.
26#[non_exhaustive]
27#[derive(Debug, Clone, Default)]
28pub enum FailedMultipartUploadPolicy {
29    /// Abort the upload on any individual part failure
30    #[default]
31    AbortUpload,
32    /// Leave the multipart upload open in S3, with any uploaded parts, instead of
33    /// sending AbortMultipartUpload.
34    ///
35    /// When the upload fails, the error that
36    /// [`UploadHandle::join`](crate::operation::upload::UploadHandle::join) returns carries the
37    /// upload ID in [`Error::upload_id`](crate::error::Error::upload_id). After
38    /// [`UploadHandle::abort`](crate::operation::upload::UploadHandle::abort), an
39    /// [`AbortedUpload`] whose outcome is [`AbortOutcome::Retained`] carries it. S3 keeps, and
40    /// bills for, the parts until the multipart upload is completed or aborted with that ID.
41    Retain,
42}
43
44/// Describes the result of aborting an in-progress upload.
45#[derive(Debug, Default)]
46pub struct AbortedUpload {
47    pub(crate) upload_id: Option<String>,
48    pub(crate) request_charged: Option<crate::model::RequestCharged>,
49    pub(crate) outcome: AbortOutcome,
50    pub(crate) output: Option<crate::operation::upload::UploadOutput>,
51}
52
53/// What an abort established about the object.
54#[non_exhaustive]
55#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
56pub enum AbortOutcome {
57    /// The abort stopped the upload, and the transfer manager did not observe S3 store the
58    /// object.
59    ///
60    /// S3 may still have stored it: a PutObject interrupted by the abort may have completed in
61    /// S3, and a CompleteMultipartUpload retried after an earlier attempt committed can be
62    /// answered with `NoSuchUpload`. Check for the object, for example with HeadObject, when
63    /// this matters.
64    #[default]
65    Cancelled,
66    /// S3 finished storing the object before the abort took effect. The object is not
67    /// deleted; its metadata is available from [`AbortedUpload::output`].
68    AlreadyCompleted,
69    /// The upload was stopped before S3 completed the object, and its multipart upload
70    /// was left open.
71    Retained,
72}
73
74impl AbortedUpload {
75    /// Returns whether the abort stopped the upload or the object already
76    /// exists.
77    pub fn outcome(&self) -> AbortOutcome {
78        self.outcome
79    }
80
81    /// Returns the upload's output when [`outcome`](Self::outcome) is
82    /// [`AbortOutcome::AlreadyCompleted`], and `None` otherwise.
83    pub fn output(&self) -> Option<&crate::operation::upload::UploadOutput> {
84        self.output.as_ref()
85    }
86    /// Get the multipart upload ID that was aborted, or that was left open when
87    /// [`outcome`](Self::outcome) is [`AbortOutcome::Retained`].
88    ///
89    /// Not present for uploads that did not utilize a multipart upload
90    pub fn upload_id(&self) -> Option<&str> {
91        self.upload_id.as_deref()
92    }
93
94    /// If present, indicates that the requester was successfully charged for the request.
95    ///
96    /// This functionality is not supported for directory buckets and is
97    /// not present for uploads that did not utilize a multipart upload
98    pub fn request_charged(&self) -> &Option<crate::model::RequestCharged> {
99        &self.request_charged
100    }
101}
102
103/// Policy for how to handle a failure of any individual object in a transfer
104/// involving multiple objects.
105///
106/// Default is to abort the transfer.
107#[non_exhaustive]
108#[derive(Debug, Clone, Default, PartialEq)]
109pub enum FailedTransferPolicy {
110    /// Abort the transfer on any individual failure to upload or download an object
111    #[default]
112    Abort,
113    /// Continue the transfer. The details of each failed object are available in the output
114    /// after the transfer completes.
115    Continue,
116}
117
118/// Detailed information about a failed object download
119#[non_exhaustive]
120#[derive(Debug)]
121pub struct FailedDownload {
122    /// The input for the download object operation that failed
123    pub(crate) input: crate::operation::download::DownloadInput,
124
125    /// The error encountered downloading the object
126    pub(crate) error: crate::error::Error,
127}
128
129impl FailedDownload {
130    /// The input for the download object operation that failed
131    pub fn input(&self) -> &crate::operation::download::DownloadInput {
132        &self.input
133    }
134
135    /// The error encountered downloading the object
136    pub fn error(&self) -> &crate::error::Error {
137        &self.error
138    }
139}
140
141/// Detailed information about a failed upload
142#[non_exhaustive]
143#[derive(Debug)]
144pub struct FailedUpload {
145    pub(crate) input: Option<crate::operation::upload::UploadInput>,
146    pub(crate) error: crate::error::Error,
147    /// Local filesystem path of the source file that failed to upload.
148    pub(crate) source_path: Option<std::path::PathBuf>,
149}
150
151impl FailedUpload {
152    /// The input for the failed object upload
153    pub fn input(&self) -> Option<&crate::operation::upload::UploadInput> {
154        self.input.as_ref()
155    }
156
157    /// The error encountered uploading the object
158    pub fn error(&self) -> &crate::error::Error {
159        &self.error
160    }
161
162    /// Local filesystem path of the source file that failed to upload.
163    pub fn source_path(&self) -> Option<&std::path::Path> {
164        self.source_path.as_deref()
165    }
166}
167
168/// Status of a transfer operation.
169#[derive(Debug, Clone, Copy, PartialEq, Eq)]
170#[non_exhaustive]
171pub enum TransferStatus {
172    /// Transfer is actively running.
173    Active,
174    /// Transfer completed successfully.
175    Completed,
176    /// Transfer failed with an error.
177    Failed,
178    /// Transfer was cancelled.
179    Cancelled,
180}
181
182impl TransferStatus {
183    /// Returns true if the transfer has reached a terminal state.
184    pub fn is_terminal(&self) -> bool {
185        !matches!(self, Self::Active)
186    }
187}
188
189/// Type of the bucket for the transfer
190#[derive(Debug, Clone, Copy, PartialEq)]
191#[non_exhaustive]
192pub(crate) enum BucketType {
193    Standard,
194    Express,
195}
196
197impl BucketType {
198    pub(crate) fn from_bucket_name(bucket_name: &str) -> Self {
199        if bucket_name.ends_with("--x-s3") {
200            BucketType::Express
201        } else {
202            BucketType::Standard
203        }
204    }
205}
206
207/// Internal bucket representation carrying the name and resolved kind.
208#[derive(Debug, Clone)]
209pub(crate) struct Bucket {
210    name: String,
211    kind: BucketType,
212}
213
214impl Bucket {
215    pub(crate) fn new(name: String) -> Self {
216        let kind = BucketType::from_bucket_name(&name);
217        Self { name, kind }
218    }
219
220    pub(crate) fn name(&self) -> &str {
221        &self.name
222    }
223
224    pub(crate) fn kind(&self) -> BucketType {
225        self.kind
226    }
227}
228
229/// Object-integrity information for a completed download.
230///
231/// Carries the object's reported checksum values (as returned by S3) and the
232/// outcome of checksum validation over the delivered bytes. Validation is a
233/// completion-time fact, distinct from the discovery-time [`ObjectMetadata`].
234///
235/// Whole-object downloads with checksum validation enabled report the stored
236/// values returned by checksum-mode HEAD. Caller ranges do not report object
237/// checksum values. Validation-off downloads can report stored values only
238/// when discovery receives the whole object in one GET.
239/// Values are `None` for a [`ChecksumType::Composite`] checksum, a checksum of
240/// part checksums that a checksum over the delivered bytes does not reproduce;
241/// the type is still reported.
242///
243/// A checksum mismatch is not represented here; it surfaces as an `Err` from the
244/// download's `join()`. On a successful `DownloadOutput`, [`ChecksumValidation`]
245/// distinguishes "validated" from "validation did not happen".
246///
247/// [`ObjectMetadata`]: crate::operation::download::ObjectMetadata
248#[non_exhaustive]
249#[derive(Debug, Clone)]
250pub struct IntegrityChecks {
251    checksum_crc32: Option<String>,
252    checksum_crc32c: Option<String>,
253    checksum_crc64_nvme: Option<String>,
254    checksum_sha1: Option<String>,
255    checksum_sha256: Option<String>,
256    checksum_sha512: Option<String>,
257    checksum_md5: Option<String>,
258    checksum_xxhash64: Option<String>,
259    checksum_xxhash3: Option<String>,
260    checksum_xxhash128: Option<String>,
261    checksum_type: Option<crate::model::ChecksumType>,
262    checksum_validation: ChecksumValidation,
263}
264
265impl IntegrityChecks {
266    /// The outcome of checksum validation over the delivered object bytes.
267    pub fn checksum_validation(&self) -> &ChecksumValidation {
268        &self.checksum_validation
269    }
270
271    /// The base64-encoded CRC-32 checksum reported by S3, if present.
272    pub fn checksum_crc32(&self) -> Option<&str> {
273        self.checksum_crc32.as_deref()
274    }
275
276    /// The base64-encoded CRC-32C checksum reported by S3, if present.
277    pub fn checksum_crc32c(&self) -> Option<&str> {
278        self.checksum_crc32c.as_deref()
279    }
280
281    /// The base64-encoded CRC-64/NVME checksum reported by S3, if present.
282    pub fn checksum_crc64_nvme(&self) -> Option<&str> {
283        self.checksum_crc64_nvme.as_deref()
284    }
285
286    /// The base64-encoded SHA-1 checksum reported by S3, if present.
287    pub fn checksum_sha1(&self) -> Option<&str> {
288        self.checksum_sha1.as_deref()
289    }
290
291    /// The base64-encoded SHA-256 checksum reported by S3, if present.
292    pub fn checksum_sha256(&self) -> Option<&str> {
293        self.checksum_sha256.as_deref()
294    }
295
296    /// The base64-encoded SHA-512 checksum reported by S3, if present.
297    pub fn checksum_sha512(&self) -> Option<&str> {
298        self.checksum_sha512.as_deref()
299    }
300
301    /// The base64-encoded MD5 checksum reported by S3, if present.
302    pub fn checksum_md5(&self) -> Option<&str> {
303        self.checksum_md5.as_deref()
304    }
305
306    /// The base64-encoded XXHASH64 checksum reported by S3, if present.
307    pub fn checksum_xxhash64(&self) -> Option<&str> {
308        self.checksum_xxhash64.as_deref()
309    }
310
311    /// The base64-encoded XXHASH3 checksum reported by S3, if present.
312    pub fn checksum_xxhash3(&self) -> Option<&str> {
313        self.checksum_xxhash3.as_deref()
314    }
315
316    /// The base64-encoded XXHASH128 checksum reported by S3, if present.
317    pub fn checksum_xxhash128(&self) -> Option<&str> {
318        self.checksum_xxhash128.as_deref()
319    }
320
321    /// The object's checksum type (full-object vs composite), if reported.
322    pub fn checksum_type(&self) -> Option<&crate::model::ChecksumType> {
323        self.checksum_type.as_ref()
324    }
325}
326
327/// Whether the bytes a download delivered were validated against S3's checksums.
328///
329/// Validation checks the bytes as they were received from S3, not the destination
330/// they were written to. `Validated` means every delivered byte was covered
331/// by matching response checksums or the complete object matched its stored
332/// CRC32, CRC32C or CRC64NVME checksum. Empty objects with a usable stored CRC
333/// are validated against the checksum of empty input.
334///
335/// Response checks remain active when a whole-object CRC is required; neither
336/// check can bypass a mismatch in the other. Without whole-object validation,
337/// partial response coverage is `NotValidated { reason: PartialCoverage }`.
338#[non_exhaustive]
339#[derive(Debug, Clone, PartialEq, Eq)]
340pub enum ChecksumValidation {
341    /// All delivered bytes passed response validation or whole-object CRC validation.
342    #[non_exhaustive]
343    Validated {
344        /// The lowest-offset response's algorithm when all bytes passed response checks;
345        /// otherwise the algorithm of the matching whole-object CRC.
346        algorithm: crate::model::ChecksumAlgorithm,
347    },
348    /// Not every delivered byte was validated. `reason` says why.
349    #[non_exhaustive]
350    NotValidated {
351        /// Why not every delivered byte was validated.
352        reason: NotValidatedReason,
353    },
354}
355
356/// Why not every byte a download delivered was validated.
357///
358/// When more than one reason holds, the download reports the first in this order:
359/// `Disabled`, `PartialCoverage`, `CompositeChecksum`, `UnsupportedAlgorithm`,
360/// `Unavailable`.
361#[non_exhaustive]
362#[derive(Debug, Clone, Copy, PartialEq, Eq)]
363pub enum NotValidatedReason {
364    /// Validation was not enabled: the request did not set `ChecksumMode::Enabled`,
365    /// and the client's `ResponseChecksumValidation` is `WhenRequired`.
366    Disabled,
367    /// A response carried only a part-level checksum, a value ending in `-N` such as
368    /// a composite upload's object checksum, which cannot be checked against the
369    /// bytes the response delivered.
370    CompositeChecksum,
371    /// Some delivered bytes were validated, and some were not.
372    PartialCoverage,
373    /// No response checksum was checked and no whole-object CRC was validated.
374    /// Includes objects without stored checksums and empty objects without a usable CRC.
375    Unavailable,
376    /// A response carried checksums only in algorithms the SDK does not compute,
377    /// such as MD5.
378    UnsupportedAlgorithm,
379}
380
381impl IntegrityChecks {
382    /// Build from the checksum values of `values`, the object's reported checksum
383    /// type and a resolved verdict. `None` reports no checksum values.
384    pub(crate) fn new(
385        values: Option<&crate::model::ObjectMetadata>,
386        checksum_type: Option<crate::model::ChecksumType>,
387        checksum_validation: ChecksumValidation,
388    ) -> Self {
389        let value = |f: fn(&crate::model::ObjectMetadata) -> &Option<String>| {
390            values.and_then(|m| f(m).clone())
391        };
392        Self {
393            checksum_crc32: value(|m| &m.checksum_crc32),
394            checksum_crc32c: value(|m| &m.checksum_crc32_c),
395            checksum_crc64_nvme: value(|m| &m.checksum_crc64_nvme),
396            checksum_sha1: value(|m| &m.checksum_sha1),
397            checksum_sha256: value(|m| &m.checksum_sha256),
398            checksum_sha512: value(|m| &m.checksum_sha512),
399            checksum_md5: value(|m| &m.checksum_md5),
400            checksum_xxhash64: value(|m| &m.checksum_xxhash64),
401            checksum_xxhash3: value(|m| &m.checksum_xxhash3),
402            checksum_xxhash128: value(|m| &m.checksum_xxhash128),
403            checksum_type,
404            checksum_validation,
405        }
406    }
407}
408
409// ===== Value types =====
410/// A quantity of bytes.
411///
412/// Used wherever configuration takes a size, so the unit is part of the value
413/// instead of the reader's guess. Positions, counters and buffer lengths stay
414/// integers.
415///
416/// ```
417/// use aws_s3_transfer::types::ByteSize;
418///
419/// const PART: ByteSize = ByteSize::mib(8);
420/// assert_eq!(PART.as_u64(), 8 * 1024 * 1024);
421/// assert_eq!(PART.to_string(), "8 MiB");
422/// ```
423#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
424pub struct ByteSize(u64);
425
426impl ByteSize {
427    /// A size of `bytes` bytes.
428    pub const fn new(bytes: u64) -> Self {
429        Self(bytes)
430    }
431
432    /// A size of `n` kibibytes (`n` * 2<sup>10</sup> bytes).
433    ///
434    /// # Panics
435    ///
436    /// Panics if the byte count exceeds `u64::MAX`. In a `const` context that
437    /// is a compile error.
438    pub const fn kib(n: u64) -> Self {
439        Self(mul(n, ByteUnit::Kibibyte.as_bytes_u64()))
440    }
441
442    /// A size of `n` mebibytes (`n` * 2<sup>20</sup> bytes).
443    ///
444    /// # Panics
445    ///
446    /// Panics if the byte count exceeds `u64::MAX`. In a `const` context that
447    /// is a compile error.
448    pub const fn mib(n: u64) -> Self {
449        Self(mul(n, ByteUnit::Mebibyte.as_bytes_u64()))
450    }
451
452    /// A size of `n` gibibytes (`n` * 2<sup>30</sup> bytes).
453    ///
454    /// # Panics
455    ///
456    /// Panics if the byte count exceeds `u64::MAX`. In a `const` context that
457    /// is a compile error.
458    pub const fn gib(n: u64) -> Self {
459        Self(mul(n, ByteUnit::Gibibyte.as_bytes_u64()))
460    }
461
462    /// This size in bytes.
463    pub const fn as_u64(self) -> u64 {
464        self.0
465    }
466
467    /// This size in bytes, as a `usize`.
468    ///
469    /// # Panics
470    ///
471    /// Panics where `usize` is narrower than 64 bits and the size does not
472    /// fit. A `MemoryBudgetConfig::Limit` that does not fit is reported as
473    /// `BufferPoolBuildError::CapacityOverflow` rather than panicking.
474    pub const fn as_usize(self) -> usize {
475        assert!(self.0 <= usize::MAX as u64, "byte count exceeds usize::MAX");
476        self.0 as usize
477    }
478
479    /// This size in `unit`, as an `f64`.
480    pub fn as_unit(self, unit: ByteUnit) -> f64 {
481        unit.convert(self.0)
482    }
483
484    /// Returns a type that formats this size in a fixed `unit`.
485    pub fn display_as(self, unit: ByteUnit) -> ByteSizeDisplayContext {
486        ByteSizeDisplayContext {
487            total_bytes: self.0,
488            unit,
489        }
490    }
491}
492
493const fn mul(n: u64, unit_bytes: u64) -> u64 {
494    match n.checked_mul(unit_bytes) {
495        Some(bytes) => bytes,
496        None => panic!("byte count exceeds u64::MAX"),
497    }
498}
499
500impl fmt::Display for ByteSize {
501    /// Formats in the largest binary unit that keeps the value at or above 1.
502    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
503        let units = &[ByteUnit::Gibibyte, ByteUnit::Mebibyte, ByteUnit::Kibibyte];
504        let mut unit = ByteUnit::Byte;
505        for u in units {
506            if self.0 >= u.as_bytes_u64() {
507                unit = *u;
508                break;
509            }
510        }
511        fmt::Display::fmt(&self.display_as(unit), f)
512    }
513}
514
515/// A unit a [`ByteSize`] or [`Throughput`] is displayed in.
516///
517/// The set is uneven: decimal bit units (`Kilobit`, `Megabit`, `Gigabit`) for
518/// rates, and binary byte units (`Kibibyte`, `Mebibyte`, `Gibibyte`) for sizes.
519#[non_exhaustive]
520#[derive(Debug, Clone, Copy, PartialEq, Eq)]
521pub enum ByteUnit {
522    /// 1 byte
523    Byte,
524    /// 1000 bits (125 bytes)
525    Kilobit,
526    /// 2<sup>10</sup> bytes.
527    Kibibyte,
528    /// 125 * 10<sup>3</sup> bytes.
529    Megabit,
530    /// 2<sup>20</sup> bytes.
531    Mebibyte,
532    /// 125 * 10<sup>6</sup> bytes.
533    Gigabit,
534    /// 2<sup>30</sup> bytes.
535    Gibibyte,
536}
537
538impl ByteUnit {
539    /// Convert some number of bytes into this unit as an `f64`
540    pub(crate) fn convert(&self, bytes: u64) -> f64 {
541        bytes as f64 / self.as_bytes_u64() as f64
542    }
543
544    /// The number of bytes represented by this unit
545    pub(crate) const fn as_bytes_u64(&self) -> u64 {
546        match self {
547            ByteUnit::Byte => 1,
548            ByteUnit::Kilobit => 125,
549            ByteUnit::Kibibyte => 1 << 10,
550            ByteUnit::Megabit => 125_000,
551            ByteUnit::Mebibyte => 1 << 20,
552            ByteUnit::Gigabit => 125_000_000,
553            ByteUnit::Gibibyte => 1 << 30,
554        }
555    }
556
557    pub(crate) const fn as_str(&self) -> &'static str {
558        match self {
559            ByteUnit::Byte => "B",
560            ByteUnit::Kilobit => "Kb",
561            ByteUnit::Kibibyte => "KiB",
562            ByteUnit::Megabit => "Mb",
563            ByteUnit::Mebibyte => "MiB",
564            ByteUnit::Gigabit => "Gb",
565            ByteUnit::Gibibyte => "GiB",
566        }
567    }
568}
569
570impl AsRef<str> for ByteUnit {
571    fn as_ref(&self) -> &str {
572        self.as_str()
573    }
574}
575
576impl FromStr for ByteUnit {
577    type Err = crate::error::Error;
578
579    fn from_str(s: &str) -> Result<Self, Self::Err> {
580        let unit = match s {
581            "B" => ByteUnit::Byte,
582            "Kb" => ByteUnit::Kilobit,
583            "KiB" => ByteUnit::Kibibyte,
584            "Mb" => ByteUnit::Megabit,
585            "MiB" => ByteUnit::Mebibyte,
586            "Gb" => ByteUnit::Gigabit,
587            "GiB" => ByteUnit::Gibibyte,
588            _ => {
589                return Err(crate::error::invalid_input(format!(
590                    "unknown byte unit '{}'",
591                    s
592                )))
593            }
594        };
595
596        Ok(unit)
597    }
598}
599
600/// Formats a byte count in a fixed [`ByteUnit`].
601///
602/// A count that is a whole multiple of the unit is displayed as an integer;
603/// any other count is displayed with the formatter's precision, three
604/// decimal places by default.
605#[derive(Debug)]
606pub struct ByteSizeDisplayContext {
607    total_bytes: u64,
608    unit: ByteUnit,
609}
610
611impl fmt::Display for ByteSizeDisplayContext {
612    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
613        if self.total_bytes.is_multiple_of(self.unit.as_bytes_u64()) {
614            let converted = self.total_bytes / self.unit.as_bytes_u64();
615            return write!(f, "{converted} {}", self.unit.as_str());
616        }
617        let precision = f.precision().unwrap_or(3);
618        write!(
619            f,
620            "{1:.*} {2:}",
621            precision,
622            self.unit.convert(self.total_bytes),
623            self.unit.as_str()
624        )
625    }
626}
627
628/// Measured bytes transferred over some duration
629#[derive(Debug, Clone, Copy)]
630pub struct Throughput {
631    bytes_transferred: u64,
632    elapsed: Duration,
633}
634
635impl Throughput {
636    /// Create a new throughput measurement with the given bytes read and time elapsed
637    pub const fn new(bytes_transferred: u64, elapsed: Duration) -> Throughput {
638        Throughput {
639            bytes_transferred,
640            elapsed,
641        }
642    }
643
644    /// Create a new throughput measurement assuming a one second duration
645    ///
646    /// This is convenience for:
647    ///
648    /// ```
649    /// use std::time::Duration;
650    /// use aws_s3_transfer::types::{ByteSize, Throughput};
651    /// let bytes_transferred = ByteSize::mib(5).as_u64();
652    /// assert_eq!(
653    ///     Throughput::new(bytes_transferred, Duration::from_secs(1)),
654    ///     Throughput::new_bytes_per_sec(bytes_transferred)
655    /// );
656    /// ```
657    pub const fn new_bytes_per_sec(bytes_transferred: u64) -> Throughput {
658        Self::new(bytes_transferred, Duration::from_secs(1))
659    }
660
661    /// Convert this throughput into a specific unit per second
662    pub fn as_unit_per_sec(&self, unit: ByteUnit) -> f64 {
663        (self.bytes_transferred as f64 / unit.as_bytes_u64() as f64) / self.elapsed.as_secs_f64()
664    }
665
666    /// Convert this throughput into bytes / sec
667    pub fn as_bytes_per_sec(&self) -> f64 {
668        self.as_unit_per_sec(ByteUnit::Byte)
669    }
670
671    /// Total bytes transferred
672    pub const fn bytes_transferred(&self) -> u64 {
673        self.bytes_transferred
674    }
675
676    /// Returns a type that can be used to format/display this throughput in a particular unit
677    pub fn display_as(&self, unit: ByteUnit) -> ThroughputDisplayContext<'_> {
678        ThroughputDisplayContext {
679            throughput: self,
680            unit,
681        }
682    }
683}
684
685impl PartialEq for Throughput {
686    fn eq(&self, other: &Self) -> bool {
687        self.as_bytes_per_sec() == other.as_bytes_per_sec()
688    }
689}
690
691impl PartialOrd for Throughput {
692    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
693        self.as_bytes_per_sec()
694            .partial_cmp(&other.as_bytes_per_sec())
695    }
696}
697
698/// Add two throughputs
699impl ops::Add for Throughput {
700    type Output = Self;
701
702    fn add(self, rhs: Self) -> Self::Output {
703        let bps = self.as_bytes_per_sec() + rhs.as_bytes_per_sec();
704
705        Throughput::new_bytes_per_sec(bps.round() as u64)
706    }
707}
708
709/// Subtract throughput
710impl ops::Sub for Throughput {
711    type Output = Self;
712
713    fn sub(self, rhs: Self) -> Self::Output {
714        let bps = self.as_bytes_per_sec() - rhs.as_bytes_per_sec();
715        Throughput::new_bytes_per_sec(bps.round() as u64)
716    }
717}
718
719/// Multiply throughput by a scalar
720impl ops::Mul<u64> for Throughput {
721    type Output = Self;
722
723    fn mul(self, rhs: u64) -> Self::Output {
724        Throughput::new(self.bytes_transferred * rhs, self.elapsed)
725    }
726}
727
728/// Divide throughput by a scalar
729impl ops::Div<u64> for Throughput {
730    type Output = Self;
731
732    fn div(self, rhs: u64) -> Self::Output {
733        Throughput::new(self.bytes_transferred / rhs, self.elapsed)
734    }
735}
736
737impl fmt::Display for Throughput {
738    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
739        let context = ThroughputDisplayContext {
740            throughput: self,
741            unit: ByteUnit::Megabit,
742        };
743        Display::fmt(&context, f)
744    }
745}
746
747/// Formats a [`Throughput`] as a rate in a fixed [`ByteUnit`] per
748/// second.
749///
750/// Created by [`Throughput::display_as`]. The rate is displayed with the
751/// formatter's precision when one is given.
752#[derive(Debug)]
753pub struct ThroughputDisplayContext<'a> {
754    throughput: &'a Throughput,
755    unit: ByteUnit,
756}
757
758impl fmt::Display for ThroughputDisplayContext<'_> {
759    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
760        if let Some(precision) = f.precision() {
761            write!(
762                f,
763                "{1:.*} {2:}/s",
764                precision,
765                self.throughput.as_unit_per_sec(self.unit),
766                self.unit.as_str()
767            )
768        } else {
769            write!(
770                f,
771                "{} {}/s",
772                self.throughput.as_unit_per_sec(self.unit),
773                self.unit.as_str()
774            )
775        }
776    }
777}
778
779#[cfg(test)]
780mod tests {
781    use crate::config::TargetThroughput;
782
783    #[test]
784    fn target_throughput_accepts_finite_positive_gbps() {
785        for gbps in [0.5, 1.0, 200.0] {
786            let target = TargetThroughput::gbps(gbps).unwrap();
787            assert_eq!(target.as_gbps(), gbps);
788        }
789    }
790
791    #[test]
792    fn target_throughput_rejects_values_that_are_not_a_rate() {
793        for gbps in [0.0, -1.0, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
794            assert!(TargetThroughput::gbps(gbps).is_err(), "gbps {gbps}");
795        }
796    }
797}
798
799#[cfg(test)]
800mod value_type_tests {
801    use super::{ByteSize, ByteUnit, Throughput};
802    use std::str::FromStr;
803    use std::time::Duration;
804
805    /// Every unit reports the same value through its byte and bit accessors,
806    /// at both widths. The byte values are the unit definitions; a regression
807    /// in either derivation changes one of the pairs.
808    #[test]
809    fn byte_unit_accessors_agree() {
810        let units = [
811            (ByteUnit::Byte, 1u64),
812            (ByteUnit::Kilobit, 125),
813            (ByteUnit::Kibibyte, 1024),
814            (ByteUnit::Megabit, 125_000),
815            (ByteUnit::Mebibyte, 1024 * 1024),
816            (ByteUnit::Gigabit, 125_000_000),
817            (ByteUnit::Gibibyte, 1024 * 1024 * 1024),
818        ];
819        for (unit, bytes) in units {
820            assert_eq!(unit.as_bytes_u64(), bytes, "{unit:?} bytes");
821        }
822    }
823
824    #[test]
825    fn byte_size_constructors_and_display() {
826        assert_eq!(ByteSize::kib(2).as_u64(), 2 * 1024);
827        assert_eq!(ByteSize::mib(8).as_u64(), 8 * 1024 * 1024);
828        assert_eq!(ByteSize::gib(3).as_u64(), 3 * 1024 * 1024 * 1024);
829
830        // the largest binary unit that keeps the value at or above 1
831        assert_eq!(ByteSize::new(512).to_string(), "512 B");
832        assert_eq!(ByteSize::kib(4).to_string(), "4 KiB");
833        assert_eq!(ByteSize::mib(8).to_string(), "8 MiB");
834        assert_eq!(ByteSize::new(1_610_612_736).to_string(), "1.500 GiB");
835
836        // a fixed unit on request
837        assert_eq!(
838            ByteSize::gib(1).display_as(ByteUnit::Mebibyte).to_string(),
839            "1024 MiB"
840        );
841        assert_eq!(ByteSize::mib(1).as_unit(ByteUnit::Kibibyte), 1024.0);
842    }
843
844    #[test]
845    #[should_panic(expected = "byte count exceeds u64::MAX")]
846    fn byte_size_overflow_panics() {
847        let _ = ByteSize::gib(u64::MAX);
848    }
849
850    #[test]
851    fn test_throughput_display() {
852        // default
853        assert_eq!(
854            "1 Mb/s",
855            format!("{}", Throughput::new(125_000, Duration::from_secs(1)))
856        );
857
858        let t = Throughput::new(1_000_000, Duration::from_secs(1));
859
860        // explicit
861        assert_eq!("1000000 B/s", format!("{}", t.display_as(ByteUnit::Byte)));
862        assert_eq!("8000 Kb/s", format!("{}", t.display_as(ByteUnit::Kilobit)));
863        assert_eq!(
864            "976.5625 KiB/s",
865            format!("{}", t.display_as(ByteUnit::Kibibyte))
866        );
867        assert_eq!("8 Mb/s", format!("{}", t.display_as(ByteUnit::Megabit)));
868        assert_eq!(
869            "0.954 MiB/s",
870            format!("{:.3}", t.display_as(ByteUnit::Mebibyte))
871        );
872        assert_eq!("0.008 Gb/s", format!("{}", t.display_as(ByteUnit::Gigabit)));
873        assert_eq!(
874            "0.00093 GiB/s",
875            format!("{:.5}", t.display_as(ByteUnit::Gibibyte))
876        );
877    }
878
879    #[test]
880    fn test_from_str() {
881        let units = &[
882            ByteUnit::Byte,
883            ByteUnit::Kilobit,
884            ByteUnit::Kibibyte,
885            ByteUnit::Megabit,
886            ByteUnit::Mebibyte,
887            ByteUnit::Gigabit,
888            ByteUnit::Gibibyte,
889        ];
890
891        for u in units {
892            let u2 = ByteUnit::from_str(u.as_str()).unwrap();
893            assert_eq!(*u, u2);
894        }
895
896        assert!(ByteUnit::from_str("kb").is_err());
897    }
898
899    #[test]
900    fn test_ops() {
901        let t = Throughput::new_bytes_per_sec(ByteSize::mib(10).as_u64());
902        let t2 = Throughput::new_bytes_per_sec(ByteSize::mib(5).as_u64());
903
904        assert_eq!(
905            t + t2,
906            Throughput::new_bytes_per_sec(t.bytes_transferred() + t2.bytes_transferred())
907        );
908        assert_eq!(t - t2, t2);
909        assert_eq!(
910            t * 2,
911            Throughput::new_bytes_per_sec(t.bytes_transferred() * 2)
912        );
913        assert_eq!(t / 2, t2);
914    }
915
916    #[test]
917    fn test_byte_display_context() {
918        assert_eq!("1 KiB", format!("{}", ByteSize::new(1024)));
919        assert_eq!("1 MiB", format!("{}", ByteSize::new(1024 * 1024)));
920        assert_eq!("1 GiB", format!("{}", ByteSize::new(1024 * 1024 * 1024)));
921
922        assert_eq!("727 B", format!("{}", ByteSize::new(727)));
923        assert_eq!(
924            "0.710 KiB",
925            format!("{}", ByteSize::new(727).display_as(ByteUnit::Kibibyte))
926        );
927        assert_eq!("3.420 KiB", format!("{}", ByteSize::new(3502)));
928        assert_eq!("3.41992 KiB", format!("{:.5}", ByteSize::new(3502)));
929
930        assert_eq!("7.201 MiB", format!("{}", ByteSize::new(7550498)));
931        assert_eq!(
932            "0.007 GiB",
933            format!("{}", ByteSize::new(7550498).display_as(ByteUnit::Gibibyte))
934        );
935
936        assert_eq!("1.016 GiB", format!("{}", ByteSize::new(1091242563)));
937        assert_eq!(
938            "1040.690 MiB",
939            format!(
940                "{}",
941                ByteSize::new(1091242563).display_as(ByteUnit::Mebibyte)
942            )
943        );
944    }
945}