Протоколы: gRPC, gRPC-Web, Connect

Главный факт урока: протокол выбирается не сборкой, не конфигом и не отдельным портом, а заголовком Content-Type каждого запроса. Сгенерированный handler, который вернул NewNoteServiceHandler, — это три обработчика под одним фасадом: собственный протокол Connect, классический gRPC и gRPC-Web. Каждый HTTP-запрос handler смотрит на Content-Type и передаёт его профильному обработчику: application/grpc — gRPC; application/grpc-web и его варианты — gRPC-Web; application/json и application/proto — собственный протокол Connect. Для стриминговых процедур те же роли играют application/connect+proto и application/connect+json. Диспетчеризация занимает микросекунды и не создаёт ни горутин, ни буферов заранее: это обычный switch по строке заголовка. Почему это возможно? Потому что все три протокола согласованы сверху: один и тот же путь /notes.v1.NoteService/GetNote, одни и те же message-типы, один и тот же словарь из шестнадцати кодов ошибок. Различаются они только упаковкой: как сериализуется сообщение, где едут метаданные и где объявляется итог вызова. Именно поэтому схему не нужно трогать при смене протокола — первым уроком мы это зафиксировали, теперь видите механику.

Теперь классика. gRPC определён поверх HTTP/2, и каждое сообщение в нём едет в конверте: один байт флага сжатия плюс четыре байта длины big-endian, и только затем байты сериализованного сообщения. Пять служебных байтов на каждое сообщение — это цена, за которую протокол получает независимость от кодека и поддержку сжатия на уровне сообщения. Метаданные в gRPC — не HTTP-заголовки, а отдельный механизм HTTP/2: request-заголовки уезжают в HEADERS-кадрах, а итог вызова — в трейлерах, специальных кадрах после тела. Успешный unary-вызов выглядит как HTTP 200 с телом из фреймов и трейлером grpc-status: 0; неудачный — как HTTP 200 с трейлерами grpc-status: 5 и grpc-message: not found. Да, вы не ослышались: в классическом gRPC ошибка едет с кодом 200. HTTP-статус в этом протоколе почти ничего не значит — единственный источник правды grpc-status в трейлерах. Отсюда и жёсткое требование транспорта: HTTP/2 обязателен, потому что трейлеров на HTTP/1.1 не бывает. В браузерном Fetch API трейлеры недоступны — помните тупик из первого урока? Вот его техническая причина: JavaScript физически не может прочитать grpc-status, каким бы сервер ни был.

gRPC-Web — это gRPC, адаптированный под браузерные ограничения: он работал поверх HTTP/1.1 и не требовал доступа к трейлерам, которых в браузере нет. Как? Трейлеры переехали из HTTP/2-кадров в конец тела ответа: последним элементом идёт текстовый фрейм grpc-status: 0 (или кодом ошибки), и клиентская библиотека вычитывает его из тела. На практике gRPC-Web почти всегда едет с protobuf-кодеком — бинарным фреймованным потоком, поэтому «человекочитаемость» здесь заканчивается на заголовках. Историческая раскладка такая: классический gRPC-сервер не понимает gRPC-Web, поэтому перед ним ставили переводчик — Envoy с grpc-web-фильтром, который переупаковывал запросы и ответы; это и есть «gRPC-Web требует прокси», фраза из первого урока. Connect-сервер переводчик не нужен: gRPC-Web-обработчик встроен в handler, и запрос application/grpc-web+proto обслуживается тем же кодом, что и application/grpc. При этом gRPC-Web сохраняет главный рудимент родителя: итог вызова не в HTTP-статусе — ответ обычно 200, а grpc-status вычитывается из тела, и лог-системы на уровне HTTP видят «200 OK» даже на ошибку. Это не дефект реализации, а наследие протокола: HTTP/1.1-совместимость стоит того, чтобы жертвовать статусами.

Третий обработчик обслуживает протокол, который Buf спроектировал с нуля, учтя ошибки предшественников — дальше будем звать его просто «протокол Connect». Unary-вызов на нём максимально плоский: POST по пути /package.Service/Method, тело — сериализованное сообщение без конвертов, Content-Type application/json или application/proto объявляет кодек. Итог вызова объявляется настоящим HTTP-статусом по таблице кодов из первого урока: not_found — 404, invalid_argument — 400, resource_exhausted — 429, unimplemented — 501, unavailable — 503. На ошибку тело — маленький JSON с полями code, message и опциональным details; на успех — обычный сериализованный ответ. Метаданные — обычные HTTP-заголовки в обе стороны, никаких HEADERS-кадров и текстовых фреймов-трейлеров. Стриминговые процедуры устроены чуть сложнее: там сообщения едут фреймами, потому что потоку нужна делимитация, и кодек объявляется конвертированным типом application/connect+proto или application/connect+json — но даже в стримах итог вызова остаётся в HTTP-статусе для серверного стриминга и в финальном фрейме-конце для двунаправленного. Дизайн-цель протокола сформулирована в его спецификации честно: RPC должен читаться человеком в devtools и жить на любом HTTP-транспорте, включая HTTP/1.1, без прокси-переводчиков.

