opendal 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (566) hide show
  1. checksums.yaml +4 -4
  2. data/Cargo.lock +89 -56
  3. data/Cargo.toml +1 -1
  4. data/DEPENDENCIES.rust.tsv +55 -41
  5. data/LICENSE +201 -0
  6. data/LICENSE-MPL-2.0.txt +373 -0
  7. data/NOTICE +5 -0
  8. data/core/CHANGELOG.md +175 -0
  9. data/core/Cargo.lock +225 -298
  10. data/core/Cargo.toml +100 -94
  11. data/core/DEPENDENCIES.rust.tsv +44 -73
  12. data/core/benches/metadata/README.md +21 -0
  13. data/core/benches/metadata/main.rs +541 -0
  14. data/core/benches/vs_fs/Cargo.toml +1 -1
  15. data/core/benches/vs_s3/Cargo.toml +1 -1
  16. data/core/core/Cargo.toml +7 -2
  17. data/core/core/src/blocking/delete.rs +5 -1
  18. data/core/core/src/blocking/operator.rs +12 -0
  19. data/core/core/src/blocking/read/std_reader.rs +25 -0
  20. data/core/core/src/docs/concepts.rs +70 -94
  21. data/core/core/src/docs/internals/accessor.rs +62 -293
  22. data/core/core/src/docs/internals/layer.rs +43 -59
  23. data/core/core/src/docs/internals/mod.rs +21 -23
  24. data/core/core/src/docs/mod.rs +10 -6
  25. data/core/core/src/docs/performance/concurrent_write.md +92 -55
  26. data/core/core/src/docs/performance/http_optimization.md +120 -104
  27. data/core/core/src/docs/performance/mod.rs +8 -6
  28. data/core/core/src/docs/rfcs/5485_conditional_reader.md +4 -0
  29. data/core/core/src/docs/rfcs/7182_restore_api.md +139 -557
  30. data/core/core/src/docs/rfcs/7945_limited_read.md +210 -0
  31. data/core/core/src/docs/rfcs/7948_s3_provider_presets.md +254 -0
  32. data/core/core/src/docs/rfcs/8109_writer_copy_from.md +330 -0
  33. data/core/core/src/docs/rfcs/8145_conflict_error_kind.md +210 -0
  34. data/core/core/src/docs/rfcs/8147_write_if_not_changed.md +233 -0
  35. data/core/core/src/docs/rfcs/8188_compose_api.md +292 -0
  36. data/core/core/src/docs/rfcs/8194_compact_metadata_and_operation_args.md +444 -0
  37. data/core/core/src/docs/rfcs/README.md +14 -3
  38. data/core/core/src/docs/rfcs/mod.rs +46 -22
  39. data/core/core/src/docs/specs/README.md +34 -0
  40. data/core/core/src/docs/specs/conditional-operations.md +156 -0
  41. data/core/core/src/docs/specs/metadata.md +63 -0
  42. data/core/core/src/docs/specs/mod.rs +26 -0
  43. data/core/core/src/docs/upgrade.md +114 -1
  44. data/core/core/src/layers/capability_override.rs +15 -2
  45. data/core/core/src/layers/complete.rs +347 -43
  46. data/core/core/src/layers/correctness_check.rs +718 -51
  47. data/core/core/src/layers/error_context.rs +76 -2
  48. data/core/core/src/layers/simulate.rs +91 -28
  49. data/core/core/src/lib.rs +1 -0
  50. data/core/core/src/raw/accessor.rs +91 -15
  51. data/core/core/src/raw/enum_utils.rs +7 -0
  52. data/core/core/src/raw/http_util/header.rs +22 -17
  53. data/core/core/src/raw/oio/compose/api.rs +92 -0
  54. data/core/core/src/raw/oio/compose/mod.rs +19 -0
  55. data/core/core/src/raw/oio/copy/api.rs +3 -3
  56. data/core/core/src/raw/oio/copy/block_copy.rs +32 -4
  57. data/core/core/src/raw/oio/copy/multipart_copy.rs +36 -7
  58. data/core/core/src/raw/oio/entry.rs +48 -22
  59. data/core/core/src/raw/oio/list/flat_list.rs +1 -1
  60. data/core/core/src/raw/oio/list/hierarchy_list.rs +3 -2
  61. data/core/core/src/raw/oio/mod.rs +3 -0
  62. data/core/core/src/raw/oio/read/position_read.rs +1 -1
  63. data/core/core/src/raw/oio/write/api.rs +40 -0
  64. data/core/core/src/raw/oio/write/append_write.rs +4 -4
  65. data/core/core/src/raw/oio/write/block_write.rs +2 -2
  66. data/core/core/src/raw/oio/write/multipart_write.rs +181 -48
  67. data/core/core/src/raw/oio/write/position_write.rs +1 -1
  68. data/core/core/src/raw/operation.rs +6 -0
  69. data/core/core/src/raw/ops.rs +1191 -456
  70. data/core/core/src/raw/rps.rs +11 -0
  71. data/core/core/src/raw/time.rs +14 -3
  72. data/core/core/src/services/memory/backend.rs +5 -10
  73. data/core/core/src/services/memory/lister.rs +4 -4
  74. data/core/core/src/services/memory/writer.rs +7 -6
  75. data/core/core/src/types/buffer.rs +102 -12
  76. data/core/core/src/types/bytes_range.rs +20 -1
  77. data/core/core/src/types/capability.rs +65 -0
  78. data/core/core/src/types/compact.rs +329 -0
  79. data/core/core/src/types/compose/composer.rs +183 -0
  80. data/core/core/src/types/compose/input.rs +57 -0
  81. data/core/core/src/types/compose/mod.rs +23 -0
  82. data/core/core/src/types/context/read.rs +16 -11
  83. data/core/core/src/types/context/write.rs +150 -2
  84. data/core/core/src/types/copy.rs +5 -3
  85. data/core/core/src/types/delete/deleter.rs +20 -12
  86. data/core/core/src/types/delete/input.rs +22 -64
  87. data/core/core/src/types/delete/mod.rs +0 -1
  88. data/core/core/src/types/entry.rs +8 -14
  89. data/core/core/src/types/error.rs +28 -11
  90. data/core/core/src/types/metadata.rs +709 -322
  91. data/core/core/src/types/mod.rs +9 -1
  92. data/core/core/src/types/operator/operator.rs +278 -29
  93. data/core/core/src/types/operator/operator_futures.rs +466 -105
  94. data/core/core/src/types/options.rs +631 -158
  95. data/core/core/src/types/read/futures_async_reader.rs +663 -50
  96. data/core/core/src/types/read/reader.rs +23 -5
  97. data/core/core/src/types/write/futures_async_writer.rs +27 -0
  98. data/core/core/src/types/write/writer.rs +47 -5
  99. data/core/http-transports/reqwest/Cargo.toml +1 -1
  100. data/core/layers/async-backtrace/Cargo.toml +2 -2
  101. data/core/layers/async-backtrace/src/lib.rs +21 -2
  102. data/core/layers/await-tree/Cargo.toml +2 -2
  103. data/core/layers/await-tree/src/lib.rs +25 -2
  104. data/core/layers/capability-check/Cargo.toml +2 -2
  105. data/core/layers/capability-check/src/lib.rs +98 -10
  106. data/core/layers/chaos/Cargo.toml +2 -2
  107. data/core/layers/chaos/src/lib.rs +18 -3
  108. data/core/layers/concurrent-limit/Cargo.toml +3 -3
  109. data/core/layers/concurrent-limit/src/lib.rs +53 -13
  110. data/core/layers/dtrace/Cargo.toml +2 -2
  111. data/core/layers/dtrace/src/lib.rs +29 -2
  112. data/core/layers/fastmetrics/Cargo.toml +3 -3
  113. data/core/layers/fastrace/Cargo.toml +2 -2
  114. data/core/layers/fastrace/src/lib.rs +28 -2
  115. data/core/layers/foyer/Cargo.toml +2 -2
  116. data/core/layers/foyer/src/full.rs +16 -19
  117. data/core/layers/foyer/src/lib.rs +67 -14
  118. data/core/layers/hotpath/Cargo.toml +2 -2
  119. data/core/layers/hotpath/src/lib.rs +20 -2
  120. data/core/layers/immutable-index/Cargo.toml +2 -2
  121. data/core/layers/immutable-index/src/lib.rs +48 -24
  122. data/core/layers/logging/Cargo.toml +2 -2
  123. data/core/layers/logging/src/lib.rs +46 -2
  124. data/core/layers/metrics/Cargo.toml +3 -3
  125. data/core/layers/mime-guess/Cargo.toml +2 -2
  126. data/core/layers/mime-guess/src/lib.rs +31 -4
  127. data/core/layers/observe-metrics-common/Cargo.toml +2 -2
  128. data/core/layers/observe-metrics-common/src/lib.rs +55 -2
  129. data/core/layers/otelmetrics/Cargo.toml +3 -3
  130. data/core/layers/oteltrace/Cargo.toml +2 -2
  131. data/core/layers/oteltrace/src/lib.rs +27 -2
  132. data/core/layers/prometheus/Cargo.toml +3 -3
  133. data/core/layers/prometheus-client/Cargo.toml +3 -3
  134. data/core/layers/retry/Cargo.toml +4 -4
  135. data/core/layers/retry/src/lib.rs +76 -19
  136. data/core/layers/route/Cargo.toml +3 -3
  137. data/core/layers/route/src/lib.rs +34 -7
  138. data/core/layers/tail-cut/Cargo.toml +2 -2
  139. data/core/layers/tail-cut/src/lib.rs +28 -2
  140. data/core/layers/throttle/Cargo.toml +2 -2
  141. data/core/layers/throttle/src/lib.rs +19 -2
  142. data/core/layers/timeout/Cargo.toml +3 -3
  143. data/core/layers/timeout/src/lib.rs +38 -13
  144. data/core/layers/tracing/Cargo.toml +2 -2
  145. data/core/layers/tracing/src/lib.rs +24 -3
  146. data/core/services/aliyun-drive/Cargo.toml +2 -2
  147. data/core/services/aliyun-drive/src/backend.rs +34 -24
  148. data/core/services/aliyun-drive/src/core.rs +143 -54
  149. data/core/services/aliyun-drive/src/lister.rs +19 -18
  150. data/core/services/aliyun-drive/src/reader.rs +4 -1
  151. data/core/services/aliyun-drive/src/writer.rs +3 -3
  152. data/core/services/alluxio/Cargo.toml +1 -1
  153. data/core/services/alluxio/src/backend.rs +1 -1
  154. data/core/services/alluxio/src/core.rs +113 -94
  155. data/core/services/alluxio/src/reader.rs +7 -3
  156. data/core/services/alluxio/src/writer.rs +2 -2
  157. data/core/services/azblob/Cargo.toml +2 -2
  158. data/core/services/azblob/src/backend.rs +17 -9
  159. data/core/services/azblob/src/copier.rs +41 -15
  160. data/core/services/azblob/src/core.rs +372 -135
  161. data/core/services/azblob/src/deleter.rs +41 -18
  162. data/core/services/azblob/src/lister.rs +16 -10
  163. data/core/services/azblob/src/reader.rs +4 -1
  164. data/core/services/azblob/src/writer.rs +48 -15
  165. data/core/services/azdls/Cargo.toml +3 -3
  166. data/core/services/azdls/src/backend.rs +45 -15
  167. data/core/services/azdls/src/config.rs +4 -1
  168. data/core/services/azdls/src/core.rs +276 -87
  169. data/core/services/azdls/src/deleter.rs +13 -4
  170. data/core/services/azdls/src/lister.rs +18 -12
  171. data/core/services/azdls/src/reader.rs +6 -2
  172. data/core/services/azdls/src/writer.rs +44 -23
  173. data/core/services/azfile/Cargo.toml +2 -2
  174. data/core/services/azfile/src/backend.rs +24 -8
  175. data/core/services/azfile/src/core.rs +195 -77
  176. data/core/services/azfile/src/deleter.rs +8 -1
  177. data/core/services/azfile/src/lister.rs +20 -14
  178. data/core/services/azfile/src/reader.rs +5 -2
  179. data/core/services/azfile/src/writer.rs +27 -15
  180. data/core/services/azure-common/Cargo.toml +1 -1
  181. data/core/services/b2/Cargo.toml +2 -2
  182. data/core/services/b2/src/backend.rs +30 -11
  183. data/core/services/b2/src/core.rs +134 -120
  184. data/core/services/b2/src/deleter.rs +1 -1
  185. data/core/services/b2/src/lister.rs +5 -2
  186. data/core/services/b2/src/reader.rs +5 -2
  187. data/core/services/b2/src/writer.rs +29 -12
  188. data/core/services/cacache/Cargo.toml +1 -1
  189. data/core/services/cacache/src/backend.rs +4 -5
  190. data/core/services/cacache/src/reader.rs +4 -1
  191. data/core/services/cacache/src/writer.rs +6 -2
  192. data/core/services/cloudflare-kv/Cargo.toml +1 -1
  193. data/core/services/cloudflare-kv/src/backend.rs +26 -15
  194. data/core/services/cloudflare-kv/src/config.rs +13 -2
  195. data/core/services/cloudflare-kv/src/core.rs +62 -56
  196. data/core/services/cloudflare-kv/src/deleter.rs +12 -3
  197. data/core/services/cloudflare-kv/src/lister.rs +66 -17
  198. data/core/services/cloudflare-kv/src/reader.rs +14 -9
  199. data/core/services/cloudflare-kv/src/writer.rs +10 -7
  200. data/core/services/compfs/Cargo.toml +1 -1
  201. data/core/services/compfs/src/backend.rs +11 -7
  202. data/core/services/compfs/src/lister.rs +7 -7
  203. data/core/services/compfs/src/writer.rs +1 -1
  204. data/core/services/cos/Cargo.toml +1 -1
  205. data/core/services/cos/src/backend.rs +129 -16
  206. data/core/services/cos/src/core.rs +198 -80
  207. data/core/services/cos/src/deleter.rs +4 -1
  208. data/core/services/cos/src/lister.rs +42 -27
  209. data/core/services/cos/src/reader.rs +6 -2
  210. data/core/services/cos/src/writer.rs +45 -21
  211. data/core/services/d1/Cargo.toml +1 -1
  212. data/core/services/d1/src/backend.rs +6 -5
  213. data/core/services/d1/src/core.rs +79 -63
  214. data/core/services/d1/src/reader.rs +4 -1
  215. data/core/services/d1/src/writer.rs +6 -2
  216. data/core/services/dashmap/Cargo.toml +1 -1
  217. data/core/services/dashmap/src/backend.rs +2 -2
  218. data/core/services/dashmap/src/reader.rs +4 -1
  219. data/core/services/dashmap/src/writer.rs +11 -8
  220. data/core/services/dbfs/Cargo.toml +1 -1
  221. data/core/services/dbfs/src/backend.rs +21 -15
  222. data/core/services/dbfs/src/core.rs +65 -60
  223. data/core/services/dbfs/src/deleter.rs +4 -1
  224. data/core/services/dbfs/src/lister.rs +10 -10
  225. data/core/services/dbfs/src/writer.rs +6 -3
  226. data/core/services/dropbox/Cargo.toml +2 -2
  227. data/core/services/dropbox/src/backend.rs +30 -23
  228. data/core/services/dropbox/src/core.rs +65 -63
  229. data/core/services/dropbox/src/deleter.rs +1 -1
  230. data/core/services/dropbox/src/lister.rs +17 -8
  231. data/core/services/dropbox/src/reader.rs +4 -1
  232. data/core/services/dropbox/src/writer.rs +13 -10
  233. data/core/services/etcd/Cargo.toml +1 -1
  234. data/core/services/etcd/src/backend.rs +8 -5
  235. data/core/services/etcd/src/core.rs +5 -11
  236. data/core/services/etcd/src/lister.rs +6 -1
  237. data/core/services/etcd/src/reader.rs +4 -1
  238. data/core/services/etcd/src/writer.rs +6 -3
  239. data/core/services/foundationdb/Cargo.toml +1 -1
  240. data/core/services/foundationdb/src/backend.rs +6 -5
  241. data/core/services/foundationdb/src/reader.rs +4 -1
  242. data/core/services/foundationdb/src/writer.rs +6 -2
  243. data/core/services/foyer/Cargo.toml +3 -3
  244. data/core/services/foyer/src/backend.rs +6 -5
  245. data/core/services/foyer/src/reader.rs +4 -1
  246. data/core/services/foyer/src/writer.rs +6 -2
  247. data/core/services/fs/Cargo.toml +1 -1
  248. data/core/services/fs/src/backend.rs +4 -3
  249. data/core/services/fs/src/core.rs +44 -26
  250. data/core/services/fs/src/lister.rs +9 -6
  251. data/core/services/fs/src/writer.rs +20 -13
  252. data/core/services/ftp/Cargo.toml +4 -6
  253. data/core/services/ftp/src/backend.rs +9 -5
  254. data/core/services/ftp/src/core.rs +9 -7
  255. data/core/services/ftp/src/lister.rs +7 -8
  256. data/core/services/ftp/src/reader.rs +3 -3
  257. data/core/services/ftp/src/writer.rs +3 -3
  258. data/core/services/gcs/Cargo.toml +4 -2
  259. data/core/services/gcs/src/backend.rs +53 -7
  260. data/core/services/gcs/src/composer.rs +705 -0
  261. data/core/services/gcs/src/copier.rs +14 -4
  262. data/core/services/gcs/src/core.rs +828 -124
  263. data/core/services/gcs/src/deleter.rs +33 -18
  264. data/core/services/gcs/src/lib.rs +1 -0
  265. data/core/services/gcs/src/lister.rs +21 -12
  266. data/core/services/gcs/src/reader.rs +12 -5
  267. data/core/services/gcs/src/writer.rs +632 -10
  268. data/core/services/gcs-grpc/Cargo.toml +58 -0
  269. data/core/services/gcs-grpc/README.md +19 -0
  270. data/core/services/gcs-grpc/proto/README.md +23 -0
  271. data/core/services/gcs-grpc/proto/google/storage/v2/storage.proto +171 -0
  272. data/core/services/gcs-grpc/proto/upstream-descriptor.bin +0 -0
  273. data/core/services/gcs-grpc/src/backend.rs +449 -0
  274. data/core/services/gcs-grpc/src/config.rs +116 -0
  275. data/core/services/gcs-grpc/src/copier.rs +98 -0
  276. data/core/services/gcs-grpc/src/core.rs +298 -0
  277. data/core/services/gcs-grpc/src/deleter.rs +65 -0
  278. data/core/services/gcs-grpc/src/docs.md +19 -0
  279. data/core/services/gcs-grpc/src/generated/google.storage.v2.rs +541 -0
  280. data/core/services/gcs-grpc/src/generated/mod.rs +24 -0
  281. data/core/services/gcs-grpc/src/lib.rs +43 -0
  282. data/core/services/gcs-grpc/src/lister.rs +125 -0
  283. data/core/services/gcs-grpc/src/reader.rs +140 -0
  284. data/core/services/gcs-grpc/src/writer.rs +780 -0
  285. data/core/services/gdrive/Cargo.toml +2 -2
  286. data/core/services/gdrive/src/backend.rs +123 -69
  287. data/core/services/gdrive/src/core.rs +87 -69
  288. data/core/services/gdrive/src/deleter.rs +8 -2
  289. data/core/services/gdrive/src/lister.rs +38 -26
  290. data/core/services/gdrive/src/path_index.rs +2 -2
  291. data/core/services/gdrive/src/reader.rs +9 -3
  292. data/core/services/gdrive/src/writer.rs +13 -7
  293. data/core/services/ghac/Cargo.toml +2 -2
  294. data/core/services/ghac/src/backend.rs +5 -2
  295. data/core/services/ghac/src/core.rs +59 -37
  296. data/core/services/ghac/src/reader.rs +5 -2
  297. data/core/services/ghac/src/writer.rs +16 -6
  298. data/core/services/github/Cargo.toml +1 -1
  299. data/core/services/github/src/backend.rs +16 -8
  300. data/core/services/github/src/core.rs +88 -76
  301. data/core/services/github/src/lister.rs +17 -15
  302. data/core/services/github/src/reader.rs +5 -2
  303. data/core/services/github/src/writer.rs +12 -6
  304. data/core/services/goosefs/Cargo.toml +2 -2
  305. data/core/services/goosefs/src/backend.rs +2 -2
  306. data/core/services/goosefs/src/core.rs +291 -208
  307. data/core/services/goosefs/src/docs.md +3 -0
  308. data/core/services/goosefs/src/lister.rs +2 -3
  309. data/core/services/goosefs/src/reader.rs +7 -3
  310. data/core/services/goosefs/src/writer.rs +21 -10
  311. data/core/services/goosefs/tests/safe_conditional_put.rs +37 -0
  312. data/core/services/gridfs/Cargo.toml +2 -2
  313. data/core/services/gridfs/src/backend.rs +12 -8
  314. data/core/services/gridfs/src/core.rs +1 -1
  315. data/core/services/gridfs/src/reader.rs +4 -1
  316. data/core/services/gridfs/src/writer.rs +6 -2
  317. data/core/services/hdfs/Cargo.toml +1 -1
  318. data/core/services/hdfs/src/backend.rs +1 -1
  319. data/core/services/hdfs/src/core.rs +7 -4
  320. data/core/services/hdfs/src/lister.rs +7 -9
  321. data/core/services/hdfs/src/writer.rs +5 -1
  322. data/core/services/hdfs-native/Cargo.toml +1 -1
  323. data/core/services/hdfs-native/src/backend.rs +1 -1
  324. data/core/services/hdfs-native/src/core.rs +44 -50
  325. data/core/services/hdfs-native/src/lister.rs +8 -10
  326. data/core/services/hdfs-native/src/writer.rs +5 -1
  327. data/core/services/hf/Cargo.toml +4 -3
  328. data/core/services/hf/src/backend.rs +4 -3
  329. data/core/services/hf/src/core.rs +907 -153
  330. data/core/services/hf/src/lister.rs +16 -6
  331. data/core/services/hf/src/reader.rs +377 -57
  332. data/core/services/hf/src/writer.rs +6 -2
  333. data/core/services/http/Cargo.toml +3 -3
  334. data/core/services/http/src/backend.rs +8 -6
  335. data/core/services/http/src/core.rs +57 -35
  336. data/core/services/http/src/reader.rs +5 -2
  337. data/core/services/ipfs/Cargo.toml +1 -1
  338. data/core/services/ipfs/src/backend.rs +20 -9
  339. data/core/services/ipfs/src/core.rs +43 -34
  340. data/core/services/ipfs/src/reader.rs +5 -2
  341. data/core/services/ipmfs/Cargo.toml +1 -1
  342. data/core/services/ipmfs/src/backend.rs +17 -8
  343. data/core/services/ipmfs/src/core.rs +66 -60
  344. data/core/services/ipmfs/src/deleter.rs +5 -2
  345. data/core/services/ipmfs/src/lister.rs +15 -12
  346. data/core/services/ipmfs/src/reader.rs +5 -2
  347. data/core/services/ipmfs/src/writer.rs +6 -3
  348. data/core/services/koofr/Cargo.toml +2 -2
  349. data/core/services/koofr/src/backend.rs +46 -17
  350. data/core/services/koofr/src/core.rs +64 -48
  351. data/core/services/koofr/src/deleter.rs +4 -1
  352. data/core/services/koofr/src/lister.rs +11 -10
  353. data/core/services/koofr/src/reader.rs +5 -2
  354. data/core/services/koofr/src/writer.rs +13 -7
  355. data/core/services/lakefs/Cargo.toml +1 -1
  356. data/core/services/lakefs/src/backend.rs +25 -8
  357. data/core/services/lakefs/src/core.rs +79 -73
  358. data/core/services/lakefs/src/deleter.rs +4 -1
  359. data/core/services/lakefs/src/lister.rs +17 -14
  360. data/core/services/lakefs/src/reader.rs +5 -2
  361. data/core/services/lakefs/src/writer.rs +11 -10
  362. data/core/services/memcached/Cargo.toml +1 -1
  363. data/core/services/memcached/src/backend.rs +57 -7
  364. data/core/services/memcached/src/config.rs +13 -2
  365. data/core/services/memcached/src/core.rs +11 -1
  366. data/core/services/memcached/src/reader.rs +4 -1
  367. data/core/services/memcached/src/writer.rs +6 -2
  368. data/core/services/mini_moka/Cargo.toml +1 -1
  369. data/core/services/mini_moka/src/backend.rs +8 -8
  370. data/core/services/mini_moka/src/reader.rs +4 -1
  371. data/core/services/mini_moka/src/writer.rs +11 -7
  372. data/core/services/moka/Cargo.toml +1 -1
  373. data/core/services/moka/src/backend.rs +7 -7
  374. data/core/services/moka/src/reader.rs +4 -1
  375. data/core/services/moka/src/writer.rs +10 -6
  376. data/core/services/mongodb/Cargo.toml +2 -2
  377. data/core/services/mongodb/src/backend.rs +7 -6
  378. data/core/services/mongodb/src/core.rs +1 -1
  379. data/core/services/mongodb/src/reader.rs +4 -1
  380. data/core/services/mongodb/src/writer.rs +6 -2
  381. data/core/services/monoiofs/Cargo.toml +2 -2
  382. data/core/services/monoiofs/src/backend.rs +16 -10
  383. data/core/services/monoiofs/src/core.rs +8 -9
  384. data/core/services/monoiofs/src/reader.rs +8 -10
  385. data/core/services/monoiofs/src/writer.rs +19 -24
  386. data/core/services/mysql/Cargo.toml +2 -2
  387. data/core/services/mysql/src/backend.rs +7 -6
  388. data/core/services/mysql/src/core.rs +1 -1
  389. data/core/services/mysql/src/lister.rs +7 -3
  390. data/core/services/mysql/src/reader.rs +4 -1
  391. data/core/services/mysql/src/writer.rs +6 -2
  392. data/core/services/obs/Cargo.toml +1 -1
  393. data/core/services/obs/src/backend.rs +29 -11
  394. data/core/services/obs/src/core.rs +81 -82
  395. data/core/services/obs/src/deleter.rs +4 -1
  396. data/core/services/obs/src/lister.rs +12 -5
  397. data/core/services/obs/src/reader.rs +5 -2
  398. data/core/services/obs/src/writer.rs +40 -19
  399. data/core/services/onedrive/Cargo.toml +2 -2
  400. data/core/services/onedrive/src/backend.rs +30 -21
  401. data/core/services/onedrive/src/config.rs +2 -2
  402. data/core/services/onedrive/src/core.rs +191 -90
  403. data/core/services/onedrive/src/deleter.rs +5 -2
  404. data/core/services/onedrive/src/graph_model.rs +10 -51
  405. data/core/services/onedrive/src/lister.rs +60 -24
  406. data/core/services/onedrive/src/reader.rs +17 -2
  407. data/core/services/onedrive/src/writer.rs +26 -15
  408. data/core/services/opfs/Cargo.toml +1 -1
  409. data/core/services/opfs/src/backend.rs +6 -13
  410. data/core/services/opfs/src/core.rs +33 -37
  411. data/core/services/opfs/src/lister.rs +4 -4
  412. data/core/services/opfs/src/writer.rs +1 -3
  413. data/core/services/oss/Cargo.toml +1 -1
  414. data/core/services/oss/src/backend.rs +40 -8
  415. data/core/services/oss/src/core.rs +192 -92
  416. data/core/services/oss/src/deleter.rs +16 -6
  417. data/core/services/oss/src/lister.rs +43 -27
  418. data/core/services/oss/src/reader.rs +6 -2
  419. data/core/services/oss/src/writer.rs +40 -22
  420. data/core/services/pcloud/Cargo.toml +1 -1
  421. data/core/services/pcloud/src/backend.rs +40 -6
  422. data/core/services/pcloud/src/core.rs +80 -66
  423. data/core/services/pcloud/src/deleter.rs +8 -1
  424. data/core/services/pcloud/src/lister.rs +4 -1
  425. data/core/services/pcloud/src/reader.rs +5 -2
  426. data/core/services/pcloud/src/writer.rs +6 -3
  427. data/core/services/persy/Cargo.toml +1 -1
  428. data/core/services/persy/src/backend.rs +6 -5
  429. data/core/services/persy/src/core.rs +60 -15
  430. data/core/services/persy/src/reader.rs +4 -1
  431. data/core/services/persy/src/writer.rs +6 -2
  432. data/core/services/postgresql/Cargo.toml +2 -2
  433. data/core/services/postgresql/src/backend.rs +7 -6
  434. data/core/services/postgresql/src/core.rs +1 -1
  435. data/core/services/postgresql/src/reader.rs +4 -1
  436. data/core/services/postgresql/src/writer.rs +6 -2
  437. data/core/services/redb/Cargo.toml +1 -1
  438. data/core/services/redb/src/backend.rs +6 -5
  439. data/core/services/redb/src/reader.rs +4 -1
  440. data/core/services/redb/src/writer.rs +6 -2
  441. data/core/services/redis/Cargo.toml +1 -1
  442. data/core/services/redis/src/backend.rs +18 -8
  443. data/core/services/redis/src/config.rs +13 -2
  444. data/core/services/redis/src/reader.rs +8 -4
  445. data/core/services/redis/src/writer.rs +6 -2
  446. data/core/services/rocksdb/Cargo.toml +1 -1
  447. data/core/services/rocksdb/src/backend.rs +6 -5
  448. data/core/services/rocksdb/src/lister.rs +6 -5
  449. data/core/services/rocksdb/src/reader.rs +4 -1
  450. data/core/services/rocksdb/src/writer.rs +6 -2
  451. data/core/services/s3/Cargo.toml +5 -4
  452. data/core/services/s3/src/backend.rs +995 -39
  453. data/core/services/s3/src/compatible_services.md +57 -0
  454. data/core/services/s3/src/config.rs +16 -0
  455. data/core/services/s3/src/copier.rs +190 -55
  456. data/core/services/s3/src/core.rs +299 -190
  457. data/core/services/s3/src/deleter.rs +26 -7
  458. data/core/services/s3/src/docs.md +57 -0
  459. data/core/services/s3/src/lister.rs +55 -36
  460. data/core/services/s3/src/reader.rs +22 -2
  461. data/core/services/s3/src/writer.rs +154 -32
  462. data/core/services/seafile/Cargo.toml +2 -2
  463. data/core/services/seafile/src/backend.rs +3 -3
  464. data/core/services/seafile/src/core.rs +105 -79
  465. data/core/services/seafile/src/lister.rs +11 -8
  466. data/core/services/seafile/src/reader.rs +5 -2
  467. data/core/services/seafile/src/writer.rs +6 -3
  468. data/core/services/sftp/Cargo.toml +1 -1
  469. data/core/services/sftp/src/backend.rs +19 -4
  470. data/core/services/sftp/src/core.rs +51 -46
  471. data/core/services/sftp/src/lister.rs +4 -4
  472. data/core/services/sftp/src/writer.rs +1 -1
  473. data/core/services/sled/Cargo.toml +1 -1
  474. data/core/services/sled/src/backend.rs +6 -5
  475. data/core/services/sled/src/core.rs +28 -6
  476. data/core/services/sled/src/lister.rs +6 -5
  477. data/core/services/sled/src/reader.rs +4 -1
  478. data/core/services/sled/src/writer.rs +6 -2
  479. data/core/services/sqlite/Cargo.toml +2 -2
  480. data/core/services/sqlite/src/backend.rs +12 -7
  481. data/core/services/sqlite/src/core.rs +3 -3
  482. data/core/services/sqlite/src/reader.rs +4 -1
  483. data/core/services/sqlite/src/writer.rs +7 -3
  484. data/core/services/surrealdb/Cargo.toml +2 -2
  485. data/core/services/surrealdb/src/backend.rs +7 -6
  486. data/core/services/surrealdb/src/core.rs +1 -1
  487. data/core/services/surrealdb/src/reader.rs +4 -1
  488. data/core/services/surrealdb/src/writer.rs +6 -2
  489. data/core/services/swift/Cargo.toml +1 -1
  490. data/core/services/swift/src/backend.rs +38 -8
  491. data/core/services/swift/src/core.rs +63 -67
  492. data/core/services/swift/src/deleter.rs +8 -2
  493. data/core/services/swift/src/lister.rs +11 -8
  494. data/core/services/swift/src/reader.rs +5 -2
  495. data/core/services/swift/src/writer.rs +17 -8
  496. data/core/services/tikv/Cargo.toml +2 -2
  497. data/core/services/tikv/src/backend.rs +7 -6
  498. data/core/services/tikv/src/core.rs +31 -14
  499. data/core/services/tikv/src/reader.rs +4 -1
  500. data/core/services/tikv/src/writer.rs +6 -2
  501. data/core/services/tos/Cargo.toml +2 -2
  502. data/core/services/tos/src/backend.rs +45 -21
  503. data/core/services/tos/src/copier.rs +44 -17
  504. data/core/services/tos/src/core.rs +147 -117
  505. data/core/services/tos/src/deleter.rs +9 -3
  506. data/core/services/tos/src/docs.md +1 -1
  507. data/core/services/tos/src/lister.rs +43 -28
  508. data/core/services/tos/src/reader.rs +5 -2
  509. data/core/services/tos/src/writer.rs +37 -16
  510. data/core/services/upyun/Cargo.toml +1 -1
  511. data/core/services/upyun/src/backend.rs +30 -7
  512. data/core/services/upyun/src/core.rs +122 -87
  513. data/core/services/upyun/src/deleter.rs +4 -1
  514. data/core/services/upyun/src/lister.rs +10 -10
  515. data/core/services/upyun/src/reader.rs +5 -2
  516. data/core/services/upyun/src/writer.rs +19 -7
  517. data/core/services/vercel-artifacts/Cargo.toml +1 -1
  518. data/core/services/vercel-artifacts/src/backend.rs +6 -3
  519. data/core/services/vercel-artifacts/src/core.rs +32 -27
  520. data/core/services/vercel-artifacts/src/reader.rs +5 -2
  521. data/core/services/vercel-artifacts/src/writer.rs +6 -3
  522. data/core/services/vercel-blob/Cargo.toml +1 -1
  523. data/core/services/vercel-blob/src/backend.rs +23 -6
  524. data/core/services/vercel-blob/src/core.rs +92 -81
  525. data/core/services/vercel-blob/src/lister.rs +12 -3
  526. data/core/services/vercel-blob/src/reader.rs +5 -2
  527. data/core/services/vercel-blob/src/writer.rs +19 -7
  528. data/core/services/webdav/Cargo.toml +2 -2
  529. data/core/services/webdav/src/backend.rs +25 -5
  530. data/core/services/webdav/src/core.rs +116 -59
  531. data/core/services/webdav/src/deleter.rs +4 -1
  532. data/core/services/webdav/src/lister.rs +4 -1
  533. data/core/services/webdav/src/reader.rs +6 -2
  534. data/core/services/webdav/src/writer.rs +17 -7
  535. data/core/services/webhdfs/Cargo.toml +2 -2
  536. data/core/services/webhdfs/src/backend.rs +24 -11
  537. data/core/services/webhdfs/src/core.rs +99 -98
  538. data/core/services/webhdfs/src/deleter.rs +5 -2
  539. data/core/services/webhdfs/src/lister.rs +21 -9
  540. data/core/services/webhdfs/src/reader.rs +5 -2
  541. data/core/services/webhdfs/src/writer.rs +49 -14
  542. data/core/services/yandex-disk/Cargo.toml +1 -1
  543. data/core/services/yandex-disk/src/backend.rs +28 -6
  544. data/core/services/yandex-disk/src/core.rs +97 -79
  545. data/core/services/yandex-disk/src/deleter.rs +4 -1
  546. data/core/services/yandex-disk/src/lister.rs +25 -9
  547. data/core/services/yandex-disk/src/reader.rs +5 -2
  548. data/core/services/yandex-disk/src/writer.rs +6 -3
  549. data/core/src/lib.rs +5 -0
  550. data/core/testkit/Cargo.toml +4 -4
  551. data/core/testkit/src/utils.rs +53 -8
  552. data/core/tests/behavior/async_compose.rs +297 -0
  553. data/core/tests/behavior/async_copy.rs +162 -1
  554. data/core/tests/behavior/async_delete.rs +364 -3
  555. data/core/tests/behavior/async_read.rs +86 -0
  556. data/core/tests/behavior/async_restore.rs +162 -0
  557. data/core/tests/behavior/async_stat.rs +90 -0
  558. data/core/tests/behavior/async_write.rs +330 -2
  559. data/core/tests/behavior/main.rs +4 -0
  560. data/core/upgrade.md +114 -1
  561. data/src/capability.rs +0 -1
  562. data/src/io.rs +0 -1
  563. data/src/lister.rs +0 -1
  564. data/src/metadata.rs +0 -1
  565. data/src/operator_info.rs +0 -1
  566. metadata +44 -2
