quicsilver 0.5.0-x86_64-linux

data/lib/quicsilver/server/web_transport_flow_control.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Server
+    # The limits a peer has granted this session (draft-ietf-webtrans-http3-16
+    # §5). Session flow control sits above QUIC's own: QUIC bounds the
+    # connection and each stream, this bounds one session across all of its
+    # streams.
+    #
+    # This is what we are permitted to send. WebTransportReceiveLimits below
+    # is the mirror: what the peer may send us, against limits we advertised.
+    # The two are kept apart because the rules differ. A granted limit must
+    # increase and is never spent here; an advertised one is spent and never
+    # moves on its own.
+    #
+    # Limits start at the peer's WT_INITIAL_MAX_* settings, default 0, which
+    # means nothing can be sent until a capsule raises them (§5.5).
+    class WebTransportFlowControl
+      WT = Protocol::WebTransport
+
+      attr_reader :max_data, :max_streams_bidi, :max_streams_uni
+      attr_reader :data_sent
+
+      def self.from_settings(settings)
+        new(
+          max_data: settings[Protocol::SETTINGS_WT_INITIAL_MAX_DATA].to_i,
+          max_streams_bidi: settings[Protocol::SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI].to_i,
+          max_streams_uni: settings[Protocol::SETTINGS_WT_INITIAL_MAX_STREAMS_UNI].to_i
+        )
+      end
+
+      def initialize(max_data: 0, max_streams_bidi: 0, max_streams_uni: 0)
+        @max_data = max_data
+        @max_streams_bidi = max_streams_bidi
+        @max_streams_uni = max_streams_uni
+        @data_sent = 0
+        @streams_opened_bidi = 0
+        @streams_opened_uni = 0
+      end
+
+      # Apply a limit the peer sent. Capsules travel on the CONNECT stream and
+      # so arrive in order, which is why a limit that does not increase is an
+      # error here where the equivalent QUIC frame would simply be stale
+      # (§5.6.2, §5.6.4).
+      #
+      # The BLOCKED capsules carry a limit too, but it is the sender telling us
+      # what it was stuck behind, not a grant, so it changes nothing.
+      def apply(limit)
+        case limit.kind
+        when :max_data then @max_data = increase!(:max_data, @max_data, limit.limit)
+        when :max_streams then apply_max_streams(limit)
+        when :data_blocked, :streams_blocked then nil
+        else raise ArgumentError, "Unknown flow control capsule kind #{limit.kind}"
+        end
+      end
+
+      def max_streams(direction)
+        (direction == :bidi) ? @max_streams_bidi : @max_streams_uni
+      end
+
+      def streams_opened(direction)
+        (direction == :bidi) ? @streams_opened_bidi : @streams_opened_uni
+      end
+
+      # "An endpoint MUST NOT open more streams than permitted by the current
+      # stream limit set by its peer" (§5.6.2). The limit counts closed
+      # streams too, so this only ever rises.
+      def open_stream!(direction)
+        opened = streams_opened(direction)
+        limit = max_streams(direction)
+        if opened + 1 > limit
+          raise WT::SendBlocked.new(
+            "cannot open a #{direction} stream: #{opened} of #{limit} used",
+            limit: limit, needed: 1
+          )
+        end
+
+        if direction == :bidi
+          @streams_opened_bidi += 1
+        else
+          @streams_opened_uni += 1
+        end
+      end
+
+      # "The sum of the lengths of Stream Body data sent on all streams
+      # associated with this session MUST NOT exceed the Maximum Data value
+      # advertised by a receiver" (§5.6.4). Stream bodies only: the prefix
+      # linking a stream to its session is excluded (§5.4).
+      def send_data!(bytes)
+        return if bytes.zero?
+
+        if @data_sent + bytes > @max_data
+          raise WT::SendBlocked.new(
+            "cannot send #{bytes} bytes: #{@data_sent} of #{@max_data} used",
+            limit: @max_data, needed: bytes
+          )
+        end
+
+        @data_sent += bytes
+      end
+
+      def data_remaining = @max_data - @data_sent
+
+      private
+
+      def apply_max_streams(limit)
+        if limit.direction == :bidi
+          @max_streams_bidi = increase!(:max_streams_bidi, @max_streams_bidi, limit.limit)
+        else
+          @max_streams_uni = increase!(:max_streams_uni, @max_streams_uni, limit.limit)
+        end
+      end
+
+      # "If an endpoint receives a WT_MAX_DATA capsule with a Maximum Data
+      # value that does not increase the Maximum Data value previously
+      # received, it MUST close the WebTransport session with a
+      # WT_FLOW_CONTROL_ERROR error code." Equal is not an increase.
+      def increase!(name, current, value)
+        unless value > current
+          raise WT::FlowControlError,
+            "#{name} of #{value} does not increase the current limit of #{current}"
+        end
+
+        value
+      end
+    end
+
+    # What a peer is permitted to send us in one session, and what it has used
+    # (draft-ietf-webtrans-http3-16 §5.3, §5.4).
+    #
+    # The mirror of WebTransportFlowControl: that holds limits the peer grants
+    # us, this holds limits we granted the peer and enforces them.
+    #
+    # Limits start at the WT_INITIAL_MAX_* values we advertised and rise as we
+    # issue capsules. Counting is deliberately plain integer arithmetic: this
+    # runs on every received chunk.
+    class WebTransportReceiveLimits
+      WT = Protocol::WebTransport
+
+      attr_reader :data_received, :streams_opened_bidi, :streams_opened_uni
+
+      private def increment_closed(direction)
+        if direction == :bidi
+          @streams_closed_bidi += 1
+        else
+          @streams_closed_uni += 1
+        end
+      end
+
+      private def set_max_streams(direction, value)
+        if direction == :bidi
+          @max_streams_bidi = value
+        else
+          @max_streams_uni = value
+        end
+      end
+
+      def self.from_settings(settings)
+        new(
+          max_data: settings[Protocol::SETTINGS_WT_INITIAL_MAX_DATA].to_i,
+          max_streams_bidi: settings[Protocol::SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI].to_i,
+          max_streams_uni: settings[Protocol::SETTINGS_WT_INITIAL_MAX_STREAMS_UNI].to_i
+        )
+      end
+
+      # Grant more once half the window has been used up, the way QUIC paces
+      # MAX_DATA (§5.6 refers to RFC 9000 §4.2). Waiting until it is exhausted
+      # would stall the peer for a round trip.
+      GRANT_THRESHOLD = 2
+
+      def initialize(max_data: 0, max_streams_bidi: 0, max_streams_uni: 0)
+        @max_data = max_data
+        @max_streams_bidi = max_streams_bidi
+        @max_streams_uni = max_streams_uni
+        @data_received = 0
+        @streams_opened_bidi = 0
+        @streams_opened_uni = 0
+        @data_consumed = 0
+        @streams_closed_bidi = 0
+        @streams_closed_uni = 0
+        # The windows we advertised are the increment we extend by.
+        @data_window = max_data
+        @stream_window_bidi = max_streams_bidi
+        @stream_window_uni = max_streams_uni
+      end
+
+      attr_reader :data_consumed, :max_data, :max_streams_bidi, :max_streams_uni
+
+      # The application read `bytes`, so that much of the window is free
+      # again. Returns the new limit to advertise, or nil when it is not yet
+      # worth a capsule. "Endpoints SHOULD send WT_MAX_DATA... as they consume
+      # data" (§5.6).
+      def consume_data(bytes)
+        return if bytes.zero? || @data_window.zero?
+
+        @data_consumed += bytes
+        extended = @data_consumed + @data_window
+        return unless extended - @max_data >= @data_window / GRANT_THRESHOLD
+
+        @max_data = extended
+      end
+
+      # A stream closed, so the session can afford another. Returns the new
+      # limit to advertise, or nil.
+      def close_stream(direction)
+        window = (direction == :bidi) ? @stream_window_bidi : @stream_window_uni
+        return if window.zero?
+
+        closed = increment_closed(direction)
+        extended = closed + window
+        current = max_streams(direction)
+        return unless extended - current >= [window / GRANT_THRESHOLD, 1].max
+
+        set_max_streams(direction, extended)
+      end
+
+      def max_streams(direction)
+        (direction == :bidi) ? @max_streams_bidi : @max_streams_uni
+      end
+
+      # "If an endpoint receives an incoming stream for a session that would
+      # exceed the advertised Maximum Streams value, it MUST close the
+      # WebTransport session with a WT_FLOW_CONTROL_ERROR error code" (§5.6.2).
+      #
+      # The limit counts closed streams as well as open ones, so this only ever
+      # goes up. The CONNECT stream itself is not included (§5.3).
+      def open_stream!(direction)
+        if direction == :bidi
+          @streams_opened_bidi += 1
+          exceeded!(:max_streams_bidi, @streams_opened_bidi, @max_streams_bidi)
+        else
+          @streams_opened_uni += 1
+          exceeded!(:max_streams_uni, @streams_opened_uni, @max_streams_uni)
+        end
+      end
+
+      # "The sum of the lengths of Stream Body data sent on all streams
+      # associated with this session MUST NOT exceed the Maximum Data value
+      # advertised by a receiver... If an endpoint receives Stream Body data in
+      # excess of this limit, it MUST close the WebTransport session with a
+      # WT_FLOW_CONTROL_ERROR error code" (§5.6.4).
+      #
+      # Body only: the signal value, stream type and session ID are excluded so
+      # that linking a stream to its session never costs credit (§5.4).
+      def receive_data!(bytes)
+        return if bytes.zero?
+
+        @data_received += bytes
+        exceeded!(:max_data, @data_received, @max_data)
+      end
+
+      # A reset stream consumed credit for everything its sender counted, not
+      # just what reached us. Without charging the difference the two endpoints
+      # disagree about the session total (§5.4, RFC 9000 §4.5).
+      def reset_stream!(final_size, delivered)
+        return if final_size.nil? || final_size <= delivered
+
+        receive_data!(final_size - delivered)
+      end
+
+      private
+
+      def exceeded!(name, used, limit)
+        return if used <= limit
+
+        raise WT::FlowControlError, "#{name} exceeded: #{used} of #{limit}"
+      end
+    end
+  end
+end

