Aliyun OSS Rust SDK

https://docs.rs/aliyun-oss-rust-sdk/0.2.2
Admin
An official Rust SDK for Alibaba Cloud Object Storage Service (OSS) that provides async and sync...
Tokens:38,310
Snippets:208
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Initialize Logging for Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/url.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the tracing subscriber for logging with DEBUG level and line numbers enabled. This is a common setup for debugging Rust applications. It uses the `tracing` and `tracing_subscriber` crates.

```rust
fn init_log() {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_line_number(true)
        .init();
}
```

--------------------------------

### Generate Signed Upload URL in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/url/trait.UrlApi

Example demonstrating the use of the sign_upload_url method to obtain a pre-signed URL for uploading an object to Aliyun OSS. It shows how to configure content type and expiration time for the upload.

```rust
use aliyun_oss_rust_sdk::oss::{OSS, RequestBuilder};
use aliyun_oss_rust_sdk::url::UrlApi;
let oss = OSS::from_env();//也可以使用OSS::new()方法传递参数
let build = RequestBuilder::new()
   //.with_cdn("https://mydomain.com")
   .with_content_type("text/plain") //设置上传文件的content-type
   .with_expire(60); //60秒链接过期
let upload_url = oss.sign_upload_url(
    "tmp.txt",
    &build
    );
 println!("upload_url: {}", upload_url);
//使用postman测试上传即可, PS:要注意content-type要和build中的一致
```

--------------------------------

### Generate Signed Download URL in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/url/trait.UrlApi

Example of how to use the sign_download_url method from the UrlApi trait to generate a pre-signed URL for downloading an object from Aliyun OSS. It demonstrates setting expiration time and download speed limits.

```rust
use aliyun_oss_rust_sdk::oss::{OSS, RequestBuilder};
use aliyun_oss_rust_sdk::url::UrlApi;
let oss = OSS::from_env();//也可以使用OSS::new()方法传递参数
let build = RequestBuilder::new()
   //.with_cdn("https://mydomain.com")
   .with_expire(60) //60秒链接过期
  .oss_download_speed_limit(30);//限速30kb
let download_url = oss.sign_download_url(
    "/ipas/cn/-10/ipadump.com_imem内存修改器_1.0.0.ipa",
    &build
    );
 println!("download_url: {}", download_url);
```

--------------------------------

### Test File Reading Functionality in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/oss.rs_search=std%3A%3Avec

A Rust test function that verifies the `open_file` function. It calls `open_file` with a dummy file name and unwraps the result, indicating that the file opening process should succeed without panicking.

```rust
fn test_read_file() {
    open_file("a").unwrap();
}
```

--------------------------------

### GET /objects/{key}/metadata

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/async_impl/object.rs_search=u32+-%3E+bool

Retrieves the metadata for a specific object in an Aliyun OSS bucket. This endpoint allows you to get information about an object without downloading its content.

```APIDOC
## GET /objects/{key}/metadata

### Description
Retrieves the metadata for a specific object in an Aliyun OSS bucket. This endpoint allows you to get information about an object without downloading its content.

### Method
HEAD

### Endpoint
/objects/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The path or key of the object in the bucket.

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use aliyun_oss_rust_sdk::oss::OSS;
use aliyun_oss_rust_sdk::request::RequestBuilder;

let oss = OSS::from_env();
let builder = RequestBuilder::new(); // Additional options can be added with .with_expire(), etc.
let metadata = oss.get_object_metadata("/path/to/your/object.txt", builder).await.unwrap();
println!("{:?}", metadata);
```

### Response
#### Success Response (200)
- **ObjectMetadata** (ObjectMetadata) - Contains metadata such as content type, content length, ETag, last modified date, etc.

#### Response Example
```json
{
  "content_type": "text/plain",
  "content_length": 1024,
  "etag": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "last_modified": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Read File Contents in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/oss.rs_search=std%3A%3Avec

This Rust function reads the entire content of a file into a String. It handles potential file opening and reading errors by returning a Result. Dependencies include the standard library's File and Read traits.

```rust
use std::io::Read;

fn open_file(file_name: &str) -> Result<String, std::io::Error> {
    let mut file = std::fs::File::open(file_name)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    Ok(contents)
}
```

--------------------------------

### Sign Download URL using Aliyun OSS SDK in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/url.rs

Demonstrates how to sign a download URL for Aliyun OSS. It initializes the SDK, sets up a request builder with CDN, expiration, and IP restrictions, and then signs the download URL for a specified object.

```rust
init_log();
let oss = OSS::from_env();
let build = RequestBuilder::new()
    .with_cdn("https://cdn.ipadump.com")
    .with_expire(60)
    .oss_download_allow_ip("14.145.28.62", 32);
os.sign_download_url(
    "hello.txt",
    &build,
);
```

--------------------------------

### Sign Upload URL using Aliyun OSS SDK in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/url.rs

Illustrates how to sign an upload URL for Aliyun OSS. This involves initializing the SDK, configuring a request builder with CDN, content type, and expiration, and then signing the upload URL for a temporary object.

```rust
init_log();
let oss = OSS::from_env();
let build = RequestBuilder::new()
    .with_cdn("http://cdn.ipadump.com")
    .with_content_type("text/plain")
    .with_expire(600);
