opendal-core 0.56.0

Apache OpenDAL™: One Layer, All Storage.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

- Proposal Name: `conditional_reader`
- Start Date: 2024-12-31
- RFC PR: [apache/opendal#5485](https://github.com/apache/opendal/pull/5485)
- Tracking Issue: [apache/opendal#5486](https://github.com/apache/opendal/issues/5486)

# Summary

Add `if_match`, `if_none_match`, `if_modified_since` and `if_unmodified_since` options to OpenDAL's `reader_with` API.

# Motivation

OpenDAL currently supports conditional `reader_with` operations based only on `version`. However, many storage services 
also support conditional operations based on Etag and/or modification time.

Adding these options will:

- Provide more granular control over read operations.
- Align OpenDAL with features provided by modern storage services, meeting broader use cases.

# Guide-level explanation

Four new options will be added to the `reader_with` API:

## `if_match`

Return the content only if its Etag matches the specified Etag; otherwise,
an error kind `ErrorKind::ConditionNotMatch` will be returned:

```rust
let reader = op.reader_with("path/to/file")
    .if_match(etag)
    .await?;
```

## `if_none_match`

Return the content only if its Etag does NOT match the specified Etag; otherwise,
an error kind `ErrorKind::ConditionNotMatch` will be returned:

```rust
let reader = op.reader_with("path/to/file")
    .if_none_match(etag)
    .await?;
```

## `if_modified_since`

Return the content if it has been modified since the specified time; otherwise, 
an error kind `ErrorKind::ConditionNotMatch` will be returned:

```rust
use chrono::{Duration, Utc};

let last_check = Utc::now() - Duration::seconds(3600); // 1 hour ago
let reader = op.reader_with("path/to/file")
    .if_modified_since(last_check)
    .await?;
```


## `if_unmodified_since` 

Return the content if it has NOT been modified since the specified time; otherwise, 
an error kind `ErrorKind::ConditionNotMatch` will be returned:

```rust
use chrono::{Duration, Utc};

let timestamp = Utc::now() - Duration::seconds(86400); // 24 hours ago
let reader = op.reader_with("path/to/file")
    .if_unmodified_since(timestamp)
    .await?;
```


# Reference-level explanation

The main implementation will include:

1. Add new fields(`if_modified_since`, `if_unmodified_since`) and related functions to `OpRead`.

2. Add the related functions to `FutureReader`

3. Add new capability flags:
```rust
pub struct Capability {
    // ... other fields
    pub read_with_if_modified_since: bool,
    pub read_with_if_unmodified_since: bool,
}
```
4. implement `if_modified_since`, `if_unmodified_since` for the underlying storage service.

# Drawbacks

- Add complexity to the API

# Rationale and alternatives

- Follows existing OpenDAL patterns for conditional operations

# Prior art

None

# Unresolved questions

None

# Future possibilities

None