data/lib/quicsilver/server/web_transport_manager.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Server
+    # Tracks WebTransport sessions and routes connection-level stream events.
+    #
+    # WebTransport child streams arrive at the QUIC/HTTP3 connection before they
+    # can be associated with a session. The stream prefix carries the session ID,
+    # and that prefix can be split across receives. This object owns that
+    # cross-session routing state so Server can stay focused on HTTP/3 dispatch.
+    #
+    # Scoped to a single connection — see WebTransportRegistry.
+    class WebTransportManager
+      MAX_PENDING_CONNECT_BYTES = 65_536
+      ConnectRequest = Struct.new(:stream_id, :stream_handle, :headers, :data, :early_data, :fin, keyword_init: true)
+
+      def initialize
+        @sessions = {}
+        @pending_streams = {}
+        @stream_states = {}
+        @starting_streams = {}
+        @pending_uni_streams = {}
+        @pending_connect = nil
+      end
+
+      def sessions
+        @sessions.values
+      end
+
+      def register(session)
+        session.stream_manager = self
+        @sessions[session.stream_id] = session
+      end
+
+      def unregister(stream_id)
+        @pending_connect = nil if @pending_connect&.stream_id == stream_id
+        @sessions.delete(stream_id)
+      end
+
+      def defer_connect(request)
+        if @pending_connect || routable_sessions.any?
+          return reject_stream(request.stream_id, request.stream_handle, error_code: Protocol::H3_REQUEST_REJECTED)
+        end
+        @pending_connect = request
+        @stream_states[request.stream_id] = :pending_connect
+        receive_pending_connect("", fin: request.fin)
+      end
+
+      def take_pending_connect
+        request = @pending_connect
+        @pending_connect = nil
+        @stream_states.delete(request.stream_id) if request
+        request
+      end
+
+      def cancel_pending_connect(stream_id, stream_handle)
+        return false unless @pending_connect&.stream_id == stream_id
+
+        reject_stream(stream_id, stream_handle, error_code: Protocol::H3_REQUEST_CANCELLED)
+        true
+      end
+
+      def session(stream_id)
+        session = @sessions[stream_id]
+        return session if session&.routable?
+
+        nil
+      end
+
+      def routable_sessions
+        @sessions.each_value.select(&:routable?)
+      end
+
+      def open_session
+        @sessions.each_value.find(&:open?)
+      end
+
+      def active_stream(stream_id)
+        owning_session(stream_id)&.stream(stream_id)
+      end
+
+      def session_for_stream(stream_id)
+        session = owning_session(stream_id)
+        session if session&.stream(stream_id)
+      end
+
+      def route_owned_stream(stream_id, stream_handle, payload, fin: false)
+        if @pending_connect&.stream_id == stream_id
+          receive_pending_connect(payload, fin: fin)
+        elsif (session = @sessions[stream_id])
+          session.receive_connect_stream_data(payload, fin: fin)
+        elsif known_stream?(stream_id)
+          if (stream = active_stream(stream_id))
+            stream.replace_stream_handle(stream_handle) if fin && stream_handle
+            fin ? stream.receive_fin(payload) : stream.receive_data(payload)
+          end
+        else
+          return false
+        end
+        true
+      end
+
+      def register_starting_stream(stream)
+        @starting_streams[stream.stream_handle] = stream
+      end
+
+      def discard_starting_stream(handle)
+        @starting_streams.delete(handle)
+      end
+
+      def stream_started(stream_id, handle)
+        return unless stream_id && stream_id.between?(0, (1 << 62) - 1)
+        return unless (stream = @starting_streams.delete(handle))
+
+        stream.session.stream_started(stream, stream_id)
+      end
+
+      def register_stream(stream_id, session_id)
+        @stream_states[stream_id] = session_id
+      end
+
+      def known_stream?(stream_id)
+        @stream_states.key?(stream_id)
+      end
+
+      def rejected_stream?(stream_id)
+        @stream_states[stream_id] == :rejected
+      end
+
+      def reject_session(session, status)
+        unregister(session.stream_id)
+        # Keep routing late data and FIN here until the CONNECT stream shuts down.
+        @stream_states[session.stream_id] = :rejected
+        session.reject!(status)
+      end
+
+      def reject_stream(stream_id, stream_handle, error_code: Protocol::WebTransport::BUFFERED_STREAM_REJECTED)
+        @pending_connect = nil if @pending_connect&.stream_id == stream_id
+        @pending_streams.delete(stream_id)
+        @pending_uni_streams.delete(stream_id)
+        @stream_states[stream_id] = :rejected
+        Transport::Stream.new(stream_handle).abort(error_code)
+        nil
+      end
+
+      def stream_shutdown_complete(stream_id, handle: nil)
+        @pending_connect = nil if @pending_connect&.stream_id == stream_id
+        starting = @starting_streams.delete(handle)
+        starting&.session&.remove_starting_stream(handle)
+        @pending_uni_streams.delete(stream_id)
+        @pending_streams.delete(stream_id)
+        owner = session_for_stream(stream_id)
+        known = @stream_states.delete(stream_id) || starting
+        if (session = @sessions.delete(stream_id))
+          session.notify_close
+          return true
+        end
+        return !!known unless owner
+
+        owner.remove_stream(stream_id)
+        true
+      end
+
+      def pending_stream?(stream_id)
+        @pending_streams.key?(stream_id)
+      end
+
+      def pending_payload(stream_id, stream_handle, payload)
+        pending = @pending_streams[stream_id]
+        if pending
+          pending[:buffer] << payload
+          payload = pending[:buffer]
+          stream_handle = pending[:handle]
+        end
+
+        case bidi_prefix_state(payload)
+        when :matched
+          @pending_streams.delete(stream_id)
+          payload
+        when :incomplete
+          @pending_streams[stream_id] ||= { handle: stream_handle, buffer: "".b }
+          @pending_streams[stream_id][:buffer] << payload unless pending
+          nil
+        else
+          @pending_streams.delete(stream_id)
+          nil
+        end
+      end
+
+      def bidi_stream?(payload)
+        bidi_prefix_state(payload) == :matched
+      end
+
+      def accept_bidi_stream(stream_id, stream_handle, payload, fin: false)
+        session_id, = WebTransportSession.parse_stream_prefix(payload)
+        return reject_stream(stream_id, stream_handle) unless session_id && @sessions[session_id]&.accepts_new_streams?
+
+        WebTransportSession.accept_stream(@sessions, stream_id, stream_handle, payload, fin: fin)
+      end
+
+      def route_unidirectional_stream(stream_id, stream_handle, payload, fin: false)
+        if (stream = active_stream(stream_id))
+          fin ? stream.receive_fin(payload) : stream.receive_data(payload)
+          return stream
+        end
+        return if known_stream?(stream_id)
+
+        payload = @pending_uni_streams.delete(stream_id).to_s.b + payload
+        _, length = Protocol.decode_varint_str(payload, 0)
+        if length == 0
+          return reject_stream(stream_id, stream_handle) if fin
+
+          @pending_uni_streams[stream_id] = payload
+          return
+        end
+        session_id, initial_data = WebTransportSession.parse_uni_stream_data(payload)
+        session = @sessions[session_id]
+        return reject_stream(stream_id, stream_handle) unless session&.accepts_new_streams?
+
+        stream = session.add_uni_stream(stream_handle, stream_id)
+        fin ? stream.receive_fin(initial_data) : stream.receive_data(initial_data)
+        stream
+      end
+
+      def receive_datagram(datagram)
+        stream_id, payload = Protocol::Datagram.decode(datagram)
+        return false unless (session = @sessions[stream_id])
+        return false unless session.open?
+
+        session.receive_datagram(payload)
+        true
+      rescue
+        false
+      end
+
+      def build_datagram(session, payload)
+        Protocol::Datagram.encode(session.stream_id, payload)
+      end
+
+      private
+
+      def receive_pending_connect(payload, fin:)
+        request = @pending_connect
+        if request.data.bytesize + payload.bytesize > MAX_PENDING_CONNECT_BYTES
+          return reject_stream(request.stream_id, request.stream_handle, error_code: Protocol::H3_EXCESSIVE_LOAD)
+        end
+
+        request.data << payload
+        request.fin ||= fin
+      end
+
+      def owning_session(stream_id)
+        session_id = @stream_states[stream_id]
+        return unless session_id.is_a?(Integer)
+
+        session(session_id)
+      end
+
+      def bidi_prefix_state(data)
+        type, type_len = Protocol.decode_varint_str(data, 0)
+        return :incomplete if type_len == 0 && incomplete_varint?(data, 0)
+        return :no_match unless type == WebTransportSession::WT_STREAM_BIDI && type_len > 0
+
+        _, sid_len = Protocol.decode_varint_str(data, type_len)
+        return :incomplete if sid_len == 0
+
+        :matched
+      rescue
+        :no_match
+      end
+
+      def incomplete_varint?(data, offset)
+        first = data.getbyte(offset)
+        return false unless first
+
+        length = 1 << ((first & 0xC0) >> 6)
+        data.bytesize - offset < length
+      end
+    end
+  end
+end

data/lib/quicsilver/server/web_transport_registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "web_transport_manager"
+
+module Quicsilver
+  class Server
+    # One WebTransportManager per QUIC connection.
+    #
+    # A session is identified by its CONNECT stream id, and QUIC stream ids
+    # restart on every connection, so two clients routinely both have a session
+    # on stream 0. Sharing one manager across connections routed streams into
+    # the wrong client's session.
+    class WebTransportRegistry
+      def initialize
+        @managers = {}
+        @mutex = Mutex.new
+      end
+
+      # The manager owning this connection's sessions, created on first use.
+      def for(connection_handle)
+        @mutex.synchronize do
+          @managers[connection_handle] ||= WebTransportManager.new
+        end
+      end
+
+      # Forget a connection, returning its sessions so the caller can notify
+      # them.
+      def drop(connection_handle)
+        manager = @mutex.synchronize { @managers.delete(connection_handle) }
+        return [] unless manager
+
+        manager.sessions
+      end
+
+      def connection_count
+        @mutex.synchronize { @managers.size }
+      end
+    end
+  end
+end