Struct SignedUrlBuilder 

pub struct SignedUrlBuilder { /* private fields */ }

Creates Signed URLs.

This builder allows you to generate signed URLs for Google Cloud Storage objects and buckets. Signed URLs provide a way to give time-limited read or write access to specific resources without sharing your credentials.

This implementation uses the V4 signing process.

Example: Generating a Signed URL

Generating a Signed URL for Downloading an Object (GET)

use std::time::Duration;
use google_cloud_auth::signer::Signer;
let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
    .with_method(http::Method::GET)
    .with_expiration(Duration::from_secs(3600)) // 1 hour
    .sign_with(signer)
    .await?;

println!("Signed URL: {}", url);

Generating a Signed URL for Uploading an Object (PUT)

use std::time::Duration;

let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
    .with_method(http::Method::PUT)
    .with_expiration(Duration::from_secs(3600)) // 1 hour
    .with_header("content-type", "application/json") // Optional: Enforce content type
    .sign_with(signer)
    .await?;

println!("Upload URL: {}", url);

Example: Creating a Signer

You can use google-cloud-auth to create a Signer.

Using Application Default Credentials (ADC)

This is the recommended way for most applications. It automatically finds credentials from the environment. See how Application Default Credentials works.

use google_cloud_auth::credentials::Builder;
use google_cloud_auth::signer::Signer;

let signer = Builder::default().build_signer()?;

Using a Service Account Key File

This is useful when you have a specific service account key file (JSON) and want to use it directly. Service account based signers work by local signing and do not make network requests, which can be useful in environments where network access is restricted and performance is critical.

Caution: Service account keys are a security risk if not managed correctly. See Best practices for managing service account keys for more information.

use google_cloud_auth::credentials::service_account::Builder;
use google_cloud_auth::signer::Signer;

let service_account_key = serde_json::json!({ /* add details here */ });

let signer = Builder::new(service_account_key).build_signer()?;

Implementations

impl SignedUrlBuilder

pub fn for_object<B, O>(bucket: B, object: O) -> Self

where B: Into<String>, O: Into<String>,

Creates a new SignedUrlBuilder for a specific object.

Example

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .sign_with(signer)
        .await?;
}

pub fn for_bucket<B>(bucket: B) -> Self

where B: Into<String>,

Creates a new SignedUrlBuilder for a specific bucket.

Example

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_bucket("projects/_/buckets/my-bucket")
        .sign_with(signer)
        .await?;
}

pub fn with_method(self, method: Method) -> Self

Sets the HTTP method for the signed URL. The default is GET.

Example

use google_cloud_storage::http;

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_method(http::Method::PUT)
        .sign_with(signer)
        .await?;
}

pub fn with_expiration(self, expiration: Duration) -> Self

Sets the expiration time for the signed URL. The default is 7 days.

The maximum expiration time for V4 signed URLs is 7 days.

Example

use std::time::Duration;

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_expiration(Duration::from_secs(3600))
        .sign_with(signer)
        .await?;
}

pub fn with_url_style(self, url_style: UrlStyle) -> Self

Sets the URL style for the signed URL. The default is UrlStyle::PathStyle.

Example

use google_cloud_storage::signed_url::UrlStyle;

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_url_style(UrlStyle::VirtualHostedStyle)
        .sign_with(signer)
        .await?;
}

pub fn with_header<K: Into<String>, V: Into<String>>( self, key: K, value: V, ) -> Self

Adds a header to the signed URL.

Subsequent calls to this method with the same key will override the previous value.

Note: These headers must be present in the request when using the signed URL.

Example

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_header("content-type", "text/plain")
        .sign_with(signer)
        .await?;
}

pub fn with_query_param<K: Into<String>, V: Into<String>>( self, key: K, value: V, ) -> Self

Adds a query parameter to the signed URL.

Subsequent calls to this method with the same key will override the previous value.

Example

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_query_param("generation", "1234567890")
        .sign_with(signer)
        .await?;
}

pub fn with_endpoint<S: Into<String>>(self, endpoint: S) -> Self

Sets the endpoint for the signed URL. The default is "https://storage.googleapis.com".

This is useful when using a custom domain, or when testing with some Cloud Storage emulators.

Example

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_endpoint("https://private.googleapis.com")
        .sign_with(signer)
        .await?;
}

pub fn with_client_email<S: Into<String>>(self, client_email: S) -> Self

Sets the client email for the signed URL.

If not set, the email will be fetched from the signer.

Example

async fn run(signer: &Signer) -> anyhow::Result<()> {
    let url = SignedUrlBuilder::for_object("projects/_/buckets/my-bucket", "my-object.txt")
        .with_client_email("my-service-account@my-project.iam.gserviceaccount.com")
        .sign_with(signer)
        .await?;
}

pub async fn sign_with(self, signer: &Signer) -> Result<String, SigningError>

Generates the signed URL using the provided signer.

Returns

A Result containing the signed URL as a String or a SigningError.

Trait Implementations

impl Debug for SignedUrlBuilder

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

Formats the value using the given formatter.