quic 0.0.2 → 0.0.3

data/ext/quic/tls_context.c

@@ -0,0 +1,260 @@
+#include "tls_context.h"
+#include "connection_common.h"
+
+#include <stddef.h>
+#include <string.h>
+
+#include <openssl/bio.h>
+#include <openssl/err.h>
+#include <openssl/pem.h>
+#include <openssl/x509.h>
+
+VALUE rb_cQUICTLSContext;
+
+void
+quic_tls_ctx_ref(quic_tls_ctx_t *t)
+{
+  t->refcnt++;
+}
+
+void
+quic_tls_ctx_unref(quic_tls_ctx_t *t)
+{
+  if (--t->refcnt > 0) return;
+  if (t->sign_cert_initialized) ptls_openssl_dispose_sign_certificate(&t->sign_cert);
+  /* picotls malloc()ed the list and each entry, so free(), not xfree(). */
+  if (t->ctx.certificates.list != NULL) {
+    for (size_t i = 0; i < t->ctx.certificates.count; i++) free(t->ctx.certificates.list[i].base);
+    free(t->ctx.certificates.list);
+  }
+  xfree(t->alpn);
+  xfree(t->alpn_buf);
+  xfree(t);
+}
+
+/* The QUIC::TLSContext object holds one reference. A context it never
+   finished building (an exception mid-way) is released the same way. */
+static void
+quic_tls_context_free(void *ptr)
+{
+  if (ptr != NULL) quic_tls_ctx_unref((quic_tls_ctx_t *)ptr);
+}
+
+static size_t
+quic_tls_context_size(const void *ptr)
+{
+  (void)ptr;
+  return sizeof(quic_tls_ctx_t);
+}
+
+static const rb_data_type_t quic_tls_context_type = {
+  "QUIC::TLSContext",
+  {NULL, quic_tls_context_free, quic_tls_context_size,},
+  NULL, NULL,
+  RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+quic_tls_ctx_t *
+quic_tls_context_get(VALUE tls_context)
+{
+  return (quic_tls_ctx_t *)rb_check_typeddata(tls_context, &quic_tls_context_type);
+}
+
+/* Pick the first of the server's ALPN protocols, in the server's order of
+   preference, that the client offered. Runs inside read_pkt with the GVL
+   held and never touches Ruby objects. */
+static int
+quic_tls_on_client_hello_cb(ptls_on_client_hello_t *self, ptls_t *tls,
+                            ptls_on_client_hello_parameters_t *params)
+{
+  quic_tls_ctx_t *t = (quic_tls_ctx_t *)((char *)self - offsetof(quic_tls_ctx_t, on_client_hello));
+  for (size_t i = 0; i < t->alpn_count; i++) {
+    for (size_t j = 0; j < params->negotiated_protocols.count; j++) {
+      ptls_iovec_t offered = params->negotiated_protocols.list[j];
+      if (offered.len == t->alpn[i].len &&
+          memcmp(offered.base, t->alpn[i].base, offered.len) == 0) {
+        return ptls_set_negotiated_protocol(tls, (const char *)offered.base, offered.len) == 0
+          ? 0 : PTLS_ERROR_NO_MEMORY;
+      }
+    }
+  }
+  return PTLS_ALERT_NO_APPLICATION_PROTOCOL;
+}
+
+/* Never supply a passphrase. Without a callback, PEM_read_bio_PrivateKey
+   falls back to PEM_def_callback, which prompts on the controlling terminal;
+   this way an encrypted key fails to load like any other unreadable one. */
+static int
+quic_tls_no_passphrase_cb(char *buf, int size, int rwflag, void *userdata)
+{
+  (void)buf;
+  (void)size;
+  (void)rwflag;
+  (void)userdata;
+  return -1;
+}
+
+/* Load the certificate chain and private key into t->ctx and install the
+   signer. The certificate file is PEM, the leaf first and then any
+   intermediates; there is no limit on their number. A misconfiguration
+   raises ArgumentError naming the step that failed. Everything allocated
+   here is released before raising, and libcrypto's error queue, which is
+   shared with Ruby's openssl extension, is left empty on every return. */
+static void
+quic_tls_ctx_load_certificate_and_key(quic_tls_ctx_t *t, VALUE certificate_path,
+                                      VALUE private_key_path)
+{
+  VALUE failure_class = rb_eArgError;
+  const char *failure = NULL;
+  VALUE failed_path = Qnil;
+  BIO *cert_bio = NULL;
+  BIO *key_bio = NULL;
+  X509 *leaf = NULL;
+  X509 *x;
+  STACK_OF(X509) *chain = NULL;
+  EVP_PKEY *pkey = NULL;
+  unsigned long err;
+
+  ERR_clear_error();
+
+  cert_bio = BIO_new_file(RSTRING_PTR(certificate_path), "r");
+  if (cert_bio == NULL || (leaf = PEM_read_bio_X509(cert_bio, NULL, NULL, NULL)) == NULL) {
+    failure = "failed to load certificate";
+    failed_path = certificate_path;
+    goto done;
+  }
+
+  if ((chain = sk_X509_new_null()) == NULL) {
+    failure_class = rb_eRuntimeError;
+    failure = "sk_X509_new_null failed";
+    goto done;
+  }
+  while ((x = PEM_read_bio_X509(cert_bio, NULL, NULL, NULL)) != NULL) {
+    if (!sk_X509_push(chain, x)) {
+      X509_free(x);
+      failure_class = rb_eRuntimeError;
+      failure = "sk_X509_push failed";
+      goto done;
+    }
+  }
+  /* The loop ends with PEM_R_NO_START_LINE once no PEM block is left. Any
+     other error means a broken block, as in SSL_CTX_use_certificate_chain_file. */
+  err = ERR_peek_last_error();
+  if (ERR_GET_LIB(err) != ERR_LIB_PEM || ERR_GET_REASON(err) != PEM_R_NO_START_LINE) {
+    failure = "failed to load certificate";
+    failed_path = certificate_path;
+    goto done;
+  }
+
+  key_bio = BIO_new_file(RSTRING_PTR(private_key_path), "r");
+  if (key_bio == NULL ||
+      (pkey = PEM_read_bio_PrivateKey(key_bio, NULL, quic_tls_no_passphrase_cb, NULL)) == NULL) {
+    failure = "failed to load private key";
+    failed_path = private_key_path;
+    goto done;
+  }
+
+  /* picotls has no counterpart of SSL_CTX_check_private_key. */
+  if (X509_check_private_key(leaf, pkey) != 1) {
+    failure = "private key does not match certificate";
+    failed_path = private_key_path;
+    goto done;
+  }
+
+  /* Takes its own reference on pkey. */
+  if (ptls_openssl_init_sign_certificate(&t->sign_cert, pkey) != 0) {
+    failure = "unsupported private key type";
+    failed_path = private_key_path;
+    goto done;
+  }
+  t->sign_cert_initialized = true;
+  t->ctx.sign_certificate = &t->sign_cert.super;
+
+  /* Copies the DER of each certificate into a list quic_tls_ctx_unref
+     releases. It fails only on allocation, and frees what it allocated then. */
+  if (ptls_openssl_load_certificates(&t->ctx, leaf, chain) != 0) {
+    failure_class = rb_eRuntimeError;
+    failure = "ptls_openssl_load_certificates failed";
+    goto done;
+  }
+
+done:
+  sk_X509_pop_free(chain, X509_free);
+  X509_free(leaf);
+  EVP_PKEY_free(pkey);
+  BIO_free(cert_bio);
+  BIO_free(key_bio);
+  ERR_clear_error();
+
+  if (failure == NULL) return;
+  if (NIL_P(failed_path)) rb_raise(failure_class, "%s", failure);
+  rb_raise(failure_class, "%s: %"PRIsVALUE, failure, failed_path);
+}
+
+VALUE
+quic_tls_context_server_new(VALUE certificate_path, VALUE private_key_path, VALUE alpn_ary)
+{
+  certificate_path = quic_path_value(certificate_path, "certificate_path");
+  private_key_path = quic_path_value(private_key_path, "private_key_path");
+  if (NIL_P(certificate_path)) rb_raise(rb_eArgError, "certificate_path must not be nil");
+  if (NIL_P(private_key_path)) rb_raise(rb_eArgError, "private_key_path must not be nil");
+
+  /* The object owns the context from the start, so that an exception below
+     releases whatever was built so far. */
+  VALUE self = TypedData_Wrap_Struct(rb_cQUICTLSContext, &quic_tls_context_type, NULL);
+  quic_tls_ctx_t *t = ZALLOC(quic_tls_ctx_t);
+  t->refcnt = 1;
+  DATA_PTR(self) = t;
+
+  /* Without an ALPN to pick, every handshake would end in
+     no_application_protocol. */
+  quic_copy_alpn(alpn_ary, &t->alpn, &t->alpn_count, &t->alpn_buf);
+  if (t->alpn_count == 0) rb_raise(rb_eArgError, "alpn must not be empty for a server");
+
+  t->ctx = (ptls_context_t){
+    .random_bytes = ptls_openssl_random_bytes,
+    .get_time = &ptls_get_time,
+    .key_exchanges = quic_key_exchanges,
+    .cipher_suites = quic_cipher_suites,
+    /* No session resumption: encrypt_ticket stays NULL, so no ticket is
+       ever issued. Keep this so that PSK-only resumption is refused once
+       resumption is added. */
+    .require_dhe_on_psk = 1,
+    .server_cipher_preference = 1,
+  };
+  if (ngtcp2_crypto_picotls_configure_server_context(&t->ctx) != 0) {
+    rb_raise(rb_eRuntimeError, "ngtcp2_crypto_picotls_configure_server_context failed");
+  }
+  /* verify_certificate stays NULL: no client certificate is requested. */
+  quic_tls_ctx_load_certificate_and_key(t, certificate_path, private_key_path);
+  t->on_client_hello.cb = quic_tls_on_client_hello_cb;
+  t->ctx.on_client_hello = &t->on_client_hello;
+  return self;
+}
+
+/* QUIC::TLSContext.server(certificate_path:, private_key_path:, alpn:). A
+   missing or unknown keyword raises ArgumentError as a Ruby method would. */
+static VALUE
+quic_tls_context_s_server(int argc, VALUE *argv, VALUE klass)
+{
+  (void)klass;
+  VALUE opts = Qnil;
+  rb_scan_args(argc, argv, "0:", &opts);
+  if (NIL_P(opts)) opts = rb_hash_new();
+
+  ID keywords[3];
+  VALUE values[3];
+  keywords[0] = rb_intern("certificate_path");
+  keywords[1] = rb_intern("private_key_path");
+  keywords[2] = rb_intern("alpn");
+  rb_get_kwargs(opts, keywords, 3, 0, values);
+  return quic_tls_context_server_new(values[0], values[1], values[2]);
+}
+
+void
+Init_quic_tls_context(VALUE rb_mQUICArg)
+{
+  rb_cQUICTLSContext = rb_define_class_under(rb_mQUICArg, "TLSContext", rb_cObject);
+  rb_undef_alloc_func(rb_cQUICTLSContext);
+  rb_define_singleton_method(rb_cQUICTLSContext, "server", quic_tls_context_s_server, -1);
+}

data/ext/quic/tls_context.h

@@ -0,0 +1,46 @@
+#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