quic 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9032a4ca3ee79288be00be635d283adcfe5435a9aea166e9c15868f051b675ea
-  data.tar.gz: 52377290a15ad9644312b2db8350bfe3979834eae926be6cd9e1e460e0091b01
+  metadata.gz: e019da100b72501ae5f3f097aa00344e763de5483e301b03e619c695e7ed269d
+  data.tar.gz: 922faa6c8b6b96e121849d4f17823e31cbfdeb05da3d93681603c3fb55840127
 SHA512:
-  metadata.gz: 9df57929c35a332b353df2c2955a1799e42a94d0a9afb4b1b697df085daba67aca60c2a906fd3f76c1eb07ac2cbb48d657ee12a44c87d41a4d881275ae596d8a
-  data.tar.gz: 340e5424b7fe6dc6aad37dd5be581d5d4e077b062f480e1f60d5a6c7c13d296425a66244b1278a35ed1b1cd125d052df1c8dd57e9989ebf3741c650a22f5fe51
+  metadata.gz: c1eb1754a7e98f652825f641d0a1bfb2c131d54fcaceffe2867b8000107752d39c7fcc9e739125085c84bb76272306213e5774730e408b4d6cfc2bb6ce61b5c9
+  data.tar.gz: 365881fb77b46679c549f6e19dc5988cd94f62a3ab13ee937e0514d12202a45a63c17501c6bf492b6363b2b33c81894651965f74425e44af37cc2e24f37c0aa5

data/.clang-format

@@ -0,0 +1 @@
+BasedOnStyle: LLVM

