こんにちは､びしょ～じょです｡労働に手を染めて1年経ったんですが､特に深い話はないです｡しかし金で殴る力が強くなったので､沖縄行きの飛行機に乗り遅れても翌日の航空券を買うという技ができました｡美ら海水族館の往復で乗ったバスの中で読んだ『帰りたくない―少女沖縄連れ去り事件―』が1､2番目に印象に残っています｡いい話ですね｡

1. はじめに

今回はHTTP/2を喋るgRPCサーバを実装する｡特に､gRPCプロトコルの理解のためにHTTP/2から上はgRPCのライブラリは使わずに手でやっていく｡ protobufのシリアライズ/デシリアライズはライブラリでやってもらう｡

なんと今回はTypeScriptで実装する｡型システムとか意味論とか言語設計には言いたいことがいっぱいあるが､コミュニティがメチャクソデカいんでライブラリがいっぱいあるし脳死で書いて動かすまでは極めて楽ではある｡

今回使うライブラリは､新しめのNodeの標準ライブラリのhttp2とts-protoc-gen｡クライアントはダルいんでgrpcurlを使う｡便利｡

gRPC over HTTP/2はとりあえず公式のspec[1]を読めば全部OK!! どいうったものを送ればいいのかABNFで書かれており追いやすい｡

では､いきます｡

2. proto

こんな感じのprotoを用意する｡

echo.proto

syntax = "proto3";

package services;

service Echo {
  rpc Call (EchoRequest) returns (EchoResponse);
}

message EchoRequest {
  string message = 1;
}

message EchoResponse {
  string message = 1;
}

これを実装しているサーバのservices.Echo/CallにEchoRequestをPOSTするとEchoResponseが返ってくる｡サービス名はこちらに規則が書かれている｡

3. まずは受ける

rule	op
Request	Request-Headers *Length-Prefixed-Message EOS

rule	op
Length-Prefixed-Message	Compressed-Flag Message-Length Message
Compressed-Flag	0 / 1 # encoded as 1 byte unsigned integer
Message-Length	{length of Message} # encoded as 4 byte unsigned integer (big endian)
Message	*{binary octet}

3-2. 実装

やるだけ｡

echo-service.ts

import * as H2 from 'http2';

export const call = (request: H2.Http2ServerRequest, response: H2.Http2ServerResponse) => {
    const chunks: Buffer[] = [];

    request.on('data', (chunk: Buffer) => chunks.push(chunk));
    request.on('end', () => {
        console.log(chunks);
        response.end();
    });
};

index.ts

import * as H2 from 'http2';
import * as EchoService from './echo-service'

const server = H2.createServer((request, response) => {
    switch (`${request.headers[':method']}${request.headers[':path']}`) {
        case 'POST/services.Echo/Call':
            EchoService.call(request, response);
  }
});

const port = 50051;
server.listen(port, () => {
    console.log(`listen on localhost:${port}`);
});

50051番ポートでとりえあず受ける｡ ts-nodeで適当に動かす｡

$ npx ts-node index.ts
listen on localhost:50051

叩く｡

クライアント

$ grpcurl -vv -plaintext -proto echo.proto -d '{"message": "hello"}' localhost:50051 services.Echo/Call

Resolved method descriptor:
rpc Call ( .services.EchoRequest ) returns ( .services.EchoResponse );

Request metadata to send:
(empty)

Response headers received:
(empty)

Response trailers received:
(empty)
Sent 1 request and received 0 responses
ERROR:
  Code: Unknown
  Message: OK: HTTP status code 200; transport: missing content-type field )

正しく怒られが発生している｡

サバログ

[ <Buffer 00 00 00 00 07 0a 05 68 65 6c 6c 6f> ]

長さ1のArray<Buffer>がconsole.logされたことがわかる｡ JavaScriptはそうなっている｡先頭5バイトをまず読むと､

先頭の\x00はCompressed-Flag(uncompressed)
\x00 \x00 \x00 \x07はメッセージの長さ(7)

となる｡そして､続く7バイト\x0a \x05 \x68 \x65 \x6c x6c \x6fがメッセージである｡

今回は深堀りしないが､この辺を読むと､1番目のフィールド(EchoRequestのmessage)のlength-delimited type(messageの型､string)が5バイト連なっており("hello".length)､\x68 ...("hello")というバイト列がやってきていることが読める｡

いい感じだ｡

4. デシリアライズする

さてprotobufのデータがやってきたので､ここで初めてprotobufを気にかける｡ ts-protoc-genをしてこの通り

