Skip to content

Latest commit

 

History

History
116 lines (82 loc) · 4.34 KB

Protocol.md

File metadata and controls

116 lines (82 loc) · 4.34 KB
Raw

Protocol Protocol

See also: network layer.

Every packet exchanged between xpra servers and clients must follow exactly the same format: an 8 byte header followed by the packet data encoded using rencodeplus, optionally compressed using lz4.
Only when a connection uses a protocol which cannot be identified, xpra may respond with a plain-text error message without any packet header.

Framing

When connecting over websockets, SSL, SSH or QUIC, the transport layer will obviously add its own framing.
Please refer to these protocols for the information on the packet framing used by each of these network protocols.
Only xpra's own application layer protocol is documented here.

Packet Header

The packet header is made of 8 bytes:

Index Type Length in Bytes Contents
0 Byte 1 P
1 Byte 1 protocol flags
2 Byte 1 compression level
3 Byte 1 chunk index
4 Long 4 payload size

Protocol Flags

The protocol flags is an 8-bit bitmask value.
It must contain the value 16 for rencodeplus packet data. Other values are no longer supported.
This value can then be ORed with:

  • 8 to set the flush flag which notifies the packet layer that there aren't any other packets immediately following this one
  • 2 to set the cipher flag for AES encrypted packets

Compression Level

If the compression level is zero, the payload is not compressed. Or at least, not compressed at the network layer: pixel and audio data may still be compressed but this is handled by their respective subsystem and not the transport layer.

This bitmask value is used to indicate how the packet payload is compressed.
The lower 4 bits indicate the compression level. The higher 4 bits indicate which compressor was used:

  • 16 for lz4
  • 64 for brotli

Chunk Index

The chunk index is used for sending large payloads and bypassing the packet encoder.
Packet chunks do not normally use a packet encoder or compressor.
The receiver must replace the item found at chunk index in the main packet.

Example for sending a hypothetical packet ("example-large-packet", "foo", 20MB data), send 2 chunks for better performance:

  • send the 20MB data with a chunk index of 2 (zero based)
  • send ("example-large-packet", "foo", "") with a chunk index of 0 (0 is the main packet)

The receiver must reassemble the original packet from these two chunks.

Payload

The main payload has a chunk index of zero.
Once decompressed according to the compression level flag if needed, it must be decoded according to the protocol flags using rencodeplus.

It consists of a list of items. The first item in that list is the packet-type string.
The packet type can be followed by a variable number of optional arguments.

Packet Type

The packet-type is a string which is used for dispatching the packet to the correct handler.
Each subsystem should use the same prefix for all its packet types.

The packet-type may also be sent as an integer once the hello packet has been processed by the peer if the hello packet contains an aliases capability containing the mapping from packet-type to integer.

Arguments

The only data types that should be used are:

  • integers
  • booleans
  • dictionaries
  • iterables: lists and tuples
  • byte arrays
  • strings

Floating point numbers and None values can be encoded but should be avoided.

Hello

The hello packet is the initial packet used as handshake. The connection is not fully established until both ends have received a hello packet.

The hello packet contains a single argument which is a dictionary containing all the capabilities advertised by the peer.

For example, hello packets are expected to contain a version capability containing the version string.
They may also include a username value, which can be used for authentication.
Each subsystem will also add its own attributes.