CVE Network Protocol

by Clinton Jeffery, with help

This document describes version 0.3 of the CVE Network Protocol as of 3/11/10. The document has historically served as a design (read: wishful thinking) document, which the implementation has never achieved. Various additions to the implementation have not been incorporated here, limiting the usefulness of this document. This situation is under repair.

At present CVE uses an ASCII, line-oriented human-readable text protocol, similar to a chat or MUD protocol. At present, CVE uses TCP only. At present, CVE is a monolithic server.

Requirements

The CVE protocol has the following requirements:

The protocol must support a rich set of chat capabilities: chat in room, chat in interest groups, chat with everyone...
The protocol must support a rich set of interactions with the virtual environment. Supported interactions include avatar motion and actions, manipulation of whiteboard/chalkboard, etc.
The protocol must support a rich set of interactions with computer science educational applications, such as text editors and compilers. These tools will be integrated into the environment; we do not have to work with existing tools unmodified.
The protocol must be somewhat concise. Later versions may include compression on large packets.
The protocol must be somewhat secure. Later versions may include encryption. More likely, we will use ssh tunnels.

Design

The protocol design section should include syntax of messages in general; sort of the general packet parsing. It starts with


\command arguments* \n

Most commands are short, but some commands are quite long, including tasks such as sending messages with many text lines in them. Newlines are escaped (or mangled, if you prefer) in such messages. TCP does not guarantee delivery of an entire command in a single packet. The client and server must queue up incoming unfinished commands until their newline is received. Multiple commands are generally batched into a single packet in order to reduce OS overhead.

Protocol Message Types by Example

These examples convey the flavor of the protocol. This list is not complete nor entirely correct. Things that are/were planned but not implemented should be moved down to the future work section.

Some of these items are really local client commands, not network protocol commands. For each command we need to ask: does it need to go the server? and then: which client(s) should the server forward it on to? and then: does it require a reply, and if so, from whom? Lastly: for each command, does it require that the server remember the state change and store it in a database?

Every command can be abbreviated by a unique prefix. Common commands can be abbreviated with nonunique prefixes. Each client avatar has a current default command which executes for lines not beginning with \.

Chatting

Example	Description
\say hello	chats to the current room
\tell joe hello	chats to a specific person
\tell groupname hello	chats to a specific group
\tell sessionname hello	chats to a specific session
\group hello	chats to the current group
\sig hello	chats to the current special interest group
\course hello	chats to the current course
\emote	a supposedly non-verbal

Establishing groups

There are the following types of grouns:

session: A session is a temporary membership chat group for the current-session. An ICI collaborative file-editing session ought to be (but is not yet) a special case of this which has associated files being edited.
sig: This is the persistent membership, generic chat group
course
This is a persistent membership group with extra structure and permissions for academic courses.

Example	Description
\invite	invite (currently selected person) to join group
\disband	disband current group
\groups	list my groups
\lsgroups	list all groups
\makesig unicon [closed]	Create a special interest group. The default is an open sig. An optional parameter would create a closed/moderated sig. Closed is the default for all types of groups other than sigs.
\makecourse cs371	create a course
\sig=unicon	sets the current/default special interest group you are sending to
\unicon	sends a message to any sig by name
\join unicon	join (subscribe to listen) a sig
\course cs371	sets the current course you are sending to
\ignore joe	discard all messages from user joe

A discussion on 12/19/05 produced the following

Example	Description
\createsession sessiontype sessionname	create a (temporary) group
\createsession sessionname sessionid	server assigns id to created (temporary) group
\destroysession sessionname	destroy a (temporary) group
\subsession sessiontype sessionname	create a subgroup
\invite sessionname username(s)	client invites user(s) to join group
\invite sessiontype sessionname	server forwards invitation to user(s) to join group
\join sessionname	accept membership
\decline sessionname	decline membership
\leave sessionname	exit membership
\dismiss sessionname username	kick someone out
\listsessions	client requests
\listsessions ssnname, ssntype, ssnname, ssntype, ...	server responds
\listmembers sessionname
\requestcontrol sessionname
\releasecontrol sessionname
\givecontrol sessionname username

Avatar and environment manipulation

