http3-rs

[!WARNING] このライブラリは開発中であり、仕様が積極的に変更される場合があります。

About Shiguredo's open source software

We will not respond to PRs or issues that have not been discussed on Discord. Also, Discord is only available in Japanese.

Please read https://github.com/shiguredo/oss before use.

時雨堂のオープンソースソフトウェアについて

利用前に https://github.com/shiguredo/oss をお読みください。

概要

Rust で実装された依存 0 かつ Sans I/O な HTTP/3 と WebTransport over HTTP/3 ライブラリです。

特徴

Sans I/O
- https://sans-io.readthedocs.io/index.html
依存ライブラリ 0
QUIC 非依存
- 任意の QUIC 実装と組み合わせ可能
RFC 9114 (HTTP/3) および RFC 9204 (QPACK) 準拠
WebTransport over HTTP/3 (draft-ietf-webtrans-http3-15) サポート

使い方

クライアント (リクエスト送信、レスポンス受信)

use shiguredo_http3::{ClientConnection, Header, Event, Settings};

// クライアント接続を作成
let mut conn = ClientConnection::new(Settings::default());

// H3 ストリームを初期化 (制御 + QPACK encoder/decoder)
// ストリーム ID は QUIC から割り当てられた単方向ストリーム
let init = conn.init_h3_streams(2, 6, 10).unwrap();
// init.control_data / init.encoder_data / init.decoder_data を各ストリームで送信

// リクエストを送信
let stream_id = conn.send_request(&[
    Header::new(b":method", b"GET"),
    Header::new(b":path", b"/"),
    Header::new(b":scheme", b"https"),
    Header::new(b":authority", b"example.com"),
], true).unwrap();

// 送信データを取得して QUIC で送信
if let Some((data, fin)) = conn.get_stream_data(stream_id) {
    // quic.send_stream_data(stream_id, &data, fin);
}

// QUIC からデータを受信
// conn.feed_stream(stream_id, &response_data, fin).unwrap();

// イベントを処理
while let Some(event) = conn.poll_event().unwrap() {
    match event {
        Event::HeadersEnd { stream_id } => {
            println!("Headers received on stream {}", stream_id);
        }
        Event::Data { stream_id, data } => {
            println!("Data: {} bytes", data.len());
        }
        Event::StreamEnd { stream_id } => {
            println!("Stream {} finished", stream_id);
        }
        _ => {}
    }
}

サーバー (リクエスト受信、レスポンス送信)

use shiguredo_http3::{ServerConnection, Header, Event, Settings};

// サーバー接続を作成
let mut conn = ServerConnection::new(Settings::default());

// H3 ストリームを初期化 (制御 + QPACK encoder/decoder)
let init = conn.init_h3_streams(3, 7, 11).unwrap();
// init.control_data / init.encoder_data / init.decoder_data を各ストリームで送信

// QUIC からデータを受信
// conn.feed_stream(stream_id, &request_data, fin).unwrap();

// イベントを処理
while let Some(event) = conn.poll_event().unwrap() {
    match event {
        Event::HeadersEnd { stream_id } => {
            // リクエストヘッダー受信完了
            // レスポンスを送信
            conn.send_response(stream_id, &[
                Header::new(b":status", b"200"),
                Header::new(b"content-type", b"text/plain"),
            ], false).unwrap();
            conn.send_body(stream_id, b"Hello, World!", true).unwrap();
        }
        _ => {}
    }
}

// 送信データを取得して QUIC で送信
if let Some((data, fin)) = conn.get_stream_data(stream_id) {
    // quic.send_stream_data(stream_id, &data, fin);
}

QPACK エンコード/デコード

use shiguredo_http3::qpack::{Encoder, Decoder, Header};

// エンコード
let encoder = Encoder::new();
let headers = vec![
    Header::new(b":method", b"GET"),
    Header::new(b":path", b"/"),
    Header::new(b":scheme", b"https"),
    Header::new(b":authority", b"example.com"),
];

