quic 0.0.1 → 0.0.3

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

data/examples/verify_demo.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Server certificate verification demo: handshake with a public QUIC server
+# under a few QUIC::Settings verification configurations and report how each
+# one ends.
+#
+#   1. The defaults: verify_mode :peer against the system CA store.
+#   2. ca_file holding only a throwaway CA generated on the spot. The server's
+#      chain does not lead to it, so the handshake fails with
+#      QUIC::Error::CertificateVerifyFailed.
+#   3. verify_mode :none, which skips verification entirely.
+#   4. ca_file from VERIFY_CA_FILE, when that variable is set.
+#
+# Override the target via env vars:
+#   VERIFY_HOST     (default cloudflare-quic.com)
+#   VERIFY_PORT     (default 443)
+#   VERIFY_ALPN     (default h3)
+#   VERIFY_CA_FILE  (default unset: step 4 is skipped)
+#
+# Each attempt connects its socket to the address its client resolved, so
+# both talk to the same peer (see examples/handshake_demo.rb).
+#
+# Run with: bundle exec ruby examples/verify_demo.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "quic"
+require "socket"
+require "openssl"
+require "tmpdir"
+
+TARGET_HOST = ENV.fetch("VERIFY_HOST", "cloudflare-quic.com")
+TARGET_PORT = Integer(ENV.fetch("VERIFY_PORT", "443"))
+TARGET_ALPN = ENV.fetch("VERIFY_ALPN", "h3")
+TARGET_CA_FILE = ENV["VERIFY_CA_FILE"]
+
+# A self-signed CA that no real server chains to, written as PEM into dir.
+def write_untrusted_ca(dir)
+  key = OpenSSL::PKey::EC.generate("prime256v1")
+  name = OpenSSL::X509::Name.parse("/CN=quic-ruby verify_demo CA")
+  cert = OpenSSL::X509::Certificate.new
+  cert.version = 2
+  cert.serial = 1
+  cert.subject = name
+  cert.issuer = name
+  cert.public_key = key
+  cert.not_before = Time.now - 60
+  cert.not_after = Time.now + 3600
+  factory = OpenSSL::X509::ExtensionFactory.new(cert, cert)
+  cert.add_extension(factory.create_extension("basicConstraints", "CA:TRUE", true))
+  cert.add_extension(factory.create_extension("keyUsage", "keyCertSign,cRLSign", true))
+  cert.sign(key, OpenSSL::Digest.new("SHA256"))
+  File.join(dir, "untrusted-ca.pem").tap { |path| File.write(path, cert.to_pem) }
+end
+
+# verify_result is an X509_V_ERR_* value; show the matching Ruby constant.
+def verify_result_name(value)
+  name = OpenSSL::X509.constants.grep(/\AV_ERR_/).find { |c| OpenSSL::X509.const_get(c) == value }
+  name ? "OpenSSL::X509::#{name}" : "unknown"
+end
+
+def handshake(label, settings)
+  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)
+
+  puts "== #{label} (#{addr.ip_address}:#{addr.ip_port})"
+  puts "   verify_mode=#{settings.verify_mode.inspect} ca_file=#{settings.ca_file.inspect} ca_path=#{settings.ca_path.inspect}"
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  client.bind(sock).run
+  elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
+  puts "   handshake completed (#{elapsed_ms}ms)"
+  client.close
+rescue QUIC::Error::CertificateVerifyFailed => e
+  puts "   #{e.class}: #{e.message}"
+  puts "   verify_result=#{e.verify_result.inspect} (#{verify_result_name(e.verify_result)})"
+  puts "   tls_alert=#{e.tls_alert.inspect}"
+rescue QUIC::Error::CryptoError => e
+  puts "   #{e.class}: #{e.message} (tls_alert=#{e.tls_alert.inspect})"
+rescue QUIC::Error => e
+  puts "   #{e.class}: #{e.message}"
+ensure
+  sock&.close
+  puts
+end
+
+puts "libcrypto: #{QUIC.library_versions[:openssl]}"
+puts "Target: #{TARGET_HOST}:#{TARGET_PORT}, alpn #{TARGET_ALPN}"
+puts
+
+base = QUIC::Settings.default.with(alpn: [TARGET_ALPN])
+
+handshake("system CA store (default)", base)
+
+Dir.mktmpdir do |dir|
+  handshake("ca_file with an unrelated CA", base.with(ca_file: write_untrusted_ca(dir)))
+end
+
+handshake("verify_mode :none (not verified)", base.with(verify_mode: :none))
+
+if TARGET_CA_FILE && !TARGET_CA_FILE.empty?
+  handshake("ca_file from VERIFY_CA_FILE", base.with(ca_file: TARGET_CA_FILE))
+end