Браузерные клиенты (TypeScript)

Схема одна — clients разные. К notes и eliza мы уже генерировали Go-код; теперь добавляем TypeScript. Плагин называется @bufbuild/protoc-gen-es и описывается в buf.gen.yaml, который вы заводили во втором уроке: секция plugins получает ещё одну запись, local: protoc-gen-es, с выходом в каталог src/gen и опцией target=ts. Никакого нового файла схемы не нужно — eliza.proto и notes.proto используются как есть, и это принципиальный плюс proto-first: контракт один, а артефактов два. Плагин выпишет по каждому message класс с полями, методами fromJson и toJson, плюс по каждому сервису — объект ElizaService, который в TypeScript-мире играет роль пути и метаданных: из него createClient построит типизированный клиент. Заметьте симметрию с Go: там был пакет notesv1 с типами и notesv1connect с RPC-слоем, здесь всё живёт в одном сгенерированном модуле, но деление то же самое — данные и транспорт. Версии пакетов в npm — @bufbuild/protobuf и @connectrpc/connect-web — держите согласованно: они развиваются парой, и рассинхрон рантайма с генератором даёт самые невнятные ошибки типов.

В Go клиенту нужен был http.Client — в браузере его роль играет fetch-транспорт. createConnectTransport({ baseUrl: 'http://localhost:8080' }) создаёт объект транспорта, который ходит собственным протоколом Connect: Content-Type application/json или application/proto, пути вида /connectrpc.eliza.v1.ElizaService/Say, HTTP-статусы по таблице кодов — всё это вы уже разбирали в уроке про протоколы. Есть и второй конструктор — createGrpcWebTransport: тот же клиентский API, но на проводе протокол gRPC-Web с его фреймингом и статусами в трейлерах-заголовках; он нужен, когда бэкенд — классический gRPC-сервер, прикрытый Envoy, или сервер Connect, к которому идёт деплой с gRPC-Web-совместимостью. Выбор транспорта — единственное место, где фронтенд знает о проводе; сам клиент от него не зависит. Транспорт fetch-овой природы означает и все стандартные следствия: куки и заголовки браузер ставит сам, redirect'ы и кеширование работают как в обычных fetch-вызовах, а GET-запросы для процедур с idempotency_level = NO_SIDE_EFFECTS — тот самый GET-кеш из четвёртого урока — кешируются браузерной инфраструктурой по-настоящему.

Фронтенд живёт на другом origin — и тут в игру входит CORS, политика браузера, которой не существовало в Go-мире из предыдущих уроков. Первый запрос к серверу с чужого origin браузер отправляет не сразу: увидев, что Content-Type — application/json (не простое значение), а значит, запрос не «simple», он сначала шлёт preflight — OPTIONS-запрос с заголовками Access-Control-Request-Method и Access-Control-Request-Headers. Сервер обязан ответить набором Access-Control-Allow-*: origin фронта, методами POST и GET (GET — ради кешируемых процедур), и перечислить разрешённые заголовки: Content-Type плюс клиентские — Connect-Timeout-Ms, Grpc-Timeout, X-User-Agent. Забудете перечислить хоть один — preflight не пройдёт, и браузер даже не попробует отправить настоящий запрос, а в консоли появится знаменитая «CORS policy» ошибка. Для gRPC-Web-транспорта добавляются X-Grpc-Web и expose-заголовки Grpc-Status и Grpc-Message — код ошибки приходит именно в них, и без Access-Control-Expose-Headers клиент увидит сеть сработала, а не реальный код. Сам CORS настраивается один раз в main вашего Go-сервера — веткой на OPTIONS или middleware; дальше все уроки про безопасность и деплой раскрутят тему глубже.

Теперь ошибки — и здесь всё до неприличия знакомо. Пойманный в catch объект имеет тип ConnectError из @connectrpc/connect, и его поля — это проекция *connect.Error из Go-урока: code — строковое имя кода (not_found, unauthenticated, unavailable), rawMessage — сообщение, а metadata — заголовки-метаданные вызова. Код, который сервер вернул через connect.NewError(CodeNotFound, ...), фронтенд увидит как err.code === CodeNotFound — таблица HTTP-маппинга из урока про ошибки остаётся вашим картой и в TS. Практика фронтенда добавляет один нюанс: браузерный клиент не отличает сетевые сбои от серверных отказов без кода — на упавший fetch или отказ preflight придёт ConnectError с кодом unknown, и UI должен решать, показывать ли пользователю retry. Для перехватчиков всё симметрично седьмому уроку: транспорт принимает interceptors — функции (next) => (req) => {...}, где req.header.set навешивает Authorization на каждый запрос, а next пропускает вызов дальше. Стек тот же: один auth-перехватчик на транспорте — и ни один вызов не забудет токен.

Восьмой урок научил циклу Receive с io.EOF на Go; в TypeScript-мире та же идея выражена идиоматичнее — асинхронными итераторами. Server streaming вызов возвращает AsyncIterable, и чтение потока — это for await: for await (const res of client.introduce({})) { render(res) } — цикл сам завершится, когда сервер закроет поток, а ошибка в середине прилетит исключением из цикла. Никаких ручных проверок EOF: конструкция for await спрятала внутри ровно ту семантику, которую мы разбирали в Go, — сигналом конца служит нормальное завершение итератора, а io.EOF превратился в отсутствие следующего элемента. Bidi-вызов возвращает объект с двумя полями: requests — источник, куда вы пишете свои сообщения, и responses — итератор ответов сервера. Полудуплексы из восьмого урока на месте: requests.send шлёт реплику, requests.complete закрывает вашу половину — аналог CloseRequest. Под капотом остаётся тот же фрейминг, что и в Go: каждое сообщение — отдельный фрейм в теле ответа. Стриминговые вызовы в браузере требуют Connect- или gRPC-Web-протокола — и напомним: bidi по-прежнему только на HTTP/2, ограничение протокола не отменялось.

Круг из первого урока замкнут: фронтенд на TypeScript говорит с Go-сервером напрямую — тот же контракт, те же коды, тот же фрейминг. Фронтенд-стек связан с сервером одним артефактом — схемой, и именно схеме теперь нужна охрана: в десятом уроке берём в руки buf lint и buf breaking — линт протофайлов, категории правил, конфиг buf.yaml и проверку breaking changes в CI, чтобы эволюция контракта не ломала ни Go-сервер, ни TS-клиент. Для контекста полезно вспомнить, как та же задача решалась в gRPC-мире с проксированием — об этом был урок про Envoy и gRPC-Web в курсе gRPC: Connect снимает половину этой инфраструктуры. Программа всех двадцати пяти уроков — на странице курса.