# Streaming UI Contract

## 1. Назначение документа

Этот документ фиксирует точный UI-контракт для настройки потоковых операций.

Цель:

- определить экраны и блоки wizard;
- перечислить все поля;
- перечислить валидации;
- определить protocol-specific visibility rules;
- зафиксировать UX states, warnings и system messages.

## 2. Основные экраны

Потоковая конфигурация живет в:

- `Operations Wizard`
- `Operation Detail`
- `Test Run`
- `Agent Tool Preview`
- `Logs` / `Usage` observability surfaces

Дополнительно админские страницы:

- `Stream Sessions`
- `Async Jobs`

## 3. Wizard information architecture

## 3.1. Shared wizard structure

Шаги:

1. `Protocol`
2. `Upstream`
3. `Request / Subscription`
4. `Execution Mode`
5. `Input Schema`
6. `Output / Aggregation`
7. `Safety and Limits`
8. `Tool Family`
9. `Test Run`
10. `Publish`

## 3.2. Step `Execution Mode`

Поля:

- `Mode`
  - `Unary`
  - `Window`
  - `Session`
  - `Async Job`
- `Transport behavior`
  - `Request / response`
  - `Server stream`

Подсказки:

- `Unary` для обычных request-response integrations.
- `Window` для bounded snapshots из stream или feed.
- `Session` для follow-style tools с `start/poll/stop`.
- `Async Job` для long-running operations с `status/result/cancel`.

Валидации:

- `Transport behavior=server_stream` не может использоваться с protocol, который его не поддерживает.
- `WebSocket` не может быть `Unary`.
- `SOAP` в первой волне не может быть `Session`.

## 3.3. Step `Input Schema`

Поля:

- `Input schema source`
  - manual
  - sample-derived
  - descriptor/wsdl-derived
- `Input fields`
- `Required fields`
- `Defaults`
- `Mapping preview`

## 3.4. Step `Output / Aggregation`

Поля:

- `Aggregation mode`
  - `Raw items`
  - `Summary only`
  - `Summary + samples`
  - `Stats`
  - `Latest state`
- `Items path`
- `Summary path`
- `Cursor path`
- `Status path`
- `Done path`
- `Output mapping`

Валидации:

- `Items path` обязателен для `Raw items` и `Summary + samples`.
- `Summary path` обязателен для `Summary only`, `Summary + samples`, `Stats`, `Latest state`.
- `Done path` обязателен для `Async Job`, если upstream status не выражается отдельным field set.

## 3.5. Step `Safety and Limits`

Поля:

- `Window duration`
- `Poll interval`
- `Upstream timeout`
- `Idle timeout`
- `Session lifetime`
- `Max items`
- `Max bytes`
- `Max field length`
- `Drop duplicates`
- `Sampling rate`
- `Redacted paths`

Валидации:

- `Window duration` обязателен для `Window`.
- `Poll interval` обязателен для `Session`.
- `Idle timeout` обязателен для `Session`.
- `Session lifetime` обязателен для `Session`.
- `Max items` > 0.
- `Max bytes` > 0.
- `Sampling rate` > 0 and <= 1.

## 3.6. Step `Tool Family`

Показывается только для:

- `Session`
- `Async Job`

Для `Session`:

- `Start tool name`
- `Poll tool name`
- `Stop tool name`

Для `Async Job`:

- `Start tool name`
- `Status tool name`
- `Result tool name`
- `Cancel tool name`

Валидации:

- имена обязательны;
- имена должны быть уникальны в пределах agent;
- имена не должны конфликтовать с already bound tools.

## 4. Protocol-specific UI

## 4.1. REST

Поля:

- `Base URL`
- `HTTP method`
- `Path template`
- `Headers`
- `Query mapping`
- `Body mapping`
- `SSE enabled`
- `SSE event filter`

Visibility:

- `SSE enabled` показывается только если method/endpoint допускают stream use case;
- `Window` и `Session` доступны, если оператор включает stream behavior.

## 4.2. GraphQL

Поля:

- `Endpoint`
- `Operation type`
- `Operation name`
- `Query template`
- `Variables schema`
- `Response path`

Visibility:

- `Window`, `Session`, `Async Job` скрыты в текущей продуктовой волне;
- `Subscription` UI не показывается.

## 4.3. gRPC

Поля:

- `Server address`
- `Package`
- `Service`
- `Method`
- `Descriptor source`
- `Stream kind`
  - `Unary`
  - `Server streaming`

Visibility:

