Raise default HTTP/2 receive windows

Default connection receive window is now 16 MB (was 65_535), sent via
a WINDOW_UPDATE on stream 0 as part of the connection preface. Default
stream receive window is now 4 MB (was 65_535), advertised via
SETTINGS_INITIAL_WINDOW_SIZE in the same preface. Both settable via
the new `:connection_window_size` option and the existing
`:client_settings` option.

Window size / RTT sets a hard cap on per-stream throughput. At the
previous 65_535-byte stream window:

  Path (typical RTT)       | 65 KB    | 4 MB     | 16 MB
  -------------------------|----------|----------|----------
  LAN (1 ms)               | 62 MB/s  | 4 GB/s   | 16 GB/s
  Region (20 ms)           | 3.1 MB/s | 200 MB/s | 800 MB/s
  Cross-country (70 ms)    | 0.9 MB/s | 57 MB/s  | 229 MB/s
  Transatlantic (100 ms)   | 0.6 MB/s | 40 MB/s  | 160 MB/s
  Transpacific (130 ms)    | 0.5 MB/s | 31 MB/s  | 123 MB/s
  Antipodal (230 ms)       | 0.3 MB/s | 17 MB/s  | 70 MB/s

Any caller talking to a server more than a few milliseconds away was
bottlenecked well below their link bandwidth without knowing why. 4 MB
per stream saturates gigabit anywhere on earth; 16 MB at the connection
level lets four streams run in parallel at full rate before the shared
pool binds.

Callers who want the old behaviour can pass `connection_window_size:
65_535` and `client_settings: [initial_window_size: 65_535]` to
`connect/4`.

Author: ericmj

lib/mint/http.ex

@@ -238,6 +238,11 @@ defmodule Mint.HTTP do
       server. See `Mint.HTTP2.put_settings/2` for more information. This is only used
       in HTTP/2 connections.
 
+    * `:connection_window_size` - (integer) the initial size of the connection-level
+      HTTP/2 receive window, in bytes. Sent to the server as a `WINDOW_UPDATE` frame
+      on stream 0 as part of the connection preface. Defaults to 16 MB. Can be
+      raised later with `Mint.HTTP2.set_window_size/3`.
+
   There may be further protocol specific options that only take effect when the corresponding
   connection is established. Check `Mint.HTTP1.connect/4` and `Mint.HTTP2.connect/4` for
   details.

lib/mint/http2.ex

@@ -143,6 +143,8 @@ defmodule Mint.HTTP2 do
   @transport_opts [alpn_advertised_protocols: ["h2"]]
 
   @default_window_size 65_535
+  @default_connection_window_size 16 * 1024 * 1024
+  @default_stream_window_size 4 * 1024 * 1024
   @max_window_size 2_147_483_647
 
   @default_max_frame_size 16_384
@@ -182,9 +184,10 @@ defmodule Mint.HTTP2 do
     send_window_size: @default_window_size,
     # `receive_window_size` is the client *receive* window for the
     # connection — the peak size we've advertised to the server via
-    # `WINDOW_UPDATE` frames on stream 0 (or the spec default of 65_535
-    # if we've never sent one). Mint auto-refills to maintain this peak
-    # as DATA frames arrive.
+    # `WINDOW_UPDATE` frames on stream 0. Initialized to the configured
+    # connection window during `initiate/5`, which also sends the
+    # matching WINDOW_UPDATE to bring the server's view from the spec
+    # default of 65_535 up to the advertised peak.
     receive_window_size: @default_window_size,
     encode_table: HPAX.new(4096),
     decode_table: HPAX.new(4096),
@@ -216,7 +219,7 @@ defmodule Mint.HTTP2 do
     # Settings that the client communicates to the server.
     client_settings: %{
       max_concurrent_streams: 100,
-      initial_window_size: @default_window_size,
+      initial_window_size: @default_stream_window_size,
       max_header_list_size: :infinity,
       max_frame_size: @default_max_frame_size,
       enable_push: true
@@ -1101,7 +1104,17 @@ defmodule Mint.HTTP2 do
     scheme_string = Atom.to_string(scheme)
     mode = Keyword.get(opts, :mode, :active)
     log? = Keyword.get(opts, :log, false)
+
+    connection_window_size =
+      Keyword.get(opts, :connection_window_size, @default_connection_window_size)
+
+    validate_window_size!(:connection_window_size, connection_window_size)
+
     client_settings_params = Keyword.get(opts, :client_settings, [])
+
+    client_settings_params =
+      Keyword.put_new(client_settings_params, :initial_window_size, @default_stream_window_size)
+
     validate_client_settings!(client_settings_params)
     # If the port is the default for the scheme, don't add it to the :authority pseudo-header
     authority =
@@ -1130,12 +1143,13 @@ defmodule Mint.HTTP2 do
       mode: mode,
       scheme: scheme_string,
       state: :handshaking,
-      log: log?
+      log: log?,
+      receive_window_size: connection_window_size
     }
 
+    preface = build_preface(client_settings_params, connection_window_size)
+
     with :ok <- Util.inet_opts(transport, socket),
