http3 0.0.3 → 0.0.5

data/lib/http3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTTP3
-  VERSION = "0.0.3"
+  VERSION = "0.0.5"
 end

data/lib/http3/worker_pool.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module HTTP3
+  # Threads that run the jobs posted to them, one at a time each:
+  #
+  #   pool = HTTP3::WorkerPool.new(3)
+  #   pool.start
+  #   pool.post { ... }
+  #   pool.stop(1) # => the threads still running after a second
+  #
+  # The pool does not count the free threads: Server posts only as many
+  # jobs as there are, so none waits for long.
+  class WorkerPool
+    # The priority of the threads. MRI shortens a thread's time slice of
+    # 100 ms by its negative priority, halving it for each step, so at -3,
+    # the least, a worker busy on the CPU keeps the thread that drives the
+    # connections waiting for the GVL 12.5 ms at a time. Which thread gets
+    # the GVL next does not change.
+    WORKER_PRIORITY = -3
+
+    def initialize(size)
+      @size = size
+      @jobs = Thread::Queue.new
+      @threads = []
+    end
+
+    # Make the threads, named "http3-worker-1" and on.
+    def start
+      @threads = Array.new(@size) do |i|
+        Thread.new { work }.tap do |thread|
+          thread.name = "http3-worker-#{i + 1}"
+          thread.priority = WORKER_PRIORITY
+          thread.report_on_exception = false
+        end
+      end
+      self
+    end
+
+    # Queue job for the next free thread, without waiting.
+    def post(&job)
+      @jobs << job
+      self
+    end
+
+    # Drop the jobs not started, let each thread end once its job is done,
+    # and wait up to timeout seconds for them all. Returns the number of
+    # threads still running.
+    def stop(timeout)
+      @jobs.clear
+      @jobs.close
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @threads.count do |thread|
+        thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max).nil?
+      end
+    end
+
+    private
+
+    def work
+      while (job = @jobs.pop)
+        begin
+          job.call
+        rescue Exception # rubocop:disable Lint/RescueException
+          # A job reports its own failures. Even exit in one leaves the
+          # thread for the next.
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/http3.rb

@@ -5,8 +5,11 @@ require_relative "http3/http3"
 
 require_relative "http3/request"
 require_relative "http3/response"
+require_relative "http3/body_pipe"
+require_relative "http3/body_stream"
 require_relative "http3/session"
 require_relative "http3/rack_adapter"
+require_relative "http3/worker_pool"
 require_relative "http3/server"
 
 module HTTP3

data/sig/http3/body_pipe.rbs

@@ -0,0 +1,45 @@
+module HTTP3
+  # The stream a response was being sent on is gone (reset by the client,
+  # or asked by it for no more (STOP_SENDING), its connection ended, the
+  # server stopped, or the response was aborted after waiting on its client
+  # for response_timeout).
+  class StreamClosed < IOError
+  end
+
+  module Body
+    # A response body written by the thread that runs the application and
+    # taken by the server's I/O loop. wake is called, with no lock held,
+    # each time the body goes from having nothing to take to having
+    # something.
+    class Pipe
+      def initialize: (capacity: Integer, wake: ^() -> void) -> void
+
+      # Queue chunk, waiting while capacity bytes or more are queued.
+      # Returns its size. Raises StreamClosed once the body was given up on,
+      # and IOError once it has ended.
+      def write: (String chunk) -> Integer
+
+      # End the body and wait until all of it has been taken.
+      def finish: () -> nil
+
+      # End the body with error, once what is queued has been taken, and
+      # wait until it has. Returns true once error has been taken, and false
+      # when it never will: the body had ended or been given up on (fail
+      # does nothing then), or was given up on while fail waited.
+      def fail: (Exception error) -> bool
+
+      # Wait until every chunk queued has been taken.
+      def flush: () -> self
+
+      # A chunk; once they have all been taken, :eof, or the exception given
+      # to #fail; nil while there is nothing yet. Never waits.
+      def take: () -> (String | :eof | Exception | nil)
+
+      # True when #take has something other than nil to return.
+      def ready?: () -> bool
+
+      # Give up on the body: the writer's calls raise StreamClosed.
+      def cancel: () -> nil
+    end
+  end
+end

