<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="http2.html">

  &project;

  <properties>
    <title>The HTTP2 Upgrade Protocol</title>
  </properties>

<body>

<section name="Table of Contents">
<toc/>
</section>

<section name="Introduction">

  <p>The <strong>HTTP Upgrade Protocol</strong> element represents an
  <strong>Upgrade Protocol</strong> component that supports the HTTP/2 protocol.
  An instance of this component must be associated with an existing
  <a href="http.html">HTTP/1.1 Connector</a>.</p>

  <p>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.</p>

</section>


<section name="Attributes">

  <subsection name="Common Attributes">

  <p>All implementations of <strong>Upgrade Protocol</strong> support the
  following attributes:</p>

  <attributes>

    <attribute name="className" required="true">
      <p>This must be <code>org.apache.coyote.http2.Http2Protocol</code>.</p>
    </attribute>

  </attributes>

  </subsection>

  <subsection name="Standard Implementation">

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

  <attributes>

    <attribute name="allowedTrailerHeaders" required="false">
      <p>By default Tomcat will ignore all trailer headers when processing
      HTTP/2 connections. For a header to be processed, it must be added to this
      comma-separated list of header names.</p>
    </attribute>

    <attribute name="initialWindowSize" required="false">
      <p>Controls the initial size of the flow control window for streams that
      Tomcat advertises to clients. If not specified, the default value of
      <code>65535</code> is used.</p>
    </attribute>

    <attribute name="keepAliveTimeout" required="false">
      <p>The time, in milliseconds, that Tomcat will wait between HTTP/2 frames
      before closing the connection. Negative values will be treated as an
      infinite timeout. If not specified, a default value of <code>-1</code>
      will be used.</p>
    </attribute>

    <attribute name="maxConcurrentStreamExecution" required="false">
      <p>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
      <code>200</code> will be used.</p>
    </attribute>

    <attribute name="maxConcurrentStreams" required="false">
      <p>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 <code>STREAM_REFUSED</code> error.
      If not specified, the default value of <code>200</code> will be used.</p>
    </attribute>

    <attribute name="maxHeaderCount" required="false">
      <p>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.</p>
    </attribute>

    <attribute name="maxHeaderSize" required="false">
      <p>The maximum total size for all headers in a request that is allowed by
      the container. Total size for a header is calculated as the uncompressed
      size of the header name in bytes, plus the uncompressed size of the header
      value in bytes plus an HTTP/2 overhead of 3 bytes per header. A request
      that contains a set of headers that requires more than the specified limit
      will be rejected. A value of less than 0 means no limit. If not specified,
      a default of 8192 is used.</p>
    </attribute>

    <attribute name="maxTrailerCount" required="false">
      <p>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.</p>
    </attribute>

    <attribute name="maxTrailerSize" required="false">
      <p>The maximum total size for all trailer headers in a request that is
      allowed by the container. Total size for a header is calculated as the
      uncompressed size of the header name in bytes, plus the uncompressed size
      of the header value in bytes plus an HTTP/2 overhead of 3 bytes per
      header. A request that contains a set of trailer headers that requires
      more than the specified limit will be rejected. A value of less than 0
      means no limit. If not specified, a default of 8192 is used.</p>
    </attribute>

    <attribute name="readTimeout" required="false">
      <p>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
      <code>10000</code> will be used.</p>
    </attribute>

    <attribute name="writeTimeout" required="false">
      <p>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
      <code>10000</code> will be used.</p>
    </attribute>

  </attributes>

  <p>The HTTP/2 upgrade protocol will also inherit the following limits from the
  <a href="http.html">HTTP Connector</a> it is nested with:</p>

  <ul>
    <li>maxCookieCount</li>
    <li>maxParameterCount</li>
    <li>maxPostSize</li>
    <li>maxSavePostSize</li>
  </ul>

  </subsection>

</section>

<section name="Nested Components">

  <p>This component does not support any nested components.</p>

</section>


<section name="Special Features">

  <p>This component does not support any special features.</p>

</section>

</body>

</document>