os.sign_upload_url(
    "tmp.txt",
    &build,
);
```

--------------------------------

### Sign Download URL with Rust SDK

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/url.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates signing a download URL for Aliyun OSS using the Rust SDK. It initializes logging, creates an OSS client from environment variables, and configures request options like CDN, expiration, and IP restrictions before signing the URL for a specified object.

```rust
#[test]
fn sign_download_url_test() {
    init_log();
    let oss = OSS::from_env();
    let build = RequestBuilder::new()
        .with_cdn("https://cdn.ipadump.com")
        .with_expire(60)
        .oss_download_allow_ip("14.145.28.62", 32);
    // .oss_download_speed_limit(30);
    oss.sign_download_url(
        "hello.txt",
        // "/ipas/cn/-10/ipadump.com_imem内存修改器_1.0.0.ipa",
        &build,
    );
}
```

--------------------------------

### Sign Upload URL with Rust SDK

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/url.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to sign an upload URL for Aliyun OSS using the Rust SDK. It sets up logging, obtains an OSS client, and configures request parameters such as CDN, content type, and expiration time before signing the upload URL for a temporary file.

```rust
#[test]
fn sign_upload_url_test() {
    init_log();
    let oss = OSS::from_env();
    let build = RequestBuilder::new()
        .with_cdn("http://cdn.ipadump.com")
        .with_content_type("text/plain")
        .with_expire(600);
    oss.sign_upload_url(
        "tmp.txt",
        &build,
    );
}
```

--------------------------------

### OSS Client Initialization and Debugging in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/oss.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods for initializing the `OSS` client from environment variables (`from_env`) or directly with credentials (`new`). It also includes functionality to enable debug logging for the SDK using the `open_debug` method, which is conditionally compiled based on the `debug-print` feature.

```rust
impl<'a> OSS {
   pub fn from_env() -> Self {
       let key_id = std::env::var("OSS_KEY_ID").expect("OSS_KEY_ID not found");
       let key_secret = std::env::var("OSS_KEY_SECRET").expect("OSS_KEY_SECRET not found");
       let endpoint = std::env::var("OSS_ENDPOINT").expect("OSS_ENDPOINT not found");
       let bucket = std::env::var("OSS_BUCKET").expect("OSS_BUCKET not found");
       OSS::new(key_id, key_secret, endpoint, bucket)
   }

   #[cfg(feature = "debug-print")]
   pub fn open_debug(&self) {
       unsafe{std::env::set_var("RUST_LOG", "oss=debug")};
       tracing_subscriber::fmt()
           .with_max_level(tracing::Level::DEBUG)
           .with_line_number(true)
           .init();
   }
   #[cfg(not(feature = "debug-print"))]
   pub fn open_debug(&self) {}
   pub fn new<S: Into<String>>(key_id: S, key_secret: S, endpoint: S, bucket: S) -> Self {
       OSS {
           key_id: key_id.into(),
           key_secret: key_secret.into(),
           endpoint: endpoint.into(),
           bucket: bucket.into(),
       }
   }
}
```

--------------------------------

### Define SDK Modules in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/lib.rs

This Rust code snippet defines the main modules for the aliyun-oss-rust-sdk. It includes directives for including the README file as documentation and publicly exposes modules for authentication, OSS operations, request handling, URL management, metadata, asynchronous implementation, entities, errors, and utility macros.

```rust
#![doc = include_str!("../README.md")]
pub mod auth;
pub mod oss;
pub mod request;
pub mod url;
pub mod metadata;
mod util;
pub mod async_impl;
pub mod entity;
pub mod error;
pub(crate) mod macros;
```

--------------------------------

### Define RequestType Enum in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/enum.RequestType_search=

This Rust code defines an enum `RequestType` used to represent different types of HTTP requests (GET, PUT, POST, DELETE, HEAD) for interacting with Aliyun OSS. It is a fundamental part of the SDK's request handling.

```rust
pub enum RequestType {
    Get,
    Put,
    Post,
    Delete,
    Head,
}
```

--------------------------------

### RequestBuilder Debug and Default Implementations - Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder

Provides implementations for `Debug` and `Default` traits for `RequestBuilder`. The `Debug` trait allows the struct to be formatted for debugging output, while `Default` provides a way to create a builder with its default values. This aids in testing and initial setup.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
fn default() -> Self
```

--------------------------------

### RequestBuilder Initialization and Configuration Methods - Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods for initializing and configuring a RequestBuilder. These include creating a new builder, setting HTTP or HTTPS, configuring CDN, content type, expiration, response headers, and OSS-specific settings like signature version and download limits.

```rust
pub fn new() -> Self
pub fn with_http(self) -> Self
pub fn with_cdn<S: AsRef<str>>(self, cdn: S) -> Self
pub fn with_content_type<S: AsRef<str>>(self, content_type: S) -> Self
pub fn with_expire(self, expire: Seconds) -> Self
pub fn response_content_disposition<S: AsRef<str>>(self, file_name: S) -> Self
pub fn oss_signature_version2(self) -> Self
pub fn response_content_encoding<S: AsRef<String>>(self, encoding: S) -> Self
pub fn oss_download_speed_limit<S: Into<i32>>(self, speed: S) -> Self
pub fn oss_download_allow_ip<IP, S>(self, ip: IP, mask: S) -> Self
where IP: AsRef<str>, S: Into<u8>,
pub fn oss_ac_allow(self) -> Self
pub fn oss_header_put<S: AsRef<str>>(self, key: S, value: S) -> Self
pub fn parameters_put<S: AsRef<str>>(self, key: S, value: S) -> Self
```

