# gRPC

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

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

## 2. Что поддерживается в целевом продукте

- 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. Что отложено

- `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

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

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

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

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

## 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.
