quic 0.0.1 → 0.0.3

data/lib/quic/settings.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Quic
+module QUIC
   Settings = Data.define(
     :cc_algo,
     :initial_rtt,
@@ -8,10 +8,36 @@ module Quic
     :max_stream_window,
     :handshake_timeout,
     :no_pmtud,
-    :alpn
+    :alpn,
+    :verify_mode,
+    :ca_file,
+    :ca_path,
+    :qlog_dir
   )
 
   class Settings
+    # verify_mode (:peer or :none), ca_file and ca_path control server
+    # certificate verification. They default here so that callers building a
+    # Settings without them keep working.
+    #
+    # With verify_mode :peer and both ca_file and ca_path nil, the system
+    # default store is used, and SSL_CERT_FILE / SSL_CERT_DIR are honoured.
+    # That store is loaded once per process, the first time a connection needs
+    # 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.
+    #
+    # 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
+
     def self.default
       new(
         cc_algo: :cubic,
@@ -20,8 +46,25 @@ module Quic
         max_stream_window: 0,
         handshake_timeout: 10_000_000_000,
         no_pmtud: false,
-        alpn: []
+        alpn: [],
+        verify_mode: :peer,
+        ca_file: 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

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-module Quic
-  # Quic::Stream is defined in the C extension (ext/quic/stream.c); this file
+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_until 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,35 +18,38 @@ 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.
     #   read(nil):    block until EOF, return everything that was received
     #                 (an empty String if nothing arrived before FIN).
+    #
+    # Both branches drain first and pump only when there is nothing to drain.
+    # #read_nonblock already distinguishes the two states we care about --
+    # QUIC::Error::WaitReadable for "nothing buffered yet" and EOFError for
+    # "nothing buffered and FIN seen" -- so the loop needs no separate
+    # predicate over @recv_buffer / #eof?.
     def read(length = nil)
       if length.nil?
-        @client.pump_until { eof? }
         out = +""
         out.force_encoding(Encoding::BINARY)
-        until eof?
-          # Should not happen given pump_until's predicate, but defensive.
-          out << read_nonblock(4096)
-        end
-        # Drain anything that arrived after the predicate was last evaluated.
         loop do
           out << read_nonblock(4096)
-        rescue Quic::Error::WaitReadable, EOFError
+        rescue QUIC::Error::WaitReadable
+          @client.pump_once
+        rescue EOFError
           break
         end
         out
       else
-        @client.pump_until { @recv_buffer.bytesize > 0 || @fin_received }
-        begin
-          read_nonblock(length)
+        loop do
+          return read_nonblock(length)
+        rescue QUIC::Error::WaitReadable
+          @client.pump_once
         rescue EOFError
-          nil
+          return nil
         end
       end
     end

data/lib/quic/transport_params.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Quic
+module QUIC
   TransportParams = Data.define(
     :initial_max_stream_data_bidi_local,
     :initial_max_stream_data_bidi_remote,

data/lib/quic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module Quic
-  VERSION = "0.0.1"
+module QUIC
+  VERSION = "0.0.3"
 end

data/lib/quic.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "quic/version"
+require_relative "quic/ext_include"
 
-module Quic
+module QUIC
   class Error < StandardError
     attr_reader :code
   end
@@ -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"

data/sig/quic.rbs

@@ -1,7 +1,11 @@
-module Quic
+module QUIC
   VERSION: String
 
-  def self.library_versions: () -> { ngtcp2: String, openssl: String }
+  # The directory holding quic/ext.h, the C function table other native
+  # extensions build against. Defined without loading the extension.
+  EXT_INCLUDE_DIR: String
+
+  def self.library_versions: () -> { ngtcp2: String, openssl: String, picotls: String }
 
   class Error < StandardError
     attr_reader code: Integer?
@@ -19,6 +23,15 @@ module Quic
     end
 
     class CryptoError < Error
+      # The TLS alert this endpoint sent when the handshake failed in
+      # #read_pkt, or nil. Alerts received from the peer are not recorded.
+      attr_reader tls_alert: Integer?
+    end
+
+    class CertificateVerifyFailed < CryptoError
+      # X509_V_ERR_* (comparable with OpenSSL::X509::V_ERR_*), or nil when
+      # the server sent no certificate.
+      attr_reader verify_result: Integer?
     end
 
     class HandshakeTimeout < Error
@@ -46,6 +59,12 @@ module Quic
 
     class NotBound < Error
     end
+
+    # 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 registered through quic/ext.h.
+    class InvalidState < Error
+    end
   end
 
   class TransportParams < Data
@@ -70,12 +89,63 @@ module Quic
     attr_reader no_pmtud: bool
     attr_reader alpn: Array[String]
 
+    # Client only: a server does not ask for a client certificate and
+    # ignores these three.
+    attr_reader verify_mode: :peer | :none
+    attr_reader ca_file: (String | _ToPath)?
+    attr_reader ca_path: (String | _ToPath)?
+
+    # Every connection writes its qlog to <qlog_dir>/<its first source
+    # connection ID in hex>.sqlog. nil (the default) writes none. A file
+    # that cannot be opened when a connection is made only costs that
+    # connection's qlog.
+    attr_reader qlog_dir: (String | _ToPath)?
+
     def self.default: () -> Settings
+
+    # 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.
+    def check_qlog_dir: () -> nil
+  end
+
+  # A server's certificate chain, private key and ALPN protocols (in order
+  # of preference), read once and shared by every connection made from it.
+  # A connection keeps the context it started with even after this object
+  # is gone. Only .server makes one; a misconfiguration raises
+  # ArgumentError naming what could not be loaded or used.
+  class TLSContext
+    def self.server: (certificate_path: String | _ToPath, private_key_path: String | _ToPath, alpn: Array[String]) -> TLSContext
   end
 
   module Connection
+    # The I/O loop shared by Client and Server. An internal implementation
+    # detail: not meant to be included in other classes.
+    module Pump
+      def bind: (untyped sock) -> self
+      def bound_socket: () -> untyped
+      def run: () -> void
+      def pump_once: (?timeout: Float?) -> void
+      def pump_until: () { () -> boolish } -> void
+
+      # Pops the next peer-initiated stream off the accept queue, driving
+      # the I/O loop until one arrives. timeout: nil blocks forever
+      # (requires #bind), timeout: 0 returns immediately, timeout: Numeric
+      # blocks up to that many seconds. Returns nil on timeout. Raises
+      # QUIC::Error::InvalidState when a C stream handler owns the streams.
+      def accept_stream: (?timeout: Numeric?) -> Stream?
+
+      # Non-blocking #accept_stream. Returns the next queued peer-initiated
+      # stream, or raises QUIC::Error::WaitReadable when the queue is empty.
+      def accept_stream_nonblock: () -> Stream
+    end
+
     class Client
-      def self.new: (host: String, port: Integer, ?transport_params: TransportParams?, ?settings: Settings?) -> Client
+      include Pump
+
+      attr_reader remote_address: Addrinfo
+
+      def self.new: (host: String, port: Integer, ?address_family: Symbol?, ?transport_params: TransportParams?, ?settings: Settings?) -> Client
 
       def self._open: (
         local_sockaddr: String,
@@ -97,14 +167,148 @@ module Quic
       def in_closing_period?: () -> bool
       def in_draining_period?: () -> bool
 
-      def bind: (untyped sock) -> Client
-      def bound_socket: () -> untyped
-      def run: () -> void
-      def pump_once: (?timeout: Float?) -> void
-      def pump_until: () { () -> boolish } -> void
+      # Sends an application CONNECTION_CLOSE (frame type 0x1d) to the peer
+      # carrying error_code and reason, then transitions the underlying
+      # ngtcp2_conn to the closing period. Requires #bind to have been
+      # called; raises QUIC::Error::NotBound otherwise. A second #close call
+      # after the connection has already entered the closing or draining
+      # period is a no-op.
+      def close: (?error_code: Integer, ?reason: String) -> nil
+
+      # Always nil: only a connection an Endpoint made has a closing reason.
+      def error: () -> Exception?
+    end
+
+    class Server
+      include Pump
+
+      attr_reader remote_address: Addrinfo
+
+      # Waits for the first datagram on sock (bound to the listen address,
+      # not connected), connects sock to its sender, and returns a Server
+      # for that one client; call #run to complete the handshake.
+      # - The wait has no timeout; close sock from another thread to give up.
+      # - If anything fails after the first datagram arrived, sock stays
+      #   connected to its sender: discard it and accept on a new socket.
+      # - settings must name at least one ALPN protocol; leaving it out
+      #   raises ArgumentError, since QUIC::Settings.default has none.
+      # - The certificate file is PEM, the leaf certificate first and then
+      #   any intermediates.
+      def self.accept: (
+        sock: untyped,
+        certificate_path: String | _ToPath,
+        private_key_path: String | _ToPath,
+        ?transport_params: TransportParams?,
+        ?settings: Settings?
+      ) -> Server
+
+      # Builds a server connection from initial_packet, the first datagram a
+      # client sent; feed that datagram to #read_pkt afterwards. The
+      # certificate file is PEM, the leaf certificate first and then any
+      # intermediates. settings.alpn must not be empty (ArgumentError).
+      # A first packet that cannot start a connection raises
+      # QUIC::Error::Proto.
+      def self._accept: (
+        initial_packet: String,
+        local_sockaddr: String,
+        remote_sockaddr: String,
+        certificate_path: String | _ToPath,
+        private_key_path: String | _ToPath,
+        transport_params: TransportParams,
+        settings: Settings
+      ) -> Server
+
+      def open_bidi_stream: () -> Stream
+      def open_uni_stream: () -> Stream
+
+      def write_pkt: (?String? buffer) -> String?
+      def read_pkt: (String packet, local_sockaddr: String, remote_sockaddr: String) -> nil
+
+      def expiry: () -> Integer?
+      def handle_expiry: () -> nil
+      def handshake_completed?: () -> bool
+      def in_closing_period?: () -> bool
+      def in_draining_period?: () -> bool
+
+      # Sends an application CONNECTION_CLOSE (frame type 0x1d) to the peer
+      # carrying error_code and reason, then transitions the underlying
+      # ngtcp2_conn to the closing period. Requires #bind to have been
+      # called; raises QUIC::Error::NotBound otherwise. A connection an
+      # Endpoint made needs no #bind: the CONNECTION_CLOSE goes out through
+      # Endpoint#write_pkt. A second #close call after the connection has
+      # already entered the closing or draining period, or after it left
+      # its Endpoint, is a no-op.
+      def close: (?error_code: Integer, ?reason: String) -> nil
+
+      # Why the Endpoint closed this 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; otherwise a QUIC::Error made (not
+      # raised) from ngtcp2's error code. Always nil for a connection no
+      # Endpoint made.
+      def error: () -> Exception?
     end
   end
 
+  # Many server connections on one UDP socket, which must not be connected
+  # and must be bound to the address it serves. The Endpoint routes each
+  # datagram to its connection, 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.
+  # A connection's failure never raises from these methods; it closes that
+  # connection alone (see Connection::Server#error). The connections have
+  # no socket, so only their non-blocking methods work.
+  class Endpoint
+    attr_reader local_address: Addrinfo
+
+    # tls_context's ALPN list is the server's; settings.alpn is not read.
+    # max_connections counts closing and draining connections too.
+    def self.new: (
+      local_address: Addrinfo,
+      tls_context: TLSContext,
+      ?transport_params: TransportParams?,
+      ?settings: Settings?,
+      ?max_connections: Integer
+    ) -> Endpoint
+
+    def self._new: (
+      local_sockaddr: String,
+      tls_context: TLSContext,
+      transport_params: TransportParams,
+      settings: Settings,
+      max_connections: Integer
+    ) -> Endpoint
+
+    # Routes one datagram from remote (an AF_INET or AF_INET6 sockaddr, as
+    # Addrinfo#to_sockaddr makes; ArgumentError otherwise); local defaults
+    # to local_address. Returns the connection it went to, which may be a
+    # new one, or nil when the Endpoint answered or dropped it.
+    def read_pkt: (String packet, remote: String, ?local: String?) -> Connection::Server?
+
+    # The next datagram to send and its destination sockaddr, or nil when
+    # there is none left: the Endpoint's own answers first (at most 1024
+    # wait; any beyond are dropped), then each connection's packets in turn.
+    def write_pkt: () -> [String, String]?
+
+    # The earliest CLOCK_MONOTONIC time (ns) #handle_expiry is due, or nil.
+    def expiry: () -> Integer?
+
+    # Runs the timers that are due and takes out of the table the
+    # connections that are finished.
+    def handle_expiry: () -> nil
+
+    # The connections that left the table since the last call.
+    def take_closed: () -> Array[Connection::Server]
+
+    # The connections in the table, closing and draining ones included.
+    def connections: () -> Array[Connection::Server]
+
+    # Refuses every new connection from now on with CONNECTION_REFUSED.
+    def stop_accepting: () -> nil
+
+    # The context new connections are made with; existing ones keep theirs.
+    def tls_context=: (TLSContext) -> TLSContext
+  end
+
   class Stream
     INITIATORS: Array[Symbol]
 
@@ -115,22 +319,36 @@ module Quic
     def read: (?Integer? length) -> String?
     def read_nonblock: (Integer length) -> String
 
-    # Blocks (by internally calling Client#pump_once) until the peer's flow
-    # control window has room for the full payload, then queues all bytes
-    # and returns data.bytesize. Requires the parent Client to be bound to
-    # a socket via Client#bind; raises Quic::Error::NotBound otherwise.
+    # Blocks (by internally calling #pump_once on the owning Client or
+    # Server) until the peer's flow control window has room for the full
+    # payload, then queues all bytes and returns data.bytesize. Requires the
+    # owning connection to be bound to a socket via #bind; raises
+    # QUIC::Error::NotBound otherwise.
     def write: (String data, ?fin: bool) -> Integer
 
     # Non-blocking variant. Queues as much of `data` as the current flow
     # control window allows and returns the byte count actually queued.
-    # Raises Quic::Error::WaitWritable (mixed in with IO::WaitWritable) when
+    # Raises QUIC::Error::WaitWritable (mixed in with IO::WaitWritable) when
     # the window is zero and the payload is non-empty. If only a partial
     # prefix is accepted, `fin: true` is NOT propagated; the caller must
     # re-issue with `fin: true` on the trailing chunk.
     def write_nonblock: (String data, ?fin: bool) -> Integer
     def eof?: () -> bool
+
+    # True once the stream is fully closed: both directions have finished
+    # (FIN or reset) and everything sent has been acknowledged. Stays false
+    # if the connection closes first, since ngtcp2 does not report stream
+    # closure then. Keeps returning true after the stream has left the
+    # connection. A bare Stream is never closed.
+    def closed?: () -> bool
+
     def close_write: () -> nil
     def close_read: () -> nil
     def close: () -> nil
+
+    # Aborts the send side with RESET_STREAM carrying error_code (default 0).
+    # After #reset, #write / #write_nonblock raise QUIC::Error::StreamClosed.
+    # The read side is unaffected. Idempotent: a second #reset is a no-op.
+    def reset: (?Integer error_code) -> nil
   end
 end

metadata

@@ -1,18 +1,34 @@
 --- !ruby/object:Gem::Specification
 name: quic
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Yusuke Nakamura
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: A thin Ruby binding around ngtcp2 for the QUIC transport protocol, with
-  LibreSSL as the TLS backend. Both are vendored via mini_portile2 at install time;
-  no system libraries required. The API is intentionally optimized for synchronous
-  I/O and String-based buffers. Public API is not yet stable.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mini_portile2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A thin Ruby binding around ngtcp2 for the QUIC transport protocol, using
+  picotls for TLS 1.3. ngtcp2 and picotls are vendored via mini_portile2 at install
+  time and linked statically; the crypto primitives and X.509 come from the host's
+  OpenSSL (or LibreSSL), linked dynamically, so the process shares one libcrypto with
+  Ruby's openssl extension. The API is intentionally optimized for synchronous I/O
+  and String-based buffers. Public API is not yet stable.
 email:
 - yusuke1994525@gmail.com
 executables: []
@@ -22,19 +38,36 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- LICENSE-DEPENDENCIES.txt
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/doq_demo.rb
 - examples/echo_demo.rb
+- examples/echo_server_demo.rb
 - examples/handshake_demo.rb
+- examples/io_loop_demo.rb
+- examples/verify_demo.rb
 - ext/quic/connection_client.c
+- ext/quic/connection_common.c
+- ext/quic/connection_common.h
+- ext/quic/connection_server.c
+- ext/quic/endpoint.c
+- ext/quic/endpoint.h
+- ext/quic/ext_api.c
 - ext/quic/extconf.rb
+- ext/quic/include/quic/ext.h
+- ext/quic/patches/picotls/0001-openssl-use-raw-public-key-api-for-X25519.patch
 - ext/quic/quic.c
 - ext/quic/quic.h
 - ext/quic/stream.c
 - ext/quic/stream.h
+- ext/quic/tls_context.c
+- ext/quic/tls_context.h
 - lib/quic.rb
 - lib/quic/connection.rb
+- lib/quic/endpoint.rb
+- lib/quic/ext_include.rb
 - lib/quic/settings.rb
 - lib/quic/stream.rb
 - lib/quic/transport_params.rb
@@ -48,6 +81,7 @@ metadata:
   homepage_uri: https://github.com/unasuke/quic-ruby
   source_code_uri: https://github.com/unasuke/quic-ruby
   changelog_uri: https://github.com/unasuke/quic-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -62,8 +96,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Thin Ruby binding around ngtcp2 for the QUIC transport protocol, with LibreSSL
-  as the TLS backend.
+summary: Thin Ruby binding around ngtcp2 for the QUIC transport protocol, using picotls
+  for TLS 1.3 over the system OpenSSL.
 test_files: []