quic 0.0.2 → 0.0.4

data/ext/quic/tls_context.h

@@ -0,0 +1,47 @@
+#ifndef QUIC_TLS_CONTEXT_H
+#define QUIC_TLS_CONTEXT_H 1
+
+#include "quic.h"
+
+/* A server's TLS context: the certificate chain, the signer and the ALPN
+   list, read once and shared by every connection made from it. Reference
+   counted: the QUIC::TLSContext object holds one reference and each server
+   connection another, so a context replaced on an Endpoint lives on until
+   the last connection that uses it is freed. */
+typedef struct {
+  /* Handed to ptls_server_new. certificates.list is malloc()ed by picotls
+     and freed with the context. */
+  ptls_context_t ctx;
+  /* Referenced by ctx.sign_certificate; holds a reference to the key. */
+  ptls_openssl_sign_certificate_t sign_cert;
+  bool sign_cert_initialized;
+  /* ctx.on_client_hello points here; the callback recovers this struct
+     from its self argument with offsetof, so it needs no connection. */
+  ptls_on_client_hello_t on_client_hello;
+  /* The ALPN protocols the server accepts, in its order of preference. The
+     entries point into alpn_buf. */
+  ptls_iovec_t *alpn;
+  size_t alpn_count;
+  uint8_t *alpn_buf;
+  long refcnt;
+} quic_tls_ctx_t;
+
+extern VALUE rb_cQUICTLSContext;
+
+void Init_quic_tls_context(VALUE rb_mQUICArg);
+
+/* QUIC::TLSContext.server, callable from C: a new QUIC::TLSContext object
+   holding the one reference to a new context. alpn_ary must be a non-empty
+   Array of 1-255 byte Strings. Raises ArgumentError naming what could not
+   be loaded or used. */
+VALUE quic_tls_context_server_new(VALUE certificate_path,
+                                  VALUE private_key_path, VALUE alpn_ary);
+
+/* The context behind a QUIC::TLSContext object. Raises TypeError for any
+   other object. */
+quic_tls_ctx_t *quic_tls_context_get(VALUE tls_context);
+
+void quic_tls_ctx_ref(quic_tls_ctx_t *t);
+void quic_tls_ctx_unref(quic_tls_ctx_t *t);
+
+#endif /* QUIC_TLS_CONTEXT_H */

data/lib/quic/connection.rb

@@ -4,46 +4,11 @@ require "socket"
 
 module QUIC
   module Connection
-    class Client
-      attr_reader :remote_address
-
-      # Build a Client and pin a single peer address. address_family takes a
-      # Symbol (:inet for IPv4, :inet6 for IPv6) or nil to defer family
-      # selection to Addrinfo.udp's implicit resolution. Pin the resolved
-      # Addrinfo into @remote_address so callers can match their UDPSocket's
-      # connected sockaddr (otherwise DNS round-robin between Client.new and
-      # sock.connect can produce a path that ngtcp2 silently drops).
-      def self.new(host:, port:, address_family: nil, transport_params: nil, settings: nil)
-        family = case address_family
-        when nil then nil
-        when :inet then Socket::AF_INET
-        when :inet6 then Socket::AF_INET6
-        else
-          raise ArgumentError, "unknown address_family: #{address_family.inspect}"
-        end
-
-        remote_address = if family
-          Addrinfo.getaddrinfo(host, port, family, :DGRAM, Socket::IPPROTO_UDP).first
-        else
-          Addrinfo.udp(host, port)
-        end
-
-        remote_sockaddr = remote_address.to_sockaddr
-        local_sockaddr = Addrinfo.udp("0.0.0.0", 0).to_sockaddr
-
-        client = _open(
-          local_sockaddr: local_sockaddr,
-          remote_sockaddr: remote_sockaddr,
-          server_name: host,
-          transport_params: transport_params || QUIC::TransportParams.default,
-          settings: settings || QUIC::Settings.default
-        )
-        client.instance_variable_set(:@host, host)
-        client.instance_variable_set(:@port, port)
-        client.instance_variable_set(:@remote_address, remote_address)
-        client
-      end
-
+    # The Ruby side of the I/O loop, shared by Client and Server. It is an
+    # internal implementation detail: not meant to be included in other
+    # classes, and the ivars and methods it relies on are not a public
+    # contract.
+    module Pump
       # Attach an IO.select / #send / #recvfrom-compatible UDP socket so that
       # #run and Stream blocking I/O can drive the wire transparently. Caller
       # is responsible for socket lifetime; we do not close it. The socket
