HN 日本語サマリー

← 一覧へ戻る
プログラミング

hyper HTTPライブラリのバグを発見

We found a bug in the hyper HTTP library (blog.cloudflare.com)

144 pointsby Pop_-65 コメント

要約

Cloudflareのチームは、Workers上でRustで構築されたImagesサービスにおいて、hyper HTTPライブラリに潜在する特定条件下でのみ発生する競合状態のバグを発見しました。このバグは、大規模な画像の変換リクエストにおいて、データが途中で切断されるにもかかわらず200 OKが返されるという事象を引き起こしました。6週間にわたる調査の結果、わずか4行のコードでこのバグを修正しました。

全文翻訳

hyper HTTPライブラリのバグ発見方法

RustでWorkers上に構築されたImagesサービスは、Cloudflareのエッジネットワーク上のすべてのマシンで実行されています。クライアント接続を処理するために、私たちはRust向けのオープンソースHTTPライブラリであるhyperを使用しています。

昨年、Workersでリモート画像のカスタムプログラマティックワークフローを可能にするImagesバインディングを導入しました。2025年末に、WorkersランタイムとImagesサービス間のより直接的でローカルな接続を提供するために、このバインディングをリアーキテクチャしました。

ロールアウト直後、変換リクエストが失敗しているという報告を受けました。しかし、それは断続的であり、大きな画像でのみ発生しました。さらに奇妙なことに、これらのリクエストへの応答は、エラーログなしで200ステータスを返しました。画像データは単に切り詰められていました。2メガバイトになるはずの応答が、数百キロバイトで届くことがありました。

私たちは、Imagesバインディングが処理済み画像データをクライアントに返す方法に影響を与えた、hyperライブラリ内の特定の条件下でのみ発生するレースコンディションという、ほぼ見えないバグを6週間かけて追跡しました。最終的に、それを修正するには4行のコードで済みました。

ホップ、ハンドオフ、そしてhyper

開発者がCloudflare上で構築する際、Workersからバインディングを通じてアクセス可能なプラットフォームサービス群からフルスタックアプリケーションを構成します。バインディングは、コンピューティング、ストレージ、AI推論、メディア処理などの開発者プラットフォーム上のリソースへの直接APIを提供します。

Imagesバインディングは、画像最適化と配信を分離します。HTTP応答として出力を返す必要なく、画像をトランスコード、合成、または操作できます。また、URLインターフェースで課される固定シーケンスに従うのではなく、任意の順序で最適化パラメータを適用できます。ここでは、ワーカーは画像データをImages APIに直接渡し、操作をチェーンし、ストリームとして処理結果を取得できます。

const result = await env.IMAGES
  .input(image)
  .transform({ width: 800, rotate: 90 })
  .output({ format: "image/avif" });
return result.response();

大まかに言うと、画像データが当社のさまざまなサービスを通過する仕組みは次のとおりです。

[画像: BLOG-3318 image 1]

パイプは、仲介サービスとImages間のソケット接続を表し、データはカーネルのバッファを通じてプロセスからプロセスへと手渡されます。

バインディングは、Workersランタイムによって管理されるソケット接続を通じてImagesと通信します。ソケット接続は2つのプロセス間の通信チャネルです。ソケットの両端には、オペレーティングシステムのカーネルによって管理されるバッファがあります。これらのバッファは、一方の側がデータを書き込んだ後、もう一方の側が読み取る前にデータが一時的に保持される一時的な領域です。

HyperはImagesサービス側の接続を管理し、ソケットからの着信リクエストを読み取り、ソケットに応答を書き戻します。

Imagesバインディングを使用するリクエストの場合、Imagesサービスは入力を読み取り、要求された最適化操作を実行し、結果をエンコードします。その後、エンコードされた画像全体を単一のインメモリブロックとしてhyperに渡します。

Hyperはこの応答データを独自の内部バッファに書き込みます。この時点で、hyperはエンコード作業が完了したと見なします。送信に必要なすべてのバイトを持っているからです。次のステップは、内部バッファをソケットのアウトバウンドバッファにフラッシュし、データをImagesサービスから反対側の仲介サービスに移動させることです。

反対側のリーダーが高速であれば、hyperは一度にすべてをフラッシュできます。リーダーが到着する速度でデータを消費しているため、アウトバウンドバッファには空きがあります。すべてのデータが送信されると、hyperはソケットでshutdownを発行し、接続が完了し、これ以上データは書き込まれないことを示します。しかし、リーダーが(たとえ数ミリ秒であっても)遅い場合、アウトバウンドバッファがいっぱいになり、hyperは書き込みを続行できる空きができるまで待つ必要があります。

