quic 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12a202268fc7d9b862cdc0b6577284f5ae98fc275229b129be39f03656ce6967
-  data.tar.gz: eef365c93fcce127f4621ac8aa244ea0b020f239c29bd56bdd5706998852449d
+  metadata.gz: 2598a7b8f6d545c4f092bc5885644fdc6a6cc19406489ebba6dcd40e90d63394
+  data.tar.gz: 71076bbc240ea79b361bac74443748dcbc725e6cb5fcc22ff6587935a1afb9e1
 SHA512:
-  metadata.gz: a6fdb666ea56dc95b50087da5f43a14366416434029e59b4e041f4a7a5eb41a79abbf530403bb7b4505ada4da5387cf6fcba5fc29f8350bc0466bb5ad8f58dc4
-  data.tar.gz: 33f053db5b35c2c7dd428d5e6ad3e29b58b4624f208ebae9593b3bb160fdfd7622942c13d75311ebd854411371f09690627a1f42366d1b3fe24d06362cbe7f36
+  metadata.gz: 6b882c40642e5efdf6a45717c6dba5fe890c26dbe7bbae66ef9b3871e17958773dd7c41877a5b9decf40e0fd6ba03359f632b8f9ca6dc393cabf36600d03acf1
+  data.tar.gz: 29a203887f07455ae6d8d6c76d553bb82fe9c1d72aa2233f797f60093e353dbf028b8b8d3b8f6e40a645b9535cb6b089f4971cf763e96a45af7cc7a494e03a2b

data/CHANGELOG.md