let mut buf = vec![0u8; 1024];
let encoded_len = encoder.encode(&mut buf, &headers).unwrap();

// デコード
let decoder = Decoder::new();
let decoded = decoder.decode(&buf[..encoded_len]).unwrap();

WebTransport over HTTP/3

use shiguredo_http3::webtransport::{
    Session, SessionState, Capsule, Stream, StreamHeader, Datagram,
    FlowControlLimits,
};

// セッションを作成 (session_id = CONNECT ストリーム ID)
let mut session = Session::new(0);
assert_eq!(session.state(), SessionState::Pending);

// セッション状態を遷移
session.set_connecting();
assert_eq!(session.state(), SessionState::Connecting);
session.set_established();
assert_eq!(session.state(), SessionState::Established);

// ローカルのフロー制御リミットを初期化
session.initialize_local_limits(FlowControlLimits {
    max_streams_uni: 10,
    max_streams_bidi: 10,
    max_data: 1_000_000,
});

// ストリームを追加
let stream = Stream::new(4, 0, true); // stream_id, session_id, bidirectional
session.add_stream(stream);

// ストリームヘッダーのエンコード/デコード
let header = StreamHeader::new(0); // session_id
let mut buf = Vec::new();
// 単方向ストリーム: Stream Type (0x54) + Session ID
header.encode_unidirectional(&mut buf);
// 双方向ストリーム: Signal Value (0x41) + Session ID
header.encode_bidirectional(&mut buf);

// Datagram のエンコード/デコード (Quarter Stream ID = session_id / 4)
let datagram = Datagram::new(0, b"hello".to_vec()).unwrap();
let mut buf = Vec::new();
datagram.encode(&mut buf);
let (decoded, consumed) = Datagram::decode(&buf).unwrap();

// Capsule を送信キューに追加
session.queue_capsule(Capsule::MaxData { maximum: 2_000_000 });

// 送信待ち Capsule を取り出す
let capsules = session.take_pending_capsules();

// グレースフルシャットダウン
session.drain();
assert_eq!(session.state(), SessionState::Draining);

// エラーでクローズ (WT_CLOSE_SESSION Capsule を生成)
// session.close_with_error(0, "bye");

HTTP/3

このライブラリが対応している HTTP/3 の機能です。

フレームタイプ (RFC 9114 Section 7.2)

DATA (0x00) - データ転送
HEADERS (0x01) - ヘッダー (QPACK 圧縮)
SETTINGS (0x04) - 接続設定
GOAWAY (0x07) - 接続終了

SETTINGS パラメータ (RFC 9114 Section 7.2.4.1)

SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x01)
SETTINGS_MAX_FIELD_SECTION_SIZE (0x06)
SETTINGS_QPACK_BLOCKED_STREAMS (0x07)
SETTINGS_ENABLE_CONNECT_PROTOCOL (0x08)
SETTINGS_H3_DATAGRAM (0x33)
予約 ID のフィルタリング (0x1f * N + 0x21)
HTTP/2 専用 ID の検出と拒否 (0x02-0x05)

ストリーム

制御ストリーム (0x00)
QPACK エンコーダーストリーム (0x02)
QPACK デコーダーストリーム (0x03)
リクエスト/レスポンスストリーム

エラーコード (RFC 9114 Section 8.1)

H3_NO_ERROR (0x100)
H3_GENERAL_PROTOCOL_ERROR (0x101)
H3_INTERNAL_ERROR (0x102)
H3_STREAM_CREATION_ERROR (0x103)
H3_CLOSED_CRITICAL_STREAM (0x104)
H3_FRAME_UNEXPECTED (0x105)
H3_FRAME_ERROR (0x106)
H3_EXCESSIVE_LOAD (0x107)
H3_ID_ERROR (0x108)
H3_SETTINGS_ERROR (0x109)
H3_MISSING_SETTINGS (0x10a)
H3_REQUEST_REJECTED (0x10b)
H3_REQUEST_CANCELLED (0x10c)
H3_REQUEST_INCOMPLETE (0x10d)
H3_MESSAGE_ERROR (0x10e)
H3_CONNECT_ERROR (0x10f)
H3_VERSION_FALLBACK (0x110)
QPACK_DECOMPRESSION_FAILED (0x200)
QPACK_ENCODER_STREAM_ERROR (0x201)
QPACK_DECODER_STREAM_ERROR (0x202)

