Struct Connection 

pub struct Connection { /* private fields */ }

One HTTP/2 connection, either end.

Implementations

impl Connection

pub fn server(cfg: Config) -> Connection

A server connection. It expects the client preface; its own SETTINGS are already in Connection::output.

Examples found in repository

examples/bench_h2.rs (line 27)

fn pair() -> (Connection, Connection, Vec<u8>) {
    let cfg = Config { window_autotune: false, ..Config::default() };
    let mut c = Connection::client(cfg.clone());
    let mut s = Connection::server(cfg);
    let mut buf = Vec::with_capacity(64 * 1024);
    for _ in 0..3 {
        transfer(&mut c, &mut buf);
        s.recv(&buf, 0, &mut |_| {});
        transfer(&mut s, &mut buf);
        c.recv(&buf, 0, &mut |_| {});
    }
    (c, s, buf)
}

pub fn client(cfg: Config) -> Connection

A client connection (h2c prior knowledge, or h2 after ALPN). The preface and SETTINGS are already in Connection::output, and requests can be sent at once.

Examples found in repository

examples/bench_h2.rs (line 26)

fn pair() -> (Connection, Connection, Vec<u8>) {
    let cfg = Config { window_autotune: false, ..Config::default() };
    let mut c = Connection::client(cfg.clone());
    let mut s = Connection::server(cfg);
    let mut buf = Vec::with_capacity(64 * 1024);
    for _ in 0..3 {
        transfer(&mut c, &mut buf);
        s.recv(&buf, 0, &mut |_| {});
        transfer(&mut s, &mut buf);
        c.recv(&buf, 0, &mut |_| {});
    }
    (c, s, buf)
}

pub fn server_upgrade( cfg: Config, http2_settings: &[u8], ) -> Result<Connection, Error>

A server connection after an HTTP/1.1 Upgrade: h2c request (RFC 7540 §3.2) was answered with 101 Switching Protocols. http2_settings is the request’s HTTP2-Settings value. The request itself becomes stream 1, half-closed (remote) with its handler running: answer it with Connection::send_response on stream 1.

pub fn client_upgrade(cfg: Config, head: bool) -> Connection

A client connection after the server answered our HTTP/1.1 Upgrade: h2c request with 101. The upgrade request is stream 1, half-closed (local); its response arrives as events for stream 1. head says whether that request was HEAD.

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

Bytes waiting to be written to the transport.

Examples found in repository

examples/bench_h2.rs (line 20)

fn transfer(from: &mut Connection, buf: &mut Vec<u8>) {
    buf.clear();
    buf.extend_from_slice(from.output());
    from.advance_output(buf.len());
}

pub fn take_output(&mut self, empty: Vec<u8>) -> Vec<u8>

Takes every byte of Connection::output as an owned buffer (no copy), leaving empty (cleared) to collect the next output. Same as reading output() and calling advance_output with its length.

pub fn advance_output(&mut self, n: usize)

Marks n bytes of Connection::output as written.

Examples found in repository

examples/bench_h2.rs (line 21)

fn transfer(from: &mut Connection, buf: &mut Vec<u8>) {
    buf.clear();
    buf.extend_from_slice(from.output());
    from.advance_output(buf.len());
}

pub fn role(&self) -> Role

This end’s role.

pub fn wants_close(&self) -> bool

True when the transport should be closed once Connection::output is flushed: after a connection error, or after a GOAWAY (sent or received) once every stream is done.

pub fn close_code(&self) -> Option<ErrorCode>

The error code of the GOAWAY we closed the connection with.

pub fn active_handlers(&self) -> u32

Streams whose handler work is still running (server).

pub fn open_streams(&self) -> u32

Streams open or half-closed.

pub fn tracked_streams(&self) -> usize

Streams the engine still tracks (open, or closed with work running).

Examples found in repository

examples/bench_h2.rs (line 81)

fn bench_requests(streams: usize, total: usize) -> f64 {
    let (mut c, mut s, mut buf) = pair();
    let mut ids = Vec::with_capacity(streams);
    // warm up (tables, buffers)
    for _ in 0..100 {
        batch(&mut c, &mut s, &mut buf, &mut ids, streams);
    }
    let rounds = total / streams;
    let t = Instant::now();
    let mut got = 0;
    for _ in 0..rounds {
        got += batch(&mut c, &mut s, &mut buf, &mut ids, streams);
    }
    let ns = t.elapsed().as_nanos() as f64 / (rounds * streams) as f64;
    assert_eq!(got, rounds * streams * BODY.len());
    assert_eq!(s.tracked_streams(), 0);
    ns
}

pub fn peer_max_concurrent_streams(&self) -> u32

The peer’s SETTINGS_MAX_CONCURRENT_STREAMS.

pub fn can_open_stream(&self) -> bool

True when a client may open another stream now.

pub fn send_capacity(&self, stream: u32) -> usize

Bytes stream may send now: the smaller of its window, the connection window and the room in the output buffer.

pub fn receive_windows(&self) -> (u32, u32)

The connection’s current receive targets (connection, per stream), after auto-tuning.

