Struct h2::client::SendRequest

source ·
pub struct SendRequest<B: Buf> { /* private fields */ }
Expand description

Initializes new HTTP/2 streams on a connection by sending a request.

This type does no work itself. Instead, it is a handle to the inner connection state held by Connection. If the associated connection instance is dropped, all SendRequest functions will return Error.

SendRequest instances are able to move to and operate on separate tasks / threads than their associated Connection instance. Internally, there is a buffer used to stage requests before they get written to the connection. There is no guarantee that requests get written to the connection in FIFO order as HTTP/2 prioritization logic can play a role.

SendRequest implements Clone, enabling the creation of many instances that are backed by a single connection.

See module level documentation for more details.

Implementations§

source§

impl<B> SendRequest<B>
where B: Buf,

source

pub fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Error>>

Returns Ready when the connection can initialize a new HTTP/2 stream.

This function must return Ready before send_request is called. When Poll::Pending is returned, the task will be notified once the readiness state changes.

See module level docs for more details.

source

pub fn ready(self) -> ReadySendRequest<B>

Consumes self, returning a future that returns self back once it is ready to send a request.

This function should be called before calling send_request.

This is a functional combinator for poll_ready. The returned future will call SendStream::poll_ready until Ready, then returns self to the caller.

§Examples
// First, wait until the `send_request` handle is ready to send a new
// request
let mut send_request = send_request.ready().await.unwrap();
// Use `send_request` here.

See module level docs for more details.

source

pub fn send_request( &mut self, request: Request<()>, end_of_stream: bool, ) -> Result<(ResponseFuture, SendStream<B>), Error>

Sends a HTTP/2 request to the server.

send_request initializes a new HTTP/2 stream on the associated connection, then sends the given request using this new stream. Only the request head is sent.

On success, a ResponseFuture instance and SendStream instance are returned. The ResponseFuture instance is used to get the server’s response and the SendStream instance is used to send a request body or trailers to the server over the same HTTP/2 stream.

To send a request body or trailers, set end_of_stream to false. Then, use the returned SendStream instance to stream request body chunks or send trailers. If end_of_stream is not set to false then attempting to call SendStream::send_data or SendStream::send_trailers will result in an error.

If no request body or trailers are to be sent, set end_of_stream to true and drop the returned SendStream instance.

§A note on HTTP versions

The provided Request will be encoded differently depending on the value of its version field. If the version is set to 2.0, then the request is encoded as per the specification recommends.

If the version is set to a lower value, then the request is encoded to preserve the characteristics of HTTP 1.1 and lower. Specifically, host headers are permitted and the :authority pseudo header is not included.

The caller should always set the request’s version field to 2.0 unless specifically transmitting an HTTP 1.1 request over 2.0.

§Examples

Sending a request with no body

// First, wait until the `send_request` handle is ready to send a new
// request
let mut send_request = send_request.ready().await.unwrap();
// Prepare the HTTP request to send to the server.
let request = Request::get("https://www.example.com/")
    .body(())
    .unwrap();

// Send the request to the server. Since we are not sending a
// body or trailers, we can drop the `SendStream` instance.
let (response, _) = send_request.send_request(request, true).unwrap();
let response = response.await.unwrap();
// Process the response

Sending a request with a body and trailers

// First, wait until the `send_request` handle is ready to send a new
// request
let mut send_request = send_request.ready().await.unwrap();

// Prepare the HTTP request to send to the server.
let request = Request::get("https://www.example.com/")
    .body(())
    .unwrap();

// Send the request to the server. If we are not sending a
// body or trailers, we can drop the `SendStream` instance.
let (response, mut send_stream) = send_request
    .send_request(request, false).unwrap();

// At this point, one option would be to wait for send capacity.
// Doing so would allow us to not hold data in memory that
// cannot be sent. However, this is not a requirement, so this
// example will skip that step. See `SendStream` documentation
// for more details.
send_stream.send_data(b"hello", false).unwrap();
send_stream.send_data(b"world", false).unwrap();

// Send the trailers.
let mut trailers = HeaderMap::new();
trailers.insert(
    header::HeaderName::from_bytes(b"my-trailer").unwrap(),
    header::HeaderValue::from_bytes(b"hello").unwrap());

send_stream.send_trailers(trailers).unwrap();

let response = response.await.unwrap();
// Process the response
source

pub fn is_extended_connect_protocol_enabled(&self) -> bool

Returns whether the extended CONNECT protocol is enabled or not.

This setting is configured by the server peer by sending the SETTINGS_ENABLE_CONNECT_PROTOCOL parameter in a SETTINGS frame. This method returns the currently acknowledged value received from the remote.

Trait Implementations§

source§

impl<B> Clone for SendRequest<B>
where B: Buf,

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<B> Debug for SendRequest<B>
where B: Buf,

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<B> Freeze for SendRequest<B>

§

impl<B> RefUnwindSafe for SendRequest<B>

§

impl<B> Send for SendRequest<B>
where B: Send,

§

impl<B> Sync for SendRequest<B>
where B: Send,

§

impl<B> Unpin for SendRequest<B>

§

impl<B> UnwindSafe for SendRequest<B>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more