middleware_protocol.txt from AlphaMail at Krugle

Show middleware_protocol.txt syntax highlighted

This document is an overview of the protocol used to talk between the web mail
client and the IMAP caching daemon.

Goals for protocol
------------------
- Must be easy to machine-parse
- Must support a sufficient subset of IMAP to build a webmail client
- Must be efficient for very short requests. Web clients connect, make a few
  simple requests, and disconnect.
- Should not have features that the webmail system does not use
- The primary (and most time consuming) items to construct should be available
  as pre-grouped items. For example folder lists, and message lists.

Interaction Considerations
--------------------------
- The bigger items of content are passed via on-disk cache, not via this
  protocol
- The web client must be able to determine what character set is being used
  for any messages passed in the protocol
- UID validity on a mailbox can change (i.e. cache times out, web client
  reconnects with non-expired cookie, cache reconnects and gets new
  uidvalidity). As a result, all protocol requests that work on a mailbox
  require the uidvalidity that was returned in a messagelist.
- Delimiters for folders are not specified in IMAP. In this protocol,
  path delimiters are always '/'.
- All folder paths are relative to the user's top-level mail directory, which
  is configured in IMAP. Folders and paths in this protocol cannot begin
  with '~' or '/'. Also, '.' and '..' are not allowed as standalone path
  components.

Protocol Stages

1) Authentication
   
   When the web client first connects, it must send the following command:

   access imaphost user password

   Failure to send this command, or failure of the command itself will result
   in the response:
   
   NO <reason>
   
   followed by disconnection. 

   Success of this command will result in:

   OK

2) Once authenticated, the client can send any other command. Command success
   will result in the output of the command, followed by the single-line
   response:

   OK

   Output always precedes the OK response. Failure of a command always results
   in:

   NO <reason>

   Commands should be sent with a newline only, and single-line responses will
   always be terminated by newlines only. Carriage returns are allowed in the
   variable length data responses (i.e. CAT), but will not be used as part
   of protocol requests, and single-line responses.

COMMANDS
--------

lsub [base] - List subscribed folders, starting from a base location. The
   heirarchy separator is always /, and base is always relative to the user's
   top-level mail directory, as configured in the cache daemon.

   Returns a _recursive_ list of selectable folders. One per line.

   The folder names themselves are encoded in IMAP modified UTF-7, as
   specified in RFC3501.
   
   lsub
   d 4 mail
   OK
   lsub mail
   other
   Sent
   stuff/other
   OK

list [base] - List all possible folders in the account. 

   Same input and ouput as lsub.

create folder

   Input: folder name must be in modified UTF-7 (see lsub). Delimiter is /.

   create mail/&ZeVnLIqe-
   OK

delete folder

   Use imap utf-7.

   delete mail/&ZeVnLIqe-
   OK

rename folder (NOT IMPLEMENTED YET)

   Use imap utf-7.

   rename mail/&ZeVnLIqe- mail/stuff
   OK

messagelist folder sort-order [start num]

   Get the primary attributes for messages in a folder.

   attribute-list is a quoted, comma-separated list of desired header fields,
   along with two special request keywords: snippet and size. Snippet returns
   up to the first 80 characters of the body of the message. Size returns the
   total size of the rfc822 message.
   
   The supported sort orders are "from", "date", and "thread". All of these,
   including "thread" return the same format. In each case, the messages will
   be sorted in the proper order for (expanded) display from top to bottom.
   If doing threading, a special "threadlevel" field is added as a shortcut
   for the client. The threadlevel field will be an indication of how deep the
   message in question is nested in terms of the current message list.

   start is the starting offset
   num is the number of messages to get

   The first response line contains the number of messages in the folder, the
   IMAP uidvalidity, and the last change time of the cache (in seconds).

   Each of the remaining responses is split into multiple lines. The first
   line is the message UID, a colon, followed by the flags. The remaining
   lines are headers as they appear in the rfc822 header of the message, 
   except for threadlevel, which is an indentation number when sorting by
   thread.

   The response includes message headers, along with a snippet of the body
   text in the following format:

   snippet:character encoding:snippet

   FLAGS: (S = seen, A = answered, R = Replied to, D = marked for delete, 
           W = forwarded)

   messagelist inbox thread 1 1
   2:1029938453:100293944
   102:SDT
   Snippet:us-ascii:This is a test
   subject: This is a test
   from: tkay@uoregon.edu
   date: 1/1/2005 12:21 pm
   to: tkay@uoregon.edu
   threadlevel: 1
   size: 103245
   OK

read folder uidvalidity uid (NOT IMPLEMENTED)

   Indicate to the cache that the webapp wants to read the specified message.
   This command returns the location of the relevant cache file. Use IMAP
   UTF-7 for folder names. Use a mime decoder to interpret the message.

   read inbox 1029938453 102
   /tmp/FileCache/imap/tkay/1029938453/inbox/102/rfc822
   OK

cat folder uidvalidity uid

   Dump the given message over the connection in uninterpreted rfc822 format.

   Response is NO, or a size in bytes on one line, followed by that many bytes
   of data, followed by OK.

   cat inbox 1029938453 102
   10234
   Subject: ...
   <rest of 10234 bytes>OK

trash folder uidvalidity uid

   Mark a message for removal

   trash inbox 1029938453 102
   OK

untrash folder uidvalidity uid

   Remove the deleted flag from a message.

   untrash inbox 1029938453 102
   OK
   
move folder uidvalidity uid destfolder

   Move a message to a different folder. Use IMAP UTF-7 for the folder name.

   move inbox 1029938453 102 mail/other/&ZeVnLIqe-
   OK

expunge folder

   Compress the named folder by removing deleted messages.

   expunge inbox
   OK

append size folder

   Append a message in RFC format to the named folder. Size does not include
   the line termination for this command.

   append 1231 mail/sent
   <1231 bytes>
   OK

ssub base

   Set folder subscriptions for a specific location. The server will send a
   prompt (:) after the request. The client should send folder names, one per
   line. The server will prompt with a colon each time. The client ends with a
   period (.) on a line.  The example below labels the server with S:, and the
   client with C: to show the interaction.

   C: ssub mail/
   S: :
   C: sent
   S: :
   C: Trash
   S: :
   C: .
   OK

flag folder uidvalidity uid [+-][SARDW]

   Set or remove a flag on a message. See messagelist for a description of the
   supported flags. Only one flag may be changed per command.

   flag inbox 1252291837 102 +R
   OK

datecrop folder days (not implemented yet)

   Delete and expunge all messages in a folder that are older than the
   specified number of days.

   datecrop "mail/Trash" 7
   OK
See more files for this project here