docs: add detailed streaming specifications

2026-04-06 02:35:00 +03:00
parent 7f15b2db9e
commit dbc57a0419
8 changed files with 1775 additions and 4 deletions
@@ -0,0 +1,123 @@
+# Protocol Capability Matrix
+
+## 1. Назначение документа
+
+Этот документ фиксирует capability matrix по всем protocol families и execution modes.
+
+Он нужен как source of truth для:
+
+- UI availability rules;
+- admin-api validation;
+- runtime dispatch;
+- roadmap planning.
+
+## 2. Matrix by protocol and execution mode
+
+| Protocol | Unary | Window | Session | Async Job | Notes |
+| --- | --- | --- | --- | --- | --- |
+| REST | Yes | Yes | Yes | Yes | window/session используют SSE или bounded polling |
+| GraphQL | Yes | No | No | Limited | async job только как явная status/result workflow model |
+| gRPC | Yes | Yes | Yes | Yes | только unary и server-streaming |
+| WebSocket | No | Yes | Yes | Yes | upstream-only adapter |
+| SOAP | Yes | Limited | No | Yes | request-response first, async через separate workflow contract |
+
+## 3. Matrix by protocol and transport behavior
+
+| Protocol | Request/Response | Server Stream | Stateful Session |
+| --- | --- | --- | --- |
+| REST | Yes | Yes | Limited |
+| GraphQL | Yes | No | No |
+| gRPC | Yes | Yes | Yes |
+| WebSocket | No | Yes | Yes |
+| SOAP | Yes | Limited | No |
+
+## 4. Matrix by protocol and artifact requirements
+
+| Protocol | Sample JSON | Descriptor | WSDL/XSD | Query Template | Subscribe Template |
+| --- | --- | --- | --- | --- | --- |
+| REST | Optional | No | No | No | Optional |
+| GraphQL | Optional | No | No | Yes | No |
+| gRPC | Optional | Yes | No | No | No |
+| WebSocket | Optional | No | No | No | Yes |
+| SOAP | Optional | No | Yes | No | No |
+
+## 5. Matrix by protocol and auth support
+
+| Protocol | None | Bearer | Basic | API Key Header | API Key Query | WS-Security |
+| --- | --- | --- | --- | --- | --- | --- |
+| REST | Yes | Yes | Yes | Yes | Yes | No |
+| GraphQL | Yes | Yes | Yes | Yes | Limited | No |
+| gRPC | Yes | Yes | Yes | Limited | No | No |
+| WebSocket | Yes | Yes | Yes | Yes | Limited | No |
+| SOAP | Yes | Yes | Yes | Limited | Limited | Future |
+
+## 6. Matrix by protocol and UI blocks
+
+| UI Block | REST | GraphQL | gRPC | WebSocket | SOAP |
+| --- | --- | --- | --- | --- | --- |
+| Endpoint URL | Yes | Yes | No | Yes | Optional |
+| Method selector | Yes | No | No | No | No |
+| Query template | No | Yes | No | No | No |
+| Descriptor upload | No | No | Yes | No | No |
+| WSDL upload | No | No | No | No | Yes |
+| Subscribe template | Optional | No | No | Yes | No |
+| Subprotocol list | No | No | No | Yes | No |
+| SOAP headers | No | No | No | No | Yes |
+| Stream kind selector | Optional | No | Yes | Yes | Limited |
+
+## 7. Validation rules matrix
+
+## 7.1. Unsupported combinations
+
+- `GraphQL + Window`
+- `GraphQL + Session`
+- `WebSocket + Unary`
+- `SOAP + Session`
+- `gRPC + Session` для non-server-streaming method
+- `REST + Server Stream` без stream-capable target model
+
+## 7.2. Conditionally supported combinations
+
+- `GraphQL + Async Job`
+  Требует отдельного status/result workflow contract.
+
+- `SOAP + Window`
+  Допускается только для polling-style workflow, а не для native stream.
+
+- `SOAP + Async Job`
+  Требует отдельной operation family для status/result.
+
+## 8. Product-wave grouping
+
+### Wave 1
+
+- REST
+- GraphQL query/mutation
+- gRPC unary
+- Streamable HTTP downstream
+- Window/session/job core model
+
+### Wave 2
+
+- REST SSE
+- gRPC server-streaming
+- session/job tool families
+- streaming UI
+
+### Wave 3
+
+- WebSocket upstream adapter
+- richer streaming observability
+
+### Wave 4
+
+- SOAP foundation
+- WSDL/XSD tooling
+- SOAP UI flow
+
+### Wave 5
+
+- GraphQL subscriptions
+- gRPC client-streaming
+- gRPC bidi
+- advanced enterprise security stacks