suyanhanx commented on code in PR #2852: URL: https://github.com/apache/incubator-opendal/pull/2852#discussion_r1291134201
########## 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#0000](https://github.com/apache/incubator-opendal/issues/0000) + +# 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 Review Comment: I'm considering keeping the `capability` name. Adding a `full` doesn't seem to show much of a difference. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
