BSR: Buf Schema Registry

Модуль — это набор протофайлов, публикуемый под именем вида buf.build/acme/notes: владелец (пользователь или организация) плюс название. Модуль в buf.yaml v2 получает имя прямо в записи секции modules — поле name рядом со знакомым path. Имя — это одновременно и адрес в реестре, и часть пути импорта для потребителей: чужая схема обращается к вашей через import с путём внутри модуля, ровно как ваши eliza и notes живут в одном модуле и видят друг друга. Важно не путать модуль с репозиторием: один git-репозиторий может содержать несколько модулей (в v2 они перечисляются в modules списком), и наоборот — модуль можно публиковать из любого CI. Наш проект из курса — один модуль path: proto из второго урока, и чтобы выйти в реестр, ему нужно только имя. Хорошая новость для существующих проектов: добавление имени — обратимо и не ломает локальную работу, buf lint и buf generate продолжают работать точно так же, просто появляется возможность публикации. Если вы публиковали пакеты в npm или crates.io — механика владельца и имени покажется знакомой до звона.

Публикация — одна команда: buf push отправляет текущее состояние модуля в реестр и создаёт коммит. Коммит BSR — это неизменяемый снимок всех схем модуля с дайджестом; редактировать историю нельзя, только добавлять новые коммиты — git-модель без force push. На коммиты указывают метки (labels): метка main двигается на каждый push и всегда указывает на свежую версию, а метки вида v1.0.0, v1.0.1 вы ставите сами — это ваши semantic-версии. Потребитель пинируется на метку и получает предсказуемую схему, пока вы её не подвинете. Реквизиты доступа buf берёт из окружения: buf registry login записывает токен в конфиг локальной машины, а в CI токен передаётся переменной BUF_TOKEN из секретов — об этом ниже. Первому push-у обычно предшествует автоматическая проверка: buf lint и buf breaking против main — публиковать нелинтованную схему значит раздавать её грязь всем потребителям. В реестре у модуля появляется страница: документация из комментариев протофайлов, дерево пакетов, история коммитов и граф зависимостей — то, что в npm-мире вы видели на странице пакета. Замечу и типовую ошибку новичков: метки — не ветки. Метка указывает на один коммит и сдвигается или нет; ветвистую историю версий в protobuf-мире не строят — для несовместимых изменений заводят новую версию пакета notes.v2, как вы проходили в десятом уроке.

Второй дар реестра — зависимости. Схема перестаёт быть островом: импортируйте типы из чужих модулей, и buf сам подтянет их из реестра при сборке. Классический кейс — buf.build/googleapis/googleapis, курируемый (curated) модуль с аннотациями Google: вы уже слышали о нём в контексте REST-совместимости — опции google.api.http, которыми grpc-gateway описывает REST-маршруты, живут именно там. Подключение двухшаговое: перечислить модуль в секции deps вашего buf.yaml, затем buf dep update — buf разрешит зависимости, скачает их в локальный кеш и запишет buf.lock. Файл buf.lock — это ваш package-lock.json: он фиксирует дайджесты (криптографические отпечатки) конкретных версий каждой зависимости, и его коммитят вместе с buf.yaml — сборка становится воспроизводимой: у всех разработчиков и в CI одни и те же байты чужих схем, даже если владелец зависимости выпустил новый коммит. Обновление — сознательный шаг: buf dep update пересматривает зафиксированные версии (в v2 можно ограничить диапазон, например только патчи), diff buf.lock идёт в ревью как любой настоящий апдейт зависимостей. И обратите внимание: зависимости — это тоже модули со своими метками, поэтому пинирование работает одинаково и для ваших зависимостей, и для ваших потребителей.