--------------------------------

### Checking Type Equivalence with Generic Parameters in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/entity/struct.PolicyResp_search=u32+-%3E+bool

Demonstrates how the `equivalent` method in Rust's `aliyun-oss-rust-sdk` checks for type equivalence, particularly when dealing with generic parameters like `K`. It flags a potential issue where `u32` might not be found and suggests `i32` as a possible substitute when `u32` is expected to match a generic type `K`.

```rust
use aliyun_oss_rust_sdk::request::RequestType;

// Example usage demonstrating the context of the 'equivalent' method.
// This is illustrative and assumes a scenario where type checking is performed.
let req_type_a = RequestType::PutObject;
let req_type_b = RequestType::GetObject;

// The 'equivalent' method would be called internally or explicitly,
// potentially encountering the type issue described in the analysis.
// For instance, if K is constrained to u32 and a mismatch occurs:
// if K: TryInto<u32> { ... }
```

--------------------------------

### Request Building and Signing in Rust for Aliyun OSS

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/oss.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Implements methods for formatting the host URL (`format_host`) based on CDN or endpoint configurations, and for constructing the complete HTTP request, including headers and authorization signatures (`build_request`). It also includes a helper for generating the current date string in the required format (`date`).

```rust
pub fn format_host<S: AsRef<str>>(&self, bucket: S, key: S, build: &RequestBuilder) -> String {
   let key = if key.as_ref().starts_with("/") {
       key.as_ref().to_string()
   } else {
       format!("/{{}}", key.as_ref())
   };
   if let Some(cdn) = &build.cdn {
       format!("{{}}{{}}", cdn, key,)
   } else {
       if self.endpoint().starts_with("https") {
           format!(
               "https://{{}}.{{}}",
               bucket.as_ref(),
               self.endpoint().replacen("https://", "", 1),
               key,
           )
       } else {
           format!(
               "http://{{}}.{{}}",
               bucket.as_ref(),
               self.endpoint().replacen("http://", "", 1),
               key,
           )
       }
   }
}

pub fn build_request<S: AsRef<str>>(
   &self,
   key: S,
   build: RequestBuilder,
) -> Result<(String, HeaderMap), InvalidHeaderValue> {
   let mut build = build.clone();
   let host = self.format_host(self.bucket(), key.as_ref().to_string(), &build);
   let mut header = HeaderMap::new();
   let date = self.date();
   header.insert(DATE, date.parse()?);
   build.headers.insert(DATE.to_string(), date);
   let key = key.as_ref();
   let authorization = self.oss_sign(key, &build);
   if let Some(content_type) = build.content_type {
       header.insert(CONTENT_TYPE, content_type.parse()?);
   }
   header.insert(AUTHORIZATION, authorization.parse()?);
   Ok((host, header))
}
pub fn date(&self) -> String {
   let now: DateTime<Utc> = Utc::now();
   now.format("%a, %d %b %Y %T GMT").to_string()
}
```

--------------------------------

### Define and Implement RequestType Enum in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/request.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines an enum `RequestType` to represent HTTP request methods (GET, PUT, POST, DELETE, HEAD). It implements the `Display` trait for easy conversion to string representations and is marked as `Send` and `Sync` for thread safety.

```rust
use std::collections::HashMap;
use std::fmt::{Display, Formatter};

pub type Seconds = i64;

#[derive(PartialEq, Eq, Clone, Debug)]
pub enum RequestType {
    Get,
    Put,
    Post,
    Delete,
    Head,
}

impl Display for RequestType{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            RequestType::Get => write!(f, "GET"),
            RequestType::Put => write!(f, "PUT"),
            RequestType::Post => write!(f, "POST"),
            RequestType::Delete => write!(f, "DELETE"),
            RequestType::Head => write!(f, "HEAD"),
        }
    }
}

unsafe impl Send for RequestType {}
unsafe impl Sync for RequestType {}

```

--------------------------------

### Implement new() for PolicyBuilder in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/entity/struct.PolicyBuilder_search=

Provides a constructor for creating a new instance of PolicyBuilder. This is a fundamental method for initializing the policy building process within the aliyun-oss-rust-sdk.

```rust
pub fn new() -> Self
```

--------------------------------

### Get Object Metadata in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/async_impl/object.rs_search=u32+-%3E+bool

Retrieves the metadata for a specified object in Aliyun OSS. It uses a `RequestBuilder` to configure request options like expiration time. This function sends a HEAD request to the OSS endpoint and parses the response headers to extract metadata. Dependencies include the `aliyun-oss-rust-sdk` and `tokio` for async operations.

