Skip to content

HTTP/2

With HTTP/2, one connection can send many requests at the same time, and Dox serves HTTP/2 on the same port as HTTP/1.1.

Use HTTP/2 for one of these reasons:

  • You want to serve gRPC. gRPC works only over HTTP/2.
  • Your proxy sends HTTP/2 to the app. The proxy then sends many requests on a small number of connections. The app can serve more requests with fewer connections.

HTTP/2 is off by default. If you do not turn on HTTP/2, nothing changes.

Turn on HTTP/2

Set http2 to true in the app config:

lib/config/app.dart
AppConfig appConfig = AppConfig(
  http2: true,
  // ...
);

The port then accepts HTTP/1.1 and HTTP/2. Old clients and health checks continue to work, because Dox finds the protocol of each connection.

You do not change your routes, middleware, or controllers.

Read the protocol of a request

To find the protocol of a request, read req.protocolVersion. The value is 2.0 for an HTTP/2 request. For an HTTP/1.x request, the value is 1.0 or 1.1:

Route.get('/protocol', (DoxRequest req) {
  return req.protocolVersion; // '2.0'
});

You can do a test with curl:

curl --http2-prior-knowledge http://localhost:3000/protocol

Limit the open requests on one connection

One HTTP/2 connection can have many open requests. maxConcurrentStreams sets the maximum number of open requests on one connection. The default is 250. This value is correct for most apps.

To let each client keep fewer open requests, set a lower number:

lib/config/app.dart
AppConfig appConfig = AppConfig(
  http2: true,
  maxConcurrentStreams: 100,
  // ...
);

Use a proxy

Dox uses h2c. h2c is HTTP/2 over plain TCP, without TLS. Your proxy must do the TLS.

Browsers use HTTP/2 only with TLS. The browser sends HTTP/2 with TLS to the proxy, and the proxy sends the requests to Dox:

browser  --HTTP/2 + TLS-->  proxy  --h2c or HTTP/1.1-->  Dox

For the Caddy and nginx config, see Deployment: HTTP/2 and gRPC.

Use the server without Dox

If you use the native server without Dox, give the same two options to NativeHttpServer.bind:

NativeHttpServer server = await NativeHttpServer.bind(
  3000,
  http2: true,
  maxConcurrentStreams: 100,
);

Protection

HTTP/2 has some known attacks. Dox has protection against these attacks by default. You do not set anything.

  • Rapid Reset. A client can open requests and cancel them very quickly. This adds work to your app. In Dox, a cancelled request stays in the maxConcurrentStreams count until your handler stops. For this reason, the attack does not work. Dox does not close the connection of a normal client that has some timeouts.
  • Floods. If a client sends too many resets, SETTINGS frames, PING frames, or empty frames, Dox sends GOAWAY ENHANCE_YOUR_CALM. Then Dox closes the connection.
  • Large or slow bodies. A request body on HTTP/2 has the same limits as on HTTP/1.1: maxBodySize, maxMultipartSize, and bodyTimeout. See Size limits.
  • Idle and slow clients. A connection with no open request closes after idleTimeout. If a client does not read a response for 30 seconds, Dox stops that response.

On the internet, keep a proxy in front of Dox. See the deployment guide.

Benchmark

HTTP/2 is faster when a client sends many requests on one connection. On one isolate, HTTP/2 does approximately 1.6 times the requests of HTTP/1.1.

One isolate: HTTP/2 is 1.6× faster

GET / answers Hello, World!. The server has 4 cores and runs one isolate.

req/s
HTTP/216 conn × 16 requests 587,000fastest
HTTP/24 conn × 64 requests 465,0001.3× slower
HTTP/1.1256 conn, http2 on 373,0001.6× slower
HTTP/1.1256 conn, http2 off 364,0001.6× slower

Dox · one isolate · Linux · oha · median of 3 runs

The two HTTP/1.1 rows are almost the same. Thus, http2: true does not make your HTTP/1.1 clients slower.

Load Requests a second
HTTP/1.1, 256 connections, http2 off 364,000
HTTP/1.1, 256 connections, http2 on 373,000
HTTP/2, 16 connections × 16 requests each 587,000
HTTP/2, 4 connections × 64 requests each 465,000

With 4 isolates, HTTP/1.1 and HTTP/2 both do approximately 630,000 requests a second. This number is the limit of the load tool on 4 cores, not the limit of Dox. HTTP/2 gives the largest increase when the app has few isolates.

Test setup

  • The app has one route, GET /. This route sends Hello, World!.
  • The app is an AOT build. The build command is dart build cli.
  • All tests ran in Linux containers on one machine with 8 cores. The server used 4 cores. The load tool, oha, used the other 4 cores.
  • Each number is the median of 3 runs. Each run took 10 seconds, after a warm up of 3 seconds.

Details

  • Dox passes all 146 tests of the h2spec conformance suite in strict mode.
  • maxConcurrentStreams must be 1 or more. Dox uses it only when http2 is true.