QUIC carries many independent, reliable byte streams over one encrypted UDP connection. Every connection is TLS 1.3: a client must trust the server’s certificate chain and verify that it names the requested host or IP, exactly as in TLS. Unlike TCP plus TLS, a slow or lost packet on one stream does not stall the others, and opening a stream costs no extra round trip.
std/quic/openssl binds the QUIC client and server stack in OpenSSL 3.5. The
backend owns its UDP socket, packet buffers, protocol timers and stream buffers;
your program chooses when to wait and when to process events. Every call is
nonblocking.
Choose an entry point
| Need | Starting point | Your responsibility |
|---|---|---|
| Connect to a QUIC server | openssl.Connection.connect |
Resolve the address, supply trust and ALPN, drive the handshake. |
| Accept QUIC connections | openssl.Listener.bind and accept |
Supply the certificate chain and key; handshake each accepted connection. |
| Exchange messages | open_bidirectional, open_unidirectional, accept_stream |
Frame messages on each stream; conclude or reset it. |
| Wait without spinning | wait(milliseconds) or timeout_ms plus your own poller |
Call again until operations stop reporting Pending. |
| Share error handling across backends | Portable std/quic |
Map quic.Error kinds to your protocol’s policy. |
QUIC is not HTTP/3. This package moves bytes on streams; an application protocol (your own framing, or a future HTTP/3 layer) defines what they mean.
Quickstart
This hosted example requires Linux GNU, macOS, or Windows x64 and OpenSSL 3.5+
headers, libssl and libcrypto, set up as in the TLS quickstart;
dodo run adds the libraries automatically. One process plays both roles over
loopback, so no peer program or Internet service is needed.
In a fresh disposable example directory, generate a two-day local certificate and key:
openssl req -x509 -newkey rsa:2048 -noenc -keyout key.pem -out cert.pem -days 2 -subj /CN=localhost -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
Save this as quic_start.dodo:
package quic_start
import "std/console"
import "std/fs"
import "std/io"
import "std/net"
import "std/platform"
import "std/quic"
import "std/quic/openssl"
const ALPN: &[u8] = b"\x0bhello-quic1"
// Process both endpoints' network events; one process plays both roles here.
fn turn(listener: &mut openssl.Listener, client: &mut openssl.Connection) -> void!quic.Error {
client.wait(5)?
return listener.wait(5)
}
fn exchange(certificate: &[u8], key: &[u8]) -> i32!quic.Error {
server_config := openssl.Config.server(certificate, key, ALPN)
any := net.SocketAddress.new(net.IpAddress.v4(127, 0, 0, 1), 0)
listener := openssl.Listener.bind(&server_config, &any)?
bound := listener.local_address()?
client_config := openssl.Config.client(b"localhost", ALPN)
client_config.system_roots = false
client_config.trust_pem = certificate
client := openssl.Connection.connect(&client_config, &bound)?
request: Option<openssl.Stream> = none
accepted: Option<openssl.Connection> = none
reply := [0u8; 64]
used := 0usize
for i in 0..2000 {
// Server: accept the connection, then answer each stream it opens.
match listener.accept()? {
some(connection) => { accepted = some(connection) }
none => {}
}
match &mut accepted {
some(connection) => {
match connection.accept_stream()? {
some(stream) => {
sent := stream.send(b"Hello, QUIC!\n")?
if sent.transferred != 13 { return ok(5) }
stream.conclude()?
}
none => {}
}
}
none => {}
}
// Client: once verified, open one stream and read the reply to its end.
if client.handshake()? == quic.State.Ready {
match &mut request {
some(stream) => {
progress := stream.receive(&mut reply[used..])?
used += progress.transferred
if progress.state == quic.State.Finished {
output := console.stdout()
match io.write_all(&mut output, &reply[..used]) {
ok(_) => { return ok(0) }, err(_) => { return ok(3) },
}
}
}
none => {
request = client.open_bidirectional()?
match &mut request {
some(stream) => { stream.conclude()? }
none => {}
}
}
}
}
turn(&mut listener, &mut client)?
}
return ok(2)
}
// Reads a whole PEM file, or none if it is missing or larger than `storage`.
fn load(name: &str, storage: &mut[u8]) -> Option<usize> {
path := platform.workspace()
match fs.read_file(name, storage, &mut path) {
ok(report) => {
if report.eof { return some(report.read) }
return none
},
err(_) => { return none },
}
}
fn main() -> i32 {
certificate := [0u8; 4096]
key := [0u8; 4096]
cert_length := 0usize
key_length := 0usize
match load("cert.pem", &mut certificate) {
some(length) => { cert_length = length }, none => { return 4 },
}
match load("key.pem", &mut key) {
some(length) => { key_length = length }, none => { return 4 },
}
match exchange(&certificate[..cert_length], &key[..key_length]) {
ok(code) => { return code },
err(reason) => {
errors := console.stderr()
match errors.println(&reason) {
ok(_) => {}, err(_) => {},
}
return 1
},
}
}
dodo run quic_start.dodo
Expected stdout is Hello, QUIC! followed by a newline. Exit 0 means the client
verified the server certificate for localhost, both sides agreed on the ALPN
protocol, and the client received the server’s whole reply on a stream. Delete
the example directory, including key.pem, when finished.
Exit 4 means a PEM file is missing or larger than 4096 bytes: rerun the setup
command. Exit 1 prints a quic.Error; VerificationFailed means the trust
file, hostname or validity dates do not match. Exit 2 means no reply arrived
within the loop’s bound, and 3 that output failed.
The loop shows the whole model. Each turn makes every endpoint try its next step
without blocking: accept, answer, open, read. turn then waits a few
milliseconds for datagrams or timers and processes them. An operation that
reports Pending (or none) is retried on a later turn, never treated as
failure. The server releases its stream right after conclude(); a concluded
stream still delivers its buffered bytes and FIN.
API and contracts
std/quic contains the portable vocabulary: Error, ErrorKind, State,
Progress and CloseInfo. Importing it loads no socket, cryptography, clock
or allocator, so protocol code above QUIC can be portable. std/quic/openssl
selects the OpenSSL backend and needs a hosted target.
| Type | Owns | Created by |
|---|---|---|
Listener |
A bound UDP socket, the server context, connections not yet accepted | Listener.bind(&config, &address) |
Connection |
One QUIC connection; a client connection also owns its connected UDP socket | Connection.connect(&config, &address) or listener.accept() |
Stream |
One stream’s send and receive parts | open_bidirectional(), open_unidirectional(), accept_stream() |
Configuration and verification
openssl.Config.client(hostname, alpn) verifies the server’s chain and its
hostname; IP literals match iPAddress SANs, DNS names also configure SNI, and
partial-label wildcards are disabled. Connection.connect takes an already
resolved net.SocketAddress (see DNS); the hostname is checked
independently of the address. There is no option that disables client peer
verification.
openssl.Config.server(certificate, key, alpn) requires an identity. Set
require_client_certificate=true and trust_pem for mutual authentication.
trust_pem, system_roots, certificate_pem, private_key_pem and
verification_time behave as in TLS, with
the same 1 MiB PEM and 253-byte hostname limits. Encrypted keys are rejected
without prompting.
QUIC requires ALPN, so alpn is mandatory: an RFC 7301 list of length-prefixed
protocol names such as b"\x10rift-messaging/1". The server selects the first
protocol in its own list that the client offers; without overlap the handshake
fails and the client sees ConnectionClosed with a transport CloseInfo
(code 376, no_application_protocol). selected_alpn copies the result.
idle_timeout_ms requests a client idle timeout; 0 keeps OpenSSL’s 30-second
default, and the connection uses the smaller nonzero value of both peers.
OpenSSL 3.5 cannot set it on a listener, so a server Config with a nonzero
value fails InvalidInput. QUIC has no implicit keep-alive here: keep idle
connections open with your own periodic traffic, such as a protocol ping.
Construction validates and copies all configuration; no borrow survives it.
Invalid input fails InvalidInput before a socket exists. A bind failure
reports Network with the operating-system error code in code. Scoped IPv6
(link-local) addresses are rejected because OpenSSL’s address type cannot carry
a scope.
Handshakes and connections
connect and accept return immediately. Call handshake() until it reports
Ready; only then is the peer verified. Accepted connections may still be
handshaking, and one that fails, for example because the client rejected the
certificate, reports an error from handshake(): drop it and keep accepting.
handshake() also reports ConnectionClosed once a connection has ended,
including when a server rejects a client certificate after the client finished
its half of the TLS 1.3 handshake.
A client connection uses a connected UDP socket, so a peer that refuses
datagrams (no listener on that port) ends the handshake promptly with
ConnectionClosed, a local transport close, instead of waiting for a timeout.
An unreachable host that stays silent is bounded only by your deadline and the
idle timeout.
handshake_until(now, deadline, cancelled) takes an explicit monotonic time,
inclusive deadline and cancellation snapshot, like the TLS stream. Timeout or
cancellation aborts the connection.
close(code) sends CONNECTION_CLOSE with an application error code after
concluded streams have been flushed; call it until it reports Finished.
close_info() reports why a connection ended: its code, whether this side
closed it (including idle timeout), and whether the code is a QUIC transport
error rather than an application code. abort() and dropping release a
connection immediately without notifying the peer, which then waits for its
idle timeout; close first when the peer should know.
Streams
open_bidirectional() and open_unidirectional() return none until the
handshake has completed and while the peer’s stream limit is exhausted;
OpenSSL 3.5 allows each peer 100 concurrent streams of each kind and does not
make that limit configurable. accept_stream() returns the next stream the peer
opened, or none. Stream IDs follow RFC 9000: bit 0 is set for
server-initiated streams and bit 1 for unidirectional ones. readable(),
writable() and local() describe a stream’s direction and origin.
send(source)copies an accepted prefix into the stream’s send buffer and reportsPendingwhen the 512 KiB buffer or the peer’s flow-control window is full. Accepted bytes no longer borrow your storage.receive(destination)copies an initialized prefix.Pendingmeans no data yet;Finishedmeans the peer concluded the stream and every byte was read.conclude()sends FIN after all accepted bytes; it is idempotent, and later sends failClosed.reset(code)abandons the sending part with RESET_STREAM; the peer’s nextreceivefailsStreamResetwithapplication == code.- Dropping a stream that was neither concluded nor reset resets it with code 0. A concluded stream keeps delivering its buffered bytes.
Streams also implement the std/io polling contract with read, write,
poll_read and poll_write. Pending becomes WouldBlock or io.PollState.Pending,
and Finished becomes EOF. A reset or closed connection maps to
io.ErrorKind.ConnectionReset; take_error() returns the typed quic.Error
with its application code.
Event processing and waiting
All objects created from one listener share its socket and event loop, so
processing events on any of them advances all of them. process() handles
received datagrams and expired timers without waiting. wait(milliseconds)
waits for socket readiness until the earlier of your bound (capped at 60 s) and
the next protocol timer, then processes events. timeout_ms() reports when the
next timer is due, or none, for integration with another poller.
The backend starts no threads. Objects are neither Send nor Sync: serialize all calls for one listener or client connection, and its streams, on one execution lane. Releasing a listener or connection while streams still exist is safe; the native state lives until its last object is released.
Errors and limits
| Kind | Meaning and next step |
|---|---|
VerificationFailed |
Check trust roots, hostname or IP SAN, validity dates and verification time; code is the X.509 result. |
ConnectionClosed |
The connection ended; application holds the CONNECTION_CLOSE code and close_info() the details. |
StreamReset |
The peer reset the stream or stopped reading it; application holds its code. Other streams are unaffected. |
Closed |
The object was aborted, or the stream part was concluded or reset locally. |
InvalidInput |
Invalid configuration, or an operation in the wrong direction such as receive on a local unidirectional stream. |
Network |
A socket operation failed; code is the operating-system error. |
TimedOut / Cancelled |
handshake_until aborted the connection. |
Backend / Protocol |
Inspect the numeric code and discard the connection. |
Errors carry only kinds and numbers, never plaintext, keys or certificate text.
QUIC error codes are at most quic.MAX_CODE (2^62 - 1); larger codes fail
InvalidInput.
OpenSSL allocates its connection, packet and stream buffers internally, so
Dodo cannot bound total backend memory; the per-stream send buffer is 512 KiB.
Server address validation (retry tokens) stays enabled. 0-RTT early data,
session resumption, datagrams (RFC 9221), connection migration control and
peer-address queries for accepted connections are not exposed. On Windows the
backend uses Winsock through OpenSSL and links ws2_32.
Verification
cargo test --test quic_library generates a local CA and short-lived leaf/key,
then compiles and runs a Dodo fixture at -O0 and -O3 on IPv4 loopback. It
checks a 1 MiB stream that must hit send-buffer backpressure, the reply, a
server-initiated unidirectional stream released after FIN, stream IDs and
directions, reset codes through the typed and std/io paths, graceful close
codes on both sides, ALPN selection and mismatch, wrong-host, untrusted and
expired rejections, a refused port, mandatory client certificates, idle
timeout, deadline and cancellation aborts, bind conflicts, and invalid
configuration. Further checks
compile the portable std/quic vocabulary for WebAssembly and Cortex-M0,
reject the backend on freestanding targets, and cross-compile it for Windows
x64. No private credential is checked into the repository.
Complete API reference
For every public type, field, constant, and function signature, see std/quic and std/quic/openssl.