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
/*
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

use std::default::Default;
use std::fmt;
use std::path::Path;
use std::pin::Pin;

use bytes::{Buf, Bytes};

use crate::io::path_body::PathBody;
use crate::io::path_body::PathBodyBuilder;
use crate::io::size_hint::SizeHint;
use crate::io::PartBuffer;
use crate::memory::BufferPool;
use crate::memory::SegmentedBytes;

/// Source of binary data.
///
/// `InputStream` wraps a stream of data for ease of use.
///
/// To create an `InputStream`:
///
/// * From an in-memory source: use [`from_static`] or one of the provided `From` implementations.
/// * From a file path: use [`from_path`] or [`read_from`]
/// * From a custom implementation: use [`from_part_stream`]
///
/// [`from_static`]: InputStream::from_static
/// [`from_path`]: InputStream::from_path
/// [`read_from`]: InputStream::read_from
/// [`from_part_stream`]: InputStream::from_part_stream
///
#[derive(Debug)]
pub struct InputStream {
    pub(super) inner: RawInputStream,
}

impl InputStream {
    /// Create a new `InputStream` from a static byte slice
    pub fn from_static(bytes: &'static [u8]) -> Self {
        let inner = RawInputStream::Buf(bytes.into());
        Self { inner }
    }

    /// Return the bounds on the remaining length of the `InputStream`
    pub fn size_hint(&self) -> SizeHint {
        self.inner.size_hint()
    }

    /// Returns a [`PathBodyBuilder`], allowing you to build a `InputStream` with
    /// full control over how the file is read (eg. specifying the length of
    /// the file or the starting offset to read from).
    ///
    /// ```no_run
    /// # {
    /// use aws_s3_transfer::io::InputStream;
    ///
    /// async fn input_stream_from_file() -> InputStream {
    ///     let stream = InputStream::read_from()
    ///         .path("docs/some-large-file.csv")
    ///         // Specify the length of the file used (skips an additional call to retrieve the size)
    ///         .length(123_456)
    ///         .build()
    ///         .expect("valid path");
    ///     stream
    /// }
    /// # }
    /// ```
    pub fn read_from() -> PathBodyBuilder {
        PathBodyBuilder::new()
    }

    /// Create a new `InputStream` that reads data from a given `path`.
    ///
    /// ## Warning
    /// The file must not be modified until the upload completes. The stream records the file's
    /// length when it is built and reads the contents as the upload proceeds. Each attempt of a
    /// single-request upload reads the file again and calculates its checksum from the bytes read.
    /// A multipart upload reads each part from the file once, and every attempt of that part sends
    /// the same bytes.
    ///
    /// A change during the upload is not detected: a file shortened below the recorded length
    /// fails the upload, bytes past the recorded length are not uploaded, and bytes rewritten in
    /// place are uploaded with checksums that match the rewritten data. To have S3 reject an object
    /// that doesn't match the file as it was before the upload, calculate the file's checksum
    /// first and supply it with
    /// [`ChecksumStrategy::with_expected_value`](crate::types::ChecksumStrategy::with_expected_value).
    ///
    /// The path must name a regular file, directly or through symbolic links.
    /// Upload pipes and devices with [`InputStream::from_part_stream`] and
    /// [`TokioIo`](crate::io::adapters::TokioIo).
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::InputInvalid`](crate::error::ErrorKind::InputInvalid)
    /// when the path does not name a regular file, and
    /// [`ErrorKind::IOError`](crate::error::ErrorKind::IOError) when the
    /// file's metadata cannot be read, for example because the file does not
    /// exist.
    ///
    /// # Examples
    /// ```no_run
    /// use aws_s3_transfer::io::InputStream;
    /// use std::path::Path;
    ///  async fn make_stream() -> InputStream {
    ///     InputStream::from_path("docs/rows.csv").expect("file should be readable")
    /// }
    /// ```
    pub fn from_path(path: impl AsRef<Path>) -> Result<InputStream, crate::error::Error> {
        Self::read_from().path(path).build()
    }

    /// Returns `true` when this `InputStream` reads from a local file.
    pub(crate) fn is_file_backed(&self) -> bool {
        matches!(self.inner, RawInputStream::Fs(_))
    }

    /// Checks, without opening it, that a file-backed stream's path names a
    /// regular file. Does nothing for other streams. The file is checked again
    /// when it is opened.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::InputInvalid`](crate::error::ErrorKind::InputInvalid)
    /// if the path does not name a regular file, and
    /// [`ErrorKind::IOError`](crate::error::ErrorKind::IOError) if its metadata
    /// cannot be read.
    pub(crate) fn check_file_type(&self) -> Result<(), crate::error::Error> {
        match &self.inner {
            RawInputStream::Fs(path_body) => path_body.check_file_type(),
            RawInputStream::Buf(_) | RawInputStream::Dyn(_) => Ok(()),
        }
    }

    /// Convert this input stream into an [`SdkBody`] suitable for a top-level
    /// retryable SDK call (e.g. `PutObject`). The returned body is retryable at
    /// the SDK layer:
    ///
    /// * In-memory (`Buf`) streams go through [`SdkBody::from`] whose rebuild
    ///   path is a cheap `Bytes` clone. Keeping the native in-memory body (rather
    ///   than a custom wrapper) is what lets the SDK take its inline-checksum
    ///   path; wrapping would force aws-chunked trailer encoding.
    /// * File-backed (`Fs`) streams open the file once, then go through
    ///   [`SdkBody::retryable`]. Each retry constructs a fresh
    ///   [`DirectFileBody`] or [`OffloadedFileBody`] with an independent cursor
    ///   over the same open file identity.
    ///
    /// `direct_io` selects between the two file-body implementations: `true`
    /// when the caller owns the polling thread (managed-thread direct I/O),
    /// `false` when HTTP may poll the body on any thread. Offloaded readers use
    /// the Tokio runtime executing this conversion, including across retries.
    ///
    /// File-backed bodies acquire bounded chunks from `buffer_pool`.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::InputInvalid`](crate::error::ErrorKind::InputInvalid)
    /// if a file-backed stream's path does not open as a regular file, and
    /// [`ErrorKind::IOError`](crate::error::ErrorKind::IOError) if it cannot be
    /// opened.
    ///
    /// # Panics
    ///
    /// Panics when converting an offloaded file body outside Tokio execution.
    /// Panics on `Dyn` streams. Dyn sources cannot be rewound and must route
    /// through the multipart upload path (see [`is_mpu_only`](Self::is_mpu_only)).
    ///
    /// [`SdkBody`]: aws_smithy_types::body::SdkBody
    /// [`SdkBody::from`]: aws_smithy_types::body::SdkBody::from
    /// [`SdkBody::retryable`]: aws_smithy_types::body::SdkBody::retryable
    /// [`DirectFileBody`]: crate::operation::upload::file_body::DirectFileBody
    /// [`OffloadedFileBody`]: crate::operation::upload::file_body::OffloadedFileBody
    pub(crate) fn into_sdk_body(
        self,
        direct_io: bool,
        buffer_pool: BufferPool,
    ) -> Result<aws_smithy_types::body::SdkBody, crate::error::Error> {
        use crate::operation::upload::file_body::{
            DirectFileBody, FileBodySource, OffloadedFileBody,
        };
        use aws_smithy_types::body::SdkBody;
        match self.inner {
            RawInputStream::Buf(bytes) => Ok(SdkBody::from(bytes)),
            RawInputStream::Fs(path_body) => {
                let source = FileBodySource::new(path_body.open()?, buffer_pool);
                let offset = path_body.offset;
                let length = path_body.length;
                if direct_io {
                    Ok(SdkBody::retryable(move || {
                        SdkBody::from_body_1_x(DirectFileBody::new(source.clone(), offset, length))
                    }))
                } else {
                    let reader_runtime = tokio::runtime::Handle::current();
                    Ok(SdkBody::retryable(move || {
                        SdkBody::from_body_1_x(OffloadedFileBody::new(
                            source.clone(),
                            offset,
                            length,
                            reader_runtime.clone(),
                        ))
                    }))
                }
            }
            RawInputStream::Dyn(_) => panic!(
                "InputStream::into_sdk_body called on Dyn stream; \
                 Dyn sources must route through the multipart upload path \
                 (is_mpu_only() should have been checked upstream)"
            ),
        }
    }

    /// Test if this InputStream can only be uploaded via MPU (e.g. a custom `PartStream`
    /// implementation from a user can only be a MPU due to the ability to provide custom
    /// metadata like checksums).
    pub(crate) fn is_mpu_only(&self) -> bool {
        // TODO - for our own wrappers we can probably be smarter
        matches!(self.inner, RawInputStream::Dyn(_))
    }

    /// Create a new `InputStream` that reads data from the given [`PartStream`] implementation
    /// for a [multipart upload].
    ///
    /// NOTE: Implementing `PartStream` directly is a more advanced use case. You should reach for
    /// one of the provided implementations or adapters first if possible.
    ///
    /// # Size bounds
    ///
    /// The stream must emit at least [`SizeHint::lower`](crate::io::SizeHint::lower) bytes and no
    /// more than its optional [`SizeHint::upper`](crate::io::SizeHint::upper). Equal bounds declare
    /// an exact size and are retained as the independent `MpuObjectSize` sent to S3. For nonexact
    /// bounds, completion sends the validated number of bytes actually emitted. Contradictory
    /// bounds, early EOF, and output past the upper bound fail the upload.
    ///
    /// # Streams without an upper bound
    ///
    /// A stream whose [`size_hint`](PartStream::size_hint) has no upper bound is read until it ends,
    /// with no declared total. Prefer declaring a size when one is available, because without it:
    ///
    /// - The object is capped at `part_size * 10_000` — about 78 GiB at the default part size, since
    ///   there is no total to size parts against. Exceeding it fails partway through, not up front,
    ///   and the parts already uploaded are lost. Configure a larger part size for larger objects.
    /// - A failure mid-stream leaves an incomplete multipart upload. Call
    ///   [`abort`](crate::operation::upload::UploadHandle::abort), or use S3 lifecycle rules.
    /// - `MpuObjectSize` is the size actually uploaded rather than an independently declared one, so
    ///   it cannot detect a part this crate dropped or duplicated.
    ///
    /// [multipart upload]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html
    pub fn from_part_stream<T: PartStream + Send + Sync + 'static>(stream: T) -> Self {
        let inner = RawInputStream::Dyn(BoxStream::new(stream));
        Self { inner }
    }
}

#[derive(Debug)]
pub(super) enum RawInputStream {
    /// In-memory buffer to read from
    Buf(Bytes),
    /// File based input
    Fs(PathBody),
    /// User provided custom stream
    Dyn(BoxStream),
}

/// The context of an input stream.
#[derive(Debug)]
pub struct StreamContext {
    part_size: usize,
    /// Shared payload-memory pool used by this client.
    buffer_pool: BufferPool,
    /// When true, file I/O runs directly on the calling thread.
    direct_io: bool,
    /// Per-transfer cumulative metrics.
    metrics: std::sync::Arc<crate::transfer::MetricsState>,
    /// Per-client telemetry (windowed throughput, latency tracking).
    telemetry: std::sync::Arc<crate::telemetry::Telemetry>,
}

impl StreamContext {
    pub(super) fn new(
        part_size: usize,
        buffer_pool: BufferPool,
        direct_io: bool,
        metrics: std::sync::Arc<crate::transfer::MetricsState>,
        telemetry: std::sync::Arc<crate::telemetry::Telemetry>,
    ) -> Self {
        Self {
            part_size,
            buffer_pool,
            direct_io,
            metrics,
            telemetry,
        }
    }

    /// The part size to use when yielding parts.
    /// NOTE: this _may_ differ from the configured part size (e.g. if the target part size would
    /// result in exceeding the maximum number of parts allowed).
    pub fn part_size(&self) -> usize {
        self.part_size
    }

    /// Creates an empty [`PartBuffer`] of [`Self::part_size`] bytes, charged to this context's
    /// pool.
    pub(crate) fn part_buffer(&self) -> PartBuffer {
        PartBuffer::new(&self.buffer_pool, self.part_size)
    }

    /// Whether file I/O should run directly on the calling thread.
    pub(crate) fn direct_io(&self) -> bool {
        self.direct_io
    }

    /// Record an IO sample to per-transfer metrics and per-client telemetry.
    pub(crate) fn record_io(&self, sample: &crate::metrics::IoSample) {
        self.metrics.record_io(sample);
        self.telemetry.io_counters.record(sample);
    }
}

/// Contents and (optional) metadata for a single part of a [multipart upload].
///
/// [`PartData::new`] accepts one contiguous [`Bytes`] value.
/// [`PartData::from_segmented`] accepts an existing [`SegmentedBytes`] value
/// without gathering its immutable segments.
///
/// [multipart upload]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html
#[derive(Clone, PartialEq, Eq)]
pub struct PartData {
    // 1-indexed
    pub(crate) part_number: u64,
    pub(crate) data: SegmentedBytes,
    pub(crate) checksum: Option<String>,
}

impl std::fmt::Debug for PartData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PartData")
            .field("part_number", &self.part_number)
            .field("data_len", &self.data.len())
            .field("checksum", &self.checksum)
            .finish()
    }
}

impl PartData {
    /// Creates a part from contiguous immutable data.
    ///
    /// The data is retained without copying and uses the SDK's native
    /// contiguous request-body path.
    ///
    /// `part_number` is the part's position in the object: S3 assembles the
    /// object in part-number order, whatever order the parts are produced in.
    /// It must be between 1 and 10,000 and unique within the upload. A number
    /// outside that range fails the upload with
    /// [`ErrorKind::InputInvalid`](crate::error::ErrorKind::InputInvalid)
    /// before the part is sent; a repeated number fails it with the same kind
    /// before the upload is completed.
    ///
    /// Number parts 1 to N without gaps. S3 requires part numbers to start at 1
    /// and be consecutive in a directory bucket, and in a general purpose
    /// bucket when parts carry a CRC32, CRC32C, SHA-1 or SHA-256 checksum; it
    /// rejects other numbering when the upload is completed.
    pub fn new(part_number: u64, data: impl Into<Bytes>) -> Self {
        Self::from_segmented(part_number, SegmentedBytes::from(data.into()))
    }

    /// Creates a part from an existing segmented payload.
    ///
    /// The transfer manager retains the payload's immutable owners through
    /// request retries without gathering its presentation segments.
    ///
    /// `part_number` is the part's position in the object: S3 assembles the
    /// object in part-number order, whatever order the parts are produced in.
    /// It must be between 1 and 10,000 and unique within the upload. A number
    /// outside that range fails the upload with
    /// [`ErrorKind::InputInvalid`](crate::error::ErrorKind::InputInvalid)
    /// before the part is sent; a repeated number fails it with the same kind
    /// before the upload is completed.
    ///
    /// Number parts 1 to N without gaps. S3 requires part numbers to start at 1
    /// and be consecutive in a directory bucket, and in a general purpose
    /// bucket when parts carry a CRC32, CRC32C, SHA-1 or SHA-256 checksum; it
    /// rejects other numbering when the upload is completed.
    pub fn from_segmented(part_number: u64, data: SegmentedBytes) -> Self {
        Self {
            part_number,
            data,
            checksum: None,
        }
    }

    /// Sets this part's checksum: the base64 encoding of the big-endian checksum of this part's
    /// data in the upload's [`ChecksumStrategy`](crate::types::ChecksumStrategy) algorithm.
    ///
    /// The value is sent with the part when the upload has a checksum strategy, set on the upload
    /// or applied by default. Otherwise the upload fails with
    /// [`ErrorKind::InputInvalid`](crate::error::ErrorKind::InputInvalid). Without a value, the
    /// transfer manager calculates the part's checksum as the part is sent, when the upload has a
    /// checksum strategy.
    pub fn with_checksum(mut self, checksum: impl Into<String>) -> Self {
        self.checksum = Some(checksum.into());
        self
    }
}

/// Trait representing a stream of object parts (streaming body).
///
/// Individual parts are streamed via [`PartStream::poll_part`]. The transfer manager polls one
/// operation at a time with exclusive access to the stream, but a pending operation may resume on
/// a different thread. Implementations must retain any partial progress in `Self`, arrange for the
/// task waker to be notified before returning [`Poll::Pending`](std::task::Poll::Pending), and
/// return promptly rather than block the executor thread.
///
/// [`Poll::Ready(None)`](std::task::Poll::Ready) marks end-of-stream. The transfer manager does not
/// poll the stream again after that result.
///
/// [`size_hint`](PartStream::size_hint) declares bounds on the total bytes emitted before EOF.
pub trait PartStream {
    /// Polls for the next complete upload part.
    ///
    /// Returns [`Poll::Ready(Some(Ok(part)))`](std::task::Poll::Ready) when one part is available.
    /// Returns [`Poll::Ready(None)`](std::task::Poll::Ready) at end-of-stream. The transfer manager
    /// does not poll the stream again after end-of-stream or an error.
    ///
    /// The transfer manager does not check part sizes. S3 requires every part except the
    /// highest-numbered one to be at least 5 MiB; a smaller part is uploaded, and the upload fails
    /// when S3 rejects `CompleteMultipartUpload`. [`StreamContext::part_size`] is the size the
    /// transfer manager uses for its own parts.
    ///
    /// Each part's number is its position in the object, between 1 and 10,000, unique within the
    /// upload, and best numbered 1 to N without gaps. Parts may be returned in any order (see
    /// [`PartData::new`]).
    ///
    /// Returns [`Poll::Pending`](std::task::Poll::Pending) when the next part is not ready. Before
    /// returning `Pending`, the implementation must arrange for `cx.waker()` to be notified when
    /// polling may make progress. Partial reads, pending futures, and acquired storage must be
    /// retained in `Self`; dropping them and recreating the operation on the next poll can lose
    /// progress or notification. A later poll may use a different thread and a different waker.
    ///
    /// Implementations must return promptly and must not block the executor thread.
    fn poll_part(
        self: std::pin::Pin<&mut Self>,
        cx: &mut std::task::Context<'_>,
        stream_cx: &StreamContext,
    ) -> std::task::Poll<Option<std::io::Result<PartData>>>;

    /// Returns the bounds on the total size of the stream.
    ///
    /// Equal bounds are exact. When an upper bound is present it must be greater than or equal to
    /// the lower bound. The transfer manager captures this declaration once before polling begins;
    /// it must describe the complete sequence of parts returned before end-of-stream.
    fn size_hint(&self) -> crate::io::SizeHint;

    /// Returns the object's expected checksum, if the stream has one.
    ///
    /// The value is sent on `CompleteMultipartUpload`, and S3 rejects the upload unless the object
    /// matches it. `None` (the default implementation) sends no expected value.
    ///
    /// Called once, after [`PartStream::poll_part()`] yields the final part, and only when the
    /// upload's [`ChecksumStrategy`](crate::types::ChecksumStrategy) is
    /// [full object](crate::types::ChecksumStrategy::full_object) and has no value set with
    /// [`ChecksumStrategy::with_expected_value`](crate::types::ChecksumStrategy::with_expected_value).
    ///
    /// Return the base64 encoding of the big-endian checksum of the object's data in the
    /// strategy's algorithm. The value must cover the object's bytes in part-number order, which
    /// is the order S3 assembles them in, not necessarily the order the parts were returned.
    fn full_object_checksum(&self) -> Option<String> {
        None
    }
}

pub(crate) struct BoxStream {
    inner: Pin<Box<dyn PartStream + Send + Sync + 'static>>,
}

impl BoxStream {
    fn new<T: PartStream + Send + Sync + 'static>(inner: T) -> Self {
        BoxStream {
            inner: Box::pin(inner),
        }
    }

    pub(crate) fn poll_next(
        &mut self,
        cx: &mut std::task::Context<'_>,
        stream_cx: &StreamContext,
    ) -> std::task::Poll<Option<std::io::Result<PartData>>> {
        self.inner.as_mut().poll_part(cx, stream_cx)
    }

    pub(crate) fn full_object_checksum(&self) -> Option<String> {
        self.inner.full_object_checksum()
    }
}

impl fmt::Debug for BoxStream {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("BoxStream(dyn PartStream)").finish()
    }
}

impl RawInputStream {
    pub(super) fn size_hint(&self) -> SizeHint {
        match self {
            RawInputStream::Buf(bytes) => SizeHint::exact(bytes.remaining() as u64),
            RawInputStream::Fs(path_body) => SizeHint::exact(path_body.length),
            RawInputStream::Dyn(box_body) => box_body.inner.size_hint(),
        }
    }
}

impl Default for InputStream {
    fn default() -> Self {
        Self {
            inner: RawInputStream::Buf(Bytes::default()),
        }
    }
}

impl From<Bytes> for InputStream {
    fn from(value: Bytes) -> Self {
        Self {
            inner: RawInputStream::Buf(value),
        }
    }
}

impl From<Vec<u8>> for InputStream {
    fn from(value: Vec<u8>) -> Self {
        Self::from(Bytes::from(value))
    }
}

impl From<&'static [u8]> for InputStream {
    fn from(slice: &'static [u8]) -> InputStream {
        Self::from(Bytes::from_static(slice))
    }
}

impl From<&'static str> for InputStream {
    fn from(slice: &'static str) -> InputStream {
        Self::from(Bytes::from_static(slice.as_bytes()))
    }
}