```rust
use aliyun_oss_rust_sdk::oss::OSS;
use aliyun_oss_rust_sdk::request::RequestBuilder;

// Assuming OSS::from_env() and RequestBuilder::new() are configured elsewhere
// let oss = OSS::from_env();
// let builder = RequestBuilder::new()
//    .with_expire(60);
// let metadata = oss.get_object_metadata("/hello.txt", builder).await.unwrap();
// println!("{:?}", metadata);

pub async fn get_object_metadata<S: AsRef<str>>(&self, key: S, build: RequestBuilder) -> Result<ObjectMetadata, OssError>{
    let mut build = build.clone();
    build.method = RequestType::Head;
    let key = self.format_key(key);
    let (url, headers) = self.build_request(key.as_str(), build)
        .map_err(|e| OssError::Err(format!("build request error: {}", e)))?;
    debug!("put object from file: {} headers: {:?}", url,headers);
    let client = Client::new();
    let response = client.head(url)
        .headers(headers)
        .send()
        .await?;
    if response.status().is_success() {
        let metadata = ObjectMetadata::new(response.headers());
        Ok(metadata)
    } else {
        let status = response.status();
        let result = response.text().await?;
        debug!("get object status: {} error: {}", status,result);
        Err(OssError::Err(format!("get object status: {} error: {}", status, result)))
    }
}
```

--------------------------------

### Rust Methods for RequestBuilder Initialization and Configuration

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder_search=std%3A%3Avec

Provides core methods for initializing and configuring a RequestBuilder. Includes creating a new builder, setting HTTP/HTTPS, adding CDN information, content type, expiration, and response disposition.

```rust
pub fn new() -> Self
```

```rust
pub fn with_http(self) -> Self
```

```rust
pub fn with_cdn<S: AsRef<str>>(self, cdn: S) -> Self
```

```rust
pub fn with_content_type<S: AsRef<str>>(self, content_type: S) -> Self
```

```rust
pub fn with_expire(self, expire: Seconds) -> Self
```

```rust
pub fn response_content_disposition<S: AsRef<str>>(self, file_name: S) -> Self
```

--------------------------------

### OSS Client Configuration and Initialization (Rust)

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/oss.rs

Defines the `OSS` struct for storing Aliyun OSS credentials and configuration. It includes a `new` constructor and a `from_env` function to initialize the client using environment variables.

```rust
/// OSS配置
#[derive(Debug, Clone)]
pub struct OSS {
    key_id: String,
    key_secret: String,
    endpoint: String,
    bucket: String,
}

unsafe impl Send for OSS {}

unsafe impl Sync for OSS {}

pub trait OSSInfo {
    fn endpoint(&self) -> String;
    fn bucket(&self) -> String;
    fn key_id(&self) -> String;
    fn key_secret(&self) -> String;
}

impl OSSInfo for OSS {
    fn endpoint(&self) -> String {
        self.endpoint.clone()
    }
    fn bucket(&self) -> String {
        self.bucket.clone()
    }

    fn key_id(&self) -> String {
        self.key_id.clone()
    }

    fn key_secret(&self) -> String {
        self.key_secret.clone()
    }
}

impl<'a> OSS {
    pub fn from_env() -> Self {
        let key_id = std::env::var("OSS_KEY_ID").expect("OSS_KEY_ID not found");
        let key_secret = std::env::var("OSS_KEY_SECRET").expect("OSS_KEY_SECRET not found");
        let endpoint = std::env::var("OSS_ENDPOINT").expect("OSS_ENDPOINT not found");
        let bucket = std::env::var("OSS_BUCKET").expect("OSS_BUCKET not found");
        OSS::new(key_id, key_secret, endpoint, bucket)
    }

    pub fn new<S: Into<String>>(key_id: S, key_secret: S, endpoint: S, bucket: S) -> Self {
        OSS {
            key_id: key_id.into(),
            key_secret: key_secret.into(),
            endpoint: endpoint.into(),
            bucket: bucket.into(),
        }
    }
}
```

--------------------------------

### AuthAPI

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/auth/trait.AuthAPI_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods for signing requests with Aliyun OSS.

```APIDOC
## Trait AuthAPI

### Description
This trait defines the authentication methods required for interacting with Aliyun OSS.

### Methods

#### `fn sign<S: AsRef<str>>(&self, object: S, build: &RequestBuilder) -> String`

*   **Description**: Signs a request for a given object using the specified `RequestBuilder`.
*   **Parameters**:
    *   `object` (String) - The object key or path to sign.
    *   `build` (RequestBuilder) - The request builder containing details for signing.
*   **Returns**: A signed string.

#### `fn oss_sign<S: AsRef<str>>(&self, object: S, build: &RequestBuilder) -> String`

*   **Description**: An alternative signing method for Aliyun OSS requests.
*   **Parameters**:
    *   `object` (String) - The object key or path to sign.
    *   `build` (RequestBuilder) - The request builder containing details for signing.
*   **Returns**: A signed string.

### Dyn Compatibility
This trait is **not** dyn compatible.
```

--------------------------------

### Rust Methods for OSS Specific Configurations in RequestBuilder

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder_search=std%3A%3Avec

Details methods for applying Aliyun OSS-specific configurations to the RequestBuilder. This includes setting signature version, response content encoding, download speed limits, allowed IPs, and custom OSS headers.

```rust
pub fn oss_signature_version2(self) -> Self
```

```rust
pub fn response_content_encoding<S: AsRef<String>>(self, encoding: S) -> Self
```

```rust
pub fn oss_download_speed_limit<S: Into<i32>>(self, speed: S) -> Self
```

```rust
pub fn oss_download_allow_ip<IP, S>(self, ip: IP, mask: S) -> Self
where IP: AsRef<str>,
S: Into<u8>,
```