イベント

SettingsReceived - SETTINGS フレーム受信
HeadersBegin - ヘッダー受信開始
Header - 個別ヘッダー受信
HeadersEnd - ヘッダー受信完了
Data - データ受信
StreamEnd - ストリーム終了
StreamReset - ストリームリセット (RESET_STREAM 受信)
StopSending - 送信停止要求 (STOP_SENDING 受信)
GoawayReceived - GOAWAY 受信
ConnectionError - 接続エラー

未実装機能

以下の機能は実装していません:

サーバープッシュ (CANCEL_PUSH, PUSH_PROMISE, MAX_PUSH_ID)
- 受信時にエラーを返す

QPACK (RFC 9204)

このライブラリが対応している QPACK の機能です。

ヘッダー圧縮

静的テーブル (99 エントリ)
動的テーブル
Huffman エンコーディング
整数エンコーディング (プレフィックス付き)

エンコーダーストリーム命令

Set Dynamic Table Capacity
Insert With Name Reference (静的/動的テーブル)
Insert With Literal Name
Duplicate

デコーダーストリーム命令

Section Acknowledgment
Stream Cancellation
Insert Count Increment

フィールド行表現

Indexed Field Line (静的/動的テーブル)
Literal Field Line with Name Reference
Literal Field Line with Literal Name
Indexed Field Line with Post-Base Index

WebTransport over HTTP/3

draft-ietf-webtrans-http3 の複数バージョンをサポートし、ピアの SETTINGS から自動的に draft を判定して応答します。

対応 draft バージョン

draft	ステータス	備考
draft-02	対応	`SETTINGS_ENABLE_WEBTRANSPORT` / `:protocol = webtransport`
draft-07	対応	`SETTINGS_WEBTRANSPORT_MAX_SESSIONS` / セッションゴーン / ドレイン
draft-14	対応	`SETTINGS_WT_MAX_SESSIONS` / カプセルベースフロー制御
draft-15	対応	`SETTINGS_WT_ENABLED` / `:protocol = webtransport-h3` / ALPN

詳細な差分は docs/WT_HTTP3.md を参照してください。

draft 毎の主要な挙動の違い

項目	draft-02	draft-07	draft-15
`:protocol` 値	`webtransport`	`webtransport`	`webtransport-h3`
SETTINGS パラメータ	`SETTINGS_ENABLE_WEBTRANSPORT` (`0x2b603742`)	`SETTINGS_WEBTRANSPORT_MAX_SESSIONS` (`0xc671706a`)	`SETTINGS_WT_ENABLED` (`0x2c7cf000`)
バージョンネゴシエーション	`Sec-Webtransport-Http3-Draft02` ヘッダー	SETTINGS コードポイント	SETTINGS コードポイント + ALPN ヘッダー
アプリケーションエラーコード幅	8 bit	32 bit	32 bit
`SETTINGS_ENABLE_CONNECT_PROTOCOL`	暗黙 (不要)	サーバーのみ必須	サーバーのみ必須
`SETTINGS_H3_DATAGRAM`	不要	明示的に必須	明示的に必須
QUIC `max_datagram_frame_size`	不要	明示的に必須	明示的に必須
`reset_stream_at` transport parameter	不要	不要	必須
データグラム形式	Datagram Format Type `WEB_TRANSPORT` (`0xff7c00`)	Quarter Stream ID (RFC 9297)	Quarter Stream ID (RFC 9297)
セッション終了カプセル	`CLOSE_WEBTRANSPORT_SESSION`	`CLOSE_WEBTRANSPORT_SESSION`	`WT_CLOSE_SESSION`
ドレインカプセル	なし	`DRAIN_WEBTRANSPORT_SESSION`	`WT_DRAIN_SESSION`
セッション終了時のエラーコード	指定なし	`WEBTRANSPORT_SESSION_GONE` (`0x170d7b68`)	`WT_SESSION_GONE` (`0x170d7b68`)
セッションレベルフロー制御	なし	なし	カプセルベース (`WT_MAX_DATA` / `WT_MAX_STREAMS`)
ALPN ネゴシエーション	なし	なし	`WT-Available-Protocols` / `WT-Protocol`
TLS エクスポーター	なし	なし	`EXPORTER-WebTransport`
優先度制御	なし	なし	RFC 9218 推奨
`RESET_STREAM_AT` の使用	不要	不要	必須 (ストリームヘッダー確実配信のため)