data/sig/http3/body_stream.rbs

@@ -0,0 +1,41 @@
+module HTTP3
+  module Body
+    # The stream a streaming body (Rack 3's call(stream)) is called with:
+    # writes go to a Body::Pipe, reads come from the request body. Its
+    # methods behave as IO's do. Once the stream has gone away (the client
+    # reset it or sent STOP_SENDING, or it was aborted after
+    # response_timeout), write and flush raise StreamClosed, and so do
+    # close_write and close, once;
+    # writing past length, the content-length, fails the pipe and raises
+    # StreamClosed too.
+    class Stream
+      def initialize: (pipe: Pipe, input: StringIO | ::File, length: Integer?) -> void
+
+      # Read from the request body, as IO#read does. Raises IOError after
+      # close_read.
+      def read: (?Integer? length, ?String outbuf) -> String?
+
+      # Write each of objects, as a String, waiting while the pipe is full.
+      # Returns the bytes written. Raises IOError after close_write.
+      def write: (*_ToS objects) -> Integer
+
+      def <<: (_ToS object) -> self
+
+      # Wait until what has been written has been taken to be sent. Raises
+      # IOError after close_write.
+      def flush: () -> self
+
+      # Close the request body; may be called again.
+      def close_read: () -> nil
+
+      # End the body, and wait until all of it has been taken; fail the pipe
+      # instead if it is short of length. May be called again, and does
+      # nothing then.
+      def close_write: () -> nil
+
+      def close: () -> nil
+
+      def closed?: () -> bool
+    end
+  end
+end

data/sig/http3/nghttp3/connection.rbs

@@ -1,5 +1,26 @@
 module HTTP3
   module Nghttp3
+    # A callback, a Callbacks block or a body block, runs while nghttp3 is
+    # in the middle of a call on the connection, and may call back into it
+    # only as far as nghttp3 allows there. Inside the callbacks of
+    # #read_stream, it may call #submit_request, #submit_response,
+    # #submit_info, #submit_trailers, #resume_stream, #block_stream,
+    # #unblock_stream, #shutdown_stream_read, #shutdown_stream_write,
+    # #submit_shutdown_notice, #shutdown, #set_max_client_streams_bidi and
+    # #stream_writable?; inside any other callback, none of the methods that
+    # call into nghttp3. Anything else, #close among it, raises
+    # InvalidStateError. #closed?, #server?, #client?, #pending_data and the
+    # stream user data methods call no nghttp3 and can be called anywhere.
+    #
+    # Once #read_stream or #writev_stream has raised for an error nghttp3
+    # returned, or another method for a fatal one, nghttp3 allows nothing
+    # but deleting the connection: only #close and the methods that call no
+    # nghttp3 can be called, and the rest raise InvalidStateError.
+    #
+    # What nghttp3 asserts of its callers raises instead: a stream id out of
+    # 0..2**62-1 or of the wrong kind raises ArgumentError, and a call on a
+    # connection of the wrong role, or before or after the calls nghttp3
+    # needs, InvalidStateError.
     class Connection
       # Creates a new client connection
       def self.client_new: (?Settings? settings, ?Callbacks? callbacks) -> Connection
@@ -7,10 +28,12 @@ module HTTP3
       # Creates a new server connection
       def self.server_new: (?Settings? settings, ?Callbacks? callbacks) -> Connection
 
-      # Binds the control stream
+      # Binds the control stream, a unidirectional stream of this end (id % 4
+      # == 3 for a server, 2 for a client)
       def bind_control_stream: (Integer stream_id) -> self
 
-      # Binds QPACK encoder and decoder streams
+      # Binds QPACK encoder and decoder streams, unidirectional streams of
+      # this end as for bind_control_stream
       def bind_qpack_streams: (Integer encoder_stream_id, Integer decoder_stream_id) -> self
 
       # Closes the connection
@@ -29,7 +52,9 @@ module HTTP3
 
       # Reads data on a stream from the QUIC layer. ts is the time in
       # nanoseconds on a monotonic clock (CLOCK_MONOTONIC by default). An