bin/protogen.sh

#!/usr/bin/bash

set -eu

protoc \
  --plugin="protoc-plugin-ts=$(npx which protoc-gen-ts)" \
  --js_out="import_style=commonjs,binary:$2" \
  --ts_out="$2" \
  $1

$ mkdir pb
$ ./bin/protogen.sh echo.proto pb
$ ls pb
echo_pb.d.ts  echo_pb.js

よし｡こいつらを引っ張ってなんかいい感じにやる｡

echo-service.ts

import * as H2 from 'http2';
import * as Echo from './pb/echo_pb';

...

とりあえずEcho.EchoRequest.deserializeBinaryすればEchoRequestが手に入るようだ｡ Uint8Arrayを渡す必要がある｡ Uint8ArrayはUint8､つまり1要素が1～255のnumberから成るArrayである｡型は無いんでランタイムに値を詰め込むだけ｡確かにバイト列がやってくるんでUint8Arrayなのね｡

いい感じのライブラリが標準に無いし知らんのでこの辺を実装する｡

hexdata.ts

import * as Assert from 'assert';

type T = Uint8Array;

const encoder = new TextEncoder();
const decoder = new TextDecoder();

export const fromString = (v: string): T => encoder.encode(v);
export const fromBit = (i: boolean): T => Uint8Array.of(i ? 1 : 0);
// uint32をいい感じにuint8 arrayに敷き詰める
export const fromByte = (i: number): T => {
    // がんばる
    Assert.ok(i < 2 ** 32);
    return new Uint8Array(Uint32Array.of(i).buffer).reverse();
};
// ビャッとやる
export const toString = (...ts: T[]) => {
    const tmp = new Uint8Array(ts.reduce((acc, t) => acc + t.length, 0));

    ts.reduce((offset, t) => {
        tmp.set(t, offset);
        return t.length + offset;
    }, 0);

    return decoder.decode(tmp);
};

まあ真面目にやらんでいいのでこんなもんでしょう｡

ではこれを使ってEchoService.callを変更する｡先述のとおり､request bodyを構成するArray<Buffer>が来るのでこれを合体してBufferにする｡ request bodyには先頭5byteにmessageの情報が入っているが､今回は雑に捨てる｡

echo-service.ts

import * as H2 from 'http2';
import * as Echo from './pb/echo_pb'
import * as HexData from './hexdata'

export const call = (request: H2.Http2ServerRequest, response: H2.Http2ServerResponse) => {
    const chunks: Buffer[] = [];

    request.on('data', (chunk: Buffer) => chunks.push(chunk));
    request.on('end', () => {
        // Array<Buffer>を合体して雑に5byte捨てる
        const echoRequest = Echo.EchoRequest.deserializeBinary(HexData.fromString(chunks.join().substring(5)));
        console.log(JSON.stringify(echoRequest.toObject()));
        response.end();
    });
};

では同様に動かすと

$ npx ts-node index.ts
listen on localhost:50051
{"message":"hello"}

イージャン｡

5. そして返す……がしかし

いい感じなったんでこれを返す｡

rule	op
Response	(Response-Headers *Length-Prefixed-Message Trailers) / Trailers-Only

これを返す｡ Trailers-Onlyは今回無視する²｡

Response-Headersは

rule	op
Response-Headers	HTTP-Status [Message-Encoding] [Message-Accept-Encoding] Content-Type *Custom-Metadata
HTTP-Status	":status 200"
Message-Encoding	"grpc-encoding" Content-Coding
Message-Accept-Encoding	"grpc-accept-encoding" Content-Coding *("," Content-Coding)
Content-Type	"content-type" "application/grpc" [("+proto" / "+json" / {custom})]
Custom-Metadata	(省略)³

Trailersは

rule	op
Trailers	Status [Status-Message] *Custom-Metadata
Status	"grpc-status" 1*DIGIT ; 0-9
Status-Message	"grpc-message" Percent-Encoded
Percent-Encoded	1*(Percent-Byte-Unencoded / Percent-Byte-Encoded)
Percent-Byte-Unencoded	1*( %x20-%x24 / %x26-%x7E ) ; space and VCHAR, except %
Percent-Byte-Encoded	"%" 2HEXDIGIT ; 0-9 A-F

サーバは常にHTTP status200を返し､gRPCのstatusとしてgrpc-statusを利用するようだ｡

今回は異常系も考えんでいいか｡

echo-service.ts