draft-02 / draft-07 ではセッションレベルフロー制御が存在しないため、同時セッションは原則 1 つに制限されます。draft-15 ではカプセルベースのフロー制御 (WT_MAX_DATA, WT_MAX_STREAMS, WT_DATA_BLOCKED, WT_STREAMS_BLOCKED) によって複数セッションを扱えます。

CONNECT リクエスト/レスポンス

拡張 CONNECT (RFC 8441, RFC 9220) によるセッション確立
ドラフトバージョンネゴシエーション (draft-02/07/14/15)
:protocol 疑似ヘッダー (webtransport / webtransport-h3)
トランスポートケイパビリティ検証 (SETTINGS / QUIC パラメータ)
CONNECT リクエスト/レスポンスバリデーション

ストリーム

双方向ストリーム (WT_STREAM フレーム, シグナル値 0x41)
単方向ストリーム (ストリームタイプ 0x54)
ストリームヘッダーのエンコード/デコード
単方向ストリーム分類 (WebTransport / HTTP/3 の判定)

Capsule Protocol

WT_CLOSE_SESSION (0x2843)
WT_DRAIN_SESSION (0x78ae)
WT_MAX_DATA (0x190B4D3D)
WT_MAX_STREAMS_BIDI (0x190B4D3F)
WT_MAX_STREAMS_UNI (0x190B4D40)
WT_DATA_BLOCKED (0x190B4D41)
WT_STREAMS_BLOCKED_BIDI (0x190B4D43)
WT_STREAMS_BLOCKED_UNI (0x190B4D44)

HTTP Datagram

Quarter Stream ID エンコード/デコード (RFC 9297)
QUIC DATAGRAM フレームペイロードの処理

フロー制御

セッションレベルのデータフロー制御
ストリーム数の制限
ブロック通知

セッション管理

セッション状態: Pending → Connecting → Established → Draining → Closed
セッション確立前のストリーム/データグラムバッファリング
グレースフルシャットダウン (WT_DRAIN_SESSION)

エラーコード

BUFFERED_STREAM_REJECTED (0x3994bd84)
SESSION_GONE (0x170d7b68)
FLOW_CONTROL_ERROR (0x045d4487)
ALPN_ERROR (0x0817b3dd)
REQUIREMENTS_NOT_MET (0x212c0d48)
アプリケーションエラーコード変換 (0x00000000-0xffffffff)

SETTINGS

SETTINGS_ENABLE_WEBTRANSPORT (0x2b603742) - draft-02
SETTINGS_WEBTRANSPORT_MAX_SESSIONS (0xc671706a) - draft-07
SETTINGS_WT_MAX_SESSIONS (0x14e9cd29) - draft-14
SETTINGS_WT_ENABLED (0x2c7cf000) - draft-15
SETTINGS_WT_INITIAL_MAX_STREAMS_UNI (0x2b64) - draft-15
SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI (0x2b65) - draft-15
SETTINGS_WT_INITIAL_MAX_DATA (0x2b61) - draft-15

制限 (DoS 対策)

デフォルト値:

最大ヘッダーセクションサイズ: 16KB
QPACK 最大テーブル容量: 4096 バイト
QPACK ブロックストリーム数: 100

Limits で各制限値をカスタマイズ可能です。

