http3 0.0.4 → 0.0.5

data/lib/http3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTTP3
-  VERSION = "0.0.4"
+  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/rack_adapter.rbs

@@ -13,18 +13,28 @@ module HTTP3
     # 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
 
-    # 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. A body read with each
-    # raises InvalidResponse from next once it passes content-length or ends
-    # short of it.
-    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.

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,14 +20,21 @@ 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

data/sig/http3/session.rbs

@@ -5,6 +5,9 @@ module HTTP3
     # 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
@@ -12,64 +15,127 @@ module HTTP3
     # 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, as
     # soon as they pass the limit; the rest of them is not read. Requests
-    # not yet taken 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
-    # (#expire_requests); nil is no limit.
+    # 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)?) -> Session
+                      ?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
-    # (408, 413, 431, 503) or nil for the application to answer it. One
-    # answered directly comes out as soon as it is refused, with neither
-    # headers nor body.
-    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).
+    # 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 runs out of time, or nil.
+    # 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. 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, 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.
+    # 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
 
-    # Bytes of the Body::Chunks bodies queued but not taken by nghttp3 yet.
+    # 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. Resets our
-    # side of the requests the client reset before their end
-    # (H3_REQUEST_INCOMPLETE).
+    # 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) raise
-    # Nghttp3::InvalidStateError.
+    # 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
@@ -78,19 +144,32 @@ module HTTP3
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http3
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Yusuke Nakamura
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.6
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -75,9 +75,6 @@ extensions:
 - ext/http3/extconf.rb
 extra_rdoc_files: []
 files:
-- ".clang-format"
-- ".vscode/extensions.json"
-- ".vscode/settings.json"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE-DEPENDENCIES.txt
@@ -94,13 +91,18 @@ files:
 - ext/http3/nghttp3_settings.c
 - ext/http3/session.c
 - lib/http3.rb
+- lib/http3/body_pipe.rb
+- lib/http3/body_stream.rb
 - lib/http3/rack_adapter.rb
 - lib/http3/request.rb
 - lib/http3/response.rb
 - lib/http3/server.rb
 - lib/http3/session.rb
 - lib/http3/version.rb
+- lib/http3/worker_pool.rb
 - sig/http3.rbs
+- sig/http3/body_pipe.rbs
+- sig/http3/body_stream.rbs
 - sig/http3/nghttp3/callbacks.rbs
 - sig/http3/nghttp3/connection.rbs
 - sig/http3/nghttp3/error.rbs
@@ -113,6 +115,7 @@ files:
 - sig/http3/response.rbs
 - sig/http3/server.rbs
 - sig/http3/session.rbs
+- sig/http3/worker_pool.rbs
 homepage: https://github.com/unasuke/http3-ruby
 licenses:
 - MIT

data/.clang-format

@@ -1 +0,0 @@
-BasedOnStyle: LLVM

data/.vscode/extensions.json

@@ -1,6 +0,0 @@
-{
-    "recommendations": [
-        "ms-vscode.cpptools",
-        "shopify.ruby-lsp",
-    ]
-}

data/.vscode/settings.json

@@ -1,10 +0,0 @@
-{
-    "[c][cpp]": {
-        "editor.formatOnSave": true,
-        "editor.defaultFormatter": "ms-vscode.cpptools"
-    },
-    "[json][jsonc]": {
-        "editor.formatOnSave": true,
-        "editor.defaultFormatter": "vscode.json-language-features"
-    }
-}