txt: ## dist_zef-raku-community-modules-MoarVM-Remote.md
  ## Chunk 2 of 2
   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.
  