From c1927a05227adb1c349ac4addd1348d818fb462c Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Thu, 29 Feb 2024 11:42:51 +0800 Subject: [PATCH] docs: Fix and improve docs for presign operations (#4294) Signed-off-by: Xuanwo --- core/src/services/azblob/core.rs | 14 ++- core/src/services/azdls/backend.rs | 3 +- core/src/services/memcached/binary.rs | 5 +- core/src/services/vercel_blob/core.rs | 3 +- core/src/services/vercel_blob/writer.rs | 5 +- core/src/services/webdav/core.rs | 18 ++- core/src/services/webdav/lister.rs | 3 +- core/src/services/webdav/writer.rs | 3 +- core/src/types/operator/operator.rs | 153 ++++++++++++++++++++---- 9 files changed, 165 insertions(+), 42 deletions(-) diff --git a/core/src/services/azblob/core.rs b/core/src/services/azblob/core.rs index c0c6790b17e2..dcf474b18435 100644 --- a/core/src/services/azblob/core.rs +++ b/core/src/services/azblob/core.rs @@ -15,6 +15,12 @@ // specific language governing permissions and limitations // under the License. +use std::fmt; +use std::fmt::Debug; +use std::fmt::Formatter; +use std::fmt::Write; +use std::time::Duration; + use base64::prelude::BASE64_STANDARD; use base64::Engine; use bytes::Bytes; @@ -29,12 +35,8 @@ use http::Response; use reqsign::AzureStorageCredential; use reqsign::AzureStorageLoader; use reqsign::AzureStorageSigner; -use serde::{Deserialize, Serialize}; -use std::fmt; -use std::fmt::Debug; -use std::fmt::Formatter; -use std::fmt::Write; -use std::time::Duration; +use serde::Deserialize; +use serde::Serialize; use uuid::Uuid; use crate::raw::*; diff --git a/core/src/services/azdls/backend.rs b/core/src/services/azdls/backend.rs index 7e128524cee4..4d6a36ed3b8c 100644 --- a/core/src/services/azdls/backend.rs +++ b/core/src/services/azdls/backend.rs @@ -31,7 +31,8 @@ use serde::Deserialize; use super::core::AzdlsCore; use super::error::parse_error; use super::lister::AzdlsLister; -use super::writer::{AzdlsWriter, AzdlsWriters}; +use super::writer::AzdlsWriter; +use super::writer::AzdlsWriters; use crate::raw::*; use crate::*; diff --git a/core/src/services/memcached/binary.rs b/core/src/services/memcached/binary.rs index 5fbce6a5ca5a..ef33a891bc59 100644 --- a/core/src/services/memcached/binary.rs +++ b/core/src/services/memcached/binary.rs @@ -15,7 +15,10 @@ // specific language governing permissions and limitations // under the License. -use tokio::io::{self, AsyncReadExt, AsyncWriteExt, BufReader}; +use tokio::io::AsyncReadExt; +use tokio::io::AsyncWriteExt; +use tokio::io::BufReader; +use tokio::io::{self}; use tokio::net::TcpStream; use crate::raw::*; diff --git a/core/src/services/vercel_blob/core.rs b/core/src/services/vercel_blob/core.rs index 54900dfff8d9..9fea54d9f9eb 100644 --- a/core/src/services/vercel_blob/core.rs +++ b/core/src/services/vercel_blob/core.rs @@ -29,11 +29,10 @@ use serde::Serialize; use serde_json::json; use self::constants::*; +use super::error::parse_error; use crate::raw::*; use crate::*; -use super::error::parse_error; - pub(super) mod constants { // https://github.com/vercel/storage/blob/main/packages/blob/src/put.ts#L16 // x-content-type specifies the MIME type of the file being uploaded. diff --git a/core/src/services/vercel_blob/writer.rs b/core/src/services/vercel_blob/writer.rs index 46b8e32b8bd7..f7f3b90d759e 100644 --- a/core/src/services/vercel_blob/writer.rs +++ b/core/src/services/vercel_blob/writer.rs @@ -20,7 +20,10 @@ use std::sync::Arc; use async_trait::async_trait; use http::StatusCode; -use super::core::{InitiateMultipartUploadResponse, Part, UploadPartResponse, VercelBlobCore}; +use super::core::InitiateMultipartUploadResponse; +use super::core::Part; +use super::core::UploadPartResponse; +use super::core::VercelBlobCore; use super::error::parse_error; use crate::raw::*; use crate::*; diff --git a/core/src/services/webdav/core.rs b/core/src/services/webdav/core.rs index 126f1e3f9df8..9f24e5f0609f 100644 --- a/core/src/services/webdav/core.rs +++ b/core/src/services/webdav/core.rs @@ -15,15 +15,21 @@ // specific language governing permissions and limitations // under the License. +use std::collections::VecDeque; +use std::fmt; +use std::fmt::Debug; +use std::fmt::Formatter; + +use bytes::Bytes; +use http::header; +use http::Request; +use http::Response; +use http::StatusCode; +use serde::Deserialize; + use super::error::parse_error; use crate::raw::*; use crate::*; -use bytes::Bytes; -use http::{header, Request, Response, StatusCode}; -use serde::Deserialize; -use std::collections::VecDeque; -use std::fmt; -use std::fmt::{Debug, Formatter}; /// The request to query all properties of a file or directory. /// diff --git a/core/src/services/webdav/lister.rs b/core/src/services/webdav/lister.rs index b69efb61b559..ab9d7c608567 100644 --- a/core/src/services/webdav/lister.rs +++ b/core/src/services/webdav/lister.rs @@ -15,9 +15,10 @@ // specific language governing permissions and limitations // under the License. +use std::sync::Arc; + use async_trait::async_trait; use http::StatusCode; -use std::sync::Arc; use super::core::*; use super::error::*; diff --git a/core/src/services/webdav/writer.rs b/core/src/services/webdav/writer.rs index 72ec6c098e1f..a5e79501e2d9 100644 --- a/core/src/services/webdav/writer.rs +++ b/core/src/services/webdav/writer.rs @@ -15,9 +15,10 @@ // specific language governing permissions and limitations // under the License. +use std::sync::Arc; + use async_trait::async_trait; use http::StatusCode; -use std::sync::Arc; use super::core::*; use super::error::parse_error; diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index f3039c0bf952..dbf18c89d819 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -2003,6 +2003,14 @@ impl Operator { /// Presign an operation for read. /// + /// # Notes + /// + /// ## Extra Options + /// + /// `presign_read` is a wrapper of [`Self::presign_read_with`] without any options. To use + /// extra options like `override_content_disposition`, please use [`Self::presign_read_with`] + /// instead. + /// /// # Example /// /// ```no_run @@ -2036,26 +2044,66 @@ impl Operator { Ok(rp.into_presigned_request()) } - /// Presign an operation for read option described in OpenDAL [RFC-1735][`crate::docs::rfcs::rfc_1735_operation_extension`]. + /// Presign an operation for read with extra options. /// - /// You can pass `OpRead` to this method to specify the content disposition. + /// # Options /// - /// # Example + /// ## `override_content_disposition` + /// + /// Override the [`content-disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header returned by storage services. /// /// ```no_run + /// use std::time::Duration; + /// /// use anyhow::Result; - /// use futures::io; /// use opendal::Operator; - /// use std::time::Duration; /// - /// #[tokio::main] /// async fn test(op: Operator) -> Result<()> { /// let signed_req = op /// .presign_read_with("test.txt", Duration::from_secs(3600)) /// .override_content_disposition("attachment; filename=\"othertext.txt\"") /// .await?; - /// # Ok(()) - /// # } + /// Ok(()) + /// } + /// ``` + /// + /// ## `override_cache_control` + /// + /// Override the [`cache-control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header returned by storage services. + /// + /// ```no_run + /// use std::time::Duration; + /// + /// use anyhow::Result; + /// use opendal::Operator; + /// + /// async fn test(op: Operator) -> Result<()> { + /// let signed_req = op + /// .presign_read_with("test.txt", Duration::from_secs(3600)) + /// .override_cache_control("no-store") + /// .await?; + /// Ok(()) + /// } + /// ``` + /// + /// ## `override_content_type` + /// + /// Override the [`content-type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) header returned by storage services. + /// + /// ```no_run + /// use std::time::Duration; + /// + /// use anyhow::Result; + /// use futures::io; + /// use opendal::Operator; + /// + /// async fn test(op: Operator) -> Result<()> { + /// let signed_req = op + /// .presign_read_with("test.txt", Duration::from_secs(3600)) + /// .override_content_type("text/plain") + /// .await?; + /// Ok(()) + /// } /// ``` pub fn presign_read_with( &self, @@ -2078,19 +2126,27 @@ impl Operator { /// Presign an operation for write. /// + /// # Notes + /// + /// ## Extra Options + /// + /// `presign_write` is a wrapper of [`Self::presign_write_with`] without any options. To use + /// extra options like `content_type`, please use [`Self::presign_write_with`] instead. + /// /// # Example /// /// ```no_run + /// use std::time::Duration; + /// /// use anyhow::Result; - /// use futures::io; /// use opendal::Operator; - /// use std::time::Duration; /// - /// #[tokio::main] /// async fn test(op: Operator) -> Result<()> { - /// let signed_req = op.presign_write("test.txt", Duration::from_secs(3600)).await?; - /// # Ok(()) - /// # } + /// let signed_req = op + /// .presign_write("test.txt", Duration::from_secs(3600)) + /// .await?; + /// Ok(()) + /// } /// ``` /// /// - `signed_req.method()`: `PUT` @@ -2106,29 +2162,80 @@ impl Operator { self.presign_write_with(path, expire).await } - /// Presign an operation for write with option described in OpenDAL [RFC-0661][`crate::docs::rfcs::rfc_0661_path_in_accessor`] + /// Presign an operation for write with extra options. /// - /// You can pass `OpWrite` to this method to specify the content length and content type. + /// # Options /// - /// # Example + /// ## `content_type` + /// + /// Set the [`content-type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) header returned by storage services. /// /// ```no_run + /// use std::time::Duration; + /// /// use anyhow::Result; - /// use futures::io; /// use opendal::Operator; + /// + /// async fn test(op: Operator) -> Result<()> { + /// let signed_req = op + /// .presign_write_with("test", Duration::from_secs(3600)) + /// .content_type("text/csv") + /// .await?; + /// let req = http::Request::builder() + /// .method(signed_req.method()) + /// .uri(signed_req.uri()) + /// .body(())?; + /// + /// Ok(()) + /// } + /// ``` + /// + /// ## `content_disposition` + /// + /// Set the [`content-disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header returned by storage services. + /// + /// ```no_run /// use std::time::Duration; /// - /// #[tokio::main] + /// use anyhow::Result; + /// use opendal::Operator; + /// /// async fn test(op: Operator) -> Result<()> { - /// let signed_req = op.presign_write_with("test", Duration::from_secs(3600)) - /// .content_type("text/csv").await?; + /// let signed_req = op + /// .presign_write_with("test", Duration::from_secs(3600)) + /// .content_disposition("attachment; filename=\"cool.html\"") + /// .await?; /// let req = http::Request::builder() /// .method(signed_req.method()) /// .uri(signed_req.uri()) /// .body(())?; /// - /// # Ok(()) - /// # } + /// Ok(()) + /// } + /// ``` + /// + /// ## `cache_control` + /// + /// Set the [`cache-control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header returned by storage services. + /// + /// ```no_run + /// use std::time::Duration; + /// + /// use anyhow::Result; + /// use opendal::Operator; + /// + /// async fn test(op: Operator) -> Result<()> { + /// let signed_req = op + /// .presign_write_with("test", Duration::from_secs(3600)) + /// .cache_control("no-store") + /// .await?; + /// let req = http::Request::builder() + /// .method(signed_req.method()) + /// .uri(signed_req.uri()) + /// .body(())?; + /// + /// Ok(()) + /// } /// ``` pub fn presign_write_with( &self,