RFC-3232: Align List API (apache#3232)

* rfc: Align list API Signed-off-by: Xuanwo <[email protected]> * Add docs Signed-off-by: Xuanwo <[email protected]> * Update links Signed-off-by: Xuanwo <[email protected]> --------- Signed-off-by: Xuanwo <[email protected]>
Zheaoli · Oct 12, 2023 · 82cbdc9 · 82cbdc9
1 parent b768a28
commit 82cbdc9
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 0 deletions.
diff --git a/core/src/docs/rfcs/3232_align_list_api.md 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<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
diff --git 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 {}