Bureaucrats, Check users, Interface administrators, Push subscription managers, Suppressors, Administrators
415
edits
CollabVM 1.2 Protocol Reference: Difference between revisions
no edit summary
No edit summary |
No edit summary |
||
| (11 intermediate revisions by the same user not shown) | |||
|
All messages on the CollabVM protocol are UTF-8 string arrays encoded in Guacamole Format, detailed in the Design section of the [https://guacamole.apache.org/doc/0.9.5/gug/guacamole-protocol.html Guacamole 0.9.5 Manual, Chapter 9]. Servers '''SHOULD''' drop the connection if the client sends a message not conforming to this.
Every message consists of an "opcode" at position zero, followed by zero to unlimited parameters.
== nop ==
==== Response ====
The server will respond with a [[#Client Renamed|Client Renamed]] event, however with one key difference: The status will always be <code>0</code> (success), even if the requested username was not available for whatever reason. In this case, a guest username is assigned.
=== Connect to a VM ===
Possible statuses:
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
</td></tr>
<tr><td>1</td><td>The connection was successful and the client is now connected to the VM.</td></tr>
</table>
After successfully connecting to a VM, the client will begin to recieve messages as normal, and may send messages.
== Client-to-Server Opcodes ==
These opcodes may be sent by the client at any time after the handshake to perform various actions
===
Used to log in with a CollabVM account. This should only be sent if the server announced authentication using the <code>auth</code> opcode during the handshake phase. Sending this opcode otherwise is undefined behavior.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>login</code></td></tr>
<tr><td>Parameter 1</td><td>A session token OR bot token obtained from the authentication server announced during handshake.</td></tr>
</table>
==== Response ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>login</code></td></tr>
<tr><td>Parameter 1</td><td>Login status. <code>0</code> for error, <code>1</code> for success.</td></tr>
<tr><td>Parameter 2</td><td>Human-readable error. Only sent if status was <code>0</code></td></tr>
</table>
After a successful login, the client should expect to be renamed and have their rank updated by the server.
=== Rename ===
Used to change the client's username. This opcode is not available on servers that use account authentication, and the server will respond with an error.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td>The username requested by the client. If omitted, the server will reassign a guest username.</td></tr>
</table>
==== Response ====
The server will respond with a [[#Client Renamed|Client Renamed]] event.
=== Send Chat ===
Send a public chat message to the server.
<table class="wikitable">
<tr><td>Opcode</td><td><code>chat</code></td></tr>
<tr><td>Parameter 1</td><td>Chat message to send</td></tr>
</table>
=== Take turn ===
Request a turn on the VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>turn</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code> to take a turn, <code>0</code> to cancel your turn. If not specified, the server will infer <code>1</code>.</td></tr>
</table>
=== Mouse Instruction ===
Send a mouse update to the VM. Only effective if the client has the turn or is an Admin. This opcode has no response.
<table class="wikitable">
<tr><td>Opcode</td><td><code>mouse</code></td></tr>
<tr><td>Parameter 1</td><td>X position of the mouse pointer on the VM screen</td></tr>
<tr><td>Parameter 2</td><td>Y position of the mouse pointer on the VM screen</td></tr>
<tr><td>Parameter 3</td><td>Bitmask of mouse buttons being held. See [https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#pointerevent Remote Framebuffer Protocol§PointerEvent]</td></tr>
</table>
=== Keyboard Instruction ===
Send a keyboard update to the VM. Only effective if the client has the turn or is an Admin. This opcode has no response.
<table class="wikitable">
<tr><td>Opcode</td><td><code>key</code></td></tr>
<tr><td>Parameter 1</td><td>Key symbol for the key being pressed as a base-10 integer. See [https://cgit.freedesktop.org/xorg/proto/x11proto/tree/keysymdef.h keysymdef.h] for a list (values are in hex and must be converted to base 10)</td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to press the key, <code>0</code> to release.</td></tr>
</table>
=== Vote-for-reset ===
Vote for or against resetting the VM to snapshot.
<table class="wikitable">
<tr><td>Opcode</td><td><code>vote</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code> to vote in favor of a reset, <code>0</code> to vote against a reset. If there is no active vote, <code>1</code> is used to start one, while <code>0</code> has no effect.</td></tr>
</table>
== Admin Opcodes ==
These opcodes may be sent to perform administration actions on the VM.
=== Staff Login ===
Used to log in as an Admin or Moderator on the VM using a staff password. This opcode is disabled if the VM uses Account Authentication, in which case the [[#Account Login|Account Login]] opcode should be used instead.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>2</code></td></tr>
<tr><td>Parameter 2</td><td>The staff password</td></tr>
</table>
==== Response ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td>Status of the login. See below for possible values.</td></tr>
<tr><td>Parameter 3</td><td>[[#Permissions|Permissions]] integer defining available moderation actions. Only sent if status is <code>3</code></td></tr>
</table>
Status can be one of the following:
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
<tr><td>0</td><td>Invalid credentials, or access denied for another reason.</td></tr>
<tr><td>1</td><td>Logged in successfully as Admin</td></tr>
<tr><td>3</td><td>Logged in successfully as Moderator</td></tr>
</table>
After successfully logging in, the server will also send a new [[#New User(s)|New User]] event to announce your rank change.
= Rank =
CollabVM has four ranks:
<tr><td>2</td><td>Admin</td><td>Has all permissions on the VM.</td></tr>
<tr><td>3</td><td>Moderator</td><td>Permissions vary depending on server configuration. Even with all permissions granted moderators can still not use the QEMU monitor.</td></tr>
</table>
= Permissions =
When logging in as a Moderator, permissions are defined by a bitmask that can contain the following values:
<table class="wikitable">
<tr><th>Value</th><th>Description</th></tr>
<tr><td>1</td><td>Reset the VM back to it's initial state.</td></tr>
<tr><td>2</td><td>Reboot the VM</td></tr>
<tr><td>4</td><td>Ban a user from your VM</td></tr>
<tr><td>8</td><td>Forcibly pass or cancel a vote to reset</td></tr>
<tr><td>16</td><td>Mute a user, preventing them from chatting or taking turns</td></tr>
<tr><td>32</td><td>Kick a user from the VM</td></tr>
<tr><td>64</td><td>Jump to the front of the turn queue, as well as clear the turn queue and end individual turns</td></tr>
<tr><td>128</td><td>Rename another user</td></tr>
<tr><td>256</td><td>Get the IP address of another user</td></tr>
<tr><td>512</td><td>Send a raw (not HTML-sanitized) chat message, allowing the execution of arbitrary scripts on another user's browser. Admins will not be affected by XSS messages sent by mods.</td></tr>
</table>
| |||