Рефлексия сервера

У любого gRPC-сервера есть досадное свойство: он говорит на бинарном протоколе, и пока у вас нет proto-файлов, сгенерированных заглушек и под рукой нужных версий, вы не можете отправить ему ни одного запроса — даже чтобы проверить, что сервис вообще жив. Серверную рефлексию придумали именно для этого: стандартный сервис gRPC, добавив который, сервер начинает отдавать сведения о собственных схемах по самому же gRPC. Док пакета reflection в grpc-go формулирует назначение в одну строку: «Package reflection implements server reflection service». Механика проста и рекурсивна по красоте: рефлексия — это обычный gRPC-сервис поверх вашего сервера, и он отвечает на вопросы «какие у тебя сервисы?» и «какие у них схемы?» тем же транспортом, что и бизнес-вызовы. Спросить эти вопросы можно из кода, но главный потребитель — утилита grpcurl из экосистемы: её README честно называет её «basically curl for gRPC servers» и объясняет проблему, которую она решает: «gRPC servers use a binary encoding on the wire», поэтому «they are basically impossible to interact with using regular curl» — обычный curl, не умеющий HTTP/2 и protobuf, бесполезен. Решение — «This program accepts messages using JSON encoding, which is much more friendly for both humans and scripts»: grpcurl принимает данные в JSON, а схему для перекодирования берёт у сервера через рефлексию. Полезно сразу развести роли двух «встроенных» сервисов из соседних уроков: health из семнадцатого отвечает на вопрос «работаешь ли ты» и знает только статусы, а рефлексия отвечает на вопрос «что ты умеешь» — имена сервисов, методы, типы сообщений. Первая нужна оркестратору, вторая — человеку за терминалом, и включают их обычно вместе.

Первая неожиданность ждёт в списке сервисов после Register: их станет на два больше. Док функции объясняет почему: «Register registers the server reflection service on the given gRPC server. Both the v1 and v1alpha versions are registered» — grpc-go регистрирует сразу обе версии сервиса рефлексии: grpc.reflection.v1.ServerReflection и grpc.reflection.v1alpha.ServerReflection. История тут важна для понимания вывода grpcurl: протокол рефлексии существует давно как v1alpha, а строгое семантически-версионированное v1 появилось позже, и чтобы старые клиенты не сломались, сервер держит оба варианта. В каноническом proto-файле v1alpha об этом сказано прямо: «Warning: this entire file is deprecated. Use this instead» — и рядом option deprecated = true, но исчезать v1alpha не торопится, потому что инструменты разных экосистем до сих пор говорят именно на ней. Если вам точно не нужна обратная совместимость, есть отдельная функция с честным предостережением: «RegisterV1 registers only the v1 version of the server reflection service», дальше док советует: «Many clients may only support v1alpha so most users should use Register instead, at least until clients have upgraded» — большинство должно использовать Register, пока клиенты не обновились. Внутри обе версии — это одна и та же реализация: конструктор NewServerV1 собирает структуру ServerReflectionServer с тремя полями. Поле Services — «The source of advertised RPC services. If not specified, the reflection server will report an empty list when asked to list services» — источник имён сервисов, обычно сам grpc.Server; док уточняет, что список можно и подрезать: «can be customized by wrapping a grpc.Server or using an alternate implementation that returns a custom set of service names» — удобно, если в списке не должно быть внутренних сервисов. Два других поля — резолверы: DescriptorResolver, по умолчанию protoregistry.GlobalFiles (глобальный реестр дескрипторов, куда сгенерированные пакеты кладут свои схемы), и ExtensionResolver, по умолчанию protoregistry.GlobalTypes — реестр расширений. Оба можно подменить своими — рефлексия честно работает через интерфейсы.

