From af546742873d7482528f9ba6355694f6cca389b6 Mon Sep 17 00:00:00 2001 From: Andreas Tolfsen Date: Fri, 13 Oct 2017 17:08:57 +0100 Subject: [PATCH] Bug 1407990 - Move protocol definition to doc/Protocol.md. r=maja_zf DONTBUILD MozReview-Commit-ID: 6U9vpIvFtJR --HG-- extra : rebase_source : 04851c75e47691bbe69f1d0d6071d10241e0f573 --- testing/marionette/README.md | 112 ----------------------------- testing/marionette/doc/Intro.md | 2 +- testing/marionette/doc/Protocol.md | 110 ++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 113 deletions(-) create mode 100644 testing/marionette/doc/Protocol.md diff --git a/testing/marionette/README.md b/testing/marionette/README.md index a956b1df9e57..9cefa5175519 100644 --- a/testing/marionette/README.md +++ b/testing/marionette/README.md @@ -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 ======= diff --git a/testing/marionette/doc/Intro.md b/testing/marionette/doc/Intro.md index 770925ae8556..1185a01f1432 100644 --- a/testing/marionette/doc/Intro.md +++ b/testing/marionette/doc/Intro.md @@ -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 diff --git a/testing/marionette/doc/Protocol.md b/testing/marionette/doc/Protocol.md new file mode 100644 index 000000000000..3d52ac97e475 --- /dev/null +++ b/testing/marionette/doc/Protocol.md @@ -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].