Trait ureq::Middleware[−][src]

pub trait Middleware: Send + Sync + 'static {
    fn handle(
        &self, 
        request: Request, 
        next: MiddlewareNext<'_>
    ) -> Result<Response, Error>;
}
Expand description

Chained processing of request (and response).

Middleware as fn

The middleware trait is implemented for all functions that have the signature

Fn(Request, MiddlewareNext) -> Result<Response, Error>

That means the easiest way to implement middleware is by providing a fn, like so

fn my_middleware(req: Request, next: MiddlewareNext) -> Result<Response, Error> {
    // do middleware things

    // continue the middleware chain
    next.handle(req)
}

Adding headers

A common use case is to add headers to the outgoing request. Here an example of how.

fn my_middleware(req: Request, next: MiddlewareNext) -> Result<Response, Error> {
    // set my bespoke header and continue the chain
    next.handle(req.set("X-My-Header", "value_42"))
}

let agent = ureq::builder()
    .middleware(my_middleware)
    .build();

let result: serde_json::Value =
    agent.get("http://httpbin.org/headers").call()?.into_json()?;

assert_eq!(&result["headers"]["X-My-Header"], "value_42");

State

To maintain state between middleware invocations, we need to do something more elaborate than the simple fn and implement the Middleware trait directly.

Example with mutex lock

In the examples directory there is an additional example count-bytes.rs which uses a mutex lock like shown below.

struct MyState {
    // whatever is needed
}

struct MyMiddleware(Arc<Mutex<MyState>>);

impl Middleware for MyMiddleware {
    fn handle(&self, request: Request, next: MiddlewareNext) -> Result<Response, Error> {
        // These extra brackets ensures we release the Mutex lock before continuing the
        // chain. There could also be scenarios where we want to maintain the lock through
        // the invocation, which would block other requests from proceeding concurrently
        // through the middleware.
        {
            let mut state = self.0.lock().unwrap();
            // do stuff with state
        }

        // continue middleware chain
        next.handle(request)
    }
}

Example with atomic

This example shows how we can increase a counter for each request going through the agent.

use ureq::{Request, Response, Middleware, MiddlewareNext, Error};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;

// Middleware that stores a counter state. This example uses an AtomicU64
// since the middleware is potentially shared by multiple threads running
// requests at the same time.
struct MyCounter(Arc<AtomicU64>);

impl Middleware for MyCounter {
    fn handle(&self, req: Request, next: MiddlewareNext) -> Result<Response, Error> {
        // increase the counter for each invocation
        self.0.fetch_add(1, Ordering::SeqCst);

        // continue the middleware chain
        next.handle(req)
    }
}

let shared_counter = Arc::new(AtomicU64::new(0));

let agent = ureq::builder()
    // Add our middleware
    .middleware(MyCounter(shared_counter.clone()))
    .build();

agent.get("http://httpbin.org/get").call()?;
agent.get("http://httpbin.org/get").call()?;

// Check we did indeed increase the counter twice.
assert_eq!(shared_counter.load(Ordering::SeqCst), 2);

Required methods

Handle of the middleware logic.

Implementors