RFC-2852: Native Capability (#2852)

* Save work Signed-off-by: Xuanwo <[email protected]> * Add proposal Signed-off-by: Xuanwo <[email protected]> * Assign number Signed-off-by: Xuanwo <[email protected]> * Update tracking issues Signed-off-by: Xuanwo <[email protected]> --------- Signed-off-by: Xuanwo <[email protected]>
apache · Aug 14, 2023 · bb51cbe · bb51cbe
1 parent 57944b7
commit bb51cbe
Show file tree

Hide file tree

Showing 2 changed files with 61 additions and 0 deletions.
diff --git a/core/src/docs/rfcs/2852_native_capability.md b/core/src/docs/rfcs/2852_native_capability.md
@@ -0,0 +1,58 @@
+- Proposal Name: `native_capability`
+- Start Date: 2023-08-11
+- RFC PR: [apache/incubator-opendal#2852](https://github.com/apache/incubator-opendal/pull/2852)
+- Tracking Issue: [apache/incubator-opendal#2859](https://github.com/apache/incubator-opendal/issues/2859)
+
+# Summary
+
+Add `native_capability` and `full_capability` to `Operator` so that users can make more informed decisions.
+
+# Motivation
+
+OpenDAL adds `Capability` to inform users whether a service supports a specific feature. However, this is not enough for users to make decisions. OpenDAL doesn't simply expose the services' API directly; instead, it simulates the behavior to make it more useful.
+
+For example, `s3` doesn't support seek operations like a local file system. But it's a quite common operation for users. So OpenDAL will try to simulate the behavior by calculating the correct offset and reading the data from that offset instead. After this simulation, the `s3` service has the `read_can_seek` capability now.
+
+As another example, most services like `s3` don't support blocking operations. OpenDAL implements a `BlockingLayer` to make it possible. After this implementation, the `s3` service has the `blocking` capability now.
+
+However, these capabilities alone are insufficient for users to make informed decisions. Take the `s3` service's `blocking` capability as an example. Users are unable to determine whether it is a native capability or not, which may result in them unknowingly utilizing this feature in performance-sensitive scenarios, leading to significantly poor performance.
+
+So this proposal intends to address this issue by adding `native_capability` and `full_capability` to `OperatorInfo`. Users can use `native_capability` to determine whether a capability is native or not.
+
+# Guide-level explanation
+
+We will add two new APIs `native_capability()` and `full_capability()` in `OperatorInfo`, and remove the `capability()` and related `can_xxx()` API.
+
+```diff
++ pub fn native_capability(&self) -> Capability
++ pub fn full_capability(&self) -> Capability
+- pub fn capability(&self) -> Capability
+```
+
+# Reference-level explanation
+
+We will add two new fields `native_capability` and `full_capability` in `AccessorInfo`:
+
+- Services SHOULD only set `native_capability`, and `full_capability` will be the same as `native_capability`.
+- Layers MAY change `full_capability` and MUST NOT modify `native_capability`.
+- `OperatorInfo` should forward `native_capability()` and `full_capability()` to `AccessorInfo`.
+
+# Drawbacks
+
+None
+
+# 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
@@ -154,3 +154,6 @@ pub mod rfc_2774_lister_api {}
 
 #[doc = include_str!("2779_list_with_metakey.md")]
 pub mod rfc_2779_list_with_metakey {}
+
+#[doc = include_str!("2852_native_capability.md")]
+pub mod rfc_2852_native_capability {}