Skip to content

Commit 297bbf9

Browse files
authored
feat: Add {stat,list}_has_* to carry the metadata that backend returns (#5318)
1 parent 41b6f27 commit 297bbf9

File tree

2 files changed

+125
-79
lines changed

2 files changed

+125
-79
lines changed

core/src/types/capability.rs

Lines changed: 124 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -17,153 +17,198 @@
1717

1818
use std::fmt::Debug;
1919

20-
/// Capability is used to describe what operations are supported
21-
/// by current Operator.
20+
/// Capability defines the supported operations and their constraints for a storage Operator.
2221
///
23-
/// Via capability, we can know:
22+
/// # Overview
2423
///
25-
/// - Whether current Operator supports read or not.
26-
/// - Whether current Operator supports read with if match or not.
27-
/// - What's current Operator max supports batch operations count.
24+
/// This structure provides a comprehensive description of an Operator's capabilities,
25+
/// including:
2826
///
29-
/// Add fields of Capabilities with be public and can be accessed directly.
27+
/// - Basic operations support (read, write, delete, etc.)
28+
/// - Advanced operation variants (conditional operations, metadata handling)
29+
/// - Operational constraints (size limits, batch limitations)
3030
///
31-
/// # Notes
31+
/// # Capability Types
3232
///
33-
/// Every operator has two kinds of capabilities:
33+
/// Every operator maintains two capability sets:
3434
///
35-
/// - [`OperatorInfo::native_capability`][crate::OperatorInfo::native_capability] reflects the native
36-
/// support for operations.
37-
/// - [`OperatorInfo::full_capability`][crate::OperatorInfo::full_capability] reflects the full support
38-
/// for operations.
35+
/// 1. [`OperatorInfo::native_capability`][crate::OperatorInfo::native_capability]:
36+
/// Represents operations natively supported by the storage backend.
3937
///
40-
/// It's possible that some operations are not supported by current Operator, but still
41-
/// can be used. For examples:
38+
/// 2. [`OperatorInfo::full_capability`][crate::OperatorInfo::full_capability]:
39+
/// Represents all available operations, including those implemented through
40+
/// alternative mechanisms.
4241
///
43-
/// - S3 doesn't support `seek` natively, but we implement it via `range` header.
44-
/// - S3 doesn't support blocking API, but `BlockingLayer` makes it possible.
42+
/// # Implementation Details
4543
///
46-
/// Users can use full_capability to decide what operations can be used and use native_capability to
47-
/// decide if this operation optimized or not.
44+
/// Some operations might be available even when not natively supported by the
45+
/// backend. For example:
4846
///
49-
/// # Naming Style
47+
/// - Blocking operations are provided through the BlockingLayer
5048
///
51-
/// - Operation itself should be in lower case, like `read`, `write`.
52-
/// - Operation with sub operations should be named like `presign_read`.
53-
/// - Operation with variants should be named like `read_can_seek`.
54-
/// - Operation with arguments should be named like `read_with_range`.
55-
/// - Operation with limitations should be named like `batch_max_operations`.
49+
/// Developers should:
50+
/// - Use `full_capability` to determine available operations
51+
/// - Use `native_capability` to identify optimized operations
52+
///
53+
/// # Field Naming Conventions
54+
///
55+
/// Fields follow these naming patterns:
56+
///
57+
/// - Basic operations: Simple lowercase (e.g., `read`, `write`)
58+
/// - Compound operations: Underscore-separated (e.g., `presign_read`)
59+
/// - Variants: Capability description (e.g., `write_can_empty`)
60+
/// - Parameterized operations: With-style (e.g., `read_with_if_match`)
61+
/// - Limitations: Constraint description (e.g., `write_multi_max_size`)
62+
/// - Metadata Results: Returning metadata capabilities (e.g., `stat_has_content_length`)
63+
///
64+
/// All capability fields are public and can be accessed directly.
5665
#[derive(Copy, Clone, Default)]
5766
pub struct Capability {
58-
/// If operator supports stat.
67+
/// Indicates if the operator supports metadata retrieval operations.
5968
pub stat: bool,
60-
/// If operator supports stat with if match.
69+
/// Indicates if conditional stat operations using If-Match are supported.
6170
pub stat_with_if_match: bool,
62-
/// If operator supports stat with if none match.
71+
/// Indicates if conditional stat operations using If-None-Match are supported.
6372
pub stat_with_if_none_match: bool,
64-
/// if operator supports stat with override cache control.
73+
/// Indicates if Cache-Control header override is supported during stat operations.
6574
pub stat_with_override_cache_control: bool,
66-
/// if operator supports stat with override content disposition.
75+
/// Indicates if Content-Disposition header override is supported during stat operations.
6776
pub stat_with_override_content_disposition: bool,
68-
/// if operator supports stat with override content type.
77+
/// Indicates if Content-Type header override is supported during stat operations.
6978
pub stat_with_override_content_type: bool,
70-
/// if operator supports stat with version.
79+
/// Indicates if versioned stat operations are supported.
7180
pub stat_with_version: bool,
81+
/// Indicates whether cache control information is available in stat response
82+
pub stat_has_cache_control: bool,
83+
/// Indicates whether content disposition information is available in stat response
84+
pub stat_has_content_disposition: bool,
85+
/// Indicates whether content length information is available in stat response
86+
pub stat_has_content_length: bool,
87+
/// Indicates whether content MD5 checksum is available in stat response
88+
pub stat_has_content_md5: bool,
89+
/// Indicates whether content range information is available in stat response
90+
pub stat_has_content_range: bool,
91+
/// Indicates whether content type information is available in stat response
92+
pub stat_has_content_type: bool,
93+
/// Indicates whether entity tag is available in stat response
94+
pub stat_has_etag: bool,
95+
/// Indicates whether last modified timestamp is available in stat response
96+
pub stat_has_last_modified: bool,
97+
/// Indicates whether version information is available in stat response
98+
pub stat_has_version: bool,
99+
/// Indicates whether user-defined metadata is available in stat response
100+
pub stat_has_user_metadata: bool,
72101

73-
/// If operator supports read.
102+
/// Indicates if the operator supports read operations.
74103
pub read: bool,
75-
/// If operator supports read with if match.
104+
/// Indicates if conditional read operations using If-Match are supported.
76105
pub read_with_if_match: bool,
77-
/// If operator supports read with if none match.
106+
/// Indicates if conditional read operations using If-None-Match are supported.
78107
pub read_with_if_none_match: bool,
79-
/// if operator supports read with override cache control.
108+
/// Indicates if Cache-Control header override is supported during read operations.
80109
pub read_with_override_cache_control: bool,
81-
/// if operator supports read with override content disposition.
110+
/// Indicates if Content-Disposition header override is supported during read operations.
82111
pub read_with_override_content_disposition: bool,
83-
/// if operator supports read with override content type.
112+
/// Indicates if Content-Type header override is supported during read operations.
84113
pub read_with_override_content_type: bool,
85-
/// if operator supports read with version.
114+
/// Indicates if versioned read operations are supported.
86115
pub read_with_version: bool,
87116

88-
/// If operator supports write.
117+
/// Indicates if the operator supports write operations.
89118
pub write: bool,
90-
/// If operator supports write can be called in multi times.
119+
/// Indicates if multiple write operations can be performed on the same object.
91120
pub write_can_multi: bool,
92-
/// If operator supports write with empty content.
121+
/// Indicates if writing empty content is supported.
93122
pub write_can_empty: bool,
94-
/// If operator supports write by append.
123+
/// Indicates if append operations are supported.
95124
pub write_can_append: bool,
96-
/// If operator supports write with content type.
125+
/// Indicates if Content-Type can be specified during write operations.
97126
pub write_with_content_type: bool,
98-
/// If operator supports write with content disposition.
127+
/// Indicates if Content-Disposition can be specified during write operations.
99128
pub write_with_content_disposition: bool,
100-
/// If operator supports write with cache control.
129+
/// Indicates if Cache-Control can be specified during write operations.
101130
pub write_with_cache_control: bool,
102-
/// If operator supports write with if none match.
131+
/// Indicates if conditional write operations using If-None-Match are supported.
103132
pub write_with_if_none_match: bool,
104-
/// If operator supports write with if not exist.
133+
/// Indicates if write operations can be conditional on object non-existence.
105134
pub write_with_if_not_exists: bool,
106-
/// If operator supports write with user defined metadata
135+
/// Indicates if custom user metadata can be attached during write operations.
107136
pub write_with_user_metadata: bool,
108-
/// write_multi_max_size is the max size that services support in write_multi.
109-
///
110-
/// For example, AWS S3 supports 5GiB as max in write_multi.
137+
/// Maximum size supported for multipart uploads.
138+
/// For example, AWS S3 supports up to 5GiB per part in multipart uploads.
111139
pub write_multi_max_size: Option<usize>,
112-
/// write_multi_min_size is the min size that services support in write_multi.
113-
///
114-
/// For example, AWS S3 requires at least 5MiB in write_multi expect the last one.
140+
/// Minimum size required for multipart uploads (except for the last part).
141+
/// For example, AWS S3 requires at least 5MiB per part.
115142
pub write_multi_min_size: Option<usize>,
116-
/// write_multi_align_size is the align size that services required in write_multi.
117-
///
118-
/// For example, Google GCS requires align size to 256KiB in write_multi.
143+
/// Required size alignment for multipart uploads.
144+
/// For example, Google GCS requires 256KiB alignment.
119145
pub write_multi_align_size: Option<usize>,
120-
/// write_total_max_size is the max size that services support in write_total.
121-
///
122-
/// For example, Cloudflare D1 supports 1MB as max in write_total.
146+
/// Maximum total size supported for write operations.
147+
/// For example, Cloudflare D1 has a 1MB total size limit.
123148
pub write_total_max_size: Option<usize>,
124149

125-
/// If operator supports create dir.
150+
/// Indicates if directory creation is supported.
126151
pub create_dir: bool,
127152

128-
/// If operator supports delete.
153+
/// Indicates if delete operations are supported.
129154
pub delete: bool,
130-
/// if operator supports delete with version.
155+
/// Indicates if versioned delete operations are supported.
131156
pub delete_with_version: bool,
132157

133-
/// If operator supports copy.
158+
/// Indicates if copy operations are supported.
134159
pub copy: bool,
135160

136-
/// If operator supports rename.
161+
/// Indicates if rename operations are supported.
137162
pub rename: bool,
138163

139-
/// If operator supports list.
164+
/// Indicates if list operations are supported.
140165
pub list: bool,
141-
/// If backend supports list with limit.
166+
/// Indicates if list operations support result limiting.
142167
pub list_with_limit: bool,
143-
/// If backend supports list with start after.
168+
/// Indicates if list operations support continuation from a specific point.
144169
pub list_with_start_after: bool,
145-
/// If backend supports list with recursive.
170+
/// Indicates if recursive listing is supported.
146171
pub list_with_recursive: bool,
147-
/// if operator supports list with version.
172+
/// Indicates if versioned listing is supported.
148173
pub list_with_version: bool,
174+
/// Indicates whether cache control information is available in list response
175+
pub list_has_cache_control: bool,
176+
/// Indicates whether content disposition information is available in list response
177+
pub list_has_content_disposition: bool,
178+
/// Indicates whether content length information is available in list response
179+
pub list_has_content_length: bool,
180+
/// Indicates whether content MD5 checksum is available in list response
181+
pub list_has_content_md5: bool,
182+
/// Indicates whether content range information is available in list response
183+
pub list_has_content_range: bool,
184+
/// Indicates whether content type information is available in list response
185+
pub list_has_content_type: bool,
186+
/// Indicates whether entity tag is available in list response
187+
pub list_has_etag: bool,
188+
/// Indicates whether last modified timestamp is available in list response
189+
pub list_has_last_modified: bool,
190+
/// Indicates whether version information is available in list response
191+
pub list_has_version: bool,
192+
/// Indicates whether user-defined metadata is available in list response
193+
pub list_has_user_metadata: bool,
149194

150-
/// If operator supports presign.
195+
/// Indicates if presigned URL generation is supported.
151196
pub presign: bool,
152-
/// If operator supports presign read.
197+
/// Indicates if presigned URLs for read operations are supported.
153198
pub presign_read: bool,
154-
/// If operator supports presign stat.
199+
/// Indicates if presigned URLs for stat operations are supported.
155200
pub presign_stat: bool,
156-
/// If operator supports presign write.
201+
/// Indicates if presigned URLs for write operations are supported.
157202
pub presign_write: bool,
158203

159-
/// If operator supports batch.
204+
/// Indicates if batch operations are supported.
160205
pub batch: bool,
161-
/// If operator supports batch delete.
206+
/// Indicates if batch delete operations are supported.
162207
pub batch_delete: bool,
163-
/// The max operations that operator supports in batch.
208+
/// Maximum number of operations supported in a single batch.
164209
pub batch_max_operations: Option<usize>,
165210

166-
/// If operator supports blocking.
211+
/// Indicates if blocking operations are supported.
167212
pub blocking: bool,
168213
}
169214

core/src/types/metadata.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ pub struct Metadata {
4747
etag: Option<String>,
4848
last_modified: Option<DateTime<Utc>>,
4949
version: Option<String>,
50+
5051
user_metadata: Option<HashMap<String, String>>,
5152
}
5253

0 commit comments

Comments
 (0)