Skip to content
Experimental

HTTP/3

代码示例: http3-netty

HTTP/3 是一种运行在 QUIC 而非 TCP 之上的 HTTP 协议。

Ktor 提供了配合 Netty 服务器引擎的实验性 HTTP/3 支持。

HTTP/3 支持使用的是实验性 Ktor API。要使用该功能,需要选用 ExperimentalKtorApi。

启用 HTTP/3 ​

HTTP/3 始终使用 TLS,因此您需要配置至少一个 SSL 连接器。

要启用 HTTP/3,请在 Netty 引擎配置中调用 enableHttp3() 函数:

kotlin
@OptIn(ExperimentalKtorApi::class)
fun main(args: Array<String>) {
    val keyStore = KeyStore.getInstance("JKS").apply {
        FileInputStream("keystore.jks").use {
            load(it, "foobar".toCharArray())
        }
    }

    embeddedServer(
        Netty,
        configure = {
            sslConnector(
                keyStore = keyStore,
                keyAlias = "server",
                keyStorePassword = { "foobar".toCharArray() },
                privateKeyPassword = { "foobar".toCharArray() }
            ) {
                host = "0.0.0.0"
                port = 8443
            }
            enableHttp3()
        }
    ){
        module()
    }.start(wait = true)
}

对于每个 SSL 连接器,Ktor 都会通过 UDP 将一个 HTTP/3 端点绑定到相同的主机和端口。HTTP/1.1 和 HTTP/2 则在该端口上继续使用 TCP。

要了解有关配置证书和 SSL 连接器的更多信息,请参阅 Ktor Server 中的 SSL 与证书。

配置 HTTP/3 ​

要自定义 HTTP/3 和 QUIC 的行为,请使用 enableHttp3() 配置块内的可用选项:

kotlin
enableHttp3 {
    quicTokenHandler = HmacQuicTokenHandler()
    quicMaxIdleTimeout = 30.seconds
    quicInitialMaxData = 10_000_000
    quicInitialMaxStreamDataBidirectionalLocal = 1_000_000
    quicInitialMaxStreamDataBidirectionalRemote = 1_000_000
    quicInitialMaxStreamsBidirectional = 100
    udpSocketCount = 1
    udpReceiveBufferSize = 0
    udpSendBufferSize = 0
}

以下是可用选项:

quicTokenHandler

默认为 null。

指定用于 QUIC 地址验证的 QuicTokenHandler。使用 HmacQuicTokenHandler 启用基于 HMAC 的重试令牌。

quicMaxIdleTimeout

默认为 30.seconds。

指定 QUIC 连接在关闭前可以保持空闲的时长。必须大于 0。

quicInitialMaxData

默认为 10_000_000。

指定连接的最大数据限制初始值。必须大于 0。

quicInitialMaxStreamDataBidirectionalLocal

默认为 1_000_000。

指定本地发起的双向流的初始流量控制限制。必须大于 0。

quicInitialMaxStreamDataBidirectionalRemote

默认为 1_000_000。

指定远程发起的双向流的初始流量控制限制。必须大于 0。

quicInitialMaxStreamsBidirectional

默认为 100。

指定可以打开的双向流的初始数量。必须大于 0。

udpSocketCount

默认为 1。

指定 HTTP/3 端点的 UDP 套接字数量。大于 1 的值需要平台支持 SO_REUSEPORT。

udpReceiveBufferSize

默认为 0。

指定以字节为单位的 UDP 接收缓冲区(SO_RCVBUF)大小。如果设置为 0,操作系统将使用其默认值。

udpSendBufferSize

默认为 0。

指定以字节为单位的 UDP 发送缓冲区(SO_SNDBUF)大小。如果设置为 0,操作系统将使用其默认值。

这些选项仅适用于 HTTP/3 连接,不会影响 HTTP/1.1 或 HTTP/2。

配置 QUIC 服务器编解码器 ​

对于高级 Netty 配置,请使用 configureQuicServerCodec 选项来自定义底层的 QuicServerCodecBuilder:

kotlin
enableHttp3 {
    configureQuicServerCodec = {
        // 配置 Netty QUIC 服务器编解码器。
    }
}

仅当需要底层 QUIC 传输配置时才使用此选项。