-      # exception raised by a callback comes out of here.
+      # exception raised by a callback comes out of here. A server reads the
+      # streams the client opened (even ids), a client the request streams
+      # and the server's unidirectional streams (id % 4 of 0 or 3).
       def read_stream: (Integer stream_id, String data, ?fin: bool, ?ts: Integer?) -> Integer
 
       # Gets stream data to send to the QUIC layer. An exception raised by a
@@ -64,7 +89,7 @@ module HTTP3
       def shutdown_stream_read: (Integer stream_id) -> self
 
       # Tells a server connection how many bidirectional streams the client
-      # may open in total
+      # may open in total. It never goes down (ArgumentError).
       def set_max_client_streams_bidi: (Integer max_streams) -> self
 
       # The body Strings handed to nghttp3 that the peer has not acknowledged
@@ -72,23 +97,32 @@ module HTTP3
       def pending_data: (Integer stream_id) -> Array[String]
 
       # HTTP operations
-
-      # Submits an HTTP request (client only)
+      #
+      # The submit_* methods read each NV's name, value and flags as they
+      # are, without to_str or to_int, and raise ArgumentError for an
+      # element that is not an NV with String name and value and flags of
+      # 0..255; nothing is submitted then. They need #bind_qpack_streams
+      # first.
+
+      # Submits an HTTP request (client only) on a client-initiated
+      # bidirectional stream (id % 4 == 0)
       def submit_request: (Integer stream_id, Array[NV] headers, ?body: String?) ?{ (Integer stream_id) -> (String | Symbol | nil) } -> self
 
       # Submits an HTTP response (server only)
       def submit_response: (Integer stream_id, Array[NV] headers, ?body: String?) ?{ (Integer stream_id) -> (String | Symbol | nil) } -> self
 
-      # Submits a 1xx informational response
+      # Submits a 1xx informational response (server only)
       def submit_info: (Integer stream_id, Array[NV] headers) -> self
 
       # Submits trailer headers (implicitly ends the stream)
       def submit_trailers: (Integer stream_id, Array[NV] trailers) -> self
 
-      # Signals the intention to shut down the connection gracefully
+      # Signals the intention to shut down the connection gracefully. Needs
+      # #bind_control_stream first, and cannot follow #shutdown.
       def submit_shutdown_notice: () -> self
 
-      # Initiates graceful shutdown
+      # Initiates graceful shutdown. Needs #bind_control_stream first, and
+      # can be called once.
       def shutdown: () -> self
 
       # Associates arbitrary data with a stream

data/sig/http3/nghttp3/nv.rbs

@@ -1,6 +1,10 @@
 module HTTP3
   module Nghttp3
     class NV
+      # flags is an Integer of 0..255, the NV_FLAG_* constants or-ed
+      # together; anything else raises ArgumentError. NV_FLAG_NO_COPY_NAME
+      # and NV_FLAG_NO_COPY_VALUE are ignored, and nghttp3 copies the name
+      # and value all the same.
       def initialize: (String name, String value, ?flags: Integer) -> void
 
       def name: () -> String

data/sig/http3/nghttp3/qpack.rbs

@@ -5,7 +5,9 @@ module HTTP3
         # Creates a new QPACK encoder
         def initialize: (Integer max_dtable_capacity) -> void
 
-        # Encodes headers for a given stream
+        # Encodes headers for a given stream. headers are checked as
+        # Connection#submit_request checks them, and a stream_id out of
+        # 0..2**62-1 raises ArgumentError.
         def encode: (Integer stream_id, Array[NV] headers) -> { prefix: String, data: String, encoder_stream: String }
 
         # Reads decoder stream data
@@ -22,10 +24,15 @@ module HTTP3
       end
 
       class Decoder
+        # The most streams decoded at once: decode on a new stream past it
+        # raises InvalidStateError, until one is finished or cancelled.
+        MAX_STREAMS: Integer
+
         # Creates a new QPACK decoder
         def initialize: (Integer max_dtable_capacity, Integer max_blocked_streams) -> void
 
-        # Decodes headers from a stream
+        # Decodes headers from a stream. A stream_id out of 0..2**62-1 raises
+        # ArgumentError.
         def decode: (Integer stream_id, String data, ?fin: bool) -> { headers: Array[{ name: String, value: String, token: Integer }]?, blocked: bool, consumed: Integer }
 
         # Reads encoder stream data
