remote/doc/marionette/Protocol.md

   1 # Protocol
   2
   3 Marionette provides an asynchronous, parallel pipelining user-facing
   4 interface.  Message sequencing limits chances of payload race
   5 conditions and provides a uniform way in which payloads are serialised.
   6
   7 Clients that deliver a blocking WebDriver interface are still
   8 expected to not send further command requests before the response
   9 from the last command has come back, but if they still happen to do
  10 so because of programming error, no harm will be done.  This guards
  11 against [mixing up responses].
  12
  13 Schematic flow of messages:
  14
  15 ```text
  16         client      server
  17           |            |
  18 msgid=1    |----------->|
  19           |  command   |
  20           |            |
  21 msgid=2    |<-----------|
  22           |  command   |
  23           |            |
  24 msgid=2    |----------->|
  25           |  response  |
  26           |            |
  27 msgid=1    |<-----------|
  28           |  response  |
  29           |            |
  30 ```
  31
  32 The protocol consists of a `command` message and the corresponding
  33 `response` message.  A `response` message must always be sent in
  34 reply to a `command` message.
  35
  36 This means that the server implementation does not need to send
  37 the reply precisely in the order of the received commands: if it
  38 receives multiple messages, the server may even reply in random order.
  39 It is therefore strongly advised that clients take this into account
  40 when imlpementing the client end of this wire protocol.
  41
  42 This is required for pipelining messages.  On the server side,
  43 some functions are fast, and some less so.  If the server must
  44 reply in order, the slow functions delay the other replies even if
  45 its execution is already completed.
  46
  47 [mixing up responses]: https://bugzil.la/1207125
  48
  49 ## Command
  50
  51 The request, or `command` message, is a four element JSON Array as shown
  52 below, that may originate from either the client- or server remote ends:
  53
  54 ```python
  55 [type, message ID, command, parameters]
  56 ```
  57
  58 * _type_ must be 0 (integer).  This indicates that the message
  59   is a `command`.
  60
  61 * _message ID_ is a 32-bit unsigned integer.  This number is
  62   used as a sequencing number that uniquely identifies a pair of
  63   `command` and `response` messages.  The other remote part will
  64   reply with a corresponding `response` with the same message ID.
  65
  66 * _command_ is a string identifying the RPC method or command
  67   to execute.
  68
  69 * _parameters_ is an arbitrary JSON serialisable object.
  70
  71 ## Response
  72
  73 The response message is also a four element array as shown below,
  74 and must always be sent after receiving a `command`:
  75
  76 ```python
  77 [type, message ID, error, result]
  78 ```
  79
  80 * _type_ must be 1 (integer).  This indicates that the message is a
  81   `response`.
  82
  83 * _message ID_ is a 32-bit unsigned integer.  This corresponds
  84   to the `command`’s message ID.
  85
  86 * _error_ is null if the command executed correctly.  If the
  87   error occurred on the server-side, then this is an [error] object.
  88
  89 * _result_ is the result object from executing the `command`, if
  90   it executed correctly.  If an error occurred on the server-side,
  91   this field is null.
  92
  93 The structure of the result field can vary, but is documented
  94 individually for each command.
  95
  96 ## Error object
  97
  98 An error object is a serialisation of JavaScript error types,
  99 and it is structured like this:
 100
 101 ```javascript
 102 {
 103   "error": "invalid session id",
 104   "message": "No active session with ID 1234",
 105   "stacktrace": ""
 106 }
 107 ```
 108
 109 All the fields of the error object are required, so the stacktrace and
 110 message fields may be empty strings.  The error field is guaranteed
 111 to be one of the JSON error codes as laid out by the [WebDriver standard].
 112
 113 ## Clients
 114
 115 Clients may be implemented in any language that is capable of writing
 116 and receiving data over TCP socket.  A [reference client] is provided.
 117 Clients may be implemented both synchronously and asynchronously,
 118 although the latter is impossible in protocol levels 2 and earlier
 119 due to the lack of message sequencing.
 120
 121 [WebDriver standard]: https://w3c.github.io/webdriver/#dfn-error-code
 122 [reference client]: https://searchfox.org/mozilla-central/source/testing/marionette/client/