quic 0.0.2 → 0.0.4

data/sig/quic.rbs

@@ -1,6 +1,10 @@
 module QUIC
   VERSION: 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
@@ -19,7 +23,7 @@ module QUIC
     end
 
     class CryptoError < Error
-      # The TLS alert this client sent when the handshake failed in
+      # 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
@@ -55,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
@@ -78,15 +88,61 @@ module QUIC
     attr_reader handshake_timeout: Integer
     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
+      include Pump
+
       attr_reader remote_address: Addrinfo
 
       def self.new: (host: String, port: Integer, ?address_family: Symbol?, ?transport_params: TransportParams?, ?settings: Settings?) -> Client
@@ -111,32 +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
-
-      # Pops the next peer-initiated (server) 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.
-      def accept_stream: (?timeout: Numeric?) -> Stream?
-
-      # Non-blocking #accept_stream. Returns the next queued server stream,
-      # or raises QUIC::Error::WaitReadable when the queue is empty.
-      def accept_stream_nonblock: () -> Stream
-
       # 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 Client#bind to have been
+      # 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]
 
@@ -147,10 +319,11 @@ 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
@@ -161,6 +334,14 @@ module QUIC
     # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quic
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Yusuke Nakamura
@@ -36,26 +36,42 @@ extensions:
 - ext/quic/extconf.rb
 extra_rdoc_files: []
 files:
+- ".clang-format"
+- ".git-blame-ignore-revs"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE-DEPENDENCIES.txt
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/demo_certificates.rb
 - examples/doq_demo.rb
 - examples/echo_demo.rb
+- examples/echo_endpoint_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