mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-12 12:55:46 +00:00
Bug 1407990 - Move protocol definition to doc/Protocol.md. r=maja_zf
DONTBUILD MozReview-Commit-ID: 6U9vpIvFtJR --HG-- extra : rebase_source : 04851c75e47691bbe69f1d0d6071d10241e0f573
This commit is contained in:
parent
03d523593a
commit
af54674287
@ -31,118 +31,6 @@ This binds to a TCP socket, over which [clients] can communicate
|
||||
with Marionette using the [protocol].
|
||||
|
||||
|
||||
Protocol
|
||||
========
|
||||
|
||||
Marionette provides an asynchronous, parallel pipelining user-facing
|
||||
interface. Message sequencing limits chances of payload race
|
||||
conditions and provides a uniform way in which payloads are serialised.
|
||||
|
||||
Clients that deliver a blocking WebDriver interface are still
|
||||
expected to not send further command requests before the response
|
||||
from the last command has come back, but if they still happen to do
|
||||
so because of programming error, no harm will be done. This guards
|
||||
against [mixing up responses].
|
||||
|
||||
Schematic flow of messages:
|
||||
|
||||
client server
|
||||
| |
|
||||
msgid=1 |----------->|
|
||||
| command |
|
||||
| |
|
||||
msgid=2 |<-----------|
|
||||
| command |
|
||||
| |
|
||||
msgid=2 |----------->|
|
||||
| response |
|
||||
| |
|
||||
msgid=1 |<-----------|
|
||||
| response |
|
||||
| |
|
||||
|
||||
The protocol consists of a [command] message and the corresponding
|
||||
[response] message. A [response] message must always be sent in
|
||||
reply to a [commmand] message.
|
||||
|
||||
This means that the server implementation does not need to send
|
||||
the reply precisely in the order of the received commands: if it
|
||||
receives multiple messages, the server may even reply in random order.
|
||||
It is therefore strongly adviced that clients take this into account
|
||||
when imlpementing the client end of this wire protocol.
|
||||
|
||||
This is required for pipelining messages. On the server side,
|
||||
some functions are fast, and some less so. If the server must
|
||||
reply in order, the slow functions delay the other replies even if
|
||||
its execution is already completed.
|
||||
|
||||
[mixing up responses]: https://bugzil.la/1207125
|
||||
|
||||
|
||||
Command
|
||||
-------
|
||||
|
||||
The request, or command message, is a four element JSON Array as shown
|
||||
below, that may originate from either the client- or server remote ends:
|
||||
|
||||
[type, message ID, command, parameters]
|
||||
|
||||
* _type_ must be 0 (integer). This indicates that the message
|
||||
is a [command].
|
||||
|
||||
* _message ID_ is a 32-bit unsigned integer. This number is
|
||||
used as a sequencing number that uniquely identifies a pair of
|
||||
[command] and [response] messages. The other remote part will
|
||||
reply with a corresponding [response] with the same message ID.
|
||||
|
||||
* _command_ is a string identifying the RPC method or command
|
||||
to execute.
|
||||
|
||||
* _parameters_ is an arbitrary JSON serialisable object.
|
||||
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
The response message is also a four element array as shown below,
|
||||
and must always be sent after receiving a [command]:
|
||||
|
||||
[type, message ID, error, result]
|
||||
|
||||
* _type_ must be 1 (integer). This indicates that the message is a
|
||||
[response].
|
||||
|
||||
* _message ID_ is a 32-bit unsigned integer. This corresponds
|
||||
to the [command]’s message ID.
|
||||
|
||||
* _error_ is null if the command executed correctly. If the
|
||||
error occurred on the server-side, then this is an [error] object.
|
||||
|
||||
* _result_ is the result object from executing the [command], iff
|
||||
it executed correctly. If an error occurred on the server-side,
|
||||
this field is null.
|
||||
|
||||
The structure of the result field can vary, but is documented
|
||||
individually for each command.
|
||||
|
||||
|
||||
Error object
|
||||
------------
|
||||
|
||||
An error object is a serialisation of JavaScript error types,
|
||||
and it is structured like this:
|
||||
|
||||
{
|
||||
"error": "invalid session id",
|
||||
"message": "No active session with ID 1234",
|
||||
"stacktrace": ""
|
||||
}
|
||||
|
||||
All the fields of the error object are required, so the stacktrace and
|
||||
message fields may be empty strings. The error field is guaranteed
|
||||
to be one of the JSON error codes as laid out by the [WebDriver standard].
|
||||
|
||||
|
||||
Clients
|
||||
=======
|
||||
|
||||
|
@ -70,7 +70,7 @@ need to download a Marionette client or use the in-tree client.
|
||||
[5] ./Debugging.md
|
||||
[6] https://developer.mozilla.org/en-US/docs/Marionette/Builds
|
||||
[7] https://github.com/mozilla-b2g/marionette_js_client
|
||||
[8] https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
|
||||
[8] ./Protocol.md
|
||||
|
||||
|
||||
Bugs
|
||||
|
110
testing/marionette/doc/Protocol.md
Normal file
110
testing/marionette/doc/Protocol.md
Normal file
@ -0,0 +1,110 @@
|
||||
Protocol
|
||||
========
|
||||
|
||||
Marionette provides an asynchronous, parallel pipelining user-facing
|
||||
interface. Message sequencing limits chances of payload race
|
||||
conditions and provides a uniform way in which payloads are serialised.
|
||||
|
||||
Clients that deliver a blocking WebDriver interface are still
|
||||
expected to not send further command requests before the response
|
||||
from the last command has come back, but if they still happen to do
|
||||
so because of programming error, no harm will be done. This guards
|
||||
against [mixing up responses].
|
||||
|
||||
Schematic flow of messages:
|
||||
|
||||
client server
|
||||
| |
|
||||
msgid=1 |----------->|
|
||||
| command |
|
||||
| |
|
||||
msgid=2 |<-----------|
|
||||
| command |
|
||||
| |
|
||||
msgid=2 |----------->|
|
||||
| response |
|
||||
| |
|
||||
msgid=1 |<-----------|
|
||||
| response |
|
||||
| |
|
||||
|
||||
The protocol consists of a [command] message and the corresponding
|
||||
[response] message. A [response] message must always be sent in
|
||||
reply to a [commmand] message.
|
||||
|
||||
This means that the server implementation does not need to send
|
||||
the reply precisely in the order of the received commands: if it
|
||||
receives multiple messages, the server may even reply in random order.
|
||||
It is therefore strongly adviced that clients take this into account
|
||||
when imlpementing the client end of this wire protocol.
|
||||
|
||||
This is required for pipelining messages. On the server side,
|
||||
some functions are fast, and some less so. If the server must
|
||||
reply in order, the slow functions delay the other replies even if
|
||||
its execution is already completed.
|
||||
|
||||
[mixing up responses]: https://bugzil.la/1207125
|
||||
|
||||
|
||||
Command
|
||||
-------
|
||||
|
||||
The request, or command message, is a four element JSON Array as shown
|
||||
below, that may originate from either the client- or server remote ends:
|
||||
|
||||
[type, message ID, command, parameters]
|
||||
|
||||
* _type_ must be 0 (integer). This indicates that the message
|
||||
is a [command].
|
||||
|
||||
* _message ID_ is a 32-bit unsigned integer. This number is
|
||||
used as a sequencing number that uniquely identifies a pair of
|
||||
[command] and [response] messages. The other remote part will
|
||||
reply with a corresponding [response] with the same message ID.
|
||||
|
||||
* _command_ is a string identifying the RPC method or command
|
||||
to execute.
|
||||
|
||||
* _parameters_ is an arbitrary JSON serialisable object.
|
||||
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
The response message is also a four element array as shown below,
|
||||
and must always be sent after receiving a [command]:
|
||||
|
||||
[type, message ID, error, result]
|
||||
|
||||
* _type_ must be 1 (integer). This indicates that the message is a
|
||||
[response].
|
||||
|
||||
* _message ID_ is a 32-bit unsigned integer. This corresponds
|
||||
to the [command]’s message ID.
|
||||
|
||||
* _error_ is null if the command executed correctly. If the
|
||||
error occurred on the server-side, then this is an [error] object.
|
||||
|
||||
* _result_ is the result object from executing the [command], iff
|
||||
it executed correctly. If an error occurred on the server-side,
|
||||
this field is null.
|
||||
|
||||
The structure of the result field can vary, but is documented
|
||||
individually for each command.
|
||||
|
||||
|
||||
Error object
|
||||
------------
|
||||
|
||||
An error object is a serialisation of JavaScript error types,
|
||||
and it is structured like this:
|
||||
|
||||
{
|
||||
"error": "invalid session id",
|
||||
"message": "No active session with ID 1234",
|
||||
"stacktrace": ""
|
||||
}
|
||||
|
||||
All the fields of the error object are required, so the stacktrace and
|
||||
message fields may be empty strings. The error field is guaranteed
|
||||
to be one of the JSON error codes as laid out by the [WebDriver standard].
|
Loading…
Reference in New Issue
Block a user