HTTP2 server_settings frame is ignored

[David-Klemenc]

Creating a HTTP connection always return the same (server) settings (ignoring the frame sent from the server):

Mint.HTTP2.connect(:http, "localhost", 5001)

{:ok,
 %Mint.HTTP2{
   transport: Mint.Core.Transport.TCP,
   socket: #Port<0.30>,
   mode: :active,
   hostname: "localhost",
   port: 5001,
   scheme: "http",
   authority: "localhost:5001",
   state: :handshaking,
   buffer: "",
   window_size: 65535,
   encode_table: %HPAX.Table{
     protocol_max_table_size: 4096,
     max_table_size: 4096,
     huffman_encoding: :never,
     entries: [],
     size: 0,
     length: 0,
     pending_minimum_resize: nil
   },
   decode_table: %HPAX.Table{
     protocol_max_table_size: 4096,
     max_table_size: 4096,
     huffman_encoding: :never,
     entries: [],
     size: 0,
     length: 0,
     pending_minimum_resize: nil
   },
   ping_queue: {[], []},
   client_settings_queue: {[[]], []},
   next_stream_id: 3,
   streams: %{},
   open_client_stream_count: 0,
   open_server_stream_count: 0,
   ref_to_stream_id: %{},
   server_settings: %{
     max_concurrent_streams: 100,
     max_frame_size: 16384,
     max_header_list_size: :infinity,
     initial_window_size: 65535,
     enable_push: true,
     enable_connect_protocol: false
   },
   client_settings: %{
     max_concurrent_streams: 100,
     max_frame_size: 16384,
     max_header_list_size: :infinity,
     initial_window_size: 65535,
     enable_push: true
   },
   headers_being_processed: nil,
   proxy_headers: [],
   private: %{},
   log: false
 }}

testing the same connection with nghttp returns:

nghttp -nv http://localhost:5001 
[  0.042] Connected
[  0.043] send SETTINGS frame <length=18, flags=0x00, stream_id=0>
          (niv=3)
          [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
          [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
          [SETTINGS_NO_RFC7540_PRIORITIES(0x09):1]
[  0.043] send HEADERS frame <length=49, flags=0x05, stream_id=1>
          ; END_STREAM | END_HEADERS
          (padlen=0)
          ; Open new stream
          :method: GET
          :path: /
          :scheme: http
          :authority: localhost:5001
          priority: u=3
          accept: */*
          accept-encoding: gzip, deflate
          user-agent: nghttp2/1.67.1
[  0.093] recv SETTINGS frame <length=6, flags=0x00, stream_id=0>
          (niv=1)
          [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):255]
[  0.093] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
          ; ACK
          (niv=0)
[  0.093] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
          ; ACK
          (niv=0)
[  0.124] recv (stream_id=1) :status: 200
[  0.124] recv (stream_id=1) date: Tue, 18 Nov 2025 09:24:23 GMT
[  0.124] recv (stream_id=1) content-length: 1965
[  0.124] recv (stream_id=1) cache-control: max-age=0, private, must-revalidate
[  0.124] recv (stream_id=1) x-request-id: GHkPlXvgXDwp6WIAAAaF
[  0.124] recv HEADERS frame <length=113, flags=0x04, stream_id=1>
          ; END_HEADERS
          (padlen=0)
          ; First response header
[  0.124] recv DATA frame <length=1965, flags=0x01, stream_id=1>
          ; END_STREAM
[  0.125] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
          (last_stream_id=0, error_code=NO_ERROR(0x00), opaque_data(0)=[])

Finch does not show the correct max_concurrent_streams for the server which are:
SETTINGS_MAX_CONCURRENT_STREAMS(0x03):255

I setup the server with bandit - here is the config that sets max_concurrent_streams option:

{
  Bandit,
  http_2_options: [default_local_settings: [max_concurrent_streams: 255]],
  scheme: :http,
  plug: BanditRouter,
  port: 5001,
}

[whatyouhide]

@David-Klemenc I might not remember this 100% correctly, but I’m fairly confident that the server sends the SETTINGS frame after connecting. So, per spec, you start the client with the default settings for the server and then update them whenever a SETTINGS frame comes in. If you consume TCP/TLS data coming from the server after connecting you should receive that SETTINGS frame and you'll get an updated connection. Mint is really low level so you should be prepared to consume these SETTINGS frames at any time anyway, since they could change over the course of a connection's lifetime.

Does that make sense? Can you verify that that's what's happening?

[David-Klemenc]

I looked at the code and I think this function is never called:

  # SETTINGS

  defp handle_settings(conn, frame, responses) do
    settings(flags: flags, params: params) = frame

    if flag_set?(flags, :settings, :ack) do
      conn = apply_client_settings(conn)
      {conn, responses}
    else
      conn = apply_server_settings(conn, params)
      frame = settings(flags: set_flags(:settings, [:ack]), params: [])
      conn = send!(conn, Frame.encode(frame))
      {conn, responses}
    end
  end

[the-mikedavis]

There's a macro that delegates handle_frame/3 to that function:

mint/lib/mint/http2.ex

Lines 1532 to 1538 in e28c85a

	for frame_name <- stream_level_frames ++ connection_level_frames ++ [:window_update, :unknown] do
	function_name = :"handle_#{frame_name}"
	defp handle_frame(conn, Frame.unquote(frame_name)() = frame, responses) do
	unquote(function_name)(conn, frame, responses)
	end
	end

[the-mikedavis]

#311 might be related - since #387 the initial SETTINGS frame from the server is handled as it comes in: connect/3 doesn't block waiting for it.

[whatyouhide]

Yep, so as I suspected this is by design. The spec is clear that SETTINGS must be the first frame sent by the server, but blocking connect waiting for that is potentially problematic for performance reasons.

My advice here: Mint is low level, so wrap its connect function into a function that establishes the connection and waits for the first SETTINGS frame. If the current Mint API doesn't really let you know when a SETTINGS frame comes in, we could extend the Mint API to also keep track of how many SETTINGS frames were received (and subsequently acked) by the conn and keep that count in the conn itself.

I'll close this issue now as that would be a separate piece of work anyway in case we want to do it, cc @ericmj @wojtekmach.

[ericmj]

@whatyouhide What do you think about adding an optional_response that is triggered by the settings frame so that if implementors want to block connection set up for the settings frame it would be easier?

[whatyouhide]

@ericmj yeah considering we now have that for the status reason phrase thing from a recent PR, that would be nice. However we don't have a precedent of connection-wide "responses"—all responses today have a request reference in them. So, not sure we want to "break" that API.