Второе отличие рефлексии от привычных unary-сервисов: у неё один-единственный метод, и это двунаправленный стрим. Комментарий в canonical proto объясняет дизайн: «The reflection service is structured as a bidirectional stream, ensuring all related requests go to a single server» — все связанные запросы гарантированно попадают на один сервер, потому что живут в одном соединении. Метод называется ServerReflectionInfo: клиент пишет сообщения ServerReflectionRequest, сервер отвечает ServerReflectionResponse, и делается это в цикле — recv, обработка, send, пока клиент не закроет стрим. Реализация в grpc-go описывает вопросы честно, по одному доку на каждый: «ListServices returns the names of services this server exposes» — а для символьного поиска proto предписывает формат: «This field should be a fully-qualified symbol name (e.g. <package>.<service>[.<method>] or <package>.<type>)». У запроса есть поле host — легаси, которое сервер просто возвращает обратно в ответе в поле valid_host, — и oneof message_request из пяти вариантов, а у ответа симметричный oneof message_response. Обработчик в реализации grpc-go до смешного лаконичен: switch по типу запроса, и на каждый вариант — либо собранный ответ, либо ErrorResponse с кодом и текстом. В proto это поле описано с обещанием совместимости: «This field uses the error codes defined in grpc::StatusCode» — коды те же, что вы разбираете в обработке ошибок из тринадцатого урока, только едут внутри обычного сообщения, а не в статусе RPC. Это важная деталь: «не найдено» в рефлексии — не ошибка стрима, а нормальный ответ ErrorResponse с кодом NotFound, стрим продолжает работать, и клиент может спросить что-то ещё. Единственный случай, когда стрим умирает настоящей ошибкой, — невалидный запрос без распознанного поля oneof: обработчик выходит с status.Errorf(codes.InvalidArgument, «invalid MessageRequest: %v», ...) — недопустимое сообщение роняет весь вызов, а не превращается в ответ об ошибке. Ответы сервера при этом всегда эхом несут original_request — исходный запрос клиента — так что отладчик видит пару вопрос-ответ целиком.

list_services даёт только имена, и весь магический комфорт grpcurl начинается на втором типе запросов — file_containing_symbol и file_by_filename. Ответ — FileDescriptorResponse, и в proto он описан подчеркнуто честно: «Serialized FileDescriptorProto messages. We avoid taking a dependency on descriptor.proto, which uses proto2 only features, by making them opaque bytes instead» — поле это просто массив байт: сериализованные FileDescriptorProto, намеренно непрозрачные, чтобы протокол не зависел от версии descriptor.proto. Клиент сам их разбирает — grpcurl строит из байтов живые схемы и дальше работает с ними как будто у него были ваши proto-файлы. Сколько файлов придёт? Внутренняя реализация grpc-go описывает функцию дословно так: «FileDescWithDependencies returns a slice of serialized fileDescriptors in wire format ([]byte). The fileDescriptors will include fd and all the transitive dependencies of fd with names not in sentFileDescriptors» — сервер отдаёт не один файл, а весь транзитивный граф импортов: описали в order.proto импорт google/timestamp.proto — приедут оба. Map sentFileDescriptors — локальная переменная стрима: сервер помнит, что уже отправил в этом соединении, и не шлёт повторно, что прямо разрешено протоколом: «The reflection service is allowed to avoid sending FileDescriptorProtos that were previously sent in response to earlier requests in the stream». Ищет сервер символ через FindDescriptorByName из реестра, и символ — это не только имя типа: док функции говорит «The given symbol can be a type, a service or a method» — годится и сервис, и метод вида shop.v1.OrderService/GetOrder в записи с точками, и enum, и поле. Не нашлось — ErrorResponse с кодом NotFound и текстом ошибки реестра; файл с путём-плейсхолдером (импортирован, но сам не слинкован в бинарник) трактуется как отсутствующий. Практический нюанс про file_by_filename: путь — это то, под каким именем файл зарегистрирован в реестре дескрипторов, как правило путь от корня proto-модуля, например shop/v1/order.proto, а не расположение на диске сервера; угадать его легко через describe, где grpcurl показывает имена файлов.

