shiguredo_http11 2026.1.1

HTTP/1.1 Library
Documentation

http11-rs

shiguredo_http11 Documentation GitHub Actions License

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/1.1 スタイル テキストプロトコルライブラリです。HTTP/1.1 の他、RTSP/1.0, RTSP/2.0 等のプロトコルでも利用できます。

特徴

  • Sans I/O
  • 依存ライブラリ 0
  • 圧縮/展開トレイト (Compressor / Decompressor) の提供
    • ライブラリ本体は圧縮実装を含まず、利用者が任意の実装を組み込める

使い方

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

use shiguredo_http11::{Request, ResponseDecoder};

// リクエストを作成してエンコード
let request = Request::new("GET", "/")
    .header("Host", "example.com")
    .header("Connection", "close");
let bytes = request.encode();
// bytes を送信...

// レスポンスをデコード
let mut decoder = ResponseDecoder::new();
// 受信データを feed...
// decoder.feed(&received_data)?;
// if let Some(response) = decoder.decode()? { ... }

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

use shiguredo_http11::{RequestDecoder, Response};

// リクエストをデコード
let mut decoder = RequestDecoder::new();
// 受信データを feed...
// decoder.feed(&received_data)?;
// if let Some(request) = decoder.decode()? { ... }

// レスポンスを作成してエンコード
let response = Response::new(200, "OK")
    .header("Content-Type", "text/plain")
    .body(b"Hello, World!".to_vec());
let bytes = response.encode();
// bytes を送信...

圧縮/展開 (Content-Encoding)

ライブラリ本体は圧縮/展開の実装は含みません。 代わりに Compressor / Decompressor トレイトを提供し、利用者が任意の実装を組み込めます。

use shiguredo_http11::{ResponseDecoder, ResponseEncoder};
use shiguredo_http11::compression::{Compressor, Decompressor, NoCompression};

// 展開器を組み込んだデコーダー
let decoder = ResponseDecoder::with_decompressor(MyGzipDecompressor::new());

// 圧縮器を組み込んだエンコーダー
let encoder = ResponseEncoder::with_compressor(MyGzipCompressor::new());

// 従来通りの使い方 (圧縮なし)
let decoder = ResponseDecoder::new(); // NoCompression がデフォルト

サンプル (examples/) では flate2, brotli, zstd クレートを使った実装例を提供しています。

HEAD リクエストの処理

HEAD リクエストへのレスポンスは、RFC 9110 Section 9.3.2 に基づき GET と同じヘッダーを返しますがボディは送信しません。

use shiguredo_http11::{Request, Response, ResponseDecoder};

// サーバー側: HEAD リクエストへのレスポンス
// RFC 9110 Section 9.3.2: GET と同じヘッダーを返すがボディは送信しない
let is_head = request.method.eq_ignore_ascii_case("HEAD");

let body = b"Hello, World!";
let mut response = Response::new(200, "OK")
    .header("Content-Type", "text/plain")
    .header("Content-Length", &body.len().to_string())
    .omit_body(is_head);

if !is_head {
    response = response.body(body.to_vec());
}
let bytes = response.encode();

// クライアント側: HEAD レスポンスの受信
let request = Request::new("HEAD", "/")
    .header("Host", "example.com");
let bytes = request.encode();
// bytes を送信...

let mut decoder = ResponseDecoder::new();
decoder.set_expect_no_body(true); // HEAD レスポンスではボディなし
// decoder.feed(&received_data)?;
// if let Some(response) = decoder.decode()? { ... }

ストリーミングエンコード

ヘッダーのみをエンコードし、後からボディをチャンクで送信できます。

use shiguredo_http11::{Response, encode_chunk};

let response = Response::new(200, "OK")
    .header("Transfer-Encoding", "chunked");
let headers = response.encode_headers();
// headers を送信...

// チャンクを送信
let chunk1 = encode_chunk(b"Hello, ");
let chunk2 = encode_chunk(b"World!");
let last = encode_chunk(b""); // 終端チャンク

ストリーミングデコード

大きなボディを扱う場合や、ボディを受信しながら処理したい場合はストリーミング API を使用します。

  • decode_headers() - ヘッダーをデコードして (RequestHead/ResponseHead, BodyKind) を返す
  • peek_body() - 利用可能なボディデータをゼロコピーで取得
  • consume_body(len) - ボディデータを消費して BodyProgress を返す
  • progress() - 状態機械を進める (Chunked のチャンクサイズ行パース等)
  • mark_eof() - 接続終了を通知 (close-delimited ボディ用、ResponseDecoder のみ)

