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

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 explicitly checks this condition at lines 70-76, rejecting any configuration that attempts to enable HTTP/3 without TLS.

// 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 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:

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:

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.

Method 3: Programmatic Go Implementation

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

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: 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: 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: 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.
• Implementation uses quic-go: The runtime in 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}