[incubator-opendal] branch refactor-page created (now a6a5927c8)

[xu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a change to branch refactor-page
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git


      at a6a5927c8 rfc: Align list API

This branch includes the following new commits:

     new a6a5927c8 rfc: Align list API

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[incubator-opendal] 01/01: rfc: Align list API

[xu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch refactor-page
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git

commit a6a5927c8b193e413669ac1978945223edf9a34b
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Sat Oct 7 15:54:18 2023 +0800

    rfc: Align list API
    
    Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
 core/src/docs/rfcs/0000_align_list_api.md | 69 +++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/core/src/docs/rfcs/0000_align_list_api.md b/core/src/docs/rfcs/0000_align_list_api.md
new file mode 100644
index 000000000..11566bcb2
--- /dev/null
+++ b/core/src/docs/rfcs/0000_align_list_api.md
@@ -0,0 +1,69 @@
+- Proposal Name: `align_list_api`
+- Start Date: 2023-10-07
+- RFC PR: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/pull/0000)
+- Tracking Issue: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/issues/0000)
+
+# 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<Option<Vec<Entry>>>;
+}
+```
+
+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<Option<Entry>>;
+}
+```
+
+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