gRPC транспорт в go-kit

Сервис из уроков 04-10 отдаёт миру JSON по HTTP — и для публичного API это правильный выбор: читаемо, отлаживается curl'ом, открывается любым клиентом. Но внутри кластера сервисы зовут сервисы десятки раз на каждый внешний запрос, и там HTTP/1.1 с JSON начинает мешать: текстовые заголовки на каждый вызов, отсутствие контракта в коде — схема запроса живёт в догадках и чужих README, а клиентские библиотеки каждый пишет сам. gRPC решает обе проблемы: контракт объявляется в .proto-файле, из него кодогенерация выдаёт структуры и клиентский код на любом языке, а перевозкой занимается бинарный protobuf поверх HTTP/2 — мультиплексирование многих вызовов на одном TCP-соединении, без Head-of-Line блокировки HTTP/1.1. Позиция go-kit остаётся той же, что в уроке 01-filosofiya: транспорт — плагин, и gRPC — просто ещё один плагин рядом с HTTP. Endpoint не меняется, обёртки из уроков 06-10 не меняются, сервис не знает, кто его вызвал. Это и есть обещание «go kit grpc — то же ядро, другие ноги»: готовый адаптер живёт в пакете kit/transport/grpc, и сейчас мы его смонтируем. Когда gRPC не нужен: браузер (для него есть отдельная история grpc-web), публичный API и интеграции, где проще отдал JSON-форму, чем объяснять партнёру protoc.

Контракт начинается с файла. proto3 описывает service Strings с двумя rpc — Uppercase и Count, ровно те же операции, что в интерфейсе сервиса из урока 03, — и message-типы, зеркальные request/response-структурам из урока 02: поле s на входе, поля v и err на выходе, c для счётчика. Номера после знака равенства — это proto-аналог json-тегов из урока 02: уникальный идентификатор поля в бинарном формате, и менять их после релиза нельзя, как нельзя менять json-теги. Err-поле объявлено строкой — сериализуемой, в отличие от error; бизнес-ошибка едет в ответе, как ты привык. Компилятор protoc с двумя плагинами выдаёт pb-пакет: структуры UppercaseRequest и UppercaseReply, интерфейс StringsServer, который должен реализовать твой сервер, глобальную переменную Strings_ServiceDesc — описание сервиса для каркаса — и функцию RegisterStringsServer, связывающую каркас с твоей реализацией. Обрати внимание на правило из урока 05 в новом свете: кодеки — единственное место, где легальны транспортные типы. Здесь транспортными типами стали сгенерированные структуры pb.*, и граница не сдвинулась: endpoint и сервис про protobuf не узнают никогда.

Здесь gRPC-транспорт сюрпризит того, кто привык к HTTP. kithttp.NewServer возвращает http.Handler: ты монтируешь его на mux, и каркас net/http сам зовёт ServeHTTP — go-kit контролирует всю дорогу от запроса до endpoint'а. У gRPC стандартная точка входа другая: каркас google.golang.org/grpc вызывает методы ТВОЕЙ реализации сгенерированного интерфейса StringsServer — и вставиться в эту цепочку извне библиотека не может. Поэтому grpctrans.NewServer(ep, dec, enc, options...) возвращает не готовый http.Handler, а grpctrans.Handler — объект с одним методом ServeGRPC(ctx, request) (context.Context, interface{}, error): принимает уже разобранное каркасом proto-сообщение, зовёт endpoint через декодер и энкодер, возвращает сгенерированный ответ. Склейкой занимается тонкий адаптер — твой grpcServer: каждый метод интерфейса делает три строки — передать запрос в ServeGRPC и type-assert ответа. Кодеки при этом знакомые до боли: те же имена типов DecodeRequestFunc и EncodeResponseFunc, что и в kithttp, сигнатура func(context.Context, interface{}) (interface{}, error) — только вместо http.Request на вход приходит pb.UppercaseRequest, и декодеру почти нечего парсить: каркас уже превратил байты в структуру.

Адаптер — обычная структура с двумя Handler'ами по числу rpc. Обязательная деталь: встраивание pb.UnimplementedStringsServer. Генератор требует, чтобы реализация встраивала этот тип (в интерфейсе есть mustEmbedUnimplementedStringsServer) — страховка совместимости: когда в .proto добавят новый rpc, старый сервер не упадёт при регистрации, а ответит честным codes.Unimplemented. Методы grpcServer повторяют сигнатуры интерфейса: ctx и pb.UppercaseRequest на входе, pb.UppercaseReply и error на выходе. Три строки тела: позвать ServeGRPC, вернуть ошибку как есть, привести ответ к нужному типу — тот самый шов из урока 02, теперь в обратную сторону. Конструктор NewGRPCServer принимает готовые endpoint'ы — те самые makeUppercaseEndpoint и makeCountEndpoint из урока 02, уже обёрнутые логами, метриками, спанами, лимитером и breaker'ом, — и на каждый строит свой grpctrans.Handler со своими кодеками. Никакого состояния, никаких goroutine: адаптер существует только чтобы каркас и endpoint встретились.

