This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new c4c31c68c RFC-3526: List Recursive (#3526)
c4c31c68c is described below
commit c4c31c68c3d093c8f9a76ae19c315b2e95f44bb0
Author: Xuanwo <[email protected]>
AuthorDate: Thu Nov 9 18:43:57 2023 +0800
RFC-3526: List Recursive (#3526)
* rfc: List Recursive
Signed-off-by: Xuanwo <[email protected]>
* polish
Signed-off-by: Xuanwo <[email protected]>
* Assign number
Signed-off-by: Xuanwo <[email protected]>
---------
Signed-off-by: Xuanwo <[email protected]>
---
core/src/docs/rfcs/3526_list_recursive.md | 59 +++++++++++++++++++++++++++++++
core/src/docs/rfcs/mod.rs | 3 ++
2 files changed, 62 insertions(+)
diff --git a/core/src/docs/rfcs/3526_list_recursive.md
b/core/src/docs/rfcs/3526_list_recursive.md
new file mode 100644
index 000000000..ac393b3d9
--- /dev/null
+++ b/core/src/docs/rfcs/3526_list_recursive.md
@@ -0,0 +1,59 @@
+- Proposal Name: `list_recursive`
+- Start Date: 2023-11-08
+- RFC PR:
[apache/incubator-opendal#3526](https://github.com/apache/incubator-opendal/pull/3526)
+- Tracking Issue:
[apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/issues/0000)
+
+# Summary
+
+Use `recursive` to replace `delimiter`.
+
+# Motivation
+
+OpenDAL add `delimiter` in `list` to allow users to control the list behavior:
+
+- `delimiter == "/"` means use `/` as delimiter of path, it behaves like list
current dir.
+- `delimiter == ""` means don't set delimiter of path, it behaves like list
current dir and all it's children.
+
+Ideally, we should allow users to input any delimiter such as `|`, `-`, and
`+`.
+
+The `delimiter` concept can be challenging for users unfamiliar with object
storage services. Currently, only `/` and empty spaces are accepted as
delimiters, despite not being fully implemented across all services. We need to
inform users that `delimiter == "/"` is used to list the current directory,
while `delimiter == ""` is used for recursive listing. This may not be
immediately clear.
+
+So, why not use `recursive` directly for more clear API behavior?
+
+# Guide-level explanation
+
+OpenDAL will use `recursive` to replace `delimiter`. Default behavior is not
changed, so users that using `op.list()` is not affected.
+
+For users who is using `op.list_with(path).delimiter(delimiter)`:
+
+- `op.list_with(path).delimiter("")` -> `op.list_with(path).recursive(true)`
+- `op.list_with(path).delimiter("/")` -> `op.list_with(path).recursive(false)`
+- `op.list_with(path).delimiter(other_value)`: not supported anymore.
+
+# Reference-level explanation
+
+We will add `recursive` as a new arg in `OpList` and remove all fields related
to `delimiter`.
+
+# Drawbacks
+
+## Can't support to use `|`, `-`, and `+` as delimiter
+
+We never support this feature before.
+
+# Rationale and alternatives
+
+None
+
+# Prior art
+
+None
+
+# Unresolved questions
+
+None
+
+# Future possibilities
+
+## Add delete with recursive support
+
+Some services have native support for delete with recursive, such as azfile.
We can add this feature in the future if needed.
diff --git a/core/src/docs/rfcs/mod.rs b/core/src/docs/rfcs/mod.rs
index 95de473c3..16fdddf83 100644
--- a/core/src/docs/rfcs/mod.rs
+++ b/core/src/docs/rfcs/mod.rs
@@ -172,3 +172,6 @@ pub mod rfc_3243_list_prefix {}
#[doc = include_str!("3356_lazy_reader.md")]
pub mod rfc_3356_lazy_reader {}
+
+#[doc = include_str!("3526_list_recursive.md")]
+pub mod rfc_3526_list_recursive {}
