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 的重試權杖 (retry token)。

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 socket 數量。大於 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 傳輸配置時使用此選項。