diff --git a/core/src/docs/rfcs/1735_operation_extension.md b/core/src/docs/rfcs/1735_operation_extension.md new file mode 100644 index 00000000000..ad5aad78481 --- /dev/null +++ b/core/src/docs/rfcs/1735_operation_extension.md @@ -0,0 +1,117 @@ +- Proposal Name: `operation_extension` +- Start Date: 2023-03-23 +- RFC PR: [apache/incubator-opendal#1735](https://github.com/apache/incubator-opendal/pull/1735) +- Tracking Issue: [apache/incubator-opendal#1738](https://github.com/apache/incubator-opendal/issues/1738) + +# 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 used 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, ++ if_match: Option, ++ if_none_match: Option, ++ override_content_disposition: Option, +} +``` + +For `OpWrite`: + +```diff +pub struct OpWrite { + append: bool, + + content_type: Option, + content_disposition: Option, ++ cache_control: Option, +} +``` + +We will provide different default options for each service. For example, we can add `default_storage_class` for `s3`. + + +# Drawbacks + +None + +# Rationale and alternatives + +## Why using `override_content_disposition` instead of `response_content_disposition`? + +`response_content_disposition` is not a part of HTTP standard, it's the private API provided by `s3`. + +- `azblob` will use `x-ms-blob-content-disposition` header +- `ocios` will use `httpResponseContentDisposition` query + +OpenDAL does not accept the query as is. Instead, we have created a more readable name `override_content_disposition` to clarify its purpose. + +# 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 9d21655ce28..a0f6ec2f6c4 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!("1735_operation_extension.md")] +pub mod rfc_1735_operation_extension {}