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.
Messages
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.
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 Opcodes
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.
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.
Initial connection
Upon making a WebSocket connection, the server will immediately begin sending NOPs, which will continue for the duration of the connection.
The client must first acquire a username, through the use of the rename opcode specified below.
The client may now get a list of all VMs on the server using the list opcode, or if it already knows the VM ID, it may immediately connect with the connect opcode.
Opcodes
list
Get a list of all VMs running on the server. No parameters.
Response
The server will respond with three arguments for each VM:
ID: The ID of the VM
Name: A display name for the VM. May contain HTML.
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.
connect
Connect to a VM
Parameters
ID: The ID of the VM to connect to. Can be retrieved with the list opcode.
Response
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.
Server-to-Client Opcodes
adduser
Sent to indicate that one or more users have joined the VM. This will always be sent on connection.
Parameters
The server will send two parameters for each user:
Username: The username of the new user
Rank: The rank of the user as an integer (see the Staff section).
remuser
Sent when one or more users leaves the VM.
Parameters
Number: The number of users who have left
Username: Username of the user who left. Repeated for each user if there are more than one
rename
Sent when a user changes their username.
Parameters
Parameters if the client's username is being changed, either by their use of the rename opcode or by staff:
0: This parameter will always be 0 and is used to differentiate between the client being renamed and another user
Status: This parameter is used for the status of the rename. It can have one of the below values:
| 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. |
Username: The client's new username. This will either be the requested username, or one generated by the server if a new username was not specified or was rejected for one of the reasons above.
Parameters if another user is being renamed:
1: This parameter will always be 1 and is used to differentiate between the client being renamed and another user
Old Name: The user's old username
New Name: The user's new username
chat
Sent when another user sends a chat message.
Parameters
This opcode will mostly have two parameters. However at the beginning of the connection, the server will send a chat history, containing the below parameters for each message.
Username: The user who sent the chat message.
Message: The chat message. The server MUST HTML-sanitize the message, otherwise this poses a severe vulnerability to users.
size
Used to indicate the screen size of the VM. This will be sent after connecting and after any resolution change on the VM.
Parameters
Layer: This will always be zero (for the screen) on current server implementations. Some servers may implement other layers such as virtual mouse. Clients are not obligated to support these.
Width: The new width
Height: The new height
png
Used to update the VM screen. The server will send one initial PNG message containing the entire screen on connection, and after that will send a dirty rect for each update
Parameters
mask: This will always be zero on current server implementations.
layer: This will always be zero (for the screen) on current server implementations. Some servers may implement other layers such as virtual mouse. Clients are not obligated to support these.
x: X-axis position of the rect
y: Y-axis position of the rect
data: The base64-encoded rect. This may be either PNG or JPEG and can be determined through magic numbers or headers.
vote
Sent when a Vote-to-reset on the VM updates
Parameters
Status: The status of the vote. Values:
| 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. All below parameters will be omitted. The server may send the result in the chat. |
| 3 | Sent if the client tried to start a vote, however there is an active cooldown. Only the time parameter is given. |
Time: 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.
Yes: The number of users who have voted in favor of resetting the VM
No: The number of users who have voted against resetting the VM
turn
Indicates an update of the VM's turn queue
Parameters
Turn time: How much time is left on the current user's turn in milliseconds.
Queue count: The amount of users in the queue.
Queue: Each user in the queue given as separate parameters
Waiting timer: How much longer until the client will get a turn in milliseconds. Only sent if the client is waiting.
Client-to-Server Opcodes
Rank
CollabVM has three ranks:
0: Unregistered. The default rank with no permissions that all users have prior to logging in.
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.