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:42:57 UTC
(opendal) branch main updated: docs: Fix and improve docs for presign operations (#4294)
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git
The following commit(s) were added to refs/heads/main by this push:
new c1927a0522 docs: Fix and improve docs for presign operations (#4294)
c1927a0522 is described below
commit c1927a05227adb1c349ac4addd1348d818fb462c
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Thu Feb 29 11:42:51 2024 +0800
docs: Fix and improve docs for presign operations (#4294)
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,