BodyKind はボディの種類を表します:

  • ContentLength(usize) - Content-Length による固定長
  • Chunked - Transfer-Encoding: chunked
  • CloseDelimited - 接続終了までがボディ (レスポンスのみ、RFC 9112)
  • Tunnel - CONNECT 2xx レスポンス後のトンネルモード (Transfer-Encoding/Content-Length は無視)
  • None - ボディなし

BodyProgress はデコードの進捗を表します:

  • Continue - 継続中
  • Complete { trailers } - 完了 (トレーラーヘッダーがある場合は含む)

HTTP/1.1

このライブラリが対応している HTTP/1.1 の仕組みです。

Transfer-Encoding

  • chunked 転送エンコーディングのデコード/エンコード
  • チャンクサイズの 16 進数パース
  • トレーラーヘッダーの処理
  • chunk extension の受信処理 (RFC 9112 が specialized service 向けと明記、一般的に使われていない。受信時は内容を破棄)
  • ストリーミング送信用のチャンクエンコード API

Content-Length

  • Content-Length ヘッダーのパース
  • エンコード時の Content-Length 自動計算
  • ボディサイズ制限によるチェック

Connection

  • Connection ヘッダー (keep-alive, close) の処理
  • HTTP/1.1 デフォルトでの keep-alive 動作
  • is_keep_alive() によるキープアライブ判定

ボディ処理

  • Transfer-Encoding: chunked が最優先
  • Content-Length による固定長ボディ
  • ステータスコード 1xx/204/304 はボディなし
  • HEAD リクエストへのレスポンスはボディなし
  • CONNECT 2xx レスポンスはトンネルモードに移行

ヘッダー

  • 大文字小文字を区別しないヘッダー名の比較
  • 同一名ヘッダーの複数値対応
  • ヘッダー数/行長の制限

キャッシュ (RFC 9111)

  • Cache-Control ヘッダー
    • max-age, s-maxage, max-stale, min-fresh
    • stale-while-revalidate, stale-if-error
    • no-cache, no-store, no-transform
    • only-if-cached, must-revalidate, proxy-revalidate
    • must-understand, public, private, immutable
  • Age ヘッダー
  • Expires ヘッダー

条件付きリクエスト (RFC 9110)

  • If-Match / If-None-Match ヘッダー (ETag 比較)
  • If-Modified-Since / If-Unmodified-Since ヘッダー
  • If-Range ヘッダー (ETag または日時)

Range リクエスト (RFC 9110)

  • Range ヘッダーのパース (bytes=0-499, 500-, -500)
    • RangeSpec (Range, FromStart, Suffix)
    • 実際のバイト範囲計算 (to_bounds)
  • Content-Range ヘッダーの生成
    • 満たせない範囲 (unsatisfied) の表現
  • Accept-Ranges ヘッダー

認証 (RFC 7617, RFC 7616, RFC 6750)

  • Basic / Digest / Bearer 認証のエンコード/デコード
  • Authorization / WWW-Authenticate ヘッダー
  • Proxy-Authorization / Proxy-Authenticate ヘッダー

URI (RFC 3986)

  • URI のパース (scheme, host, port, path, query, fragment)
  • パーセントエンコーディング/デコーディング
    • 汎用 (percent_encode)
    • パス用 (percent_encode_path)
    • クエリ用 (percent_encode_query)
    • デコード (percent_decode, percent_decode_bytes)
  • 相対 URI の解決
  • URI の正規化 (normalize)
  • origin-form 生成 (HTTP request-target 用)

その他のヘッダー

  • Content-Type (メディアタイプ、charset、boundary)
  • Content-Encoding (gzip, deflate, compress, identity, 拡張エンコーディング対応)
  • Content-Disposition (inline/attachment、filename、filename*)
  • Content-Language
  • Content-Location
  • Date (HTTP-date 形式: IMF-fixdate (推奨)、RFC 850 / asctime (obs-date、廃止、受信のみ対応))
  • ETag (Strong/Weak)
  • Cookie / Set-Cookie
  • Host ヘッダーのパース/検証 (IPv4, IPv6 リテラル, IPv-future 対応)
  • Multipart (multipart/form-data)
  • Trailer ヘッダー (RFC 9112 Section 7.1.2 禁止フィールド検証、一般的に使われていない)
  • Expect ヘッダー
  • Upgrade ヘッダー
  • Content-Digest / Repr-Digest / Want-Content-Digest / Want-Repr-Digest (RFC 9530)

