quic 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2598a7b8f6d545c4f092bc5885644fdc6a6cc19406489ebba6dcd40e90d63394
-  data.tar.gz: 71076bbc240ea79b361bac74443748dcbc725e6cb5fcc22ff6587935a1afb9e1
+  metadata.gz: e019da100b72501ae5f3f097aa00344e763de5483e301b03e619c695e7ed269d
+  data.tar.gz: 922faa6c8b6b96e121849d4f17823e31cbfdeb05da3d93681603c3fb55840127
 SHA512:
-  metadata.gz: 6b882c40642e5efdf6a45717c6dba5fe890c26dbe7bbae66ef9b3871e17958773dd7c41877a5b9decf40e0fd6ba03359f632b8f9ca6dc393cabf36600d03acf1
-  data.tar.gz: 29a203887f07455ae6d8d6c76d553bb82fe9c1d72aa2233f797f60093e353dbf028b8b8d3b8f6e40a645b9535cb6b089f4971cf763e96a45af7cc7a494e03a2b
+  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,36 @@
+## [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
+- `QUIC::Connection::Server` serves a single connection per UDP socket. `Server.accept(sock:, certificate_path:, private_key_path:, transport_params: nil, settings: nil)` waits for the first datagram, connects the socket to its sender and returns a Server whose handshake `#run` completes; streams, `#accept_stream` and `#close` then work as on a Client. The certificate file is PEM, leaf first, and `settings` must name at least one ALPN protocol; `verify_mode`, `ca_file` and `ca_path` are ignored, since no client certificate is requested. A certificate or key that cannot be loaded or used, or an empty ALPN list, raises `ArgumentError`; a first datagram that cannot start a connection raises `QUIC::Error::Proto`. There is no Retry, address validation or Version Negotiation, and `Server.new` is private. ([#9](https://github.com/unasuke/quic-ruby/pull/9))
+- `QUIC::Stream#closed?` returns true once both directions of the stream have finished and everything sent has been acknowledged. It stays false if the connection closes first. ([#9](https://github.com/unasuke/quic-ruby/pull/9))
+- A C function table for other native extensions, declared in `quic/ext.h` (ABI 1.0). An extension looks up `quic_ext_get_api` with `rb_ext_resolve_symbol` (Ruby 3.3 or later) and registers a C stream handler on a connection; the handler then owns every stream of that connection, receiving stream data and handing out what to send as `#write_pkt` builds each packet. `QUIC::EXT_INCLUDE_DIR` tells an extconf.rb where the header is. quic.so now exports `quic_ext_get_api` besides `Init_quic`; ngtcp2 and picotls stay hidden. ([#12](https://github.com/unasuke/quic-ruby/pull/12))
+- `QUIC::Error::InvalidState`, raised by `#open_bidi_stream`, `#open_uni_stream`, `#accept_stream` and `#accept_stream_nonblock` of a connection whose streams belong to a C stream handler. ([#12](https://github.com/unasuke/quic-ruby/pull/12))
+- `QUIC::TLSContext.server(certificate_path:, private_key_path:, alpn:)` reads a server's certificate chain and private key once and keeps them with its ALPN protocols, for every connection made from it to share. A connection holds on to the context it started with. The checks and `ArgumentError` messages are those of `Server.accept`, which now builds one inside; `TLSContext.new` raises `TypeError`. ([#13](https://github.com/unasuke/quic-ruby/pull/13))
+- `QUIC::Endpoint` serves many connections on one unconnected UDP socket, leaving the socket and the I/O loop to the caller. `Endpoint.new(local_address:, tls_context:, transport_params: nil, settings: nil, max_connections: 1024)`; `#read_pkt(packet, remote:, local: nil)` routes a datagram by its connection ID and returns the `Connection::Server` it went to, making one for a new client; `#write_pkt` returns `[packet, sockaddr]` pairs until nil; `#expiry` and `#handle_expiry` run every connection's timers; `#take_closed` hands out the connections that have finished; `#connections`, `#stop_accepting` and `#tls_context=` complete it. It answers an unsupported version with Version Negotiation, a packet for an unknown connection with a Stateless Reset (at most 100 in a burst, then one a second), and a new connection beyond `max_connections` or after `#stop_accepting` with CONNECTION_REFUSED. At most 1024 of these answers wait for `#write_pkt`; any beyond are dropped. A connection's own failure closes that connection alone and never raises from the Endpoint. Its connections have no socket: `#close` queues the CONNECTION_CLOSE for `#write_pkt`, and only non-blocking stream methods work. There is no Retry or address validation. ([#14](https://github.com/unasuke/quic-ruby/pull/14))
+- `QUIC::Connection::Server#error` (and `Client#error`) tells why an Endpoint closed the connection: nil when the peer closed it, it timed out idle or `#close` was called, the exception itself when Ruby code in a callback raised, and otherwise a `QUIC::Error` made from ngtcp2's error code. It is always nil for a connection no Endpoint made. ([#14](https://github.com/unasuke/quic-ruby/pull/14))
+- `QUIC::Settings#qlog_dir` (a String or Pathname, nil by default) makes every connection write its qlog to `<qlog_dir>/<its first source connection ID in hex>.sqlog`. `Client.new`, `Connection::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. ([#15](https://github.com/unasuke/quic-ruby/pull/15))
+
+### Changed
+- The extension no longer uses the ngtcp2 functions and callbacks deprecated in 1.22.0 and 1.23.0, and calls their `*2` replacements instead. Behavior is unchanged. ([#8](https://github.com/unasuke/quic-ruby/pull/8))
+- `#accept_stream_nonblock` now raises `QUIC::Error::WaitReadable` with "no peer-initiated stream available" (was "no server-initiated stream available"), as it serves `QUIC::Connection::Server` too. ([#9](https://github.com/unasuke/quic-ruby/pull/9))
+- picotls's `lib/pembase64.c`, a PEM loader nothing uses, is no longer built at install time, so every picotls source compiled into the gem is MIT licensed. ([#10](https://github.com/unasuke/quic-ruby/pull/10))
+
+### Fixed
+- `QUIC::Stream#read` and `#read_nonblock` give the peer flow control credit back for what they hand to the application. Before, a connection stopped receiving once `initial_max_data` (1 MiB by default) had been used up. ([#11](https://github.com/unasuke/quic-ruby/pull/11))
+- When a stream the peer opened closes, the peer may open another one. Before, it could open only `initial_max_streams_bidi` bidirectional streams over the whole connection. A stream that closes while it waits for `#accept_stream` is given back only once it has been accepted, so that the streams waiting there stay within that limit. ([#11](https://github.com/unasuke/quic-ruby/pull/11))
+- An exception raised by Ruby code inside an ngtcp2 callback (for example a `FrozenError`) comes out of `#read_pkt`, `#write_pkt` or `#handle_expiry` instead of unwinding through ngtcp2. ([#11](https://github.com/unasuke/quic-ruby/pull/11))
+- `QUIC::Stream#write` and `#write_nonblock` count the bytes already queued but not yet sent against the peer's window, and `#write_pkt` no longer raises `QUIC::Error::FlowControl` when that window is full; the data waits until the peer extends it. ([#11](https://github.com/unasuke/quic-ruby/pull/11))
+- `#read_pkt`, `Client._open` and `Server._accept` raise `ArgumentError` for a sockaddr String other than an AF_INET or AF_INET6 sockaddr of that family's exact size, as `Addrinfo#to_sockaddr` makes. ngtcp2 copied an address of any length into room for a `sockaddr_in6`, so a longer String overran the heap. ([#14](https://github.com/unasuke/quic-ruby/pull/14))
+
 ## [0.0.2] - 2026-09-27
 
 ### Added

data/LICENSE-DEPENDENCIES.txt

@@ -57,9 +57,8 @@ 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.
+each source file. The files compiled into libpicotls.a, lib/picotls.c,
+lib/hpke.c and lib/openssl.c, are MIT licensed; the text is reproduced below.
 
 The MIT License
 
@@ -83,19 +82,3 @@ 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

@@ -50,10 +50,75 @@ 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.
 
+### Server
+
+```ruby
+require "quic"
+require "socket"
+
+sock = UDPSocket.new(Socket::AF_INET)
+sock.bind("127.0.0.1", 4433)
+server = QUIC::Connection::Server.accept(
+  sock: sock, certificate_path: "server.pem", private_key_path: "server.key",
+  settings: QUIC::Settings.default.with(alpn: ["perf"])
+)
+server.run # completes the handshake
+stream = server.accept_stream
+stream.write(stream.read, fin: true) # echo everything up to the client's FIN
+begin
+  server.pump_until { stream.closed? }
+rescue QUIC::Error::Closed
+  # the client closed the connection before the stream finished
+end
+```
+
+`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
 
 The server certificate is verified by default, against the system's trusted CAs.
@@ -70,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.**
-- **No server side.** Only the client (`QUIC::Connection::Client`) exists; there is no listen/accept.
+- **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
@@ -91,7 +190,7 @@ 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.
+The gem ships no third-party binaries: [ngtcp2](https://github.com/ngtcp2/ngtcp2) (MIT, with an embedded PCG random number generator under Apache-2.0 OR MIT) and [picotls](https://github.com/h2o/picotls) (MIT) 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
 

data/Rakefile

@@ -17,4 +17,11 @@ Rake::ExtensionTask.new("quic", GEMSPEC) do |ext|
   ext.lib_dir = "lib/quic"
 end
 
+# A test-only extension that drives quic/ext.h like the http3 gem does
+# (test/test_quic_ext_api.rb). It lands in test/ext/ and is never packaged.
+Rake::ExtensionTask.new("quic_ext_echo") do |ext|
+  ext.ext_dir = "test/ext/quic_ext_echo"
+  ext.lib_dir = "test/ext"
+end
+
 task default: %i[clobber compile test standard]

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_demo.rb

@@ -3,8 +3,7 @@
 # Stream API demo: open a bidirectional stream, write a small payload with
 # FIN, then block on Stream#read until the peer echoes the bytes back and
 # closes its side. Requires a local QUIC echo server (default: 127.0.0.1:4433
-# with ALPN "perf"); ngtcp2 ships an examples/server binary that does this
-# when built with --enable-examples.
+# with ALPN "perf"), such as examples/echo_server_demo.rb.
 #
 # Override the target via env vars:
 #   QUIC_ECHO_HOST  (default 127.0.0.1)
@@ -12,10 +11,10 @@
 #   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.
+# examples/echo_server_demo.rb prints the path of the CA it generated; pass
+# it as QUIC_ECHO_CA_FILE to verify the certificate. Verification is off
+# without it. 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
 

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Echo server for examples/echo_demo.rb: accept one QUIC connection, echo
+# every stream back to the client (read up to its FIN, then write it all
+# back with FIN), and exit once the client closes the connection, goes away,
+# or opens no new stream for 10 seconds.
+#
+# No certificate files are needed. A throwaway CA and a server certificate it
+# signed are generated at startup, 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
+#   QUIC_ECHO_PORT  (default 4433)
+#   QUIC_ECHO_ALPN  (default perf)
+#
+# Run with: bundle exec ruby examples/echo_server_demo.rb
+# then, from another terminal: 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")
+ACCEPT_TIMEOUT = 10
+
+Dir.mktmpdir("quic-echo-server-") do |dir|
+  ca_file, certificate_path, private_key_path = DemoCertificates.generate(dir, BIND_HOST)
+
+  sock = UDPSocket.new(Socket::AF_INET)
+  sock.bind(BIND_HOST, BIND_PORT)
+  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
+
+  server = QUIC::Connection::Server.accept(
+    sock: sock, certificate_path: certificate_path, private_key_path: private_key_path,
+    settings: QUIC::Settings.default.with(alpn: [ALPN])
+  )
+  puts "accepted #{server.remote_address.inspect_sockaddr}"
+  server.run
+  puts "handshake completed"
+
+  begin
+    while (stream = server.accept_stream(timeout: ACCEPT_TIMEOUT))
+      data = stream.read
+      stream.write(data, fin: true)
+      puts "stream #{stream.id}: echoed #{data.bytesize} bytes"
+      server.pump_until { stream.closed? }
+    end
+    puts "no new stream for #{ACCEPT_TIMEOUT} seconds"
+  rescue QUIC::Error::Closed
+    puts "client closed the connection"
+  rescue Errno::ECONNREFUSED
+    # The socket is connected to the client, so once the client's socket is
+    # gone without a CONNECTION_CLOSE, the ICMP port unreachable surfaces
+    # here, from sending to it.
+    puts "client went away without closing the connection"
+  end
+
+  server.close
+  sock.close
+end