The HTTP2 Upgrade Protocol

Table of Contents

Introduction

The HTTP Upgrade Protocol element represents an Upgrade Protocol component that supports the HTTP/2 protocol. An instance of this component must be associated with an existing HTTP/1.1 Connector.

HTTP/2 connectors use non-blocking I/O, only utilising a container thread from the thread pool when there is data to read and write. However, because the Servlet API is fundamentally blocking, each HTTP/2 stream requires a dedicated container thread for the duration of that stream.

Requests processed using HTTP/2 will have the following additional request attributes available:

  • org.apache.coyote.connectionID will return the HTTP/2 connection ID
  • org.apache.coyote.streamID will return the HTTP/2 stream ID

Attributes

Common Attributes

All implementations of Upgrade Protocol support the following attributes:

Attribute Description
className

This must be org.apache.coyote.http2.Http2Protocol.

Standard Implementation

The HTTP/2 Upgrade Protocol implementation supports the following attributes in addition to the common attributes listed above.

Attribute Description
initialWindowSize

Controls the initial size of the flow control window for streams that Tomcat advertises to clients. If not specified, the default value of 65535 is used.

keepAliveTimeout

The time, in milliseconds, that Tomcat will wait between HTTP/2 frames when there is no active Stream before closing the connection. Negative values will be treated as an infinite timeout. If not specified, a default value of 20000 will be used.

maxConcurrentStreamExecution

The controls the maximum number of streams for any one connection that can be allocated threads from the container thread pool. If more streams are active than threads are available, those streams will have to wait for a stream to become available. If not specified, the default value of 20 will be used.

maxConcurrentStreams

The controls the maximum number of active streams permitted for any one connection. If a client attempts to open more active streams than this limit, the stream will be reset with a STREAM_REFUSED error. If not specified, the default value of 100 will be used.

maxHeaderCount

The maximum number of headers in a request that is allowed by the container. A request that contains more headers than the specified limit will be rejected. A value of less than 0 means no limit. If not specified, a default of 100 is used.

maxTrailerCount

The maximum number of trailer headers in a request that is allowed by the container. A request that contains more trailer headers than the specified limit will be rejected. A value of less than 0 means no limit. If not specified, a default of 100 is used.

overheadContinuationThreshold

The threshold below which the payload size of a non-final CONTINUATION frame will trigger an increase in the overhead count (see overheadCountFactor). The overhead count will be increased by overheadContinuationThreshold/payloadSize so that the smaller the CONTINUATION frame, the greater the increase in the overhead count. A value of zero or less disables the checking of non-final CONTINUATION frames. If not specified, a default value of 1024 will be used.

overheadCountFactor

The factor to apply when counting overhead frames to determine if a connection has too high an overhead and should be closed. The overhead count starts at -10 * overheadCountFactor. The count is decreased by 20 for each data frame sent or received and each headers frame received. The count is increased by the overheadCountFactor for each setting, priority, priority update and ping frame received. If the overhead count exceeds zero, the connection is closed. A value of less than 1 disables this protection. In normal usage a value of approximately 20 or higher will close the connection before any streams can complete. If not specified, a default value of 10 will be used.

overheadResetFactor

The amount by which the overhead count (see overheadCountFactor) will be increased for each reset frame received. If not specified, a default value of 50 will be used. A value of less than zero will be treated as zero.

overheadDataThreshold

The threshold below which the average payload size of the current and previous non-final DATA frames will trigger an increase in the overhead count (see overheadCountFactor). The overhead count will be increased by overheadDataThreshold/average so that the smaller the average, the greater the increase in the overhead count. A value of zero or less disables the checking of non-final DATA frames. If not specified, a default value of 1024 will be used.

overheadWindowUpdateThreshold

The threshold below which the average size of current and previous WINDOW_UPDATE frame will trigger an increase in the overhead count (see overheadCountFactor). The overhead count will be increased by overheadWindowUpdateThreshold/average so that the smaller the average, the greater the increase in the overhead count. A value of zero or less disables the checking of WINDOW_UPDATE frames. If not specified, a default value of 1024 will be used.

readTimeout

The time, in milliseconds, that Tomcat will wait for additional data when a partial HTTP/2 frame has been received. Negative values will be treated as an infinite timeout. If not specified, a default value of 5000 will be used.

streamReadTimeout

The time, in milliseconds, that Tomcat will wait for additional data frames to arrive for the stream when an application is performing a blocking I/O read and additional data is required. Negative values will be treated as an infinite timeout. If not specified, a default value of 20000 will be used.

streamWriteTimeout

The time, in milliseconds, that Tomcat will wait for additional window update frames to arrive for the stream and/or connection when an application is performing a blocking I/O write and the stream and/or connection flow control window is too small for the write to complete. Negative values will be treated as an infinite timeout. If not specified, a default value of 20000 will be used.

useSendfile

Use this boolean attribute to enable or disable sendfile capability. The default value is true.

This setting is ignored, and the sendfile capability disabled, if the useAsyncIO attribute of the associated Connector is set to false.

The HTTP/2 sendfile capability uses MappedByteBuffer which is known to cause file locking on Windows.

writeTimeout

The time, in milliseconds, that Tomcat will wait to write additional data when an HTTP/2 frame has been partially written. Negative values will be treated as an infinite timeout. If not specified, a default value of 5000 will be used.

The HTTP/2 upgrade protocol will also inherit the following limits from the HTTP Connector it is nested with:

  • allowedTrailerHeaders
  • compressibleMimeType
  • compression
  • compressionMinSize
  • maxCookieCount
  • maxHttpHeaderSize
  • maxHttpRequestHeaderSize
  • maxParameterCount
  • maxPostSize
  • maxSavePostSize
  • maxTrailerSize
  • noCompressionUserAgents

Nested Components

This component does not support any nested components.

Special Features

This component does not support any special features.