crank/docs/protocol-capability-matrix.md

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