quicsilver 0.5.0-x86_64-linux

data/lib/quicsilver/server/web_transport_stream.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "protocol/http/body/writable"
+require_relative "receive_queue"
+
+module Quicsilver
+  class Server
+    # A reliable bidirectional stream within a WebTransport session.
+    #
+    # Streams are opened by either the client or server. Data is reliable
+    # and ordered — unlike datagrams, nothing is dropped.
+    #
+    # Usage:
+    #   session.on_stream do |stream|
+    #     Thread.new do
+    #       while (data = stream.read)
+    #         stream.write("echo: #{data}")
+    #       end
+    #       stream.close_write
+    #     end
+    #   end
+    #
+    #   # Server-initiated:
+    #   stream = session.open_stream
+    #   stream.write("server push")
+    #   stream.close
+    #
+    class WebTransportStream
+      class ResetError < Quicsilver::Error
+        attr_reader :http_error_code, :application_error_code
+
+        def initialize(http_error_code)
+          @http_error_code = http_error_code
+          @application_error_code = Protocol::WebTransport.http_to_application_error(http_error_code)
+          super("WebTransport stream reset (HTTP/3 code 0x#{http_error_code.to_s(16)})")
+        end
+      end
+
+      attr_reader :stream_id, :session
+
+      def self.validate_overflow_code(code)
+        unless code.is_a?(Integer) && code.between?(0, 0xffff_ffff)
+          raise ArgumentError, "Receive overflow code must be a 32-bit application error code"
+        end
+      end
+
+      def self.validate_backpressure(enabled, bytes, chunks)
+        unless enabled == true || enabled == false
+          raise ArgumentError, "Receive backpressure must be true or false"
+        end
+        if enabled && [bytes, chunks].any? { |limit| limit > 0xffff_ffff_ffff_ffff }
+          raise ArgumentError, "Receive backpressure limits must fit in 64 bits"
+        end
+      end
+
+      # The receive policy has one home: WebTransportSession#accept! defines
+      # the defaults and passes them in, so there is nothing to keep in sync.
+      def initialize(session:, stream:, stream_id:, direction: :bidi,
+        receive_buffer_bytes:, receive_buffer_chunks:, receive_overflow_code:,
+        receive_backpressure:)
+        @session = session
+        @stream = stream
+        @stream_id = stream_id
+        # Stream body bytes accepted from the peer, for session accounting.
+        @body_received = 0
+        @session_stream_closed = false
+        @direction = direction
+        @read_open = direction != :send_only
+        @write_open = direction != :receive_only
+        self.class.validate_overflow_code(receive_overflow_code)
+        @receive_overflow_error = Protocol::WebTransport.application_error_to_http(receive_overflow_code)
+        @receive_queue = ReceiveQueue.new(bytes: receive_buffer_bytes, chunks: receive_buffer_chunks)
+        self.class.validate_backpressure(receive_backpressure, receive_buffer_bytes, receive_buffer_chunks)
+        @receive_backpressure = receive_backpressure
+        @input = ::Protocol::HTTP::Body::Writable.new(queue: @receive_queue)
+        @close_callback = nil
+        @peer_reset_callback = nil
+        @peer_stop_sending_callback = nil
+        @close_notified = false
+      end
+
+      def stream_handle
+        @stream.handle if @stream.respond_to?(:handle)
+      end
+
+      def notify_start(stream_id)
+        @stream_id = stream_id
+      end
+
+      def replace_stream_handle(handle)
+        @stream = Transport::Stream.new(handle)
+      end
+
+      def write(data)
+        raise "Cannot write to a receive-only stream" if @direction == :receive_only
+        raise IOError, "Stream is closed for writing" unless @write_open
+
+        payload = data.to_s.b
+        # Charge the session budget before the bytes leave. Raises SendBlocked
+        # when the peer has not granted enough, having told it so (draft-16
+        # §5.6.4); nothing is sent in that case.
+        @session&.count_sent_data(payload.bytesize)
+        @stream.send(payload)
+      end
+
+      # Whether `bytes` can be written now. Writes are all or nothing, so a
+      # write past the session's remaining credit raises SendBlocked and sends
+      # nothing; check here to avoid that.
+      def writable?(bytes = 1)
+        return false unless @write_open && @direction != :receive_only
+
+        @session.nil? || @session.can_send?(bytes)
+      end
+
+      # Finish sending and discard unread input; use close_write to keep reading.
+      def close
+        close_write
+      ensure
+        discard_input
+      end
+
+      # One application reader; never call from the transport event loop.
+      def read
+        raise IOError, "Cannot read from a send-only stream" if @direction == :send_only
+
+        chunk = @input.read
+        # Reading frees session window, which is what the peer is granted more
+        # against (draft-16 §5.6).
+        @session&.count_consumed_data(chunk.bytesize) if chunk
+        chunk
+      end
+
+      def on_close(&block)
+        @close_callback = block
+      end
+
+      # The peer reset its sending side (RESET_STREAM): our read side is now
+      # closed and `read` raises ResetError. Writing is unaffected.
+      #
+      # Yields the application error code, or nil when the peer used a code
+      # outside the WebTransport range (draft-16 §4.4 — still a reset, just no
+      # application code to report).
+      def on_peer_reset(&block)
+        @peer_reset_callback = block
+      end
+
+      # The peer asked us to stop sending (STOP_SENDING): our write side is now
+      # closed and `write` raises IOError. Reading is unaffected.
+      #
+      # Yields the application error code on the same terms as on_peer_reset.
+      def on_peer_stop_sending(&block)
+        @peer_stop_sending_callback = block
+      end
+
+      # Reset this stream with an application error code.
+      #
+      # §4.4: application codes are 32-bit and share the HTTP/3 error space, so
+      # they are mapped into the reserved WT_APPLICATION_ERROR range.
+      def reset(error_code)
+        return unless @write_open || @read_open
+
+        abort(Protocol::WebTransport.application_error_to_http(error_code))
+      end
+
+      def abort(http_error_code)
+        @stream.abort(http_error_code)
+      ensure
+        notify_close(error: ResetError.new(http_error_code))
+      end
+
+      def open?
+        @read_open || @write_open
+      end
+
+      def enable_receive_backpressure
+        return unless @receive_backpressure && @read_open
+
+        @receive_queue.release_capacity_to do |bytes, chunks|
+          unless @stream.grant_receive_credit(bytes, chunks)
+            abort(@receive_overflow_error) if @read_open
+          end
+        end
+      end
+
+      # Called by Server when data arrives on this stream. :nodoc:
+      def receive_data(data)
+        return true unless @read_open
+
+        data ||= "".b
+        # Every byte here was sent inside a limit we advertised, so it is
+        # accepted (RFC 9000 §4.1). With backpressure on, the pause is that we
+        # stop granting native receive credit until the reader drains (§4.2);
+        # credit bounds every receive after the first grant, and the first is
+        # bounded by the initial stream window from the handshake. With
+        # backpressure off there is no pause, only the overflow policy below.
+        accepted = data.bytesize
+        if accepted.positive?
+          @input.write(data)
+          # Stream body only; the prefix that links this stream to its session
+          # is stripped before we see it and costs no credit (draft-16 §5.4).
+          @body_received += accepted
+          @session&.count_received_data(accepted)
+        end
+        return overflow! if !@receive_backpressure && @receive_queue.over_limit?
+
+        enable_receive_backpressure
+        true
+      rescue ::Protocol::HTTP::Body::Writable::Closed, ClosedQueueError, ResetError
+        # Closing can race the write after the read-open check above.
+        raise if @read_open
+
+        # The read side is already closed, so this data was not consumed and
+        # there is no read side left to close. Never report full consumption.
+        false
+      end
+
+      # receive_backpressure: false. The reader is too far behind and the app
+      # chose not to slow the peer, so ask it to stop (RFC 9000 §3.5) and close
+      # our read side; the write side stays open so the app can still say why.
+      def overflow!
+        @stream.stop_sending(@receive_overflow_error)
+        false
+      ensure
+        close_read(ResetError.new(@receive_overflow_error))
+      end
+
+      # A FIN only ends the read side once its data is fully consumed; under
+      # backpressure a deferred suffix is still outstanding. :nodoc:
+      def receive_fin(data)
+        notify_read_close if receive_data(data)
+      end
+
+      # Called by Server when the peer has closed its write side. :nodoc:
+      def notify_read_close
+        return unless @read_open
+
+        @read_open = false
+        @input.close_write
+        notify_close_callback
+      end
+
+      # RESET_STREAM ends our read side; the write side stays open. :nodoc:
+      def notify_peer_reset(http_error_code, final_size = nil)
+        error = ResetError.new(http_error_code)
+        begin
+          # The sender counted everything up to the final size, including what
+          # never reached us, so the session owes credit for the difference
+          # (§5.4).
+          @session&.count_reset_stream(final_size, @body_received)
+          close_read(error)
+        ensure
+          @peer_reset_callback&.call(error.application_error_code)
+        end
+      end
+
+      # STOP_SENDING ends our write side; MsQuic answers it, and we keep
+      # receiving on the read side. :nodoc:
+      def notify_peer_stop_sending(http_error_code)
+        @write_open = false
+        begin
+          notify_close_callback unless open?
+        ensure
+          @peer_stop_sending_callback&.call(Protocol::WebTransport.http_to_application_error(http_error_code))
+        end
+      end
+
+      # Called by Server when the stream is reset or fully closed. :nodoc:
+      #
+      # Under backpressure an errored close also sends STOP_SENDING. abort
+      # already requests a transport abort, so this is belt and braces for a
+      # stream with paused input; it is not known to be required. It cannot
+      # re-enter notify_peer_stop_sending, since our own STOP_SENDING is not
+      # delivered back to us as a peer event.
+      def notify_close(error: nil)
+        if error && @receive_backpressure && @read_open
+          @stream.stop_sending(error.http_error_code)
+        end
+      ensure
+        @read_open = false
+        @write_open = false
+        error ? @input.close(error) : @input.close_write
+        notify_close_callback
+      end
+
+      def close_write
+        return unless @write_open
+
+        @stream.send("".b, fin: true)
+        @write_open = false
+        notify_close_callback unless open?
+      end
+
+      private
+
+      # Close the read half and fail pending reads, leaving the write half as is.
+      def close_read(error)
+        @read_open = false
+        @input.close(error)
+        notify_close_callback unless open?
+      end
+
+      def discard_input
+        @stream.stop_sending(Protocol::WebTransport.application_error_to_http(0)) if @read_open
+      ensure
+        @read_open = false
+        @input.close
+        notify_close_callback
+      end
+
+      def notify_session_stream_closed
+        return if @session_stream_closed
+
+        @session_stream_closed = true
+        @session&.count_closed_stream(@direction == :bidi ? :bidi : :uni)
+      end
+
+      def notify_close_callback
+        return if @close_notified
+
+        @close_notified = true
+        notify_session_stream_closed
+        @close_callback&.call
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/configuration.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class Configuration
+      # True when max_concurrent_requests is our default rather than the
+      # application's choice. :nodoc:
+      def max_concurrent_requests_default? = @max_concurrent_requests_default
+
+      # Advertise a stream limit the server can actually serve. RFC 9114 A.1:
+      # "In contrast to HTTP/2, stream concurrency in HTTP/3 is managed by
+      # QUIC." Advertising more than we can hold means a peer opens streams we
+      # then reject with 503, which is a refusal for doing exactly what we
+      # permitted. :nodoc:
+      def limit_concurrent_requests!(capacity)
+        return unless @max_concurrent_requests_default
+        return if capacity >= @max_concurrent_requests
+
+        @max_concurrent_requests = capacity
+      end
+
+      attr_reader :cert_file, :key_file, :idle_timeout_ms, :server_resumption_level, :max_concurrent_requests,
+        :max_unidirectional_streams, :stream_receive_window, :stream_receive_buffer, :connection_flow_control_window,
+        :pacing_enabled, :send_buffering_enabled, :initial_rtt_ms, :initial_window_packets, :max_ack_delay_ms,
+        :keep_alive_interval_ms, :congestion_control_algorithm, :migration_enabled,
+        :disconnect_timeout_ms, :handshake_idle_timeout_ms,
+        :max_body_size, :max_header_size, :max_header_count, :max_frame_payload_size,
+        :early_data_policy,
+        :cibir_id, :transport_server_id,
+        :mode
+
+      QUIC_SERVER_RESUME_AND_ZERORTT = 1
+      QUIC_SERVER_RESUME_ONLY = 2
+      QUIC_SERVER_RESUME_AND_REUSE = 3
+      QUIC_SERVER_RESUME_AND_REUSE_ZERORTT = 4
+
+      # Congestion control algorithms
+      CONGESTION_CONTROL_CUBIC = 0
+      CONGESTION_CONTROL_BBR = 1
+
+      DEFAULT_ALPN = "h3"
+
+      # Flow control defaults — cross-referenced with quiche, quic-go, lsquic, RFC 9000
+      # See: https://github.com/microsoft/msquic/blob/main/docs/Settings.md
+      DEFAULT_STREAM_RECEIVE_WINDOW = 262_144       # 256KB (quiche/quic-go use 1MB, MsQuic default 64KB)
+      DEFAULT_STREAM_RECEIVE_BUFFER = 32_768        # 32KB (MsQuic default 4KB — too small for typical responses)
+      DEFAULT_CONNECTION_FLOW_CONTROL_WINDOW = 16_777_216  # 16MB - connection-wide flow control
+
+      # Throughput defaults
+      DEFAULT_PACING_ENABLED = true              # RFC 9002: MUST pace or limit bursts
+      DEFAULT_SEND_BUFFERING_ENABLED = true      # MsQuic recommended — coalesces small writes
+      DEFAULT_INITIAL_RTT_MS = 100               # MsQuic default 333ms is satellite-grade; 100ms matches Chromium
+      DEFAULT_INITIAL_WINDOW_PACKETS = 10        # Matches RFC 9002 recommendation
+      DEFAULT_MAX_ACK_DELAY_MS = 25              # Matches RFC 9000 default
+
+      # HTTP/3 parser limits — prevent OOM from malicious clients
+      DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024   # 10MB — matches common reverse proxy defaults
+      DEFAULT_MAX_HEADER_SIZE = 65_536           # 64KB — matches Envoy/nginx defaults
+      DEFAULT_MAX_HEADER_COUNT = 100             # Matches nginx default
+      DEFAULT_MAX_FRAME_PAYLOAD_SIZE = 1_048_576 # 1MB — single frame can't exceed this
+
+
+      # Connection management defaults
+      DEFAULT_KEEP_ALIVE_INTERVAL_MS = 0         # 0 = disabled. Set to 20000 for NAT traversal
+      DEFAULT_CONGESTION_CONTROL_ALGORITHM = CONGESTION_CONTROL_CUBIC  # CUBIC (0) or BBR (1)
+      DEFAULT_MIGRATION_ENABLED = true           # Client IP migration. Disable behind load balancers
+      DEFAULT_DISCONNECT_TIMEOUT_MS = 16_000     # How long to wait for ACK before path declared dead
+      DEFAULT_HANDSHAKE_IDLE_TIMEOUT_MS = 10_000 # Handshake timeout (separate from connection idle)
+
+      # Matches MsQuic and quic-go. A handler slower than this loses its
+      # response: the lower of the two endpoints' values applies.
+      DEFAULT_IDLE_TIMEOUT_MS = 30_000
+
+      def initialize(cert_file = nil, key_file = nil, options = {})
+        @idle_timeout_ms = options.fetch(:idle_timeout_ms, DEFAULT_IDLE_TIMEOUT_MS)
+        @server_resumption_level = options.fetch(:server_resumption_level, QUIC_SERVER_RESUME_AND_ZERORTT)
+        # Maximum concurrent bidirectional streams the peer can open.
+        # Matches quic-go and Chromium defaults. MsQuic ceiling: 65,535.
+        @max_concurrent_requests = options.fetch(:max_concurrent_requests, 100)
+        # Whether the application chose this, or it is our default. A server
+        # that knows its own capacity lowers the default so the limit it
+        # advertises is one it can honour; an explicit value is never touched.
+        @max_concurrent_requests_default = !options.key?(:max_concurrent_requests)
+
+        # Maximum concurrent unidirectional streams the peer can open.
+        # HTTP/3 requires 3 (control, QPACK encoder, QPACK decoder).
+        # Default of 10 provides headroom for GREASE and server push.
+        # Bump to 100 for WebTransport (opens many uni streams for
+        # server-initiated data channels) or MASQUE proxy tunnels.
+        @max_unidirectional_streams = options.fetch(:max_unidirectional_streams, 10)
+        @alpn = options.fetch(:alpn, DEFAULT_ALPN)
+
+        # Flow control
+        @stream_receive_window = options.fetch(:stream_receive_window, DEFAULT_STREAM_RECEIVE_WINDOW)
+        @stream_receive_buffer = options.fetch(:stream_receive_buffer, DEFAULT_STREAM_RECEIVE_BUFFER)
+        @connection_flow_control_window = options.fetch(:connection_flow_control_window, DEFAULT_CONNECTION_FLOW_CONTROL_WINDOW)
+
+        # Throughput
+        @pacing_enabled = options.fetch(:pacing_enabled, DEFAULT_PACING_ENABLED)
+        @send_buffering_enabled = options.fetch(:send_buffering_enabled, DEFAULT_SEND_BUFFERING_ENABLED)
+        @initial_rtt_ms = options.fetch(:initial_rtt_ms, DEFAULT_INITIAL_RTT_MS)
+        @initial_window_packets = options.fetch(:initial_window_packets, DEFAULT_INITIAL_WINDOW_PACKETS)
+        @max_ack_delay_ms = options.fetch(:max_ack_delay_ms, DEFAULT_MAX_ACK_DELAY_MS)
+
+        # Connection management
+        @keep_alive_interval_ms = options.fetch(:keep_alive_interval_ms, DEFAULT_KEEP_ALIVE_INTERVAL_MS)
+        @congestion_control_algorithm = options.fetch(:congestion_control_algorithm, DEFAULT_CONGESTION_CONTROL_ALGORITHM)
+        @migration_enabled = options.fetch(:migration_enabled, DEFAULT_MIGRATION_ENABLED)
+        @disconnect_timeout_ms = options.fetch(:disconnect_timeout_ms, DEFAULT_DISCONNECT_TIMEOUT_MS)
+        @handshake_idle_timeout_ms = options.fetch(:handshake_idle_timeout_ms, DEFAULT_HANDSHAKE_IDLE_TIMEOUT_MS)
+
+        # HTTP/3 parser limits — sensible defaults prevent OOM from malicious clients.
+        # RFC 9114 §4.2.2: SETTINGS_MAX_FIELD_SECTION_SIZE limits header block size.
+        # Override with nil to disable (not recommended in production).
+        @max_body_size = options.fetch(:max_body_size, DEFAULT_MAX_BODY_SIZE)
+        @max_header_size = options.fetch(:max_header_size, DEFAULT_MAX_HEADER_SIZE)
+        @max_header_count = options.fetch(:max_header_count, DEFAULT_MAX_HEADER_COUNT)
+        @max_frame_payload_size = options.fetch(:max_frame_payload_size, DEFAULT_MAX_FRAME_PAYLOAD_SIZE)
+
+        # 0-RTT early data policy (RFC 8470)
+        # :reject (default) — send 425 Too Early for unsafe methods on 0-RTT
+        # :allow — pass all 0-RTT requests to the Rack app with env["quicsilver.early_data"]
+        @early_data_policy = options.fetch(:early_data_policy, :reject)
+        unless %i[reject allow].include?(@early_data_policy)
+          raise ServerConfigurationError, "Invalid early_data_policy: #{@early_data_policy.inspect} (must be :reject or :allow)"
+        end
+
+        # MsQuic CIBIR (Connection ID Based Implicit Routing). Applications own
+        # the meaning of these bytes; Quicsilver validates and passes them to MsQuic.
+        # MsQuic currently supports CIBIR at offset 0 only, so offset is not configurable.
+        @cibir_id = normalize_cibir_id(options[:cibir_id])
+
+        # MsQuic fixed Server ID for QUIC-aware load balancers. This is
+        # process-global MsQuic state; Server applies it before opening MsQuic.
+        @transport_server_id = normalize_transport_server_id(options[:transport_server_id])
+
+        # Application interface mode:
+        # :rack (default) — app is a Rack app, auto-wrapped with Protocol::Rack::Adapter
+        # :falcon — app is a native protocol-http app, used directly
+        @mode = options.fetch(:mode, :rack)
+        unless %i[rack falcon].include?(@mode)
+          raise ServerConfigurationError, "Invalid mode: #{@mode.inspect} (must be :rack or :falcon)"
+        end
+
+        validate_certificate_paths!(cert_file, key_file)
+
+        @cert_file = cert_file
+        @key_file = key_file
+
+        unless File.exist?(@cert_file)
+          raise ServerConfigurationError, "Certificate file not found: #{@cert_file}"
+        end
+
+        unless File.exist?(@key_file)
+          raise ServerConfigurationError, "Key file not found: #{@key_file}"
+        end
+      end
+
+      # Common HTTP/3 ALPN Values:
+      # "h3" - HTTP/3 (most common)
+      # "h3-29" - HTTP/3 draft version 29
+      def alpn
+        @alpn
+      end
+
+      def cibir_bytes
+        [@cibir_id].pack("H*") if @cibir_id
+      end
+
+      def to_h
+        {
+          cert_file: @cert_file,
+          key_file: @key_file,
+          idle_timeout_ms: @idle_timeout_ms,
+          server_resumption_level: @server_resumption_level,
+          max_concurrent_requests: @max_concurrent_requests,
+          max_unidirectional_streams: @max_unidirectional_streams,
+          alpn: alpn,
+          stream_receive_window: @stream_receive_window,
+          stream_receive_buffer: @stream_receive_buffer,
+          connection_flow_control_window: @connection_flow_control_window,
+          pacing_enabled: @pacing_enabled ? 1 : 0,
+          send_buffering_enabled: @send_buffering_enabled ? 1 : 0,
+          initial_rtt_ms: @initial_rtt_ms,
+          initial_window_packets: @initial_window_packets,
+          max_ack_delay_ms: @max_ack_delay_ms,
+          keep_alive_interval_ms: @keep_alive_interval_ms,
+          congestion_control_algorithm: @congestion_control_algorithm,
+          migration_enabled: @migration_enabled ? 1 : 0,
+          disconnect_timeout_ms: @disconnect_timeout_ms,
+          handshake_idle_timeout_ms: @handshake_idle_timeout_ms
+        }
+      end
+
+      private
+        HEX = /\A[[:xdigit:]]+\z/
+        TRANSPORT_SERVER_ID = /\A[[:xdigit:]]{8}\z/
+
+        def normalize_cibir_id(value)
+          return if value.nil?
+
+          cibir_id = value.to_s
+          if cibir_id.empty? || cibir_id.bytesize.odd? || cibir_id.bytesize > 12 || !cibir_id.match?(HEX)
+            raise ServerConfigurationError, "cibir_id must be 1..6 bytes encoded as an even-length hex string"
+          end
+
+          cibir_id.downcase
+        end
+
+        def normalize_transport_server_id(value)
+          return if value.nil?
+
+          unless value.is_a?(String) && value.match?(TRANSPORT_SERVER_ID)
+            raise ServerConfigurationError, "transport_server_id must be exactly 4 bytes encoded as an 8-character hex string"
+          end
+
+          value.downcase
+        end
+
+        def validate_certificate_paths!(cert_file, key_file)
+          cert_file_missing = cert_file.to_s.empty?
+          key_file_missing = key_file.to_s.empty?
+
+          if cert_file_missing && key_file_missing
+            raise ServerConfigurationError, "cert_file and key_file are required"
+          elsif cert_file_missing
+            raise ServerConfigurationError, "cert_file is required when key_file is provided"
+          elsif key_file_missing
+            raise ServerConfigurationError, "key_file is required when cert_file is provided"
+          end
+        end
+    end
+  end
+end