CollabVM 1.2 Protocol Reference

This is the protocol reference for CollabVM 1.2, detailing how the protocol works and how to do different things.

The CollabVM protocol is the mutilated corpse of what used to be Guacamole 0.9.5. It maintains the same instruction format and opcodes for getting the VM display and controlling it, but that's about it.

Wire Protocol

The connection starts with the client making a WebSocket connection to the CollabVM endpoint. This can be anything, for example wss://computernewb.com/collab-vm/vm0 for VM0b0t.

The client MUST use guacamole as the WebSocket subprotocol and servers MUST reject any connections not using this subprotocol.

The CollabVM protocol supports multiple VMs, however current server implementations only support one per instance. This is not a requirement and new servers are welcome to support multiple VMs.

Each VM has its own ID. This ID is arbitrary however MUST be unique against all other VMs on the server, and all VMs that will be used on the same webapp.

Each client has their own username. The client must set a username or request that the server assign it one before connecting to a VM.

Assigned usernames are, by convention, guest followed by five random digits. However, the server may use whatever format it pleases.

Message Format

All messages on the CollabVM protocol are UTF-8 string arrays encoded in Guacamole Format, detailed in the Design section of the Guacamole 0.9.5 Manual, Chapter 9. Servers SHOULD drop the connection if the client sends a message not conforming to this.

nop

This is a keepalive signal sent through the duration of the session used to verify that the client is still connected.

The server MUST send a 3.nop; periodically and the client MUST respond with the same.

The server MAY omit sending NOPs if there is other activity by the client.

Servers MUST drop any client which does not respond to the NOP in a timely manner.

Clients MUST NOT send a NOP until prompted by the server.

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.

Handshake

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 auth opcode to announce this. This indicates a few changes in behavior:

• Clients may login using the login opcode.
• 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

Opcode	auth
Parameter 1	The base URL of the authentication server used by this instance. Ex: https://auth.collabvm.org

Obtain 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.

Request

Opcode

list

Response

Parameters 1 through 3 are repeated for every available VM.

Opcode	list
Parameter 1	The ID of the node, that should be passed to the connect opcode.
Parameter 2	A display name for the VM. May contain HTML.
Parameter 3	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.

Request a username

Before connecting, the client must now obtain a username.

Request

Opcode	rename
Parameter 1	(OPTIONAL) The username requested by the client. May be omitted if the client has no preference. The server is under no obligation to respect this and may provide a guest username for a multitude of reasons

Response

The server will respond with a Client Renamed event, however with one key difference: The status will always be 0 (success), even if the requested username was not available for whatever reason. In this case, a guest username is assigned.

Connect to a VM

The client may now connect to a VM as follows:

Request

Opcode	connect
Parameter 1	The ID of the VM to connect to. Can be retrieved with the list opcode.

Response

Opcode	connect
Parameter 1	The status of the connection. See below

Possible statuses:

Value	Status
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.
1	The connection was successful and the client is now connected to the VM.

After successfully connecting to a VM, the client will begin to recieve messages as normal, and may send messages.

Server-to-Client Opcodes

These messages may be sent by the server at any time after completing the handshake and must be handled by the client.

New User(s)

Sent to indicate that one or more users have joined the VM. This may also be sent during the handshake.

This may be resent for an already-joined user to announce that they have changed ranks after logging in. Make sure to check for duplicates.

Parameters 1 and 2 are repeated for each user added.

Opcode	adduser
Parameter 1	The username of the added user.
Parameter 2	The Rank of the added user as an integer.

Removed User(s)

Sent when one or more users disconnect from the VM.

Parameter 2 is repeated for each user removed.

Opcode	remuser
Parameter 1	The number of users that have left
Parameter 2	The username that has left the VM.

Client Renamed

Sent when the current client (you) is renamed, either by you or the server.

Opcode	rename
Parameter 1	0
Parameter 2	The status of the rename. See below for available values.
Parameter 3	The client's new username. This may not necessarily be the username requested by the client, as the server can refuse this request for a variety of reasons and may instead assign a guest name.

Possible rename statuses:

Value	Status
0	The client got their requested username. If the renaming is sent by a staff member this must always be used even if the requested username was not available.
1	The username was already taken.
2	The username was invalid. See requirements above.
3	The username is not allowed by the server.

User Renamed

Sent when another user in the list is renamed.

