Crate reqsign_core

Expand description

Core components for signing API requests.

This crate provides the foundational types and traits for the reqsign ecosystem. It defines the core abstractions that enable flexible and extensible request signing.

§Overview

The crate is built around several key concepts:

Context: A container that holds implementations for file reading, HTTP sending, and environment access
Traits: Abstract interfaces for credential loading (ProvideCredential) and request signing (SignRequest)
Signer: The main orchestrator that coordinates credential loading and request signing

§Request URI contract

Built-in request signers expect the request URI to be a valid, wire-ready URI with an authority. Callers must construct the intended path and query structure and percent-encode data components exactly once before signing. Structural URI delimiters remain literal, while delimiter bytes that belong to data must already be encoded, such as %2F for a slash inside one path segment.

Existing path and query representations are authoritative. Canonicalization is a service-specific, read-only view: header authentication preserves the URI, while query authentication appends protocol-encoded authentication fields without decoding, sorting, or rebuilding the existing URI.

Signer::sign runs the service signer against a private candidate request head. On error, the caller’s method, URI, version, headers, and extensions remain unchanged. On success, only the URI and headers are committed; the caller retains ownership of the method, version, and extensions.

expires_in is a service-specific validity input, not a universal selector between header and query authentication. The service and credential type determine the authentication mode.

SigningCredential::is_valid controls whether a cached credential can be reused without refresh. SigningCredential::is_valid_at checks exact usability at the timestamp returned by SignRequest::required_valid_until. A refreshed credential only needs to satisfy the exact operation requirement; provider errors are returned without retrying internally or falling back to the old cached credential.

§Example

use reqsign_core::{Context, OsEnv, ProvideCredential, Result, SignRequest, Signer, SigningCredential};
use http::request::Parts;
use std::time::Duration;

// Define your credential type
#[derive(Clone, Debug)]
struct MyCredential {
    key: String,
    secret: String,
}

impl SigningCredential for MyCredential {
    fn is_valid(&self) -> bool {
        !self.key.is_empty() && !self.secret.is_empty()
    }
}

// Implement credential loader
#[derive(Debug)]
struct MyLoader;

impl ProvideCredential for MyLoader {
    type Credential = MyCredential;

    async fn provide_credential(&self, _: &Context) -> Result<Option<Self::Credential>> {
        Ok(Some(MyCredential {
            key: "my-access-key".to_string(),
            secret: "my-secret-key".to_string(),
        }))
    }
}

// Implement request builder
#[derive(Debug)]
struct MyBuilder;

impl SignRequest for MyBuilder {
    type Credential = MyCredential;

    async fn sign_request(
        &self,
        _ctx: &Context,
        req: &mut Parts,
        _cred: Option<&Self::Credential>,
        _expires_in: Option<Duration>,
    ) -> Result<()> {
        // Add example header
        req.headers.insert("x-custom-auth", "signed".parse()?);
        Ok(())
    }
}

// Create a context with your implementations
let ctx = Context::new()
    .with_file_read(MockFileRead)
    .with_http_send(MockHttpSend)
    .with_env(OsEnv);

// Create a signer
let signer = Signer::new(ctx, MyLoader, MyBuilder);

// Sign your requests
let mut parts = http::Request::builder()
    .method("GET")
    .uri("https://example.com")
    .body(())
    .unwrap()
    .into_parts()
    .0;

signer.sign(&mut parts, None).await?;

§Traits

This crate defines several important traits:

FileRead: For asynchronous file reading
HttpSend: For sending HTTP requests
Env: For environment variable access
ProvideCredential: For loading credentials from various sources
SignRequest: For building service-specific signing requests
SigningCredential: For validating credentials

§Utilities

The crate also provides utility modules:

hash: Cryptographic hashing utilities
time: Time manipulation utilities
utils: General utilities including data redaction

Re-exports§

pub use error::Error;
pub use error::ErrorKind;
pub use error::Result;

Modules§

error: Error types for reqsign operations
hash: Hash related utils.
time: Time related utils.
utils: Utility functions and types.

Structs§

CommandOutput: CommandOutput represents the output of a command execution.
Context: Context provides the context for the request signing.
NoopCommandExecute: NoopCommandExecute is a no-op implementation that always returns an error.
NoopEnv: NoopEnv is a no-op implementation that always returns None/empty.
NoopFileRead: NoopFileRead is a no-op implementation that always returns an error.
NoopHttpSend: NoopHttpSend is a no-op implementation that always returns an error.
OsEnv: Implements Env for the OS context, both Unix style and Windows.
ProvideCredentialChain: A chain of credential providers that will be tried in order.
Signer: Loads credentials and atomically signs request heads.
SigningRequest: A service-local canonicalization view and signed-header staging area.
StaticEnv: StaticEnv provides a static env environment.

Enums§

SigningMethod: A service-selected authentication placement.

Traits§

CommandExecute: CommandExecute is used to execute external commands for credential retrieval.
CommandExecuteDyn: CommandExecuteDyn is the dyn version of CommandExecute.
Env: Permits parameterizing the home functions via the _from variants
FileRead: FileRead is used to read the file content entirely in Vec<u8>.
FileReadDyn: FileReadDyn is the dyn version of FileRead.
HttpSend: HttpSend is used to send http request during the signing process.
HttpSendDyn: HttpSendDyn is the dyn version of HttpSend.
MaybeSend: MaybeSend is a marker to determine whether a type is Send or not.
ProvideCredential: ProvideCredential is the trait used by signer to load the credential from the environment. ` Service may require different credential to sign the request, for example, AWS require access key and secret key, while Google Cloud Storage require token.
ProvideCredentialDyn: ProvideCredentialDyn is the dyn version of ProvideCredential.
SignRequest: Service-specific request signing.
SignRequestDyn: SignRequestDyn is the dyn version of SignRequest.
SigningCredential: A credential that can distinguish cache freshness from exact usability.

Type Aliases§

BoxedFuture: BoxedFuture is the type alias of futures::future::BoxFuture.