### ----------------------------------------------------
### -- MoarVM::Remote
### -- Licenses: Artistic-2.0
### -- Authors: Timo Paulssen
### -- File: README.md
### ----------------------------------------------------
### -- Chunk 2 of 2
 Raku syntax. This is just for ease of reading: the Raku data structure will be automatically converted to/from MessagePack data on the wire.

### Initial Handshake

Upon receving a connection, MoarVM will immediately send the following **24** bytes if it is willing and able to accept the connection:

  * The string "MOARVM-REMOTE-DEBUG\0" encoded in ASCII

  * A big endian, unsigned, 16-bit major protocol version number - =item big endian, unsigned, 16-bit minor protocol version number

Otherwise, it will send the following response, explaining why it cannot, and then close the connection:

  * The string "MOARVM-REMOTE-DEBUG!" encoded in ASCII

  * A big endian, unsigned, 16-bit length for an error string explaining the rejection (length in bytes)

  * The error string, encoded in UTF-8

A client that receives anything other than a response of this form must close the connection and report an error. A client that receives an error response must report the error.

Otherwise, the client should check if it is able to support the version of the protocol that the server speaks. The onus is on clients to support multiple versions of the protocol should the need arise. See versioning below for more. If the client does not wish to proceed, it should simply close the connection.

If the client is statisfied with the version, it should send:

  * The string "MOARVM-REMOTE-CLIENT-OK\0" encoded in ASCII

For the versions of the protocol defined in this document, all further communication will be in terms of MessagePack messages.

MessagePack envelope
--------------------

Every exchange using MessagePack must be an object at the top level. The object must always have the following keys:

  * `type` which must have an integer value. This specifies the type of the message. Failing to include this field or failing to have its value be an integer is a protocol error, and any side receiving such a message should terminate the connection.

  * `id` which must have an integer value. This is used to associate a response with a request, where required. Any interaction initiated by the client should have an odd `id`, starting from 1. Any interaction initiated by the server should have an even `id`, starting from 2.

The object may contain further keys, which will be determined by message type.

Versioning
----------

Backwards-incompatible changes, if needed, will be made by incrementing the major version number. A client seeing a major version number it does not recognize or support must close the connection and not attempt any further interaction, and report an error.

The minor version number is incremented for backwards-compatible changes. A client may proceed safely with a higher minor version number of the protocol than it knows about. However, it should be prepared to accept and disregard message types that it does not recognize, as well as any keys in an object (encoded using MessagePack) that it does not recognize.

The client can use the minor version number to understand what features are supported by the remote MoarVM instance.

The MoarVM instance must disregard keys in a MessagePack object that it does not understand. For message types that it does not recognize, it must send a message of type "Message Type Not Understood" (format defined below); the connection should be left intact by MoarVM, and the client can decide how to proceed.

Security considerations
-----------------------

Any client connected to the debug protocol will be able to perform remote code execution using the running MoarVM instance. Therefore, MoarVM must only bind to `localhost` by default. It may expose an option to bind to further interfaces, but should display a warning about the dangers of this option.

Remote debugging should be performed by establishing a secure tunnel from the client to the server, for example using SSH port forwarding. This provides both authentication and protection against tampering with messages.

AUTHOR
======

  * Timo Paulssen

  * Raku Community

COPYRIGHT AND LICENSE
=====================

Copyright 2011 - 2020 Timo Paulssen

Copyright 2021 - 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.