コンテントネゴシエーション

  • Accept (media-type, q 値)
  • Accept-Charset (deprecated: RFC 9110 Section 12.5.2)
  • Accept-Encoding
  • Accept-Language
  • Vary

セキュリティ

  • Response Splitting 対策: ヘッダー行の CR/LF と obs-fold を拒否
  • Request Smuggling 対策: Transfer-Encoding と Content-Length の同時指定拒否
  • Request Smuggling 対策: Content-Length の不一致検出

制限 (DoS 対策)

デフォルト値:

  • 最大バッファサイズ: 64KB
  • 最大ヘッダー数: 100
  • 最大ヘッダー行長: 8KB
  • 最大ボディサイズ: 10MB
  • 最大チャンクサイズ行長: 64 bytes

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

既知の制限事項

  • obs-text (0x80-0xFF) の非 UTF-8 バイト列はヘッダー値として拒否されます。RFC 9110 では obs-text を含むフィールド値は構文上有効ですが、本ライブラリはヘッダー値を Rust の String として扱うため、非 UTF-8 バイト列を受け付けません。

サンプル

サンプルは Tokio と Rustls を利用しています。引数のライブラリには noargs を利用しています。

http11_client

HTTP/HTTPS クライアントの例です。

cargo run -p http11_client -- https://example.com/
cargo run -p http11_client -- http://httpbin.org/get

機能:

  • HTTP/HTTPS リクエスト送信
  • レスポンス受信とボディ表示
  • rustls-platform-verifier による TLS 検証
  • 圧縮レスポンスの展開 (gzip, br, zstd)

http11_server

HTTP/HTTPS サーバーの例です。

cargo run -p http11_server -- --port 8080
cargo run -p http11_server -- --port 8443 --tls --cert cert.pem --key key.pem

オプション:

  • -p, --port <PORT>: リッスンポート (デフォルト: 8080)
  • --tls: HTTPS 有効化 (ポートデフォルト: 8443)
  • --cert <PATH>: 証明書ファイル (PEM 形式)
  • --key <PATH>: 秘密鍵ファイル (PEM 形式)

機能:

  • HEAD リクエスト対応 (RFC 9110 Section 9.3.2)
  • Keep-Alive 対応 (タイムアウト 60 秒、最大リクエスト数 1000)
  • Accept-Encoding に基づく圧縮 (gzip, br, zstd)
  • エンドポイント: / (HTML), /info (JSON), /echo (リクエスト詳細)

http11_reverse_proxy

HTTP/HTTPS リバースプロキシの例です。

cargo run -p http11_reverse_proxy -- --port 8888 --upstream https://example.com
curl http://localhost:8888/

オプション:

  • -p, --port <PORT>: リッスンポート (デフォルト: 8888)
  • -u, --upstream <URL>: アップストリーム URL (デフォルト: https://example.com)
  • --debug: デバッグログ有効化

機能:

  • ストリーミング転送 (chunked, content-length, close-delimited 対応)
  • 接続プール (ホストあたり最大 10 接続)
  • hop-by-hop ヘッダーの処理
  • HEAD リクエスト対応

http11_server_io_uring

io_uring + kTLS を使った HTTPS サーバーの例です。Linux 専用です。

cargo run -p http11_server_io_uring -- --port 8443 --cert cert.pem --key key.pem

前提条件:

  • Linux カーネル 6.7 以上
  • CONFIG_TLS=y または CONFIG_TLS=m

オプション:

  • -p, --port <PORT>: リッスンポート (デフォルト: 8443)
  • --cert <PATH>: 証明書ファイル (PEM 形式)
  • --key <PATH>: 秘密鍵ファイル (PEM 形式)

機能:

  • io_uring SQPOLL モード
  • kTLS (Kernel TLS) によるカーネルレベル暗号化
  • HEAD リクエスト対応 (RFC 9110 Section 9.3.2)
  • Keep-Alive 対応 (最大リクエスト数 1000)
  • Accept-Encoding に基づく圧縮 (gzip, br, zstd)

規格書

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

ライセンス

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.

時雨堂の Rust 向け OSS ライブラリ