Module rfc_2852_native_capability 

Native capability

• Proposal Name: native_capability
• Start Date: 2023-08-11
• RFC PR: apache/opendal#2852
• Tracking Issue: apache/opendal#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.

+ 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