@@ -1,4 +1,25 @@
-## [Unreleased]
+## [0.0.2] - 2026-09-27
+
+### Added
+- Server certificates are now verified, by default against the system's trusted CAs. `QUIC::Settings` gains `verify_mode` (`:peer`, the default, or `:none`), `ca_file` and `ca_path`; setting either of the latter trusts only the certificates found there. The system store is loaded once per process, so `SSL_CERT_FILE` / `SSL_CERT_DIR` are honoured but later changes to them are not picked up. A rejected certificate raises `QUIC::Error::CertificateVerifyFailed`, which carries the X509 error as `#verify_result`. ([#3](https://github.com/unasuke/quic-ruby/pull/3))
+- `QUIC::Error::CryptoError#tls_alert` holds the TLS alert this client sent when a handshake failed in `#read_pkt`. Alerts received from the peer are not recorded. ([#3](https://github.com/unasuke/quic-ruby/pull/3))
+- `QUIC::Connection::Client#close(error_code: 0, reason: "")` sends an application CONNECTION_CLOSE (frame type 0x1d) over the bound socket and transitions ngtcp2 to the closing period. Pre-handshake calls are a best-effort no-op; a second `#close` after the closing/draining period is also a no-op.
+- `QUIC::Connection::Client.new(address_family:)` accepts `:inet` / `:inet6` / `nil` to pin the resolved peer address family, and `QUIC::Connection::Client#remote_address` exposes the resolved `Addrinfo` so callers can line their connected socket's path up with ngtcp2's.
+- `QUIC::Connection::Client#accept_stream(timeout: nil)` / `#accept_stream_nonblock` return peer-initiated (server) streams. `#accept_stream` blocks (driving the I/O loop) until a stream arrives, with `timeout: 0` returning immediately and a `Numeric` timeout returning `nil` after the deadline; `#accept_stream_nonblock` raises `QUIC::Error::WaitReadable` when none is queued.
+- `QUIC::Stream#reset(error_code = 0)` aborts the send side with RESET_STREAM. Subsequent `#write` / `#write_nonblock` raise `QUIC::Error::StreamClosed`.
+- `QUIC.library_versions` now includes a `:picotls` key holding the commit hash picotls was built from, since picotls has neither a version macro nor releases.
+
+### Changed
+- The top-level namespace is now `QUIC` instead of `Quic`, and every constant moves with it: `QUIC::Connection::Client`, `QUIC::Stream`, `QUIC::Settings`, `QUIC::TransportParams`, and `QUIC::Error` together with its subclasses. No `Quic` alias is left behind. The gem name and `require "quic"` are unchanged.
+- The TLS 1.3 handshake is now performed by [picotls](https://github.com/h2o/picotls) instead of LibreSSL's libssl.
+- LibreSSL is no longer vendored. ngtcp2 and picotls are downloaded and built at install time and linked statically, but the cryptographic primitives and X.509 handling now come from the host's OpenSSL (or LibreSSL), linked dynamically and located through `pkg-config` (`--with-openssl-dir=` overrides it). OpenSSL 1.1.1 or later is required, and installing now needs the OpenSSL development package. This shares one libcrypto with Ruby's `openssl` extension: two copies in one process interposed on each other's global symbols, which reported the wrong library version and could segfault depending on `require` order. `QUIC.library_versions[:openssl]` therefore reports the host library.
+- ngtcp2 is now built from 1.25.0 (was 1.22.1), and picotls from `f07f1c8`, the revision ngtcp2 1.25.0 is tested against. ngtcp2 now requires a C11 compiler to build. ([#4](https://github.com/unasuke/quic-ruby/pull/4))
+- quic.so exports only `Init_quic`. The symbols of the statically linked ngtcp2 and picotls are no longer visible to the rest of the process. ([#2](https://github.com/unasuke/quic-ruby/pull/2), by [@hanazuki](https://github.com/hanazuki))
+- `QUIC::Connection::Client` is now GC.compact safe: the C-side struct's back-reference to the owning Ruby object is updated via a `dcompact` slot.
+- The entries in this section were rewritten to state the difference from 0.0.1, rather than the succession of steps that got there. ([#5](https://github.com/unasuke/quic-ruby/pull/5))
+
+### Fixed
+- `QUIC::Stream#read` hung until the idle timeout instead of returning. Both branches of the blocking read waited on a predicate that could never become true once the peer had sent anything, so the read spun in the I/O loop until ngtcp2 gave up. A read that can be satisfied from the receive buffer now performs no I/O at all.
 
 ## [0.0.1] - 2026-05-28
 

data/LICENSE-DEPENDENCIES.txt

@@ -0,0 +1,101 @@
+Licenses of bundled dependencies
+================================
+
+The quic gem downloads ngtcp2 and picotls at install time, builds them on the
+installing machine and links them into quic.so statically. It therefore
+redistributes no third-party binaries; their terms are reproduced below for
+reference. libcrypto is the host's OpenSSL (or LibreSSL) and is neither
+bundled nor redistributed. The quic gem itself is MIT licensed; see
+LICENSE.txt.
+
+
+ngtcp2 1.25.0 -- https://github.com/ngtcp2/ngtcp2
+-------------------------------------------------
+
+The MIT License
+
+Copyright (c) 2016 ngtcp2 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+Portions of ngtcp2
+------------------
+
+ngtcp2 embeds code derived from other projects. Those files are compiled into
+the statically linked libngtcp2 and are covered by their own terms:
+
+  * lib/ngtcp2_pcg.c embeds the PCG random number generator, taken from
+    imneme/pcg-c, and carries "Copyright 2014-2019 Melissa O'Neill
+    <oneill@pcg-random.org>, and the PCG Project contributors". It states
+    "SPDX-License-Identifier: (Apache-2.0 OR MIT)"; under the MIT option its
+    terms are the MIT terms reproduced above.
+
+  * Several files under lib/ carry "Copyright (c) 2012-2023 nghttp2
+    contributors". They are distributed under the same MIT terms as the ngtcp2
+    COPYING text above.
+
+
+picotls f07f1c8 -- https://github.com/h2o/picotls
+-------------------------------------------------
+
+picotls has no top-level license file; the terms are stated in the header of
+each source file. Of the files compiled into libpicotls.a, lib/picotls.c,
+lib/hpke.c and lib/openssl.c are MIT licensed, while lib/pembase64.c is under
+an ISC-style license. Both texts are reproduced below.
+
+The MIT License
+
+Copyright (c) 2016 DeNA Co., Ltd., Kazuho Oku
+Copyright (c) 2022 Fastly, Kazuho Oku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+The ISC-style license
+
+Copyright (c) 2016 Christian Huitema <huitema@huitema.net>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -1,6 +1,6 @@
-# Quic
+# QUIC
 
-`quic` is a thin Ruby binding around [ngtcp2](https://github.com/ngtcp2/ngtcp2) for the QUIC transport protocol, with [LibreSSL](https://github.com/libressl/portable) as the TLS backend. Both dependencies are vendored at install time via [`mini_portile2`](https://github.com/flavorjones/mini_portile) (no system libraries required).
+`quic` is a thin Ruby binding around [ngtcp2](https://github.com/ngtcp2/ngtcp2) for the QUIC transport protocol. TLS 1.3 is handled by [picotls](https://github.com/h2o/picotls). ngtcp2 and picotls are vendored at install time via [`mini_portile2`](https://github.com/flavorjones/mini_portile) and linked statically; the cryptographic primitives and X.509 handling come from the host's OpenSSL (or LibreSSL), linked dynamically.
 
 The gem is intentionally optimized for **synchronous I/O and `String`-based buffers**. It exposes ngtcp2 primitives (`#read_pkt` / `#write_pkt` / `#expiry` / `#handle_expiry`) and lets the caller own the I/O loop. If you need Fiber Scheduler / `IO::Buffer` / `async` ecosystem integration, see [`socketry/protocol-quic`](https://github.com/socketry/protocol-quic) instead.
 
@@ -8,13 +8,74 @@ This project is in early development; the public API is not yet stable.
 
 ## Installation
 
-Not yet released to RubyGems.org. To use from a Gemfile while it is in development:
+```ruby
+gem "quic"
+```
+
+The gem is built from source at install time, so the host needs:
+
+- OpenSSL 1.1.1 or later, **with its development package** (`libssl-dev`, `openssl-devel`, …). LibreSSL works too — see below.
+- `autoconf`, `automake`, `libtool`, `pkg-config` and a C11 compiler, to build ngtcp2.
+- either `patch` or `git`, to apply the picotls patch in `ext/quic/patches/` (`mini_portile2` uses `git apply` when `git` is available and falls back to `patch -p1`).
+
+OpenSSL is located through `pkg-config`. If it lives somewhere `pkg-config` does not look, point at the prefix:
+
+```console
+$ gem install quic -- --with-openssl-dir=$(brew --prefix openssl@3)
+```
+
+Linking the host's libcrypto rather than bundling one is deliberate: the process then shares a single libcrypto with Ruby's own `openssl` extension. Two copies in one process interpose on each other's global symbols, which silently misroutes calls and can crash the VM.
+
+**LibreSSL** is supported and exercised: `ext/quic/patches/picotls/` carries a patch that restores picotls's X25519 key exchange there, which upstream disables because LibreSSL lacks `EVP_PKEY_{get1,set1}_tls_encodedpoint()`. The patch is a no-op on OpenSSL, where X25519 is available anyway.
+
+## Usage
 
 ```ruby
-gem "quic", github: "unasuke/quic-ruby"
+require "quic"
+require "socket"
+
+client = QUIC::Connection::Client.new(
+  host: "cloudflare-quic.com", port: 443, address_family: :inet,
+  settings: QUIC::Settings.default.with(alpn: ["h3"])
+)
+sock = UDPSocket.new(Socket::AF_INET)
+sock.connect(client.remote_address.ip_address, client.remote_address.ip_port)
+client.bind(sock).run # completes the handshake, verifying the certificate
+client.handshake_completed? # => true
 ```
 
-The native extension downloads and builds LibreSSL and ngtcp2 release tarballs during `bundle install`, so the host needs `autoconf`, `automake`, `libtool`, `pkg-config`, and a C toolchain available.
+Pinning the address family and connecting the socket to `client.remote_address` keeps the socket and ngtcp2's connection path on the same peer address; resolving the host name twice could otherwise pick different DNS records.
+
+More complete programs live in [`examples/`](examples/):
+
+- [`handshake_demo.rb`](examples/handshake_demo.rb): prints the library versions and times a handshake.
+- [`echo_demo.rb`](examples/echo_demo.rb): exchanges data on a stream with a local echo server.
+- [`doq_demo.rb`](examples/doq_demo.rb): sends a DNS over QUIC query.
+- [`io_loop_demo.rb`](examples/io_loop_demo.rb): sends the same query from an I/O loop the script owns, calling `#write_pkt` / `#read_pkt` / `#handle_expiry` itself.
+- [`verify_demo.rb`](examples/verify_demo.rb): tries the certificate verification settings described below against a public server.
+
+### Certificate verification
+
+The server certificate is verified by default, against the system's trusted CAs.
+
+Setting `ca_file` (a PEM bundle) or `ca_path` (a hashed certificate directory) trusts only the certificates found there:
+
+```ruby
+settings = QUIC::Settings.default.with(alpn: ["h3"], ca_file: "/path/to/ca.pem")
+```
+
+`verify_mode: :none` turns verification off, for example against a local test server with a self-signed certificate:
+
+```ruby
+settings = QUIC::Settings.default.with(alpn: ["perf"], verify_mode: :none)
+```
+
+## Limitations
+
+- **No certificate revocation checking.** CRLs and OCSP are not consulted.
+- **No session resumption or 0-RTT.**
+- **No server side.** Only the client (`QUIC::Connection::Client`) exists; there is no listen/accept.
+- **Key exchanges and cipher suites are fixed.** X25519, secp256r1 and secp384r1 with AES-128-GCM, AES-256-GCM and ChaCha20-Poly1305. They cannot be selected from Ruby.
 
 ## Development
 
@@ -30,6 +91,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/unasuk
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+The gem ships no third-party binaries: [ngtcp2](https://github.com/ngtcp2/ngtcp2) (MIT, with portions under the Chromium BSD-3-Clause license) and [picotls](https://github.com/h2o/picotls) (MIT, with one file under an ISC-style license) are downloaded and built on the installing machine, and libcrypto is the host's. Their license texts are in [LICENSE-DEPENDENCIES.txt](LICENSE-DEPENDENCIES.txt) for reference.
+
 ## Code of Conduct
 
-Everyone interacting in the Quic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/unasuke/quic-ruby/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the quic-ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/unasuke/quic-ruby/blob/main/CODE_OF_CONDUCT.md).

data/examples/doq_demo.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# DNS over QUIC (RFC 9250) demo: send one DNS query to a public DoQ resolver
+# and print the answers. This exercises the pieces a real protocol needs --
+# ALPN negotiation, a client-initiated bidirectional stream, a half-close via
+# FIN, and reading until the peer closes its side.
+#
+# Three rules from RFC 9250 shape the code below:
+#
+#   * ALPN is "doq" and the default port is 853 (RFC 9250 section 4.1.1, 4.1.2).
+#   * Each query/response pair gets its own bidirectional stream, and the
+#     client signals FIN after the query (section 4.2).
+#   * The DNS message is framed with a 2-octet length prefix, as in DNS over
+#     TCP, and the DNS Message ID must be 0 (section 4.2.1). QUIC stream IDs
+#     already correlate a response with its query, so the DNS-level ID is
+#     redundant and carrying one would leak an identifier.
+#
+# The query is built and parsed with Resolv::DNS::Message from the standard
+# library, so this needs no gems beyond quic itself. It also does not add
+# EDNS(0) padding, which RFC 9250 section 5.5.2 recommends for privacy.
+#
+# Run with: bundle exec ruby examples/doq_demo.rb [name] [type]
+#   bundle exec ruby examples/doq_demo.rb ruby-lang.org AAAA
+#
+# Override the resolver via env vars:
+#   DOQ_HOST  (default dns.quad9.net)
+#   DOQ_PORT  (default 853)
+#
+# Other resolvers this was checked against: dns.adguard-dns.com and
+# unfiltered.adguard-dns.com.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "quic"
+require "resolv"
+require "socket"
+
+TARGET_HOST = ENV.fetch("DOQ_HOST", "dns.quad9.net")
+TARGET_PORT = Integer(ENV.fetch("DOQ_PORT", "853"))
+QUERY_NAME = ARGV[0] || "example.com"
+QUERY_TYPE = ARGV[1] || "A"
+
+# Resolv only gives well-known names to a handful of resource classes; the
+# rest arrive as Resolv::DNS::Resource::TypeNN_ClassNN. Map the numeric type
+# back to a name for display, falling back to the RFC 3597 TYPENN form.
+TYPE_NAMES = %w[A NS CNAME SOA PTR MX TXT AAAA SRV].to_h { |name|
+  [Resolv::DNS::Resource::IN.const_get(name)::TypeValue, name]
+}.freeze
+
+resource_class = begin
+  Resolv::DNS::Resource::IN.const_get(QUERY_TYPE)
+rescue NameError
+  abort "unknown query type: #{QUERY_TYPE}"
+end
+
+# Pin the lookup to one IPv4 address and connect the socket to the address
+# the client resolved, so both talk to the same peer. See
+# examples/handshake_demo.rb for why that matters.
+client = QUIC::Connection::Client.new(
+  host: TARGET_HOST, port: TARGET_PORT, address_family: :inet,
+  settings: QUIC::Settings.default.with(alpn: ["doq"])
+)
+addr = client.remote_address
+sock = UDPSocket.new(Socket::AF_INET)
+sock.connect(addr.ip_address, addr.ip_port)
+
+puts "resolver: #{TARGET_HOST} (#{addr.ip_address}:#{addr.ip_port}), alpn doq"
+puts "query:    #{QUERY_NAME} #{QUERY_TYPE}"
+puts
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+client.bind(sock).run
+handshake_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
+puts "handshake completed in #{handshake_ms}ms"
+
+# Message ID 0, recursion desired.
+query = Resolv::DNS::Message.new(0)
+query.rd = 1
+query.add_question(QUERY_NAME, resource_class)
+wire = query.encode
+
+stream = client.open_bidi_stream
+# The 2-octet length prefix and the message go out together, with FIN: the
+# client has nothing more to send on this stream.
+stream.write([wire.bytesize].pack("n") + wire, fin: true)
+puts "sent #{wire.bytesize} bytes on stream #{stream.id}, half-closed"
+
+# The server answers and closes its side, so read until EOF. With no length,
+# Stream#read returns everything received, or an empty String if nothing was.
+response = stream.read
+abort "resolver closed the stream without a response" if response.bytesize < 2
+
+length = response.unpack1("n")
+body = response.byteslice(2, length)
+if body.nil? || body.bytesize < length
+  abort "truncated response: length prefix says #{length}, got #{response.bytesize - 2}"
+end
+
+answer = Resolv::DNS::Message.decode(body)
+rcode = answer.rcode
+total_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
+puts "received #{body.bytesize} bytes, rcode #{rcode} (#{total_ms}ms total)"
+puts
+
+if answer.answer.empty?
+  puts "(no answer records)"
+else
+  answer.each_answer do |name, ttl, data|
+    value = case data
+    when Resolv::DNS::Resource::IN::A, Resolv::DNS::Resource::IN::AAAA then data.address.to_s
+    when Resolv::DNS::Resource::IN::CNAME, Resolv::DNS::Resource::IN::NS,
+      Resolv::DNS::Resource::IN::PTR then data.name.to_s
+    when Resolv::DNS::Resource::IN::MX then "#{data.preference} #{data.exchange}"
+    when Resolv::DNS::Resource::IN::TXT then data.strings.join(" ")
+    else data.inspect
+    end
+    type_value = data.class::TypeValue
+    puts format("%-34s %6d  %-6s %s", name, ttl, TYPE_NAMES.fetch(type_value, "TYPE#{type_value}"), value)
+  end
+end
+
+client.close
+sock.close

data/examples/echo_demo.rb

@@ -10,6 +10,12 @@
 #   QUIC_ECHO_HOST  (default 127.0.0.1)
 #   QUIC_ECHO_PORT  (default 4433)
 #   QUIC_ECHO_ALPN  (default perf)
+#   QUIC_ECHO_CA_FILE (default unset: the server certificate is not verified)
+#
+# The echo server usually runs with a self-signed certificate, so
+# verification is off unless QUIC_ECHO_CA_FILE names a CA to trust. When it
+# is set, the certificate must match QUIC_ECHO_HOST, which means an IP SAN
+# of 127.0.0.1 with the default host.
 #
 # Run with: bundle exec ruby examples/echo_demo.rb
 
@@ -20,19 +26,23 @@ require "socket"
 TARGET_HOST = ENV.fetch("QUIC_ECHO_HOST", "127.0.0.1")
 TARGET_PORT = Integer(ENV.fetch("QUIC_ECHO_PORT", "4433"))
 TARGET_ALPN = ENV.fetch("QUIC_ECHO_ALPN", "perf")
-
-addr = Addrinfo.getaddrinfo(TARGET_HOST, TARGET_PORT, Socket::AF_INET, Socket::SOCK_DGRAM).first
-sock = UDPSocket.new
-sock.connect(addr.ip_address, addr.ip_port)
-
-settings = Quic::Settings.default.with(alpn: [TARGET_ALPN])
-client = Quic::Connection::Client._open(
-  local_sockaddr: Addrinfo.udp("0.0.0.0", 0).to_sockaddr,
-  remote_sockaddr: addr.to_sockaddr,
-  server_name: TARGET_HOST,
-  transport_params: Quic::TransportParams.default,
-  settings: settings
+TARGET_CA_FILE = ENV["QUIC_ECHO_CA_FILE"]
+
+settings = QUIC::Settings.default.with(alpn: [TARGET_ALPN])
+settings = if TARGET_CA_FILE.nil? || TARGET_CA_FILE.empty?
+  settings.with(verify_mode: :none)
+else
+  settings.with(ca_file: TARGET_CA_FILE)
+end
+
+# Connect the socket to the address the client resolved, so both talk to the
+# same peer (see examples/handshake_demo.rb).
+client = QUIC::Connection::Client.new(
+  host: TARGET_HOST, port: TARGET_PORT, address_family: :inet, settings: settings
 )
+addr = client.remote_address
+sock = UDPSocket.new(Socket::AF_INET)
+sock.connect(addr.ip_address, addr.ip_port)
 client.bind(sock).run
 
 stream = client.open_bidi_stream
@@ -46,4 +56,5 @@ response = stream.read
 puts "received #{response.bytesize} bytes:"
 puts response
 
+client.close
 sock.close

data/examples/handshake_demo.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # Sample script: drive a real QUIC + TLS 1.3 handshake against a public
-# HTTP/3 server (cloudflare-quic.com:443) using Client#bind + Client#run.
+# HTTP/3 server (cloudflare-quic.com:443) using Client#bind + Client#run, and
+# print the library versions the extension was built with.
 #
-# Why _open instead of Client.new: Client.new resolves the hostname via
-# Addrinfo.udp, and UDPSocket#connect resolves it independently. Cloudflare
-# returns multiple A/AAAA records, so the two resolutions can disagree
-# and ngtcp2 then drops every reply with "ignore packet from unknown path".
-# Pre-resolving once to a single IPv4 sockaddr and feeding it to both
-# _open and the socket avoids this.
+# address_family: :inet pins the lookup to a single IPv4 address, and the
+# socket is connected to client.remote_address so that it talks to the same
+# peer as the connection path ngtcp2 holds. Cloudflare returns several A/AAAA
+# records; a second, independent lookup could pick another one, and ngtcp2
+# would then drop every reply as coming from an unknown path.
 #
 # Run with: bundle exec ruby examples/handshake_demo.rb
 
@@ -19,21 +19,17 @@ require "socket"
 TARGET_HOST = "cloudflare-quic.com"
 TARGET_PORT = 443
 
-addr = Addrinfo.getaddrinfo(TARGET_HOST, TARGET_PORT, Socket::AF_INET, Socket::SOCK_DGRAM).first
-sock = UDPSocket.new
-sock.connect(addr.ip_address, addr.ip_port)
-
-settings = Quic::Settings.default.with(alpn: ["h3"])
-client = Quic::Connection::Client._open(
-  local_sockaddr: Addrinfo.udp("0.0.0.0", 0).to_sockaddr,
-  remote_sockaddr: addr.to_sockaddr,
-  server_name: TARGET_HOST,
-  transport_params: Quic::TransportParams.default,
-  settings: settings
+client = QUIC::Connection::Client.new(
+  host: TARGET_HOST, port: TARGET_PORT, address_family: :inet,
+  settings: QUIC::Settings.default.with(alpn: ["h3"])
 )
+addr = client.remote_address
+sock = UDPSocket.new(Socket::AF_INET)
+sock.connect(addr.ip_address, addr.ip_port)
 
-puts "ngtcp2: #{Quic.library_versions[:ngtcp2]}"
-puts "TLS:    #{Quic.library_versions[:openssl]}"
+puts "ngtcp2: #{QUIC.library_versions[:ngtcp2]}"
+puts "picotls: #{QUIC.library_versions[:picotls]}"
+puts "libcrypto: #{QUIC.library_versions[:openssl]}"
 puts "Target: #{TARGET_HOST} (#{addr.ip_address}:#{addr.ip_port})"
 puts
 
@@ -42,4 +38,6 @@ client.bind(sock).run
 elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
 
 puts "handshake_completed? #{client.handshake_completed?} (#{elapsed_ms}ms)"
+
+client.close
 sock.close

data/examples/io_loop_demo.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Caller-owned I/O loop demo: the same DNS over QUIC query as
+# examples/doq_demo.rb, but without Client#bind / #run or the blocking
+# Stream#read / #write. The script owns the socket and the loop, and calls the
+# packet-level primitives itself:
+#
+#   Client#write_pkt       the next datagram to send, or nil when there is
+#                          nothing more to send right now
+#   Client#read_pkt        feed one received datagram to the connection
+#   Client#expiry          the next timer deadline (CLOCK_MONOTONIC in
+#                          nanoseconds), or nil
+#   Client#handle_expiry   run the connection's timers (retransmission,
+#                          idle timeout, ...)
+#   Stream#write_nonblock  queue stream data; raises QUIC::Error::WaitWritable
+#                          when the peer's flow control window is full
+#   Stream#read_nonblock   take received stream data; raises
+#                          QUIC::Error::WaitReadable when none has arrived,
+#                          EOFError once the peer has finished
+#
+# None of these touch the network. Every step that has to wait goes through
+# #pump below, which flushes outgoing packets and then waits for a datagram or
+# the next timer, whichever comes first. That is the part to adapt when the
+# loop has to live inside something else, such as an event loop that also
+# serves other sockets.
+#
+# Run with: bundle exec ruby examples/io_loop_demo.rb [name]
+#
+# Override the resolver via env vars:
+#   DOQ_HOST  (default dns.quad9.net)
+#   DOQ_PORT  (default 853)
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "quic"
+require "resolv"
+require "socket"
+
+TARGET_HOST = ENV.fetch("DOQ_HOST", "dns.quad9.net")
+TARGET_PORT = Integer(ENV.fetch("DOQ_PORT", "853"))
+QUERY_NAME = ARGV[0] || "example.com"
+TIMEOUT_SEC = 10
+
+client = QUIC::Connection::Client.new(
+  host: TARGET_HOST, port: TARGET_PORT, address_family: :inet,
+  settings: QUIC::Settings.default.with(alpn: ["doq"])
+)
+addr = client.remote_address
+sock = UDPSocket.new(Socket::AF_INET)
+sock.connect(addr.ip_address, addr.ip_port)
+
+# read_pkt needs the network path a datagram arrived on, and it has to match
+# the path the connection was created with. Client.new creates it with an
+# unspecified local address (0.0.0.0:0) and the resolved remote address.
+LOCAL_SOCKADDR = Addrinfo.udp("0.0.0.0", 0).to_sockaddr
+REMOTE_SOCKADDR = addr.to_sockaddr
+
+# One turn of the loop: send everything the connection has queued, then wait
+# until a datagram arrives or the next timer is due, and hand that over.
+def pump(client, sock, deadline, stats)
+  while (pkt = client.write_pkt)
+    sock.send(pkt, 0)
+    stats[:sent] += 1
+  end
+
+  now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  abort "timed out after #{TIMEOUT_SEC}s" if now > deadline
+  wait = deadline - now
+  if (expiry = client.expiry)
+    until_expiry = (expiry - Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)) / 1e9
+    wait = until_expiry.clamp(0.0, wait)
+  end
+
+  if IO.select([sock], nil, nil, wait)
+    data, = sock.recvfrom(2048)
+    client.read_pkt(data, local_sockaddr: LOCAL_SOCKADDR, remote_sockaddr: REMOTE_SOCKADDR)
+    stats[:received] += 1
+  else
+    client.handle_expiry
+    stats[:timers] += 1
+  end
+end
+
+stats = Hash.new(0)
+deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TIMEOUT_SEC
+
+puts "resolver: #{TARGET_HOST} (#{addr.ip_address}:#{addr.ip_port}), alpn doq"
+puts "query:    #{QUERY_NAME} A"
+puts
+
+pump(client, sock, deadline, stats) until client.handshake_completed?
+puts "handshake completed: #{stats[:sent]} datagrams sent, #{stats[:received]} received"
+
+# RFC 9250: DNS Message ID 0, framed with a 2-octet length prefix, one
+# bidirectional stream per query, FIN after the query.
+query = Resolv::DNS::Message.new(0)
+query.rd = 1
+query.add_question(QUERY_NAME, Resolv::DNS::Resource::IN::A)
+wire = query.encode
+pending = [wire.bytesize].pack("n") + wire
+
+stream = client.open_bidi_stream
+# write_nonblock queues as much as the flow control window allows and returns
+# that count. FIN only goes out with the last byte, so keep passing fin: true
+# for whatever is left.
+until pending.empty?
+  begin
+    queued = stream.write_nonblock(pending, fin: true)
+    pending = pending.byteslice(queued..)
+  rescue QUIC::Error::WaitWritable
+    pump(client, sock, deadline, stats)
+  end
+end
+puts "queued #{wire.bytesize + 2} bytes + FIN on stream #{stream.id}"
+
+# Nothing has been sent yet: the query leaves on the next pump, which happens
+# here as soon as read_nonblock finds nothing to read.
+response = String.new(encoding: Encoding::BINARY)
+loop do
+  response << stream.read_nonblock(4096)
+rescue QUIC::Error::WaitReadable
+  pump(client, sock, deadline, stats)
+rescue EOFError
+  break
+end
+
+abort "resolver closed the stream without a response" if response.bytesize < 2
+length = response.unpack1("n")
+body = response.byteslice(2, length)
+abort "truncated response" if body.nil? || body.bytesize < length
+
+answer = Resolv::DNS::Message.decode(body)
+puts "received #{body.bytesize} bytes, rcode #{answer.rcode}"
+puts "loop totals: #{stats[:sent]} datagrams sent, #{stats[:received]} received, #{stats[:timers]} timer runs"
+puts
+
+answer.each_answer do |name, ttl, data|
+  next unless data.is_a?(Resolv::DNS::Resource::IN::A)
+  puts format("%-34s %6d  A      %s", name, ttl, data.address)
+end
+
+# Client#close writes the CONNECTION_CLOSE datagram to a bound socket itself,
+# so bind the socket now, only for that.
+client.bind(sock).close
+sock.close