CollabVM 1.2 Protocol Reference: Difference between revisions

no edit summary
No edit summary
No edit summary
All messages with a return value will be replied to with a message with a matching opcode, and additional arguments specified in this reference.
 
== Connection Opcodesnop ==
 
These are the opcodes used throughout the entire connection.
 
=== nop ===
 
This is a keepalive signal sent through the duration of the session used to verify that the client is still connected.
Clients '''MAY''' drop the connection if the server does not send '''any''' messages over a period of time. However this should not be limited strictly to NOPs as these may not be consistently sent if there is other activity on the connection.
 
== Initial connectionHandshake ==
 
Upon making a WebSocket connection, the server will immediately begin sending NOPs, which will continue for the duration of the connection. The client is immediately in the handshaking phase of the connection.
 
The handshake is as follows:
 
=== Authentication announcement ===
 
A server that uses CollabVM Account Authentication will send a message with the <code>auth</code> opcode to announce this. This indicates a few changes in behavior:
 
* Clients may login using the <code>login</code> opcode.
Upon making a WebSocket connection, the server will immediately begin sending NOPs, which will continue for the duration of the connection.
* Clients may not change username except by logging in or having a guest username assigned.
* Depending on server configuration, clients may not be able to chat, take turns, or vote without logging in
* Staff-password authentication is disabled
 
===== Parameters =====
The client must first acquire a username, through the use of the <code>rename</code> opcode specified below.
 
<table class="wikitable">
The client may now get a list of all VMs on the server using the <code>list</code> opcode, or if it already knows the VM ID, it may immediately connect with the <code>connect</code> opcode.
<tr><td>Opcode</td><td><code>auth</code></td></tr>
<tr><td>Parameter 1</td><td>The base URL of the authentication server used by this instance. Ex: <code>https://auth.collabvm.org</code></td></tr>
</table>
 
=== OpcodesObtain a list of VMs ===
 
The first thing the client may want to do is obtain a list of VMs available on this server. If the client already knows exactly what node ID it wants to connect to (common for bots) this may be skipped.
==== list ====
 
==== nopRequest ====
Get a list of all VMs running on the server. No parameters.
 
<table class="wikitable">
===== Response =====
<tr><td>Opcode</td><td><code>list</code></td></tr>
</table>
 
===== Response =====
The server will respond with three arguments for each VM:
 
Parameters 1 through 3 are repeated for every available VM.
'''ID''': The ID of the VM
 
<table class="wikitable">
'''Name''': A display name for the VM. May contain HTML.
<tr><td>Opcode</td><td><code>list</code></td></tr>
<tr><td>Parameter 1</td><td>The ID of the node, that should be passed to the <code>connect</code> opcode.</td></tr>
'''Name''':<tr><td>Parameter 2</td><td>A display name for the VM. May contain HTML.</td></tr>
'''Thumbnail''':<tr><td>Parameter 3</td><td>A Base64-encoded thumbnail for the VM. Will be either PNG or JPEG depending on the server implementation. This can be determined through magic numbers.</td></tr>
</table>
 
=== Connect to a VM ===
'''Thumbnail''': A Base64-encoded thumbnail for the VM. Will be either PNG or JPEG depending on the server implementation. This can be determined through magic numbers.
 
The client may now connect to a VM as follows:
==== connect ====
 
==== listRequest ====
Connect to a VM
 
<table class="wikitable">
===== Parameters =====
<tr><td>Opcode</td><td><code>connect</code></td></tr>
'''ID''':<tr><td>Parameter 1</td><td>The ID of the VM to connect to. Can be retrieved with the list opcode.</td></tr>
</table>
 
==== connectResponse ====
'''ID''': The ID of the VM to connect to. Can be retrieved with the list opcode.
 
<table class="wikitable">
===== Response =====
<tr><td>Opcode</td><td><code>connect</code></td></tr>
<tr><td>Parameter 1</td><td>The status of the connection. See below</td></tr>
</table>
 
Possible statuses:
The server will respond with either 1 or 0
 
'''1''': The connection was successful and the client is now connected to the VM.
'''0''': The connection failed. This is usually due to an invalid VM ID but depending on the server implementation and protocol extensions could mean something else.
 
= Post-Connection =
After successfully connecting to a VM, the client will begin to recieve messages as normal, and may send messages.