GRPC API

Используйте gRPC, чтобы обращаться к постоянно работающему серверу GoCPG: получать статистику графа, выполнять SQL-запросы, искать символы и обновлять CPG. GrpcTransport — асинхронный Python-клиент CodeGraph для этих операций. Он возвращает типизированные Pydantic-модели результатов.

Справочник предназначен для разработчиков интеграций. Здесь описаны настройка соединения, пример чтения статистики, группы операций и обработка ошибок. Формат сообщений и сигнатуры удалённых вызовов определены в protobuf-файлах.

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

Сгенерированные Python-классы для удалённых вызовов находятся в src/services/gocpg/proto/gocpg/v1/. Для примера ниже импортируйте готовый клиент GrpcTransport из src.services.gocpg.

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

Передайте настройки как объект в GrpcTransport(config=connection_config). Клиент читает из него атрибуты grpc_host, grpc_port, grpc_api_key и grpc_tls_cert; отсутствующие атрибуты получают значения из таблицы. Например, объект SimpleNamespace из Python-модуля types позволяет задать эти атрибуты без отдельного класса конфигурации. Путь grpc_tls_cert указывает на PEM-файл корневого сертификата в файловой системе клиента. Для локального соединения с настройками по умолчанию используйте GrpcTransport(), как в примере ниже.

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

Получение статистики графа

Подготовьте Python-окружение по руководству установки. Выполните пример из корня репозитория CodeGraph с активированным окружением. Нужен gRPC-сервер GoCPG, которому доступен выбранный CPG. По умолчанию пример подключается к localhost:50051. Для другого адреса задайте CODEGRAPH_GRPC_HOST и CODEGRAPH_GRPC_PORT в терминале. Для защищённого соединения укажите путь к корневому CA в CODEGRAPH_GRPC_TLS_CERT и настроенный ключ API в CODEGRAPH_GRPC_API_KEY. Эти переменные читает код примера и передаёт значения клиенту; он не загружает настройки из config.yaml.

Сохраните следующий код в grpc_example.py:

import asyncio
import os
from types import SimpleNamespace

from src.services.gocpg import GrpcTransport


async def main():
    connection = SimpleNamespace(
        grpc_host=os.environ.get("CODEGRAPH_GRPC_HOST", "localhost"),
        grpc_port=int(os.environ.get("CODEGRAPH_GRPC_PORT", "50051")),
        grpc_api_key=os.environ.get("CODEGRAPH_GRPC_API_KEY"),
        grpc_tls_cert=os.environ.get("CODEGRAPH_GRPC_TLS_CERT"),
    )
    transport = GrpcTransport(config=connection)
    try:
        result = await transport.stats(os.environ["CODEGRAPH_CPG_PATH"], timeout=30)
        print(result.total_nodes, result.total_edges)
    finally:
        await transport.close()


asyncio.run(main())

Задайте абсолютный путь к существующему CPG и запустите файл в Bash:

export CODEGRAPH_CPG_PATH="<absolute-cpg-path>"
python grpc_example.py

Программа выводит два целых числа: количество узлов и рёбер графа. Значения зависят от выбранного графа. Метод stats возвращает GoCPGStatsResult; поля methods, calls, files и tables дают более подробную статистику. Блок finally закрывает канал после успешного вызова или ошибки.

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

• parse, update, ci_update и create_indexes создают или обновляют DuckDB CPG. Parse и update читают поток сообщений сервера и передают прогресс в настроенную функцию обратного вызова.
• 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 или соответствующее поле типизированного запроса. Пути к исходникам, репозиторию, результату и базе нормализуются до абсолютных перед RPC. Сервер GoCPG должен видеть эти пути в своей среде выполнения: локальный путь клиента не монтируется на удалённый сервер автоматически.

Транспорт задаёт следующие сроки ожидания по умолчанию, в секундах:

• parse: 3600.
• update и ci_update: 600.
• create_indexes, scan и run_maintenance: 300.
• query, stats, quality_stats и search: 60.
• validate_rule, методы навигации, одиночные lifecycle-вызовы и plan_refresh: 30.
• watch_database_status: 60.

Чтобы изменить срок ожидания, задайте timeout в аргументах метода или в его типизированном запросе.

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

Статус DEADLINE_EXCEEDED преобразуется в GoCPGTimeoutError. Для parse статус FAILED_PRECONDITION с деталями empty_scope преобразуется в EmptyAuditScopeError: выбранная область не содержит исходников для разбора. Остальные gRPC-статусы преобразуются в GoCPGProcessError с именем статуса и деталями сервера. Если поток parse или update завершился без итогового результата, клиент может вернуть модель на основе запрошенного пути результата. Проверьте содержимое графа и данные о его происхождении, чтобы определить результат операции. При разборе с явно заданной политикой области аудита отсутствие итогового результата вызывает ValueError: audit_scope_invalid_provenance: terminal parse result missing. Запрос состояния показывает доступность сервера; содержимое и происхождение графа показывают, какие данные доступны для анализа.

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

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

Транспорт передаёт настроенный ключ API в метаданных авторизации и проверяет сертификат сервера по заданному корневому CA. Храните секреты в доверенном хранилище и ограничивайте файловые права сервера нужными путями. Используйте незашифрованный insecure_channel внутри защищённой локальной сети.

Python gRPC-клиент получает путь к базе через db_path. В MCP-вызовах агента хранилище определяется из контекста проекта и среды выполнения.

Справка и диагностика

Руководство установки описывает подготовку окружения CodeGraph и GoCPG. Руководство по диагностике поможет проверить конфигурацию и восстановить подключение. Контракты сообщений и удалённых вызовов указаны в таблице сервисов выше.