@@ -34,7 +41,7 @@ module HTTP3
         # Returns data to be sent on the decoder stream
         def decoder_stream_data: () -> String
 
-        # Cancels decoding for the given stream
+        # Cancels decoding for the given stream (stream_id 0..2**62-1)
         def cancel_stream: (Integer stream_id) -> void
 
         # Sets the maximum dynamic table capacity

data/sig/http3/rack_adapter.rbs

@@ -8,11 +8,36 @@ module HTTP3
     CONNECTION_FIELDS: Array[String]
     FIELD_NAME: Regexp
     FORBIDDEN_IN_VALUE: Regexp
+    # The schemes a request may have.
+    SCHEMES: Array[String]
+    # What :authority, or host, must look like.
+    AUTHORITY: Regexp
 
-    def initialize: (untyped app) -> void
+    # A body read with each, and a streaming body, go through a Body::Pipe
+    # of pipe_capacity bytes, whose wake is wake.
+    def initialize: (untyped app, pipe_capacity: Integer, wake: ^() -> void) -> void
 
-    # Raises what the application raises, and InvalidResponse for an
-    # answer that cannot be sent; the Rack body is closed either way.
-    def call: (Request request, remote: Addrinfo) -> Response
+    # Returns [response, fill]. Answers, without calling the application,
+    # CONNECT with 501, and with 400 a request whose scheme is not http or
+    # https, whose path has a fragment, or whose authority is malformed or
+    # differs from its host field. Raises what the application raises, and
+    # InvalidResponse for an answer that cannot be sent (among them a
+    # status outside 200..599, and a content-length that is malformed or
+    # that a file or array body does not have); the Rack body is closed
+    # either way. fill is nil, the Rack body closed already, unless the
+    # response sends a body that is read with each or is a streaming body
+    # (call): then the response has a Body::Pipe, and fill writes the body
+    # to it, fails it once the body passes content-length, ends short of
+    # it or raises (or, with each, yields a chunk that is not a String),
+    # and closes the Rack body. A streaming body is called with a
+    # Body::Stream whose read reads the request body, and ends when call
+    # returns. fill returns nil, or an exception the body raised that did
+    # not abort its stream, the body having ended or the server having
+    # given up on it, for the caller to log.
+    def call: (Request request, remote: Addrinfo) -> [Response, (^() -> Exception?)?]
+
+    # The 400s and 501s #call answered since the last call, as
+    # {status => count}; the count starts over.
+    def take_refusals: () -> Hash[Integer, Integer]
   end
 end

data/sig/http3/request.rbs

@@ -1,11 +1,13 @@
 module HTTP3
   # A request as a Session put it together. headers holds [name, value]
-  # pairs with lowercase names, the pseudo-headers first.
+  # pairs with lowercase names, the pseudo-headers first. input is the
+  # body, a binary IO at its start, which becomes rack.input: a StringIO,
+  # or a temporary File once the body is past request_body_buffer_size.
   class Request < Data
     attr_reader stream_id: Integer
     attr_reader headers: Array[[String, String]]
-    attr_reader body: String
+    attr_reader input: StringIO | ::File
 
-    def self.new: (stream_id: Integer, headers: Array[[String, String]], body: String) -> Request
+    def self.new: (stream_id: Integer, headers: Array[[String, String]], input: StringIO | ::File) -> Request
   end
 end

data/sig/http3/response.rbs

@@ -3,9 +3,9 @@ module HTTP3
   class Response < Data
     attr_reader status: Integer
     attr_reader headers: Array[[String, String]]
-    attr_reader body: Body::File | Body::Chunks | nil
+    attr_reader body: Body::File | Body::Chunks | Body::Pipe | nil
 
-    def self.new: (status: Integer, headers: Array[[String, String]], body: Body::File | Body::Chunks | nil) -> Response
+    def self.new: (status: Integer, headers: Array[[String, String]], body: Body::File | Body::Chunks | Body::Pipe | nil) -> Response
   end
 
   module Body

data/sig/http3/server.rbs

@@ -1,7 +1,7 @@
 module HTTP3
   # An HTTP/3 server for a Rack 3 application on one UDP address. #run
   # serves until SIGTERM or SIGINT, then drains; SIGHUP reloads the