@@ -61,7 +26,7 @@ module QUIC
       # QUIC::Error::NotBound if #bind has not been called. Propagates any
       # QUIC::Error subclass raised by #read_pkt / #handle_expiry.
       def run
-        raise QUIC::Error::NotBound, "QUIC::Connection::Client#bind(sock) has not been called" if @sock.nil?
+        raise QUIC::Error::NotBound, "#{self.class}#bind(sock) has not been called" if @sock.nil?
 
         pump_until { handshake_completed? }
       end
@@ -72,7 +37,7 @@ module QUIC
       # fire. Public-ish so Stream blocking ops can share it; documented as
       # "internal" for users.
       def pump_once(timeout: nil)
-        raise QUIC::Error::NotBound, "QUIC::Connection::Client#bind(sock) has not been called" if @sock.nil?
+        raise QUIC::Error::NotBound, "#{self.class}#bind(sock) has not been called" if @sock.nil?
 
         while (pkt = write_pkt)
           @sock.send(pkt, 0)
@@ -82,10 +47,11 @@ module QUIC
         ready = IO.select([@sock], nil, nil, wait_for)
         if ready
           data, _addr = @sock.recvfrom(2048)
-          # Reuse the same path tuple that Client.new / Client._open passed to
-          # ngtcp2_conn_client_new so the read_pkt path matches the stored
-          # connection path. local is 0.0.0.0:0 (Client.new convention) and
-          # remote comes from the connected socket (assumes #connect was used).
+          # Reuse the same path tuple the connection was built with so the
+          # read_pkt path matches the stored connection path. A Client leaves
+          # @local_sockaddr unset, so local is 0.0.0.0:0 (Client.new
+          # convention); remote comes from the connected socket (assumes
+          # #connect was used).
           read_pkt(
             data,
             local_sockaddr: pump_local_sockaddr,
@@ -102,9 +68,9 @@ module QUIC
         pump_once until pred.call
       end
 
-      # Pop the next peer-initiated (server) stream off the accept queue,
-      # driving the I/O loop until one arrives. The queue is fed by the
-      # recv_stream_data callback the first time a server stream carries data.
+      # Pop the next peer-initiated stream off the accept queue, driving the
+      # I/O loop until one arrives. The queue is fed by the recv_stream_data
+      # callback the first time a peer-initiated stream carries data.
       #
       # timeout: nil      block until a stream is available (requires #bind)
       # timeout: 0        return immediately; nil if the queue is empty
@@ -112,7 +78,8 @@ module QUIC
       #
       # Returns a QUIC::Stream, or nil on timeout.
       def accept_stream(timeout: nil)
-        stream = @accept_queue.shift
+        require_stream_mode
+        stream = take_accepted_stream
         return stream unless stream.nil?
         return nil if timeout == 0
 
@@ -125,22 +92,40 @@ module QUIC
           else
             pump_once
           end
-          stream = @accept_queue.shift
+          stream = take_accepted_stream
           return stream unless stream.nil?
         end
       end
 
       # Non-blocking variant of #accept_stream. Returns the next queued
-      # server stream, or raises QUIC::Error::WaitReadable (IO::WaitReadable
-      # mixin) when the queue is empty. Does not require #bind.
+      # peer-initiated stream, or raises QUIC::Error::WaitReadable
+      # (IO::WaitReadable mixin) when the queue is empty. Does not require
+      # #bind.
       def accept_stream_nonblock
-        stream = @accept_queue.shift
-        raise QUIC::Error::WaitReadable, "no server-initiated stream available" if stream.nil?
+        require_stream_mode
+        stream = take_accepted_stream
+        raise QUIC::Error::WaitReadable, "no peer-initiated stream available" if stream.nil?
         stream
       end
 
       private
 
+      # A C stream handler (quic/ext.h) registered on the connection owns
+      # every stream, so no QUIC::Stream is ever queued for #accept_stream.
+      def require_stream_mode
+        return unless @stream_handler
+        raise QUIC::Error::InvalidState, "the connection's streams belong to a C stream handler"
+      end
+
+      # The next stream off the accept queue, or nil. Telling the stream it
+      # has been accepted lets the peer open another one in place of a
+      # stream that closed while it waited in the queue.
+      def take_accepted_stream
+        stream = @accept_queue.shift
+        stream&.__send__(:_accepted)
+        stream
+      end
+
       def pump_timeout(caller_timeout)
         ngtcp2_expiry_ns = expiry
         if ngtcp2_expiry_ns.nil?
@@ -153,11 +138,111 @@ module QUIC
       end
 
       def pump_local_sockaddr
-        @pump_local_sockaddr ||= Addrinfo.udp("0.0.0.0", 0).to_sockaddr
+        @local_sockaddr ||= Addrinfo.udp("0.0.0.0", 0).to_sockaddr
       end
 
       def pump_remote_sockaddr
-        @pump_remote_sockaddr ||= @sock.remote_address.to_sockaddr
+        @remote_sockaddr ||= @sock.remote_address.to_sockaddr
+      end
+    end
+
+    class Client
+      include Pump
+
+      attr_reader :remote_address
+
+      # Build a Client and pin a single peer address. address_family takes a
+      # Symbol (:inet for IPv4, :inet6 for IPv6) or nil to defer family
+      # selection to Addrinfo.udp's implicit resolution. Pin the resolved
+      # Addrinfo into @remote_address so callers can match their UDPSocket's
+      # connected sockaddr (otherwise DNS round-robin between Client.new and
+      # sock.connect can produce a path that ngtcp2 silently drops).
+      def self.new(host:, port:, address_family: nil, transport_params: nil, settings: nil)
+        family = case address_family
+        when nil then nil
+        when :inet then Socket::AF_INET
+        when :inet6 then Socket::AF_INET6
+        else
+          raise ArgumentError, "unknown address_family: #{address_family.inspect}"
+        end
+
+        remote_address = if family
+          Addrinfo.getaddrinfo(host, port, family, :DGRAM, Socket::IPPROTO_UDP).first
+        else
+          Addrinfo.udp(host, port)
+        end
+
+        remote_sockaddr = remote_address.to_sockaddr
+        local_sockaddr = Addrinfo.udp("0.0.0.0", 0).to_sockaddr
+        settings ||= QUIC::Settings.default
+        settings.check_qlog_dir
+
+        client = _open(
+          local_sockaddr: local_sockaddr,
+          remote_sockaddr: remote_sockaddr,
+          server_name: host,
+          transport_params: transport_params || QUIC::TransportParams.default,
+          settings: settings
+        )
+        client.instance_variable_set(:@host, host)
+        client.instance_variable_set(:@port, port)
+        client.instance_variable_set(:@remote_address, remote_address)
+        client
+      end
+    end
+
+    # One server-side connection. Built by Server.accept (or Server._accept)
+    # from the first datagram a client sent; there is no public Server.new,
+    # since an object without an ngtcp2 connection behind it would be
+    # unusable.
+    class Server
+      include Pump
+
+      attr_reader :remote_address
+
+      private_class_method :new
+
+      # Wait for the first datagram on sock and build a connection for its
+      # sender. sock must be bound to the listen address and not connected.
+      # It is connected to the first sender, so this Server serves exactly
+      # that one client and shares the I/O loop with Client as is. The
+      # handshake is left to #run.
+      #
+      # The wait for the first datagram has no timeout; close sock from
+      # another thread to give up. If anything fails after that datagram
+      # arrived, sock stays connected to its sender: discard it and accept on
+      # a new socket. accept never closes sock; its lifetime is the caller's.
+      #
+      # settings must name at least one ALPN protocol, so the default
+      # (QUIC::Settings.default) raises ArgumentError. A qlog_dir that is not
+      # a writable directory raises ArgumentError before the wait.
+      def self.accept(sock:, certificate_path:, private_key_path:, transport_params: nil, settings: nil)
+        settings ||= QUIC::Settings.default
+        settings.check_qlog_dir
+
+        data, sender = sock.recvfrom(2048)
+        sock.connect(sender[3], sender[1])
+        # Read both addresses back from the connected socket so that the path
+        # given to ngtcp2 here and every later read_pkt path come from one
+        # source and always match.
+        local_sockaddr = sock.local_address.to_sockaddr
+        remote_sockaddr = sock.remote_address.to_sockaddr
+
+        server = _accept(
+          initial_packet: data,
+          local_sockaddr: local_sockaddr,
+          remote_sockaddr: remote_sockaddr,
+          certificate_path: certificate_path,
+          private_key_path: private_key_path,
+          transport_params: transport_params || QUIC::TransportParams.default,
+          settings: settings
+        )
+        server.instance_variable_set(:@local_sockaddr, local_sockaddr)
+        server.instance_variable_set(:@remote_sockaddr, remote_sockaddr)
+        server.instance_variable_set(:@remote_address, sock.remote_address)
+        server.bind(sock)
+        server.read_pkt(data, local_sockaddr: local_sockaddr, remote_sockaddr: remote_sockaddr)
+        server
       end
     end
   end

data/lib/quic/endpoint.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module QUIC
+  # Many server connections on one UDP socket. The Endpoint routes each
+  # datagram to its connection by connection ID, makes connections for new
+  # clients and answers what no connection can (Version Negotiation,
+  # Stateless Reset, CONNECTION_REFUSED). The socket and the I/O loop stay
+  # with the caller:
+  #
+  #   loop do
+  #     data, addr = sock.recvfrom(65_535)            # or recvmsg_nonblock
+  #     endpoint.read_pkt(data, remote: addr.to_sockaddr)
+  #     endpoint.handle_expiry                         # when endpoint.expiry is due
+  #     while (pkt, to = endpoint.write_pkt)
+  #       sock.send(pkt, 0, to)
+  #     end
+  #     endpoint.take_closed.each { |conn| ... }
+  #   end
+  #
+  # The socket must not be connected, and must be bound to the address it
+  # serves (not 0.0.0.0): every path's local address is local_address.
+  #
+  # The Endpoint's own answers wait for #write_pkt in a queue of at most
+  # 1024; any beyond are dropped, so call #write_pkt often under load.
+  #
+  # A connection's failure never raises from the Endpoint's methods. It
+  # closes that connection alone, and Connection#error tells why. The
+  # connections have no socket, so only their non-blocking methods work;
+  # #close queues its CONNECTION_CLOSE for #write_pkt.
+  class Endpoint
+    attr_reader :local_address
+
+    # tls_context is a QUIC::TLSContext; its ALPN list is the server's, and
+    # settings.alpn is not read. max_connections counts connections in their
+    # closing or draining period too.
+    def self.new(local_address:, tls_context:, transport_params: nil, settings: nil, max_connections: 1024)
+      raise TypeError, "local_address must be an Addrinfo (got #{local_address.class})" unless local_address.is_a?(Addrinfo)
+      unless max_connections.is_a?(Integer)
+        raise TypeError, "max_connections must be an Integer (got #{max_connections.class})"
+      end
+      settings ||= QUIC::Settings.default
+      settings.check_qlog_dir
+
+      endpoint = _new(
+        local_sockaddr: local_address.to_sockaddr,
+        tls_context: tls_context,
+        transport_params: transport_params || QUIC::TransportParams.default,
+        settings: settings,
+        max_connections: max_connections
+      )
+      endpoint.instance_variable_set(:@local_address, local_address)
+      endpoint
+    end
+  end
+end

data/lib/quic/ext_include.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module QUIC
+  # The directory holding quic/ext.h, the C function table other native
+  # extensions build against. An extconf.rb adds it to its include path:
+  #
+  #   require "quic/ext_include"
+  #   append_cppflags("-I#{QUIC::EXT_INCLUDE_DIR}")
+  #
+  # This file does not load the extension, so extconf.rb can require it.
+  EXT_INCLUDE_DIR = File.expand_path("../../ext/quic/include", __dir__)
+end

data/lib/quic/settings.rb

@@ -11,7 +11,8 @@ module QUIC
     :alpn,
     :verify_mode,
     :ca_file,
-    :ca_path
+    :ca_path,
+    :qlog_dir
   )
 
   class Settings
