Interceptors

Интерсептор в Connect — это интерфейс из трёх методов, и он один на все случаи: WrapUnary оборачивает обычный вызов «запрос — ответ», WrapStreamingClient — стриминговые вызовы на клиенте, WrapStreamingHandler — стриминговые вызовы на сервере. Выглядит он так: WrapUnary(UnaryFunc) UnaryFunc, где UnaryFunc — это функция вида func(ctx, AnyRequest) (AnyResponse, error), а AnyRequest и AnyResponse — интерфейсные типы пакета connect, под которыми скрывается любое сообщение. Интерсептор написан один раз для всех методов всех сервисов, а конкретный тип сообщения он достаёт приведением req.Any().(*notesv1.GetNoteRequest), если ему это нужно. Самая ценная деталь — req.Spec(): небольшой объект с полями Procedure (путь процедуры вида /notes.v1.NoteService/GetNote) и StreamType (тип вызова: unary или стрим). Это значит, что перехватчик знает, какой именно метод вызывается, — и может логировать, метрики ставить, авторизацию дифференцировать по процедурам. Хелпер connect.UnaryInterceptorFunc экономит для unary-случая черновую работу: принимает вашу функцию вида func(next UnaryFunc) UnaryFunc и возвращает готовый Interceptor, у которого стриминговые методы — pass-through. Когда дойдёт до стриминга, допишете остальные два метода — обёртки симметричны, и в уроке про стриминг мы это сделаем. Пока же всё, что вы видели в middleware-мире Gin и Echo, переносится сюда с поправкой на типы.

Подключение на сервере — одна опция в конструкторе, который вы уже знаете по третьему уроку. path, handler := notesv1connect.NewNoteServiceHandler(&notesServer{}, connect.WithInterceptors(logInterceptor())) — и теперь каждая процедура NoteService проходит через лог. Порядок в списке имеет смысл: connect.WithInterceptors(a, b, c) оборачивает вызов так, что a — внешний слой, b — средний, c — внутренний; на пути запроса первым срабатывает a, последним — c, а на пути ответа наоборот. Простое правило для запоминания: перечисление читается как луковица, первый — самый внешний слой. Это тот же порядок, к которому вы привыкли в цепочках grpc.ChainUnaryInterceptor и в middleware-стеках фреймворков. Практические следствия: авторизацию ставьте раньше логирования, если лог должен видеть уже аутентифицированного пользователя, но позже, если важно логировать и отклонённые запросы — порядок выражает намерение, и его стоит комментировать в коде. Интерсепторы применяются ко всем процедурам хендлера сразу — на один вызов NewNoteServiceHandler можно повесить всю цепочку сквозной логики. Заметьте, что интерсепторы видят и запрос, и ответ, включая заголовки: серверный перехватчик может добавить заголовок в ответ через res.Header().Set — это часто нужно для версионирования API или трассировки.

Первая сюрпризная деталь для тех, кто вырос на gRPC: в gRPC перехватчики для клиента и сервера — разные миры (UnaryClientInterceptor и UnaryServerInterceptor, разные сигнатуры), а в Connect это один и тот же интерфейс Interceptor, который можно подключить и туда, и туда. Клиентское подключение выглядит зеркально: notesv1connect.NewNoteServiceClient(http.DefaultClient, url, connect.WithInterceptors(authInterceptor{})). Зачем это нужно на клиенте? Классика — авторизация: клиентский интерсептор навешивает токен на каждый исходящий запрос в одном месте, и ни один вызов в кодовой базе не забудет Authorization. Вторая классика — трассировка и метрики: проставить trace-заголовки, посчитать исходящие вызовы. Третья — ретраи с backoff: перехватчик, который перехватывает неудачи кода unavailable и повторяет вызов с паузой; библиотека сознательно не делает ретраи по умолчанию, потому что политика повторов — слишком контекстная вещь. На клиенте порядок той же луковицы: первый в списке — внешний, первым видит исходящий запрос. И заметьте элегантность: у нас уже был ответ на вопрос «как передать заголовки в unary-вызов» — в пятом уроке мы обещали, что это сделает перехватчик. Вот он, момент исполнения: клиентский auth interceptor — это ровно тот механизм, которым сгенерированный клиент вкладывает метаданные в каждый вызов.