Теперь инструмент. grpcurl — CLI на Go из fullstorydev, ставится из релизов brew'ем, snap'ом или go install, и его README задаёт ожидания точно: «It's basically curl for gRPC servers». Ключевая мысль, которую стоит проговорить вслух: «In fact, the way the tool transforms JSON request data into a binary encoded protobuf is using that very same schema» — grpcurl кодирует ваш JSON в protobuf по той самой схеме, которую вы ему дадите; если сервер не отвечает рефлексией, README продолжает, «you will either need the proto source files that define the service or need protoset files that grpcurl can use». То есть без схем grpcurl слеп: схемы либо приходят с сервера (рефлексия — путь по умолчанию), либо даются флагами. Командный интерфейс — три глагола из usage: «%s [flags] [address] [list|describe] [symbol]». С list всё просто: адрес и verb, и на выходе отсортированные имена сервисов. С describe шире: «If 'describe' is indicated, the descriptor for the given symbol is shown. The symbol should be a fully-qualified service, enum, or message name. If no symbol is given then the descriptors for all exposed or known services are shown» — без символа describe печатает всё, с символом — конкретную схему, включая методы, поля с номерами и типами, enum-значения. Третий случай — когда ни list, ни describe не указаны: «the symbol must be a fully-qualified method name in 'service/method' or 'service.method' format. In this case, the request body will be used to invoke the named method» — это уже вызов, о нём через блок. Флаг -plaintext: «Use plain-text HTTP/2 when connecting to server (no TLS)» — для локальной отладки без сертификатов, как в двенадцатом уроке; для TLS-сервера понадобится -cacert/-cert/-key. Ещё две удобные мелочи: -max-time — «The maximum total time the operation can take, in seconds. This sets a timeout on the gRPC context», дедлайн для всего вызова, и -max-msg-sz — потолок входящего сообщения, «defaults to 4,194,304 (4 megabytes)». И, разумеется, важно понимать диагноз при его отсутствии: если сервер без рефлексии, grpcurl падает с ошибкой ровно такого текста — «server does not support the reflection API».

Настоящий workflow отладки — вызов. Адресация описана в usage дословно: «If neither verb is present, the symbol must be a fully-qualified method name in 'service/method' or 'service.method' format» — слэш или точка, оба варианта grpcurl понимает, в отличие от wire-формата, где разделитель всегда слэш: на проводе путь /shop.v1.OrderService/GetOrder вы видели в четвёртом уроке. Тело запроса — флаг -d: «Data for request contents. If the value is '@' then the request contents are read from stdin» — JSON строкой или из stdin, что удобно для многострочных сообщений и скриптов. Если тело не дали, grpcurl не падает: «If no body is given but one is required (i.e. the method is unary or server-streaming), an empty instance of the method's request type will be sent» — уйдёт пустое сообщение, отличный способ проверить валидацию на сервере. Стримовые методы тоже поддержаны, и это одна из причин предпочесть grpcurl самодельным скриптам: для client- и bidi-стримов несколько JSON-сообщений склеиваются подряд (а в формате text — разделяются служебным байтом), для bidi в интерактивном терминале grpcurl читает stdin построчно и отвечает по мере поступления. Помните из седьмого-девятого уроков, что стрим — это один вызов с несколькими сообщениями: grpcurl покажет каждый ответ отдельным JSON-блоком. Типичный цикл отладки выглядит так: list, чтобы убедиться, что сервер вообще тот; describe сервиса и метода, чтобы снять имена полей; вызов с -d; разбор ошибки в JSON — и повтор. Ошибка кода (не-Nil статус) печатается в stderr, и по умолчанию тело ответа в этом случае не показывается — включите -format-error, чтобы увидеть и сообщение статуса в том же JSON-формате. Для метода из десятого урока с метаданными в ответе пригодится -v: verbose-режим печатает заголовки ответа и трейлеры, где сервер оставляет время или идентификатор трассировки.