```rust
pub fn oss_ac_forward_allow(self) -> Self
```

```rust
pub fn oss_header_put<S: AsRef<str>>(self, key: S, value: S) -> Self
```

--------------------------------

### RequestBuilder Constructor and Configuration Methods

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder_search=u32+-%3E+bool

Provides methods for creating and configuring a RequestBuilder instance. These include initializing a new builder, setting HTTP or HTTPS, configuring CDN, content type, expiration, response disposition, signature version, and IP-based access control.

```rust
pub fn new() -> Self

pub fn with_http(self) -> Self

pub fn with_cdn<S: AsRef<str>>(self, cdn: S) -> Self

pub fn with_content_type<S: AsRef<str>>(self, content_type: S) -> Self

pub fn with_expire(self, expire: Seconds) -> Self

pub fn response_content_disposition<S: AsRef<str>>(self, file_name: S) -> Self

pub fn oss_signature_version2(self) -> Self

pub fn response_content_encoding<S: AsRef<String>>(self, encoding: S) -> Self

pub fn oss_download_speed_limit<S: Into<i32>>(self, speed: S) -> Self

pub fn oss_download_allow_ip<IP, S>(self, ip: IP, mask: S) -> Self
where IP: AsRef<str>, S: Into<u8>,

pub fn oss_ac_forward_allow(self) -> Self

pub fn oss_header_put<S: AsRef<str>>(self, key: S, value: S) -> Self

pub fn parameters_put<S: AsRef<str>>(self, key: S, value: S) -> Self
```

--------------------------------

### RequestBuilder Initialization and Configuration Methods - Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder

Provides methods for creating and configuring a `RequestBuilder`. These methods allow setting the HTTP method, CDN, content type, expiry, response disposition, signature version, encoding, download speed limits, allowed IPs, and custom OSS headers or parameters. They return a mutable reference to the `RequestBuilder` for chaining.

```rust
pub fn new() -> Self
pub fn with_http(self) -> Self
pub fn with_cdn<S: AsRef<str>>(self, cdn: S) -> Self
pub fn with_content_type<S: AsRef<str>>(self, content_type: S) -> Self
pub fn with_expire(self, expire: Seconds) -> Self
pub fn response_content_disposition<S: AsRef<str>>(self, file_name: S) -> Self
pub fn oss_signature_version2(self) -> Self
pub fn response_content_encoding<S: AsRef<String>>(self, encoding: S) -> Self
pub fn oss_download_speed_limit<S: Into<i32>>(self, speed: S) -> Self
pub fn oss_download_allow_ip<IP, S>(self, ip: IP, mask: S) -> Self
where IP: AsRef<str>,
S: Into<u8>,
pub fn oss_ac_forward_allow(self) -> Self
pub fn oss_header_put<S: AsRef<str>>(self, key: S, value: S) -> Self
pub fn parameters_put<S: AsRef<str>>(self, key: S, value: S) -> Self
```

--------------------------------

### RequestBuilder Configuration API

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/request.rs_search=std%3A%3Avec

This section covers the methods available on the `RequestBuilder` struct to configure various aspects of an Aliyun OSS request, such as setting the HTTP method, adding headers, specifying query parameters, and configuring OSS-specific options.

```APIDOC
## RequestBuilder Methods

### Description
Methods for configuring HTTP requests for Aliyun Object Storage Service (OSS) using the Rust SDK.

### Method
N/A (These are builder methods)

### Endpoint
N/A

### Parameters
This section describes the various configuration methods available on the `RequestBuilder` struct.

#### `new()`
- **Description**: Creates a new `RequestBuilder` with default settings.

#### `with_http()`
- **Description**: Configures the request to use HTTP instead of HTTPS.

#### `with_cdn(cdn: S)` where `S: AsRef<str>`
- **Description**: Sets a CDN for the request.
- **Parameters**:
  - **cdn** (string) - The CDN to use.

#### `with_content_type(content_type: S)` where `S: AsRef<str>`
- **Description**: Sets the `Content-Type` header for the request.
- **Parameters**:
  - **content_type** (string) - The content type.

#### `with_expire(expire: Seconds)`
- **Description**: Sets the expiration time for the request in seconds.
- **Parameters**:
  - **expire** (Seconds) - The expiration time in seconds.

#### `response_content_disposition(file_name: S)` where `S: AsRef<str>`
- **Description**: Sets the `response-content-disposition` parameter to control how the response content is presented (e.g., for file downloads).
- **Parameters**:
  - **file_name** (string) - The filename to suggest for the download.

#### `oss_signature_version2()`
- **Description**: Sets the OSS signature version to "OSS2".

#### `response_content_encoding(encoding: S)` where `S: AsRef<String>`
- **Description**: Sets the `response-content-encoding` parameter.
- **Parameters**:
  - **encoding** (string) - The content encoding to specify.

#### `oss_download_speed_limit(speed: S)` where `S: Into<i32>`
- **Description**: Sets the OSS traffic limit for downloads in KB/s. The speed must be greater than 30 KB/s.
- **Parameters**:
  - **speed** (integer) - The download speed limit in KB/s.

#### `oss_download_allow_ip(ip: IP, mask: S)` where `IP: AsRef<str>, S: Into<u8>`
- **Description**: Configures IP access control for downloads, specifying the allowed IP address and subnet mask.
- **Parameters**:
  - **ip** (string) - The allowed IP address.
  - **mask** (integer) - The subnet mask.

#### `oss_ac_forward_allow()`
- **Description**: Enables forwarding for Access Control (AC).

#### `oss_header_put(key: S, value: S)` where `S: AsRef<str>`
- **Description**: Adds a custom OSS header to the request.
- **Parameters**:
  - **key** (string) - The header key.
  - **value** (string) - The header value.

#### `parameters_put(key: S, value: S)` where `S: AsRef<str>`
- **Description**: Adds a custom query parameter to the request.
- **Parameters**:
  - **key** (string) - The parameter key.
  - **value** (string) - The parameter value.

### Request Example
```rust
use aliyun_oss_rust_sdk::request::{RequestBuilder, RequestType, Seconds};