...
    request.on('data', (chunk: Buffer) => chunks.push(chunk));
    request.on('end', () => {
        const echoRequest = decodeEchoRequest(chunks.join().substring(5));
        const echoResponse = new Echo.EchoResponse();
        echoResponse.setMessage(echoRequest.getMessage());
        const msg = echoResponse.serializeBinary();
        const len = HexData.fromByte(msg.length);
        // compressしない
        const compression = HexData.fromBit(false);
        const responseBody = HexData.toString(compression, len, msg);
        response.writeHead(200, { 'content-type': 'application/grpc+proto' });
        response.write(responseBody);
        response.write('grpc-status: 0');
        response.end();
    });
...

よし｡サーバを再起動してgrpcurlをさっきと同じ引数で叩く｡

$ grpcurl ...

Resolved method descriptor:
rpc Call ( .services.EchoRequest ) returns ( .services.EchoResponse );

Request metadata to send:
(empty)

Response headers received:
content-type: application/grpc+proto
date: Sat, 17 Apr 2021 19:43:51 GMT

Response trailers received:
(empty)
Sent 1 request and received 0 responses
ERROR:
  Code: ResourceExhausted
  Message: grpc: received message larger than max (1919968045 vs. 4194304)

は?

5-1. HTTP/2の`trailers`

[1]をガッコリ読むと

For responses end-of-stream is indicated by the presence of the END_STREAM flag on the last received HEADERS frame that carries Trailers.

END_STREAMとHEADERS 何? ^^;

これはHTTP/2の話になる｡ちょうど↑の文のちょっと下にHTTP/2のframing sequenceの例が挙がっている｡レスポンスの方を見ると､

HEADERS (flags = END_HEADERS)
:status = 200
grpc-encoding = gzip
content-type = application/grpc+proto

DATA
<Length-Prefixed Message>

HEADERS (flags = END_STREAM, END_HEADERS)
grpc-status = 0 # OK
trace-proto-bin = jher831yy13JHy3hc

なんすかこれ｡確かに､RFCを見るとtrailing header fileldsというのが存在するようだ｡勉強不足でした｡

つまりtrailing header fieldsにgrpc-statusとかgrpc-messageを突っ込めばいいらしい｡ streaming rpcをやっていってエラーを吐くときにメッセージを返しやすいとかなのかしら｡

5-2. あとはやるだけ

echo-server.ts

...
        response.writeHead(200, { 'content-type': 'application/grpc+proto' });
        response.write(responseBody);
        response.addTrailers({ 'grpc-status': 0 });
        response.end();
...

叩く｡

$ grpcurl ...

Resolved method descriptor:
rpc Call ( .services.EchoRequest ) returns ( .services.EchoResponse );

Request metadata to send:
(empty)

Response headers received:
content-type: application/grpc+proto
date: Sat, 17 Apr 2021 21:00:57 GMT

Estimated response size: 7 bytes

Response contents:
{
  "message": "hello"
}

Response trailers received:
(empty)
Sent 1 request and received 1 response )

あーキタキタこれこれ

6. おわりに

あ～～～～～～～今日もgRPCを完全に理解しちまったな……｡完全に理解したんですが､[1]のRequestを見るとgrpc-timeoutとかgrpc-accept-encodingとかgrpc-message-typeとかあるし､ステータスコードもなんか色々あるし､当然ながらgRPCのライブラリを使ったほうがよい｡でもgRPCは何をやってるか知ってると良いことがあるかもしれない｡gRPCライブラリのない言語でgRPCサーバをやっていきたい場合など⁴｡

今回のコード全体はこちら

GitHub - Nymphium/grpc-over-http2-by-hand

Contribute to Nymphium/grpc-over-http2-by-hand development by creating an account on GitHub.

https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md ↩
エラーを返す場合に使う｡voidを返すrpcがあるならその場合もあるかもしれんけどprotobufの仕様上ない? ↩
key-value形式で色々メタデータを送れる｡今回は使わないので省略した｡ ↩
筆者はOCamlでgRPCサーバを実装したかったが､gRPCのOCaml bindingがなかったために本稿を書ける程度にはgRPCについて調べたという経緯がある｡HTTP/2に関する部分がかなり渋いので諦めてenvoyでHTTP/2と1.1をやっていったほうが良いかなと思っている｡ ↩

なんだかんだガチプロトタイピングにはTypeScript楽だしgRPCを手作りする

1. はじめに

2. proto

3. まずは受ける

3-1. 仕様をよむ

3-2. 実装

4. デシリアライズする

5. そして返す……がしかし

5-1. HTTP/2の`trailers`

5-2. あとはやるだけ

6. おわりに