config: add support for codec_type (#2156)

* config: add support for codec_type

* add comma

* fix warning block

* fix docs

docs/reference/readme.md

@@ -926,6 +926,40 @@ Do not append proxy IP address to `x-forwarded-for` HTTP header. See [Envoy](htt
 The number of trusted reverse proxies in front of pomerium. This affects `x-forwarded-proto` header and [`x-envoy-external-address` header](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-envoy-external-address), which reports tursted client address. [Envoy](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xff_num_trusted_hops#x-forwarded-for) docs for more detail.
 
 
+### Codec Type
+- Environment Variable: `CODEC_TYPE`
+- Config File Key: `codec_type`
+- Type: `string`
+- Default: `auto` (`http1` in all-in-one mode)
+
+Specifies the codec to use for downstream connections. Either `auto`, `http1` or `http2`.
+
+When `auto` is specified the codec will be determined via TLS ALPN or protocol inference.
+
+:::warning
+
+With HTTP/2, browsers typically coalesce connections for the same IP address that use the same
+TLS certificate. For example, you may have `authenticate.localhost.pomerium.io` and
+`example.localhost.pomerium.io` using the same wildcard certificate (`*.localhost.pomerium.io`)
+and both pointing to `127.0.0.1`. Your browser sees this and re-uses the initial connection
+it makes to `example` for `authenticate`. But unfortunately the routes necessary to handle
+`authenticate` don't exist on `example` so the proxy cannot handle the request.
+
+If this happens Pomerium will respond with a `421 Misdirected Request` status. Most browsers will attempt to
+make the request on a new HTTP/2 connection. However not all browsers implement this behavior
+(notably Safari), and users may end up seeing a blank page instead.
+
+If you see this happen, there are several ways to mitigate the problem:
+
+1. Don't re-use TLS certificates for shared IP domains.
+2. Don't re-use IP addresses for shared TLS certificates.
+3. Don't use HTTP/2.
+
+More details on this problem are available in [Github Issue #2150](https://github.com/pomerium/pomerium/issues/2150).
+
+:::
+
+
 ## Data Broker Service
 The databroker service is used for storing user session data.
 

docs/reference/settings.yaml

@@ -1046,6 +1046,40 @@ settings:
           The number of trusted reverse proxies in front of pomerium. This affects `x-forwarded-proto` header and [`x-envoy-external-address` header](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-envoy-external-address), which reports tursted client address. [Envoy](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xff_num_trusted_hops#x-forwarded-for) docs for more detail.
         shortdoc: |
           The number of trusted reverse proxies in front of pomerium.
+      - name: "Codec Type"
+        keys: ["codec_type"]
+        attributes: |
+          - Environment Variable: `CODEC_TYPE`
+          - Config File Key: `codec_type`
+          - Type: `string`
+          - Default: `auto` (`http1` in all-in-one mode)
+        doc: |
+          Specifies the codec to use for downstream connections. Either `auto`, `http1` or `http2`.
+
+          When `auto` is specified the codec will be determined via TLS ALPN or protocol inference.
+
+          :::warning
+
+          With HTTP/2, browsers typically coalesce connections for the same IP address that use the same
+          TLS certificate. For example, you may have `authenticate.localhost.pomerium.io` and
+          `example.localhost.pomerium.io` using the same wildcard certificate (`*.localhost.pomerium.io`)
+          and both pointing to `127.0.0.1`. Your browser sees this and re-uses the initial connection
+          it makes to `example` for `authenticate`. But unfortunately the routes necessary to handle
+          `authenticate` don't exist on `example` so the proxy cannot handle the request.
+
+          If this happens Pomerium will respond with a `421 Misdirected Request` status. Most browsers will attempt to
+          make the request on a new HTTP/2 connection. However not all browsers implement this behavior
+          (notably Safari), and users may end up seeing a blank page instead.
+
+          If you see this happen, there are several ways to mitigate the problem:
+
+          1. Don't re-use TLS certificates for shared IP domains.
+          2. Don't re-use IP addresses for shared TLS certificates.
+          3. Don't use HTTP/2.
+
+          More details on this problem are available in [Github Issue #2150](https://github.com/pomerium/pomerium/issues/2150).
+
+          :::
   - name: "Data Broker Service"
     doc: |
       The databroker service is used for storing user session data.