Crate pincer 

Declarative HTTP client for Rust.

Define HTTP clients using proc-macros with async/await and Tower middleware.

Example

use pincer::prelude::*;

#[derive(Debug, Deserialize)]
pub struct User {
    id: u64,
    name: String,
}

#[pincer(url = "https://api.example.com")]
pub trait UserApi {
    #[get("/users/{id}")]
    async fn get_user(&self, #[path] id: u64) -> pincer::Result<User>;
}

let client = UserApiClientBuilder::default().build()?;
let user = client.get_user(42).await?;

See the tutorial for a complete guide.

Re-exports

pub use tower;

pub use percent_encoding;

pub use serde_html_form;

pub use url;

Modules

_tutorial

Tutorial: Building HTTP Clients with pincer

header

HTTP header types

middleware

Tower middleware layers for pincer HTTP client.

prelude

Prelude module for convenient imports.

Structs

ApiClient

Generic API client wrapper.

ClientConfig

Configuration for the HTTP client.

ClientConfigBuilder

Builder for ClientConfig.

DefaultErrorDecoder

Default error decoder that always returns None.

Form

A multipart form containing multiple parts.

HyperClient

HTTP client using hyper-util with connection pooling, TLS, and middleware support.

HyperClientBuilder

Builder for HyperClient.

ParamMeta

Metadata about a single parameter.

ParameterMetadata

All parameter metadata for a method call.

Part

A single part in a multipart form.

PathTemplate

The original path template before parameter substitution.

Request

An HTTP request with method, URL, headers, optional body, and extensions.

RequestBuilder

Builder for constructing Request instances.

Response

HTTP response with status, headers, and body.

StatusCode

An HTTP status code (status-code in RFC 9110 et al.).

Enums

ContentType

Content type for request bodies.

Error

Main error type for pincer operations.

Method

HTTP request method.

ParamLocation

Parameter location in the HTTP request.

Traits

ErrorDecoder

Trait for decoding HTTP error responses into typed errors.

HttpClient

Core HTTP client trait.

HttpClientExt

Extension trait for HttpClient with convenience methods.

PincerClient

Trait for types that can be used as pincer API clients.

ToQueryPairs

Trait for types that can be converted to query parameter pairs.

Functions

from_json

Deserialize JSON bytes to a value with path-aware error messages.

to_form

Serialize a value to form URL-encoded bytes.

to_json

Serialize a value to JSON bytes.

to_query_string

Serialize a value to a query string.

Type Aliases

Result

Result type alias using crate::Error.

ServiceFuture

Future type for Tower Service implementation.

Attribute Macros

delete

Mark a method as a DELETE request.

get

Mark a method as a GET request.

head

Mark a method as a HEAD request.

http

Mark a method with a custom HTTP method and path.

options

Mark a method as an OPTIONS request.

patch

Mark a method as a PATCH request.

pincer

Mark a trait as a pincer HTTP client.

post

Mark a method as a POST request.

put

Mark a method as a PUT request.

Derive Macros

Query

Derive the ToQueryPairs trait for a struct.