gRPC и Protocol Buffers

01Идея: удалённые вызовы процедур по контракту

В REST вы мыслите ресурсами и HTTP-глаголами: GET /orders/42. В gRPC вы мыслите функциями: OrderService.GetOrder(id). Это называется RPC — remote procedure call, удалённый вызов процедуры. Важное отличие — контракт. В gRPC API описывается в .proto-файле на Protocol Buffers (Protobuf) — языке описания интерфейсов. Компилятор (protoc или Buf CLI) превращает этот файл в код: классы сообщений, клиентский stub, который вызывается как обычный метод, и серверный интерфейс, который вы реализуете. Если сервер меняет тип поля, клиенты, которые перегенерируют код, получают ошибку компиляции, а не сюрприз в продакшене. Представьте .proto-файл как юридически обязывающее меню, которому должны следовать и кухня, и гости.

• Protobuf: язык схем и бинарная кодировка.
• Stub: сгенерированный клиентский объект, методы которого делают сетевые вызовы.
• Channel: долгоживущее соединение с адресом сервера.

02Пишем .proto-файл

.proto-файл объявляет package, сообщения (формы данных) и сервисы (группы RPC-методов). У каждого поля есть тип и номер поля. По сети передаётся именно номер, а не имя, поэтому после публикации его нельзя менять или переиспользовать. Синтаксис proto3 — распространённый выбор; более новые «editions» Protobuf объединяют поведение proto2 и proto3 через feature-флаги, но proto3-файлы остаются полностью поддерживаемыми. Для дат используйте well-known типы, например google.protobuf.Timestamp, и держите по одному сообщению запроса и ответа на каждый метод, чтобы потом добавлять поля, не ломая сигнатуры.

1syntax = "proto3";
2 
3package shop.orders.v1;
4 
5import "google/protobuf/timestamp.proto";
6 
7service OrderService {
8  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
9  rpc WatchOrders(WatchOrdersRequest) returns (stream OrderEvent);
10}
11 
12message GetOrderRequest { string order_id = 1; }
13message GetOrderResponse { Order order = 1; }
14message WatchOrdersRequest { string customer_id = 1; }
15message OrderEvent { Order order = 1; string type = 2; }
16 
17message Order {
18  string id = 1;
19  int64 total_cents = 2;
20  google.protobuf.Timestamp created_at = 3;
21}

03Под капотом: HTTP/2, фрейминг и коды статусов

gRPC работает поверх HTTP/2. Каждый вызов — это HTTP/2-поток на общем TCP-соединении, поэтому много вызовов мультиплексируются без head-of-line blocking на уровне HTTP. Запрос — это POST на /package.Service/Method с content-type application/grpc. Каждое сообщение — бинарный Protobuf с префиксом длины. Metadata (аналог заголовков) несёт auth-токены и ID трассировки. Результаты завершаются трейлерами с grpc-status и grpc-message. У gRPC свои коды статусов, отдельные от HTTP: OK, INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, PERMISSION_DENIED, UNAUTHENTICATED, RESOURCE_EXHAUSTED, UNAVAILABLE, DEADLINE_EXCEEDED и другие. Клиенты должны повторять запрос только при безопасных кодах вроде UNAVAILABLE и только для идемпотентных методов.

1POST /shop.orders.v1.OrderService/GetOrder HTTP/2
2content-type: application/grpc
3te: trailers
4authorization: Bearer <token>
5grpc-timeout: 2S
6 
7<5-byte prefix><binary GetOrderRequest>
8 
9HTTP/2 200
10content-type: application/grpc
11<5-byte prefix><binary GetOrderResponse>
12grpc-status: 0

04Четыре вида RPC

gRPC поддерживает четыре формы вызова. Unary — один запрос и один ответ, как обычная функция. Server streaming отправляет один запрос и получает поток ответов — полезно для live-обновлений заказов или больших выборок. Client streaming отправляет поток запросов и получает один ответ — полезно для загрузки телеметрии или чанков. Bidirectional streaming позволяет обеим сторонам независимо отправлять данные в одном вызове — используется для чатов, совместного редактирования или real-time управления. Внутри одного вызова потоки упорядочены, а flow control обеспечивает HTTP/2. Долгоживущим потокам нужны keepalive и логика переподключения, потому что прокси и балансировщики закрывают простаивающие соединения.