クレート構成

このリポジトリには以下のクレートが含まれています。

shiguredo_http3

Sans I/O な HTTP/3 ライブラリ本体です。依存ライブラリ 0 で RFC 9114 および RFC 9204 に準拠しています。

tokio-s2n-quic

shiguredo_http3 (Sans I/O) と s2n-quic (AWS) を組み合わせた HTTP/3 / WebTransport の Tokio 統合です。

TLS には Rustls を、暗号ライブラリには aws-lc-rs を使用しています。

ngtcp2-sys

ngtcp2 C ライブラリへの低レベル FFI バインディングです。WebTransport 対応のため webtransport ブランチを使用しています。リリースされたらタグに切り替える予定です。

nghttp3-sys

nghttp3 C ライブラリへの低レベル FFI バインディングです。WebTransport 対応のため webtransport ブランチを使用しています。リリースされたらタグに切り替える予定です。

shiguredo_ngtcp2

ngtcp2/nghttp3 の Rust バインディングです。ngtcp2-sys/nghttp3-sys の上に安全な Rust API を提供します。

TLS には aws-lc-sys (BoringSSL 互換) を使用しています。

tokio-ngtcp2

shiguredo_ngtcp2 を Tokio と統合し、非同期 HTTP/3 クライアント/サーバーを提供します。

tokio-s2n-quic との差異は、QUIC および HTTP/3 プロトコル処理に ngtcp2/nghttp3 を使用している点です。相互運用性テスト用です。

規格書

このライブラリが準拠している RFC 一覧です。

RFC 9000 - QUIC: A UDP-Based Multiplexed and Secure Transport
- https://datatracker.ietf.org/doc/html/rfc9000
- 可変長整数エンコーディングのみ
RFC 9114 - HTTP/3
- https://datatracker.ietf.org/doc/html/rfc9114
RFC 9204 - QPACK: Field Compression for HTTP/3
- https://datatracker.ietf.org/doc/html/rfc9204
RFC 9297 - HTTP Datagrams and the Capsule Protocol
- https://datatracker.ietf.org/doc/html/rfc9297
- Quarter Stream ID エンコーディング
RFC 8441 - Bootstrapping WebSockets with HTTP/2
- https://datatracker.ietf.org/doc/html/rfc8441
- 拡張 CONNECT の定義
RFC 9220 - Bootstrapping WebSockets with HTTP/3
- https://datatracker.ietf.org/doc/html/rfc9220
- HTTP/3 における拡張 CONNECT の適用
draft-ietf-webtrans-overview-12 - WebTransport Protocol Framework
- https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-overview-12
draft-ietf-webtrans-http3-15 - WebTransport over HTTP/3
- https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3-15

ライセンス

Apache License 2.0

Copyright 2026-2026, Shiguredo Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

shiguredo_http3 2026.1.0-canary.0

http3-rs

About Shiguredo's open source software

時雨堂のオープンソースソフトウェアについて

概要

特徴

使い方

クライアント (リクエスト送信、レスポンス受信)

サーバー (リクエスト受信、レスポンス送信)

QPACK エンコード/デコード

WebTransport over HTTP/3

HTTP/3

フレームタイプ (RFC 9114 Section 7.2)

SETTINGS パラメータ (RFC 9114 Section 7.2.4.1)

ストリーム

エラーコード (RFC 9114 Section 8.1)

イベント

未実装機能

QPACK (RFC 9204)

ヘッダー圧縮

エンコーダーストリーム命令

デコーダーストリーム命令

フィールド行表現

WebTransport over HTTP/3

対応 draft バージョン

draft 毎の主要な挙動の違い

CONNECT リクエスト/レスポンス

ストリーム

Capsule Protocol

HTTP Datagram

フロー制御

セッション管理

エラーコード

SETTINGS

制限 (DoS 対策)

クレート構成

shiguredo_http3

tokio-s2n-quic

ngtcp2-sys

nghttp3-sys

shiguredo_ngtcp2

tokio-ngtcp2

規格書

ライセンス