Example	Description
\goto 0,0,3.5	move to (x,y,z)
\goto sh371	move (teleport) to sh371
\look	get a 2D detailed look at nearest 2D object
\look board	get a 2D detailed look at the nearest whiteboard
\look screen	get a 2D detailed look at the nearest PC screen
\look up	go back to 3D view
\look 0,0,3.5	(turn and) look at (x,y,z)
\pen red	set the current pen to red
\whiteboard sh118b-a	set/lock the current whiteboard to sh118b-a
\draw 50,50	set (x,y) on the nearest board to current pen color
\drawline 50,50,55,30	draw line from (x,y)-(x2,y2) on the nearest board to current pen color
\fillrectangle 50,50,10,10 fill rectangle from (x,y) with (width,height) on the nearest board to current pen color
\erase	erase the nearest board
\door	toggle nearest door more open or closed
\hand	toggle (raise/lower) hand
\follow	follow the currently targeted user
\voice [on off]	enable disable realtime microphone
\sound [on off]	enable disable realtime speaker
\video [on off]	enable disable realtime videocamera feed

File Transfer

Example	Description
\putfile dat/avatars/curtis.avt 206	dat/avatars/curtis.avt is the file to upload, and it is 206 bytes. Immediately after the newline (after the 6) the actual contents of the file (ASCII or binary; use writes()/reads() for no newline-handling) would be sent.
\getfile dat/avatars/curtis.avt	this asks the server to execute a \putfile

Issues:

for large files, break reads/writes up into chunks and service other active connections while transfer is in progress. Under such a circumstance, connection/session manager has to remember for a given connection that it has a file transfer in-progress and new data is not a new command.
permissions model: do not allow this at chat command line!
private file transfer: \putfile userid dat/...

Miscellaneous

Example	Description
\quit!	exits immediately
\exit	exits with a grace period
\afk	marks you as away from keyboard
\who	show who is on the system
\loc	shows your current location
\log [on off]	turns on/off your private recorder
\cmd say	sets the default command to \say

Teacher/lecture tasks

Example	Description
\give joe pen	give joe permission to draw on the board
\give joe voice	give joe permission to speak
\give joe legs	give joe permission to move
\take joe ...	remove students' specific permissions
\stop joe	remove all of joe's permissions, he is paralyzed

Administrator tasks

Example	Description
\enroll joe cs371	adds joe to a class
\kill joe	dumps joe out of the application
\lock joe	prevents joe from logging in any more

Collaborative IDE and Browser Protocol

Issues:

two sources of changes need to be transmitted: changes from the textlist (or editabletextlist, or htmlbrowser) widget, and changes from the scrollbar. Except: scrollbar changes already propagate to the textlist widget, so perhaps we can catch them there.
commands messages vs. content messages
how often do commands synchronize?
who is keeping track of who-all is in the collaborative session
who is keeping track of who owns the write "token"
commands for requesting and releasing the write "token"
Refactoring of groups to support: chat, voice, and browsing/editing groups
Invitation-based session creation.

Future Work

UDP

Those interactions which are transient (e.g. avatar motion) are appropriate for a UDP subsystem.

Model Editing

The purpose of a Model Editing subsystem in the protocol is to allow dynamic changes to the CVE model to be seen by others. A module that is of particular interest in planning for such a protocol is model/CVEBuilder.icn, which reads/parses .dat files and constructs virtual objects from them. Some basic issues include:

should a single server process support multiple models, such that someone can login to model A and within it, create a model B.
how to error check each creation or edit
whether to bundle certain edits explicitly in the protocol. For example, suppose you push a wall to increase a room's size -- the room(s) behind the wall should probably shrink correspondingly, or reject such an edit.

Editing Message Description
\make class name params create a new virtual object
\move name params alter coordinates of virtual object
\edit name param=val ... alter attributes of virtual object
\texture dat/uidaho/jeb121/sign.gif ... upload a texture

Editing Message	Description
\make class name params	create a new virtual object
\move name params	alter coordinates of virtual object
\edit name param=val ...	alter attributes of virtual object
\texture dat/uidaho/jeb121/sign.gif ...	upload a texture

Examples:

\make Room bedroom5 13.2 0 11 5 3.3 4.4
(          name       x  y  x w  h   l  texture (defaults) )
\edit bedroom5 floor=floor.gif