2020/10/20にNode.js v15がリリースされました 🎉
\n色々新機能や破壊的変更が加わっているので、詳しくは公式のリリースノート等をご参照ください。
\n\n— Node.js v15.0.0 is here!. This blog was written by Bethany… | by Node.js | Oct, 2020 | Medium
\n
また、Node.jsのコラボレータによる日本語のわかりやすい記事もあるのであわせてご覧ください。
\nまとめは以上にして本題です。本記事はv15の変更点まとめを目的とした記事ではなく、v15にて新しく追加されたQUICを用いてシンプルなHTTP/3サーバを実装してHTTP over QUIC(HTTP/3)の使用感を掴むことを目的としています。この記事を読み終えると以下のものが手に入ります。
\nまずQUICおよびHTTP/3について軽くおさらいし、QUICモジュールを利用する環境構築を構築、HTTP/3サーバのデモコードと簡単な説明をして、最後にcURLを用いて動作確認します。仕様の詳細にはあまり触れずに実装するために必要な情報にフォーカスします。
\n当記事ではNode.jsのv15.0.1を前提にコードを書いています。またQUICは登場したばかりで現在のStability indexはStability: 1 - Experimental\n、しかもHTTP over QUICについてはUndocumentedです。
\nおそらくQUICをラップしたHTTP/3用の高レベルのAPIが今後登場するでしょうし、後方互換のない破壊的変更が予告なく加わる可能性もあります。ここで得た知識は陳腐化する前提でエッジなAPIをシュッと試したい方は読み進めてもらえればと思います。
なお、当記事ではこれらを前提に書いています。
\n真面目に解説するとボリュームがありすぎるので参考になったリンクを掲載します。概論をおさえておくと以後の理解がスムーズになると思います。
\n少なくとも注意すべきことは、**QUIC＝HTTP/3ではないということです。QUICを利用した新しいHTTPの仕様がHTTP/3です。**QUICはHTTP以外のプロトコルでも使用できるよう設計されています。
\nまた、**Node.jsのQUICにおいても同様です。**QUICを扱う＝HTTP/3を扱うではありません。Node.jsで提供されたQUIC APIはQUICそのものを扱う低レイヤのAPIです。そのためQUICを用いてHTTP/3サーバを実装するというイメージを持っておいてください。ここを混同するとドキュメントの読み方やトラブルシューティング時に混乱します。
実装を始める前に、既存のHTTP/3のサイトで動作確認します。ユーザエージェントがHTTP/3に対応しているかどうかはこちらのサイトから確認できます。
\n\n現時点ではHTTP/3のブラウザの対応状況はいまひとつです。iOS Safariでフラグつきでサポートされている、Google Chromeにてサポートされているとの情報を得ましたが、私の環境ではどちらも動作しませんでした。
\nhttps://caniuse.com/?search=quic
\n本記事では動作確認にcURLを利用します。cURLでHTTP/3を利用するためにcURLをソースコードからビルドする必要があり、cURL公式のDockerイメージにもHTTP/3に対応したタグがないためHTTP/3対応したビルドを配布されているcurlのHTTP/3通信をDocker上で使ってみる - Qiitaを利用させてもらいます。試しに http3.is に対してリクエストを送った結果の抜粋がこちらです。
\n$ docker run -it --rm ymuski/curl-http3 curl -v https://http3.is --http3\n* Trying 199.232.233.77:443...\n* Sent QUIC client Initial, ALPN: h3-29,h3-28,h3-27\n* Connected to http3.is (199.232.233.77) port 443 (#0)\n* h3 [:method: GET]\n* h3 [:path: /]\n* h3 [:scheme: https]\n* h3 [:authority: http3.is]\n* h3 [user-agent: curl/7.73.0-DEV]\n* h3 [accept: */*]\n* Using HTTP/3 Stream ID: 0 (easy handle 0x55f88c209a20)\n> GET / HTTP/3\n> Host: http3.is\n> user-agent: curl/7.73.0-DEV\n> accept: */*\n>\n< HTTP/3 200\n...\n Your browser does not support the video tag, but it does support HTTP/3!\n...\n* Connection #0 to host http3.is left intactHTTP/3に対応してる旨のHTMLが返ってきました。出力からHTTP/3で通信されているのがわかります。\n次にサーバを実装して、このcurlコマンドを使って動作確認をします。
\nQUICはExperimentalな機能のためQUICを使用するにはフラグをつけてNodeをビルドし直す必要があります。よくあるExperimentalな機能とは違い--experimental-...などのフラグをnodeコマンドに渡しても動作しません。また執筆時点（2020/10/22）ではQUICに対応したDockerイメージもありません。手元でビルドするのは少しハードルが高いかもしれませんが、やることは単にフラグをつけていつも通りNode.jsをビルドするだけです。
$ cd /path/to/nodejs/node\n$ ./configure --experimental-quic\n$ make -j4 # コア数を指定すると早くなります\n$ ./node -p -e \"require('net').createQuicSocket\"\n[Function: createQuicSocket] # <-- 表示されたらOK\n$ node -p -e \"require('net').createQuicSocket\"\nundefined # <-- グローバルなnodeだとundefinedになるrequire('net').createQuicSocketが存在していれば成功です。**以後、./nodeと書いてある場合はいまビルドしたNode.jsを実行するという意味を持ちます。**グローバルにインストールされているnodeコマンドを起動しないようご注意ください。
QUICを使用するにはlocalhostであっても証明書が必須です。適当に自己証明書を作成しておきます。
\n$ mkdir .certs\n$ cd .certs\n$ openssl genrsa 2024 > server.key\n$ openssl req -new -key server.key -subj \"/C=JP\" > server.csr\n$ openssl x509 -req -days 3650 -signkey server.key < server.csr > server.crt\n$ cd -\n$ ls .certs\nserver.crt server.csr server.key環境構築が終わったので本題です。さっそくサーバを実装します。
\n今回は静的なファイルを配信するサーバを実装します。このように起動できるhttp3-serve.jsを実装します。
\nPORT=8888 PUBLIC_ROOT=$PWD ./node http3-serve.jsパラメータは２つです。設定値はすべて環境変数で与えます。
\ncontent-lengthとcontent-typeヘッダも返すいよいよ実装です。先にコードを載せます。このjsはES Modules形式で記述しています。package.jsonに\"type\": \"module\"フィールドが設定されている前提で読んでください。
// [数字] ...と書いてあるところを順に触れていきます。
import fs from 'fs'\nimport fsPromises from 'fs/promises'\nimport path from 'path'\nimport { createQuicSocket } from 'net'\nimport { lookup } from 'mime-types'\n\nconst { PORT, DOCUMENT_ROOT } = process.env\n\nconst key = await fs.readFileSync('./.certs/server.key')\nconst cert = await fs.readFileSync('./.certs/server.crt')\n\n// [1] QUICソケットの初期化\nconst server = createQuicSocket({\n endpoint: { port: PORT },\n server: { key, cert, alpn: 'h3-29' },\n})\n\nserver.on('session', async (session) => {\n // [2] session, streamイベント\n session.on('stream', (stream) => {\n // [3] リクエストヘッダを受け取る\n stream.on('initialHeaders', (rawHeaders) => {\n const headers = new Map(rawHeaders)\n const url = new URL(headers.get(':path'), 'https://localhost')\n const requestPath = path.join(DOCUMENT_ROOT, url.pathname)\n fsPromises\n .stat(requestPath)\n .then((stats) => {\n if (!stats.isFile()) {\n // [4] レスポンスヘッダを返す\n stream.submitInitialHeaders({\n ':status': '403',\n })\n stream.end()\n return\n }\n\n stream.submitInitialHeaders({\n ':status': '200',\n 'content-length': stats.size,\n 'content-type': lookup(requestPath) || 'application/octet-stream',\n })\n // [5] レスポンスボディを返す\n fs.createReadStream(requestPath).pipe(stream)\n })\n .catch((e) => {\n stream.submitInitialHeaders({\n ':status': '404',\n })\n stream.end()\n })\n })\n })\n})\n\nawait server.listen()\nconsole.log(`The socket is listening on :${PORT}`)// [1] QUICソケットの初期化\nconst server = createQuicSocket({\n endpoint: { port: PORT },\n server: { key, cert, alpn: 'h3-29' },\n})特にserver.alpnが重要です。単にQUICを扱うなら任意の値が指定可能ですが、HTTP/3のサーバを立てるなら値を（現バージョンにおいては）h3-29にする必要があります。
\n\nALPN identifiers that are known to Node.js (such as the ALPN identifier for HTTP/3) will alter how the QuicSession and QuicStream objects operate internally, but the QUIC implementation for Node.js has been designed to allow any ALPN to be specified and used.
\n\n
createQuicSocketに指定可能な全てのオプションは公式ドキュメントをご確認ください。
\n\n\n\n
session, streamイベントserver.on('session', async (session) => {\n // [2] session, streamイベント\n session.on('stream', (stream) => {QUICのセッションが開始されたときにsessionイベントが呼び出されます。コールバックの引数はQuicSessionのインスタンスです。QuicSessionが確立した後にクライアントがストリームを作成した時にstreamイベントが呼び出されます。コールバックの引数はQuicStreamのインスタンスです。基本的に１リクエストにつき１回streamイベントが呼び出されます。
QuicSessionは以下の４つの状態のいずれかをとります。このうちInitialに相当するのがsessionイベントです。Readyに相当するのが次に紹介するstreamイベントです。
\n\n\n
\n- Initial - Entered as soon as the QuicSession is created
\n- Handshake - Entered as soon as the TLS 1.3 handshake between the client and server begins. The handshake is always initiated by the client
\n- Ready - Entered as soon as the TLS 1.3 handshake completes. Once the QuicSession enters the Ready state, it may be used to exchange application data using QuicStream instances
\n- Closed - Entered as soon as the QuicSession connection has been terminated
\n— Client and server QuicSessions | Node.js v15.0.1 Documentation
\n
QuicStreamはstream.Duplexを継承しており、リクエストボディはstreamから読み込めます。
// [3] リクエストヘッダを受け取る\nstream.on('initialHeaders', (rawHeaders) => {QuicSessionが確立した後にクライアントがストリームを作成し、リクエストヘッダが届いた時に呼び出されます。rawHeadersにはこのような値が格納されています。
\n[\n [ ':method', 'GET' ],\n [ ':path', '/hoge' ],\n [ ':scheme', 'https' ],\n [ ':authority', 'host.docker.internal:8080' ],\n [ 'user-agent', 'curl/7.73.0-DEV' ],\n [ 'accept', '*/*' ]\n]:からはじまるヘッダは擬似ヘッダ（Pseudo-Header Fields）と呼ぶそうです。よく利用するであろう擬似ヘッダは:methodと:pathです。名前から察する通り:methodはHTTPメソッド、:pathはリクエストされたパス（クエリ文字列含む）が格納されています。リクエストボディが不要ならこの時点でリクエストを処理できます。
他にもヘッダに関するメソッド、イベントがありますが、使い分けは以下の通りです。
\n\n\n\n
\n\n- Informational Headers: Any response headers transmitted within a block of headers using a 1xx status code
\n- Initial Headers: HTTP request or response headers
\n- Trailing Headers: A block of headers that follow the body of a request or response
\n- Push Promise Headers: A block of headers included in a promised push stream
\n
// [4] レスポンスヘッダを返す\nstream.submitInitialHeaders({\n ':status': '403',\n})\nstream.end()streamイベントで受け取ったQuicStreamに対してsubmitInitialHeadersメソッドをコールすることでレスポンスヘッダを返せます。
\nHTTPステータスコードは:statusという擬似ヘッダでセットします。
ボディを返さずにレスポンスを終了する場合はendでストリームを閉じます。
// [5] レスポンスボディを返す\nfs.createReadStream(requestPath).pipe(stream)QuicStreamはストリームです。リクエストボディの読み取りとレスポンスボディの書き込み両方に対応するためにstream.Duplexを継承しています。
\nファイルの内容をレスポンスするならReadableなストリームを作りパイプするだけです。ストリームではない文字列を書き込む場合はstream.write('...')などを使用できます。この辺はストリームの基礎的な話なので詳しくは割愛します。
駆け足ですが解説は以上です。次に作ったサーバの動作確認をします。
\n最後に起動したサーバの動作確認をします。サーバが正常に起動すると以下のような出力になると思います。
\n$ PORT=8080 DOCUMENT_ROOT=$PWD ./node http3-serve.js \nThe socket is listening on :8080\n(node:10968) ExperimentalWarning: The QUIC protocol is experimental and not yet supported for production use\n(Use `node --trace-warnings ...` to show where the warning was created)curlコマンドを利用していくつかリクエストを飛ばしてみます。host.docker.internalはホスト側のlocalhostを参照するDockerの特殊なホスト名です。Linuxの方は適宜読み替えてください。
まずは正常系です。ファイルが存在しているので200が返されます。
\n$ echo 'Hello world' > hello.txt # サーバを起動したディレクトリで適当なファイルを作る\n$ docker run -it --rm ymuski/curl-http3 curl -v 'https://host.docker.internal:8080/hello.txt' --http3\n* Trying 192.168.65.2:8080...\n* Sent QUIC client Initial, ALPN: h3-29,h3-28,h3-27\n* Connected to host.docker.internal (192.168.65.2) port 8080 (#0)\n* h3 [:method: GET]\n* h3 [:path: /hello.txt]\n* h3 [:scheme: https]\n* h3 [:authority: host.docker.internal:8080]\n* h3 [user-agent: curl/7.73.0-DEV]\n* h3 [accept: */*]\n* Using HTTP/3 Stream ID: 0 (easy handle 0x562874d14a40)\n> GET /hello.txt HTTP/3\n> Host: host.docker.internal:8080\n> user-agent: curl/7.73.0-DEV\n> accept: */*\n>\n< HTTP/3 200\n< content-length: 12\n< content-type: text/plain\n<\nHello world\n* Connection #0 to host host.docker.internal left intactファイルが存在しないパスにリクエストします。404が返されます。
\n$ docker run -it --rm ymuski/curl-http3 curl -v 'https://host.docker.internal:8080/xxx' --http3\n* Trying 192.168.65.2:8080...\n* Sent QUIC client Initial, ALPN: h3-29,h3-28,h3-27\n* Connected to host.docker.internal (192.168.65.2) port 8080 (#0)\n* h3 [:method: GET]\n* h3 [:path: /xxx]\n* h3 [:scheme: https]\n* h3 [:authority: host.docker.internal:8080]\n* h3 [user-agent: curl/7.73.0-DEV]\n* h3 [accept: */*]\n* Using HTTP/3 Stream ID: 0 (easy handle 0x56541c3d9a30)\n> GET /xxx HTTP/3\n> Host: host.docker.internal:8080\n> user-agent: curl/7.73.0-DEV\n> accept: */*\n>\n< HTTP/3 404\n* Connection #0 to host host.docker.internal left intact最後にリクエストしたパスがファイルではない場合のテストです。403が返されます。
\n$ mkdir dir # サーバを起動したディレクトリでディレクトリを作成する\n$ docker run -it --rm ymuski/curl-http3 curl -v 'https://host.docker.internal:8080/dir' --http3\n* Trying 192.168.65.2:8080...\n* Sent QUIC client Initial, ALPN: h3-29,h3-28,h3-27\n* Connected to host.docker.internal (192.168.65.2) port 8080 (#0)\n* h3 [:method: GET]\n* h3 [:path: /dir]\n* h3 [:scheme: https]\n* h3 [:authority: host.docker.internal:8080]\n* h3 [user-agent: curl/7.73.0-DEV]\n* h3 [accept: */*]\n* Using HTTP/3 Stream ID: 0 (easy handle 0x562fe362ba30)\n> GET /dir HTTP/3\n> Host: host.docker.internal:8080\n> user-agent: curl/7.73.0-DEV\n> accept: */*\n>\n< HTTP/3 403\n* Connection #0 to host host.docker.internal left intact本記事では本当に最低限の処理しかしてないので、あとはドキュメントやソースコード、QUIC、HTTP/3の仕様書を読みながらいろいろ試してみてください。Node.jsの内部実装の話や、0-RTT・Server pushなどのHTTP/3の他の機能を試す記事も書けたら書こうと思います。ただ、冒頭にも書いた通り現時点ではまだUndocumentedなAPIなので深く使い込むのは時期尚早だと思います。今後QUICをラップした高レベルのAPIがおそらく登場するので、しっかり学ぶのはそれを待ってからでも遅くないと思います。
\nNode.jsのコミュニティはオープンで誰でも開発・議論に参加できます。例えばドキュメントの誤字脱字やAPIに対するフィードバック、仕様と実装が乖離しているなどの何かしらの問題を見つけたらチャンスと思ってコントリビュートしてもらえればと思います。興味のある方はnodejs/nodeリポジトリからぜひ参加してみてください。
\nこれらの一次情報が参考になりました。
\nこれらの二次情報も参考になりました。
\n