@@ -25,7 +26,15 @@ module QUIC
     # it; later changes to those variables or to the CA bundle are not picked
     # up. Setting ca_file or ca_path trusts only the certificates found there.
     # With verify_mode :none, ca_file and ca_path are ignored.
-    def initialize(verify_mode: :peer, ca_file: nil, ca_path: nil, **rest)
+    #
+    # Only a client uses verify_mode, ca_file and ca_path. A server ignores
+    # them, since it does not ask for a client certificate.
+    #
+    # qlog_dir (a String or Pathname) makes every connection write its qlog
+    # to <qlog_dir>/<its first source connection ID in hex>.sqlog. A file
+    # that cannot be opened when a connection is made only costs that
+    # connection's qlog.
+    def initialize(verify_mode: :peer, ca_file: nil, ca_path: nil, qlog_dir: nil, **rest)
       super
     end
 
@@ -40,8 +49,22 @@ module QUIC
         alpn: [],
         verify_mode: :peer,
         ca_file: nil,
-        ca_path: nil
+        ca_path: nil,
+        qlog_dir: nil
       )
     end
+
+    # Raises ArgumentError unless qlog_dir is nil or a directory this
+    # process can write to. Client.new, Connection::Server.accept and
+    # Endpoint.new call it, so that a wrong qlog_dir shows up when they are
+    # set up rather than as qlog files that never appear.
+    def check_qlog_dir
+      return if qlog_dir.nil?
+
+      path = qlog_dir.respond_to?(:to_path) ? qlog_dir.to_path : qlog_dir
+      return if path.is_a?(String) && File.directory?(path) && File.writable?(path)
+
+      raise ArgumentError, "qlog_dir is not a writable directory: #{path}"
+    end
   end
 end

