# Codec Type

## Summary

**Codec Type** specifies the codec to use for downstream connections.

## How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :------------------- | :------------------------ | :------- | :---------- |
| `codec_type`         | `CODEC_TYPE`              | `string` | `auto`      |

### Examples

```yaml
codec_type: http1
```

```bash
CODEC_TYPE=http2
```

**Enterprise:**

`codec_type` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

| **[Parameter name](https://www.pomerium.com/docs/deploy/k8s/reference.md#spec)** | **Type** | **Usage** | **Default** |
| :-- | :-- | :-- | :-- |
| `codecType` | `string` | **optional** | `auto` |

### Examples

```yaml
codecType: http2
```

See [Kubernetes - Global Configuration](https://www.pomerium.com/docs/deploy/k8s/configure.md) for more information.

### Options

| **Options** | **Description** |
| :-- | :-- |
| `auto` | Either `http1` or `http2` will be determined via TLS ALPN or protocol inference |
| `http1` | Only support `http1` |
| `http2` | Only support `http2` |
| `http3` | Starts both a UDP and TCP listener on [address](https://www.pomerium.com/docs/reference/address.md). The UDP listener is configured to use QUIC with HTTP/3. The TCP listener is configured to use `auto` as the codec type, and an `Alt-Svc` header is added to all responses indicating `h3` is available (Available since v0.29) |

## Protocol Details

### HTTP/1.1 (`http1`)

HTTP/1.1 is the traditional protocol for web communication, operating over TCP. It supports basic request-response interactions but lacks advanced features like multiplexing, which can lead to inefficiencies such as head-of-line blocking.

### HTTP/2 (`http2`)

HTTP/2 enhances performance over HTTP/1.1 by introducing:

- **Multiplexing**: Allows multiple requests and responses concurrently over a single connection.
- **Header Compression**: Reduces overhead by compressing HTTP headers.
- **Server Push**: Enables servers to send resources proactively to clients.

These features improve page load times and resource utilization, especially for applications with multiple simultaneous requests.

### HTTP/3 (`http3`)

HTTP/3 is the latest version of the HTTP protocol, utilizing QUIC over UDP. Benefits include:

- **Reduced Latency**: Faster connection establishment with 0-RTT (zero round-trip time) support.
- **Improved Performance**: Better handling of packet loss and network congestion.
- **Connection Migration**: Maintains connections even when network changes occur (e.g., switching from Wi-Fi to cellular).

**Considerations**:

- **Network Compatibility**: Ensure that firewalls, routers, and network devices allow UDP traffic on the necessary ports. Some networks may block UDP traffic, which can prevent HTTP/3 connections from being established.
- **Fallback Mechanism**: When HTTP/3 is enabled, Pomerium also provides a TCP listener that supports `http1` and `http2` protocols. This allows clients that cannot use HTTP/3 (due to network restrictions or lack of support) to fall back to earlier protocol versions.
- **Client Support**: Only clients that support HTTP/3 and QUIC can leverage these benefits. Older clients will continue to use HTTP/1.1 or HTTP/2.

Because HTTP/3 relies on QUIC over UDP, it may be blocked by some network environments that restrict UDP traffic. Ensure that your deployment environment permits UDP on the necessary ports, and be prepared for clients in restrictive networks to fall back to HTTP/1.1 or HTTP/2.

When `codec_type` is set to `http3`, Pomerium operates as follows:

- **UDP Listener**: Listens for QUIC connections to serve HTTP/3 traffic.
- **TCP Listener**: Continues to support `http1` and `http2` based on the `auto` codec type.
- **Alt-Svc Header**: Adds an `Alt-Svc` header to HTTP responses, informing clients that HTTP/3 is available.

This configuration allows clients that support HTTP/3 to upgrade their connections while maintaining compatibility with clients using earlier protocol versions.