docs: Fix and improve docs for presign operations (#4294)

Signed-off-by: Xuanwo <[email protected]>
apache · Feb 29, 2024 · c1927a0 · c1927a0
1 parent 5bf4683
commit c1927a0
Show file tree

Hide file tree

Showing 9 changed files with 165 additions and 42 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,