ローカル化

Cloudflareネットワーク上のすべての着信トラフィックは、セキュリティおよびパフォーマンス機能を実行し、適切なバックエンドにリクエストをルーティングする内部仲介サービスであるFLを通過します。バインディングを最初にリリースしたとき、画像データはWorkersランタイムからFLを経由してImagesサービスに流れていました。

このパスは、最初のリリースには自然な選択であり、URLインターフェースと同じアーキテクチャに従っていました。しかし、時間の経過とともに、FLとのこの結合は制約となりました。バインディングへのすべての変更は、FLのリリースサイクルに従う必要がありました。

2025年12月、ImagesチームはFLを新しい仲介サービス、つまり同じマシンで実行される内部ワーカーバインディングに置き換えました。元のアーキテクチャでは、データはFLをネットワークソケット経由で移動していました。このパスは、DNSルックアップやルーティングなど、FLの完全な処理パイプラインのオーバーヘッドを伴いました。

内部バインディングは、Unixソケットを使用してこれらの置き換えを行い、同じマシン上のサービスを直接接続し、FLとネットワークスタックのオーバーヘッドをバイパスしました。これにより、Imagesへのリクエストパスが高速化され、チームはバインディングリリースを独立して制御できるようになりました。

ロールアウトから数日以内に、最初のお客様からの報告を受けました。

200 OK (OKではない)

問題の最初の兆候は、非標準的なセットアップを持つ顧客から来ました。それは、1つのパイプラインが別のパイプラインにネストされた、2層の画像処理でした。

まず、ワーカーはImagesバインディングを使用して、R2から複数の大きなソース画像(JPEG背景とPNGオーバーレイレイヤー)を1つの結合されたJPEGに合成しました。次に、URLインターフェースを介して結果をさらに圧縮、トランスコード、リサイズしました。

[画像: BLOG-3318 image 2]

バグは、内部パイプラインの戻りパスで発生し、応答が外部パイプラインに到達する前に切り詰められました。

内部パイプライン(変換バインディング)は合成を処理しました。外部パイプライン(変換URL)は、スケーリングやフォーマット変換などの配信最適化を処理しました。このレイヤードアプローチにより、内部パイプラインが切り詰められた応答をサイレントに返すと、表示される唯一のエラーは1つ上のレベルに現れました。

error reading a body from connection: end of file before message length reached

外部パイプラインは、内部パイプラインからHTTP 200を受け取り、数メガバイトを約束するContent-Lengthヘッダーを持っていました。実際のボディは、そのうちのわずかな部分でした。1つのリクエストでは、期待される3.3 MBのうち約200 KBしか届きませんでした。エラーは外部パイプラインで表面化しましたが、切り詰めはバインディング、仲介サービス、Imagesサービス、またはその間のどこかで発生した可能性があります。

ブラウザが切り詰められた画像を受信すると、結果は表示されます。フォーマットによっては、画像は部分的にレンダリングされる(例:下半分が欠落しているか灰色になっている)か、デコードに完全に失敗し、代わりに壊れた画像が表示されます。

暗闇でのデバッグ

