Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(core): Add upgrade to v0.51 #5406

Merged
merged 2 commits into from
Dec 11, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 89 additions & 1 deletion core/src/docs/upgrade.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,91 @@
# Upgrade to v0.51

## Public API

### New VISION: One Layer, All Storage

OpenDAL has refined its vision to **One Layer, All Storage**, driven by the following core principles: **Open Community**, **Solid Foundation**, **Fast Access**, **Object Storage First**, and **Extensible Architecture**.

Explore the detailed vision at [OpenDAL Vision](https://opendal.apache.org/docs/vision).

### RFC-5313: Remove Metakey

OpenDAL v0.51 implements [RFC-5313](https://opendal.apache.org/docs/rust/opendal/docs/rfcs/rfc_5314_remove_metakey/index.html), which removes the concept of metakey.

The following structs have been removed:

- `Metakey`

The following APIs have been removed:

- `list_with(path).metakey()`

Users no longer need to pass the metakey into the list. Instead, services will make their best effort to return as much metadata as possible. Users can check items like `Capability::list_has_etag` before making a call.

### Remove not used capability: `write_multi_align_size`

The capability `write_multi_align_size` is not utilized by any services, and we have no plans to support it in the future; therefore, we have removed it.

### CapabilityCheckLayer and CorrectnessCheckLayer

OpenDAL used to perform capability checks for all services, but since v0.51, it only conducts checks that impact data correctness like `write_with_if_not_exists` or `delete_with_version` by default in the `CorrectnessCheckLayer`. If users wish to verify other non-critical capabilities like `write_with_content_type` or `write_with_cache_control`, they should manually enable the `CapabilityCheckLayer`.

### RFC-3911: Deleter API

OpenDAL v0.51 implements [RFC-3911](https://opendal.apache.org/docs/rust/opendal/docs/rfcs/rfc_3911_deleter_api/index.html), which adds `Deleter` in OpenDAL to replace `batch` operation.

The following new APIs have been added:

- [`Operator::delete_iter`]
- [`Operator::delete_try_iter`]
- [`Operator::delete_stream`]
- [`Operator::delete_try_stream`]
- [`Operator::deleter`]
- [`Deleter::delete`]
- [`Deleter::delete_iter`]
- [`Deleter::delete_try_iter`]
- [`Deleter::delete_stream`]
- [`Deleter::delete_try_stream`]
- [`Deleter::flush`]
- [`Deleter::close`]
- [`Deleter::into_sink`]
- [`DeleteInput`]
- [`IntoDeleteInput`]
- [`FuturesDeleteSink`]

The following APIs have been deprecated and will be removed in the future releases:

- `Operator::remove` (replace with [`Operator::delete_iter`])
- `Operator::remove_via` (replace with [`Operator::delete_stream`])

As a result of this change, the `limit` and `with_limit` APIs on `Operator` have also been deprecated; they are currently no-ops.

## Raw API

### `adapter::kv` now returns `Scanner` instead of `Vec<String>`

To support returning key-value entries in a streaming manner instead of loading them all into memory, OpenDAL updated its adapter API to return a `Scanner` instead of a `Vec<String>`.

```diff
- async fn scan(&self, path: &str) -> Result<Vec<String>>
+ async fn scan(&self, path: &str) -> Result<Self::Scanner>
```

All services intending to implement `kv::Adapter` should adhere to this API change.

## Align `metadata` API to `info`

OpenDAL changes it's old `metadata` API to `info` to align with the new `AccessorInfo` struct.

```diff
- fn metadata(&self) -> Arc<AccessorInfo>
+ fn info(&self) -> Arc<AccessorInfo>
```

### Remove not used struct: `RangeWriter`

The struct `RangeWriter` is not utilized by any services, and we have no plans to support it in the future; therefore, we have removed it.

# Upgrade to v0.50

## Public API
Expand All @@ -12,7 +100,7 @@ Previously, `list("a/b")` would not return `a/b` even if it does exist. Since v0

### Refactoring of the metrics-related layer

In OpenDAL v0.50.0, we did a refactor on all metrics-related layers. They are now sharing the same underlying implemenationts. `PrometheusLayer`, `PrometheusClientLayer` and `MetricsLayer` are now have similar public APIs and exactly the same metrics value.
In OpenDAL v0.50.0, we did a refactor on all metrics-related layers. They are now sharing the same underlying implementations. `PrometheusLayer`, `PrometheusClientLayer` and `MetricsLayer` are now have similar public APIs and exactly the same metrics value.

# Upgrade to v0.49

Expand Down
Loading