crank/docs/streaming-ui-contract.md

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

Для test-run UX:

• wizard status block должен различать unary, window, session, async_job;
• window показывает bounded flags window_complete, truncated, has_more;
• session показывает session_id, poll_after_ms и переводит оператора к странице Stream Sessions;
• async_job показывает job_id и переводит оператора к странице Async Jobs;
• request/response preview textareas остаются общими для всех режимов.

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