Раз вызов без побочных эффектов уезжает GET-ом по обычному URL, его начинает обслуживать вся HTTP-инфраструктура кеширования: браузерный HTTP-кеш, прокси корпоративной сети, CDN на границе, а также ретраи становятся безопасными — повторить GET можно без страха задвоить запись. В gRPC GET-вызовы существовали только как редко реализованная экзотика спецификации, в gRPC-Web их нет вовсе, у Connect это первоклассный путь. Правила гигиены: помечайте NO_SIDE_EFFECTS только действительно чистые процедуры — чтения, подсчёты, статусы; метод с пометкой обязан не иметь последствий, иначе кеш превратит первый вызов в единственный настоящий. Учтите и границу: GET-оптимизация — собственность протокола Connect; клиенты на gRPC и gRPC-Web будут ходить тем же методом POST, и это нормально — контракт от этого не ломается, пометка просто игнорируется теми обработчиками. И да, кешу нужна помощь с заголовками Cache-Control — их ставит ваш middleware или CDN-политика; протокол гарантирует форму запроса, а политику устаревания определяете вы.

Соберём всё в одну карту — она отвечает на вопрос, который вы будете задавать себе в каждом новом проекте. Протокол gRPC выбирайте, когда оба конца ваши и нативные: сервис-сервис внутри периметра, клиенты на Go/Kotlin/Java, HTTP/2 гарантирован от начала до конца. gRPC-Web — когда в цепочке есть браузер, но сервер остаётся классическим gRPC, и прокси-переводчик уже стоит или стоит того по другим причинам; это протокол совместимости, а не выбора. Собственный протокол Connect — дефолт для новых проектов: он обслуживается тем же handler-ом, читается curl-ом, живёт на HTTP/1.1, даёт браузеру то же самое без прокси и добавляет GET-кеш для чистых процедур. Спор «grpc web vs connect» на практике решается одним вопросом: есть ли у вас уже классический gRPC-бэкенд и Envoy? Если да — gRPC-Web достался бесплатно; если вы начинаете с чистого листа — берите протокол Connect и не оглядывайтесь, а gRPC оставьте как опцию совместимости, которая включена всегда и без настройки.

Диспетчеризация по Content-Type даёт свойство, ради которого всё затевалось: контракт один, клиентов сколько угодно. Пометим это на примере notes.v1, который мы собираем с первого урока: хендлер GetNote возвращает одну и ту же заметку — но curl получает JSON со статусом 404 на промахе, grpc-клиент из курса по gRPC-серверам — трейлер grpc-status: 5, а TypeScript-клиент девятого урока — объект ошибки с кодом not_found. Ни одна строка серверного кода не знает, кто на другом конце: обработчики протоколов переводят один и тот же *connect.Error в формат своего провода. Отсюда три практических вывода. Первый: версии схем эволюционируют независимо от протоколов — совместимость живёт в protobuf-поле за полем. Второй: метрики и логи на уровне HTTP стоит снимать с Content-Type — вы увидите, каким протоколом реально пользуются, и увидите, что gRPC-клиентов у вашего Connect-сервера может не оказаться вовсе. Третий: переезд клиента с gRPC на протокол Connect — это строка в его конфигурации, а не серверная эпопея: handler принял бы его завтра без деплоя.

Последний кирпич — маршрутизация. Путь каждого вызова — это строка /package.Service/Method из схемы, и регистрация сервиса в ServeMux не зависит от того, каким протоколом к нему поедут: path, handler := notesv1connect.NewNoteServiceHandler(&notesServer{}); mux.Handle(path, handler). Хотите второй сервис — второй mux.Handle рядом, как мы делали с ElizaService в третьем уроке; пути не пересекаются, потому что включают полное имя сервиса. Важно понять уровень, на котором развилка: mux различает сервисы по пути, а handler внутри одного сервиса различает протоколы по Content-Type — два независимых измерения маршрутизации, и каждое решается своим механизмом. Поэтому «три обработчика на одном сервере» — не фигура речи: на одном порту живут все три протокола для каждого сервиса, и ни один из них не конфликтует с middleware, health-чеками и статикой, потому что всё это обычный net/http. Никакого отдельного порта «для gRPC», никакого отдельного listener-а: если вы видели такие конструкции в чистом grpc-go, здесь они не нужны — и это одна из самых недооценённых экономик курса.

Теперь вы знаете connect протоколы не понаслышке: диспетчер по Content-Type, конверты gRPC, трейлеры-в-теле gRPC-Web, честные статусы и GET-кеш протокола Connect — и понимаете, почему один handler покрывает всё это без единой настройки. Следующий урок — клиенты: как из Go-кода выбрать протокол осознанно — опции connect.WithGRPC() и connect.WithGRPCWeb(), требования к HTTP/2-транспорту, метаданные и таймауты. Дальше — ошибки в полную силу (шестой урок) и перехватчики (седьмой), которые видят протокол вызова через req.Spec(). Программа всех двадцати пяти уроков — на странице курса. Домашняя работа урока: прогнать три вызова GetNote из этого урока — curl-ом, grpcurl-ом и браузерным fetch с application/grpc-web+proto — и записать в заметки, чем отличаются ответы на уровне статусов; это войдёт в ваш тестовый арсенал проекта.