-  # certificate and key.
+  # certificate and key. The application runs on threads worker threads.
   class Server
     ALPN: Array[String]
     SIGNALS: Hash[String, String]
@@ -20,9 +20,22 @@ module HTTP3
       ?settings: QUIC::Settings?,
       ?qlog_dir: (String | _ToPath)?,
       ?max_connections: Integer,
+      ?threads: Integer,
       ?max_request_body: Integer,
       ?max_field_section_size: Integer,
+      ?max_connection_request_buffer: Integer,
+      ?max_total_request_buffer: Integer,
+      ?request_body_buffer_size: Integer,
+      ?max_connection_request_spool: Integer,
+      ?max_total_request_spool: Integer,
+      ?max_connection_request_spool_files: Integer,
+      ?max_total_request_spool_files: Integer,
       ?send_buffer_size: Integer,
+      ?max_connection_send_buffer: Integer,
+      ?max_total_send_buffer: Integer,
+      ?request_timeout: (Integer | Float)?,
+      ?response_timeout: (Integer | Float)?,
+      ?refusal_log_interval: Integer | Float,
       ?shutdown_timeout: Numeric,
       ?logger: Logger
     ) -> void

data/sig/http3/session.rbs

@@ -2,51 +2,174 @@ module HTTP3
   # HTTP/3 on one QUIC connection, driven by HTTP3::Server's I/O loop. The
   # on_* methods are called by the C part with the parts of each request.
   class Session
+    # What .shared_buffer returns, to be passed to .attach as it is.
+    type shared_buffer = Object
+
+    # What .shared_spool returns, to be passed to .attach as it is.
+    type shared_spool = Object
+
+    # What a field counts for besides its name and value (RFC 9114 section
+    # 4.2.2).
+    FIELD_OVERHEAD: Integer
+
     # Take over quic_conn's streams. Requests over max_request_body bytes of
-    # body get 413, over max_field_section_size bytes of headers 431.
-    def self.attach: (QUIC::Connection::Server quic_conn, max_request_body: Integer, max_field_section_size: Integer) -> Session
+    # body get 413, over max_field_section_size bytes of headers 431, as
+    # soon as they pass the limit; the rest of them is not read. Requests
+    # may hold max_connection_request_buffer bytes, and those of every
+    # Session sharing shared_buffer its limit; more gets 503. One not in
+    # full within request_timeout seconds of its headers gets 408, and one
+    # not handed out within request_timeout seconds of its end 503
+    # (#expire_requests); nil is no limit. A body past
+    # request_body_buffer_size bytes goes to a temporary file, all of it
+    # (.spool_file). The files may hold max_connection_request_spool bytes
+    # and be max_connection_request_spool_files many; those of every
+    # Session sharing shared_spool count against its limits. More, or a
+    # file that cannot be made or written, gets 503. A request counts until
+    # its stream closes, or, once handed out, until #finish, though its
+    # stream or connection has gone. A response whose body has waited on
+    # its client for response_timeout seconds is aborted
+    # (#expire_responses): a limit on a stall, not on the whole response;
+    # nil is no limit. The caller calls #expire_requests and
+    # #expire_responses every turn, and waits no longer than
+    # #next_request_deadline and #next_response_deadline.
+    def self.attach: (QUIC::Connection::Server quic_conn, max_request_body: Integer, max_field_section_size: Integer,
+                      ?max_connection_request_buffer: Integer, ?shared_buffer: shared_buffer?,
+                      ?request_timeout: (Integer | Float)?, ?request_body_buffer_size: Integer,
+                      ?max_connection_request_spool: Integer, ?max_connection_request_spool_files: Integer,
+                      ?shared_spool: shared_spool?, ?response_timeout: (Integer | Float)?) -> Session
+
+    # A limit of limit bytes for the requests of every Session given it.
+    def self.shared_buffer: (Integer limit) -> shared_buffer
+
+    # Limits of limit bytes in temporary files, and of files open at once,
+    # for the requests of every Session given it.
+    def self.shared_spool: (Integer limit, files: Integer) -> shared_spool
+
+    # A temporary file without a name in Dir.tmpdir, in binary mode.
+    # Raises SystemCallError when none can be had.
+    def self.spool_file: () -> ::File
 
     def self._attach: (QUIC::Connection::Server quic_conn, Integer max_field_section_size) -> Session
 
