diff --git a/core/src/docs/rfcs/3232_align_list_api.md b/core/src/docs/rfcs/3232_align_list_api.md new file mode 100644 index 000000000000..788d57d0017e --- /dev/null +++ b/core/src/docs/rfcs/3232_align_list_api.md @@ -0,0 +1,69 @@ +- Proposal Name: `align_list_api` +- Start Date: 2023-10-07 +- RFC PR: [apache/incubator-opendal#3232](https://github.com/apache/incubator-opendal/pull/3232) +- Tracking Issue: [apache/incubator-opendal#3236](https://github.com/apache/incubator-opendal/issues/3236) + +# Summary + +Refactor internal `Page` API to `List` API. + +# Motivation + +OpenDAL's `Lister` is implemented by `Page`: + +```rust +#[async_trait] +pub trait Page: Send + Sync + 'static { + /// Fetch a new page of [`Entry`] + /// + /// `Ok(None)` means all pages have been returned. Any following call + /// to `next` will always get the same result. + async fn next(&mut self) -> Result>>; +} +``` + +Each call to `next` will retrieve a page of `Entry` objects. This design is modeled after the `list_object` API used in object storage services. However, this design has several drawbacks: + +- Services like `fs`, `hdfs` needs to buffer the whole page in memory before returning it to the caller. +- `Page` is not aligned with `opendal::Lister` make it hard to understand the code. +- `Page` is not aligned with `Read` & `Write` which is poll based. + +# Guide-level explanation + +No user-facing changes. + +# Reference-level explanation + +We will rename `Page` to `List` and change the API to: + +```rust +pub trait List: Send + Sync + 'static { + /// Fetch a new [`Entry`] + /// + /// `Ok(None)` means all entries have been returned. Any following call + /// to `next` will always get the same result. + fn poll_next(&mut self, cx: &mut Context<'_>) -> Result>; +} +``` + +All `page` related code will be replaced by `list`. + +# Drawbacks + +Breaking changes for raw API. + +# Rationale and alternatives + +None + +# Prior art + +None + +# Unresolved questions + +None + +# Future possibilities + +None diff --git a/core/src/docs/rfcs/mod.rs b/core/src/docs/rfcs/mod.rs index 25c8e0f9c257..e154a4b2ff9d 100644 --- a/core/src/docs/rfcs/mod.rs +++ b/core/src/docs/rfcs/mod.rs @@ -160,3 +160,6 @@ pub mod rfc_2852_native_capability {} #[doc = include_str!("3017_remove_write_copy_from.md")] pub mod rfc_3017_remove_write_copy_from {} + +#[doc = include_str!("3232_align_list_api.md")] +pub mod rfc_3232_align_list_api {}