pub struct ChecksumStrategy { /* private fields */ }Expand description
How an upload’s checksums are chosen.
S3 checks each checksum an upload sends against the bytes it receives, and stores a checksum with the object. See Checking object integrity. A strategy answers three questions:
-
Which algorithm? S3 stores the object’s checksum in this algorithm, named by a type from
checksum. -
Should the stored checksum cover the whole object?
full_object: the stored checksum equals a checksum of the whole object, so it can be compared with one computed elsewhere. CRC64NVME, CRC32 or CRC32C: theFullObjectAlgorithmtypes.composite: for a multipart upload, the stored checksum is a checksum of the part checksums. It depends on the part size and doesn’t equal a checksum of the object. CRC32, CRC32C, SHA1 or SHA256: theCompositeAlgorithmtypes. A single-request upload sends a full object checksum of the same algorithm.
A constructor called with an algorithm its checksum type doesn’t support doesn’t compile.
-
Do you know the expected checksum?
with_expected_valuegives S3 the value to check the uploaded object against; S3 rejects the upload if it doesn’t match. A single-request upload sends the value in place of a checksum calculated from the body. A multipart upload still calculates each part’s checksum and also sends the value withCompleteMultipartUpload. Supply one to check the stored object against its source: the checksums the transfer manager calculates cover only the bytes it sends, so they don’t detect a source that changed or was read incorrectly. For a full object strategy, aPartStreamcan instead return the value fromPartStream::full_object_checksumafter its final part.
The transfer manager calculates a checksum of each body it sends: the body of a single-request
upload, and each part of a multipart upload. It doesn’t calculate a value you supply, with
with_expected_value or through a PartStream. It never calculates the object-level checksum of
a multipart upload: that value comes from you, or S3 derives it from the part checksums.
§Default
An upload without a strategy uses ChecksumStrategy::default(), a full object CRC64NVME
strategy, when the request checksum policy is the default
RequestChecksumCalculation::WhenSupported.
Under
RequestChecksumCalculation::WhenRequired,
an upload without a strategy sends no checksums; S3 still stores a full object CRC64NVME checksum
for the object. A strategy set on the upload is used under either policy.
Set the policy through aws_types::SdkConfig::builder. With sdk-v1, it can also be set on the
S3 configuration builder before conversion into S3ClientConfig.
§What is sent
A single-request upload sends one checksum of the body: the expected value, or one calculated as the body is sent.
A multipart upload:
CreateMultipartUploaddeclares the algorithm and the type.- Each
UploadPartcarries its part’s checksum: the value aPartStreamset withPartData::with_checksum, or else one calculated as the part is sent. CompleteMultipartUploadcarries the type, each part’s checksum and, for a full object strategy, the expected value if there is one.- S3 derives the object’s checksum from the part checksums. With an expected value, a mismatch fails the upload.
§Rules
- A composite strategy with an expected value is valid only for a single-request upload.
initiatefails withErrorKind::InputInvalidbefore any request is sent when the body’s size has no upper bound, the body is aPartStream, or its upper bound is at least the multipart threshold. - Number a
PartStream’s parts consecutively from 1. S3 requires it for parts that carry some checksums and failsCompleteMultipartUploadotherwise; seePartData::new. - Checksum values are the base64 encoding of the big-endian checksum.
§Downloads
A full object CRC lets a download, including one split into ranges, check the whole object it
received. A composite checksum allows checks of responses that align with stored parts, not of
the object as a whole. See ChecksumValidation.
Implementations§
Source§impl ChecksumStrategy
impl ChecksumStrategy
Sourcepub fn full_object<A: FullObjectAlgorithm>(algorithm: A) -> Self
pub fn full_object<A: FullObjectAlgorithm>(algorithm: A) -> Self
Returns a strategy whose stored checksum is a full object checksum in algorithm, for a
single-request or multipart upload.
FullObjectAlgorithm lists the supported algorithms.
Sourcepub fn composite<A: CompositeAlgorithm>(algorithm: A) -> Self
pub fn composite<A: CompositeAlgorithm>(algorithm: A) -> Self
Returns a strategy whose stored checksum, for a multipart upload, is a composite checksum
in algorithm. A single-request upload sends a full object checksum in algorithm.
CompositeAlgorithm lists the supported algorithms.
Sourcepub fn with_expected_value(self, value: impl Into<String>) -> Self
pub fn with_expected_value(self, value: impl Into<String>) -> Self
Sets the object’s expected checksum: the base64 encoding of the big-endian checksum of the whole object in the strategy’s algorithm.
S3 rejects the upload unless the object matches value. The transfer manager sends value
as given and does not check it. A single-request upload sends it in place of a checksum
calculated from the body; a multipart upload still calculates each part’s checksum and
sends value with CompleteMultipartUpload.
A composite strategy with an expected value is valid only for a single-request upload.
initiate fails with ErrorKind::InputInvalid,
before any request is sent, for an upload sent as a multipart upload: the body’s size has no
upper bound, the body is a PartStream, or its upper bound is at
least the multipart threshold.
Sourcepub fn algorithm(&self) -> &ChecksumAlgorithm
pub fn algorithm(&self) -> &ChecksumAlgorithm
The algorithm of every checksum the upload sends and of the checksum S3 stores.
Sourcepub fn multipart_checksum_type(&self) -> &ChecksumType
pub fn multipart_checksum_type(&self) -> &ChecksumType
The type of the object’s checksum when the upload is sent as a multipart upload:
ChecksumType::FullObject or ChecksumType::Composite.
A single-request upload always has a full object checksum.
Sourcepub fn expected_value(&self) -> Option<&str>
pub fn expected_value(&self) -> Option<&str>
The expected value set with with_expected_value, if any.
A value returned from
PartStream::full_object_checksum is not
reported here.
Trait Implementations§
Source§impl Clone for ChecksumStrategy
impl Clone for ChecksumStrategy
Source§impl Debug for ChecksumStrategy
impl Debug for ChecksumStrategy
Source§impl Default for ChecksumStrategy
impl Default for ChecksumStrategy
impl Eq for ChecksumStrategy
Source§impl PartialEq for ChecksumStrategy
impl PartialEq for ChecksumStrategy
impl StructuralPartialEq for ChecksumStrategy
Auto Trait Implementations§
impl Forget for ChecksumStrategy
impl Freeze for ChecksumStrategy
impl Move for ChecksumStrategy
impl RefUnwindSafe for ChecksumStrategy
impl Send for ChecksumStrategy
impl Sync for ChecksumStrategy
impl Unpin for ChecksumStrategy
impl UnsafeUnpin for ChecksumStrategy
impl UnwindSafe for ChecksumStrategy
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more