# GEP-XXXX: Support HTTP3 over QUIC
Issue: #XXXX
Status: TBD (Provisional|Implementable)

## TLDR

This GEP proposes adding support for HTTP3 over QUIC.

## Goals

- Support HTTP3 over QUIC for downstream clients

## Non-Goals

- Support other QUIC-based protocols (e.g. mqtt-over-quic, etc)
- Support HTTP3-based TLS Passthrough
- Support HTTP3 for upstream backends
- Provide a workaround if [`MixedProtocolLBService`](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) is not supported yet. It's already graduated to beta in k8s v1.24 and enabled by default. The adoption is slow, but there are open issues for major cloud providers to support it.

## Introduction

(Can link to external doc -- but we should bias towards copying
the content into the GEP as online documents are easier to lose
-- e.g. owner messes up the permissions, accidental deletion)

On 6 June 2022, IETF published HTTP/3 as a Proposed Standard in RFC 9114.

// TODO practical usecases

### Enabling http3 in current Ingress controllers and Loadbalancers

#### Emissary-ingress/Ambassador (v3.1.0)

Emissary-ingress/Ambassador is based on Envoyproxy and HTTP3-over-QUIC is already supported in this ingress controller. It can be enabled by creating a new `Listener` object:

// TODO sample config

#### Traefik (v2.8)

Like Emissary, it's already supported in Traefik ingress controller and it can be enabled by configuring the Traefik itself by providing the required parameters using cli flags or config file:

// TODO sample config

#### Nginx (cloudflare/quiche and nginx-quic branch)

It's not officialy released, but it can be configured using `cloudflare/quiche`'s nginx module or the experimental module in `nginx-quic` branch of Nginx. In both of them, it can be enabled by using `http3` or `quic` option in the `listen` directive.

// TODO sample configuration

#### HAProxy (v2.6)

It's officially announced in HAProxy 2.6 and it can be by defining a new `bind` directive in a `frontend` block.

// TODO sample config

#### Envoyproxy (v1.24)

Envoyproxy supports both downstream and upstream modes and it can be enabled by defining a new `listener` with the required `codec` and `transport`.

// TODO example config

## API

It introduces a new field called `spec.listeners[].http3.*` in `Gateway` object:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: mixed-http3-and-https
spec:
  gatewayClassName: http3-enabled-gateway
  listeners:
  - name: foo-https
    protocol: HTTPS
    port: 443
    hostname: foo.example.com
    http3:
      enabled: true
      alternativeAuthorityHeader: ":443"
      options:
          key1: value1
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert
      options:
        minTlsVersion: 1.3

#### HTTP3 object/field

| Field | Type | Default | Description |
| -------- | -------- | -------- | ------- |
| `http3.enabled` | boolean | false | indicates http3 is enabled on this listener |
| `http3.alternativeAuthorityHeader` | string | same as `host:port` | advertised host:port in `alt-svc` header for tcp-based HTTP traffic |
| `http3.options` | key-value | empty list | controller specific options such as GSO, GRO, other parameters defined in [`alt-svc`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc#syntax) header, intial window size, etc |

`http3` field can be considered as `extended` support level.

**note**: if http3 becomes the default protocol in the near future, this field can be easily deprecated without changing the rest of the object fields.

## Alternatives

### 1. Separated `listener` by defining a new protocol

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: separated-listener-for-http3
spec:
  gatewayClassName: http3-enabled-gateway
  listeners:
  - name: http3
    protocol: HTTP3
    port: 443 # can be used for alt-svc, but you can't set it to a different port
    hostname: foo.example.com
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert
      options:
        minTlsVersion: 1.3
  - name: https
    protocol: HTTPS
    port: 443
    hostname: foo.example.com
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert

In this design, you need to create a new `listener` for HTTP3 traffic. It allows you to enable HTTP3 traffic with a similar API, also you're be able to enable it only for certain HTTPRoutes. The downside is you can't customize quic or HTTP3 related parameters such as advertised port in `alt-svc` header.

### 2. `GatewayClass` instead of `Gateway`

As you need to provide listening port and certificate to enable HTTP3, it's almost impossible to do this in `GatewayClass` object, unless the controller itself enables it by default in all HTTPS listeners. For example, you can set `PILOT_ENABLE_QUIC_LISTENERS` env to `true` and Istio will handle HTTP3 traffic behind the scene: https://github.com/istio/istio/wiki/Experimental-QUIC-and-HTTP-3-support-in-Istio-gateways .

// TODO why it can not be a good option (hidden information: needs to bind on UDP too, ..., less control, less customization, alt-svc, firewall rules/policies, udp performance considerations and configuraiton, ...)

### 3. `HTTPRoute` or a new `HTTP3Route` object

- In most implementations, it's completely transparent to backend applications, and it's up to client to decide which HTTP version wants to use. (in downstream mode)
- It's still HTTP, so it doesn't make sense to have a new `HTTP3Route` object for just HTTP3.
- There's an open [issue](https://github.com/grpc/grpc/issues/19126) for supporting GRPC over HTTP3, so in the future it can be also used with [`GRPCRoute`](https://github.com/kubernetes-sigs/gateway-api/blob/main/site-src/geps/gep-1016.md)

### 4. `quic` instead of `http3`

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: separated-listener-for-http3
spec:
  gatewayClassName: http3-enabled-gateway
  listeners:
  - name: http3-over-quic
    protocol: HTTP
    port: 443
    hostname: foo.example.com
    quic:
      options:
        key_1: value_1
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert
      options:
        minTlsVersion: 1.3
  - name: https
    protocol: HTTPS
    port: 443
    hostname: foo.example.com
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert

// 1. it can also be used for TLSRoute / TLS Passthrough
// 2. // TODO

## Appendix

### A.1. `ALT-SVC` header

> The alternate service (Alt-svc:) header and its corresponding ALT-SVC HTTP/2 frame are not specifically created for QUIC or HTTP/3. They are part of an already designed and created mechanism for a server to tell a client: "look, I run the same service on THIS HOST using THIS PROTOCOL on THIS PORT". See details in [RFC 7838](https://tools.ietf.org/html/rfc7838).
>
> A client that receives such an Alt-svc response is then advised to, if it supports and wants to, connect to that given other host in parallel in the background - using the specified protocol - and if it is successful switch its operations over to that instead of the initial connection.
>
> https://http3-explained.haxx.se/en/h3/h3-altsvc

// TODO: why `alt-svc` is needed?

1. firewall rules/policies
2. different ip/port
3. different protocol ...
4. ...

## In-progress works

- SVCP and HTTPS DNS records: https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https
- Improving alt-svc header: https://docs.google.com/document/d/1QNaXduqohACK93qLPpxkPJ2rHQMgWqUPL-DkZS11htQ/edit# + https://www.ietf.org/archive/id/draft-nygren-altsvc-fixes-00.txt

## References

- [IETF QUIC Working Group](https://quicwg.org/)
- [RFC 9114 - HTTP/3](https://www.rfc-editor.org/rfc/rfc9114.html)