Raccoon Message Server

The Raccoon message server is responsible for maintaining information about
a collection of "topics." Each topic consists of "notes," which are each
documents in the RFC822 format. In general, a Raccoon server is used for a
specific administrative domain, where particular standards and guidelines
are enforced.

A Raccoon server may also be used to host the Jalot system. Within Jalot,
threaded topics are used as task lists, and threads within a topic are
used as tasks.

Commands are given as a one-line command, followed by a one-line response
from the server.  Each response is prepended by a 3-digit number called
a response code.  Response codes between 200 and 299 are considered
"success" responses.  Responses between 300 and 349 are considered
"success" responses, and the server will send additional lines of
response. Responses between 350 and 399 are consider "proceed" responses
-- the server accepted the command and is expecting additional input
from the client.  Responses between 400 and 499 are considered user
errors.  Responses between 500 and 599 indicate server errors, either
because of an internal problem with the server or because the specific
command is not implemented.  Responses between 800 and 899 are
asynchronous messages, and are described in the XMessage Protocol
document. If a client does not enable XMessages, then the client will
never receive an asynchronous message, and does not need to handle them
correctly.

The additional input for the 300 response codes are given as additional
lines of input.  The end of the additional lines of input are marked by
a line containing only a period (".").  If a line begins with a period,
then the sender prepends a period and the recipient removes the period.
For example:
    Server: 302 Note body follows \t noteno:1
    Server: From: Tanj
    Server: Formal-Name: lbrintle-isca/Tanj/Lee Brintle
    Server: Date: Fri, 03 Feb 2006 02:12:51 GMT
    Server: Subject: Changed Owner
    Server:
    Server: lbrintle-isca/Tanj/Lee Brintle
    Server: is new owner of task
    Server: ..tricky line
    Server: The above line should be read as ".tricky line"
    Server: .

Unlike the HTTP protocol, the Raccoon protocol is stateful.  Gateways
exist between stateless protocols and the Raccoon protocol.

Raccoon uses many "tag/value" pairs, where a tag is sent, followed by
a colon, followed by a value. This document describes plain-text messages;
all clients and all servers are required to both understand and handle
the plain-text versions of notes and other bodies of data.  Further, a
client who extends the functionality to handle other formats -- such as
HTML -- are still required to provide a good, plain-text version of the
data to clients who do not request the extended type.

In general, a command consists of a command word, a target, and optional
parameters appended to the end of the command, separated by tabs.  This
allows the protocol to be expanded and for clients and servers to discover
mutually-implemented extensions.  A response is a 3-digit response code,
a local human-readable explanation of the response code, and zero or more
tab-delimited tag/value pairs.  If a command has a variable type of
response, The tag portion of the first pair is usually omitted.

In this document, the string " \t " represents the tab character.  That
is, the example string:
    Server: 202 Cannot process login \t Invalid password
means that after the "login" portion of the response is an ASCII 9
character followed by the string "Invalid password".  The spaces are
there for readability purposes.

There are many locations where a user's identity is given.  Raccoon
defines a "formal name" as being a three-part tuple, separated by
'/' characters:
     accountid/handle/real name
The accountid is authentication-specific and permanently and uniquely
identifies the user. The handle is a unique display name requested by
the user which may change over time. The real name is either the real
name of the user or the special value "(hidden)", indicating that the
user does not wish his or her real name to be displayed.  The real name
may contain a '/' character.

Welcome banner

Upon connection and without client input, a Raccoon server sends a welcome
response; a successful welcome means that the server is available for
login and commands. A 400-level error indicates that the client does
not have permission to access the server, and a 500-level error indicates
that the server is unavilable for some reason.
    Client: <connect>
    Server: 200 Server started

LOGIN username \t password

Logs the specified user into the system. The authentication information
may vary from system to system. Possible options include actual
name/password values or authentication information from single signon
systems such as Bamboo or Passport.
    Client: LOGIN Gestalt \t testaccount
    Server: 202 Logged in \t handle:Gestalt \t flags:sysop

    Client: LOGIN Gestalt \t badpassword
    Server: 405 Cannot process login \t Invalid password