ここから、リクエストパスを内側に向かって作業し、各レイヤーをテストして、どこで切り詰めが発生しているかを特定しました。これらの取り組みの一部は行き止まりに終わりました。他のものは、検索を絞り込むための手がかりを残しました。

  • 再現の構築。 顧客のネストされたセットアップを模倣したワーカーを構築し、バインディングだけでバグをトリガーできるまでレイヤーを剥がしました。小さなスクリプトでバッチでリクエストを送信できました。初期の実行では、25件中19件のリクエストが失敗しました。届いたデータの量(約200 KB)は、本番環境のソケットバッファのサイズに疑わしいほど近かったです。これは、問題が顧客の設定に関連するものではなく、オンデマンドでバグをトリガーする信頼性の高い方法を与えてくれたことを確認しました。
  • タイムアウトの調査。 早期に、切り詰めがタイムアウト動作(つまり、接続が時間制限後に閉じられる)に関連しているのではないかと疑いました。この理論は、切り詰めがリクエスト期間と相関していなかったため、当てはまりませんでした。
  • hyperバージョンの更新。 バグが最初に報告されたとき、私たちは0.14.xを実行していましたが、最新のhyperバージョンは約1.8.xでした。最も明白な答えが正しく(そして最も簡単な)答えである場合に備えて、hyperバージョン0.14、1.7、1.8でテストしました。しかし、バグは各バージョンで発生したため、アップストリームの修正はありませんでした。
  • ローカルでの再現。 macOSとDebian VMでローカル統合テストを実行しました。かなりの負荷の下でも、ローカルリクエストは失敗を引き起こしませんでした。バインディングソケットへの直接のcurlリクエストやキャプチャされたリクエストの再生は、常に機能するように見えました。バグは、実際の同時実行性と反対側のソケットの実際のWorkersランタイムクライアントが存在する、完全な本番パスでのみ発生しました。これにより、ランタイム自体が疑われました。
  • Workersランタイムの除外。 Workersランタイムがバインディングソケットを介してImagesと通信するために使用するHTTPクライアントを調べました。接続の両側のトレースには、予期しないクローズや早期終了を示すシステムコールは表示されませんでした。クライアントは正しく動作し、他の複数のサービスが同じクライアントを問題なく使用していることを確認しました。
  • 分散トレーシング。 リクエストトレースをエンドツーエンドで検査することにより、切り詰められたボディが顧客の設定の外部変換レイヤーに到達する前に既に存在していたことを確認しました。これにより、問題は内部パイプライン、つまりImagesサービスを経由するバインディングパスに絞られました。
  • 仲介サービスの計装。 応答データを転送する前にボディサイズを測定するために、仲介サービスに計装を追加しました。ボディはImagesサービスを離れるときには既に切り詰められていたため、仲介サービスは除外されました。
  • Imagesサービス内の詳細なトレーシング。 サービスレベルでは、リクエストは処理され、画像は正しくエンコードされ、応答はHTTP 200で返されました。

一貫した唯一のシグナルは、バグがタイミング依存的であることでした。それは、本番パスでのみ、実際の同時実行性があり、大きな画像でのみ発生しました。

真実の核

アプリケーションレベルのデバッグツールは、システムが何をしようとしていると考えているかしか示しませんでした。しかし、システムによれば、すべてが順調でした。トレーシングは応答が送信されたと述べ、ログはエラーを報告せず、Imagesサービスはすべてのリクエストで200を返しました。

システムが実際に行っていることを確認するために、Imagesサービスにstraceをアタッチしました。straceは、プロセスがカーネルに対して行うシステムコールを記録します。これにより、どのバイトがいつ書き込まれたか、シャットダウンがいつ呼び出されたか、クライアントが終了シグナルを送信したかどうかを正確に確認できます。

トレースの設定はデリケートでした。straceは、システムコールが発生したときにそれをインターセプトすることで機能し、各システムコールにわずかなタイミングオーバーヘッドを追加します。狭い範囲のシステムコールをフィルタリングすることで、そのオーバーヘッドを最小限に抑えました。しかし、フィルターを広げると、フラッシュとシャットダウンチェックの間のタイミングがシフトし、バグが完全に消えてしまうほどプロセスが遅くなりました。それだけでも、問題がタイミングに敏感であるという私たちの理論を強化しました。

再現ワーカーを使用してバグをトリガーし、成功したリクエストと失敗したリクエスト間のシステムコール出力を比較しました。

成功したリクエストでは、ソケットバッファが許容するチャンクとして応答が書き込まれ、すべてのデータが送信された後にのみシャットダウンが呼び出されます。たとえば、これは次のようになります。

sendto(42, "HTTP/1.1 200 OK\r\nContent-Length: 14991808\r\n...", ...) = 219264
sendto(42, "\xff\xd8\xff\xe0...", 292352) = 292352
// ... バッファが空になるまで書き込みを続ける ...
sendto(42, "...", 292352) = 292352
shutdown(42, SHUT_WR) = 0

バグを再現したとき、失敗したリクエストは次のようになりました。

sendto(42, "HTTP/1.1 200 OK\r\nContent-Length: 14991808\r\n...", ...) = 219264
shutdown(42, SHUT_WR) = 0

ここでは、ヘッダーとボディのわずかな部分に対して1回の書き込みしかなく、すぐにシャットダウンが呼び出されます。14.9 MBの応答のうち、約219 KBしか送信されませんでした。残りの約14.8 MBの画像データはhyperの内部バッファから決して移動せず、書き込みとシャットダウンの間にクライアントからの終了シグナルもありませんでした。代わりに、Imagesサービスは接続を自分で早期にシャットダウンし、完了したと本気で信じていました。

失敗したリクエストは、バグが断続的にトリガーされるレースコンディションであることを確認しました。リクエストが成功するか失敗するかは、フラッシュ操作とシャットダウン操作がオーバーラップするかどうかに依存し、これはリクエストごとに変化しました。バッファがまだ満杯のときにhyperが接続が完了したと判断した正確な瞬間に、データが失われました。