Канон из уроков 02 и 05 в gRPC работает дословно, потому что он не про HTTP, а про разделение каналов. Бизнес-ошибка лежит в Err-поле response-структуры с Failer — и в gRPC-энкодере она едет строкой в *pb.UppercaseReply.Err: клиент получит валидный ответ с err="empty string" и err-канал не дёрнет. Инфраструктурный сбой — дедлайн, недоступная база, сломанный декодер — возвращается по err канала, и здесь вступает каркас: ошибки контекста он конвертирует сам, context.DeadlineExceeded станет кодом DeadlineExceeded, а любую незнакомую ошибку — кодом Unknown с текстом. Unknown — это «непонятно что»: такой код не отличит плохой запрос от аварии, алерты и ретраи по нему слепы. Лечится опцией grpctrans.ServerErrorEncoder — она принимает ErrorEncoder func(ctx, err) error, который возвращает status.Error с осмысленным кодом: прямой аналог твоей таблицы codeFrom из урока 04, только вместо HTTP-статусов — коды gRPC. Правило то же: sentinel-ошибки сервиса мапишь сознательно, всё остальное честно падает в Internal.

У HTTP-запроса были заголовки, у gRPC — metadata.MD: пары ключ-значение, где ключи в нижнем регистре, а каждое значение — срез строк, потому что один ключ может повторяться. Транспорт читает и пишет metadata теми же хуками, к которым ты привык в HTTP, только имена другие. ServerBefore принимает ServerRequestFunc — func(ctx, *metadata.MD) context.Context: функция достаёт из md.Get("x-request-id") значения и кладёт их в контекст — request_id из урока 06 переезжает на новый транспорт без единой правки в логах. Клиентская половина зеркальна: ClientBefore принимает ClientRequestFunc — из контекста в исходящий md через md.Set или md.Append. А для трейсинга go-kit даёт готовую пару: kitot.GRPCToContext(tracer, operationName, logger) на сервере и kitot.ContextToGRPC(tracer, logger) на клиенте — обещание из урока 08-tracing выполнено, SpanContext путешествует в metadata, как uber-trace-id в HTTP-заголовках. ServerAfter работает на выходе: его функции дописывают ответные заголовки — аналог финализатора. Вся наблюдаемость курса — логи 06, метрики 07, спаны 08 — продолжает работать, потому что она стоит на контексте, а контекст транспорт поставляет всегда.

У gRPC есть собственный перехватный механизм, и важно не путать его с опциями go-kit. Интерсептор — функция func(ctx, req, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error): она обёрнута вокруг ВСЕГО вызова метода, от каркаса до ответа; в info.FullMethod лежит путь вида /strings.Strings/Uppercase. Подключаются они на каркасе: grpc.UnaryInterceptor для одного, grpc.ChainUnaryInterceptor для цепочки — первый в цепочке снаружи, как middleware роутера. Типовые jobs: recovery — поймать панику и вернуть codes.Internal вместо обрыва соединения; аутентификация — проверить токен в metadata и оборвать вызов до всякого декодирования; метрики уровня каркаса — счётчик grpc_server_handled_total по методам. Отсюда разница: ServerBefore работает ВНУТРИ Handler'а — когда метод уже выбран и ServeGRPC уже запущен, — он читает metadata в контекст и ни при каких условиях не может «отклонить» вызов. Интерсептор — снаружи, он видит сырой req и может не пустить handler дальше. Правило курса: то, что решает «пустить/не пустить» и ловит паники, — в интерсепторы; то, что поставляет данные в контекст для endpoint'а, — в ServerBefore. Метрики endpoint'а остаются в instrumentingMiddleware из урока 07-metriki, интерсептор их не заменяет, а дополняет транспортным уровнем.

Клиентская сторона — недостающая деталь фабрики из урока 12-discovery. grpc.Dial(target, opts...) строит grpc.ClientConn — виртуальное соединение с инстансом (лениво: реальный коннект происходит на первом вызове); вместо устаревшего WithInsecure передай grpc.WithTransportCredentials(insecure.NewCredentials()). Дальше grpctrans.NewClient(conn, &pb.Strings_ServiceDesc, "Uppercase", enc, dec, options...) возвращает Client с методом Endpoint() — исходящий вызов стал endpoint'ом, как и обещал клиентский транспорт из урока 04. ServiceDesc берётся сгенерированный: клиенту из него важны только ServiceName и MethodName — они склеятся в путь /strings.Strings/Uppercase, поля Handler нужны серверной диспетчеризации, до которой клиенту дела нет. Кодеки клиента зеркальны серверным: EncodeRequestFunc пакует UppercaseRequest в pb.UppercaseRequest, DecodeResponseFunc разворачивает *pb.UppercaseReply в UppercaseResponse. А теперь главная строчка: фабрика возвращает conn вторым значением — io.Closer. HTTP-фабрика возвращала nil, gRPC-фабрика честно отдаёт соединение: когда инстанс покраснел и ушёл из sd.Event, Endpointer вызовет Close у его фабричного результата — conn закрыт, ресурсы отданы. Дальше цепочка из урока 11 не меняется ни на символ: lb.NewRoundRobin и lb.Retry работают поверх gRPC-ног так же, как поверх HTTP. В новых версиях grpc-go вместо grpc.Dial рекомендуют grpc.NewClient — сигнатура та же, семантика чище.

Транспортная глава закрыта: endpoint из урока 02-endpoint обзавёлся вторым лицом — HTTP из урока 04-http-transport и gRPC из этого урока едят один и тот же набор с обёртками из уроков 06-10, а gRPC-клиент встал в фабрику из урока 12 и замкнул круг discovery. Освежить кодеки — в уроке 05-codeki, балансировку с ретраями — в уроке 11-lb-proxy; карта курса — на странице курса. Дальше два урока про middleware как самостоятельный слой: сначала урок 14-endpoint-middleware — логи и метрики как endpoint-обёртки, тот же instrumentingMiddleware, но собранный по правилам пакета endpoint; затем урок 15-service-middleware — декораторы сервиса и инъекция зависимостей. Транспорт может меняться, слои — нет: в этом и был план.