|
17 | 17 |
|
18 | 18 | use std::fmt::Debug;
|
19 | 19 |
|
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. |
22 | 21 | ///
|
23 |
| -/// Via capability, we can know: |
| 22 | +/// # Overview |
24 | 23 | ///
|
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: |
28 | 26 | ///
|
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) |
30 | 30 | ///
|
31 |
| -/// # Notes |
| 31 | +/// # Capability Types |
32 | 32 | ///
|
33 |
| -/// Every operator has two kinds of capabilities: |
| 33 | +/// Every operator maintains two capability sets: |
34 | 34 | ///
|
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. |
39 | 37 | ///
|
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. |
42 | 41 | ///
|
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 |
45 | 43 | ///
|
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: |
48 | 46 | ///
|
49 |
| -/// # Naming Style |
| 47 | +/// - Blocking operations are provided through the BlockingLayer |
50 | 48 | ///
|
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. |
56 | 65 | #[derive(Copy, Clone, Default)]
|
57 | 66 | pub struct Capability {
|
58 |
| - /// If operator supports stat. |
| 67 | + /// Indicates if the operator supports metadata retrieval operations. |
59 | 68 | pub stat: bool,
|
60 |
| - /// If operator supports stat with if match. |
| 69 | + /// Indicates if conditional stat operations using If-Match are supported. |
61 | 70 | 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. |
63 | 72 | 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. |
65 | 74 | 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. |
67 | 76 | 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. |
69 | 78 | pub stat_with_override_content_type: bool,
|
70 |
| - /// if operator supports stat with version. |
| 79 | + /// Indicates if versioned stat operations are supported. |
71 | 80 | 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, |
72 | 101 |
|
73 |
| - /// If operator supports read. |
| 102 | + /// Indicates if the operator supports read operations. |
74 | 103 | pub read: bool,
|
75 |
| - /// If operator supports read with if match. |
| 104 | + /// Indicates if conditional read operations using If-Match are supported. |
76 | 105 | 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. |
78 | 107 | 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. |
80 | 109 | 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. |
82 | 111 | 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. |
84 | 113 | pub read_with_override_content_type: bool,
|
85 |
| - /// if operator supports read with version. |
| 114 | + /// Indicates if versioned read operations are supported. |
86 | 115 | pub read_with_version: bool,
|
87 | 116 |
|
88 |
| - /// If operator supports write. |
| 117 | + /// Indicates if the operator supports write operations. |
89 | 118 | 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. |
91 | 120 | pub write_can_multi: bool,
|
92 |
| - /// If operator supports write with empty content. |
| 121 | + /// Indicates if writing empty content is supported. |
93 | 122 | pub write_can_empty: bool,
|
94 |
| - /// If operator supports write by append. |
| 123 | + /// Indicates if append operations are supported. |
95 | 124 | pub write_can_append: bool,
|
96 |
| - /// If operator supports write with content type. |
| 125 | + /// Indicates if Content-Type can be specified during write operations. |
97 | 126 | 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. |
99 | 128 | 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. |
101 | 130 | 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. |
103 | 132 | 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. |
105 | 134 | 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. |
107 | 136 | 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. |
111 | 139 | 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. |
115 | 142 | 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. |
119 | 145 | 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. |
123 | 148 | pub write_total_max_size: Option<usize>,
|
124 | 149 |
|
125 |
| - /// If operator supports create dir. |
| 150 | + /// Indicates if directory creation is supported. |
126 | 151 | pub create_dir: bool,
|
127 | 152 |
|
128 |
| - /// If operator supports delete. |
| 153 | + /// Indicates if delete operations are supported. |
129 | 154 | pub delete: bool,
|
130 |
| - /// if operator supports delete with version. |
| 155 | + /// Indicates if versioned delete operations are supported. |
131 | 156 | pub delete_with_version: bool,
|
132 | 157 |
|
133 |
| - /// If operator supports copy. |
| 158 | + /// Indicates if copy operations are supported. |
134 | 159 | pub copy: bool,
|
135 | 160 |
|
136 |
| - /// If operator supports rename. |
| 161 | + /// Indicates if rename operations are supported. |
137 | 162 | pub rename: bool,
|
138 | 163 |
|
139 |
| - /// If operator supports list. |
| 164 | + /// Indicates if list operations are supported. |
140 | 165 | pub list: bool,
|
141 |
| - /// If backend supports list with limit. |
| 166 | + /// Indicates if list operations support result limiting. |
142 | 167 | pub list_with_limit: bool,
|
143 |
| - /// If backend supports list with start after. |
| 168 | + /// Indicates if list operations support continuation from a specific point. |
144 | 169 | pub list_with_start_after: bool,
|
145 |
| - /// If backend supports list with recursive. |
| 170 | + /// Indicates if recursive listing is supported. |
146 | 171 | pub list_with_recursive: bool,
|
147 |
| - /// if operator supports list with version. |
| 172 | + /// Indicates if versioned listing is supported. |
148 | 173 | 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, |
149 | 194 |
|
150 |
| - /// If operator supports presign. |
| 195 | + /// Indicates if presigned URL generation is supported. |
151 | 196 | pub presign: bool,
|
152 |
| - /// If operator supports presign read. |
| 197 | + /// Indicates if presigned URLs for read operations are supported. |
153 | 198 | pub presign_read: bool,
|
154 |
| - /// If operator supports presign stat. |
| 199 | + /// Indicates if presigned URLs for stat operations are supported. |
155 | 200 | pub presign_stat: bool,
|
156 |
| - /// If operator supports presign write. |
| 201 | + /// Indicates if presigned URLs for write operations are supported. |
157 | 202 | pub presign_write: bool,
|
158 | 203 |
|
159 |
| - /// If operator supports batch. |
| 204 | + /// Indicates if batch operations are supported. |
160 | 205 | pub batch: bool,
|
161 |
| - /// If operator supports batch delete. |
| 206 | + /// Indicates if batch delete operations are supported. |
162 | 207 | pub batch_delete: bool,
|
163 |
| - /// The max operations that operator supports in batch. |
| 208 | + /// Maximum number of operations supported in a single batch. |
164 | 209 | pub batch_max_operations: Option<usize>,
|
165 | 210 |
|
166 |
| - /// If operator supports blocking. |
| 211 | + /// Indicates if blocking operations are supported. |
167 | 212 | pub blocking: bool,
|
168 | 213 | }
|
169 | 214 |
|
|
0 commit comments