From eee6208c2594cbb138adc2496a2257464a5268e6 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Mon, 21 Aug 2023 06:32:09 -0400 Subject: [PATCH] Move FAQ to a separate file (#166) The FAQ was very useful for initial phase of spec development but is now more of historical interest. Moving it to a separate file to avoid distracting spec readers. --- faq.md | 56 +++++++++++++++++++++++++++++++++++++++++++ specification.md | 62 ------------------------------------------------ 2 files changed, 56 insertions(+), 62 deletions(-) create mode 100644 faq.md diff --git a/faq.md b/faq.md new file mode 100644 index 0000000..337a04e --- /dev/null +++ b/faq.md @@ -0,0 +1,56 @@ +# FAQ about OpAMP specification + +## What is WebSocket? + +WebSocket is a bidirectional, message-oriented protocol that uses plain HTTP for +establishing the connection and then uses the HTTP's existing TCP connection to +deliver messages. It has been an +[RFC](https://datatracker.ietf.org/doc/html/rfc6455) standard for a decade now. +It is widely supported by browsers, servers, proxies and load balancers, has +libraries in virtually all popular programming languages, is supported by +network inspection and debugging tools, is secure and efficient and provides the +exact message-oriented semantics that we need for OpAMP. + +## Why not Use TCP Instead of WebSocket? + +We could roll out our own message-oriented implementation over TCP but there are +no benefits over WebSocket which is an existing widely supported standard. A +custom TCP-based solution would be more work to design, more work to implement +and more work to troubleshoot since existing network tools would not recognize +it. + +## Why not alwaysUse HTTP Instead of WebSocket? + +Regular HTTP is a half-duplex protocol, which makes delivery of messages from +the Server to the client tied to the request time of the client. This means that +if the Server needs to send a message to the client the client either needs to +periodically poll the Server to give the Server an opportunity to send a message +or we should use something like long polling. + +Periodic polling is expensive. OpAMP protocol is largely idle after the initial +connection since there is typically no data to deliver for hours or days. To +have a reasonable delivery latency the client would need to poll every few +seconds and that would significantly increase the costs on the Server side (we +aim to support many millions simultaneous of Agents, which would mean servicing +millions of polling requests per second). + +Long polling is more complicated to use than WebSocket since it only provides +one-way communication, from the Server to the client and necessitates the second +connection for client-to-Server delivery direction. The dual connection needed +for a long polling approach would make the protocol more complicated to design +and implement without much gains compared to WebSocket approach. + +## Why not Use gRPC Instead of WebSocket? + +gRPC is a big dependency that some implementations are reluctant to take. gRPC +requires HTTP/2 support from all intermediaries and is not supported in some +load balancers. As opposed to that, WebSocket is usually a small library in most +language implementations (or is even built into runtime, like it is in browsers) +and is more widely supported by load balancers since it is based on HTTP/1.1 +transport. + +Feature-wise gRPC streaming would provide essentially the same functionality as +WebSocket messages, but it is a more complicated dependency that has extra +requirements with no additional benefits for our use case (benefits of gRPC like +ability to multiplex multiple streams over one connection are of no use to +OpAMP). diff --git a/specification.md b/specification.md index 139d859..8ee42cb 100644 --- a/specification.md +++ b/specification.md @@ -165,11 +165,6 @@ Status: [Beta] + [Ignorable Capability Extensions](#ignorable-capability-extensions) + [Non-Ignorable Capability Extensions](#non-ignorable-capability-extensions) + [Protobuf Schema Stability](#protobuf-schema-stability) -- [FAQ for Reviewers](#faq-for-reviewers) - * [What is WebSocket?](#what-is-websocket) - * [Why not Use TCP Instead of WebSocket?](#why-not-use-tcp-instead-of-websocket) - * [Why not alwaysUse HTTP Instead of WebSocket?](#why-not-alwaysuse-http-instead-of-websocket) - * [Why not Use gRPC Instead of WebSocket?](#why-not-use-grpc-instead-of-websocket) - [Future Possibilities](#future-possibilities) - [References](#references) * [Agent Management](#agent-management) @@ -2643,63 +2638,6 @@ defined elsewhere in this specification: - Adding new choices to existing enums. - Adding new choices to existing oneof fields. -## FAQ for Reviewers - -### What is WebSocket? - -WebSocket is a bidirectional, message-oriented protocol that uses plain HTTP for -establishing the connection and then uses the HTTP's existing TCP connection to -deliver messages. It has been an -[RFC](https://datatracker.ietf.org/doc/html/rfc6455) standard for a decade now. -It is widely supported by browsers, servers, proxies and load balancers, has -libraries in virtually all popular programming languages, is supported by -network inspection and debugging tools, is secure and efficient and provides the -exact message-oriented semantics that we need for OpAMP. - -### Why not Use TCP Instead of WebSocket? - -We could roll out our own message-oriented implementation over TCP but there are -no benefits over WebSocket which is an existing widely supported standard. A -custom TCP-based solution would be more work to design, more work to implement -and more work to troubleshoot since existing network tools would not recognize -it. - -### Why not alwaysUse HTTP Instead of WebSocket? - -Regular HTTP is a half-duplex protocol, which makes delivery of messages from -the Server to the client tied to the request time of the client. This means that -if the Server needs to send a message to the client the client either needs to -periodically poll the Server to give the Server an opportunity to send a message -or we should use something like long polling. - -Periodic polling is expensive. OpAMP protocol is largely idle after the initial -connection since there is typically no data to deliver for hours or days. To -have a reasonable delivery latency the client would need to poll every few -seconds and that would significantly increase the costs on the Server side (we -aim to support many millions simultaneous of Agents, which would mean servicing -millions of polling requests per second). - -Long polling is more complicated to use than WebSocket since it only provides -one-way communication, from the Server to the client and necessitates the second -connection for client-to-Server delivery direction. The dual connection needed -for a long polling approach would make the protocol more complicated to design -and implement without much gains compared to WebSocket approach. - -### Why not Use gRPC Instead of WebSocket? - -gRPC is a big dependency that some implementations are reluctant to take. gRPC -requires HTTP/2 support from all intermediaries and is not supported in some -load balancers. As opposed to that, WebSocket is usually a small library in most -language implementations (or is even built into runtime, like it is in browsers) -and is more widely supported by load balancers since it is based on HTTP/1.1 -transport. - -Feature-wise gRPC streaming would provide essentially the same functionality as -WebSocket messages, but it is a more complicated dependency that has extra -requirements with no additional benefits for our use case (benefits of gRPC like -ability to multiplex multiple streams over one connection are of no use to -OpAMP). - ## Future Possibilities Define specification for Concentrating Proxy that can serve as intermediary to