-
-
Notifications
You must be signed in to change notification settings - Fork 171
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
#3981 add documentation on network protocol
- Loading branch information
Showing
6 changed files
with
266 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| #  Protocol | ||
|
|
||
| See also: [network layer](../Network/). | ||
|
|
||
| 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](https://github.com/Xpra-org/xpra/tree/master/xpra/net/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](https://github.com/Xpra-org/xpra/blob/master/xpra/net/protocol/header.py) | ||
| 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 | ||
| or `4` for `yaml` data (unsupported). | ||
| 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](./AES.md) | ||
|
|
||
| ### 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](../Subsystems) 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 now 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](../Usage/Authentication.md). | ||
| Each [subsystem](../Subsystems) will also add its own attributes. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| #  Audio Subsystem | ||
|
|
||
| For usage related information, see [audio feature](../Features/Audio.md). | ||
|
|
||
| ## Common | ||
|
|
||
| [xpra.audio](https://github.com/Xpra-org/xpra/tree/master/xpra/audio/) contains the components used for capturing and playing back audio streams | ||
| using [GStreamer](https://gstreamer.freedesktop.org/). | ||
| In order to avoid interfering with the performance of the main thread, | ||
| all audio processing is done in a separate process. | ||
| For historical reasons, this is done using a [subprocess wrapper](https://github.com/Xpra-org/xpra/tree/master/xpra/audio/wrapper.py) | ||
| rather than the builtin [multiprocessing](https://docs.python.org/3/library/multiprocessing.html) module. | ||
|
|
||
| ### Pulseaudio | ||
|
|
||
| [xpra.audio.pulseaudio](https://github.com/Xpra-org/xpra/tree/master/xpra/audio/pulseaudio) is often used for playback on Linux systems. | ||
| This is also the prefered backend for audio capture in server sessions. | ||
| The xpra server will usually start a pulseaudio instance hidden away | ||
| in a per-session user prefix so that multiple sessions can forward audio streams | ||
| independently. | ||
|
|
||
| ## Capabilities | ||
|
|
||
| The client and server should expose the following capabilities in their `hello` packet | ||
| with the `audio` prefix: | ||
|
|
||
| | Capability | Type | Purpose | | ||
| |------------|-----------------|----------------------------------------------------| | ||
| | `decoders` | List of strings | The audio formats that can be received and decoded | | ||
| | `encoders` | List of strings | The audio formats that can be encoded and sent | | ||
| | `send` | boolean | If sending audio is enabled | | ||
| | `receive` | boolean | If receiving audio is enabled | | ||
|
|
||
| The lists of `decoders` and `encoders` contain strings such as: `mp3`, `opus+ogg`, `vorbis`... | ||
| You can run [xpra.audio.gstreamer_util](../../xpra/audio/gstreamer_util.py) to see which | ||
| encoders and decoders are available on the system. | ||
|
|
||
|
|
||
| ## Client | ||
|
|
||
| [xpra.client.mixins.audio](../../xpra/client/mixins/audio.py) | ||
|
|
||
|
|
||
| ## Server | ||
|
|
||
| [xpra.server.mixins.audio](../../xpra/server/mixins/audio.py) | ||
|
|
||
| ## Client connection | ||
|
|
||
| [xpra.server.source.audio](../../xpra/server/source/audio.py) | ||
|
|
||
|
|
||
| ## Network Packets | ||
|
|
||
| This protocol is identical in both directions. | ||
| Audio being forwarded from the server to the client (aka "_speaker forwarding_") | ||
| uses the same packets as audio coming from the client to the server (aka "_microphone forwarding_"). | ||
|
|
||
| | Packet Type | Arguments | Purpose | Information | | ||
| |----------------------|----------------------------------------------------------------------------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------| | ||
| | `sound-data` | `codec` : string <br/>`data` : bytes<br/>`attributes` : dictionary | Audio stream data | The initial and final packets may omit the `data` argument and should set the `start-of-stream` / `end-of-stream` attributes | | ||
| | `sound-control` | `subcommand` : string<br/>(ie: `start`, `stop`, `sync`, `new-sequence`)<br/>`argument` : Any | Send a request to the peer | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| #  Clipboard | ||
|
|
||
| For usage related information, see [clipboard feature](../Features/Clipboard.md). | ||
|
|
||
| ## Implementations | ||
|
|
||
| [xpra.clipboard](https://github.com/Xpra-org/xpra/tree/master/xpra/clipboard/) contains the platform independent base class | ||
| used by all the backends. | ||
| It contains common features such as basic configuration, scheduling, filtering, etc. | ||
|
|
||
| | Platform | Link | | ||
| |----------|-----------------------------------------------------------------------------------| | ||
| | `x11` | [xpra.x11.gtk_x11.clipboard](../../xpra/x11/gtk_x11/clipboard.py) | | ||
| | `win32` | [xpra.platform.win32.clipboard](../../xpra/platform/win32/clipboard.py) | | ||
| | `MacOS` | [xpra.platform.darwin.osx_clipboard](../../xpra/platform/darwin/osx_clipboard.py) | | ||
| | others | [xpra.gtk_common.gtk_clipboard](../../xpra/gtk_common/gtk_clipboard.py) | | ||
|
|
||
|
|
||
| ## Capabilities | ||
|
|
||
| The client and server should expose the following capabilities in their `hello` packet | ||
| with the `clipboard` prefix: | ||
|
|
||
| | Capability | Value | Information | | ||
| |---------------------|-----------------------------|--------------------------------------------------------------------------------------| | ||
| | `enabled` | `enabled` : boolean | Whether clipboard support is enabled | | ||
| | `notifications` | `enabled` : boolean | Request the peer to send `clipboard-pending-requests` packets | | ||
| | `want_targets` | `enabled` : boolean | Request the peer to send `target`s with `clipboard-token` packets | | ||
| | `greedy` | `enabled` : boolean | Request the peer to send clipboard data with `clipboard-token` packets | | ||
| | `preferred-targets` | `targets` : list of strings | The `target`s that the peer should try to use | | ||
| | `direction` | `direction`: string | Optional, which direction is supported, ie: `none`, `to-client`, `to-server`, `both` | | ||
|
|
||
| Notes: | ||
| * `MacOS` clients set the `want_targets` flag | ||
| * both `MacOS` and `MS Windows` clients set the `greedy` flag | ||
|
|
||
| ## Client | ||
|
|
||
| [xpra.client.mixins.clipboard](../../xpra/client/mixins/clipboard.py) | ||
|
|
||
|
|
||
| ## Server | ||
|
|
||
| [xpra.server.mixins.clipboard](../../xpra/server/mixins/clipboard.py) | ||
|
|
||
| ## Client connection | ||
|
|
||
| [xpra.server.source.clipboard](../../xpra/server/source/clipboard.py) | ||
|
|
||
|
|
||
| ## Network Packets | ||
|
|
||
| This protocol is identical in both directions, | ||
| as either end can send and receive clipboard events. | ||
|
|
||
| | Packet Type | Arguments | Optional Arguments | Information | | ||
| |-------------------------------|----------------------------------------------------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `set-clipboard-enabled` | `enabled` : boolean | `reason` : string | Either end is free to enable or disable the clipboard at any time and should notify the peer. | | ||
| | `clipboard-enable-selections` | list of `selection`s | | The selections that the peer wants to synchronize with | | ||
| | `clipboard-token` | `selection` | list of `target`s, `target`, `data-type`, `data-format` and `data` | Notify the peer of a clipboard state change event for the given `selection`, this may include the new clipboard contents if known and / or if the client is known to be _greedy_ | | ||
| | `clipboard-request` | `request-id`, `target` | | Request clipboard contents from the peer | | ||
| | `clipboard-contents` | `request_id`, `selection`, `data-type`, `data-format`, `data` | | Response to a `clipboard-request` | | ||
| | `clipboard-contents-none` | | | Empty response to a `clipboard-request` | | ||
| | `clipboard-pending-requests` | `pending-requests` : integers | | The number of clipboard requests waiting | | ||
|
|
||
|
|
||
| Clipboard data format details: | ||
|
|
||
| | Argument | Data type | Information | | ||
| |----------------|-----------|---------------------------------------------------------------| | ||
| | `selection` | `string` | X11 supports 3 different _clipboards_, known as selections | | ||
| | `request-id` | `integer` | Each `clipboard-request` should use a new unique identifier | | ||
| | `target` | `string` | A clipboard format, ie: `STRING`, `UTF8_STRING`, `text/plain` | | ||
| | `data-type` | `string` | The type of the contents, ie: `bytes` or `ATOM` | | ||
| | `data-format` | `integer` | The number of bits used by each item | | ||
| | `data` | variable | Typically, `bytes` that need to be decoded | |