-    # Finished requests, each with the status to answer it with directly
-    # (413, 431) or nil for the application to answer it.
-    def take_requests: () -> Array[[Request, Integer?]]
+    # The requests refused since the last call, each with the status to
+    # answer it with directly (408, 413, 431, 503). One comes out as soon
+    # as it is refused, with neither headers nor body.
+    def take_refusals: () -> Array[[Request, Integer]]
+
+    # The next request received in full, for the application, or nil. The
+    # caller closes its input, and calls #finish, once done with it; what
+    # it holds counts until then, even after its stream has closed.
+    def next_request: () -> Request?
+
+    # The caller is done with a request #next_request handed out: what it
+    # held no longer counts, though its stream or connection has gone.
+    # Calling it again does nothing.
+    def finish: (Integer stream_id) -> void
+
+    # True while the request on stream_id can still be answered: its stream
+    # is open, the client has neither reset it nor asked for no more of it
+    # (STOP_SENDING), it has not been refused, and it has not been answered.
+    def answerable?: (Integer stream_id) -> bool
+
+    # The first exception a temporary file raised since the last call (its
+    # request got 503), or nil.
+    def take_spool_error: () -> Exception?
+
+    # Refuse with 408 the requests still coming in whose request_timeout
+    # has passed at now (CLOCK_MONOTONIC), and with 503 those that have
+    # waited that long to be handed out.
+    def expire_requests: (Float now) -> void
+
+    # When the next request still coming in, or waiting to be handed out,
+    # runs out of time, or nil.
+    def next_request_deadline: () -> Float?
+
+    # Abort with H3_REQUEST_CANCELLED the responses whose body has waited
+    # on its client response_timeout seconds or more at now
+    # (CLOCK_MONOTONIC), cancelling a Body::Pipe, whose writer then gets
+    # StreamClosed. Returns how many.
+    def expire_responses: (Float now) -> Integer
+
+    # When the next response waiting on its client runs out of time, or nil.
+    def next_response_deadline: () -> Float?
 
     # Send response. Yields the exception of a file body whose descriptor
-    # could not be duplicated; its stream is aborted.
+    # could not be duplicated; its stream is aborted. Raises
+    # Nghttp3::InvalidStateError for a request already answered.
     def respond: (Request request, Response response) ?{ (SystemCallError error) -> void } -> void
 
-    # Queue more of each Body::Chunks body, up to limit unsent bytes per
-    # stream. Yields the request and exception of a body that raised.
-    def fill_bodies: (Integer limit) ?{ (Request request, Exception error) -> void } -> void
+    # Queue more of each Body::Chunks and Body::Pipe body, up to limit
+    # unsent bytes per stream, connection_limit on the connection, and room
+    # bytes queued now (nil for no limit); a chunk may pass a limit.
+    # Returns the bytes queued. Yields the request (its pseudo-headers
+    # only, without body) and exception of a body that raised or failed.
+    def fill_bodies: (Integer limit, ?connection_limit: Integer?, ?room: Integer?) ?{ (Request request, Exception error) -> void } -> Integer
+
+    # True when a Body::Chunks body, or a Body::Pipe with something to
+    # take, could take more.
+    def wants_fill?: (Integer limit, ?connection_limit: Integer?, ?room: Integer?) -> bool
 
-    def wants_fill?: (Integer limit) -> bool
+    # Bytes of the Body::Chunks and Body::Pipe bodies queued but not taken
+    # by nghttp3 yet.
+    def unsent_total: () -> Integer
 
-    # True while a request stream is open.
+    # True while a request stream is open, or a request waits to be handed
+    # out.
     def busy?: () -> bool
 
-    # Let go of closed streams; yields a body close that raised.
+    # Let go of closed streams (a Body::Pipe is cancelled); yields a body
+    # close that raised. Resets our side of the requests the client reset
+    # before their end (H3_REQUEST_INCOMPLETE), and of those it reset once
+    # they had come in full, while they waited to be handed out or once
+    # handed out and not answered (H3_REQUEST_CANCELLED).
     def release_closed: () ?{ (Integer stream_id, Exception error) -> void } -> void
 
