gRPC API

GrpcTransport — асинхронный Python-клиент CodeGraph для запущенного gRPC-сервера GoCPG. Он возвращает те же Pydantic-модели, что и subprocess-транспорт. Здесь описана граница клиента, а wire-схема не копируется вручную: её канонический источник — protobuf-файлы.

Канонические сервисы

Сгенерированные Python-stub находятся в src/services/gocpg/proto/gocpg/v1/. Поддерживаемый клиент разделён между src/services/gocpg/runtime/grpc_transport.py и соседними mixin-файлами grpc_transport_*.py.

Настройка соединения

Размер отправляемого и принимаемого сообщения ограничен 64 MiB. Без grpc_tls_cert клиент использует grpc.aio.insecure_channel, поэтому такой режим допустим только внутри уже защищённой границы. Сертификат включает TLS с проверкой сервера, но не настраивает клиентский сертификат.

Группы операций

• parse, update, ci_update и create_indexes создают или обновляют DuckDB CPG. Parse и update читают server stream и передают прогресс в настроенный callback.
• query, stats, quality_stats, а также методы frontend, веток и подмодулей используют QueryService.
• search, scan и validate_rule используют PatternService; scan работает потоково.
• nav_symbols, nav_callers, nav_callees, nav_hierarchy, nav_outline, nav_usages, nav_deps и nav_resolve используют NavigationService.
• lifecycle_status вызывает GetDatabaseStatus, watch_database_status — WatchDatabaseStatus; freshness, обслуживание и plan_refresh используют соответствующие lifecycle RPC, включая PlanRefresh.

Типизированный вход определяйте по сигнатуре Python-метода, wire-контракт — по protobuf. Не восстанавливайте поля запроса из старой опубликованной версии этой страницы.

Пути и дедлайны

Для операций с базой требуется явный db_path или соответствующее поле типизированного запроса. Пути к исходникам, репозиторию, output и базе нормализуются до абсолютных перед RPC. Сервер GoCPG должен видеть эти пути в своём runtime-контексте: локальный путь клиента не монтируется на удалённый сервер автоматически.

Транспорт задаёт разные дедлайны для разных операций: parse — 3600 секунд; update и CI update — 600; создание индексов и обслуживание — 300; query и pattern обычно — 60; navigation и одиночные status-запросы обычно — 30; наблюдение за статусом — 60. При необходимости передавайте ограниченный timeout, предусмотренный типизированным методом.

Обработка сбоев

Статус DEADLINE_EXCEEDED преобразуется в GoCPGTimeoutError. Остальные gRPC-статусы — в GoCPGProcessError с именем статуса и деталями сервера. Если поток parse или update завершился без итогового результата клиент возвращает ограниченную модель на основе запрошенного output; наличие ожидаемого графа проверяйте отдельной health- или metadata-операцией.

Если сервер недоступен, сначала проверьте хост, порт, цепочку доверия и bearer metadata. Перед повтором длительного parse выполните лёгкую health- или metadata-операцию. Не отключайте TLS и не убирайте API key, чтобы скрыть ошибку сертификата или авторизации.

Граница безопасности

Транспорт умеет передать API key и проверить сертификат сервера, но не определяет tenant- авторизацию и владельца пути. Храните секреты вне исходников, ограничивайте файловые права сервера и открывайте plaintext insecure_channel только внутри защищённой локальной сети.

db_path здесь относится к Python gRPC-клиенту. Он не разрешает передавать пути хранилища в agent-facing MCP-вызовы: там хранилище определяется из контекста проекта и runtime.

Источники истины

• src/services/gocpg/runtime/grpc_transport.py — канал и основные CPG-операции.
• src/services/gocpg/runtime/grpc_transport_query.py — query- и metadata-методы.
• src/services/gocpg/runtime/grpc_transport_pattern.py — pattern-методы.
• src/services/gocpg/runtime/grpc_transport_navigation.py — navigation-методы.
• src/services/gocpg/runtime/grpc_transport_lifecycle.py — lifecycle- и refresh-методы.
• src/services/gocpg/runtime/grpc_transport_errors.py — стабильное преобразование ошибок.
• gocpg/api/proto/gocpg/v1/ — авторитетные protobuf-контракты сервисов и сообщений.