gRPC

1. Роль протокола в проекте

gRPC поддерживается как третий основной протокол платформы в управляемой форме. Цель состоит не в том, чтобы покрыть все возможности gRPC, а в том, чтобы представить unary и bounded server-streaming методы как MCP tools с предсказуемым жизненным циклом.

2. Что поддерживается в MVP

unary RPC
bounded server-streaming через execution modes window, session, async_job
загрузка .proto
загрузка descriptor set
загрузка примеров JSON для MCP input/output при необходимости
извлечение services, methods, request/response messages
отображение входных и выходных параметров в UI
mapping MCP input -> protobuf request
mapping protobuf response -> MCP output
автогенерация чернового mapping
ручная донастройка через JSONPath
вызов метода по descriptor metadata
auth/transport settings на уровне соединения
тестовый вызов перед публикацией

3. Что не входит в MVP

client streaming
bidirectional streaming
обязательная поддержка server reflection
генерация нового Rust-кода под каждый загруженный .proto
сложные сценарии с долгоживущими сессиями вызовов

4. Ключевое архитектурное ограничение

В проекте поддерживаются unary-методы и bounded server-streaming, потому что MCP tool в этой архитектуре должен оставаться управляемым.

Это означает:

один request message;
один bounded response или управляемая session/job-семантика;
явно ограниченный lifecycle stream-сессии.

Streaming gRPC не публикуется как бесконечный raw stream. Он допускается только там, где runtime умеет bounded-ить, агрегировать и завершать результат.

5. Внутренняя модель gRPC operation

gRPC operation должна включать:

server_addr
package
service
method
descriptor_ref
descriptor_set_b64
input_schema
output_schema
input_mapping
output_mapping
execution_config
tool_description

6. Как оператор настраивает gRPC operation

Загружает .proto или descriptor set.
Система извлекает список services и methods.
Оператор выбирает конкретный unary- или server-streaming метод.
UI показывает структуру request message и response message.
При необходимости загружает примеры JSON для MCP input/output.
Система строит черновую схему, стартовый mapping и runtime-ready snapshot descriptor set для выбранного метода.
Оператор задает или уточняет входные MCP-параметры.
Настраивает маппинг во входные protobuf fields.
Настраивает маппинг из response fields в MCP output.
При необходимости уточняет mapping через JSONPath.
Выполняет тест.
Публикует operation как MCP tool.

7. Поведение runtime

При выполнении gRPC operation runtime должен:

Валидировать MCP input по нормализованной схеме.
Применить input mapping.
Построить protobuf request message из JSON.
Для unary выполнить unary RPC вызов.
Для server-streaming собрать bounded окно или session step.
Преобразовать protobuf response или stream items в нормализованный JSON.
Применить output mapping.
Вернуть итоговый результат.

8. Критические нюансы

.proto и descriptor handling должны быть отделены от runtime-вызова;
protobuf discovery не должен жить внутри gRPC adapter;
runtime использует сохраненный descriptor_set_b64, а не исходный .proto;
oneof, enum, repeated, map и well-known types требуют отдельной нормализации;
map на слое нормализованной schema модели представляется как array объектов вида { key, value };
oneof на слое нормализованной schema модели представляется как oneof с вариантами-объектами, каждый из которых содержит одно допустимое поле;
схема сообщения должна быть представлена в UI как обычная форма полей, а не как сырой protobuf descriptor;
пользователь не должен видеть внутреннюю сложность protobuf-контракта больше, чем это нужно для настройки operation.
JSONPath используется как единый способ точечной адресации вложенных полей при настройке mapping поверх нормализованной JSON-модели.

9. Почему gRPC ограничивается controlled streaming

Причина не только в сложности реализации. Главное ограничение архитектурное:

MCP tool моделируется как завершенный вызов;
LLM работает с запросом и конечным ответом;
UI платформы построен вокруг формы входа и формы выхода;
streaming требует отдельной session-модели, buffering, cancellation и состояния.

Поэтому поддержка gRPC в Crank ограничивается unary и bounded server-streaming. Client-streaming и bidi остаются вне scope до появления полноценной interactive session model.

6.6 KiB Raw Blame History Unescape Escape