MOO CLIENT REQUEST PROTOCOL

Erik Ostrom, Dave Van Buren, Pavel Curtis, David Nichols, Jay Carlson

22 Feb 1993

Conversion to `help help-format' 21 May 1994 by Jay Carlson.

(Any first-person pronouns refer to Erik.)

AUTHENTICATION

An authentication key is generated and uploaded by the client to the server at login. Proposed method:


  #$#authentication-key <key>

This requires that the server be compiled with OUT_OF_BAND_PREFIX set to "#$#". (It's actually possible to do it as a verb on $player, but many MOOs have a programmer command "#" which does something very different.) The authentication key may not contain spaces, double-quotes, colons, or backslashes.

GENERAL RULES

String sent by server:


  #$#<request-name><*-if-data-follows> [<auth-key>] <keyword>: <value> ...

An identifying tag #$# is placed at the beginning of the request line.

<request-name> is the type of request, e.g. "edit" or "ftp".
<request-name> cannot contain spaces, double-quotes, backslashes, or asterisks.
<*-if-data-follows> is either "*" if this request is followed by additional lines of data, or the empty string.
<keyword> is the name of an argument to the request. Keywords cannot contain spaces, double-quotes, colons, or backslashes.
<value> is the value of the corresponding argument. A <value> can contain any printing ASCII character (including space), but must be quoted in the standard MOO style (with double quotes, using backslash to escape quotes and backslashes) if it either contains spaces or is the empty string. Arbitrary order of keyword: value pairs is allowed.

Keyword: value pairs may be optional. We haven't discussed what clients should do with unrecognized keywords; my plan is for the client simply to ignore them and work with the keywords it recognizes.

REQUEST DEFINITIONS

edit

Type of information. Clients may or may not be able to use a special editing mode depending on type.

name: <name>

User-friendly indication of what's in this. Good for buffer name.

upload: <command>

Command to use to begin upload of this text.

ftp

host: <name>

Name of the host that has the document.

directory: <dir>

Name of the directory that the document is in.

file: <name>

Name of the file within the directory.

type: <type>

Type of document. Current types include ($ftp.recognized_types):


      {"ascii", "binary", "fits", "plaintext", "postscript",

       "compressed", "tar"}

destination: <dir>

Place to store the document locally. I don't fully understand this.

gopher

(Larry has a local-gopher protocol--this is my attempt to render it into the New Protocol.)

host: <name>

Name of the host to connect to.

port: <number>

Port to connect to. Default is 70.

path: <string>

String to send to the gopher server. Default is the empty string.

description:

Description string. First character is the type character, rest of characters are human-readable name of object. This seems unnecessarily arcane to me--why not separate these?

EXAMPLES

A request to provide an editing session for a property. The request is followed by lines of data, prepended with a special tag (@@@, unless someone has strong feelings about changing it), and marked at the end with another tag (#$#END, again subject to change). The advantage of this over dot-quoting is that it should be fairly easy for the client to figure out if there's been some breakage on the server end and the transmission has terminated early. (A line that doesn't start with @@@ and isn't #$#END should set off warning bells.)


  #$#edit* 12345678 type: text name: Dave.test upload: "@set-note-text #75.test"

  @@@This is a test.

  @@@

  #$#END

A request to provide an editing session for a verb.


  #$#edit* 12345678 type: program name: Dave:test upload: "@program #75:test none none none"

  @@@player:tell("This is a test.");

  #$#END

A request to upload a file from an anonymous ftp site. The request line contains all the data necessary.


  #$#ftp 12345678 host: ipac.caltech.edu directory: /pub/deposit file: mud.el.Z type: "compressed ascii" destination: clients/mud.el.Z

A request to retrieve a document from a gopher server.


  #$#gopher 12345678 host: gopher.gac.edu description: "1Gustavus Adolphus College"

In this case, we take advantage of default values for the port: and path: arguments ("70" and "", respectively).