Skip to main content

Connection

Struct Connection 

Source
pub struct Connection { /* private fields */ }

Implementations§

Source§

impl Connection

Source

pub fn new(role: Role, limits: Limits) -> Result<Self>

A connection whose initial SETTINGS advertises limits: the concurrent-stream, frame-size and header-list limits, in that (ascending) identifier order.

Source

pub fn with_settings( role: Role, limits: Limits, settings: &Settings, ) -> Result<Self>

A connection whose initial SETTINGS frame carries exactly settings, serialised in ascending identifier order. Settings::new() sends an empty frame, which is what Node’s server sends.

limits is what this endpoint enforces on its own. A parameter in settings that corresponds to a limit replaces it once the peer acknowledges the frame (and at once, if that relaxes it: the peer may act on the new value before its ack reaches us). A client that does not name ENABLE_PUSH leaves push enabled, as the protocol defaults it, and surfaces each promise as Event::PushPromise.

Source

pub fn settings(&mut self, settings: &Settings) -> Result<()>

Send a SETTINGS frame carrying settings to a live connection - Node’s session.settings(). It may be called while earlier frames are still unacknowledged; each is acknowledged in turn with Event::SettingsAck.

A parameter that loosens what this endpoint enforces - a larger MAX_FRAME_SIZE, INITIAL_WINDOW_SIZE, MAX_HEADER_LIST_SIZE or MAX_CONCURRENT_STREAMS - applies at once, because the peer may act on it before its acknowledgement arrives. One that tightens applies when the peer acknowledges the frame (RFC 9113 section 6.5.3), so frames the peer sent under the old value are never treated as errors.

Values this endpoint could not honour are refused before anything is sent: ENABLE_PUSH above 1 from a client, anything but 0 from a server, and the out-of-range values RFC 9113 section 6.5.2 forbids.

Source

pub fn limits(&self) -> Limits

What this endpoint enforces now, including the effect of SETTINGS it has sent (see settings).

Source

pub fn local_settings(&self) -> &Settings

Every parameter this endpoint has sent and the peer has acknowledged - Node’s session.localSettings, less the defaults nobody sent.

Source

pub fn remote_settings(&self) -> &Settings

Every parameter the peer has sent - Node’s session.remoteSettings, less the defaults the peer did not send.

Source

pub fn pending_settings(&self) -> usize

SETTINGS frames sent and not yet acknowledged.

Source

pub fn set_settings_deadline(&mut self, deadline: Option<Instant>)

Host-supplied deadline for the oldest outstanding SETTINGS frame’s acknowledgement; no clock is sampled. Each acknowledgement clears it, so a host with further frames outstanding sets the next one after each Event::SettingsAck.

Source

pub fn next_timeout(&self) -> Option<Instant>

Source

pub fn handle_timeout(&mut self, now: Instant) -> Option<Error>

Source

pub fn eof(&mut self)

Notify transport loss, then call poll_failed_stream until exhausted.

Source

pub fn poll_failed_stream(&mut self) -> Option<u32>

Exactly one terminal result for each still-open stream after connection failure. Fully ended/reset streams have already produced their terminal event.

Source

pub fn output(&self) -> &[u8] ⓘ

Source

pub fn consume_output(&mut self, n: usize) -> Result<()>

Source

pub fn open(&mut self, headers: &[Header], end_stream: bool) -> Result<u32>

Source

pub fn push(&mut self, stream: u32, headers: &[Header]) -> Result<u32>

Promise a response to the request headers on stream, a request stream the client opened (RFC 9113 section 8.4). Returns the promised stream, which then carries the response through send_headers and send_data. Refused when the peer disabled push with ENABLE_PUSH = 0.

Source

pub fn send_headers( &mut self, id: u32, headers: &[Header], end_stream: bool, ) -> Result<()>

Source

pub fn send_data( &mut self, id: u32, bytes: &[u8], end_stream: bool, ) -> Result<usize>

Returns accepted bytes (zero on flow-control stall). Host retains remainder.

Source

pub fn release_capacity(&mut self, id: u32, n: u32) -> Result<()>

Return n bytes of a stream’s receive window to the peer; n may not exceed that stream’s unreleased count.

A terminated stream has already had its remaining credit returned in bulk, so a late release for one is a no-op, not an error — a host that buffers a body and releases when the application consumes it can always call this, whatever happened to the stream meanwhile. An id this connection has never used is still an error.

Source

pub fn unreleased(&self, id: u32) -> Option<u32>

Received DATA bytes for id whose flow-control credit the host has not yet returned with release_capacity. None once the stream is gone, its credit having been returned in bulk. Padding never appears here: receive releases it as it is consumed.

Source

pub fn reset(&mut self, id: u32, code: u32) -> Result<()>

Terminate a stream with RST_STREAM.

The stream’s outstanding connection-level credit is returned and its table slot is freed at once, so resetting a stream that still holds unreleased DATA — the ordinary “one stream errors while its siblings are live” case — costs the connection nothing. Frames the peer already had in flight for the stream are then ignored rather than failing the connection (RFC 9113 section 5.1).

The frame is sent even when the stream has no record left — it may have been reset already, or refused before one existed, as after Event::Unprocessed. Encoding what the host asks for is this type’s job; deciding not to is the host’s. Only an id this connection has never used is an error.

Source

pub fn set_reject_unsolicited_ping_ack(&mut self, reject: bool)

RFC 9113 leaves a PING acknowledgement that answers nothing this endpoint sent without a required reaction, and by default it is only reported as Event::Ping. With reject set it fails the connection with GOAWAY(INTERNAL_ERROR), as Node does: no legitimate peer sends one.

Source

pub fn ping(&mut self, data: [u8; 8]) -> Result<()>

Source

pub fn shutdown(&mut self) -> Result<()>

Graceful close: GOAWAY(NO_ERROR) naming the last stream this connection has processed, then drain. A stream the peer opens before it sees the frame does not fail the connection and is not answered: it arrives as Event::Unprocessed and the host decides.

Source

pub fn goaway( &mut self, code: u32, last_stream: u32, opaque: &[u8], ) -> Result<()>

GOAWAY with an explicit error code, last stream id and opaque debug data, the form shutdown cannot express. The connection starts draining either way.

Source

pub fn is_drained(&self) -> bool

Source

pub fn receive<'a>(&mut self, input: &'a [u8]) -> Result<Step<'a>>

Auto Trait Implementations§

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> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

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, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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.