Common tag/value pairs in resposne: handle, flags

LIST [target [filters]]

Returns a list of topics within the server, filtered by an optional
argument. The default listing is "public"; only non-private topics are
listed.

Target is one of: ALL, PUBLIC, PRIVATE, TODO, JOINED, NAMED, THREADS.
Filters include "owner" and "flags".

Joined topics are defined as any topic that the user issued a "SETRC"
command with a non-zero argument. To-do topics are defined as any topic
that has any note equal to or higher than the most recent SETRC value.
Raccoon supports moderated topics, where the server may not list topics
as being "TODO" until the new notes have been approved.

Each topic is returned on its own line, with "topic" and "name" as
required tag/value pairs.  A topic is a unique numeric identifier for
the topic, and must fit within an unsigned four-byte number. Other
optional tag/value pairs include:
    desc          A longer, more descriptive version of the topic name
    firstnote     The lowest available note
    lastnote      The highest available note
    maxnote       The highest actual note
    internalid    A server-specific string identifying the topic
    flags         A comma-seperated list of flags.  Possible flags include
                  private, nosubject, moderated, threaded, cananon,
                  forceanon, autojoin, closed.  Any flag may be prepended
                  with "no" to indicate explicitly that the flag is not
                  set; for example "noprivate" means a public topic.
    todo          The number of notes equal to or higher than the user's
                  current SETRC value, or 0 if the user has no SETRC
                  value.  This number may be an approximation.
    owner         The current owner of the topic. Within Jalot, the owner
                  of a thread (task) is the person currently responsible
                  for that task.
    parenttopic   In threads, this '/'-delimited string indicates which
                  parent topic and which note in that topic was the start
                  of this thread.  For example, "parenttopic:409/142"
                  indicates that this thread contains replies to post
                  142 in topic 409.

Which tag/value pairs may vary depending on the type of command.

    Client: LIST PRIVATE \t owner:Tanj
    Server: 301 Topic list follows
    Server: topic:0 \t name:Raccoon \t
            desc:The starting place for conversation \t firstnote:0 \t
            lastnote:0 \t internalid:96 \t maxnote:0 \t
            owner:lbrintle-leepfrog/Tanj/Lee Brintle
    Server: .

TOPIC { topicname | topicid }

Sets the current topic to either the specific topic topicid or a topic
whose name either exactly matches topicname or, if no topics match exactly,
a topic whose name is "similar" to topicname; the definition of "similar"
is left up to the implementers of the server.  The response to the command
contains a tag/value list similar to the results of a LIST command.

    Client: TOPIC 0
    Server: 204 Topic set to: \t topic:0 \t name:Raccoon \t
            desc:The starting place for conversation \t firstnote:0 \t
            lastnote:0 \t internalid:96 \t maxnote:0 \t
            owner:lbrintle-leepfrog/Tanj/Lee Brintle

READ [ > | < ] noteno [DAMMIT]

Return an RFC822 (SMTP) formatted note from the server. If the optional
"directional" characters ">" or "<" are specified, then the next or prior
non-deleted note in the specified direction is returned. If the DAMMIT
argument is specified and the user has permission, then the contents of a
deleted note are returned. The DAMMIT form will also return the author of
an anonymous post, if the reader has permission.  The tag/value "noteno"
is required, which indicates which note was actually returned from the
server.  This is required even if the "<" or ">" arguments were not used.

As with all RFC messages, the header is separated from the body by a
single blank line.
    Client: READ >1
    Server: 302 Note body follows \t noteno:1
    Server: From: Tanj
    Server: Formal-Name: lbrintle-leepfrog/Tanj/Lee Brintle
    Server: Date: Fri, 03 Feb 2006 02:12:51 GMT
    Server: Subject: Interested groups?
    Server: Replies-Thread: 100032
    Server: Replies-Count: 0
    Server:
    Server: Anyone interested in writing a gateway between YIM and
    Server: the x-message server should contact me.
    Server: .

POST

Adds a note to the current topic. Unless the "nosubject" flag is set for
the topic, the subject line of the post is specified using the "subject:"
argument. If the user wishes to post the note under a particular
administrative authority, the authority may be given by using the
"authority:" arugment. Typical authorities are "Sysop" or "Topic
Administrator". If an inappropriate authority for the current user is
specified, the authority is silently removed.