let request = RequestBuilder::new()
    .with_http()
    .with_cdn("mycdn.com")
    .with_content_type("application/xml")
    .with_expire(300 as Seconds)
    .response_content_disposition("my_document.pdf")
    .oss_signature_version2()
    .response_content_encoding("utf-8")
    .oss_download_speed_limit(1024)
    .oss_download_allow_ip("192.168.1.1", 24)
    .oss_ac_forward_allow()
    .oss_header_put("x-oss-meta-custom", "custom-value")
    .parameters_put("custom-param", "param-value")
    .method = RequestType::Get;
```

### Response
N/A (These are builder methods, the actual request is made separately)

```

--------------------------------

### PolicyBuilder Constructor Methods (Rust)

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/entity/struct.PolicyBuilder

Provides methods to construct and configure a PolicyBuilder instance. These methods allow setting expiration, upload directory, content type, and maximum upload size, facilitating the creation of OSS policies.

```rust
pub fn new() -> Self
```

```rust
pub fn with_expire(self, expire: Seconds) -> Self
```

```rust
pub fn with_upload_dir<S: AsRef<str>>(self, upload_dir: S) -> Self
```

```rust
pub fn with_content_type<S: AsRef<str>>(self, content_type: S) -> Self
```

```rust
pub fn with_max_upload_size(self, max_upload_size: i64) -> Self
```

--------------------------------

### AuthAPI Methods

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/auth/trait.AuthAPI_search=std%3A%3Avec

This section details the methods available within the AuthAPI trait, which are used for signing OSS requests.

```APIDOC
## AuthAPI

### Description
Provides authentication and signing functionalities for Aliyun OSS requests.

### Methods

#### `sign<S: AsRef<str>>(&self, object: S, build: &RequestBuilder) -> String`

##### Description
Signs an OSS request object.

##### Method
`sign` (part of the `AuthAPI` trait)

##### Parameters

###### Path Parameters
None

###### Query Parameters
None

###### Request Body
None

##### Request Example
```rust
// This is a conceptual example, actual usage depends on the context of RequestBuilder
// let oss_client: OSS = ...;
// let request_builder: RequestBuilder = ...;
// let signature = oss_client.sign("my-object.txt", &request_builder);
```

##### Response

###### Success Response (String)
- Returns a signed string representing the request.

###### Response Example
```json
"<signed_string>"
```

#### `oss_sign<S: AsRef<str>>(&self, object: S, build: &RequestBuilder) -> String`

##### Description
Performs a specific OSS signing operation.

##### Method
`oss_sign` (part of the `AuthAPI` trait)

##### Parameters

###### Path Parameters
None

###### Query Parameters
None

###### Request Body
None

##### Request Example
```rust
// This is a conceptual example, actual usage depends on the context of RequestBuilder
// let oss_client: OSS = ...;
// let request_builder: RequestBuilder = ...;
// let signature = oss_client.oss_sign("my-object.txt", &request_builder);
```

##### Response

###### Success Response (String)
- Returns a signed string specific to the oss_sign operation.

###### Response Example
```json
"<oss_signed_string>"
```

### Trait Information

- **Dyn Compatibility**: This trait is **not** dyn compatible.
```

--------------------------------

### RequestBuilder Configuration

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/request.rs_search=

This section details the methods available for configuring a request using the RequestBuilder. It covers setting the HTTP method, CDN options, timeouts, content types, and various OSS-specific headers and parameters.

