Suggestions for CSTP - CoSy Transfer Protocol
Draft 4 - 12 September 02


Copyright © 2002 by Alastair J.W. Mayer. All rights reserved.
Note: This document is a working draft and almost certainly will change. To ensure non-proliferation of out-of-date copies, reproduction is strictly prohibited except for making a personal copy for use in conjunction with CoSy development.


Changelog - Draft 4


Introduction


This view of the system has minimal state, essentially a valid user is connected or not. Details about the user/session is kept in a 'user context' object on the server.

Most commands consist of a keyword or keyword and modifier, plus parameters which depend on the command.

Functions which can be carried out entirely on the client side (e.g.editing a message) have no representation - editing is handled by uploading (possibly preceded by downloading) the relevant file, using the appropriate command. This also includes most option settings, which belong in the client side.

The following assumes that CoSy mail will be superseded by a straight SMTP-based system, although we might want to provide hooks into that from here. Or not.

A quick list of commands (requests):


(NOTE - with the combining of "conf" and "conf/topic" into "pathname", I'm stuck for some good noun to use as the modifier (ie "new conf" and "new topic" become what?). For now I've used "OBJECT" (eg "new object") to distinguish from USER, but I'm open to better suggestions.)


The meaning and possible error and successful results for each request is detailed further below.


Session level commands:
LOGIN user password
QUIT


Admin level commands:
NEW USER user {xml user object follows}
DEL USER user {confirm}
GET USER user
CHANGE USER user {xml user object follows}
DEL OBJECT pathname {confirm}


Moderator level commands:
NEW OBJECT pathname {xml conference or topic object follows}
ADD USER pathname user
REM USER pathname user
CHANGE OBJECT pathname {xml topic (or conf) object follows}
REM OBJECT pathname {confirm}
TERMINATE pathname {confirm}

Read commands:
GET MESG pathname ('all' | (ID1 [ID2])
GET HDRS pathname ( 'all' | (ID1 [ ID2 ]))
GET PART pathname startbyte [ endbyte ]
GET THREAD pathname
GET ROOTID pathname ID
GET DATEID pathname date
POST MESG pathname parent_ID {message body follows}
WITHDRAW pathname ID
SEARCH pathname target [ ID [ ID ]]
SET COUNT pathname ID
SET MAP pathname {message-read bitmap follows}


Join commands:
REGISTER pathname
RESIGN pathname

Show (list) commands:
SHOW ALL [filter]
SHOW NEW [filter]
SHOW USERS pathname
SHOW MINE
SHOW STATUS pathname
SHOW RESUME user
SHOW INFO pathname



Following are user settings commands:
GET PROFILE
GET RESUME
POST PROFILE {object follows}
POST RESUME {object follows}
SET PASSWORD password {text follows}


Confirmation response:
YES
NO


Status codes returned:


In this draft the return codes are not well defined. Specifically they are not normalized, as shown below the same return code may be used for several different things depending on the request. This will change.


In general the result codes will fall into the following ranges (this is modelled after common internet practise).


100-199   Information message, server metadata
200-299   Success
300-399   Okay so far, send more information
400-499   Error, might work with different arguments
500-599   Error, don't try this again


Note in addition to error returns listed below, the system may also return unexpected errors for example due to server data corruption, hardware problems, etc. Similarly an error for an unrecognized command or a syntax error could be returned.


Numeric list of return codes and meanings:


Some of these may be unnecessary with a move to a unified object (ie path vs conf/topic) model. Others may not really be necessary (over detailed or redundant.)


100   Connection made


200   OK
201   OK, data follows
202   OK, no data   (in response to a request which might return data, but nothing matching found (eg a search))
221   OK, bye
251   OK, request canceled (in response to a negative confirmation)


350   OK, send data
351   Are you sure?


400   Authorization failed
405   Not a member of conf/topic
411   No such conference
412   No such topic
413   No such message
414   Conference closed
440   Conference already exists
441   Topic already exists
450   User exists
451   Malformed object
452   Object data out of range
453   Missing required data
454   Start is past end
455   Date is in future
461   No such user


500   Unrecognized request
501   Bad request syntax
502   No privilege
505   Not implemented
509   Server error
599   Sever internal error   (eg out of memory, etc)


Command (request) explanation:


Initial TCP/IP connection established.
Normal Return
   100 CSTP 1.0 Greetings


NEW USER user {xml user object follows}
Create a new user named on the system. User object should be correctly populated.
Error Returns:
   502 No privilege
   450 User exists
Normal Return
   350 OK, send user object
      Error Return
         451 Malformed user object
         452 data out of bounds
      Normal Return
         200 OK, user created




DEL USER user {confirm}
Delete the user from the system
Error Returns
   502 No privilege
   461 No such user
Normal Return
   351 Are you sure?
      Normal Return
         200 OK, user gone
         251 OK canceled


GET USER user
Get meta info (user object) for user
Error Returns
   461 No such user
Normal Return
   201 OK, Here you go {xml user object follows}
Sample output: 
GET USER al
201 OK, data follows
<userinfo name='al'>
  <realname>Alastair Mayer  </realname>
  <expire>2114495999</expire>
  <joined>978422399</joined>
</userinfo>


CHANGE USER user {xml user object follows}
Change user information (privilege, etc)
Error Returns
   461 no such user
   502 no privilege
Normal return
   350 OK, send user object
   Error return
      451 malformed object
      452 data out of bounds
   Normal return
      200 OK, done


DEL CONF conf {confirm}
Delete a conference from the system (or mark it deleted at least)
Error returns
   411 no such conf
   502 no privilege
Normal return
   351 Are you sure?
      Normal Return
         200 OK, conf gone
         251 OK canceled


LOGIN user password
Error return
   400 authorization failed
Normal return
   200 OK, logged on


QUIT
Normal return
   221 OK, bye

Moderator level commands:

NEW OBJECT pathname {xml conference (or topic) object follows}
Create a new conference or topic within an existing conf.
Error return
   411 No such conf (if creating a topic)
   440 conference exists
   441 Topic exists
   502 no privilege
Normal return
   350 OK, send details
      Error return
         451 malformed conf object
         452 missing data
      Normal return
         200 OK, created


ADD USER pathname user
Add a user to a conference (register the user in the conf)
Errors
   411 No such conf
   461 No such user
   502 Not authorized
Normal
   200 OK, added
   251 OK, was already a member {not added} (or just return 200?)


REM OBJECT pathname {confirm}
Remove a topic from a conference, or a conference from the system. (Note, this
doesn't actually delete it (the DEL command does this), just makes it invisible to all users.)
Errors
   411 No such conf
   412 No such topic
   502 Not authorized
Normal
   350 Are you sure
   Normal
      200 OK, done
      251 OK, canceled


REM USER pathname user
Remove a user from a conference (or topic)
Error
   411 No such conf
   412 No such topic
   461 No such user
   502 Not authorized
Normal
   200 OK


CHANGE pathname {xml topic (or conf) object follows}
Change topic metadata, or conference metadata (within a limited range of changes)
Errors
   411 No such conf
   412 No such topic
   502 Not authorized
Normal
   350 OK, send topic information
   Error
      451 malformed object
      452 bad data
   Normal
      200 Ok, changed


TERMINATE pathname {confirm}
End the conference (or topic) (make it readonly)
Errors
   411 No such conf
   412 No such topic
   502 Not authorized
Normal
   200 OK

Read commands:

GET MESG pathname ( 'all' | (ID1 [ID2]))
Get message(s) from conf/topic, either all of them or from message # ID1 up to (including) ID2, or just ID1 if no ID2.
Error
   405 Not a member of conf/topic
   411 No such conf
   412 No such topic
   413 No such message (ID1 or ID2 out of range)
   454 Start beyond end (ID2 < ID1)
   502 No authorization
Normal
   201 OK, here comes data {xml message object follows}
Sample output: 
GET MESG cosy_dev/tcosy 10
201 OK, data follows
<message
  topic='cosy_dev/tcosy'
  num='10'
  auth='al'
  length='129'
  created='981566168'
  subject='(null)'
  parent='7'
  comment='13'
  type='text/plain; charset=us-ascii'
>
<body>Okay, thanks.  I thought I had that in the Makefile but perhaps it worked
because of old object files that were not cleaned out.
</body>
</message>


GET HDRS pathname ( 'all' | (ID1 [ ID2 ]))
Get message header(s) rom a conference, either all headers or for msgs starting at ID1 until ID2. Same as GET MESG except no message bodies (<body>) are returned.
Errors
   405 Not a member of conf/topic
   411 No such conf
   412 No such topic
   413 no such msg
   454 start beyond end
   502 no authorization
Normal
   201 OK, here comes data {xml message header object follows}
(Note, a message header object is simply a message object with no body part.)
Sample: 
GET HDRS cosy_dev/tcosy 7 10
201 OK, data follows
<messageRange>
<message
  topic='cosy_dev/tcosy'
  num='7'
  auth='jralls'
  length='686'
  created='981522025'
  subject='(null)'
  parent='3'
  sibling='8'
  comment='10'
  type='text/plain; charset=us-ascii'
/>
<message
  topic='cosy_dev/tcosy'
  num='8'
  auth='dbetz'
  length='145'
  created='981551142'
  subject='(null)'
  parent='3'
  comment='11'
  type='text/plain; charset=us-ascii'
/>
<message
  topic='cosy_dev/tcosy'
  num='9'
  auth='al'
  length='423'
  created='981566001'
  subject='(null)'
  parent='5'
  comment='12'
  type='text/plain; charset=us-ascii'
/>
<message
  topic='cosy_dev/tcosy'
  num='10'
  auth='al'
  length='129'
  created='981566168'
  subject='(null)'
  parent='7'
  comment='13'
  type='text/plain; charset=us-ascii'
/>
</messageRange>


GET PART pathname ID [start [end]]
Get partial message #ID from conf/topic, optionally starting at byte start and going to byte end, defaults being first and last. If end is beyond the real end it is just ignored.
Error
   405 Not a member of conf/topic
   411 No such conf
   412 No such topic
   413 No such message
   454 Start beyond end
   502 No authorization

GET THREAD pathname
Get threading info for all messages in the given topic. Returns a list of all message numbers and their immediate parent message numbers.
Errors
   411 No such conf
   412 No such topic
   502 No authorization
Normal
   201 OK, here it is {xml thread object follows}
Sample 
GET THREAD gripes/nntp
201 OK, data follows
<thread entries='17'>
 <node num='1' orig='0'/>
 <node num='2' orig='1'/>
 <node num='3' orig='2'/>
 <node num='4' orig='1'/>
 <node num='5' orig='4'/>
 <node num='6' orig='4'/>
 <node num='7' orig='0'/>
 <node num='8' orig='6'/>
 <node num='9' orig='8'/>
 <node num='10' orig='8'/>
 <node num='11' orig='9'/>
 <node num='12' orig='0'/>
 <node num='13' orig='11'/>
 <node num='14' orig='13'/>
 <node num='15' orig='14'/>
 <node num='16' orig='14'/>
 <node num='17' orig='0'/>
</thread>


GET ROOTID pathname ID
If message # ID is in a thread, return the root of the thread (otherwise return ID, if it exists)
Errors
   411 No such conf
   412 No such topic
   413 No such message
   502 No authorization
Normal
   201 OK, here it is {data follows}


GET DATEID pathname date
Return the ID of the first message posted after date, or zero (or last?) if none
Errors
   411 No such conf
   412 No such topic
   455 Date is in the future (or 452 bad data?, or ignore (and return what? - 202 OK nothing found?))
   502 No authorization
Normal
   201 OK, here it is {data follows}


POST MESGpathname parent_ID {message body follows}
Add the following as a new message in conf/topic, as a comment to parent. (Start of new thread if parent==0)
Errors
   405 Not a member of conf/topic
   411 No such conf
   412 No such topic
   413 No such message
   502 No authorization
Normal
   350 OK, send the message {xml message data follows}
   Errors
      451 Malformed object
   Normal
      201 OK, added as {id follows}


WITHDRAW pathname ID
Mark the message as withdrawn. By whom depends on msg and authorization.
Errors
   405 Not a member of conf/topic
   411 No such conf
   412 No such topic
   413 No such message
   502 No authorization
Normal
   200 OK, withdrawn
   
SEARCH pathname target [ ID [ ID ]]
Search (an optional range of) messages within a conf/topic for the target. Return a list of hits. (This request needs further thought. The initial behaviour should probably be akin to current search.
Errors
   411 No such conf
   412 No such topic
   413 No such message
   502 No authorization
Normal
   201 OK, here's a list {followed by data}
   202 OK, nothing found


SET COUNT pathname ID
Mark all messages up to ID as read, all beyond as unread.
Errors
   411 No such conf
   412 No such topic
   413 No such message
   502 No authorization
Normal
   200 OK


SET MAP pathname {bitmap follows}
Mark messages as read, according to bitmap
Errors
   411 No such conf
   412 No such topic
   502 No authorization
Normal
   350 OK send data
   Errors
      451 Malformed object
      452 Bad data
   Normal
      200 OK


Join commands:

REGISTER pathname
Add the conf/topic to the connected user's list (ie, join/register the conf). Defaults to all topics if the path points to a conference. TBD if it points to something higher than a conferece.
Errors
   411 No such conf   (also returned if the conf exists but is type 'hidden', unless user is already a member of it)
   412 No such topic
   414 Conf is closed, and you're not a member
   502 No authorization
Normal
   200 OK, done
   201 OK, there's a welcome message, data follows


RESIGN pathname
Withdraw from the conference (all topics) or topic.
Errors
   4xx Not a member of conf
   4xy Not a member of topic
   5xx Not allowed to resign this conf (should this be a 400-series?)
   5xy Not allowed to resign this topic (should this be a 400-series?)
Normal
   200 OK, you're out of there

Show (list) commands:

SHOW ALL [filter]
Return a list of all conferences (systemwide), possibly just those starting with filter
Errors
   502 No authorization
Normal
   201 Open wide, here it comes {followed by data}
Sample: 
SHOW ALL sci
201 OK, data follows
<conflist filter='sci'>
<conf
  type='open'
  name='sciences'
  description='The sciences conference. Come explore the world.' />
</conflist>


SHOW NEW [filter]
Return a list of conferences, topics that the user is a member of that have new messages, and how many ('show new').
Errors
   501 No authorization
Normal
   201 Here you go {followed by data}
   202 No soup, er, new messages for you
Sample: 
SHOW NEW pro
201 OK, data follows
<usernew>
<conf name='programming'>
  <topic name='engineering' new='1' />
  <topic name='scripting' new='4' />
</conf>
<conf name='processors'>
  <topic name='news' new='8' />
  <topic name='cisc' new='2' />
</conf>
</usernew>


SHOW USERS conf
Return a list of the users registered in the conf.
Errors
   411 No such conf.
   502 Not authorized.
Normal
   201 OK, here it is {followed by data}
Sample: 
SHOW USERS cosy_dev
201 OK, data follows
<userlist>
  <user name='dbetz'/>
  <user name='dgh'/>
  <user name='vanhorn'/>
  <user name='pwalker'/>
  <user name='peabo'/>
  <user name='bwilson'/>
  <user name='arussell'/>
  <user name='rshealer'/>
  <user name='twagner'/>
  <user name='gtaylor'/>
  <user name='jdow'/>
  <user name='al'/>
</userlist>


SHOW MINE
Return the data from the user's "Confs" file, a list of all conferences/topics the user is a member of, the current user message count in each and the total number of messages in each ('show')
Errors
   502 No authorization
Normal
   201 OK, here it is {followed by data}
   202 You aren't registered in anything
Sample: 
SHOW MINE
201 OK, data follows
<userconfs>
<conf name='gripes' ntopics='4'>
  <topic name='bixdiffs' nread='1034' total='1034' />
  <topic name='bugs' nread='3400' total='3419' />
  <topic name='enhance' nread='1300' total='1300' />
  <topic name='new' nread='2' total='2' />
</conf>
<conf name='sciences' ntopics='9'>
  <topic name='main' nread='226' total='226' />
  <topic name='water_hole' nread='309' total='309' />
  <topic name='physical' nread='173' total='173' />
  <topic name='bioscience' nread='227' total='227' />
  <topic name='seti' nread='68' total='69' />
  <topic name='astronomy' nread='299' total='299' />
  <topic name='folding' nread='30' total='35' />
  <topic name='curiosity' nread='500' total='500' />
  <topic name='test' nread='8' total='8' />
</conf>
<conf name='tcosy' ntopics='1'>
  <topic name='main' nread='50' total='50' />
</conf>
</userconfs>


SHOW STATUS conf
Like SHOWUSERS, but also list last-on time for each user.
Errors
   411 No such conf.
   502 Not authorized.
Normal
   201 OK, here it is {followed by data}
Sample: 
SHOW STATUS cosy_dev
201 OK, data follows
<userlist>
  <user name='dbetz' laston='1013529893'/>
  <user name='dgh' laston='1013591749'/>
  <user name='vanhorn' laston='1013641048'/>
  <user name='pwalker' laston='1013650229'/>
  <user name='peabo' laston='1013607047'/>
  <user name='bwilson' laston='1003194058'/>
  <user name='arussell' laston='1000268180'/>
  <user name='rshealer' laston='1013635220'/>
  <user name='twagner' laston='991796167'/>
  <user name='gtaylor' laston='1013482263'/>
  <user name='jdow' laston='1013656132'/>
  <user name='al' laston='1013657284'/>
</userlist>


SHOW RESUME user
Show certain user metadata plus the contents of his resume file.
Errors
   461 No such user
   502 No authorization
Normal
   201 OK, here's data {follows}
Sample: 
SHOW RESUME al
<resume user='al'>
  <body>Alastair JW Mayer

I suppose, in some ways, this is all my fault.
Try 'help authors' if you don't quite get that.
</body>
</resume>


SHOW INFO pathname
Return metadata for the named object (conference and topic descriptions, moderators, etc.).. (This replaces SHOW CONF, SHOW MODS, and SHOW TOPICS, which are all functions that can be provided by the Middle or Presentation Layers using this request on the appropriate object and pulling out the relevant metadata.)


Errors
   411 No such object
   502 No authorization
Normal
   201 OK, data follows {data}
Sample: 
SHOW INFO gripes
201 OK, data follows
<conf
  type='open'
  name='gripes'
  description='Conf. for TCoSy program gripes - missing features, bugs, etc'
  created='981761649' >
    <moderator name='al' />
    <topic name='bixdiffs' description='Differences between BIX and TCoSy' />
    <topic name='bugs' description='Bugs or annoying behaviour common to BIX and TCoSy' />
    <topic name='enhance' description='Enhancement requests' />
    <topic name='new' description='Cosy feature announcements and so forth' />
    <topic name='nntp' description='The NNTP (newsreader) interface' />
    <topic name='bulletin_old' description='Archived bulletins for the gripes conference.' />
</conf>




Following are file transfer commands.

GET PROFILE
Return the user's profile file. Although this may be obsolete. Equivalent?
Normal
   201 OK, here {data follows}
   202 It's empty


GET RESUME
Return the user's resume file. (Different from 'showresume')
Normal
   201 OK, here {data follows}
   202 It's empty


POST PROFILE {text or object follows}
Load the user's profile file from the uploaded data. (Obsolete?) May use this to load client preferences to allow "roving profiles" for a user.
   350 Okay send data


POST RESUME {text follows}
Load the user's resume file from the uploaded data.
   350 OK, send data


SEt PASSWORD password {text follows}
Change the user's password.
Errors
   502 No authorization (do we want to deny anyone this capability?)
Normal
   350 OK, send it again to confirm
   Error
      4xx Mismatch, not changed
   Normal
      200 OK, changed.


To be continued....


That's all for now. Still needs some fleshing out, definition of XML objects, etc, etc.


Copyright © 2002, Alastair JW Mayer.