google_cloud_storage/
storage.rs

1// Copyright 2025 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15pub(crate) mod checksum;
16pub(crate) mod client;
17pub(crate) mod perform_upload;
18pub(crate) mod read_object;
19pub(crate) mod request_options;
20pub(crate) mod upload_object;
21pub mod upload_source;
22pub(crate) mod v1;
23
24use crate::model::Object;
25use crate::upload_source::Payload;
26use crate::{Error, Result};
27
28/// An unrecoverable problem in the upload protocol.
29///
30/// # Example
31/// ```
32/// # use google_cloud_storage::client::Storage;
33/// # use google_cloud_storage::UploadError;
34/// # async fn sample(client: &Storage) -> anyhow::Result<()> {
35/// use std::error::Error as _;
36/// let upload = client
37///     .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
38///     .with_if_generation_not_match(0);
39/// match upload.send().await {
40///     Ok(object) => println!("Successfully uploaded the object"),
41///     Err(error) if error.is_serialization() => {
42///         println!("Some problem {error:?} sending the data to the service");
43///         if let Some(m) = error.source().and_then(|e| e.downcast_ref::<UploadError>()) {
44///             println!("{m}");
45///         }
46///     },
47///     Err(e) => return Err(e.into()), // not handled in this example
48/// }
49/// # Ok(()) }
50/// ```
51///
52/// # Troubleshoot
53///
54/// These errors indicate a bug in the resumable upload protocol implementation,
55/// either in the service or the client library. Neither are expected to be
56/// common, but neither are impossible. We recommend you [open a bug], there is
57/// little you could do to recover from this problem.
58///
59/// While it is customary to `panic!()` when a bug triggers a problem, we do not
60/// believe it is appropriate to do so in this case, as the invariants involve
61/// different machines and the upload protocol.
62///
63/// [open a bug]: https://github.com/googleapis/google-cloud-rust/issues/new/choose
64#[derive(thiserror::Error, Debug)]
65#[non_exhaustive]
66pub enum UploadError {
67    #[error(
68        "the service previously persisted {offset} bytes, but now reports only {persisted} as persisted"
69    )]
70    UnexpectedRewind { offset: u64, persisted: u64 },
71
72    #[error("the service reports {persisted} bytes as persisted, but we only sent {sent} bytes")]
73    TooMuchProgress { sent: u64, persisted: u64 },
74}
75
76/// The error type for checksum comparisons.
77///
78/// By default the client library computes a checksum of the uploaded data, and
79/// compares this checksum against the value returned by the service.
80///
81/// # Example
82/// ```
83/// # use google_cloud_storage::client::Storage;
84/// # use google_cloud_storage::ChecksumMismatch;
85/// # async fn sample(client: &Storage) -> anyhow::Result<()> {
86/// use std::error::Error as _;
87/// let upload = client
88///     .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
89///     .with_if_generation_not_match(0);
90/// match upload.send().await {
91///     Ok(object) => println!("Successfully uploaded the object"),
92///     Err(error) if error.is_serialization() => {
93///         println!("Some problem {error:?} sending the data to the service");
94///         if let Some(m) = error.source().and_then(|e| e.downcast_ref::<ChecksumMismatch>()) {
95///             println!("The checksums did not match: {m}");
96///         }
97///     },
98///     Err(e) => return Err(e.into()), // not handled in this example
99/// }
100/// # Ok(()) }
101/// ```
102///  
103/// # Troubleshooting
104///
105/// Data integrity problems are notoriously difficult to root cause. If you are
106/// using pre-existing, or pre-computed checksum values, you may want to verify
107/// the source data.
108#[derive(thiserror::Error, Debug)]
109#[non_exhaustive]
110pub enum ChecksumMismatch {
111    #[error("mismatched CRC32C values {0}")]
112    Crc32c(String),
113    #[error("mismatched MD5 values: {0}")]
114    MD5(String),
115    #[error("mismatched CRC32C and MD5 values {0}")]
116    Both(String),
117}
google_cloud_storage/storage.rs

google_cloud_storage/
storage.rs