```APIDOC
## RequestBuilder API Documentation

### Description
The `RequestBuilder` struct allows for the fluent construction of requests to the Aliyun OSS service. It provides methods to configure the HTTP method, specify CDN usage, set expiration times, add custom headers, define query parameters, and apply OSS-specific configurations.

### Methods

- **`new()`**: Creates a new `RequestBuilder` with default settings.
- **`with_http()`**: Configures the request to use HTTP instead of HTTPS.
- **`with_cdn<S: AsRef<str>>(cdn: S)`**: Specifies a custom CDN domain for the request.
- **`with_content_type<S: AsRef<str>>(content_type: S)`**: Sets the `Content-Type` header for the request.
- **`with_expire(expire: Seconds)`**: Sets the expiration time for the request in seconds.
- **`response_content_disposition<S: AsRef<str>>(file_name: S)`**: Sets the `response-content-disposition` parameter to control download behavior.
- **`oss_signature_version2()`**: Enables OSS signature version 2.
- **`response_content_encoding<S: AsRef<String>>(encoding: S)`**: Sets the `response-content-encoding` parameter.
- **`oss_download_speed_limit<S: Into<i32>>(speed: S)`**: Sets the download speed limit in KB/s (must be >= 30).
- **`oss_download_allow_ip<IP: AsRef<str>, S: Into<u8>>(ip: IP, mask: S)`**: Configures allowed IP addresses and subnet masks for OSS access.
- **`oss_ac_forward_allow()`**: Enables forwarding of the `X-Forwarded-For` header.
- **`oss_header_put<S: AsRef<str>>(key: S, value: S)`**: Adds a custom OSS header.
- **`parameters_put<S: AsRef<str>>(key: S, value: S)`**: Adds a custom query parameter.

### Default Values
- `https`: `true`
- `method`: `RequestType::Get`
- `expire`: `60` seconds
- `headers`: Empty HashMap
- `parameters`: Empty HashMap
- `oss_headers`: Empty HashMap

### Example Usage
```rust
use aliyun_oss_rust_sdk::request::{RequestBuilder, RequestType, Seconds};

let mut request_builder = RequestBuilder::new()
    .with_content_type("application/xml")
    .with_expire(300)
    .response_content_disposition("my-file.txt")
    .oss_header_put("x-oss-meta-custom-key", "custom-value");

// You can then build the actual request object from this builder
```
```

--------------------------------

### Sign Upload URL for Aliyun OSS in Rust

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/oss/struct.OSS

Generates a signed URL for uploading objects to Aliyun OSS. This function requires the object key and a RequestBuilder for configuration. It returns a String representing the signed URL.

```rust
fn sign_upload_url<S: AsRef<str>>( &self, key: S, build: &RequestBuilder, ) -> String
```

--------------------------------

### OSS Request Building and Signing (Rust)

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/src/aliyun_oss_rust_sdk/oss.rs

Implements methods for building HTTP requests for Aliyun OSS, including formatting the host with CDN support, generating the current date in GMT format, and creating the authorization signature.

```rust
use crate::request::RequestBuilder;
use chrono::{DateTime, Utc};
use reqwest::header::{HeaderMap, InvalidHeaderValue, AUTHORIZATION, CONTENT_TYPE, DATE};

impl<'a> OSS {
    #[cfg(feature = "debug-print")]
    pub fn open_debug(&self) {
        unsafe{std::env::set_var("RUST_LOG", "oss=debug")};
        tracing_subscriber::fmt()
            .with_max_level(tracing::Level::DEBUG)
            .with_line_number(true)
            .init();
    }
    #[cfg(not(feature = "debug-print"))]
    pub fn open_debug(&self) {}

    pub fn format_host<S: AsRef<str>>(&self, bucket: S, key: S, build: &RequestBuilder) -> String {
        let key = if key.as_ref().starts_with("/") {
            key.as_ref().to_string()
        } else {
            format!("/<!-- -->{}", key.as_ref())
        };
        if let Some(cdn) = &build.cdn {
            format!("{}{}", cdn, key,)
        } else {
            if self.endpoint().starts_with("https") {
                format!(
                    "https://{}.{}{}",
                    bucket.as_ref(),
                    self.endpoint().replacen("https://", "", 1),
                    key,
                )
            } else {
                format!(
                    "http://{}.{}{}",
                    bucket.as_ref(),
                    self.endpoint().replacen("http://", "", 1),
                    key,
                )
            }
        }
    }

    pub fn build_request<S: AsRef<str>>(
        &self,
        key: S,
        build: RequestBuilder,
    ) -> Result<(String, HeaderMap), InvalidHeaderValue> {
        let mut build = build.clone();
        let host = self.format_host(self.bucket(), key.as_ref().to_string(), &build);
        let mut header = HeaderMap::new();
        let date = self.date();
        header.insert(DATE, date.parse()?);
        build.headers.insert(DATE.to_string(), date);
        let key = key.as_ref();
        let authorization = self.oss_sign(key, &build);
        if let Some(content_type) = build.content_type {
            header.insert(CONTENT_TYPE, content_type.parse()?);
        }
        header.insert(AUTHORIZATION, authorization.parse()?);
        Ok((host, header))
    }
    pub fn date(&self) -> String {
        let now: DateTime<Utc> = Utc::now();
        now.format("%a, %d %b %Y %T GMT").to_string()
    }
}
```

--------------------------------

### RequestBuilder Structure and Initialization

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/request/struct.RequestBuilder_search=std%3A%3Avec

This section details the fields of the RequestBuilder struct and how to create a new instance.

