http3 0.0.3 → 0.0.4

data/lib/http3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTTP3
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 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,26 @@ 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
 
-    # Raises what the application raises, and InvalidResponse for an
-    # answer that cannot be sent; the Rack body is closed either way.
+    # 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
+
+    # 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/server.rbs

@@ -22,7 +22,13 @@ module HTTP3
       ?max_connections: Integer,
       ?max_request_body: Integer,
       ?max_field_section_size: Integer,
+      ?max_connection_request_buffer: Integer,
+      ?max_total_request_buffer: Integer,
       ?send_buffer_size: Integer,
+      ?max_connection_send_buffer: Integer,
+      ?max_total_send_buffer: Integer,
+      ?request_timeout: (Integer | Float)?,
+      ?refusal_log_interval: Integer | Float,
       ?shutdown_timeout: Numeric,
       ?logger: Logger
     ) -> void

data/sig/http3/session.rbs

@@ -2,44 +2,88 @@ 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 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
+    # 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.
+    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
+
+    # A limit of limit bytes for the requests of every Session given it.
+    def self.shared_buffer: (Integer limit) -> shared_buffer
 
     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.
+    # (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?]]
 
+    # Refuse with 408 the requests still coming in whose request_timeout
+    # has passed at now (CLOCK_MONOTONIC).
+    def expire_requests: (Float now) -> void
+
+    # When the next request still coming in runs out of time, or nil.
+    def next_request_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
+    # 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.
+    def fill_bodies: (Integer limit, ?connection_limit: Integer?, ?room: Integer?) ?{ (Request request, Exception error) -> void } -> Integer
+
+    def wants_fill?: (Integer limit, ?connection_limit: Integer?, ?room: Integer?) -> bool
 
-    def wants_fill?: (Integer limit) -> bool
+    # Bytes of the Body::Chunks bodies queued but not taken by nghttp3 yet.
+    def unsent_total: () -> Integer
 
     # True while a request stream is open.
     def busy?: () -> bool
 
-    # Let go of closed streams; yields a body close that raised.
+    # 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).
     def release_closed: () ?{ (Integer stream_id, Exception error) -> void } -> void
 
     # Close every body still held.
     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.
     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 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
     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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http3
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Yusuke Nakamura
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.3
+        version: 0.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.3
+        version: 0.0.5
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement