Crate webtransport_quinn

WebTransport is a protocol for client-server communication over QUIC. It’s available in the browser as an alternative to HTTP and WebSockets.

WebTransport is layered on top of HTTP/3 which is then layered on top of QUIC. This library hides that detail and tries to expose only the QUIC API, delegating as much as possible to the underlying implementation. See the Quinn documentation for more documentation.

QUIC provides two primary APIs:

Streams

QUIC streams are ordered, reliable, flow-controlled, and optionally bidirectional. Both endpoints can create and close streams (including an error code) with no overhead. You can think of them as TCP connections, but shared over a single QUIC connection.

Datagrams

QUIC datagrams are unordered, unreliable, and not flow-controlled. Both endpoints can send datagrams below the MTU size (~1.2kb minimum) and they might arrive out of order or not at all. They are basically UDP packets, except they are encrypted and congestion controlled.

Limitations

WebTransport is able to be pooled with HTTP/3 and multiple WebTransport sessions. This crate avoids that complexity, doing the bare minimum to support a single WebTransport session that owns the entire QUIC connection. If you want to support HTTP/3 on the same host/port, you should use another crate (ex. h3-webtransport). If you want to support multiple WebTransport sessions over the same QUIC connection… you should just dial a new QUIC connection instead.

Structs

• RecvStream
  A stream that can be used to recieve bytes. See quinn::RecvStream.
• Request
  A mostly complete WebTransport handshake, just awaiting the server’s decision on whether to accept or reject the session based on the URL.
• SendStream
  A stream that can be used to send bytes. See quinn::SendStream.
• Session
  An established WebTransport session, acting like a full QUIC connection. See quinn::Connection.
• SessionAccept
• StreamClosed
  An error indicating the stream was already closed. Same as quinn::UnknownStream but a less confusing name.

Enums

• ClientError
  An error returned when connecting to a WebTransport endpoint.
• ReadError
  An error when reading from crate::RecvStream. Similar to quinn::ReadError.
• ReadExactError
  An error returned by crate::RecvStream::read_exact. Similar to quinn::ReadExactError.
• ReadToEndError
  An error returned by crate::RecvStream::read_to_end. Similar to quinn::ReadToEndError.
• ServerError
  An error returned when receiving a new WebTransport session.
• SessionError
  An errors returned by crate::Session, split based on if they are underlying QUIC errors or WebTransport errors.
• StoppedError
  An error returned by crate::SendStream::stopped. Similar to quinn::StoppedError.
• WebTransportError
  An error that can occur when reading/writing the WebTransport stream header.
• WriteError
  An error when writing to crate::SendStream. Similar to quinn::WriteError.

Constants

• ALPN
  The HTTP/3 ALPN is required when negotiating a QUIC connection.

Functions

• accept
  Accept a new WebTransport session from a client. Returns a Request which is then used to accept or reject the session based on the URL.
• connect
  Connect to a WebTransport server at the given URL. The UR: must be of the form https://host:port/path or else the server will reject it. Returns a Session which is a wrapper over quinn::Connection.
• connect_with
  Connect using an established QUIC connection if you want to create the connection yourself. This will only work with a brand new QUIC connection using the HTTP/3 ALPN.