```APIDOC
## Struct RequestBuilder

### Description
Used to construct requests for Aliyun OSS.

### Fields
- **cdn**: `Option<String>` - CDN configuration.
- **https**: `bool` - Whether to use HTTPS.
- **method**: `RequestType` - The HTTP method for the request.
- **expire**: `Seconds` - Expiration time in seconds.
- **headers**: `HashMap<String, String>` - Custom headers.
- **parameters**: `HashMap<String, String>` - Query parameters.
- **content_type**: `Option<String>` - Content-Type header.
- **content_md5**: `Option<String>` - Content-MD5 header.
- **oss_headers**: `HashMap<String, String>` - Custom OSS headers.

### Methods
#### `new()`
- **Description**: Creates a new `RequestBuilder` instance.
- **Returns**: `Self` (a new RequestBuilder)

#### `with_http()`
- **Description**: Configures the request to use HTTP instead of HTTPS.
- **Returns**: `Self` (the modified RequestBuilder)

#### `with_cdn<S: AsRef<str>>(cdn: S)`
- **Description**: Sets the CDN configuration for the request.
- **Parameters**:
  - **cdn** (`S` where `S: AsRef<str>`) - The CDN string.
- **Returns**: `Self` (the modified RequestBuilder)

#### `with_content_type<S: AsRef<str>>(content_type: S)`
- **Description**: Sets the Content-Type header for the request.
- **Parameters**:
  - **content_type** (`S` where `S: AsRef<str>`) - The content type string.
- **Returns**: `Self` (the modified RequestBuilder)

#### `with_expire(expire: Seconds)`
- **Description**: Sets the expiration time for the request.
- **Parameters**:
  - **expire** (`Seconds`) - The expiration time in seconds.
- **Returns**: `Self` (the modified RequestBuilder)

#### `response_content_disp`osition<S: AsRef<str>>(file_name: S)`
- **Description**: Sets the `Content-Disposition` header for the response, typically used for file downloads.
- **Parameters**:
  - **file_name** (`S` where `S: AsRef<str>`) - The desired file name for the download.
- **Returns**: `Self` (the modified RequestBuilder)

#### `oss_signature_version2()`
- **Description**: Configures the request to use OSS signature version 2.
- **Returns**: `Self` (the modified RequestBuilder)

#### `response_content_encoding<S: AsRef<String>>(encoding: S)`
- **Description**: Sets the `Content-Encoding` header for the response.
- **Parameters**:
  - **encoding** (`S` where `S: AsRef<String>`) - The content encoding string.
- **Returns**: `Self` (the modified RequestBuilder)

#### `oss_download_speed_limit<S: Into<i32>>(speed: S)`
- **Description**: Sets a speed limit for OSS downloads.
- **Parameters**:
  - **speed** (`S` where `S: Into<i32>`) - The speed limit in bytes per second.
- **Returns**: `Self` (the modified RequestBuilder)

#### `oss_download_allow_ip<IP, S>(ip: IP, mask: S)`
- **Description**: Allows specific IP addresses to download content, with an optional subnet mask.
- **Generic Parameters**:
  - **IP**: `IP: AsRef<str>`
  - **S**: `S: Into<u8>`
- **Parameters**:
  - **ip** (`IP`) - The IP address or range.
  - **mask** (`S`) - The subnet mask (as a value convertible to `u8`).
- **Returns**: `Self` (the modified RequestBuilder)

#### `oss_ac_forward_allow()`
- **Description**: Allows Access Control forward requests.
- **Returns**: `Self` (the modified RequestBuilder)

#### `oss_header_put<S: AsRef<str>>(key: S, value: S)`
- **Description**: Adds a custom OSS header to the request.
- **Parameters**:
  - **key** (`S` where `S: AsRef<str>`) - The header key.
  - **value** (`S` where `S: AsRef<str>`) - The header value.
- **Returns**: `Self` (the modified RequestBuilder)

#### `parameters_put<S: AsRef<str>>(key: S, value: S)`
- **Description**: Adds a query parameter to the request.
- **Parameters**:
  - **key** (`S` where `S: AsRef<str>`) - The parameter key.
  - **value** (`S` where `S: AsRef<str>`) - The parameter value.
- **Returns**: `Self` (the modified RequestBuilder)
```

--------------------------------

### API Trait Documentation

Source: https://docs.rs/aliyun-oss-rust-sdk/0.2.2/aliyun_oss_rust_sdk/oss/trait.API

Documentation for the `API` trait, including required and provided methods.

```APIDOC
## Trait: API

This trait defines the core API for interacting with Aliyun OSS.

### Required Methods

#### fn format_oss_resource_str<S: AsRef<str>>(&self, bucket: S, key: S) -> String

**Description**: Formats an OSS resource string with the given bucket and key.

**Method**: (Implied by trait)

**Endpoint**: N/A (This is a Rust trait method, not an HTTP endpoint)

**Parameters**:

*   **bucket** (S: AsRef<str>) - The name of the OSS bucket.
*   **key** (S: AsRef<str>) - The key of the object within the bucket.

**Response**:

*   **Success Response**:
    *   `String` - The formatted OSS resource string.

### Provided Methods

#### fn key_urlencode<S: AsRef<str>>(&self, key: S) -> String

**Description**: URL-encodes the given key.

**Method**: (Implied by trait)

**Endpoint**: N/A (This is a Rust trait method, not an HTTP endpoint)

**Parameters**:

*   **key** (S: AsRef<str>) - The key to URL-encode.

**Response**:

*   **Success Response**:
    *   `String` - The URL-encoded key.

#### fn format_key<S: AsRef<str>>(&self, key: S) -> String

**Description**: Formats the given key.

**Method**: (Implied by trait)

**Endpoint**: N/A (This is a Rust trait method, not an HTTP endpoint)

**Parameters**:

*   **key** (S: AsRef<str>) - The key to format.

**Response**:

*   **Success Response**:
    *   `String` - The formatted key.

### Dyn Compatibility

This trait is **not** dyn compatible (not object safe).
```
Tokens:
Raw