- `Window`, `Session`, `Async Job` доступны только для `Server streaming`;
- `Client streaming` и `Bidirectional` не показываются вообще.

## 4.4. WebSocket

Поля:

- `WebSocket URL`
- `Subprotocols`
- `Connect timeout`
- `Heartbeat interval`
- `Subscribe message template`
- `Unsubscribe message template`
- `Message envelope path`

Visibility:

- `Unary` не показывается;
- `Window`, `Session`, `Async Job` доступны всегда;
- `Subscribe message template` обязательно для `Window` и `Session`.

## 4.5. SOAP

Поля:

- `WSDL source`
- `Service`
- `Port`
- `Operation`
- `SOAP version`
- `SOAPAction`
- `Endpoint override`
- `Header config`

Visibility:

- `Session` скрыт;
- `Window` скрыт по умолчанию и включается только для polling-style enterprise workflows;
- `Unary` и `Async Job` доступны.

## 5. Test Run UX

## 5.1. Window

UI должен показывать:

- `Status`
- `Duration`
- `Items count`
- `Bytes count`
- `Window complete`
- `Truncated`
- `Has more`
- `Summary`
- `Items preview`
- `Cursor`

Кнопки:

- `Run window test`
- `Repeat`
- `Save config`

## 5.2. Session

UI должен показывать:

- `Session id`
- `Status`
- `Expires at`
- `Poll after`
- `Summary preview`
- `Items preview`

Кнопки:

- `Start session`
- `Poll next chunk`
- `Stop session`

## 5.3. Async Job

UI должен показывать:

- `Job id`
- `Status`
- `Progress`
- `Started at`
- `Finished at`
- `Result preview`

Кнопки:

- `Start job`
- `Refresh status`
- `Get result`
- `Cancel job`

## 6. Page-level states

Каждый streaming-aware экран обязан поддерживать:

- `idle`
- `validating`
- `saving`
- `testing`
- `running`
- `completed`
- `failed`
- `stopped`
- `expired`

## 7. Warnings and messages

## 7.1. Validation warnings

- `This mode will truncate responses above the configured byte limit.`
- `Current protocol does not support the selected execution mode.`
- `Session lifetime is shorter than idle timeout.`
- `Aggregation mode summary_only hides raw items from the final tool output.`
- `WebSocket reconnect may duplicate events if upstream does not provide cursor semantics.`
- `SOAP async mode requires a separate status/result contract.`

## 7.2. Confirmations

- `Stop current session?`
- `Cancel running job?`
- `Switching execution mode will reset protocol-specific fields.`

## 7.3. Errors

- `Streaming configuration is invalid.`
- `Test session expired.`
- `Upstream did not return any messages within the configured window.`
- `The collected stream payload was truncated by size limits.`
- `This protocol does not support the selected execution mode.`

## 8. Stream Sessions page

Колонки:

- `Session ID`
- `Operation`
- `Agent`
- `Mode`
- `Status`
- `Created`
- `Last poll`
- `Expires`

Actions:

- `Open`
- `Stop`
- `Delete`

Detail view:

- `Session metadata`
- `Cursor preview`
- `State summary`
- `Recent events summary`

## 9. Async Jobs page

Колонки:

- `Job ID`
- `Operation`
- `Agent`
- `Status`
- `Progress`
- `Created`
- `Updated`
- `Finished`

Actions:

- `Open`
- `Cancel`
- `Get result`

Detail view:

- `Job metadata`
- `Progress payload`
- `Result preview`
- `Error preview`

## 10. Exact frontend adapters

Ожидаемые frontend modules:

- `streaming-form.js`
- `streaming-validation.js`
- `stream-test-run.js`
- `stream-sessions.js`
- `async-jobs.js`

Ожидаемые frontend functions:

- `loadProtocolCapabilities()`
- `applyStreamingPreset()`
- `validateStreamingConfig()`
- `serializeStreamingConfig()`
- `deserializeStreamingConfig()`
- `startWindowTest()`
- `startSessionTest()`
- `pollSessionTest()`
- `stopSessionTest()`
- `startAsyncJobTest()`
- `refreshAsyncJobStatus()`
- `loadAsyncJobResult()`

## 11. Shared UI rules

- UI никогда не должен предлагать unsupported mode;
- UI должен строить availability по `protocol-capabilities`, а не по hardcoded if-else;
- UI должен явно объяснять, почему поле скрыто или disabled;
- UI должен всегда показывать итоговую tool topology:
  - `1 tool`
  - `3 tools start/poll/stop`
  - `4 tools start/status/result/cancel`