-         client_settings = settings(stream_id: 0, params: client_settings_params),
-         preface = [@connection_preface, Frame.encode(client_settings)],
          :ok <- transport.send(socket, preface),
          conn = update_in(conn.client_settings_queue, &:queue.in(client_settings_params, &1)),
          conn = put_in(conn.socket, socket),
@@ -1148,6 +1162,26 @@ defmodule Mint.HTTP2 do
     end
   end
 
+  defp build_preface(client_settings_params, connection_window_size) do
+    settings_frame = Frame.encode(settings(stream_id: 0, params: client_settings_params))
+
+    if connection_window_size > @default_window_size do
+      increment = connection_window_size - @default_window_size
+      update_frame = Frame.encode(window_update(stream_id: 0, window_size_increment: increment))
+      [@connection_preface, settings_frame, update_frame]
+    else
+      [@connection_preface, settings_frame]
+    end
+  end
+
+  defp validate_window_size!(name, value) do
+    unless is_integer(value) and value >= @default_window_size and value <= @max_window_size do
+      raise ArgumentError,
+            "the :#{name} option must be an integer in " <>
+              "#{@default_window_size}..#{@max_window_size}, got: #{inspect(value)}"
+    end
+  end
+
   @doc """
   See `Mint.HTTP.get_socket/1`.
   """

test/mint/http2/conn_test.exs

@@ -135,6 +135,8 @@ defmodule Mint.HTTP2Test do
   end
 
   describe "set_window_size/3" do
+    @describetag connect_options: [connection_window_size: 65_535]
+
     test "bumps the connection-level receive window by sending WINDOW_UPDATE on stream 0",
          %{conn: conn} do
       assert HTTP2.get_window_size(conn, :connection) == 65_535
@@ -1865,6 +1867,51 @@ defmodule Mint.HTTP2Test do
     end
   end
 
+  describe "default receive windows" do
+    test "advertises the configured connection window with a WINDOW_UPDATE in the preface",
+         %{conn: conn} do
+      # The default :connection_window_size is 16 MB; the preface carries
+      # a WINDOW_UPDATE for `16 MB - 65_535` so the server sees the peak
+      # from the start.
+      assert conn.receive_window_size == 16 * 1024 * 1024
+    end
+
+    test "advertises the configured stream window via SETTINGS", %{conn: conn} do
+      # The default :client_settings[:initial_window_size] is 4 MB.
+      assert conn.client_settings.initial_window_size == 4 * 1024 * 1024
+
+      {conn, _ref} = open_request(conn)
+      assert_recv_frames [headers(stream_id: stream_id)]
+
+      assert conn.streams[stream_id].receive_window_size == 4 * 1024 * 1024
+    end
+
+    @tag connect_options: [connection_window_size: 1_000_000]
+    test "supports a custom :connection_window_size", %{conn: conn} do
+      assert conn.receive_window_size == 1_000_000
+    end
+
+    @tag connect_options: [connection_window_size: 65_535]
+    test "omits the preface WINDOW_UPDATE when the configured window equals the spec default",
+         %{conn: conn} do
+      # At 65_535 there's nothing to advertise beyond SETTINGS — the
+      # preface should not carry an extra WINDOW_UPDATE.
+      assert conn.receive_window_size == 65_535
+    end
+
+    test "rejects a :connection_window_size below the spec minimum" do
+      assert_raise ArgumentError, ~r/:connection_window_size/, fn ->
+        HTTP2.initiate(:https, self(), "localhost", 443, connection_window_size: 1024)
+      end
+    end
+
+    test "rejects a :connection_window_size above 2^31-1" do
+      assert_raise ArgumentError, ~r/:connection_window_size/, fn ->
+        HTTP2.initiate(:https, self(), "localhost", 443, connection_window_size: 2_147_483_648)
+      end
+    end
+  end
+
   describe "settings" do
     test "put_settings/2 can be used to send settings to server", %{conn: conn} do
       {:ok, conn} =

test/support/mint/http2/test_server.ex

@@ -1,6 +1,6 @@
 defmodule Mint.HTTP2.TestServer do
   import ExUnit.Assertions
-  import Mint.HTTP2.Frame, only: [settings: 1, goaway: 1, ping: 1]
+  import Mint.HTTP2.Frame, only: [settings: 1, goaway: 1, ping: 1, window_update: 1]
 
   alias Mint.HTTP2.Frame
 
@@ -144,10 +144,18 @@ defmodule Mint.HTTP2.TestServer do
     # First we get the connection preface.
     {:ok, unquote(connection_preface) <> rest} = :ssl.recv(socket, 0, 100)
 
-    # Then we get a SETTINGS frame.
-    assert {:ok, frame, ""} = Frame.decode_next(rest)
+    # Then we get a SETTINGS frame, optionally followed by a WINDOW_UPDATE
+    # on stream 0 if the client raised its connection-level receive window.
+    assert {:ok, frame, rest} = Frame.decode_next(rest)
     assert settings(flags: ^no_flags, params: _params) = frame
 
-    :ok
+    case rest do
+      "" ->
+        :ok
+
+      _ ->
+        assert {:ok, window_update(stream_id: 0), ""} = Frame.decode_next(rest)
+        :ok
+    end
   end
 end