tame_gcs/v1/
objects.rs

1//! Types and APIs for interacting with GCS [Objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
2
3use crate::common::StorageClass;
4use http::uri::Authority;
5use std::collections::BTreeMap;
6
7#[doc(hidden)]
8#[macro_export]
9macro_rules! __make_obj_url {
10    ($url:expr, $authority:expr, $id:expr) => {{
11        format!(
12            $url,
13            $authority.as_str(),
14            percent_encoding::percent_encode($id.bucket().as_ref(), $crate::util::PATH_ENCODE_SET),
15            percent_encoding::percent_encode($id.object().as_ref(), $crate::util::PATH_ENCODE_SET)
16        )
17    }};
18}
19
20mod delete;
21mod download;
22mod get;
23mod insert;
24mod list;
25mod patch;
26mod rewrite;
27
28pub use delete::*;
29pub use download::*;
30pub use get::*;
31pub use insert::*;
32pub use list::*;
33pub use patch::*;
34pub use rewrite::*;
35
36pub type Timestamp = time::OffsetDateTime;
37
38/// Helper struct used to collate all of the operations available for
39/// [Objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
40/// Additionally, it can also be used to specify a custom authority.
41#[derive(Clone, Debug)]
42pub struct Object {
43    authority: Authority,
44}
45
46impl Object {
47    /// Supplies a custom HTTP authority, allowing a GCS host other than the
48    /// standard `storage.googleapis.com` to be used
49    pub fn with_authority(authority: Authority) -> Self {
50        Self { authority }
51    }
52}
53
54impl Default for Object {
55    /// Defaults to the standard GCS location `storage.googleapis.com`
56    fn default() -> Self {
57        Self {
58            authority: Authority::from_static("storage.googleapis.com"),
59        }
60    }
61}
62
63/// [Metadata](https://cloud.google.com/storage/docs/json_api/v1/objects#resource)
64/// associated with an Object.
65#[derive(Default, Serialize, Deserialize)]
66#[serde(rename_all = "camelCase")]
67pub struct Metadata {
68    /// The ID of the object, including the bucket name, object name, and generation number.
69    #[serde(skip_serializing)]
70    pub id: Option<String>,
71    /// The link to this object.
72    #[serde(skip_serializing)]
73    pub self_link: Option<String>,
74    /// The name of the object. Required if not specified by URL parameter. **writable**
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub name: Option<String>,
77    /// The name of the bucket containing this object.
78    #[serde(skip_serializing)]
79    pub bucket: Option<String>,
80    /// The content generation of this object. Used for object versioning.
81    #[serde(default, skip_serializing, deserialize_with = "from_str_opt")]
82    pub generation: Option<i64>,
83    /// The version of the metadata for this object at this generation.
84    /// Used for preconditions and for detecting changes in metadata.
85    /// A metageneration number is only meaningful in the context of a
86    /// particular generation of a particular object.
87    #[serde(default, skip_serializing, deserialize_with = "from_str_opt")]
88    pub metageneration: Option<i64>,
89    /// `Content-Type` of the object data. If an object is stored without
90    /// a `Content-Type`, it is served as `application/octet-stream`. **writable**
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub content_type: Option<String>,
93    /// `Content-Disposition` of the object data. **writable**
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub content_disposition: Option<String>,
96    /// `Content-Encoding` of the object data. **writable**
97    #[serde(skip_serializing_if = "Option::is_none")]
98    pub content_encoding: Option<String>,
99    /// The creation time of the object in RFC 3339 format.
100    #[serde(default, skip_serializing, deserialize_with = "timestamp_rfc3339_opt")]
101    pub time_created: Option<Timestamp>,
102    /// The modification time of the object metadata in RFC 3339 format.
103    #[serde(default, skip_serializing, deserialize_with = "timestamp_rfc3339_opt")]
104    pub updated: Option<Timestamp>,
105    /// Storage class of the object. **writable**
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub storage_class: Option<StorageClass>,
108    /// The time at which the object's storage class was last changed.
109    /// When the object is initially created, it will be set to timeCreated.
110    #[serde(default, skip_serializing, deserialize_with = "timestamp_rfc3339_opt")]
111    pub time_storage_class_updated: Option<Timestamp>,
112    /// `Content-Length` of the data in bytes.
113    #[serde(default, skip_serializing, deserialize_with = "from_str_opt")]
114    pub size: Option<u64>,
115    /// MD5 hash of the data; encoded using base64. For more information
116    /// about using the MD5 hash, see `Hashes and ETags: Best Practices`. **writable**
117    #[serde(skip_serializing_if = "Option::is_none")]
118    pub md5_hash: Option<String>,
119    /// Media download link.
120    #[serde(skip_serializing)]
121    pub media_link: Option<String>,
122    /// `Content-Language` of the object data. **writable**
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub content_language: Option<String>,
125    /// `CRC32c` checksum, as described in RFC 4960, Appendix B; encoded
126    /// using base64 in big-endian byte order. For more information about
127    /// using the `CRC32c` checksum, see `Hashes and ETags: Best Practices`.
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub crc32c: Option<String>,
130    /// HTTP 1.1 Entity tag for the object.
131    #[serde(skip_serializing)]
132    pub etag: Option<String>,
133    /// User-provided metadata, in key/value pairs. **writable**
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub metadata: Option<BTreeMap<String, String>>,
136}
137
138use serde::de::Deserialize;
139
140fn from_str_opt<'de, T, D>(deserializer: D) -> Result<Option<T>, D::Error>
141where
142    T: std::str::FromStr,
143    T::Err: std::fmt::Display,
144    D: serde::de::Deserializer<'de>,
145{
146    let s: &str = Deserialize::deserialize(deserializer)?;
147    T::from_str(s).map_err(serde::de::Error::custom).map(Some)
148}
149
150fn from_str<'de, T, D>(deserializer: D) -> Result<T, D::Error>
151where
152    T: std::str::FromStr,
153    T::Err: std::fmt::Display,
154    D: serde::de::Deserializer<'de>,
155{
156    let s: &str = Deserialize::deserialize(deserializer)?;
157    T::from_str(s).map_err(serde::de::Error::custom)
158}
159
160fn timestamp_rfc3339_opt<'de, D>(deserializer: D) -> Result<Option<Timestamp>, D::Error>
161where
162    D: serde::de::Deserializer<'de>,
163{
164    let ts_str: &str = Deserialize::deserialize(deserializer)?;
165    Timestamp::parse(ts_str, &time::format_description::well_known::Rfc3339)
166        .map_err(serde::de::Error::custom)
167        .map(Some)
168}
tame_gcs/v1/objects.rs

tame_gcs/v1/
objects.rs
