Capture the connection for a given request

When making a request with Hyper, the underlying connection must implement the Connection trait. capture_connection allows a caller to capture the returned Connected structure as soon as the connection is established.

Note: If establishing a connection fails, CaptureConnection::connection_metadata will always return none.

Examples

Synchronous access: The CaptureConnection::connection_metadata method allows callers to check if a connection has been established. This is ideal for situations where you are certain the connection has already been established (e.g. after the response future has already completed).

use hyper_util::client::legacy::connect::capture_connection;
let mut request = http::Request::builder()
  .uri("http://foo.com")
  .body(())
  .unwrap();

let captured_connection = capture_connection(&mut request);
// some time later after the request has been sent...
let connection_info = captured_connection.connection_metadata();
println!("we are connected! {:?}", connection_info.as_ref());

Asynchronous access: The CaptureConnection::wait_for_connection_metadata method returns a future resolves as soon as the connection is available.

# #[cfg(feature  = "tokio")]
# async fn example() {
use hyper_util::client::legacy::connect::capture_connection;
use hyper_util::client::legacy::Client;
use hyper_util::rt::TokioExecutor;
use bytes::Bytes;
use http_body_util::Empty;
let mut request = http::Request::builder()
  .uri("http://foo.com")
  .body(Empty::<Bytes>::new())
  .unwrap();

let mut captured = capture_connection(&mut request);
tokio::task::spawn(async move {
    let connection_info = captured.wait_for_connection_metadata().await;
    println!("we are connected! {:?}", connection_info.as_ref());
});

let client = Client::builder(TokioExecutor::new()).build_http();
client.request(request).await.expect("request failed");
# }