Теперь серверная сторона авторизации — самый частый запрос к перехватчикам в реальных проектах. Схема двухходовая. Ход первый — проверка: интерсептор достаёт заголовок Authorization через req.Header().Get, валидирует токен (для JWT — подпись и срок, мы строили такую проверку в курсах Gin и Echo), и на провал отвечает connect.NewError(connect.CodeUnauthenticated, ...) — ровно тот код и тот HTTP 401, что мы разобрали в уроке про ошибки. Ход второй — передача личности дальше: кто авторизовался, хендлеру надо знать. Идиома Go — контекст: интерсептор создаёт новый контекст через context.WithValue с закрытым (нестроковым) ключом и кладёт туда claims, а хендлер достаёт их через маленький типизированный хелпер вида UserFromContext(ctx). Строковые ключи в WithValue — чреватые коллизиями грабли, о которых предупреждает сама документация пакета context; закрытый тип key из вашего пакета снимает вопрос. Заметьте, что это тот же паттерн, который вы строили в gRPC-мире — только там проверка жила в grpc.UnaryInterceptor и metadata.FromIncomingContext, здесь — в connect-интерсепторе и req.Header(). Тонкая деталь: интерсептор обязан вернуть новый контекст — next(ctx, req) со старым ctx потеряет claims по дороге. И вторая: если у вас есть процедуры, которым авторизация не нужна (health-чеки), интерсептор может ветвиться по req.Spec().Procedure — whitelist живёт в одном месте, а не размазан по хендлерам.

Вопрос, который вы обязаны себе задать: зачем ещё один механизм, если в мире net/http есть middleware? Ответ не «либо-либо», а карта территории. Middleware работает на уровне HTTP-запроса: видит http.ResponseWriter и *http.Request, не знает ни процедур, ни сообщений, и живёт только на серверной стороне. Интерсептор работает на уровне RPC: знает процедуру через Spec, видит message-типы, работает и на сервере, и на клиенте, и умеет в стриминг через отдельные методы. Отсюда раскладка. На middleware — то, что про HTTP как таковой: TLS-редиректы, сжатие, CORS, восстановление после паник, общий лимит соединений. На интерсепторы — то, что про вызовы: логирование процедур, метрики по методам, авторизация по токенам, ретраи и трассировка на клиенте. Два инструмента прекрасно живут вместе: handler, который вернул NewNoteServiceHandler, — обычный http.Handler, и его можно обернуть в любую цепочку chi или Echo middleware — в уроке про интеграцию с фреймворками мы это и сделаем. Тонкость про паники: middleware с recover защитит сервер от падения, но интерсептор — правильное место, чтобы превратить панику в код internal на конкретном вызове. И ещё наблюдение из практики: лог-строка интерсептора с процедурой и кодом почти всегда полезнее лог-строки middleware с путём и статусом — потому что путь у RPC один на все методы сервиса.

Две вещи, которые стоит знать про перехватчики, чтобы не изобретать велосипеды. Первая — экосистема: официальные пакеты Connect дают готовые интерсепторы для типовых задач. Самый ходовой — connectrpc.com/otelconnect: интерсептор OpenTelemetry, который расставляет трейсы и метрики на каждый вызов с процедурой в атрибутах, и подключается одной опцией WithInterceptors(otelconnect.NewInterceptor()) — к серверу или клиенту, без разницы. Придёт время мониторинга (семнадцатый урок) — начнёте с него, а не с самописного. Вторая — стриминг. Всё, что мы написали, касалось unary-вызовов; для стриминговых у интерфейса есть методы WrapStreamingClient и WrapStreamingHandler, а вместо request-объекта там streaming-соединение со своими RequestHeader и Spec. Структура та же — до next, next, после next, — но цикл сообщений добавляет нюансы: логирующий интерсептор на стриме считает не один вызов, а поток сообщений, и метрики там размечаются иначе. Это тема восьмого урока, где стриминг разберём целиком: типы Stream, Send/Receive, и вот эти самые перехватчики на живом примере. Пока зафиксируйте правило: если ваш сервис обещает поддерживать стриминг, у каждого Interceptor должны быть реализованы все три метода — хотя бы pass-through, как в примере с авторизацией.

Сквозная логика заняла своё место: логирование с процедурами, авторизация через контекст, метрики — всё в перехватчиках, подключаемых одной опцией. Следующий урок — стриминг: ServerStreaming, ClientStreaming и Bidi через connect.Stream, перехватчики для потоков и то, как ошибки и таймауты ведут себя, когда ответов много. После стриминга выйдем в браузер — TypeScript-клиенты из девятого урока, — затем в тулчейн buf: линт, breaking changes и кодогенерация из десятого и одиннадцатого. Программа всех двадцати пяти уроков — на странице курса. Для сравнения полезно держать в голове, как перехватчики устроены в gRPC: их разбор с цепочками и контекстом мы делали в уроке про gRPC-interceptors — положите рядом, и вы увидите, что Connect свёл два разных типа в один интерфейс, а всё остальное — порядок, контекст, авторизация — вы уже умеете.