You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2024/02/29 03:22:01 UTC

(opendal) branch fix-docs created (now 6998b6be91)

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

xuanwo pushed a change to branch fix-docs
in repository https://gitbox.apache.org/repos/asf/opendal.git


      at 6998b6be91 docs: Fix and improve docs for presign operations

This branch includes the following new commits:

     new 6998b6be91 docs: Fix and improve docs for presign operations

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.



(opendal) 01/01: docs: Fix and improve docs for presign operations

Posted by xu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch fix-docs
in repository https://gitbox.apache.org/repos/asf/opendal.git

commit 6998b6be91505e9078687a7dc8249a4a8d09873c
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Thu Feb 29 11:21:41 2024 +0800

    docs: Fix and improve docs for presign operations
    
    Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
 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 c0c6790b17..dcf474b184 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 7e128524ce..4d6a36ed3b 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 5fbce6a5ca..ef33a891bc 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 54900dfff8..9fea54d9f9 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 46b8e32b8b..f7f3b90d75 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 126f1e3f9d..9f24e5f060 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 b69efb61b5..ab9d7c6085 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 72ec6c098e..a5e79501e2 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 f3039c0bf9..dbf18c89d8 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,