pub struct Connection { /* private fields */ }Implementations§
Source§impl Connection
impl Connection
Sourcepub fn new(role: Role, limits: Limits) -> Result<Self>
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.
Sourcepub fn with_settings(
role: Role,
limits: Limits,
settings: &Settings,
) -> Result<Self>
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.
Sourcepub fn settings(&mut self, settings: &Settings) -> Result<()>
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.
Sourcepub fn limits(&self) -> Limits
pub fn limits(&self) -> Limits
What this endpoint enforces now, including the effect of SETTINGS it
has sent (see settings).
Sourcepub fn local_settings(&self) -> &Settings
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.
Sourcepub fn remote_settings(&self) -> &Settings
pub fn remote_settings(&self) -> &Settings
Every parameter the peer has sent - Node’s session.remoteSettings,
less the defaults the peer did not send.
Sourcepub fn pending_settings(&self) -> usize
pub fn pending_settings(&self) -> usize
SETTINGS frames sent and not yet acknowledged.
Sourcepub fn set_settings_deadline(&mut self, deadline: Option<Instant>)
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.
pub fn next_timeout(&self) -> Option<Instant>
pub fn handle_timeout(&mut self, now: Instant) -> Option<Error>
Sourcepub fn poll_failed_stream(&mut self) -> Option<u32>
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.
pub fn output(&self) -> &[u8] ⓘ
pub fn consume_output(&mut self, n: usize) -> Result<()>
pub fn open(&mut self, headers: &[Header], end_stream: bool) -> Result<u32>
Sourcepub fn push(&mut self, stream: u32, headers: &[Header]) -> Result<u32>
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.
pub fn send_headers( &mut self, id: u32, headers: &[Header], end_stream: bool, ) -> Result<()>
Sourcepub fn send_data(
&mut self,
id: u32,
bytes: &[u8],
end_stream: bool,
) -> Result<usize>
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.
Sourcepub fn release_capacity(&mut self, id: u32, n: u32) -> Result<()>
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.
Sourcepub fn unreleased(&self, id: u32) -> Option<u32>
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.
Sourcepub fn reset(&mut self, id: u32, code: u32) -> Result<()>
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.
Sourcepub fn set_reject_unsolicited_ping_ack(&mut self, reject: bool)
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.
pub fn ping(&mut self, data: [u8; 8]) -> Result<()>
Sourcepub fn shutdown(&mut self) -> Result<()>
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.
Sourcepub fn goaway(
&mut self,
code: u32,
last_stream: u32,
opaque: &[u8],
) -> Result<()>
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.