grpcurl принимает и печатает JSON по правилам canonical JSON mapping из proto3-спецификации — тому набору правил, который в Go реализован в protojson, а исторически — в предшественнике jsonpb, которым grpcurl и пользуется внутри. Базовых правил немного, и их стоит выучить как таблицу умножения, потому что они объясняют девять десятых ошибок при вызовах. Первое: имена полей. На выходе используется JSON-имя поля — по умолчанию camelCase, полученный из snake_case имени в proto (у поля order_id JSON-имя orderId); на вход принимаются оба варианта — и camelCase, и оригинальное proto-имя, так что «order_id: 7» и «orderId: 7» эквивалентны. Второе: 64-битные целые. int64, sint64, uint64, fixed64 сериализуются как JSON-строки в кавычках: int64-значение сорока двух приедет строкой «42», а не числом — не потерять точность на больших числах; в proto с полем int64 отправить число без кавычек grpcurl обычно тоже простит, но принимать от JSON-ответов строку — привычка правильная. Третье: bytes — base64-строка, стандартная или URL-safe. Четвёртое: enum — строковое имя значения на вход и выход; числовой номер принимается на входе, но в ответах ждите имена. Пятое: WellKnownTypes имеют особые JSON-формы: Timestamp — RFC3339-строка, Duration — «3.5s», Any — объект с @type, Empty — {}. Шестое: неизвестные поля — ошибка: разбор остановится с сообщением про unknown field, если не включить флаг -allow-unknown-fields — «When true, the request contents, if 'json' format is used, allows unknown fields to be present. They will be ignored when parsing the request». Это удобно, когда отлаживаете ответ клиента с лишними полями, но по умолчанию строгость — защита от опечаток. Седьмое: пустые поля в ответе опускаются; если нужен полный вид — флаг -emit-defaults: «Emit default values for JSON-encoded responses». Все эти правила едины и для protojson в вашем Go-коде, если вы когда-нибудь сериализуете сообщения в JSON руками: тот же camelCase, те же строки для int64, тот же base64 — выучив grpcurl, вы выучили protojson.

Отладка защищённого сервиса — три четверти работы с grpcurl, и здесь у утилиты три разных флага, которые важно не перепутать. Первый и главный — -H: «Additional headers in 'name: value' format. May specify more than one via multiple flags. These headers will also be included in reflection requests to a server» — заголовки уходят и в ваши RPC, и в reflection-запросы. Это принципиально для связки с десятым уроком: если серверная авторизация живёт в перехватчике, который читает authorization из метаданных каждого вызова, то без токена умрёт и сам describe — рефлексия на вашем сервере ходит через тот же перехватчик. Формально это видно в выводе: reflection-запрос — такой же RPC с путём /grpc.reflection.v1.ServerReflection/ServerReflectionInfo, интерсепторы применяются к нему на общих основаниях; так что -H 'authorization: Bearer ...' — не украшение, а билет внутрь. Второй флаг — -rpc-header: «Additional RPC headers ... will only be used when invoking the requested RPC method. They are excluded from reflection requests» — строго для вызова метода. Когда это нужно? Когда серверный интерсептор рефлексии не должен видеть ваши заголовки, или когда заголовок конфликтует с чем-то в reflection-запросах, или вы просто хотите чистый эксперимент: с -rpc-header list работает без токена, а invoke требует его. Третий — -reflect-header, симметричный: «will only be used during reflection requests and will be excluded when invoking the requested RPC method» — только для рефлексии. Распределение по трём флагам даёт полный контроль: общее — -H, только RPC — -rpc-header, только reflection — -reflect-header. Транспортная часть из двенадцатого урока переносится один в один: -plaintext против -cacert/-cert/-key (взаимный TLS grpcurl тоже умеет), а -insecure с честным предупреждением «(NOT SECURE!)» — только для лабораторий. Пара практических привычек: сначала проверьте доступ без токена (ожидание — честная ошибка Unauthenticated, если авторизация настроена), затем с токеном; и держите -max-time, чтобы зависший вызов не висел терминал.

Сервер без рефлексии — не тупик, просто grpcurl пойдёт в схему с диска. Диагноз вы увидите сразу: «server does not support the reflection API» — это константа ErrReflectionNotSupported из кода grpcurl, которую утилита отдаёт, когда reflection-клиент получил отказ. Первый вариант — исходники: флаг -proto задаёт proto-файл, док читается как инструкция: «The name of a proto source file. Source files given will be used to determine the RPC schema instead of querying for it from the remote server via the gRPC reflection API», а импорты резолвятся через -import-path: «Paths will be searched in the order given. If no import paths are given, all files (including all imports) must be provided as -proto flags» — либо все пути импортов, либо все файлы перечислены явно. Это то самое место, где важен proto import path из третьего урока: grpcurl собирает дескрипторы так же, как protoc, и требует те же пути. Второй вариант — protoset: «The name of a file containing an encoded FileDescriptorSet. This file's contents will be used to determine the RPC schema instead of querying for it from the remote server via the gRPC reflection API» — бинарный файл с набором дескрипторов, который собирает protoc --descriptor_set_out=order.protoset shop/v1/order.proto (при желании с --include_imports, чтобы зависимости приехали в файл, — иначе их придётся подкладывать отдельными -proto). Protoset удобнее в CI: один бинарный артефакт вместо пачки файлов и путей, версия схем зашита в релиз. Есть и гибрид: «-use-reflection ... Defaults to true unless a -proto or -protoset option is provided. If -use-reflection is used in combination with a -proto or -protoset flag, the provided descriptor sources will be used in addition to server reflection to resolve messages and extensions» — список сервисов при этом берётся с сервера, а типы — с диска; полезно, когда сервер знает сервисы, но какие-то зависимости в рефлексию не слинкованы. И заметьте симметрию: у grpcurl есть -protoset-out — «With the list and describe verbs, the listed or described elements and their transitive dependencies will be written to the named file» — можно один раз скачать схемы с живого сервера с рефлексией и дальше ходить в его оффлайн-копию, в том числе на сервер, где рефлексию выключили.