[画像: BLOG-3318 image 3]

リーダーがhyperの書き込みよりも遅く消費する場合、アウトバウンドバッファがいっぱいになります。hyperがバッファが空になる前に接続をシャットダウンすると、応答のごく一部だけが仲介サービスに到達します。この不完全なデータはWorkersランタイムとクライアントに転送されます。

12月のリアーキテクチャはこのバグを導入したわけではありません。このバグは長年、複数のメジャーバージョンにわたってhyperに存在していました。しかし、新しい仲介サービスは、ソケットの応答側の読み取り側を変更しました。私たちの作業仮説は、以前の仲介サービスであるFLはデータを十分に速く消費していたため、応答中にソケットバッファがいっぱいになることはめったになかったというものです。新しいリーダーは、より大きな応答中にバッファがいっぱいになることを時折許容するペースで読み取りました。

すべてをより速くした改善によって導入された、これらの数ミリ秒のバックプレッシャーは、平易な場所で隠されていた欠陥を表面化させるのに十分でした。

ディスパッチループの内部

HyperのHTTP/1接続ライフサイクルは、dispatch.rsというファイルの状態マシンによって駆動されます。これは、リクエストを読み取り、応答を書き込み、書き込みバッファをソケットにフラッシュし、いつシャットダウンするかを決定するループを実行します。簡略化すると、次のようになります。

