rusty_s3/actions/multipart_upload/
create.rs

1use std::iter;
2use std::time::Duration;
3
4use instant_xml::FromXml;
5use jiff::Timestamp;
6use url::Url;
7
8use crate::actions::{Method, S3_XML_NS, S3Action};
9use crate::signing::sign;
10use crate::sorting_iter::SortingIterator;
11use crate::{Bucket, Credentials, Map};
12
13/// Create a multipart upload.
14///
15/// A few advantages of multipart uploads are:
16///
17/// * being able to be resume without having to start back from the beginning
18/// * parallelize the uploads across multiple threads
19///
20/// Find out more about `CreateMultipartUpload` from the [AWS API Reference][api]
21///
22/// [api]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html
23#[allow(clippy::module_name_repetitions)]
24#[derive(Debug, Clone)]
25pub struct CreateMultipartUpload<'a> {
26    bucket: &'a Bucket,
27    credentials: Option<&'a Credentials>,
28    object: &'a str,
29
30    query: Map<'a>,
31    headers: Map<'a>,
32}
33
34#[allow(clippy::module_name_repetitions)]
35#[derive(Debug, Clone)]
36pub struct CreateMultipartUploadResponse(InnerCreateMultipartUploadResponse);
37
38#[derive(Debug, Clone, FromXml)]
39#[xml(rename = "InitiateMultipartUploadResult", ns(S3_XML_NS))]
40struct InnerCreateMultipartUploadResponse {
41    #[xml(rename = "UploadId")]
42    upload_id: String,
43}
44
45impl<'a> CreateMultipartUpload<'a> {
46    #[inline]
47    #[must_use]
48    pub const fn new(
49        bucket: &'a Bucket,
50        credentials: Option<&'a Credentials>,
51        object: &'a str,
52    ) -> Self {
53        Self {
54            bucket,
55            credentials,
56            object,
57
58            query: Map::new(),
59            headers: Map::new(),
60        }
61    }
62
63    /// Parse the XML response from S3
64    ///
65    /// # Errors
66    ///
67    /// Will return an error if the body is not valid XML
68    pub fn parse_response(s: &str) -> Result<CreateMultipartUploadResponse, instant_xml::Error> {
69        let parsed = instant_xml::from_str(s)?;
70        Ok(CreateMultipartUploadResponse(parsed))
71    }
72}
73
74impl CreateMultipartUploadResponse {
75    #[must_use]
76    pub fn upload_id(&self) -> &str {
77        &self.0.upload_id
78    }
79}
80
81impl<'a> S3Action<'a> for CreateMultipartUpload<'a> {
82    const METHOD: Method = Method::Post;
83
84    fn query_mut(&mut self) -> &mut Map<'a> {
85        &mut self.query
86    }
87
88    fn headers_mut(&mut self) -> &mut Map<'a> {
89        &mut self.headers
90    }
91
92    fn sign_with_time(&self, expires_in: Duration, time: &Timestamp) -> Url {
93        let url = self.bucket.object_url(self.object).unwrap();
94        let query = iter::once(("uploads", "1"));
95
96        match self.credentials {
97            Some(credentials) => sign(
98                time,
99                Self::METHOD,
100                url,
101                credentials.key(),
102                credentials.secret(),
103                credentials.token(),
104                self.bucket.region(),
105                expires_in.as_secs(),
106                SortingIterator::new(query, self.query.iter()),
107                self.headers.iter(),
108            ),
109            None => crate::signing::util::add_query_params(url, query),
110        }
111    }
112}
113
114#[cfg(test)]
115mod tests {
116    use pretty_assertions::assert_eq;
117
118    use super::*;
119    use crate::{Bucket, Credentials, UrlStyle};
120
121    #[test]
122    fn aws_example() {
123        // Fri, 24 May 2013 00:00:00 GMT
124        let date = Timestamp::from_second(1369353600).unwrap();
125        let expires_in = Duration::from_secs(86400);
126
127        let endpoint = "https://s3.amazonaws.com".parse().unwrap();
128        let bucket = Bucket::new(
129            endpoint,
130            UrlStyle::VirtualHost,
131            "examplebucket",
132            "us-east-1",
133        )
134        .unwrap();
135        let credentials = Credentials::new(
136            "AKIAIOSFODNN7EXAMPLE",
137            "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
138        );
139
140        let action = CreateMultipartUpload::new(&bucket, Some(&credentials), "test.txt");
141
142        let url = action.sign_with_time(expires_in, &date);
143        let expected = "https://examplebucket.s3.amazonaws.com/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&uploads=1&X-Amz-Signature=a6289f9e5ff2a914c6e324403bcd00b1d258c568487faa50d317ef0910c25c0a";
144
145        assert_eq!(expected, url.as_str());
146    }
147
148    #[test]
149    fn anonymous_custom_query() {
150        let expires_in = Duration::from_secs(86400);
151
152        let endpoint = "https://s3.amazonaws.com".parse().unwrap();
153        let bucket = Bucket::new(
154            endpoint,
155            UrlStyle::VirtualHost,
156            "examplebucket",
157            "us-east-1",
158        )
159        .unwrap();
160
161        let action = CreateMultipartUpload::new(&bucket, None, "test.txt");
162        let url = action.sign(expires_in);
163        let expected = "https://examplebucket.s3.amazonaws.com/test.txt?uploads=1";
164
165        assert_eq!(expected, url.as_str());
166    }
167}
rusty_s3/actions/multipart_upload/create.rs

rusty_s3/actions/multipart_upload/
create.rs