Не всякую схему хочется светить: контракты коммерческого API, внутренние протоколы, схемы с бизнес-логикой в именах полей. BSR закрывает это полем visibility у модуля: public — модуль виден всем (значение по умолчанию), private — доступ только владельцу и приглашённым участникам организации. Доступ к приватным модулям и публикация вообще — по токенам: buf registry login создаёт и сохраняет токен локально, а для автоматизации токен передаётся переменной BUF_TOKEN: buf читает её из окружения и никогда не требует аргументов с секретом. Отсюда железное правило CI: BUF_TOKEN живёт в секретах пайплайна (GitHub Actions secrets, GitLab CI variables) и подставляется в шаги, где buf ходит в реестр — buf dep update, buf generate с удалёнными входами, buf push. Класть токен в buf.yaml, go.mod или код — нельзя: конфиги едут в репозиторий, а токен — это ключ к вашим схемам. Организационная механика тоже на месте: в BSR можно завести организацию, пригласить команду и раздавать права на модули — тонкая настройка ролей у Buf платная, но базовая приватность публичной учетной записи хватает для учебного и пет-проектного цикла. Токены отзываются и перевыпускаются — ротация секрета в CI делается без деплоя кода.

Третий дар реестра — сгенерированный код как сервис. BSR умеет сам прогонять плагины по вашим схемам и публиковать готовые SDK: Go-модули в собственном прокси buf.build/gen/go и npm-пакеты для TypeScript. Потребителю не нужен ни buf, ни плагины — обычный go get по адресу вида buf.build/gen/go/acme/notes/protocolbuffers/go (message-типы) и buf.build/gen/go/acme/notes/bufbuild/connect-go (Connect-слой с клиентами) — в разговорной речи такой набор называют bsr go SDK. Импорты в коде честные Go-пути: notesv1 из protocolbuffers-ветки и notesv1connect из bufbuild/connect-go ветки — те же пакеты, которые вы генерировали локально, только с путём реестра. Для TypeScript — npm-пакет @buf/acme_notes.notes.v1 с теми же модулями, что делал protoc-gen-es из девятого урока. Когда это выбирать: внешним потребителям API, у которых нет buf и не должно быть; мобильным и фронтенд-командам, которые хотят просто npm install. Когда нет: внутри команды, где buf уже стоит, локальная генерация из deps даёт больше контроля — вы управляете версиями плагинов и не ждёте, пока SDK реестра прогонится. Версии SDK следуют коммитам и меткам модуля, так что пинирование потребителя работает так же, как для схем.

Соберём конвейер, который намечался в десятом уроке. Там вы ставили buf breaking --against '.git#branch=main' — сравнение с веткой собственного репозитория. С реестром появляется более честный эталон: buf breaking --against buf.build/acme/notes — сравнение с последней опубликованной версией модуля. Разница принципиальна: main может уйти вперёд от того, что реально скачали потребители, — коммиты в ветке ещё не релиз. Проверка против реестра отвечает на единственный правильный вопрос: сломает ли следующий push тех, кто уже живёт на v1.0.1? Полный цикл релиза выглядит так: PR проходит lint и breaking против main (дисциплина разработки), перед публикацией — breaking против published-версии (дисциплина релиза), затем buf push с меткой. И несовместимые изменения перестают быть проблемой: вы выпускаете notes.v2 рядом с notes.v1 — оба пакета живут в модуле параллельно, потребители переезжают по своему графику, а buf breaking молчит, потому что каждый пакет эволюционирует внутри своей версии. Так вы получаете ту же дисциплину, что проходили в уроке про версионирование gRPC, но с механикой, которая живёт в CI, а не в головах.

Конвейер схем собран целиком: buf lint охраняет стиль, buf breaking — совместимость против main и против опубликованных версий, buf generate — код, а BSR — дистрибуцию модулей, зависимостей и SDK. Схемы теперь ходят между машинами и командами — а значит, встаёт вопрос, кто имеет право их вызывать и по какому проводу. В тринадцатом уроке закрываем безопасность: TLS на обычном net/http, аутентификация через интерсепторы из седьмого урока, авторизация по процедурам и ограничение протоколов. Для повторения смежного: полная форма эволюции схем — в десятом уроке, а пара ключей auth connect приведёт в раздел доков Connect, откуда начинается боевой стек безопасности. Программа всех двадцати пяти уроков — на странице курса.