[incubator-opendal] 01/01: RFC: Operation Extension

[xu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch proposal-of-http-headers
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git

commit f6cd0a847076aee4bdd2b1921825c41f53f1c271
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Thu Mar 23 19:15:32 2023 +0800

    RFC: Operation Extension
    
    Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
 core/src/docs/rfcs/0000_operation_extension.md | 110 +++++++++++++++++++++++++
 core/src/docs/rfcs/mod.rs                      |   3 +
 2 files changed, 113 insertions(+)

diff --git a/core/src/docs/rfcs/0000_operation_extension.md b/core/src/docs/rfcs/0000_operation_extension.md
new file mode 100644
index 00000000..93600fae
--- /dev/null
+++ b/core/src/docs/rfcs/0000_operation_extension.md
@@ -0,0 +1,110 @@
+- Proposal Name: `operation_extension`
+- Start Date: 2023-03-23
+- RFC PR: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/pull/0000)
+- Tracking Issue: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/issues/0000)
+
+# Summary
+
+Extend operation capabilities to support additional native features.
+
+# Motivation
+
+OpenDAL only supports a limited set of capabilities for operations.
+
+- `read`/`stat`: only supports `range`
+- `write`: only supports `content_type` and `content_disposition`
+
+Our community has a strong need for more additional native features. For example:
+
+- [opendal#892](https://github.com/apache/incubator-opendal/issues/892) wants [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control): Allow users to specify the cache control headers for the uploaded files.
+- [opendal#825](https://github.com/apache/incubator-opendal/issues/825) wants [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) and [If-None-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match): Allow users to makes a request conditional.
+- [opendal#1726](https://github.com/apache/incubator-opendal/issues/1726) wants [response-content-disposition](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html): Allow users to specify the content disposition for the downloaded files.
+
+All of these feature requests are essentially asking for the same thing: the capability to define supplementary arguments for operations, particularly about HTTP services.
+
+# Guide-level explanation
+
+In this RFC, we will allow users to specify the standard HTTP headers like cache_control/if_match:
+
+```rust
+let op = OpRead::default().
+    with_cache_control("max-age=3600").
+    with_if_match("\"bfc13a64729c4290ef5b2c2730249c88ca92d82d\"");
+let bs = o.read_with(op).await?;
+```
+
+Also, we will support some non-standard but widely users features like `response-content-disposition`:
+
+```rust
+let op = OpRead::default().
+    with_override_content_disposition("attachment; filename=\"foo.txt\"");
+let req = op.presign_read_with("filename", Duration::hours(1), op)?;
+```
+
+And, finally, we will support allow specify the default headers for services. Take `s3`'s `storage_class` as an example:
+
+```rust
+let mut builder = S3::default();
+builder.default_storage_class("STANDARD_IA");
+builder.default_cache_control("max-age=3600");
+```
+
+In general, we will support the following features:
+
+- Allow users to specify the (non-)standard HTTP headers for operations.
+- Allow users to specify the default HTTP headers for services.
+
+# Reference-level explanation
+
+We will make the following changes in OpenDAL:
+
+For `OpRead` & `OpStat`:
+
+```diff
+pub struct OpRead {
+    br: BytesRange,
++   cache_control: Option<String>,
++   if_match: Option<String>,
++   if_none_match: Option<String>,
++   override_content_disposition: Option<String>,
+}
+```
+
+For `OpWrite`:
+
+```diff
+pub struct OpWrite {
+    append: bool,
+
+    content_type: Option<String>,
+    content_disposition: Option<String>,
++   cache_control: Option<String>,
+}
+```
+
+We will provide different default options for each service. For example, we can add `default_storage_class` for `s3`.
+
+
+# Drawbacks
+
+None
+
+# Rationale and alternatives
+
+None
+
+# Prior art
+
+None
+
+# Unresolved questions
+
+None
+
+# Future possibilities
+
+## Strict Mode
+
+Additionally, we have implemented a `strict` option for the `Operator`. If users enable this option, OpenDAL will return an error message for unsupported options. Otherwise, it will ignore them.
+
+For instance, if users rely on the `if_match` behavior but services like `fs` and `hdfs` do not support it natively, they can use the `op.with_strict()` function to prompt OpenDAL to return an error.
diff --git a/core/src/docs/rfcs/mod.rs b/core/src/docs/rfcs/mod.rs
index 9d21655c..00aa8509 100644
--- a/core/src/docs/rfcs/mod.rs
+++ b/core/src/docs/rfcs/mod.rs
@@ -130,3 +130,6 @@ pub mod rfc_1420_object_writer {}
 
 #[doc = include_str!("1477_remove_object_concept.md")]
 pub mod rfc_1477_remove_object_concept {}
+
+#[doc = include_str!("0000_operation_extension.md")]
+pub mod rfc_0000_operation_extension {}