• Unary: rpc Get(Req) returns (Res)
• Server streaming: rpc Watch(Req) returns (stream Event)
• Client streaming: rpc Upload(stream Chunk) returns (Summary)
• Bidirectional: rpc Chat(stream Msg) returns (stream Msg)

05Сервер и клиент на Node.js на практике

В Node.js официальная реализация — @grpc/grpc-js. Можно загружать .proto в рантайме через @grpc/proto-loader, как ниже, или заранее сгенерировать TypeScript-код через Buf и плагины вроде ts-proto или protobuf-es для полной типобезопасности. Каждый клиентский вызов должен передавать дедлайн; без него зависший сервер может держать ресурсы бесконечно. Продакшен-серверы используют TLS (createSsl) или работают в plaintext только внутри mesh, который обеспечивает mTLS.

1import * as grpc from "@grpc/grpc-js";
2import * as loader from "@grpc/proto-loader";
3 
4const def = loader.loadSync("orders.proto", { keepCase: false, longs: String });
5const pkg = grpc.loadPackageDefinition(def) as any;
6const Svc = pkg.shop.orders.v1.OrderService;
7 
8const server = new grpc.Server();
9server.addService(Svc.service, {
10  getOrder: (call: any, cb: any) => {
11    if (!call.request.orderId) return cb({ code: grpc.status.INVALID_ARGUMENT, details: "orderId required" });
12    cb(null, { order: { id: call.request.orderId, totalCents: "4200" } });
13  },
14});
15server.bindAsync("0.0.0.0:50051", grpc.ServerCredentials.createInsecure(), () => {});
16 
17const client = new Svc("localhost:50051", grpc.credentials.createInsecure());
18client.getOrder({ orderId: "42" }, { deadline: Date.now() + 2000 }, console.log);

06gRPC в браузере и на edge

Браузеры не могут полностью управлять HTTP/2-фреймами или читать трейлеры из fetch, поэтому не умеют говорить на нативном gRPC. Есть два распространённых решения. gRPC-Web — немного другой wire-формат, который прокси (Envoy) транслирует в настоящий gRPC; он поддерживает только unary и server streaming. Connect — более новое семейство протоколов от Buf, серверы которого одновременно говорят на gRPC, gRPC-Web и простом, дружелюбном к HTTP/JSON протоколе Connect, так что браузер может вызывать тот же сервис обычным fetch. Многие команды вместо этого оставляют REST или GraphQL на публичном edge и используют gRPC только за ним, с шлюзом вроде grpc-gateway или Envoy, транскодирующим JSON в gRPC.

07Инструменты и чеклист для продакшена

Используйте Buf CLI, чтобы линтить .proto-файлы, ловить ломающие изменения в CI и воспроизводимо генерировать код из buf.gen.yaml. Версионируйте пакеты в имени (orders.v1, orders.v2). Включите стандартный сервис health checking, чтобы балансировщики и пробы Kubernetes могли проверять готовность, а в непродакшен-окружениях — server reflection, чтобы инструменты вроде grpcurl могли исследовать API. Пробрасывайте дедлайны и метаданные трассировки (OpenTelemetry) через вызовы. Лимиты размера сообщений задавайте осознанно; в большинстве реализаций максимальный размер получаемого сообщения по умолчанию — 4 MB.

1# Lint, check for breaking changes vs main, then generate code
2buf lint
3buf breaking --against ".git#branch=main"
4buf generate
5 
6# Call a running server (needs reflection or the .proto)
7grpcurl -plaintext -d '{"order_id":"42"}' localhost:50051 shop.orders.v1.OrderService/GetOrder
8grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

08Wire-формат Protobuf и почему он компактный