Typical command tag/value pairs include "authority", which allows
moderators or administrators to make administrative notes; and "flags",
which contains flags such as "anonymous" or "noreply".

The server provides the entire header of the note; only the body is passed
by the client to the POST command.  The sucessful reply will contain a
value of the newly create not number; other tag/value pairs may be
provided.  If the topic is threaded, a tag/value pair in the response will
include "replythread", which is the topicid of the topic which will contain
replies to the new post.  The server will automatically set the RC value of
the new note's reply thread to 1 for the author.

SETRC rcval

The RC value of the current topic for the current user is set to rcval.
The RC value is used by the server in at least four ways:
  - Topics with a non-0 RC value will be show in the LIST JOINED command
  - Topics who have a lastnote greater than or equal to a user's RC value
    for that topic are displayed in the "LIST TODO" command
  - If the "todo" tag/value pair is included in a topic listing, it is
    based on the RC value.
  - It is the value shown with the "SHOW RCVAL" command, which the client
    may use as it wishes.
An RC value of "0" means that the user is no longer interested in this
topic.

This is a way to store client-specific information on the server; the
server can send only the information to the client that the client is
interested in, and can be used when a user uses multiple clients to access
the same server.

Note that the value is not the most recent note, it is one *beyond* the
most recently read note.  For example, if the user has read notes one
through three, the client would typically set an RC value to four -- the
next highest note.

SETT permission username newperm SETT defperm newperm

Sets the permissions for a specific user, or the default permissions for
all users. Permissions can be any combination of: read, post, join, delown
(delete own notes), delall (delete anyone's notes), approve, admin, none,
all, or basic. Basic means "whatever is typical for this server," and is
usually read, post, join, and delete own.

SETT fieldname newvalue

Changes a specific field for a topic, where field is one of the following:

     Fieldname    Function
     name      Name of the topic
     admin     Primary topic administrator
     desc      Short topic description
     info      Long (multi-screen) topic description
     postmsg   A hints message for users who post to the topic
     setflag   Sets a flag, see below for available flags
     clrflag   Clears a flag set with "setflag"

Flags for a topic include:
  isprivate    Users may not access the topic unless invited
  nosubject    Posts do not include subject lines
  moderated    Notes must be approved before typical users can read
  threaded     When a post is made to a threaded topic, a new topic is
               automatically created to hold the replies to that note.
  cananon      Users may choose to post anonymously to this topic
  forceanon    All posts will be anonymous
  autojoin     A new user is automatically joined to this topic
  closed       No new posts may be made to this topic

SHOW { rcval | topic | info | defperm | permissions | joined }

Show the current value of various topic settings. The "rcval" argument will
return the value most recently used in the "SETRC" command.  Topic returns
the same information as the TOPIC command.  Info returns an RFC-822-style
note containing information about the topic set by SETT INFO.  Defperm
lists the default permissions; permissions lists the permissions of the
listed user.  Joined lists all of the users who have a non-zero SETRC
value.

DELETE NOTE noteno

Delete note noteno. The contents of the note may still be accessible by
using the DAMMIT argument to the read command, although the permissions and
ability will vary depending on implementation.

DELETE TOPIC

Deletes the current topic. Future topics created will have a different
internal number, but the topicid is permitted to be reused.  It is up
to the server to determine what happens to RC information if a topic is
deleted and a new topic is created with the same topicid.

MAKE

Creates a new topic in the system. The default values for the topic vary
from system to system.  Required Command tag/value pairs include "name"
and "desc", which is a longer version of "name".  Other tag/value pairs
include "flags".

OKAY action

Requests a permissions check for a particular operation, without actually
executing the operation. Useful for checking for posting permissions before
allowing the user to compose a post, for example.

The argument may contains additional data; for example: "OKAY MAKE Lobby"
will return false if a new forum named lobby cannot be created. Another
example is "OKAY delete note 123", which will check to see if it is okay
to delete that particular note.

QUIT

Quits the system.