data/lib/quic/stream.rb

@@ -4,7 +4,8 @@ module QUIC
   # QUIC::Stream is defined in the C extension (ext/quic/stream.c); this file
   # reopens it to add the bits that are easier to express in Ruby:
   # #initiator (a tiny lookup over @id) and the blocking #read which wraps
-  # the C #read_nonblock with an internal Client#pump_once loop.
+  # the C #read_nonblock with an internal #pump_once loop on the owning
+  # connection (@client, a Client or Server).
   class Stream
     INITIATORS = %i[client_bidi server_bidi client_uni server_uni].freeze
 
@@ -17,8 +18,8 @@ module QUIC
       INITIATORS[@id & 0b11]
     end
 
-    # IO#read-compatible blocking read. Requires the parent Client to have
-    # been #bind'ed to a socket (raised via Client#pump_once otherwise).
+    # IO#read-compatible blocking read. Requires the owning connection to
+    # have been #bind'ed to a socket (raised via its #pump_once otherwise).
     #
     #   read(length): block until at least 1 byte is available or EOF,
     #                 return up to `length` bytes, return nil at EOF.

data/lib/quic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QUIC
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/lib/quic.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "quic/version"
+require_relative "quic/ext_include"
 
 module QUIC
   class Error < StandardError
@@ -12,4 +13,5 @@ require "quic/quic"
 require_relative "quic/transport_params"
 require_relative "quic/settings"
 require_relative "quic/connection"
+require_relative "quic/endpoint"
 require_relative "quic/stream"