data/.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Format the C sources with clang-format
+cb0c551641efd2c29377ffcc1f8e1b9999926544

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.0.4] - 2026-10-22
+
+### Added
+- `examples/echo_endpoint_demo.rb`, the echo server for `examples/echo_demo.rb` on a `QUIC::Endpoint`. It serves many clients at once from an I/O loop of its own, and writes qlog when `QUIC_ECHO_QLOG_DIR` is set. ([#18](https://github.com/unasuke/quic-ruby/pull/18))
+- The README documents `QUIC::Endpoint`, `QUIC::TLSContext`, `Settings#qlog_dir` and `quic/ext.h`. Its Limitations no longer say that a server handles one connection per socket, and list instead the lack of Retry and address validation, and of client certificate authentication. ([#18](https://github.com/unasuke/quic-ruby/pull/18))
+
+### Fixed
+- A connection's qlog file is closed once the connection ends, instead of when the connection is garbage collected. ([#19](https://github.com/unasuke/quic-ruby/pull/19))
+
 ## [0.0.3] - 2026-10-13
 
 ### Added

data/README.md

@@ -51,6 +51,7 @@ 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.
 - [`echo_server_demo.rb`](examples/echo_server_demo.rb): the echo server for `echo_demo.rb`, generating its own certificate.
+- [`echo_endpoint_demo.rb`](examples/echo_endpoint_demo.rb): the same echo server on a `QUIC::Endpoint`, serving many clients at once from an I/O loop of its own, and writing qlog when `QUIC_ECHO_QLOG_DIR` is set.
 - [`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.
@@ -77,7 +78,46 @@ rescue QUIC::Error::Closed
 end
 ```
 
-`accept` connects the socket to the first client that sends to it and serves that one connection only. [`echo_server_demo.rb`](examples/echo_server_demo.rb) generates its own certificate, so it runs as is against `echo_demo.rb`.
+`accept` connects the socket to the first client that sends to it and serves that one connection only; to serve many clients on one socket, use a `QUIC::Endpoint` (below). [`echo_server_demo.rb`](examples/echo_server_demo.rb) generates its own certificate, so it runs as is against `echo_demo.rb`.
+
+### Many connections on one socket
+
+`QUIC::Endpoint` serves many connections on one UDP socket. It routes each datagram to its connection by connection ID, makes a connection for each new client, and answers what no connection can: Version Negotiation for a version it does not support, a Stateless Reset for a packet of a connection it does not know, and CONNECTION_REFUSED beyond `max_connections` (1024 by default) or after `#stop_accepting`. The socket and the I/O loop stay with you:
+
+```ruby
+require "quic"
+require "socket"
+
+tls = QUIC::TLSContext.server(
+  certificate_path: "server.pem", private_key_path: "server.key", alpn: ["perf"]
+)
+sock = UDPSocket.new(Socket::AF_INET)
+sock.bind("127.0.0.1", 4433) # the address it serves, not 0.0.0.0
+endpoint = QUIC::Endpoint.new(local_address: sock.local_address, tls_context: tls)
+
+loop do
+  expiry = endpoint.expiry # CLOCK_MONOTONIC in nanoseconds, or nil
+  now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+  if IO.select([sock], nil, nil, expiry && [expiry - now, 0].max / 1e9)
+    data, sender = sock.recvmsg(65_535)
+    endpoint.read_pkt(data, remote: sender.to_sockaddr) # the connection it went to
+  end
+  endpoint.handle_expiry
+
+  endpoint.connections.each do |conn|
+    # conn.accept_stream_nonblock, Stream#read_nonblock, Stream#write_nonblock
+  end
+
+  while (packet, to = endpoint.write_pkt)
+    sock.send(packet, 0, to)
+  end
+  endpoint.take_closed.each { |conn| warn conn.error.inspect if conn.error }
+end
+```
+
+The connections are `QUIC::Connection::Server`s without a socket of their own, so only their non-blocking methods work, and `#close` queues its CONNECTION_CLOSE for `Endpoint#write_pkt`. A connection's failure never raises from the Endpoint: it closes that connection alone, and the connection's `#error` tells why. The Endpoint's own answers wait for `#write_pkt` in a queue of at most 1024, and any beyond are dropped, so call it often under load. [`echo_endpoint_demo.rb`](examples/echo_endpoint_demo.rb) fills in the streams and runs against `echo_demo.rb`.
+
+`QUIC::TLSContext.server` reads the certificate chain (PEM, leaf first) and the private key once, for every connection made from it to share. To put a renewed certificate in place, assign a new context: `endpoint.tls_context = QUIC::TLSContext.server(...)`. New connections use it, and existing ones keep the context they started with.
 
 ### Certificate verification
 
@@ -95,11 +135,45 @@ settings = QUIC::Settings.default.with(alpn: ["h3"], ca_file: "/path/to/ca.pem")
 settings = QUIC::Settings.default.with(alpn: ["perf"], verify_mode: :none)
 ```
 
+### qlog
+
+`qlog_dir` makes every connection write its [qlog](https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/) to `<qlog_dir>/<its first source connection ID in hex>.sqlog`:
+
+```ruby
+settings = QUIC::Settings.default.with(alpn: ["h3"], qlog_dir: "/tmp/qlog")
+```
+
+It applies to clients, `Connection::Server.accept` and every connection of an Endpoint. `Client.new`, `Server.accept` and `Endpoint.new` raise `ArgumentError` unless it is a writable directory. A file that cannot be opened later, when a connection is made, only costs that connection its qlog. A connection's file is closed as soon as the connection ends, not when the connection is garbage collected.
+
+### From other native extensions
+
+Another native extension can drive a connection's streams from C instead of through `QUIC::Stream`, as the [http3](https://github.com/unasuke/http3-ruby) gem does. `quic/ext.h` declares the function table (ABI 1.0), and `QUIC::EXT_INCLUDE_DIR` tells an `extconf.rb` where it is:
+
+```ruby
+require "mkmf"
+require "quic/ext_include"
+
+append_cppflags("-I#{QUIC::EXT_INCLUDE_DIR}")
+```
+
+At run time, look the table up once `quic` is loaded. `rb_ext_resolve_symbol` needs Ruby 3.3 or later:
+
+```c
+#include <quic/ext.h>
+
+rb_require("quic");
+quic_ext_get_api_fn get = (quic_ext_get_api_fn)rb_ext_resolve_symbol("quic/quic", "quic_ext_get_api");
+const quic_ext_api *api = get ? get(QUIC_EXT_ABI_MAJOR) : NULL; /* NULL: a different ABI major */
+```
+
+A connection given a stream handler with `set_stream_handler` makes no `QUIC::Stream`: the handler receives every stream's data and hands out what to send as `#write_pkt` builds each packet, and `#open_bidi_stream`, `#accept_stream` and the like raise `QUIC::Error::InvalidState`. The comment at the top of [`ext.h`](ext/quic/include/quic/ext.h) states the rules on versions, exceptions and lifetimes.
+
 ## Limitations
 
 - **No certificate revocation checking.** CRLs and OCSP are not consulted.
 - **No session resumption or 0-RTT.**
-- **The server handles one connection per socket.** `QUIC::Connection::Server.accept` serves the first client that sends to the socket; there is no Retry, address validation, Version Negotiation, or client certificate authentication.
+- **No Retry or address validation.** An Endpoint makes a connection for any Initial packet without checking that its sender owns the source address, so Initial packets with forged addresses can fill `max_connections` for `handshake_timeout` (10 seconds by default) and keep real clients out meanwhile.
+- **No client certificate authentication.** A server does not ask for a client certificate.
 - **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

data/examples/demo_certificates.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Throwaway certificates for the server demos (echo_server_demo.rb and
+# echo_endpoint_demo.rb), so that they run without any certificate files.
+
+require "ipaddr"
+require "openssl"
+
+module DemoCertificates
+  # Write a CA and a server certificate it signed (EC P-256, valid for one
+  # day), with the server's private key, into dir. The server certificate
+  # names localhost, 127.0.0.1 and host. Returns the paths of the CA, the
+  # server certificate and the key.
+  def self.generate(dir, host)
+    now = Time.now
+
+    ca_key = OpenSSL::PKey::EC.generate("prime256v1")
+    ca_name = OpenSSL::X509::Name.parse("/CN=quic-ruby echo server demo CA")
+    ca_cert = OpenSSL::X509::Certificate.new
+    ca_cert.version = 2
+    ca_cert.serial = 1
+    ca_cert.subject = ca_name
+    ca_cert.issuer = ca_name
+    ca_cert.public_key = ca_key
+    ca_cert.not_before = now - 60
+    ca_cert.not_after = now + 86_400
+    factory = OpenSSL::X509::ExtensionFactory.new(ca_cert, ca_cert)
+    ca_cert.add_extension(factory.create_extension("basicConstraints", "CA:TRUE", true))
+    ca_cert.add_extension(factory.create_extension("keyUsage", "keyCertSign,cRLSign", true))
+    ca_cert.sign(ca_key, OpenSSL::Digest.new("SHA256"))
+
+    server_key = OpenSSL::PKey::EC.generate("prime256v1")
+    server_cert = OpenSSL::X509::Certificate.new
+    server_cert.version = 2
+    server_cert.serial = 2
+    server_cert.subject = OpenSSL::X509::Name.parse("/CN=localhost")
+    server_cert.issuer = ca_name
+    server_cert.public_key = server_key
+    server_cert.not_before = now - 60
+    server_cert.not_after = now + 86_400
+    factory = OpenSSL::X509::ExtensionFactory.new(ca_cert, server_cert)
+    server_cert.add_extension(factory.create_extension("subjectAltName", subject_alt_names(host)))
+    server_cert.add_extension(factory.create_extension("extendedKeyUsage", "serverAuth"))
+    server_cert.sign(ca_key, OpenSSL::Digest.new("SHA256"))
+
+    paths = %w[ca.pem server.pem server.key].map { |name| File.join(dir, name) }
+    File.write(paths[0], ca_cert.to_pem)
+    File.write(paths[1], server_cert.to_pem)
+    File.write(paths[2], server_key.private_to_pem)
+    paths
+  end
+
+  # localhost and 127.0.0.1, plus the bind address so that echo_demo.rb can
+  # verify the certificate against QUIC_ECHO_HOST.
+  def self.subject_alt_names(host)
+    names = ["DNS:localhost", "IP:127.0.0.1"]
+    entry = begin
+      IPAddr.new(host)
+      "IP:#{host}"
+    rescue IPAddr::InvalidAddressError
+      "DNS:#{host}"
+    end
+    names << entry unless names.include?(entry)
+    names.join(",")
+  end
+  private_class_method :subject_alt_names
+end

data/examples/echo_endpoint_demo.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# Echo server for examples/echo_demo.rb that serves many clients at once
+# through QUIC::Endpoint: one UDP socket, an I/O loop this script owns, and
+# the connections' non-blocking stream methods. Like echo_server_demo.rb, it
+# echoes every stream back (reads up to its FIN, then writes it all back
+# with FIN). It runs until Ctrl-C, which closes every connection.
+#
+# No certificate files are needed. A throwaway CA and a server certificate it
+# signed are generated at startup (see demo_certificates.rb), and the CA's
+# path is printed; the files are removed when the server exits.
+#
+# echo_demo.rb reads the same env vars, so it connects without any setup:
+#   QUIC_ECHO_HOST      address to bind (default 127.0.0.1); also added to
+#                       the certificate's SAN. Not 0.0.0.0: an Endpoint
+#                       needs the address it serves.
+#   QUIC_ECHO_PORT      (default 4433)
+#   QUIC_ECHO_ALPN      (default perf)
+#   QUIC_ECHO_QLOG_DIR  a directory to write each connection's qlog to
+#                       (default unset: no qlog)
+#
+# Run with: bundle exec ruby examples/echo_endpoint_demo.rb
+# then, from other terminals: bundle exec ruby examples/echo_demo.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "quic"
+require "socket"
+require "tmpdir"
+require_relative "demo_certificates"
+
+BIND_HOST = ENV.fetch("QUIC_ECHO_HOST", "127.0.0.1")
+BIND_PORT = Integer(ENV.fetch("QUIC_ECHO_PORT", "4433"))
+ALPN = ENV.fetch("QUIC_ECHO_ALPN", "perf")
+QLOG_DIR = ENV["QUIC_ECHO_QLOG_DIR"]
+# Datagrams read in one round of the loop at most, so that a flood of them
+# does not hold up the timers and the sending.
+RECV_BATCH = 64
+
+# One client stream: read it up to its FIN, then write it all back with FIN.
+class EchoStream
+  attr_reader :size
+
+  def initialize(stream)
+    @stream = stream
+    @data = +""
+    @reading = true
+  end
+
+  def id
+    @stream.id
+  end
+
+  # Moves the echo on as far as it can without blocking. Returns true once
+  # all of it, FIN included, is queued for sending.
+  def step
+    read while @reading
+    write
+  rescue QUIC::Error::WaitReadable, QUIC::Error::WaitWritable
+    false
+  end
+
+  private
+
+  def read
+    @data << @stream.read_nonblock(65_536)
+  rescue EOFError
+    @reading = false
+    @size = @data.bytesize
+  end
+
+  # write_nonblock queues as much as the client's flow control window has
+  # room for, and sends the FIN only along with the last byte.
+  def write
+    loop do
+      queued = @stream.write_nonblock(@data, fin: true)
+      return true if queued == @data.bytesize
+
+      @data = @data.byteslice(queued..)
+    end
+  end
+end
+
+# The streams conn's client has opened since the last call.
+def accepted_streams(conn)
+  streams = []
+  loop { streams << conn.accept_stream_nonblock }
+rescue QUIC::Error::WaitReadable
+  streams
+end
+
+def now_ns
+  Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+end
+
+def flush(endpoint, sock)
+  while (packet, to = endpoint.write_pkt)
+    sock.send(packet, 0, to)
+  end
+end
+
+Dir.mktmpdir("quic-echo-endpoint-") do |dir|
+  ca_file, certificate_path, private_key_path = DemoCertificates.generate(dir, BIND_HOST)
+  tls_context = QUIC::TLSContext.server(
+    certificate_path: certificate_path, private_key_path: private_key_path, alpn: [ALPN]
+  )
+  settings = QUIC::Settings.default
+  settings = settings.with(qlog_dir: QLOG_DIR) if QLOG_DIR
+
+  sock = UDPSocket.new(Socket::AF_INET)
+  sock.bind(BIND_HOST, BIND_PORT)
+  endpoint = QUIC::Endpoint.new(local_address: sock.local_address, tls_context: tls_context, settings: settings)
+  puts "listening on #{sock.local_address.inspect_sockaddr} (UDP), ALPN #{ALPN}"
+  puts "CA certificate: #{ca_file}"
+  puts "try a verified connection with:"
+  puts "  QUIC_ECHO_CA_FILE=#{ca_file} bundle exec ruby examples/echo_demo.rb"
+  puts "(without QUIC_ECHO_CA_FILE, echo_demo.rb does not verify the certificate)"
+  puts "writing qlog to #{QLOG_DIR}" if QLOG_DIR
+  puts
+
+  peers = {} # connection => its client's address
+  echoes = Hash.new { |hash, conn| hash[conn] = [] } # connection => its unfinished EchoStreams
+
+  begin
+    loop do
+      expiry = endpoint.expiry
+      timeout = expiry && [expiry - now_ns, 0].max / 1e9
+      if IO.select([sock], nil, nil, timeout)
+        RECV_BATCH.times do
+          data, sender = sock.recvmsg_nonblock(65_535, exception: false)
+          break if data == :wait_readable
+
+          conn = endpoint.read_pkt(data, remote: sender.to_sockaddr)
+          if conn && !peers.key?(conn)
+            peers[conn] = sender.inspect_sockaddr
+            puts "#{peers[conn]}: connected"
+          end
+        end
+      end
+      endpoint.handle_expiry
+
+      # The connections have no socket of their own, so only their
+      # non-blocking methods work.
+      endpoint.connections.each do |conn|
+        echoes[conn].concat(accepted_streams(conn).map { |stream| EchoStream.new(stream) })
+        echoes[conn].reject! do |echo|
+          next false unless echo.step
+
+          puts "#{peers[conn]}: stream #{echo.id}: echoed #{echo.size} bytes"
+          true
+        end
+      end
+
+      flush(endpoint, sock)
+
+      endpoint.take_closed.each do |conn|
+        echoes.delete(conn)
+        reason = conn.error ? " (#{conn.error.class}: #{conn.error.message})" : ""
+        puts "#{peers.delete(conn)}: closed#{reason}"
+      end
+    end
+  rescue Interrupt
+    puts
+    puts "closing #{endpoint.connections.size} connection(s)"
+    endpoint.stop_accepting
+    endpoint.connections.each(&:close)
+    flush(endpoint, sock)
+  end
+
+  sock.close
+end

data/examples/echo_server_demo.rb

@@ -20,73 +20,17 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "quic"
-require "ipaddr"
-require "openssl"
 require "socket"
 require "tmpdir"
+require_relative "demo_certificates"
 
 BIND_HOST = ENV.fetch("QUIC_ECHO_HOST", "127.0.0.1")
 BIND_PORT = Integer(ENV.fetch("QUIC_ECHO_PORT", "4433"))
 ALPN = ENV.fetch("QUIC_ECHO_ALPN", "perf")
 ACCEPT_TIMEOUT = 10
 
-# localhost and 127.0.0.1, plus the bind address so that echo_demo.rb can
-# verify the certificate against QUIC_ECHO_HOST.
-def subject_alt_names(host)
-  names = ["DNS:localhost", "IP:127.0.0.1"]
-  entry = begin
-    IPAddr.new(host)
-    "IP:#{host}"
-  rescue IPAddr::InvalidAddressError
-    "DNS:#{host}"
-  end
-  names << entry unless names.include?(entry)
-  names.join(",")
-end
-
-# Write a CA and a server certificate it signed (EC P-256, valid for one
-# day), with the server's private key, into dir. Returns the three paths.
-def generate_certificates(dir, host)
-  now = Time.now
-
-  ca_key = OpenSSL::PKey::EC.generate("prime256v1")
-  ca_name = OpenSSL::X509::Name.parse("/CN=quic-ruby echo server demo CA")
-  ca_cert = OpenSSL::X509::Certificate.new
-  ca_cert.version = 2
-  ca_cert.serial = 1
-  ca_cert.subject = ca_name
-  ca_cert.issuer = ca_name
-  ca_cert.public_key = ca_key
-  ca_cert.not_before = now - 60
-  ca_cert.not_after = now + 86_400
-  factory = OpenSSL::X509::ExtensionFactory.new(ca_cert, ca_cert)
-  ca_cert.add_extension(factory.create_extension("basicConstraints", "CA:TRUE", true))
-  ca_cert.add_extension(factory.create_extension("keyUsage", "keyCertSign,cRLSign", true))
-  ca_cert.sign(ca_key, OpenSSL::Digest.new("SHA256"))
-
-  server_key = OpenSSL::PKey::EC.generate("prime256v1")
-  server_cert = OpenSSL::X509::Certificate.new
-  server_cert.version = 2
-  server_cert.serial = 2
-  server_cert.subject = OpenSSL::X509::Name.parse("/CN=localhost")
-  server_cert.issuer = ca_name
-  server_cert.public_key = server_key
-  server_cert.not_before = now - 60
-  server_cert.not_after = now + 86_400
-  factory = OpenSSL::X509::ExtensionFactory.new(ca_cert, server_cert)
-  server_cert.add_extension(factory.create_extension("subjectAltName", subject_alt_names(host)))
-  server_cert.add_extension(factory.create_extension("extendedKeyUsage", "serverAuth"))
-  server_cert.sign(ca_key, OpenSSL::Digest.new("SHA256"))
-
-  paths = %w[ca.pem server.pem server.key].map { |name| File.join(dir, name) }
-  File.write(paths[0], ca_cert.to_pem)
-  File.write(paths[1], server_cert.to_pem)
-  File.write(paths[2], server_key.private_to_pem)
-  paths
-end
-
 Dir.mktmpdir("quic-echo-server-") do |dir|
-  ca_file, certificate_path, private_key_path = generate_certificates(dir, BIND_HOST)
+  ca_file, certificate_path, private_key_path = DemoCertificates.generate(dir, BIND_HOST)
 
   sock = UDPSocket.new(Socket::AF_INET)
   sock.bind(BIND_HOST, BIND_PORT)