quic 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2598a7b8f6d545c4f092bc5885644fdc6a6cc19406489ebba6dcd40e90d63394
-  data.tar.gz: 71076bbc240ea79b361bac74443748dcbc725e6cb5fcc22ff6587935a1afb9e1
+  metadata.gz: 9032a4ca3ee79288be00be635d283adcfe5435a9aea166e9c15868f051b675ea
+  data.tar.gz: 52377290a15ad9644312b2db8350bfe3979834eae926be6cd9e1e460e0091b01
 SHA512:
-  metadata.gz: 6b882c40642e5efdf6a45717c6dba5fe890c26dbe7bbae66ef9b3871e17958773dd7c41877a5b9decf40e0fd6ba03359f632b8f9ca6dc393cabf36600d03acf1
-  data.tar.gz: 29a203887f07455ae6d8d6c76d553bb82fe9c1d72aa2233f797f60093e353dbf028b8b8d3b8f6e40a645b9535cb6b089f4971cf763e96a45af7cc7a494e03a2b
+  metadata.gz: 9df57929c35a332b353df2c2955a1799e42a94d0a9afb4b1b697df085daba67aca60c2a906fd3f76c1eb07ac2cbb48d657ee12a44c87d41a4d881275ae596d8a
+  data.tar.gz: 340e5424b7fe6dc6aad37dd5be581d5d4e077b062f480e1f60d5a6c7c13d296425a66244b1278a35ed1b1cd125d052df1c8dd57e9989ebf3741c650a22f5fe51

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [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,35 @@ 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.
 - [`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. [`echo_server_demo.rb`](examples/echo_server_demo.rb) generates its own certificate, so it runs as is against `echo_demo.rb`.
+
 ### Certificate verification
 
 The server certificate is verified by default, against the system's trusted CAs.
@@ -74,7 +99,7 @@ settings = QUIC::Settings.default.with(alpn: ["perf"], verify_mode: :none)
 
 - **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.
+- **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.
 - **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 +116,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/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_server_demo.rb

@@ -0,0 +1,127 @@
+# 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 "ipaddr"
+require "openssl"
+require "socket"
+require "tmpdir"
+
+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)
+
+  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