Commits on Nov 9, 2022

1. Adding a header for WebSocket messages to allow future extensibility …

   Resolves open-telemetry#133
   
   Thi is ane extensibility mechanism - a header for WebSocket messages. Every WebSocket message is composed of 2 parts: varint-encoded unsigned 64 bit integer header, followed by the serialized Protobuf AgentToServer/ServerToAgent messages.
   
   The current value of the header is equal to 0. In the future when non-zero values of headers are introduced their use should be negotiated during the connection phase (via HTTP headers or via Capabilities fields). This is necessary to ensure interoperability between different OpAMP versions. Non-zero header values will not be a breaking change, they will only used after successful negotiation between the Client and Server.
   
   Note: we don't need the header for plain HTTP transport. Any extensibility for HTTP can be done via HTTP headers (not suitable for WebSocket since it cannot work per message - HTTP headers are sent once per connection).
   
   ## Example Usage
   
   The header can be used in the future for example in the following ways.
   
   ### Message Fragmentation
   
   We found that some WebSocket implementations (e.g. [AWS API Gateway](open-telemetry#60 (comment))) limit the message size to 128KB. The only way to overcome this limitation is to perform message fragmentation and reassembly in OpAMP itself. This can be done by using one bit in the header to indicate whether the message is the last fragment.
   
   ### Support Other Compression Algorithms
   
   WebSocket has built-in compression. What compression is used depends on the WebSocket implementation and realistically only "deflate" compression implementations are available. There are more modern compression algorithms (e.g. zstd), but it is impossible to use in OpAMP since most known WebSocket implementations simply don't support them.
   
   The header can easily allow supporting these other compression algorithms. We can use one or more of the header bits to indicate the compression algorithm used.
   
   Note: this sort of extension can be also done via HTTP header negotiation. However, not all WebSocket implementations allow custom HTTP headers (browsers don't).

   

   tigrannajaryan committed Nov 9, 2022
   Configuration menu

   • View commit details
   • Copy full SHA for 32dd947
   • Browse repository at this point

   Copy the full SHA

   32dd947 View commit details

   Browse the repository at this point in the history