@@ -17,14 +17,39 @@
17
17
 
18
18
  //! Options module provides options definitions for operations.
19
19
 
20
+ use crate::Metadata;
20
21
  use crate::raw::Timestamp;
21
22
  use crate::types::BytesRange;
22
23
  use std::collections::HashMap;
23
24
 
24
25
  /// Options for delete operations.
26
+ ///
27
+ /// Each condition checks the file currently stored at the delete path, and
28
+ /// every condition must hold for the delete to proceed:
29
+ ///
30
+ /// - A false condition fails the delete with
31
+ /// [`crate::ErrorKind::ConditionNotMatch`].
32
+ /// - A condition the service does not advertise through its capability fails
33
+ /// the delete with [`crate::ErrorKind::Unsupported`]; OpenDAL never
34
+ /// silently drops a condition. A service that cannot preserve a
35
+ /// combination of conditions also returns `Unsupported`.
36
+ /// - A service-side conflict unrelated to these conditions surfaces as
37
+ /// [`crate::ErrorKind::Conflict`].
38
+ ///
39
+ /// Once every condition holds, deleting a missing file remains a successful
40
+ /// no-op.
41
+ ///
42
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
43
+ /// for the complete cross-operation contract.
25
44
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
26
45
  pub struct DeleteOptions {
27
- /// The version of the file to delete.
46
+ /// Delete the given version of the file instead of the current one.
47
+ ///
48
+ /// This selects which stored version the delete removes; it is not a
49
+ /// condition on the file.
50
+ ///
51
+ /// Check [`crate::Capability::delete_with_version`] before using this
52
+ /// option.
28
53
  pub version: Option<String>,
29
54
  /// Whether to delete the target recursively.
30
55
  ///
@@ -32,6 +57,67 @@ pub struct DeleteOptions {
32
57
  /// - If `true`, all entries under the path (or sharing the prefix for file-like paths)
33
58
  /// will be removed.
34
59
  pub recursive: bool,
60
+ /// Delete only when the file at the delete path has this exact ETag.
61
+ ///
62
+ /// The condition succeeds when the file exists and its ETag equals this
63
+ /// value. A file with a different ETag, or a missing file, fails the
64
+ /// delete with [`crate::ErrorKind::ConditionNotMatch`]. Only concrete
65
+ /// ETag values are portable; a wildcard such as `"*"` has no portable
66
+ /// meaning here.
67
+ ///
68
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
69
+ /// service does not advertise [`crate::Capability::delete_with_if_match`].
70
+ pub if_match: Option<String>,
71
+ /// Delete only when the file at the delete path does not have this ETag.
72
+ ///
73
+ /// With a concrete ETag value, the condition succeeds when the file has
74
+ /// a different ETag or does not exist; deleting a missing file is then a
75
+ /// successful no-op. A file whose ETag equals this value fails the
76
+ /// delete with [`crate::ErrorKind::ConditionNotMatch`]. Only concrete
77
+ /// ETag values are portable; a wildcard such as `"*"` has no portable
78
+ /// meaning here.
79
+ ///
80
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
81
+ /// service does not advertise
82
+ /// [`crate::Capability::delete_with_if_none_match`].
83
+ pub if_none_match: Option<String>,
84
+ /// Delete only when the file at the delete path has this exact version.
85
+ ///
86
+ /// The condition succeeds when the file exists and its version equals
87
+ /// this value. A file with a different version, or a missing file, fails
88
+ /// the delete with [`crate::ErrorKind::ConditionNotMatch`].
89
+ ///
90
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
91
+ /// service does not advertise
92
+ /// [`crate::Capability::delete_with_if_version_match`].
93
+ pub if_version_match: Option<String>,
94
+ /// Delete only when the file at the delete path does not have this
95
+ /// version.
96
+ ///
97
+ /// The condition succeeds when the file exists with a different version.
98
+ /// A file whose version equals this value fails the delete with
99
+ /// [`crate::ErrorKind::ConditionNotMatch`]. When no file exists at the
100
+ /// delete path, no portable behavior is defined.
101
+ ///
102
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
103
+ /// service does not advertise
104
+ /// [`crate::Capability::delete_with_if_version_not_match`].
105
+ pub if_version_not_match: Option<String>,
106
+ /// Delete only when the file at the delete path still has the identity
107
+ /// recorded in this metadata.
108
+ ///
109
+ /// Pass metadata previously returned by OpenDAL for the same path.
110
+ /// OpenDAL derives a version match when the service supports version
111
+ /// conditions and the metadata contains a version. Otherwise it derives
112
+ /// an ETag match when possible. A changed or missing file fails the delete
113
+ /// with [`crate::ErrorKind::ConditionNotMatch`], as does combining this
114
+ /// option with a conflicting `if_match` or `if_version_match` value.
115
+ ///
116
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
117
+ /// service does not support the derived primitive condition, and
118
+ /// [`crate::ErrorKind::ConfigInvalid`] when the metadata contains neither
119
+ /// a version nor an ETag.
120
+ pub if_not_changed: Option<Metadata>,
35
121
  }
36
122
 
37
123
  /// Options for list operations.
@@ -57,6 +143,18 @@ pub struct ListOptions {
57
143
  }
58
144
 
59
145
  /// Options for read operations.
146
+ ///
147
+ /// Each condition checks the file being read, and every condition must hold
148
+ /// for the read to proceed. A missing file fails the read with
149
+ /// [`crate::ErrorKind::NotFound`] no matter which conditions are set. An
150
+ /// existing file that fails a condition returns
151
+ /// [`crate::ErrorKind::ConditionNotMatch`], and a condition the service does
152
+ /// not advertise through its capability returns
153
+ /// [`crate::ErrorKind::Unsupported`]; OpenDAL never silently drops a
154
+ /// condition.
155
+ ///
156
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
157
+ /// for the complete cross-operation contract.
60
158
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
61
159
  pub struct ReadOptions {
62
160
  /// Set `range` for this operation.
@@ -70,40 +168,82 @@ pub struct ReadOptions {
70
168
  ///
71
169
  /// The type implements `From<RangeBounds<u64>>`, so users can use `(1024..).into()` instead.
72
170
  pub range: BytesRange,
73
- /// Set `version` for this operation.
171
+ /// Read the given version of the file instead of the current one.
74
172
  ///
75
- /// This option can be used to retrieve the data of a specified version of the given path.
173
+ /// This selects which stored version the read returns; it is not a
174
+ /// condition on the file. A version that does not exist returns
175
+ /// [`crate::ErrorKind::NotFound`].
76
176
  ///
77
- /// If the version doesn't exist, an error with kind [`crate::ErrorKind::NotFound`] will be returned.
177
+ /// Check [`crate::Capability::read_with_version`] before using this
178
+ /// option.
78
179
  pub version: Option<String>,
79
180
 
80
- /// Set `if_match` for this operation.
181
+ /// Read only when the file has this exact ETag.
81
182
  ///
82
- /// This option can be used to check if the file's `ETag` matches the given `ETag`.
183
+ /// The condition succeeds when the file exists and its ETag equals this
184
+ /// value. A file with a different ETag returns
185
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
186
+ /// [`crate::ErrorKind::NotFound`]. Only concrete ETag values are
187
+ /// portable; a wildcard such as `"*"` has no portable meaning here.
83
188
  ///
84
- /// If file exists and it's etag doesn't match, an error with kind [`crate::ErrorKind::ConditionNotMatch`]
85
- /// will be returned.
189
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
190
+ /// service does not advertise [`crate::Capability::read_with_if_match`].
86
191
  pub if_match: Option<String>,
87
- /// Set `if_none_match` for this operation.
192
+ /// Read only when the file does not have this ETag.
88
193
  ///
89
- /// This option can be used to check if the file's `ETag` doesn't match the given `ETag`.
194
+ /// With a concrete ETag value, the condition succeeds when the file
195
+ /// exists with a different ETag. A file whose ETag equals this value
196
+ /// returns [`crate::ErrorKind::ConditionNotMatch`]; a missing file
197
+ /// returns [`crate::ErrorKind::NotFound`]. Only concrete ETag values
198
+ /// are portable; a wildcard such as `"*"` has no portable meaning here.
90
199
  ///
91
- /// If file exists and it's etag match, an error with kind [`crate::ErrorKind::ConditionNotMatch`]
92
- /// will be returned.
200
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
201
+ /// service does not advertise
202
+ /// [`crate::Capability::read_with_if_none_match`].
93
203
  pub if_none_match: Option<String>,
94
- /// Set `if_modified_since` for this operation.
95
- ///
96
- /// This option can be used to check if the file has been modified since the given timestamp.
97
- ///
98
- /// If file exists and it hasn't been modified since the specified time, an error with kind
99
- /// [`crate::ErrorKind::ConditionNotMatch`] will be returned.
204
+ /// Read only when the file has this exact version.
205
+ ///
206
+ /// The condition succeeds when the file exists and its version equals
207
+ /// this value. A file with a different version returns
208
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
209
+ /// [`crate::ErrorKind::NotFound`].
210
+ ///
211
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
212
+ /// service does not advertise
213
+ /// [`crate::Capability::read_with_if_version_match`].
214
+ pub if_version_match: Option<String>,
215
+ /// Read only when the file does not have this version.
216
+ ///
217
+ /// The condition succeeds when the file exists with a different version.
218
+ /// A file whose version equals this value returns
219
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
220
+ /// [`crate::ErrorKind::NotFound`].
221
+ ///
222
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
223
+ /// service does not advertise
224
+ /// [`crate::Capability::read_with_if_version_not_match`].
225
+ pub if_version_not_match: Option<String>,
226
+ /// Read only when the file was modified after this timestamp.
227
+ ///
228
+ /// The condition succeeds when the file exists and was modified after
229
+ /// this time. A file not modified since this time returns
230
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
231
+ /// [`crate::ErrorKind::NotFound`].
232
+ ///
233
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
234
+ /// service does not advertise
235
+ /// [`crate::Capability::read_with_if_modified_since`].
100
236
  pub if_modified_since: Option<Timestamp>,
101
- /// Set `if_unmodified_since` for this operation.
237
+ /// Read only when the file was not modified after this timestamp.
102
238
  ///
103
- /// This feature can be used to check if the file hasn't been modified since the given timestamp.
239
+ /// The condition succeeds when the file exists and was not modified
240
+ /// after this time. A file modified after this time returns
241
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
242
+ /// [`crate::ErrorKind::NotFound`].
104
243
  ///
105
- /// If file exists and it has been modified since the specified time, an error with kind
106
- /// [`crate::ErrorKind::ConditionNotMatch`] will be returned.
244
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
245
+ /// service does not advertise
246
+ /// [`crate::Capability::read_with_if_unmodified_since`].
107
247
  pub if_unmodified_since: Option<Timestamp>,
108
248
 
109
249
  /// Known content length of the object.
@@ -134,11 +274,14 @@ pub struct ReadOptions {
134
274
  pub chunk: Option<usize>,
135
275
  /// Controls the optimization strategy for range reads in [`crate::Reader::fetch`].
136
276
  ///
137
- /// When performing range reads, if the gap between two requested ranges is smaller than
138
- /// the configured `gap` size, OpenDAL will merge these ranges into a single read request
277
+ /// When performing range reads, if the gap between two requested ranges is less than or
278
+ /// equal to the configured `gap` size, OpenDAL will merge these ranges into a single read request
139
279
  /// and discard the unrequested data in between. This helps reduce the number of API calls
140
280
  /// to remote storage services.
141
281
  ///
282
+ /// Set to `0` to disable merging ranges separated by a gap. Overlapping or adjacent ranges
283
+ /// are still merged.
284
+ ///
142
285
  /// This optimization is particularly useful when performing multiple small range reads
143
286
  /// that are close to each other, as it reduces the overhead of multiple network requests
144
287
  /// at the cost of transferring some additional data.
@@ -162,42 +305,97 @@ pub struct ReadOptions {
162
305
  }
163
306
 
164
307
  /// Options for reader operations.
308
+ ///
309
+ /// Each condition checks the file being read, and every condition must hold
310
+ /// for the reader to produce data. A missing file fails with
311
+ /// [`crate::ErrorKind::NotFound`] no matter which conditions are set. An
312
+ /// existing file that fails a condition returns
313
+ /// [`crate::ErrorKind::ConditionNotMatch`], and a condition the service does
314
+ /// not advertise through its capability returns
315
+ /// [`crate::ErrorKind::Unsupported`]; OpenDAL never silently drops a
316
+ /// condition. Depending on the service, a conditional error may surface when
317
+ /// creating the reader or while reading from it.
318
+ ///
319
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
320
+ /// for the complete cross-operation contract.
165
321
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
166
322
  pub struct ReaderOptions {
167
- /// Set `version` for this operation.
323
+ /// Read the given version of the file instead of the current one.
168
324
  ///
169
- /// This option can be used to retrieve the data of a specified version of the given path.
325
+ /// This selects which stored version the reader returns; it is not a
326
+ /// condition on the file. A version that does not exist returns
327
+ /// [`crate::ErrorKind::NotFound`].
170
328
  ///
171
- /// If the version doesn't exist, an error with kind [`crate::ErrorKind::NotFound`] will be returned.
329
+ /// Check [`crate::Capability::read_with_version`] before using this
330
+ /// option.
172
331
  pub version: Option<String>,
173
332
 
174
- /// Set `if_match` for this operation.
333
+ /// Read only when the file has this exact ETag.
175
334
  ///
176
- /// This option can be used to check if the file's `ETag` matches the given `ETag`.
335
+ /// The condition succeeds when the file exists and its ETag equals this
336
+ /// value. A file with a different ETag returns
337
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
338
+ /// [`crate::ErrorKind::NotFound`]. Only concrete ETag values are
339
+ /// portable; a wildcard such as `"*"` has no portable meaning here.
177
340
  ///
178
- /// If file exists and it's etag doesn't match, an error with kind [`crate::ErrorKind::ConditionNotMatch`]
179
- /// will be returned.
341
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
342
+ /// service does not advertise [`crate::Capability::read_with_if_match`].
180
343
  pub if_match: Option<String>,
181
- /// Set `if_none_match` for this operation.
344
+ /// Read only when the file does not have this ETag.
182
345
  ///
183
- /// This option can be used to check if the file's `ETag` doesn't match the given `ETag`.
346
+ /// With a concrete ETag value, the condition succeeds when the file
347
+ /// exists with a different ETag. A file whose ETag equals this value
348
+ /// returns [`crate::ErrorKind::ConditionNotMatch`]; a missing file
349
+ /// returns [`crate::ErrorKind::NotFound`]. Only concrete ETag values
350
+ /// are portable; a wildcard such as `"*"` has no portable meaning here.
184
351
  ///
185
- /// If file exists and it's etag match, an error with kind [`crate::ErrorKind::ConditionNotMatch`]
186
- /// will be returned.
352
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
353
+ /// service does not advertise
354
+ /// [`crate::Capability::read_with_if_none_match`].
187
355
  pub if_none_match: Option<String>,
188
- /// Set `if_modified_since` for this operation.
189
- ///
190
- /// This option can be used to check if the file has been modified since the given timestamp.
191
- ///
192
- /// If file exists and it hasn't been modified since the specified time, an error with kind
193
- /// [`crate::ErrorKind::ConditionNotMatch`] will be returned.
356
+ /// Read only when the file has this exact version.
357
+ ///
358
+ /// The condition succeeds when the file exists and its version equals
359
+ /// this value. A file with a different version returns
360
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
361
+ /// [`crate::ErrorKind::NotFound`].
362
+ ///
363
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
364
+ /// service does not advertise
365
+ /// [`crate::Capability::read_with_if_version_match`].
366
+ pub if_version_match: Option<String>,
367
+ /// Read only when the file does not have this version.
368
+ ///
369
+ /// The condition succeeds when the file exists with a different version.
370
+ /// A file whose version equals this value returns
371
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
372
+ /// [`crate::ErrorKind::NotFound`].
373
+ ///
374
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
375
+ /// service does not advertise
376
+ /// [`crate::Capability::read_with_if_version_not_match`].
377
+ pub if_version_not_match: Option<String>,
378
+ /// Read only when the file was modified after this timestamp.
379
+ ///
380
+ /// The condition succeeds when the file exists and was modified after
381
+ /// this time. A file not modified since this time returns
382
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
383
+ /// [`crate::ErrorKind::NotFound`].
384
+ ///
385
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
386
+ /// service does not advertise
387
+ /// [`crate::Capability::read_with_if_modified_since`].
194
388
  pub if_modified_since: Option<Timestamp>,
195
- /// Set `if_unmodified_since` for this operation.
389
+ /// Read only when the file was not modified after this timestamp.
196
390
  ///
197
- /// This feature can be used to check if the file hasn't been modified since the given timestamp.
391
+ /// The condition succeeds when the file exists and was not modified
392
+ /// after this time. A file modified after this time returns
393
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
394
+ /// [`crate::ErrorKind::NotFound`].
198
395
  ///
199
- /// If file exists and it has been modified since the specified time, an error with kind
200
- /// [`crate::ErrorKind::ConditionNotMatch`] will be returned.
396
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
397
+ /// service does not advertise
398
+ /// [`crate::Capability::read_with_if_unmodified_since`].
201
399
  pub if_unmodified_since: Option<Timestamp>,
202
400
 
203
401
  /// Known content length of the object.
@@ -228,11 +426,14 @@ pub struct ReaderOptions {
228
426
  pub chunk: Option<usize>,
229
427
  /// Controls the optimization strategy for range reads in [`crate::Reader::fetch`].
230
428
  ///
231
- /// When performing range reads, if the gap between two requested ranges is smaller than
232
- /// the configured `gap` size, OpenDAL will merge these ranges into a single read request
429
+ /// When performing range reads, if the gap between two requested ranges is less than or
430
+ /// equal to the configured `gap` size, OpenDAL will merge these ranges into a single read request
233
431
  /// and discard the unrequested data in between. This helps reduce the number of API calls
234
432
  /// to remote storage services.
235
433
  ///
434
+ /// Set to `0` to disable merging ranges separated by a gap. Overlapping or adjacent ranges
435
+ /// are still merged.
436
+ ///
236
437
  /// This optimization is particularly useful when performing multiple small range reads
237
438
  /// that are close to each other, as it reduces the overhead of multiple network requests
238
439
  /// at the cost of transferring some additional data.
@@ -257,42 +458,96 @@ pub struct ReaderOptions {
257
458
  }
258
459
 
259
460
  /// Options for stat operations.
461
+ ///
462
+ /// Each condition checks the file being observed, and every condition must
463
+ /// hold for the stat to return metadata. A missing file fails the stat with
464
+ /// [`crate::ErrorKind::NotFound`] no matter which conditions are set. An
465
+ /// existing file that fails a condition returns
466
+ /// [`crate::ErrorKind::ConditionNotMatch`], and a condition the service does
467
+ /// not advertise through its capability returns
468
+ /// [`crate::ErrorKind::Unsupported`]; OpenDAL never silently drops a
469
+ /// condition.
470
+ ///
471
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
472
+ /// for the complete cross-operation contract.
260
473
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
261
474
  pub struct StatOptions {
262
- /// Set `version` for this operation.
475
+ /// Stat the given version of the file instead of the current one.
263
476
  ///
264
- /// This options can be used to retrieve the data of a specified version of the given path.
477
+ /// This selects which stored version the stat describes; it is not a
478
+ /// condition on the file. A version that does not exist returns
479
+ /// [`crate::ErrorKind::NotFound`].
265
480
  ///
266
- /// If the version doesn't exist, an error with kind [`crate::ErrorKind::NotFound`] will be returned.
481
+ /// Check [`crate::Capability::stat_with_version`] before using this
482
+ /// option.
267
483
  pub version: Option<String>,
268
484
 
269
- /// Set `if_match` for this operation.
485
+ /// Stat only when the file has this exact ETag.
270
486
  ///
271
- /// This option can be used to check if the file's `ETag` matches the given `ETag`.
487
+ /// The condition succeeds when the file exists and its ETag equals this
488
+ /// value. A file with a different ETag returns
489
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
490
+ /// [`crate::ErrorKind::NotFound`]. Only concrete ETag values are
491
+ /// portable; a wildcard such as `"*"` has no portable meaning here.
272
492
  ///
273
- /// If file exists and it's etag doesn't match, an error with kind [`crate::ErrorKind::ConditionNotMatch`]
274
- /// will be returned.
493
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
494
+ /// service does not advertise [`crate::Capability::stat_with_if_match`].
275
495
  pub if_match: Option<String>,
276
- /// Set `if_none_match` for this operation.
496
+ /// Stat only when the file does not have this ETag.
277
497
  ///
278
- /// This option can be used to check if the file's `ETag` doesn't match the given `ETag`.
498
+ /// With a concrete ETag value, the condition succeeds when the file
499
+ /// exists with a different ETag. A file whose ETag equals this value
500
+ /// returns [`crate::ErrorKind::ConditionNotMatch`]; a missing file
501
+ /// returns [`crate::ErrorKind::NotFound`]. Only concrete ETag values
502
+ /// are portable; a wildcard such as `"*"` has no portable meaning here.
279
503
  ///
280
- /// If file exists and it's etag match, an error with kind [`crate::ErrorKind::ConditionNotMatch`]
281
- /// will be returned.
504
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
505
+ /// service does not advertise
506
+ /// [`crate::Capability::stat_with_if_none_match`].
282
507
  pub if_none_match: Option<String>,
283
- /// Set `if_modified_since` for this operation.
284
- ///
285
- /// This option can be used to check if the file has been modified since the given timestamp.
286
- ///
287
- /// If file exists and it hasn't been modified since the specified time, an error with kind
288
- /// [`crate::ErrorKind::ConditionNotMatch`] will be returned.
508
+ /// Stat only when the file has this exact version.
509
+ ///
510
+ /// The condition succeeds when the file exists and its version equals
511
+ /// this value. A file with a different version returns
512
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
513
+ /// [`crate::ErrorKind::NotFound`].
514
+ ///
515
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
516
+ /// service does not advertise
517
+ /// [`crate::Capability::stat_with_if_version_match`].
518
+ pub if_version_match: Option<String>,
519
+ /// Stat only when the file does not have this version.
520
+ ///
521
+ /// The condition succeeds when the file exists with a different version.
522
+ /// A file whose version equals this value returns
523
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
524
+ /// [`crate::ErrorKind::NotFound`].
525
+ ///
526
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
527
+ /// service does not advertise
528
+ /// [`crate::Capability::stat_with_if_version_not_match`].
529
+ pub if_version_not_match: Option<String>,
530
+ /// Stat only when the file was modified after this timestamp.
531
+ ///
532
+ /// The condition succeeds when the file exists and was modified after
533
+ /// this time. A file not modified since this time returns
534
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
535
+ /// [`crate::ErrorKind::NotFound`].
536
+ ///
537
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
538
+ /// service does not advertise
539
+ /// [`crate::Capability::stat_with_if_modified_since`].
289
540
  pub if_modified_since: Option<Timestamp>,
290
- /// Set `if_unmodified_since` for this operation.
541
+ /// Stat only when the file was not modified after this timestamp.
291
542
  ///
292
- /// This feature can be used to check if the file hasn't been modified since the given timestamp.
543
+ /// The condition succeeds when the file exists and was not modified
544
+ /// after this time. A file modified after this time returns
545
+ /// [`crate::ErrorKind::ConditionNotMatch`]; a missing file returns
546
+ /// [`crate::ErrorKind::NotFound`].
293
547
  ///
294
- /// If file exists and it has been modified since the specified time, an error with kind
295
- /// [`crate::ErrorKind::ConditionNotMatch`] will be returned.
548
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
549
+ /// service does not advertise
550
+ /// [`crate::Capability::stat_with_if_unmodified_since`].
296
551
  pub if_unmodified_since: Option<Timestamp>,
297
552
 
298
553
  /// Specify the content-type header that should be sent back by the operation.
@@ -310,6 +565,23 @@ pub struct StatOptions {
310
565
  }
311
566
 
312
567
  /// Options for write operations.
568
+ ///
569
+ /// Each condition checks the file currently stored at the write path, and
570
+ /// the service evaluates it atomically with the write's visible commit:
571
+ ///
572
+ /// - A false condition fails the write with
573
+ /// [`crate::ErrorKind::ConditionNotMatch`] and leaves the previously
574
+ /// visible file unchanged. Depending on the service, the error may surface
575
+ /// when the write starts, while writing, or when closing the writer.
576
+ /// - A condition the service does not advertise through its capability fails
577
+ /// the write with [`crate::ErrorKind::Unsupported`]; OpenDAL never
578
+ /// silently drops a condition. A service that cannot preserve a
579
+ /// combination of conditions also returns `Unsupported`.
580
+ /// - A service-side conflict unrelated to these conditions surfaces as
581
+ /// [`crate::ErrorKind::Conflict`].
582
+ ///
583
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
584
+ /// for the complete cross-operation contract.
313
585
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
314
586
  pub struct WriteOptions {
315
587
  /// Sets append mode for this operation.
@@ -428,60 +700,80 @@ pub struct WriteOptions {
428
700
  /// This metadata can be retrieved later when reading the object.
429
701
  pub user_metadata: Option<HashMap<String, String>>,
430
702
 
431
- /// Sets If-Match header for this write request.
703
+ /// Write only when the file at the write path has this exact ETag.
432
704
  ///
433
- /// ### Capability
434
- ///
435
- /// Check [`crate::Capability::write_with_if_match`] before using this feature.
436
- ///
437
- /// ### Behavior
438
- ///
439
- /// - If supported, the write operation will only succeed if the target's ETag matches the specified value
440
- /// - The value should be a valid ETag string
441
- /// - Common values include:
442
- /// - A specific ETag value like `"686897696a7c876b7e"`
443
- /// - `*` - Matches any existing resource
444
- /// - If not supported, the value will be ignored
705
+ /// The condition succeeds when the file exists and its ETag equals this
706
+ /// value. A file with a different ETag, or a missing file, fails the
707
+ /// write with [`crate::ErrorKind::ConditionNotMatch`]. Only concrete
708
+ /// ETag values are portable; a wildcard such as `"*"` has no portable
709
+ /// meaning here.
445
710
  ///
446
- /// This operation provides conditional write functionality based on ETag matching,
447
- /// helping prevent unintended overwrites in concurrent scenarios.
711
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
712
+ /// service does not advertise [`crate::Capability::write_with_if_match`].
448
713
  pub if_match: Option<String>,
449
- /// Sets If-None-Match header for this write request.
450
- ///
451
- /// Note: Certain services, like `s3`, support `if_not_exists` but not `if_none_match`.
452
- /// Use `if_not_exists` if you only want to check whether a file exists.
453
- ///
454
- /// ### Capability
455
- ///
456
- /// Check [`crate::Capability::write_with_if_none_match`] before using this feature.
457
- ///
458
- /// ### Behavior
459
- ///
460
- /// - If supported, the write operation will only succeed if the target's ETag does not match the specified value
461
- /// - The value should be a valid ETag string
462
- /// - Common values include:
463
- /// - A specific ETag value like `"686897696a7c876b7e"`
464
- /// - `*` - Matches if the resource does not exist
465
- /// - If not supported, the value will be ignored
466
- ///
467
- /// This operation provides conditional write functionality based on ETag non-matching,
468
- /// useful for preventing overwriting existing resources or ensuring unique writes.
714
+ /// Write only when the file at the write path does not have this ETag.
715
+ ///
716
+ /// With a concrete ETag value, the condition succeeds when the file has
717
+ /// a different ETag or does not exist; the write then replaces or
718
+ /// creates the file. A file whose ETag equals this value fails the write
719
+ /// with [`crate::ErrorKind::ConditionNotMatch`]. Only concrete ETag
720
+ /// values are portable; a wildcard such as `"*"` has no portable meaning
721
+ /// here.
722
+ ///
723
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
724
+ /// service does not advertise
725
+ /// [`crate::Capability::write_with_if_none_match`]. Some services, such
726
+ /// as `s3`, support `if_not_exists` but not `if_none_match`; use
727
+ /// [`WriteOptions::if_not_exists`] when you only need to guard against
728
+ /// an existing file.
469
729
  pub if_none_match: Option<String>,
470
- /// Sets the condition that write operation will succeed only if target does not exist.
471
- ///
472
- /// ### Capability
473
- ///
474
- /// Check [`crate::Capability::write_with_if_not_exists`] before using this feature.
475
- ///
476
- /// ### Behavior
477
- ///
478
- /// - If supported, the write operation will only succeed if the target path does not exist
479
- /// - Will return error if target already exists
480
- /// - If not supported, the value will be ignored
481
- ///
482
- /// This operation provides a way to ensure write operations only create new resources
483
- /// without overwriting existing ones, useful for implementing "create if not exists" logic.
730
+ /// Write only when the file at the write path has this exact version.
731
+ ///
732
+ /// The condition succeeds when the file exists and its version equals
733
+ /// this value. A file with a different version, or a missing file, fails
734
+ /// the write with [`crate::ErrorKind::ConditionNotMatch`].
735
+ ///
736
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
737
+ /// service does not advertise
738
+ /// [`crate::Capability::write_with_if_version_match`].
739
+ pub if_version_match: Option<String>,
740
+ /// Write only when the file at the write path does not have this
741
+ /// version.
742
+ ///
743
+ /// The condition succeeds when the file exists with a different version.
744
+ /// A file whose version equals this value fails the write with
745
+ /// [`crate::ErrorKind::ConditionNotMatch`]. When no file exists at the
746
+ /// write path, no portable behavior is defined.
747
+ ///
748
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
749
+ /// service does not advertise
750
+ /// [`crate::Capability::write_with_if_version_not_match`].
751
+ pub if_version_not_match: Option<String>,
752
+ /// Write only when no file exists at the write path.
753
+ ///
754
+ /// The condition succeeds when the path is empty, so the write creates
755
+ /// the file. An existing file fails the write with
756
+ /// [`crate::ErrorKind::ConditionNotMatch`].
757
+ ///
758
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
759
+ /// service does not advertise
760
+ /// [`crate::Capability::write_with_if_not_exists`].
484
761
  pub if_not_exists: bool,
762
+ /// Write only when the file at the write path still has the identity
763
+ /// recorded in this metadata.
764
+ ///
765
+ /// Pass metadata previously returned by OpenDAL for the same path.
766
+ /// OpenDAL derives a version match when the service supports version
767
+ /// conditions and the metadata contains a version. Otherwise it derives
768
+ /// an ETag match when possible. A changed or missing file fails the write
769
+ /// with [`crate::ErrorKind::ConditionNotMatch`], as does combining this
770
+ /// option with a conflicting `if_match` or `if_version_match` value.
771
+ ///
772
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
773
+ /// service does not support the derived primitive condition, and
774
+ /// [`crate::ErrorKind::ConfigInvalid`] when the metadata contains neither
775
+ /// a version nor an ETag.
776
+ pub if_not_changed: Option<Metadata>,
485
777
 
486
778
  /// Sets concurrent write operations for this writer.
487
779
  ///
@@ -536,56 +828,198 @@ pub struct WriteOptions {
536
828
  pub chunk: Option<usize>,
537
829
  }
538
830
 
539
- /// Options for copy operations.
831
+ /// Options for one complete source object in a composition.
832
+ ///
833
+ /// These options select or constrain the source object. They do not apply to
834
+ /// the destination object.
540
835
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
541
- pub struct CopyOptions {
542
- /// Sets the condition that copy operation will succeed only if target does not exist.
543
- ///
544
- /// ### Capability
836
+ pub struct ComposeSourceOptions {
837
+ /// Compose this version of the source object.
545
838
  ///
546
- /// Check [`crate::Capability::copy_with_if_not_exists`] before using this feature.
839
+ /// This selects which stored version the composition reads; it is not a
840
+ /// condition on the destination object.
547
841
  ///
548
- /// ### Behavior
549
- ///
550
- /// - If supported, the copy operation will only succeed if the target path does not exist
551
- /// - Will return error if target already exists
552
- /// - If not supported, the value will be ignored
842
+ /// Check [`crate::Capability::compose_with_source_version`] before using
843
+ /// this option.
844
+ pub version: Option<String>,
845
+ /// Compose only when the selected source has this exact ETag.
553
846
  ///
554
- /// This operation provides a way to ensure copy operations only create new resources
555
- /// without overwriting existing ones, useful for implementing "copy if not exists" logic.
847
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
848
+ /// service does not advertise
849
+ /// [`crate::Capability::compose_with_source_if_match`].
850
+ pub if_match: Option<String>,
851
+ /// Compose only when the selected source retains this metadata identity.
852
+ ///
853
+ /// OpenDAL selects the metadata version when the service supports source
854
+ /// versions. Otherwise it requires the ETag when possible. The operation
855
+ /// returns [`crate::ErrorKind::Unsupported`] when the service does not
856
+ /// support the derived source option, and
857
+ /// [`crate::ErrorKind::ConfigInvalid`] when the metadata contains neither
858
+ /// identity.
859
+ pub if_not_changed: Option<Metadata>,
860
+ }
861
+
862
+ /// Options for composing complete source objects into one destination object.
863
+ ///
864
+ /// Metadata fields apply only to the destination. Conditions check the
865
+ /// destination object and follow the matching [`WriteOptions`] contracts.
866
+ #[derive(Debug, Clone, Default, Eq, PartialEq)]
867
+ pub struct ComposeOptions {
868
+ /// Sets Cache-Control metadata on the destination object.
869
+ pub cache_control: Option<String>,
870
+ /// Sets Content-Type metadata on the destination object.
871
+ pub content_type: Option<String>,
872
+ /// Sets Content-Disposition metadata on the destination object.
873
+ pub content_disposition: Option<String>,
874
+ /// Sets Content-Encoding metadata on the destination object.
875
+ pub content_encoding: Option<String>,
876
+ /// Sets user metadata on the destination object.
877
+ pub user_metadata: Option<HashMap<String, String>>,
878
+ /// Compose only when the destination has this exact ETag.
879
+ pub if_match: Option<String>,
880
+ /// Compose only when the destination does not have this ETag.
881
+ pub if_none_match: Option<String>,
882
+ /// Compose only when the destination has this exact version.
883
+ pub if_version_match: Option<String>,
884
+ /// Compose only when the destination does not have this version.
885
+ pub if_version_not_match: Option<String>,
886
+ /// Compose only when no destination object exists.
556
887
  pub if_not_exists: bool,
888
+ /// Compose only when the destination still has this metadata identity.
889
+ ///
890
+ /// OpenDAL derives a version match when the service supports version
891
+ /// conditions and the metadata contains a version. Otherwise it derives
892
+ /// an ETag match when possible. The operation returns
893
+ /// [`crate::ErrorKind::Unsupported`] when the service does not support the
894
+ /// derived primitive condition, and [`crate::ErrorKind::ConfigInvalid`]
895
+ /// when the metadata contains neither a version nor an ETag.
896
+ pub if_not_changed: Option<Metadata>,
897
+ /// Maximum number of independent backend composition tasks.
898
+ ///
899
+ /// The default value is `1`. Services that use one atomic request may
900
+ /// ignore values greater than `1`.
901
+ pub concurrent: usize,
902
+ }
557
903
 
558
- /// Sets the condition that copy operation will succeed only if the destination
559
- /// currently has the given ETag.
904
+ /// Options for copy operations.
905
+ ///
906
+ /// Each condition checks the destination file, never the source, and every
907
+ /// condition must hold for the copy to proceed:
908
+ ///
909
+ /// - A false condition fails the copy with
910
+ /// [`crate::ErrorKind::ConditionNotMatch`].
911
+ /// - A condition the service does not advertise through its capability fails
912
+ /// the copy with [`crate::ErrorKind::Unsupported`]; OpenDAL never silently
913
+ /// drops a condition.
914
+ /// - A missing source fails the copy with [`crate::ErrorKind::NotFound`];
915
+ /// when a condition error applies at the same time, which error the copy
916
+ /// returns is unspecified.
917
+ /// - A service-side conflict unrelated to these conditions surfaces as
918
+ /// [`crate::ErrorKind::Conflict`].
919
+ ///
920
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
921
+ /// for the complete cross-operation contract.
922
+ #[derive(Debug, Clone, Default, Eq, PartialEq)]
923
+ pub struct CopyOptions {
924
+ /// Copy only when no file exists at the destination path.
560
925
  ///
561
- /// ### Capability
926
+ /// The condition succeeds when the destination path is empty, so the
927
+ /// copy creates the destination file. An existing destination file fails
928
+ /// the copy with [`crate::ErrorKind::ConditionNotMatch`].
562
929
  ///
563
- /// Check [`crate::Capability::copy_with_if_match`] before using this feature.
930
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
931
+ /// service does not advertise
932
+ /// [`crate::Capability::copy_with_if_not_exists`].
933
+ pub if_not_exists: bool,
934
+
935
+ /// Copy only when the destination file has this exact ETag.
564
936
  ///
565
- /// ### Behavior
937
+ /// The condition succeeds when the destination file exists and its ETag
938
+ /// equals this value. A destination file with a different ETag, or a
939
+ /// missing destination file, fails the copy with
940
+ /// [`crate::ErrorKind::ConditionNotMatch`]. Only concrete ETag values
941
+ /// are portable; a wildcard such as `"*"` has no portable meaning here.
566
942
  ///
567
- /// - If supported, the copy operation will only succeed when the existing
568
- /// destination object's ETag matches the given value.
943
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
944
+ /// service does not advertise [`crate::Capability::copy_with_if_match`].
569
945
  pub if_match: Option<String>,
946
+ /// Copy only when the destination file does not have this ETag.
947
+ ///
948
+ /// With a concrete ETag value, the condition succeeds when the
949
+ /// destination file has a different ETag or does not exist; the copy
950
+ /// then replaces or creates the destination file. A destination file
951
+ /// whose ETag equals this value fails the copy with
952
+ /// [`crate::ErrorKind::ConditionNotMatch`]. Only concrete ETag values
953
+ /// are portable; a wildcard such as `"*"` has no portable meaning here.
954
+ ///
955
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
956
+ /// service does not advertise
957
+ /// [`crate::Capability::copy_with_if_none_match`].
958
+ pub if_none_match: Option<String>,
959
+ /// Copy only when the destination file has this exact version.
960
+ ///
961
+ /// The condition succeeds when the destination file exists and its
962
+ /// version equals this value. A destination file with a different
963
+ /// version, or a missing destination file, fails the copy with
964
+ /// [`crate::ErrorKind::ConditionNotMatch`].
965
+ ///
966
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
967
+ /// service does not advertise
968
+ /// [`crate::Capability::copy_with_if_version_match`].
969
+ pub if_version_match: Option<String>,
970
+ /// Copy only when the destination file does not have this version.
971
+ ///
972
+ /// The condition succeeds when the destination file exists with a
973
+ /// different version. A destination file whose version equals this value
974
+ /// fails the copy with [`crate::ErrorKind::ConditionNotMatch`]. When no
975
+ /// destination file exists, no portable behavior is defined.
976
+ ///
977
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
978
+ /// service does not advertise
979
+ /// [`crate::Capability::copy_with_if_version_not_match`].
980
+ pub if_version_not_match: Option<String>,
981
+ /// Copy only when the destination file still has the identity recorded
982
+ /// in this metadata.
983
+ ///
984
+ /// Pass metadata previously returned by OpenDAL for the destination
985
+ /// path. OpenDAL derives a version match when the service supports version
986
+ /// conditions and the metadata contains a version. Otherwise it derives
987
+ /// an ETag match when possible. A changed or missing destination file
988
+ /// fails the copy with [`crate::ErrorKind::ConditionNotMatch`], as does
989
+ /// combining this option with a conflicting `if_match` or
990
+ /// `if_version_match` value.
991
+ ///
992
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
993
+ /// service does not support the derived primitive condition, and
994
+ /// [`crate::ErrorKind::ConfigInvalid`] when the metadata contains neither
995
+ /// a version nor an ETag.
996
+ pub if_not_changed: Option<Metadata>,
570
997
 
571
- /// Copy from a specific source object version.
998
+ /// Copy from a specific source file version.
572
999
  ///
573
- /// ### Capability
574
- ///
575
- /// Check [`crate::Capability::copy_with_source_version`] before using this feature.
576
- ///
577
- /// ### Behavior
1000
+ /// This selects which stored version of the source the copy reads; it is
1001
+ /// not a condition on the destination file. Destination behavior follows
1002
+ /// normal copy semantics.
578
1003
  ///
579
- /// - If supported, the copy operation will read from the specified source
580
- /// version instead of the current source object.
581
- /// - Destination behavior follows normal copy semantics.
1004
+ /// Check [`crate::Capability::copy_with_source_version`] before using
1005
+ /// this option.
582
1006
  pub source_version: Option<String>,
583
1007
 
584
- /// Known content length of the source object.
1008
+ /// Asserted complete content length of the source object.
585
1009
  ///
586
- /// This is an execution hint that allows OpenDAL to avoid extra metadata
587
- /// requests while planning copy operations. It must not be used as an object
588
- /// identity or consistency condition.
1010
+ /// OpenDAL may trust this value without reading source metadata. It can use
1011
+ /// the value to plan copied ranges and to construct the returned metadata.
1012
+ /// An incorrect value can therefore cause incomplete copy planning, failed
1013
+ /// requests, or incorrect result metadata.
1014
+ ///
1015
+ /// A service can ignore this value when its copy operation already reports
1016
+ /// an authoritative copied size.
1017
+ ///
1018
+ /// This option does not pin the source object or protect the copy from a
1019
+ /// concurrent source change. Set it only when the caller can guarantee that
1020
+ /// the value describes the object that the service will copy, for example by
1021
+ /// selecting an immutable [`Self::source_version`]. Otherwise omit it if the
1022
+ /// source can change.
589
1023
  pub source_content_length_hint: Option<u64>,
590
1024
 
591
1025
  /// Sets concurrent copy operations for this copier.
@@ -609,19 +1043,58 @@ pub struct CopyOptions {
609
1043
  }
610
1044
 
611
1045
  /// Options for rename operations.
1046
+ ///
1047
+ /// The condition checks the destination file, never the source. A missing
1048
+ /// source fails the rename with [`crate::ErrorKind::NotFound`]; when a
1049
+ /// condition error applies at the same time, which error the rename returns
1050
+ /// is unspecified.
1051
+ ///
1052
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
1053
+ /// for the complete cross-operation contract.
612
1054
  #[derive(Debug, Clone, Default, Eq, PartialEq)]
613
1055
  pub struct RenameOptions {
614
- /// Sets the condition that rename operation will succeed only if target does not exist.
1056
+ /// Rename only when no file exists at the destination path.
615
1057
  ///
616
- /// ### Capability
1058
+ /// The condition succeeds when the destination path is empty. An
1059
+ /// existing destination file fails the rename with
1060
+ /// [`crate::ErrorKind::ConditionNotMatch`].
617
1061
  ///
618
- /// Check [`crate::Capability::rename_with_if_not_exists`] before using this feature.
1062
+ /// The operation returns [`crate::ErrorKind::Unsupported`] when the
1063
+ /// service does not advertise
1064
+ /// [`crate::Capability::rename_with_if_not_exists`].
1065
+ pub if_not_exists: bool,
1066
+ }
1067
+
1068
+ /// Options for restore operations.
1069
+ ///
1070
+ /// The condition checks the file currently stored at the restore path. The
1071
+ /// selected version remains the source of the restore, and the restore may
1072
+ /// still fail because that version does not exist.
1073
+ ///
1074
+ /// See the [conditional operation specification][crate::docs::specs::conditional_operations]
1075
+ /// for the complete cross-operation contract.
1076
+ #[derive(Debug, Clone, Default, Eq, PartialEq)]
1077
+ pub struct RestoreOptions {
1078
+ /// Restore this historical version as the current version.
619
1079
  ///
620
- /// ### Behavior
1080
+ /// This selects which stored version the restore promotes; it is not a
1081
+ /// condition on the file at the restore path.
621
1082
  ///
622
- /// - If the target does not exist, the rename operation succeeds.
623
- /// - If the target exists, the operation returns [`crate::ErrorKind::ConditionNotMatch`].
624
- /// - If the service does not support this condition, the operation returns
625
- /// [`crate::ErrorKind::Unsupported`].
1083
+ /// Check [`crate::Capability::restore_with_version`] before using this
1084
+ /// option.
1085
+ pub version: Option<String>,
1086
+
1087
+ /// Restore the selected version only when no file currently exists at
1088
+ /// the restore path.
1089
+ ///
1090
+ /// The condition succeeds when the restore path is empty. An existing
1091
+ /// file fails the restore with [`crate::ErrorKind::ConditionNotMatch`],
1092
+ /// which protects recovery workflows from overwriting a file recreated
1093
+ /// after the version to restore was selected.
1094
+ ///
1095
+ /// This option requires [`RestoreOptions::version`]; setting it without
1096
+ /// a version returns [`crate::ErrorKind::ConfigInvalid`]. The operation
1097
+ /// returns [`crate::ErrorKind::Unsupported`] when the service does not
1098
+ /// advertise [`crate::Capability::restore_with_if_not_exists`].
626
1099
  pub if_not_exists: bool,
627
1100
  }