-    # Close every body still held.
+    # The connection is gone: let go of the nghttp3 connection and, of each
+    # body, of what nghttp3 has not taken (a file body's descriptor
+    # included), then close every body still held. Afterwards submit_response
+    # and stop_reading raise Nghttp3::InvalidStateError, as on a failed
+    # connection, and push_chunk, push_eof and attach_file as on an aborted
+    # stream. What the requests handed out hold counts until #finish.
     def release_all: () ?{ (Integer stream_id, Exception error) -> void } -> void
 
+    # Called inside nghttp3, or inside the QUIC connection's packet
+    # handling, where submit_response, stop_reading, push_chunk, push_eof,
+    # attach_file, shutdown_notice and abort_stream (and so respond), and
+    # release_all, raise Nghttp3::InvalidStateError.
     def on_begin_headers: (Integer id) -> void
     def on_header: (Integer id, String name, String value) -> void
     def on_fields_too_large: (Integer id) -> void
     def on_end_headers: (Integer id) -> void
     def on_data: (Integer id, String bytes) -> void
     def on_end_stream: (Integer id) -> void
+    # The client reset its side of the stream.
+    def on_reset: (Integer id) -> void
+    # The client asked for no more of the response (STOP_SENDING).
+    def on_stop_sending: (Integer id) -> void
 
     # The C part.
     def submit_response: (Integer stream_id, Array[[String, String]] headers, bool has_body) -> self
+    # Read no more of the request on stream_id (STOP_SENDING with
+    # H3_NO_ERROR); for one answered before it has arrived in full.
+    def stop_reading: (Integer stream_id) -> self
+    # These three raise Nghttp3::InvalidStateError once the stream has been
+    # aborted.
     def push_chunk: (Integer stream_id, String str) -> self
     def push_eof: (Integer stream_id) -> self
     def attach_file: (Integer stream_id, IO io, Integer offset, Integer length) -> self
     def unsent_bytes: (Integer stream_id) -> Integer
+    # Since when (CLOCK_MONOTONIC seconds) the response body on stream_id
+    # has waited on the client with nothing moving: no acknowledgement of
+    # it, no wider flow control window for it, and, while that window does
+    # not hold it back, no acknowledgement of any body on the connection.
+    # nil while none of it waits, without a body, and once aborted.
+    def response_stalled_since: (Integer stream_id) -> Float?
     def take_closed: () -> Array[Integer]
     def take_error: () -> Exception?
     def shutdown_notice: () -> self
+    # Stop the stream in both directions with app_error_code. What of the
+    # body nghttp3 has not taken is let go at once (unsent_bytes no longer
+    # counts it), and a file body's descriptor closed.
     def abort_stream: (Integer stream_id, Integer app_error_code) -> self
   end
 end

data/sig/http3/worker_pool.rbs

@@ -0,0 +1,19 @@
+module HTTP3
+  # Threads that run the jobs posted to them, one at a time each.
+  class WorkerPool
+    # The priority of the threads, the least MRI has.
+    WORKER_PRIORITY: Integer
+
+    def initialize: (Integer size) -> void
+
+    # Make the threads, named "http3-worker-1" and on.
+    def start: () -> self
+
+    # Queue a job for the next free thread, without waiting.
+    def post: () { () -> void } -> self
+
+    # Drop the jobs not started, and wait up to timeout seconds for the
+    # threads to end. Returns the number still running.
+    def stop: (Numeric timeout) -> Integer
+  end
+end

data/sig/http3.rbs

@@ -26,6 +26,9 @@ module HTTP3
     # NV flag constants
     NV_FLAG_NONE: Integer
     NV_FLAG_NEVER_INDEX: Integer
+    # Ignored: nghttp3 always copies the name and value. It would otherwise
+    # read them when writev_stream sends them, and nothing keeps the Strings
+    # alive, or in place, until then.
     NV_FLAG_NO_COPY_NAME: Integer
     NV_FLAG_NO_COPY_VALUE: Integer
     NV_FLAG_TRY_INDEX: Integer