pub fn poll_timeout(&self) -> Option<u64>

The next deadline (settings acknowledgement, graceful shutdown) for Connection::handle_timeout.

pub fn handle_timeout(&mut self, now: u64, sink: &mut dyn FnMut(Event<'_>))

Fires due timers.

pub fn recv( &mut self, input: &[u8], now: u64, sink: &mut dyn FnMut(Event<'_>), ) -> usize

Processes received bytes at time now (monotonic milliseconds from any origin). Returns how many bytes were consumed; the caller keeps the rest and passes it again with more data. A buffer of max_frame_size + 9 bytes always makes progress. Input processing pauses (returns early) while more than twice max_send_buffer of output is waiting, so a peer that does not read cannot make us queue unbounded replies. After the connection is closed all input is consumed and ignored.

Examples found in repository

examples/bench_h2.rs (line 31)

fn pair() -> (Connection, Connection, Vec<u8>) {
    let cfg = Config { window_autotune: false, ..Config::default() };
    let mut c = Connection::client(cfg.clone());
    let mut s = Connection::server(cfg);
    let mut buf = Vec::with_capacity(64 * 1024);
    for _ in 0..3 {
        transfer(&mut c, &mut buf);
        s.recv(&buf, 0, &mut |_| {});
        transfer(&mut s, &mut buf);
        c.recv(&buf, 0, &mut |_| {});
    }
    (c, s, buf)
}

/// One batch: `streams` requests out, responses back. Returns body bytes received.
fn batch(c: &mut Connection, s: &mut Connection, buf: &mut Vec<u8>, ids: &mut Vec<u32>, streams: usize) -> usize {
    for _ in 0..streams {
        c.send_request(b"GET", b"https", b"example.com", b"/hello", &[(b"user-agent", b"simoom-bench"), (b"accept", b"*/*")], true).unwrap();
    }
    transfer(c, buf);
    ids.clear();
    let n = s.recv(buf, 0, &mut |e| {
        if let Event::Headers { stream, .. } = e {
            ids.push(stream);
        }
    });
    debug_assert_eq!(n, buf.len());
    for &id in ids.iter() {
        s.send_response(id, 200, &[(b"content-type", b"text/plain")], false).unwrap();
        s.send_data(id, BODY, true).unwrap();
        s.stream_finished(id);
    }
    transfer(s, buf);
    let mut got = 0;
    c.recv(buf, 0, &mut |e| {
        if let Event::Data { data, .. } = e {
            got += data.len();
        }
    });
    got
}

pub fn release(&mut self, stream: u32, n: usize)

Tells the engine the application consumed n bytes of DATA on stream, so the peer may send more. Releasing more than was delivered is ignored.

pub fn peer_max_header_list_size(&self) -> u32

The peer’s SETTINGS_MAX_HEADER_LIST_SIZE (u32::MAX until it announces one).

pub fn peer_connect_protocol(&self) -> bool

The peer (a server) allows extended CONNECT: it sent SETTINGS_ENABLE_CONNECT_PROTOCOL = 1 (RFC 8441 §3). Known once its SETTINGS arrived (Event::Settings).

pub fn send_extended_connect( &mut self, protocol: &[u8], scheme: &[u8], authority: &[u8], path: &[u8], fields: &[(&[u8], &[u8])], ) -> Result<u32, Error>

Client: opens an extended CONNECT stream (RFC 8441 §4), for example with protocol = b"websocket" for WebSocket over HTTP/2 (RFC 8441 §5). The stream stays open both ways; a 2xx response accepts the tunnel, whose bytes then travel as DATA. Fails with Error::ConnectProtocolDisabled unless the server enabled extended CONNECT.

pub fn send_response( &mut self, stream: u32, status: u16, fields: &[(&[u8], &[u8])], end_stream: bool, ) -> Result<(), Error>

Server: sends response headers on stream. A status below 200 sends an informational response (101 is not allowed in HTTP/2); then the final one follows.

Examples found in repository

examples/bench_h2.rs (line 52)

fn batch(c: &mut Connection, s: &mut Connection, buf: &mut Vec<u8>, ids: &mut Vec<u32>, streams: usize) -> usize {
    for _ in 0..streams {
        c.send_request(b"GET", b"https", b"example.com", b"/hello", &[(b"user-agent", b"simoom-bench"), (b"accept", b"*/*")], true).unwrap();
    }
    transfer(c, buf);
    ids.clear();
    let n = s.recv(buf, 0, &mut |e| {
        if let Event::Headers { stream, .. } = e {
            ids.push(stream);
        }
    });
    debug_assert_eq!(n, buf.len());
    for &id in ids.iter() {
        s.send_response(id, 200, &[(b"content-type", b"text/plain")], false).unwrap();
        s.send_data(id, BODY, true).unwrap();
        s.stream_finished(id);
    }
    transfer(s, buf);
    let mut got = 0;
    c.recv(buf, 0, &mut |e| {
        if let Event::Data { data, .. } = e {
            got += data.len();
        }
    });
    got
}

pub fn send_request( &mut self, method: &[u8], scheme: &[u8], authority: &[u8], path: &[u8], fields: &[(&[u8], &[u8])], end_stream: bool, ) -> Result<u32, Error>

Client: opens a stream with a request. authority may be empty; path is ignored for CONNECT. Returns the new stream id.

Examples found in repository

examples/bench_h2.rs (line 41)

fn batch(c: &mut Connection, s: &mut Connection, buf: &mut Vec<u8>, ids: &mut Vec<u32>, streams: usize) -> usize {
    for _ in 0..streams {
        c.send_request(b"GET", b"https", b"example.com", b"/hello", &[(b"user-agent", b"simoom-bench"), (b"accept", b"*/*")], true).unwrap();
    }
    transfer(c, buf);
    ids.clear();
    let n = s.recv(buf, 0, &mut |e| {
        if let Event::Headers { stream, .. } = e {
            ids.push(stream);
        }
    });
    debug_assert_eq!(n, buf.len());
    for &id in ids.iter() {
        s.send_response(id, 200, &[(b"content-type", b"text/plain")], false).unwrap();
        s.send_data(id, BODY, true).unwrap();
        s.stream_finished(id);
    }
    transfer(s, buf);
    let mut got = 0;
    c.recv(buf, 0, &mut |e| {
        if let Event::Data { data, .. } = e {
            got += data.len();
        }
    });
    got
}

pub fn send_trailers( &mut self, stream: u32, fields: &[(&[u8], &[u8])], ) -> Result<(), Error>

Sends trailers, ending the stream.

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

Sends body bytes on stream, as much as the stream window, the connection window and the output buffer cap allow. Returns how many bytes were accepted; end_stream applies only when all of data was accepted. When fewer were accepted the stream is remembered, and Connection::poll_writable reports it once it can send again.

Examples found in repository

examples/bench_h2.rs (line 53)

fn batch(c: &mut Connection, s: &mut Connection, buf: &mut Vec<u8>, ids: &mut Vec<u32>, streams: usize) -> usize {
    for _ in 0..streams {
        c.send_request(b"GET", b"https", b"example.com", b"/hello", &[(b"user-agent", b"simoom-bench"), (b"accept", b"*/*")], true).unwrap();
    }
    transfer(c, buf);
    ids.clear();
    let n = s.recv(buf, 0, &mut |e| {
        if let Event::Headers { stream, .. } = e {
            ids.push(stream);
        }
    });
    debug_assert_eq!(n, buf.len());
    for &id in ids.iter() {
        s.send_response(id, 200, &[(b"content-type", b"text/plain")], false).unwrap();
        s.send_data(id, BODY, true).unwrap();
        s.stream_finished(id);
    }
    transfer(s, buf);
    let mut got = 0;
    c.recv(buf, 0, &mut |e| {
        if let Event::Data { data, .. } = e {
            got += data.len();
        }
    });
    got
}

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

A stream that was short of capacity in Connection::send_data and can send again. Call it after Connection::recv and Connection::advance_output until it returns None.

pub fn reset(&mut self, stream: u32, code: ErrorCode)

Resets stream with code at the application’s request.

pub fn stream_finished(&mut self, stream: u32)

The application’s work for stream is finished: it no longer counts against the concurrency limit. A stream we have not ended is reset with CANCEL; a request body that was not read to the end is cut off with RST_STREAM(NO_ERROR) (RFC 9113 §8.1).

Examples found in repository

examples/bench_h2.rs (line 54)

fn batch(c: &mut Connection, s: &mut Connection, buf: &mut Vec<u8>, ids: &mut Vec<u32>, streams: usize) -> usize {
    for _ in 0..streams {
        c.send_request(b"GET", b"https", b"example.com", b"/hello", &[(b"user-agent", b"simoom-bench"), (b"accept", b"*/*")], true).unwrap();
    }
    transfer(c, buf);
    ids.clear();
    let n = s.recv(buf, 0, &mut |e| {
        if let Event::Headers { stream, .. } = e {
            ids.push(stream);
        }
    });
    debug_assert_eq!(n, buf.len());
    for &id in ids.iter() {
        s.send_response(id, 200, &[(b"content-type", b"text/plain")], false).unwrap();
        s.send_data(id, BODY, true).unwrap();
        s.stream_finished(id);
    }
    transfer(s, buf);
    let mut got = 0;
    c.recv(buf, 0, &mut |e| {
        if let Event::Data { data, .. } = e {
            got += data.len();
        }
    });
    got
}

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

Sends a PING; the answer arrives as Event::Pong.

pub fn shutdown(&mut self, now: u64)

Starts a graceful shutdown (RFC 9113 §6.8). A server sends GOAWAY with the largest stream id and a PING, then, after the PING round trip (or graceful_timeout_ms), the final GOAWAY with the last stream it accepted. Streams already accepted run to the end; Connection::wants_close turns true when they are done.

pub fn close(&mut self, code: ErrorCode, debug: &[u8])

Closes the connection at once with GOAWAY(code). No events follow.

Trait Implementations

impl Debug for Connection

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

Formats the value using the given formatter.