Opcode	rename
Parameter 1	1
Parameter 2	The user's old username
Parameter 3	The user's new username

Chat message

Sent when one or more chat messages are received.

Parameters 1 and 2 may be repeated for multiple chat messages, and this should be checked for. In current server implementations, this will only happen immediately after connection to send the chat history.

Opcode	chat
Parameter 1	The user who sent the chat message. This may be an empty string to indicate a system message sent by the server, such as the Message of the Day, or a vote notification.
Parameter 2	The chat message

Screen Size

Sent to announce the screen size of the VM. This will be sent after connecting and after any resolution change on the VM.

Opcode	size
Parameter 1	0
Parameter 2	Screen width
Parameter 3	Screen height

Framebuffer Update

Sent to update the VM screen. The server will send one initial message containing the entire screen on connection, and after that will send a dirty rect for each update

Opcode	png
Parameter 1	0
Parameter 2	0
Parameter 3	X-axis position of the rectangle
Parameter 4	Y-axis position of the rectangle
Parameter 5	The base64-encoded rectangle. Despite the name of the opcode, this may be either PNG or JPEG and can be determined through magic numbers or headers.

Vote-for-reset notification

Sent when a Vote-for-reset on the VM updates

Opcode	vote
Parameter 1	The status of the vote. See below for values
Parameter 2	Amount of time left on the vote in milliseconds. If the above status was 3 (cooldown), this is the amount of time before the client can start a vote.
Parameter 3	The number of users who have voted in favor of resetting the VM
Parameter 4	The number of users who have voted against resetting the VM

Possible vote statuses:

Value	Status
0	The vote has started. The yes and no parameters may not be specified, and in such case should be assumed to be zero.
1	The vote count has updated.
2	The vote has ended. No other parameters will be given.
3	Sent if the client tried to start a vote, however there is an active cooldown. Only the time parameter is given.

Turn queue update

Indicates an update of the VM's turn queue

Opcode	turn
Parameter 1	How much time is left on the current user's turn in milliseconds.
Parameter 2	The amount of users in the queue.
Parameter 3-?	Each username in the queue given as separate parameters
End parameter	How much longer until the client will get a turn in milliseconds. Only sent if the client is waiting.

Client-to-Server Opcodes

These opcodes may be sent by the client at any time after the handshake to perform various actions

Account Login

Used to log in with a CollabVM account. This should only be sent if the server announced authentication using the auth opcode during the handshake phase. Sending this opcode otherwise is undefined behavior.

Request

Opcode	login
Parameter 1	A session token OR bot token obtained from the authentication server announced during handshake.

Response

Opcode	login
Parameter 1	Login status. 0 for error, 1 for success.
Parameter 2	Human-readable error. Only sent if status was 0

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

Opcode	rename
Parameter 1	The username requested by the client. If omitted, the server will reassign a guest username.

Response

The server will respond with a Client Renamed event.

Send Chat

Send a public chat message to the server.

Request

Opcode	chat
Parameter 1	Chat message to send

Response

This opcode has no specific response, although the server will send a Chat message event for the message, provided it was not blocked or ratelimited.

Take turn

Request a turn on the VM.

Request

Opcode	turn
Parameter 1	1 to take a turn, 0 to cancel your turn. If not specified, the server will infer 1.

Response

The server will send a Turn queue update assuming the request was not blocked or ratelimited.

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.

Opcode	mouse
Parameter 1	X position of the mouse pointer on the VM screen
Parameter 2	Y position of the mouse pointer on the VM screen
Parameter 3	Bitmask of mouse buttons being held. See Remote Framebuffer Protocol§PointerEvent

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.

Opcode	key
Parameter 1	Key symbol for the key being pressed as a base-10 integer. See keysymdef.h for a list (values are in hex and must be converted to base 10)
Parameter 2	1 to press the key, 0 to release.

Admin Opcodes

These opcodes may be sent to perform administration actions on the VM.

TODO

Rank

CollabVM has four ranks:

ID	Name	Description
0	Unregistered	The default rank with no permissions that all users have prior to logging in.
1	Registered	A logged in user. This is only used by servers that use CollabVM Account Authentication.
2	Admin	Has all permissions on the VM.
3	Moderator	Permissions vary depending on server configuration. Even with all permissions granted moderators can still not use the QEMU monitor.