Каждое поле кодируется как тег (номер поля, сдвинутый влево на три бита, плюс wire type), за которым следует значение. Целые числа используют varint: маленькие числа занимают один байт, большие — больше. Поэтому номера полей с 1 по 15 так ценны: их тег помещается в один байт, так что приберегите их для частых полей. Отрицательные числа в int32/int64 всегда занимают десять байт; для значений, которые часто бывают отрицательными, используйте sint32/sint64 (zigzag-кодирование). Строки, bytes и вложенные сообщения передаются с префиксом длины. Значения по умолчанию (0, пустая строка, false) в proto3 вообще не записываются, если поле не помечено optional, — поэтому без optional или wrapper-типов нельзя отличить «не задано» от «ноль». Repeated-скаляры в proto3 по умолчанию упакованы (packed).

1message Reading {
2  int32 sensor_id = 1;        // tag 0x08, varint
3  sint32 delta = 2;           // zigzag: -1 encodes as 1 byte
4  optional double value = 3;  // presence tracked: unset != 0.0
5  repeated int32 samples = 4; // packed into one length-delimited block
6  reserved 5, 6;
7  reserved "legacy_name";
8}

09Балансировка, разрешение имён и xDS

gRPC channel — это не одно соединение, а менеджер, который разрешает целевое имя (dns:///orders.internal:50051) в адреса, открывает subchannel к каждому и для каждого вызова выбирает один согласно политике балансировки. По умолчанию pick_first отправляет всё на первый здоровый адрес; round_robin распределяет вызовы по всем. Service config, доставляемый через DNS или заданный в коде, настраивает политики, повторы и таймауты по методам. В большом масштабе gRPC-клиенты могут говорить на xDS — протоколе control plane от Envoy — и получать эндпоинты, веса и правила маршрутизации прямо из control plane, получая поведение proxyless service mesh. Это убирает лишний хоп через sidecar, но привязывает клиентов к control plane mesh.

1// Node.js: client-side round robin + retry policy via service config
2const serviceConfig = JSON.stringify({
3  loadBalancingConfig: [{ round_robin: {} }],
4  methodConfig: [{
5    name: [{ service: "shop.orders.v1.OrderService", method: "GetOrder" }],
6    timeout: "2s",
7    retryPolicy: { maxAttempts: 3, initialBackoff: "0.1s", maxBackoff: "1s",
8      backoffMultiplier: 2, retryableStatusCodes: ["UNAVAILABLE"] },
9  }],
10});
11const client = new Svc("dns:///orders.internal:50051", creds,
12  { "grpc.service_config": serviceConfig });

10Стриминг в масштабе: flow control и backpressure

Flow control в HTTP/2 даёт каждому потоку и соединению окно байтов, которое получатель готов принять. Если клиент медленно читает серверный поток, окно заполняется, и записи сервера блокируются или буферизуются — это backpressure, работающий как задумано. Проблемы появляются, когда серверный код это игнорирует и буферизует неограниченное количество сообщений в памяти. В Node.js учитывайте возвращаемое значение call.write() и ждите события 'drain'. Долгоживущим потокам также нужны keepalive-пинги, чтобы NAT-шлюзы и прокси молча не обрывали простаивающие соединения, но при слишком агрессивных keepalive клиента отклонят с GOAWAY 'too_many_pings'. Проектируйте потоки возобновляемыми: включайте курсор или порядковый номер, чтобы переподключившийся клиент мог продолжить с того места, где остановился.

11Безопасность: mTLS, аутентификация и interceptor-ы

Между сервисами mutual TLS даёт и шифрование, и идентичность: у каждого workload есть сертификат, часто выпускаемый автоматически mesh или SPIFFE/SPIRE, а серверы авторизуют вызывающих по идентичности их сертификата. Идентичность пользователя передаётся отдельно — как bearer-токен в metadata — и проверяется в серверном interceptor-е, который в gRPC играет роль middleware. В interceptor-ах же добавляют логирование, метрики, трассировку, rate limiting и восстановление после паник — единообразно для всех методов. Отключите или защитите server reflection в продакшене, ограничьте максимальный размер сообщений, чтобы не допустить злоупотребления памятью, и явно валидируйте ввод; protovalidate позволяет объявить правила вроде длины строки или формата email прямо в .proto и применять их в сгенерированном коде.