Теперь цена вопроса. Рефлексия отдаёт полную карту вашей API-поверхности любому, кто смог открыть соединение: имена всех сервисов и методов, все сообщения со всеми полями и номерами, enum-значения, опции, пути файлов. Для отладки это подарок; для атаки — разведка: вместо слепого перебора метод противник за один describe получает точные имена полей и типы, с которыми можно строить корректные запросы. Критично понимать: у reflection-сервиса нет никакого встроенного доступа-контроля — это обычный gRPC-сервис, зарегистрированный вашим вызовом Register, и защищать его вы должны теми же средствами, что остальной сервер: перехватчик авторизации из одиннадцатого урока, TLS из двенадцатого, сетевые границы. Отсюда рабочие правила прод-гигиены. Правило первое: гейтите регистрацию явно — не вызывайте reflection.Register в проде вовсе или вызывайте по флагу окружения, который включается только на стендах; поскольку регистрация — ваш код, выключатель тоже ваш. Правило второе: если рефлексия нужна в проде (некоторые инспекционные панели и отладочные прокси без неё слепы), держите её за авторизацией: перехватчик, проверяющий токен админа для путей grpc.reflection.v1 и v1alpha, — и не забудьте, что клиенты должны слать токен и в reflection-запросы, то есть grpcurl с -H. Правило третье: сеть важнее кода — отдельный админ-порт или доступ только из внутреннего контура, как и для health из семнадцатого урока: обе «служебные» поверхности закрываются одинаково. Правило четвёртое: вспомните про ServerOptions — список сервиса можно подрезать, обернув провайдер имён, если наружу не должны попадать даже имена внутренних сервисов. И последнее: рефлексия не отдаёт данные — только схемы; утечка схемы неприятна, но это не утечка пользовательских данных, и взвешивать риск стоит именно так.

Честная оговорка про формат, одна на урок: в самоучителе есть песочница с интерпретатором Go, но сеть в браузере недоступна — gRPC-сервер, kubelet и grpcurl в браузере не запустить, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет; каждая команда из урока проверяется локально за пару минут. Три эксперимента. Первый: включите reflection.Register на сервере из семнадцатого урока, запустите grpcurl -plaintext localhost:50051 list и убедитесь, что в списке четыре имени — оба reflection-сервиса, health и ваш; затем вызовите Check у grpc.health.v1.Health через grpcurl и сравните с клиентским кодом из прошлого урока. Второй: снимите токен-гейт на сервере перехватчиком из одиннадцатого урока и прогоните матрицу флагов — без заголовка, с -rpc-header, с -H: убедитесь на своих глазах, что list падает без токена только в первых двух случаях. Третий: соберите protoset командой protoc --descriptor_set_out и вызовите метод с -protoset против сервера с выключенной рефлексией — ошибка «server does not support the reflection API» исчезнет, а вывод будет тем же. Дальше по маршруту: девятнадцатый урок — оптимизация proto: как устроена сериализация на низком уровне, почему номера полей важнее имён и что такое backward compatibility при выкатке новых версий схем; рефлексия, кстати, станет вашим микроскопом — grpcurl покажет, как схемы выглядят после добавления полей. Перед ним освежите урок про метаданные — флаги -H и -rpc-header ровно про то же, — и урок про health — list_services покажет его сервис в общем списке. Полный маршрут курса — на странице gRPC-Go.