# Does Easegress Support HTTP/3 (QUIC) Protocol? Configuration and Implementation Guide

> Yes Easegress supports the HTTP/3 QUIC protocol via its HTTPServer. Learn how to configure and implement HTTP/3 in this guide.

- Repository: [MegaEase/easegress](https://github.com/megaease/easegress)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Yes, Easegress supports HTTP/3 (QUIC) protocol through an optional `http3` flag in the HTTPServer specification, which leverages the quic-go library to serve QUIC traffic alongside traditional HTTP/1.1 and HTTP/2 connections.**

Easegress, the open-source traffic orchestration system from MegaEase, implements modern HTTP standards to handle high-performance API gateways and reverse proxy scenarios. Understanding how to enable and configure HTTP/3 (QUIC) support allows you to reduce latency for clients on unstable networks while maintaining backward compatibility with existing HTTP protocols.

## How Easegress Implements HTTP/3 (QUIC) Support

Easegress integrates HTTP/3 capabilities through the industry-standard **quic-go** library, specifically utilizing the `github.com/quic-go/quic-go` and `github.com/quic-go/quic-go/http3` packages. This implementation allows the HTTPServer object to simultaneously handle HTTP/1.1, HTTP/2, and HTTP/3 connections on the same port.

### Configuration Requirements

To enable HTTP/3, you must set **`http3: true`** in your HTTPServer specification. However, this setting has a strict dependency: **HTTPS must be enabled**. The configuration validator in [`pkg/object/httpserver/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/spec.go) explicitly checks this condition at lines 70-76, rejecting any configuration that attempts to enable HTTP/3 without TLS.

```go
// From pkg/object/httpserver/spec.go (lines 70-76)
if s.HTTP3 && !s.HTTPS {
    return fmt.Errorf("http3 requires https to be enabled")
}

```

### Runtime Architecture

When the HTTPServer initializes with HTTP/3 enabled, the runtime controller in [`pkg/object/httpserver/runtime.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/runtime.go) invokes `startHTTP3Server()` (lines 62-73). This method constructs an `http3.Server` instance with a custom QUIC configuration and launches it in a dedicated goroutine. The server shares the same TLS certificates and address binding as the standard HTTP server, ensuring seamless protocol negotiation through ALPN (Application-Layer Protocol Negotiation).

## Enabling HTTP/3 in Easegress: Three Methods

You can configure HTTP/3 support through YAML manifests, command-line tools, or programmatic Go code. Each method ultimately sets the `http3` field to `true` while ensuring HTTPS is properly configured.

### Method 1: YAML Configuration

The most common approach for production deployments uses a YAML manifest defining the HTTPServer object. Ensure both `https: true` and `http3: true` appear in the spec:

```yaml
apiVersion: easegress.megaease.com/v2
kind: HTTPServer
metadata:
  name: my-http3-server
spec:
  address: "0.0.0.0"
  port: 443
  https: true          # TLS must be enabled

  http3: true          # Enable HTTP/3 (QUIC) support

  keepAlive: true
  routerKind: Ordered
  rules:
    - host: example.com
      pathname: /
      backend: my-backend

```

When applied, this configuration instructs Easegress to listen for HTTP/3 connections on UDP port 443 alongside standard TCP TLS connections.

### Method 2: Command Line with egctl

For quick testing or automation scripts, use the `egctl` command-line tool to create an HTTPServer with HTTP/3 enabled:

```bash
egctl create httpproxy \
  --name my-http3-proxy \
  --address 0.0.0.0 \
  --port 443 \
  --https true \
  --http3 true \
  --certBase64 <BASE64_CERT> \
  --keyBase64 <BASE64_KEY>

```

The `--http3 true` flag maps directly to the `http3` field in the underlying specification. The command validates that `--https true` is also provided, matching the runtime validation logic in [`spec.go`](https://github.com/megaease/easegress/blob/main/spec.go).

### Method 3: Programmatic Go Implementation

When embedding Easegress as a library or writing custom controllers, instantiate the HTTPServer spec programmatically:

```go
import (
    "github.com/megaease/easegress/v2/pkg/object/httpserver"
)

func main() {
    spec := &httpserver.Spec{
        HTTP3:      true,
        HTTPS:      true,
        Address:    "0.0.0.0",
        Port:       443,
        CertBase64: "<BASE64_CERT>",
        KeyBase64:  "<BASE64_KEY>",
    }

    // Validate configuration before applying
    if err := spec.Validate(); err != nil {
        panic(err)
    }

    // Runtime creation is handled by the Easegress supervisor framework
    // which invokes startHTTP3Server() when spec.HTTP3 == true
}

```

This approach leverages the same validation and runtime logic used by the YAML and CLI methods, ensuring consistency across all configuration interfaces.

## Key Source Files and Dependencies

Understanding the implementation requires familiarity with these specific files in the `megaease/easegress` repository:

- **[`pkg/object/httpserver/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/spec.go)**: Defines the `Spec` struct including the `HTTP3` boolean field and contains the validation logic that enforces the HTTPS requirement (lines 70-76).

- **[`pkg/object/httpserver/runtime.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/runtime.go)**: Implements the runtime lifecycle, including `startHTTP3Server()` (lines 62-73) which constructs the `http3.Server` and manages the QUIC listener in a background goroutine.

- **[`docs/07.Reference/7.01.Controllers.md`](https://github.com/megaease/easegress/blob/main/docs/07.Reference/7.01.Controllers.md)**: Official reference documentation describing the `http3` field as "Whether to support HTTP3(QUIC)" (line 116).

- **`go.mod`**: Declares the external dependency on `github.com/quic-go/quic-go`, the underlying library providing QUIC protocol implementation.

## Summary

- **Easegress supports HTTP/3 (QUIC)** through an opt-in configuration flag in the HTTPServer specification.
- **TLS is mandatory**: The `http3: true` setting requires `https: true`, enforced by validation logic in [`pkg/object/httpserver/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/spec.go).
- **Implementation uses quic-go**: The runtime in [`pkg/object/httpserver/runtime.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/runtime.go) leverages the `quic-go` library to spawn an `http3.Server` when the feature is enabled.
- **Configuration flexibility**: You can enable HTTP/3 via YAML manifests, `egctl` CLI commands, or programmatic Go code, with all methods sharing the same underlying validation and runtime behavior.

## Frequently Asked Questions

### Does Easegress support HTTP/3 without TLS?

No. HTTP/3 in Easegress requires TLS to be enabled. The specification validator in [`pkg/object/httpserver/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/spec.go) explicitly rejects configurations where `http3: true` is set but `https: false`. This aligns with the HTTP/3 standard, which operates exclusively over QUIC and requires encryption.

### What library does Easegress use for QUIC implementation?

Easegress uses the **quic-go** library (`github.com/quic-go/quic-go`), specifically the `http3` subpackage. This dependency is declared in the project's `go.mod` file and is imported in [`pkg/object/httpserver/runtime.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/runtime.go) to construct the HTTP/3 server instance and manage QUIC connections.

### Can HTTP/3 and HTTP/2 run simultaneously on the same port?

Yes. When you enable HTTP/3 in Easegress, the server listens on the same address and port for both TCP-based connections (HTTP/1.1 and HTTP/2) and UDP-based connections (HTTP/3/QUIC). The runtime in [`pkg/object/httpserver/runtime.go`](https://github.com/megaease/easegress/blob/main/pkg/object/httpserver/runtime.go) manages both listeners concurrently, allowing clients to negotiate the best available protocol via ALPN and QUIC handshake.

### How do I verify that HTTP/3 is active on my Easegress server?

You can verify HTTP/3 support by checking the server logs for successful initialization of the QUIC listener, or by using client tools that support HTTP/3. Use a browser with HTTP/3 enabled (most modern Chromium-based browsers) and inspect the protocol column in developer tools, or use the `curl` command with `--http3` flag if compiled with ngtcp2 support. Additionally, ensure your Easegress configuration shows `http3: true` in the HTTPServer spec and that no validation errors occur during startup.