fn poll_loop(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Error>> {
    loop {
        let _ = self.poll_read(cx)?;
        let _ = self.poll_write(cx)?;
        let _ = self.poll_flush(cx)?;

        if !self.conn.wants_read_again() {
            return Poll::Ready(Ok(()));
        }
    }
}

より正確には、poll_flushの前のlet _がバグの場所です。

Rustでは、let _ = exprはPoll::Pending(フラッシュがまだ完了していないというシグナル)を含む式の結果を破棄します。フラッシュにはまだバッファにメガバイト単位のデータが残っているかもしれませんが、ループはそれを知りません。

リクエストが失敗するとき、これは正確なイベントシーケンスです。

  1. Imagesサービスは画像のエンコードを完了し、応答全体を単一のインメモリブロックとしてhyperに渡します。
  2. Hyperはそのブロックを内部バッファに書き込み、書き込み状態をWriting::Closedとマークします。エンコードの観点からは、作業は完了しています。エンコードするものは何も残っていません。
  3. Hyperはpoll_flushを呼び出して、バッファされたデータをソケットに移動させます。前の例では、ソケットは約219 KBを受け入れました。残りの約14.8 MBはhyperのバッファに残ります。ソケットがいっぱいなので、カーネルはPoll::Pendingを返します。
  4. poll_loopはlet _でPoll::Pendingを破棄します。
  5. wants_read_again()をチェックします。完全なリクエストは既に受信されているため、これはfalseを返します。
  6. poll_loopはPoll::Ready(Ok(()))を返し、フラッシュは完了していませんが、ループが終了したことを示します。
  7. poll_shutdown()が発火します。SHUT_WRシステムコールが発行されます。
  8. クライアントは219 KBと接続が閉じられたことを示すEOF(end-of-file)を受信しますが、14.9 MBを期待しています。

2番目のステップでは、応答ボディがバッファされた(つまり、エンコードが完了した)時点で、実際にフラッシュされた時点ではなく、hyperは書き込み操作を完了としてマークします。ほとんどの場合、フラッシュは1回のパスで完了し、この区別は目に見えません。ソケットバッファがいっぱいになるまれな場合には、hyperは待機しませんが、フラッシュは待機する必要があります。バイトはまだhyperのバッファに残っており、ソケットにフラッシュされるのを待っています。hyperは、このデータがバッファに残ったまま接続をシャットダウンします。

これはまた、curlがバグをトリガーしなかった理由を説明しています。curlは到着したデータをすぐに読み取ります。ソケットバッファがいっぱいになることはなく、フラッシュは常にすぐに完了し、破棄された戻り値は無害です。リーダーが数ミリ秒一時停止することがあった本番パスは、バッファがちょうど悪い瞬間にいっぱいになった唯一の構成でした。

フラッシュを忘れないで

数週間の調査の後、修正自体は概念的に単純でした。hyperは、次に進む前にフラッシュが実際に完了したかどうかを確認する必要がありました。

再現ワーカーはバグが存在することを確認しましたが、なぜ特定のリクエストが失敗したのかは教えてくれませんでした。修正を記述する前に、hyper内の正確なソケット条件をトリガーできるテストが必要でした。

バグをトリガーする条件はわかっていました。つまり、1つのチャンクのデータを受け入れてからブロックするソケットです。制御されたシナリオでテストするために、TCPストリームのカスタムラッパーを構築し、満杯のソケットバッファをシミュレートしました。ラッパーは最初の書き込みで8 KBを受け入れ、その後、バッファのドレインを停止したリーダーを模倣して、それ以降のすべての書き込みでPoll::Pendingを返しました。

テストは、この制約されたソケットを介して500 KBの応答を送信し、492 KBがまだバッファされている間にhyperがシャットダウンを呼び出すかどうかを確認しました。修正なしでは呼び出しました。修正後、待機しました。

当初、ディスパッチループで修正を適用しました。poll_flushの結果を破棄する代わりに、フラッシュが実際に完了したかどうかを確認しました。

let flush_result = self.poll_flush(cx)?;

if flush_result.is_pending() {
    return Poll::Pending;
}

if !self.conn.wants_read_again() {
    return Poll::Ready(Ok(()));
}

フラッシュが完了していない場合、ループは非同期ランタイムにPoll::Pendingを返します。ランタイムはソケットが書き込み可能になるのを待ち、タスクを再度ウェイクアップしてフラッシュを続行します。接続は、すべてのデータが送信された後にのみシャットダウンされます。

この修正を展開したとき、すべてのバイトが書き込まれ、バッファが実際に空になった後にのみシャットダウンが呼び出されたことを確認しました。最初に報告した顧客も、問題がなくなったことを確認しました。

最初のソリューションは機能しましたが、ディスパッチループは修正の適切な場所ではありませんでした。早期にPoll::Pendingを返すことは、読み取りのポーリング頻度を減らすことで同じ接続上の他の操作を遅くする可能性があり、意図しないバックプレッシャーを引き起こします。また、1つの接続が複数のリクエストを連続して処理するキープアライブ接続を正しく処理しません。これらの接続は、前の応答がまだフラッシュされている間でも再利用可能であるべきです。どちらの問題も私たちの特定のサービス(キープアライブは無効になっている)には影響しませんでしたが、修正がアップストリームに貢献された場合、他のhyperユーザーに影響を与える可能性がありました。

hyperの接続ライフサイクルをトレースし、よりターゲットを絞ったアプローチを見つけました。ディスパッチループの動作を変更するのではなく、シャットダウンが実際に呼び出されるポイントで修正を適用しました。ソケットをシャットダウンする前に、hyperはバッファに残っているすべてのデータをフラッシュする必要があります。

pub(crate) fn poll_shutdown(
    &mut self,
    cx: &mut Context<'_>,
) -> Poll<io::Result<()>> {
    ready!(self.poll_flush(cx)?);
    Pin::new(&mut self.io).poll_shutdown(cx)
}

これにより、ディスパッチループは変更されません。データ損失がそうでなければ発生するポイント、つまりシャットダウン直前にのみフラッシュを追加します。

私たちが持ち帰ったもの

アプリケーションレベルのツールは、有用な手がかりを提供するエラー、クラッシュ、またはログエントリを一切表示しませんでした。アプリケーションレベルのオブザーバビリティは、その認識の下に存在するバグに対して盲点を持つ可能性があります。

失敗は断続的に発生し、応答サイズとともにスケールし、curlのような単純なツールでは再現できず、システムをより注意深く観察すると消えました。これらのシグナルは、アプリケーションロジックではなく、接続レイヤーのタイミング依存バグを示していました。

私たちのブレークスルーは、カーネルレベルのツールであるstraceを使用したことからもたらされました。これは、ソケットで実際に行われたことを記録する唯一のレイヤーです。根本的なバグは、部分的なフラッシュと早期シャットダウンの間の数ミリ秒に存在しました。これは、システムをより速くした後にのみ開いたウィンドウでした。

修正と決定的なテストをPR #4018を介してhyperium/hyperにマージしました。これは将来のhyperリリースで利用可能になり、hyperのHTTP/1実装を使用するすべてのサービスが同じレースコンディションで応答データを失うことを防ぎます。

その間、パッチを適用した内部フォークを実行しています。この修正はバインディングアーキテクチャを安定させ、その機能を拡張するための信頼性の高い基盤を作成しました。

Imagesバインディングは当初、リモート画像の変換のみをカバーしていました。今月初め、Imagesバインディングがホスト画像用の操作もサポートするようになったことを発表しました。これにより、開発者はCloudflare上でメディアリッチなアプリケーションを構築するための統一された方法を得られます。

バインディングの仕組みについては、ドキュメントでさらに詳しく読むことができます。