YO protocol V1.2
================
The YO (Yell at Object) protocol defines the format and content of
messages that may be passed between severs on a distributed MUD. It
does not ferry objects around, as the OIF protocol does, but instead
defines the messages that may be passed between objects.
COOLMUD users and programmers do not need to know the YO protocol
to program or use COOLMUD. This document is intended for people
who want to know the internals of the COOLMUD system.
YO packets consist of 7 parts: the message id, age, player object,
from object, to object, message, and arguments. Any object can send
any other object a message, but it must be directed to the appropriate
server. Any messages which do not conform to this format may be
silently discarded.
Here's a dissection of a typical YO packet:
3245 0 #3@joemud #7@joemud #9@fredmud "tell" { 1 "howdy" }
^ ^ ^ ^ ^ ^ ^
| | | | | | |
msgid age player from to msg args
Msgid
-----
This number uniquely identifies the message, as designated by the
_sending_ server. Message id's are usually 32 bit ints, generated
incrementally. If MAXINT is exceeded, the sending server may start
again at zero. Each server is only responsible for ensuring
uniqueness of the messages it sends. Reply messages use the same
msgid as the message they are replying to (see Reply Messages, below).
Age
---
This is an integer field representing the depth of messages which
have been passed. It's designed to prevent two servers spamming
each other by sending mutually recursive messages. Each execution
thread starts with an age of 0, which is incremented every time a
new message is generated. If the age reaches MAX_AGE, the error
E_MAXREC is raised and the message is discarded. Generally, the
'age' of a message is only set to zero by the server when a new
'parse' message is generated (ie., for each player command).
Player
------
This is the object id of the player who is performing the current action.
From
----
This is the object which sent the message.
To
--
This is the object to which the message was sent.
Msg
---
This is a string containing the name of the message. Messages should
be a valid identifier: one word, no spaces, beginning with an
alphabetic char or '_', subsequent chars being alphanumeric or '_'.
Args
----
These are the arguments to the message, represented as a list.
Reply Messages
==============
All normal messages must receive one of two replies:
"return" - normal return
"raise" - an error occurred
One of these two messages should be generated for each normal
message sent. Reply messages do not need to be replied to,
obviously. The reply message should have the same msgid and age as
the sent message.
Return
------
Execution completed normally, and a return value is indicated.
There should only be one argument, which is the return value.
Raise
-----
An error condition has occurred in the 'To' object. There are two
arguments to this message: the error value, and a traceback from
the object giving diagnostic information. An object which receives
this message as a reply can choose to continue, or to halt
execution. If execution is halted, it should send 'raise' to its
caller, and add its diagnostic information to the traceback string.
DATATYPES in YO 1.2
===================
There are five basic datatypes in YO messages: number (integer), string,
object, lists, and errors.
NUM
---
Numbers are integer values represented simply by their ASCII
representation. No decimals or exponents are allowed. The "msgid"
and "age" fields are examples of number values. Examples:
5
-3
0
1000
STR
---
Strings are enclosed in double quotes, and may be any length. Strings
may also contain embedded double quotes using the backslash character
(\"), embedded tabs ("\t") or newlines ("\n"). The literal " and
newline characters cannot be used.
"foo"
"The Rain In Spain"
"They call me \"The Woodmaster\", son."
Notice the embedded quotes in the last example. This would evaluate
to:
They call me "The Woodmaster", son.
The "message" field of the YO packet is an example of a STR value.
OBJ
---
Object values consist of two parts: an object id, and a server id. Object
values are preceeded by a # sign, and an '@' sign separates the objectid
and server portions, like so:
#5@coolmud
The object id is a number, and the serverid is the name of the
server. Each server maintains a mapping between these names and the
IP address and YO port of the server. Two communicating COOLMUDs
must agree on the names of all servers involved. The "player"
"from" and "to" fields of the YO packet are examples of object values.
LIST
----
A list value is a heterogenous collection of any of the 5 data
types. Braces surround the elements of the list, and a number
after the opening brace indicates the length of the list. Spaces
separate the elements of the list. Each element's type is
determined implicitly by the first character: a digit indicates a
NUM value, a doublequote indicates a string value, a # sign indicates
an object value, a brace indicates a list value, and an E indicates
an error value. The following are examples of lists:
{ 5 1 2 3 4 5 }
{ 2 #3@coolmud #10@coolmud }
{ 3 "abc" "def" "ghi" }
{ 2 { 1 "foo" } { 1 "bar" } }
{ 5 1 "two" #3@coolmud E_NONE { 1 "foo" } }
Notice that values of different types may be freely intermixed, as
in the last example, and that lists may contain other lists. The
arguments portion of the YO packet is an example of a list value.
Note: Lists are the only type whose YO representation differs
from their COOL representation. In COOL, items in a list are
comma-separated, and there is no leading length value.
ERR
---
Error values are represented as an identifier with E_ as the first
two characters. The following is a list of errors currently
recognized by YO 1.2:
E_NONE no error
E_TYPE type mismatch
E_RANGE range error
E_DIV division by zero
E_INVIND invalid indirection
E_MAXREC maximum recursion exceeded
E_METHODNF method not found
E_VARNF variable not found
E_STACKUND stack underflow
E_STACKOVR stack overflow
E_FOR for variable not a list
E_INTERNAL internal server error
Stephen White
16 July 92