[incubator-opendal] branch proposal-of-http-headers created (now f6cd0a84)

[xu...@apache.org]

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

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


      at f6cd0a84 RFC: Operation Extension

This branch includes the following new commits:

     new f6cd0a84 RFC: Operation Extension

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[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 {}