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.
- checksums.yaml +4 -4
- data/Cargo.lock +89 -56
- data/Cargo.toml +1 -1
- data/DEPENDENCIES.rust.tsv +55 -41
- data/LICENSE +201 -0
- data/LICENSE-MPL-2.0.txt +373 -0
- data/NOTICE +5 -0
- data/core/CHANGELOG.md +175 -0
- data/core/Cargo.lock +225 -298
- data/core/Cargo.toml +100 -94
- data/core/DEPENDENCIES.rust.tsv +44 -73
- data/core/benches/metadata/README.md +21 -0
- data/core/benches/metadata/main.rs +541 -0
- data/core/benches/vs_fs/Cargo.toml +1 -1
- data/core/benches/vs_s3/Cargo.toml +1 -1
- data/core/core/Cargo.toml +7 -2
- data/core/core/src/blocking/delete.rs +5 -1
- data/core/core/src/blocking/operator.rs +12 -0
- data/core/core/src/blocking/read/std_reader.rs +25 -0
- data/core/core/src/docs/concepts.rs +70 -94
- data/core/core/src/docs/internals/accessor.rs +62 -293
- data/core/core/src/docs/internals/layer.rs +43 -59
- data/core/core/src/docs/internals/mod.rs +21 -23
- data/core/core/src/docs/mod.rs +10 -6
- data/core/core/src/docs/performance/concurrent_write.md +92 -55
- data/core/core/src/docs/performance/http_optimization.md +120 -104
- data/core/core/src/docs/performance/mod.rs +8 -6
- data/core/core/src/docs/rfcs/5485_conditional_reader.md +4 -0
- data/core/core/src/docs/rfcs/7182_restore_api.md +139 -557
- data/core/core/src/docs/rfcs/7945_limited_read.md +210 -0
- data/core/core/src/docs/rfcs/7948_s3_provider_presets.md +254 -0
- data/core/core/src/docs/rfcs/8109_writer_copy_from.md +330 -0
- data/core/core/src/docs/rfcs/8145_conflict_error_kind.md +210 -0
- data/core/core/src/docs/rfcs/8147_write_if_not_changed.md +233 -0
- data/core/core/src/docs/rfcs/8188_compose_api.md +292 -0
- data/core/core/src/docs/rfcs/8194_compact_metadata_and_operation_args.md +444 -0
- data/core/core/src/docs/rfcs/README.md +14 -3
- data/core/core/src/docs/rfcs/mod.rs +46 -22
- data/core/core/src/docs/specs/README.md +34 -0
- data/core/core/src/docs/specs/conditional-operations.md +156 -0
- data/core/core/src/docs/specs/metadata.md +63 -0
- data/core/core/src/docs/specs/mod.rs +26 -0
- data/core/core/src/docs/upgrade.md +114 -1
- data/core/core/src/layers/capability_override.rs +15 -2
- data/core/core/src/layers/complete.rs +347 -43
- data/core/core/src/layers/correctness_check.rs +718 -51
- data/core/core/src/layers/error_context.rs +76 -2
- data/core/core/src/layers/simulate.rs +91 -28
- data/core/core/src/lib.rs +1 -0
- data/core/core/src/raw/accessor.rs +91 -15
- data/core/core/src/raw/enum_utils.rs +7 -0
- data/core/core/src/raw/http_util/header.rs +22 -17
- data/core/core/src/raw/oio/compose/api.rs +92 -0
- data/core/core/src/raw/oio/compose/mod.rs +19 -0
- data/core/core/src/raw/oio/copy/api.rs +3 -3
- data/core/core/src/raw/oio/copy/block_copy.rs +32 -4
- data/core/core/src/raw/oio/copy/multipart_copy.rs +36 -7
- data/core/core/src/raw/oio/entry.rs +48 -22
- data/core/core/src/raw/oio/list/flat_list.rs +1 -1
- data/core/core/src/raw/oio/list/hierarchy_list.rs +3 -2
- data/core/core/src/raw/oio/mod.rs +3 -0
- data/core/core/src/raw/oio/read/position_read.rs +1 -1
- data/core/core/src/raw/oio/write/api.rs +40 -0
- data/core/core/src/raw/oio/write/append_write.rs +4 -4
- data/core/core/src/raw/oio/write/block_write.rs +2 -2
- data/core/core/src/raw/oio/write/multipart_write.rs +181 -48
- data/core/core/src/raw/oio/write/position_write.rs +1 -1
- data/core/core/src/raw/operation.rs +6 -0
- data/core/core/src/raw/ops.rs +1191 -456
- data/core/core/src/raw/rps.rs +11 -0
- data/core/core/src/raw/time.rs +14 -3
- data/core/core/src/services/memory/backend.rs +5 -10
- data/core/core/src/services/memory/lister.rs +4 -4
- data/core/core/src/services/memory/writer.rs +7 -6
- data/core/core/src/types/buffer.rs +102 -12
- data/core/core/src/types/bytes_range.rs +20 -1
- data/core/core/src/types/capability.rs +65 -0
- data/core/core/src/types/compact.rs +329 -0
- data/core/core/src/types/compose/composer.rs +183 -0
- data/core/core/src/types/compose/input.rs +57 -0
- data/core/core/src/types/compose/mod.rs +23 -0
- data/core/core/src/types/context/read.rs +16 -11
- data/core/core/src/types/context/write.rs +150 -2
- data/core/core/src/types/copy.rs +5 -3
- data/core/core/src/types/delete/deleter.rs +20 -12
- data/core/core/src/types/delete/input.rs +22 -64
- data/core/core/src/types/delete/mod.rs +0 -1
- data/core/core/src/types/entry.rs +8 -14
- data/core/core/src/types/error.rs +28 -11
- data/core/core/src/types/metadata.rs +709 -322
- data/core/core/src/types/mod.rs +9 -1
- data/core/core/src/types/operator/operator.rs +278 -29
- data/core/core/src/types/operator/operator_futures.rs +466 -105
- data/core/core/src/types/options.rs +631 -158
- data/core/core/src/types/read/futures_async_reader.rs +663 -50
- data/core/core/src/types/read/reader.rs +23 -5
- data/core/core/src/types/write/futures_async_writer.rs +27 -0
- data/core/core/src/types/write/writer.rs +47 -5
- data/core/http-transports/reqwest/Cargo.toml +1 -1
- data/core/layers/async-backtrace/Cargo.toml +2 -2
- data/core/layers/async-backtrace/src/lib.rs +21 -2
- data/core/layers/await-tree/Cargo.toml +2 -2
- data/core/layers/await-tree/src/lib.rs +25 -2
- data/core/layers/capability-check/Cargo.toml +2 -2
- data/core/layers/capability-check/src/lib.rs +98 -10
- data/core/layers/chaos/Cargo.toml +2 -2
- data/core/layers/chaos/src/lib.rs +18 -3
- data/core/layers/concurrent-limit/Cargo.toml +3 -3
- data/core/layers/concurrent-limit/src/lib.rs +53 -13
- data/core/layers/dtrace/Cargo.toml +2 -2
- data/core/layers/dtrace/src/lib.rs +29 -2
- data/core/layers/fastmetrics/Cargo.toml +3 -3
- data/core/layers/fastrace/Cargo.toml +2 -2
- data/core/layers/fastrace/src/lib.rs +28 -2
- data/core/layers/foyer/Cargo.toml +2 -2
- data/core/layers/foyer/src/full.rs +16 -19
- data/core/layers/foyer/src/lib.rs +67 -14
- data/core/layers/hotpath/Cargo.toml +2 -2
- data/core/layers/hotpath/src/lib.rs +20 -2
- data/core/layers/immutable-index/Cargo.toml +2 -2
- data/core/layers/immutable-index/src/lib.rs +48 -24
- data/core/layers/logging/Cargo.toml +2 -2
- data/core/layers/logging/src/lib.rs +46 -2
- data/core/layers/metrics/Cargo.toml +3 -3
- data/core/layers/mime-guess/Cargo.toml +2 -2
- data/core/layers/mime-guess/src/lib.rs +31 -4
- data/core/layers/observe-metrics-common/Cargo.toml +2 -2
- data/core/layers/observe-metrics-common/src/lib.rs +55 -2
- data/core/layers/otelmetrics/Cargo.toml +3 -3
- data/core/layers/oteltrace/Cargo.toml +2 -2
- data/core/layers/oteltrace/src/lib.rs +27 -2
- data/core/layers/prometheus/Cargo.toml +3 -3
- data/core/layers/prometheus-client/Cargo.toml +3 -3
- data/core/layers/retry/Cargo.toml +4 -4
- data/core/layers/retry/src/lib.rs +76 -19
- data/core/layers/route/Cargo.toml +3 -3
- data/core/layers/route/src/lib.rs +34 -7
- data/core/layers/tail-cut/Cargo.toml +2 -2
- data/core/layers/tail-cut/src/lib.rs +28 -2
- data/core/layers/throttle/Cargo.toml +2 -2
- data/core/layers/throttle/src/lib.rs +19 -2
- data/core/layers/timeout/Cargo.toml +3 -3
- data/core/layers/timeout/src/lib.rs +38 -13
- data/core/layers/tracing/Cargo.toml +2 -2
- data/core/layers/tracing/src/lib.rs +24 -3
- data/core/services/aliyun-drive/Cargo.toml +2 -2
- data/core/services/aliyun-drive/src/backend.rs +34 -24
- data/core/services/aliyun-drive/src/core.rs +143 -54
- data/core/services/aliyun-drive/src/lister.rs +19 -18
- data/core/services/aliyun-drive/src/reader.rs +4 -1
- data/core/services/aliyun-drive/src/writer.rs +3 -3
- data/core/services/alluxio/Cargo.toml +1 -1
- data/core/services/alluxio/src/backend.rs +1 -1
- data/core/services/alluxio/src/core.rs +113 -94
- data/core/services/alluxio/src/reader.rs +7 -3
- data/core/services/alluxio/src/writer.rs +2 -2
- data/core/services/azblob/Cargo.toml +2 -2
- data/core/services/azblob/src/backend.rs +17 -9
- data/core/services/azblob/src/copier.rs +41 -15
- data/core/services/azblob/src/core.rs +372 -135
- data/core/services/azblob/src/deleter.rs +41 -18
- data/core/services/azblob/src/lister.rs +16 -10
- data/core/services/azblob/src/reader.rs +4 -1
- data/core/services/azblob/src/writer.rs +48 -15
- data/core/services/azdls/Cargo.toml +3 -3
- data/core/services/azdls/src/backend.rs +45 -15
- data/core/services/azdls/src/config.rs +4 -1
- data/core/services/azdls/src/core.rs +276 -87
- data/core/services/azdls/src/deleter.rs +13 -4
- data/core/services/azdls/src/lister.rs +18 -12
- data/core/services/azdls/src/reader.rs +6 -2
- data/core/services/azdls/src/writer.rs +44 -23
- data/core/services/azfile/Cargo.toml +2 -2
- data/core/services/azfile/src/backend.rs +24 -8
- data/core/services/azfile/src/core.rs +195 -77
- data/core/services/azfile/src/deleter.rs +8 -1
- data/core/services/azfile/src/lister.rs +20 -14
- data/core/services/azfile/src/reader.rs +5 -2
- data/core/services/azfile/src/writer.rs +27 -15
- data/core/services/azure-common/Cargo.toml +1 -1
- data/core/services/b2/Cargo.toml +2 -2
- data/core/services/b2/src/backend.rs +30 -11
- data/core/services/b2/src/core.rs +134 -120
- data/core/services/b2/src/deleter.rs +1 -1
- data/core/services/b2/src/lister.rs +5 -2
- data/core/services/b2/src/reader.rs +5 -2
- data/core/services/b2/src/writer.rs +29 -12
- data/core/services/cacache/Cargo.toml +1 -1
- data/core/services/cacache/src/backend.rs +4 -5
- data/core/services/cacache/src/reader.rs +4 -1
- data/core/services/cacache/src/writer.rs +6 -2
- data/core/services/cloudflare-kv/Cargo.toml +1 -1
- data/core/services/cloudflare-kv/src/backend.rs +26 -15
- data/core/services/cloudflare-kv/src/config.rs +13 -2
- data/core/services/cloudflare-kv/src/core.rs +62 -56
- data/core/services/cloudflare-kv/src/deleter.rs +12 -3
- data/core/services/cloudflare-kv/src/lister.rs +66 -17
- data/core/services/cloudflare-kv/src/reader.rs +14 -9
- data/core/services/cloudflare-kv/src/writer.rs +10 -7
- data/core/services/compfs/Cargo.toml +1 -1
- data/core/services/compfs/src/backend.rs +11 -7
- data/core/services/compfs/src/lister.rs +7 -7
- data/core/services/compfs/src/writer.rs +1 -1
- data/core/services/cos/Cargo.toml +1 -1
- data/core/services/cos/src/backend.rs +129 -16
- data/core/services/cos/src/core.rs +198 -80
- data/core/services/cos/src/deleter.rs +4 -1
- data/core/services/cos/src/lister.rs +42 -27
- data/core/services/cos/src/reader.rs +6 -2
- data/core/services/cos/src/writer.rs +45 -21
- data/core/services/d1/Cargo.toml +1 -1
- data/core/services/d1/src/backend.rs +6 -5
- data/core/services/d1/src/core.rs +79 -63
- data/core/services/d1/src/reader.rs +4 -1
- data/core/services/d1/src/writer.rs +6 -2
- data/core/services/dashmap/Cargo.toml +1 -1
- data/core/services/dashmap/src/backend.rs +2 -2
- data/core/services/dashmap/src/reader.rs +4 -1
- data/core/services/dashmap/src/writer.rs +11 -8
- data/core/services/dbfs/Cargo.toml +1 -1
- data/core/services/dbfs/src/backend.rs +21 -15
- data/core/services/dbfs/src/core.rs +65 -60
- data/core/services/dbfs/src/deleter.rs +4 -1
- data/core/services/dbfs/src/lister.rs +10 -10
- data/core/services/dbfs/src/writer.rs +6 -3
- data/core/services/dropbox/Cargo.toml +2 -2
- data/core/services/dropbox/src/backend.rs +30 -23
- data/core/services/dropbox/src/core.rs +65 -63
- data/core/services/dropbox/src/deleter.rs +1 -1
- data/core/services/dropbox/src/lister.rs +17 -8
- data/core/services/dropbox/src/reader.rs +4 -1
- data/core/services/dropbox/src/writer.rs +13 -10
- data/core/services/etcd/Cargo.toml +1 -1
- data/core/services/etcd/src/backend.rs +8 -5
- data/core/services/etcd/src/core.rs +5 -11
- data/core/services/etcd/src/lister.rs +6 -1
- data/core/services/etcd/src/reader.rs +4 -1
- data/core/services/etcd/src/writer.rs +6 -3
- data/core/services/foundationdb/Cargo.toml +1 -1
- data/core/services/foundationdb/src/backend.rs +6 -5
- data/core/services/foundationdb/src/reader.rs +4 -1
- data/core/services/foundationdb/src/writer.rs +6 -2
- data/core/services/foyer/Cargo.toml +3 -3
- data/core/services/foyer/src/backend.rs +6 -5
- data/core/services/foyer/src/reader.rs +4 -1
- data/core/services/foyer/src/writer.rs +6 -2
- data/core/services/fs/Cargo.toml +1 -1
- data/core/services/fs/src/backend.rs +4 -3
- data/core/services/fs/src/core.rs +44 -26
- data/core/services/fs/src/lister.rs +9 -6
- data/core/services/fs/src/writer.rs +20 -13
- data/core/services/ftp/Cargo.toml +4 -6
- data/core/services/ftp/src/backend.rs +9 -5
- data/core/services/ftp/src/core.rs +9 -7
- data/core/services/ftp/src/lister.rs +7 -8
- data/core/services/ftp/src/reader.rs +3 -3
- data/core/services/ftp/src/writer.rs +3 -3
- data/core/services/gcs/Cargo.toml +4 -2
- data/core/services/gcs/src/backend.rs +53 -7
- data/core/services/gcs/src/composer.rs +705 -0
- data/core/services/gcs/src/copier.rs +14 -4
- data/core/services/gcs/src/core.rs +828 -124
- data/core/services/gcs/src/deleter.rs +33 -18
- data/core/services/gcs/src/lib.rs +1 -0
- data/core/services/gcs/src/lister.rs +21 -12
- data/core/services/gcs/src/reader.rs +12 -5
- data/core/services/gcs/src/writer.rs +632 -10
- data/core/services/gcs-grpc/Cargo.toml +58 -0
- data/core/services/gcs-grpc/README.md +19 -0
- data/core/services/gcs-grpc/proto/README.md +23 -0
- data/core/services/gcs-grpc/proto/google/storage/v2/storage.proto +171 -0
- data/core/services/gcs-grpc/proto/upstream-descriptor.bin +0 -0
- data/core/services/gcs-grpc/src/backend.rs +449 -0
- data/core/services/gcs-grpc/src/config.rs +116 -0
- data/core/services/gcs-grpc/src/copier.rs +98 -0
- data/core/services/gcs-grpc/src/core.rs +298 -0
- data/core/services/gcs-grpc/src/deleter.rs +65 -0
- data/core/services/gcs-grpc/src/docs.md +19 -0
- data/core/services/gcs-grpc/src/generated/google.storage.v2.rs +541 -0
- data/core/services/gcs-grpc/src/generated/mod.rs +24 -0
- data/core/services/gcs-grpc/src/lib.rs +43 -0
- data/core/services/gcs-grpc/src/lister.rs +125 -0
- data/core/services/gcs-grpc/src/reader.rs +140 -0
- data/core/services/gcs-grpc/src/writer.rs +780 -0
- data/core/services/gdrive/Cargo.toml +2 -2
- data/core/services/gdrive/src/backend.rs +123 -69
- data/core/services/gdrive/src/core.rs +87 -69
- data/core/services/gdrive/src/deleter.rs +8 -2
- data/core/services/gdrive/src/lister.rs +38 -26
- data/core/services/gdrive/src/path_index.rs +2 -2
- data/core/services/gdrive/src/reader.rs +9 -3
- data/core/services/gdrive/src/writer.rs +13 -7
- data/core/services/ghac/Cargo.toml +2 -2
- data/core/services/ghac/src/backend.rs +5 -2
- data/core/services/ghac/src/core.rs +59 -37
- data/core/services/ghac/src/reader.rs +5 -2
- data/core/services/ghac/src/writer.rs +16 -6
- data/core/services/github/Cargo.toml +1 -1
- data/core/services/github/src/backend.rs +16 -8
- data/core/services/github/src/core.rs +88 -76
- data/core/services/github/src/lister.rs +17 -15
- data/core/services/github/src/reader.rs +5 -2
- data/core/services/github/src/writer.rs +12 -6
- data/core/services/goosefs/Cargo.toml +2 -2
- data/core/services/goosefs/src/backend.rs +2 -2
- data/core/services/goosefs/src/core.rs +291 -208
- data/core/services/goosefs/src/docs.md +3 -0
- data/core/services/goosefs/src/lister.rs +2 -3
- data/core/services/goosefs/src/reader.rs +7 -3
- data/core/services/goosefs/src/writer.rs +21 -10
- data/core/services/goosefs/tests/safe_conditional_put.rs +37 -0
- data/core/services/gridfs/Cargo.toml +2 -2
- data/core/services/gridfs/src/backend.rs +12 -8
- data/core/services/gridfs/src/core.rs +1 -1
- data/core/services/gridfs/src/reader.rs +4 -1
- data/core/services/gridfs/src/writer.rs +6 -2
- data/core/services/hdfs/Cargo.toml +1 -1
- data/core/services/hdfs/src/backend.rs +1 -1
- data/core/services/hdfs/src/core.rs +7 -4
- data/core/services/hdfs/src/lister.rs +7 -9
- data/core/services/hdfs/src/writer.rs +5 -1
- data/core/services/hdfs-native/Cargo.toml +1 -1
- data/core/services/hdfs-native/src/backend.rs +1 -1
- data/core/services/hdfs-native/src/core.rs +44 -50
- data/core/services/hdfs-native/src/lister.rs +8 -10
- data/core/services/hdfs-native/src/writer.rs +5 -1
- data/core/services/hf/Cargo.toml +4 -3
- data/core/services/hf/src/backend.rs +4 -3
- data/core/services/hf/src/core.rs +907 -153
- data/core/services/hf/src/lister.rs +16 -6
- data/core/services/hf/src/reader.rs +377 -57
- data/core/services/hf/src/writer.rs +6 -2
- data/core/services/http/Cargo.toml +3 -3
- data/core/services/http/src/backend.rs +8 -6
- data/core/services/http/src/core.rs +57 -35
- data/core/services/http/src/reader.rs +5 -2
- data/core/services/ipfs/Cargo.toml +1 -1
- data/core/services/ipfs/src/backend.rs +20 -9
- data/core/services/ipfs/src/core.rs +43 -34
- data/core/services/ipfs/src/reader.rs +5 -2
- data/core/services/ipmfs/Cargo.toml +1 -1
- data/core/services/ipmfs/src/backend.rs +17 -8
- data/core/services/ipmfs/src/core.rs +66 -60
- data/core/services/ipmfs/src/deleter.rs +5 -2
- data/core/services/ipmfs/src/lister.rs +15 -12
- data/core/services/ipmfs/src/reader.rs +5 -2
- data/core/services/ipmfs/src/writer.rs +6 -3
- data/core/services/koofr/Cargo.toml +2 -2
- data/core/services/koofr/src/backend.rs +46 -17
- data/core/services/koofr/src/core.rs +64 -48
- data/core/services/koofr/src/deleter.rs +4 -1
- data/core/services/koofr/src/lister.rs +11 -10
- data/core/services/koofr/src/reader.rs +5 -2
- data/core/services/koofr/src/writer.rs +13 -7
- data/core/services/lakefs/Cargo.toml +1 -1
- data/core/services/lakefs/src/backend.rs +25 -8
- data/core/services/lakefs/src/core.rs +79 -73
- data/core/services/lakefs/src/deleter.rs +4 -1
- data/core/services/lakefs/src/lister.rs +17 -14
- data/core/services/lakefs/src/reader.rs +5 -2
- data/core/services/lakefs/src/writer.rs +11 -10
- data/core/services/memcached/Cargo.toml +1 -1
- data/core/services/memcached/src/backend.rs +57 -7
- data/core/services/memcached/src/config.rs +13 -2
- data/core/services/memcached/src/core.rs +11 -1
- data/core/services/memcached/src/reader.rs +4 -1
- data/core/services/memcached/src/writer.rs +6 -2
- data/core/services/mini_moka/Cargo.toml +1 -1
- data/core/services/mini_moka/src/backend.rs +8 -8
- data/core/services/mini_moka/src/reader.rs +4 -1
- data/core/services/mini_moka/src/writer.rs +11 -7
- data/core/services/moka/Cargo.toml +1 -1
- data/core/services/moka/src/backend.rs +7 -7
- data/core/services/moka/src/reader.rs +4 -1
- data/core/services/moka/src/writer.rs +10 -6
- data/core/services/mongodb/Cargo.toml +2 -2
- data/core/services/mongodb/src/backend.rs +7 -6
- data/core/services/mongodb/src/core.rs +1 -1
- data/core/services/mongodb/src/reader.rs +4 -1
- data/core/services/mongodb/src/writer.rs +6 -2
- data/core/services/monoiofs/Cargo.toml +2 -2
- data/core/services/monoiofs/src/backend.rs +16 -10
- data/core/services/monoiofs/src/core.rs +8 -9
- data/core/services/monoiofs/src/reader.rs +8 -10
- data/core/services/monoiofs/src/writer.rs +19 -24
- data/core/services/mysql/Cargo.toml +2 -2
- data/core/services/mysql/src/backend.rs +7 -6
- data/core/services/mysql/src/core.rs +1 -1
- data/core/services/mysql/src/lister.rs +7 -3
- data/core/services/mysql/src/reader.rs +4 -1
- data/core/services/mysql/src/writer.rs +6 -2
- data/core/services/obs/Cargo.toml +1 -1
- data/core/services/obs/src/backend.rs +29 -11
- data/core/services/obs/src/core.rs +81 -82
- data/core/services/obs/src/deleter.rs +4 -1
- data/core/services/obs/src/lister.rs +12 -5
- data/core/services/obs/src/reader.rs +5 -2
- data/core/services/obs/src/writer.rs +40 -19
- data/core/services/onedrive/Cargo.toml +2 -2
- data/core/services/onedrive/src/backend.rs +30 -21
- data/core/services/onedrive/src/config.rs +2 -2
- data/core/services/onedrive/src/core.rs +191 -90
- data/core/services/onedrive/src/deleter.rs +5 -2
- data/core/services/onedrive/src/graph_model.rs +10 -51
- data/core/services/onedrive/src/lister.rs +60 -24
- data/core/services/onedrive/src/reader.rs +17 -2
- data/core/services/onedrive/src/writer.rs +26 -15
- data/core/services/opfs/Cargo.toml +1 -1
- data/core/services/opfs/src/backend.rs +6 -13
- data/core/services/opfs/src/core.rs +33 -37
- data/core/services/opfs/src/lister.rs +4 -4
- data/core/services/opfs/src/writer.rs +1 -3
- data/core/services/oss/Cargo.toml +1 -1
- data/core/services/oss/src/backend.rs +40 -8
- data/core/services/oss/src/core.rs +192 -92
- data/core/services/oss/src/deleter.rs +16 -6
- data/core/services/oss/src/lister.rs +43 -27
- data/core/services/oss/src/reader.rs +6 -2
- data/core/services/oss/src/writer.rs +40 -22
- data/core/services/pcloud/Cargo.toml +1 -1
- data/core/services/pcloud/src/backend.rs +40 -6
- data/core/services/pcloud/src/core.rs +80 -66
- data/core/services/pcloud/src/deleter.rs +8 -1
- data/core/services/pcloud/src/lister.rs +4 -1
- data/core/services/pcloud/src/reader.rs +5 -2
- data/core/services/pcloud/src/writer.rs +6 -3
- data/core/services/persy/Cargo.toml +1 -1
- data/core/services/persy/src/backend.rs +6 -5
- data/core/services/persy/src/core.rs +60 -15
- data/core/services/persy/src/reader.rs +4 -1
- data/core/services/persy/src/writer.rs +6 -2
- data/core/services/postgresql/Cargo.toml +2 -2
- data/core/services/postgresql/src/backend.rs +7 -6
- data/core/services/postgresql/src/core.rs +1 -1
- data/core/services/postgresql/src/reader.rs +4 -1
- data/core/services/postgresql/src/writer.rs +6 -2
- data/core/services/redb/Cargo.toml +1 -1
- data/core/services/redb/src/backend.rs +6 -5
- data/core/services/redb/src/reader.rs +4 -1
- data/core/services/redb/src/writer.rs +6 -2
- data/core/services/redis/Cargo.toml +1 -1
- data/core/services/redis/src/backend.rs +18 -8
- data/core/services/redis/src/config.rs +13 -2
- data/core/services/redis/src/reader.rs +8 -4
- data/core/services/redis/src/writer.rs +6 -2
- data/core/services/rocksdb/Cargo.toml +1 -1
- data/core/services/rocksdb/src/backend.rs +6 -5
- data/core/services/rocksdb/src/lister.rs +6 -5
- data/core/services/rocksdb/src/reader.rs +4 -1
- data/core/services/rocksdb/src/writer.rs +6 -2
- data/core/services/s3/Cargo.toml +5 -4
- data/core/services/s3/src/backend.rs +995 -39
- data/core/services/s3/src/compatible_services.md +57 -0
- data/core/services/s3/src/config.rs +16 -0
- data/core/services/s3/src/copier.rs +190 -55
- data/core/services/s3/src/core.rs +299 -190
- data/core/services/s3/src/deleter.rs +26 -7
- data/core/services/s3/src/docs.md +57 -0
- data/core/services/s3/src/lister.rs +55 -36
- data/core/services/s3/src/reader.rs +22 -2
- data/core/services/s3/src/writer.rs +154 -32
- data/core/services/seafile/Cargo.toml +2 -2
- data/core/services/seafile/src/backend.rs +3 -3
- data/core/services/seafile/src/core.rs +105 -79
- data/core/services/seafile/src/lister.rs +11 -8
- data/core/services/seafile/src/reader.rs +5 -2
- data/core/services/seafile/src/writer.rs +6 -3
- data/core/services/sftp/Cargo.toml +1 -1
- data/core/services/sftp/src/backend.rs +19 -4
- data/core/services/sftp/src/core.rs +51 -46
- data/core/services/sftp/src/lister.rs +4 -4
- data/core/services/sftp/src/writer.rs +1 -1
- data/core/services/sled/Cargo.toml +1 -1
- data/core/services/sled/src/backend.rs +6 -5
- data/core/services/sled/src/core.rs +28 -6
- data/core/services/sled/src/lister.rs +6 -5
- data/core/services/sled/src/reader.rs +4 -1
- data/core/services/sled/src/writer.rs +6 -2
- data/core/services/sqlite/Cargo.toml +2 -2
- data/core/services/sqlite/src/backend.rs +12 -7
- data/core/services/sqlite/src/core.rs +3 -3
- data/core/services/sqlite/src/reader.rs +4 -1
- data/core/services/sqlite/src/writer.rs +7 -3
- data/core/services/surrealdb/Cargo.toml +2 -2
- data/core/services/surrealdb/src/backend.rs +7 -6
- data/core/services/surrealdb/src/core.rs +1 -1
- data/core/services/surrealdb/src/reader.rs +4 -1
- data/core/services/surrealdb/src/writer.rs +6 -2
- data/core/services/swift/Cargo.toml +1 -1
- data/core/services/swift/src/backend.rs +38 -8
- data/core/services/swift/src/core.rs +63 -67
- data/core/services/swift/src/deleter.rs +8 -2
- data/core/services/swift/src/lister.rs +11 -8
- data/core/services/swift/src/reader.rs +5 -2
- data/core/services/swift/src/writer.rs +17 -8
- data/core/services/tikv/Cargo.toml +2 -2
- data/core/services/tikv/src/backend.rs +7 -6
- data/core/services/tikv/src/core.rs +31 -14
- data/core/services/tikv/src/reader.rs +4 -1
- data/core/services/tikv/src/writer.rs +6 -2
- data/core/services/tos/Cargo.toml +2 -2
- data/core/services/tos/src/backend.rs +45 -21
- data/core/services/tos/src/copier.rs +44 -17
- data/core/services/tos/src/core.rs +147 -117
- data/core/services/tos/src/deleter.rs +9 -3
- data/core/services/tos/src/docs.md +1 -1
- data/core/services/tos/src/lister.rs +43 -28
- data/core/services/tos/src/reader.rs +5 -2
- data/core/services/tos/src/writer.rs +37 -16
- data/core/services/upyun/Cargo.toml +1 -1
- data/core/services/upyun/src/backend.rs +30 -7
- data/core/services/upyun/src/core.rs +122 -87
- data/core/services/upyun/src/deleter.rs +4 -1
- data/core/services/upyun/src/lister.rs +10 -10
- data/core/services/upyun/src/reader.rs +5 -2
- data/core/services/upyun/src/writer.rs +19 -7
- data/core/services/vercel-artifacts/Cargo.toml +1 -1
- data/core/services/vercel-artifacts/src/backend.rs +6 -3
- data/core/services/vercel-artifacts/src/core.rs +32 -27
- data/core/services/vercel-artifacts/src/reader.rs +5 -2
- data/core/services/vercel-artifacts/src/writer.rs +6 -3
- data/core/services/vercel-blob/Cargo.toml +1 -1
- data/core/services/vercel-blob/src/backend.rs +23 -6
- data/core/services/vercel-blob/src/core.rs +92 -81
- data/core/services/vercel-blob/src/lister.rs +12 -3
- data/core/services/vercel-blob/src/reader.rs +5 -2
- data/core/services/vercel-blob/src/writer.rs +19 -7
- data/core/services/webdav/Cargo.toml +2 -2
- data/core/services/webdav/src/backend.rs +25 -5
- data/core/services/webdav/src/core.rs +116 -59
- data/core/services/webdav/src/deleter.rs +4 -1
- data/core/services/webdav/src/lister.rs +4 -1
- data/core/services/webdav/src/reader.rs +6 -2
- data/core/services/webdav/src/writer.rs +17 -7
- data/core/services/webhdfs/Cargo.toml +2 -2
- data/core/services/webhdfs/src/backend.rs +24 -11
- data/core/services/webhdfs/src/core.rs +99 -98
- data/core/services/webhdfs/src/deleter.rs +5 -2
- data/core/services/webhdfs/src/lister.rs +21 -9
- data/core/services/webhdfs/src/reader.rs +5 -2
- data/core/services/webhdfs/src/writer.rs +49 -14
- data/core/services/yandex-disk/Cargo.toml +1 -1
- data/core/services/yandex-disk/src/backend.rs +28 -6
- data/core/services/yandex-disk/src/core.rs +97 -79
- data/core/services/yandex-disk/src/deleter.rs +4 -1
- data/core/services/yandex-disk/src/lister.rs +25 -9
- data/core/services/yandex-disk/src/reader.rs +5 -2
- data/core/services/yandex-disk/src/writer.rs +6 -3
- data/core/src/lib.rs +5 -0
- data/core/testkit/Cargo.toml +4 -4
- data/core/testkit/src/utils.rs +53 -8
- data/core/tests/behavior/async_compose.rs +297 -0
- data/core/tests/behavior/async_copy.rs +162 -1
- data/core/tests/behavior/async_delete.rs +364 -3
- data/core/tests/behavior/async_read.rs +86 -0
- data/core/tests/behavior/async_restore.rs +162 -0
- data/core/tests/behavior/async_stat.rs +90 -0
- data/core/tests/behavior/async_write.rs +330 -2
- data/core/tests/behavior/main.rs +4 -0
- data/core/upgrade.md +114 -1
- data/src/capability.rs +0 -1
- data/src/io.rs +0 -1
- data/src/lister.rs +0 -1
- data/src/metadata.rs +0 -1
- data/src/operator_info.rs +0 -1
- 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
|
-
///
|
|
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
|
-
///
|
|
171
|
+
/// Read the given version of the file instead of the current one.
|
|
74
172
|
///
|
|
75
|
-
/// This
|
|
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
|
-
///
|
|
177
|
+
/// Check [`crate::Capability::read_with_version`] before using this
|
|
178
|
+
/// option.
|
|
78
179
|
pub version: Option<String>,
|
|
79
180
|
|
|
80
|
-
///
|
|
181
|
+
/// Read only when the file has this exact ETag.
|
|
81
182
|
///
|
|
82
|
-
///
|
|
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
|
-
///
|
|
85
|
-
///
|
|
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
|
-
///
|
|
192
|
+
/// Read only when the file does not have this ETag.
|
|
88
193
|
///
|
|
89
|
-
///
|
|
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
|
-
///
|
|
92
|
-
///
|
|
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
|
-
///
|
|
95
|
-
///
|
|
96
|
-
///
|
|
97
|
-
///
|
|
98
|
-
///
|
|
99
|
-
/// [`crate::ErrorKind::
|
|
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
|
-
///
|
|
237
|
+
/// Read only when the file was not modified after this timestamp.
|
|
102
238
|
///
|
|
103
|
-
///
|
|
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
|
-
///
|
|
106
|
-
///
|
|
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
|
|
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
|
-
///
|
|
323
|
+
/// Read the given version of the file instead of the current one.
|
|
168
324
|
///
|
|
169
|
-
/// This
|
|
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
|
-
///
|
|
329
|
+
/// Check [`crate::Capability::read_with_version`] before using this
|
|
330
|
+
/// option.
|
|
172
331
|
pub version: Option<String>,
|
|
173
332
|
|
|
174
|
-
///
|
|
333
|
+
/// Read only when the file has this exact ETag.
|
|
175
334
|
///
|
|
176
|
-
///
|
|
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
|
-
///
|
|
179
|
-
///
|
|
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
|
-
///
|
|
344
|
+
/// Read only when the file does not have this ETag.
|
|
182
345
|
///
|
|
183
|
-
///
|
|
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
|
-
///
|
|
186
|
-
///
|
|
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
|
-
///
|
|
189
|
-
///
|
|
190
|
-
///
|
|
191
|
-
///
|
|
192
|
-
///
|
|
193
|
-
/// [`crate::ErrorKind::
|
|
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
|
-
///
|
|
389
|
+
/// Read only when the file was not modified after this timestamp.
|
|
196
390
|
///
|
|
197
|
-
///
|
|
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
|
-
///
|
|
200
|
-
///
|
|
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
|
|
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
|
-
///
|
|
475
|
+
/// Stat the given version of the file instead of the current one.
|
|
263
476
|
///
|
|
264
|
-
/// This
|
|
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
|
-
///
|
|
481
|
+
/// Check [`crate::Capability::stat_with_version`] before using this
|
|
482
|
+
/// option.
|
|
267
483
|
pub version: Option<String>,
|
|
268
484
|
|
|
269
|
-
///
|
|
485
|
+
/// Stat only when the file has this exact ETag.
|
|
270
486
|
///
|
|
271
|
-
///
|
|
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
|
-
///
|
|
274
|
-
///
|
|
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
|
-
///
|
|
496
|
+
/// Stat only when the file does not have this ETag.
|
|
277
497
|
///
|
|
278
|
-
///
|
|
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
|
-
///
|
|
281
|
-
///
|
|
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
|
-
///
|
|
284
|
-
///
|
|
285
|
-
///
|
|
286
|
-
///
|
|
287
|
-
///
|
|
288
|
-
/// [`crate::ErrorKind::
|
|
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
|
-
///
|
|
541
|
+
/// Stat only when the file was not modified after this timestamp.
|
|
291
542
|
///
|
|
292
|
-
///
|
|
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
|
-
///
|
|
295
|
-
///
|
|
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
|
-
///
|
|
703
|
+
/// Write only when the file at the write path has this exact ETag.
|
|
432
704
|
///
|
|
433
|
-
///
|
|
434
|
-
///
|
|
435
|
-
///
|
|
436
|
-
///
|
|
437
|
-
///
|
|
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
|
-
///
|
|
447
|
-
///
|
|
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
|
-
///
|
|
450
|
-
///
|
|
451
|
-
///
|
|
452
|
-
///
|
|
453
|
-
///
|
|
454
|
-
///
|
|
455
|
-
///
|
|
456
|
-
///
|
|
457
|
-
///
|
|
458
|
-
///
|
|
459
|
-
///
|
|
460
|
-
///
|
|
461
|
-
///
|
|
462
|
-
///
|
|
463
|
-
///
|
|
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
|
-
///
|
|
471
|
-
///
|
|
472
|
-
///
|
|
473
|
-
///
|
|
474
|
-
///
|
|
475
|
-
///
|
|
476
|
-
///
|
|
477
|
-
///
|
|
478
|
-
///
|
|
479
|
-
|
|
480
|
-
///
|
|
481
|
-
///
|
|
482
|
-
///
|
|
483
|
-
///
|
|
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
|
|
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
|
|
542
|
-
///
|
|
543
|
-
///
|
|
544
|
-
/// ### Capability
|
|
836
|
+
pub struct ComposeSourceOptions {
|
|
837
|
+
/// Compose this version of the source object.
|
|
545
838
|
///
|
|
546
|
-
///
|
|
839
|
+
/// This selects which stored version the composition reads; it is not a
|
|
840
|
+
/// condition on the destination object.
|
|
547
841
|
///
|
|
548
|
-
///
|
|
549
|
-
///
|
|
550
|
-
|
|
551
|
-
///
|
|
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
|
-
///
|
|
555
|
-
///
|
|
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
|
-
|
|
559
|
-
|
|
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
|
-
///
|
|
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
|
-
///
|
|
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
|
-
///
|
|
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
|
-
///
|
|
568
|
-
///
|
|
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
|
|
998
|
+
/// Copy from a specific source file version.
|
|
572
999
|
///
|
|
573
|
-
///
|
|
574
|
-
///
|
|
575
|
-
///
|
|
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
|
-
///
|
|
580
|
-
///
|
|
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
|
-
///
|
|
1008
|
+
/// Asserted complete content length of the source object.
|
|
585
1009
|
///
|
|
586
|
-
///
|
|
587
|
-
///
|
|
588
|
-
///
|
|
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
|
-
///
|
|
1056
|
+
/// Rename only when no file exists at the destination path.
|
|
615
1057
|
///
|
|
616
|
-
///
|
|
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
|
-
///
|
|
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
|
-
///
|
|
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
|
-
///
|
|
623
|
-
///
|
|
624
|
-
|
|
625
|
-
|
|
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
|
}
|