Great Circle Associates List-Managers
(July 1999)
 

Indexed By Date: [Previous] [Next] Indexed By Thread: [Previous] [Next]

Subject: MLMAP Draft
From: Jeremy Blackman <loki @ maison-otaku . net>
Date: Thu, 8 Jul 1999 11:47:18 -0700 (PDT)
To: list-managers @ greatcircle . com

For a while, I've been working on a design for a protocol to allow a
mailing list server to be communicated with in an abstract way.  A mailing
list package would implement an MLMAP server, and then various mail
programs (or even standalone client programs) would be able to connect to
this MLMAP server and allow users to perform operations on their
subscription (subscribe, unsubscribe, change settings for MLMs where this
applies, etc.)

After a number of little rewrites, I have a basic concept for the protocol
grammar down, and a preliminary list of the userspace commands.  I have
not yet spec'd out the admin commands; I'd like comments on the userspace
ones first. :)

The grammar owes a LOT to IMAP, as people will probably notice
immediately.  I did receive one suggestion that instead of sending
text-based communication, the protocol should use RPC... I'm a little iffy
on that.  CORBA might work, but I've never used it, and I think it's
easier to ensure that EVERY given platform can handle a protocol if it's
not requiring a library like that.

I posted this to the mlmap @
 listar .
 org list, but I suspect that everyone on
that list is sorting it into a subsidiary folder and since it's been quiet
so long, simply never noticed the post.  (I'm assuming it's NOT just a
lack of interest because everyone always says 'that's a good idea' when
the topic is brought up.)  So I'm posting it here to get comments. :)

If anyone wants to comment on the MLMAP draft, I suggest subscribing to
the MLMAP list over on listar.org; send e-mail to mlmap-request @
 listar .
 org
with a subject of subscribe:

mailto:mlmap-request @
 listar .
 org?subject=subscribe

Anyway... comments are much appreciated. :)
---
MLMAP Basic Description
-----------------------

Commands are in the format:
cXXX <command> [<params>]

Responses are in the format:
rXXX <command> <result> [<text>] 
    [: <key> <value> [<key> <value>] | <key> { <text> }] [...]

The first line increments one each time, and the command/result pairs are
matchable on that, like IMAP.

The result will be 'OK', 'MOK', or 'ERROR'.  'OK' means the command was
successful, 'MOK' means the command was successful and the result will
take multiple lines.  'ERROR', of course, means an error.  In the case of
'MOK', all lines have 'MOK' until a line that simply has 'DONE'.

The set of commands is designed to be fairly generic and yet fairly
comprehensive, so as not to tie it to any one mailing list package.  This
should allow it to work for Lyris, or Majordomo, or Listserv, or Petidomo,
or Listar.  The first drafts will probably be biased in favor of Listar,
simply because I wrote that package and it's what I tend to think in terms
of, but I'm trying to write it with Majordomo and Listserv - the other two
packages I have maintained lists under - in mind as well.

Here's a sample session.  All commands come from client, all responses 
from server:

[connect]
r000 WELCOME OK : SERVER "Listar.org MLMAP Server" 
     DOMAINS (listar.org baka-con.org nausicaa.net) 
     PROTOCOLS (1.0 1.0-extended)
c001 PROTOCOL 1.0
r001 PROTOCOL OK
c002 FLAGLIST
r002 FLAGLIST OK : 
     USERFLAGS ((VACATION "User is on vacation") 
      (ACKPOST "User is notified when their post is accepted.")) 
     ADMINFLAGS ((ADMIN "User is an administrator") 
      (MODERATOR "User is a moderator."))
c003 DOMAIN listra.org
r003 DOMAIN ERROR "No such domain on this server."
c004 DOMAIN listar.org
r004 DOMAIN OK
c005 LISTS 
r005 LISTS MOK : LIST "listar-dev" NAME "Listar Development Mailing List"
r005 LISTS MOK : LIST "listar-support" NAME "Listar Support Mailing List"
r005 LISTS MOK : LIST "listar-cvs" NAME "Listar CVS Notification List"
r005 LISTS DONE
c006 LOGIN loki @
 maison-otaku .
 net MYp4ss
r006 LOGIN OK
c007 LIST listar-dev
r007 LIST OK
c008 FLAGS 
r008 FLAGS OK : FLAGS (ADMIN MODERATOR ECHOPOST)
c009 SETFLAG ACKPOST ON
r009 SETFLAG OK
c010 FLAGS 
r010 FLAGS OK : FLAGS (ADMIN MODERATOR ECHOPOST ACKPOST)
c011 PUBFILE listar-dev intro
r011 PUBFILE OK : FILE intro TEXT {
Welcome to the Listar-Dev mailing list.

Blah.  Foo... bar. Baz.

}
c011 WHO
r011 WHO ERROR "List membership not viewable over MLMAP."
c012 LOGOUT
r012 LOGOUT OK "Goodbye"
[disconnected]

MLMAP COMMANDS LIST
-------------------

WELCOME

 Client form:
    No client form.

 Server form params:
    SERVER <text>    - name of server.
    DOMAINS <list>   - list of domains.
    PROTOCOLS <list> - list of protocol versions supported

 Notes:
    WELCOME is a special command.  It's never issued from a client,
    and only occurs as the first line of a session, when an MLMAP
    client connects to a server, thus it should only ever occur as
    r000.

 Example:
    r000 WELCOME OK : SERVER "Happy Test Server" DOMAINS (testlist.org)
         PROTOCOLS (1.0 1.5)

PROTOCOL

  Client form:
    PROTOCOL <protocol version>

  Server form params:
    PROTOCOLS - List of supported protocols, provided on error.

  Notes:
    PROTOCOL is used by an MLMAP client to inform the server what protocol
    revision it wishes to use.  This ensures backwards compatibility, much
    like the 'HTTP/<version>' stamp at the end of HTTP commands for a 
    webserver.

  Examples:
    c0001 PROTOCOL 1.0
    r0001 PROTOCOL OK

    c0001 PROTOCOL 5.0
    r0001 PROTOCOL ERROR "Protocol '5.0' not supported." : PROTOCOLS (1.0 1.5)


HOST

  Client form:
    DOMAIN <host>

  Server form params:
    DOMAINS <list> - list of supported domains, provided on error

  Notes:
    DOMAIN is used to select which domain the MLMAP session applies to
    at that point, for MLMAP servers that provide multiple virtual-hosted
    domains.

  Examples:
    r0002 DOMAIN testlist.org
    r0002 DOMAIN OK

    r0002 DOMAIN foobar.com
    r0002 DOMAIN ERROR "This server does not handle 'foobar.com'." : DOMAINS (testlist.org)

DOMAINS

  Client form:
    DOMAINS

  Server form params:
    DOMAINS <list> - List of supported domains

  Notes:
    DOMAINS is used to get the list of domains that is made available
    at login time, in case you need it again.  This is to avoid clients
    that don't cache the list issuing bogus DOMAIN commands simply to
    retrieve the list of available domains.

LISTS

  Client form:
    LISTS

  Server form params:
    LIST <text> - List name/ID.
    DESC <text> - Description of list.

  Notes:
    LISTS returns a list of the available lists, as a set of MOK
    results.  It only applies to the current domain.

  Examples:
    c0002 LISTS
    r0002 LISTS ERROR "No domain set."

    c0002 LISTS
    r0002 LISTS MOK : LIST "test1" DESC "First Test List"
    r0002 LISTS MOK : LIST "test2" DESC "Second Test List"
    r0002 LISTS DONE


LOGIN

  Client form:
    LOGIN <email> [password]

  Server form params:
    <none>
    

  Notes:
    LOGIN provides a method of connecting to a specific list with a 
    specific e-mail address.  The password parameter is optional; for
    a brand-new user, it shouldn't be supplied anyway.  Not all mailing
    list packages will provide a password method of authentication at
    this level, anyway.

  Examples:
    c0002 LOGIN loki @
 listar .
 org
    r0002 LOGIN OK

    c0002 LOGIN loki @
 listar .
 org
    r0002 LOGIN ERROR "Password required."

    c0002 LOGIN loki @
 listar .
 org Foobar
    r0002 LOGIN ERROR "Password not supported."

LIST

  Client form:
    LIST <list> [password]

  Server form params:
    ALIAS <address>   - If the current e-mail address is on the list
                        under a different address, this is that other
                        address.
  
  Notes:
    The password parameter is allowable here again as well, since some
    packages may have a password at the list-level instead of the server
    level.  Alias is useful for packages that allow you to have multiple
    addresses associated with a subscription; it allows a way to inform
    the client of what the primary address for that subscription is.

  Examples:
    c0005 LIST test1
    r0005 LIST OK

    c0005 LIST test1 FooBar
    r0005 LIST OK : ALIAS "loki @
 maison-otaku .
 net"


PASSWD

  Client form:
    PASSWD <oldpass> <newpass>

  Server form params:
    <none>

  Notes:
    It changes your password for the scope you're in.  Duh. :)
    PROBABLY, something other than plaintext passwords should be
    supported, too.  PGP keys?  Kerberos?  I'm open to suggestions, both
    on what security method to employ AND on how to implement it.

  Examples:
    c0007 PASSWD foobar MyPass
    r0007 PASSWD OK

SUBSCRIBE

  Client form:
    SUBSCRIBE

  Server form params:
    <none>

  Notes:
    SUBSCRIBE requires that you have a list context focus and an e-mail
    address provided (e.g. a LOGIN and a LIST command).  Whenever
    possible, it should generate a subscribe ticket (open+confirm in
    Majordomo parlance, or subscribe-mode=confirm in Listar).

  Examples:
    c0009 SUBSCRIBE
    r0009 SUBSCRIBE ERROR "No list scope."

    c0011 SUBSCRIBE
    r0011 SUBSCRIBE OK

UNSUBSCRIBE

  Client form:
    UNSUBSCRIBE [REQUESTADMIN "<reason>"]

  Server form params:
    <none>

  Notes:
    Like SUBSCRIBE, UNSUBSCRIBE requires a list and user scope.  Ideally,
    it should generate a confirm mode ticket as well, but this may not
    always be feasible (as an address may be outdated or such).  Hence,
    the 'requestadmin' parameter, which requests admin intervention if
    unsubscribe is just plain not working.

  Examples:
    c0007 UNSUBSCRIBE
    r0007 UNSUBSCRIBE ERROR "Not on that list."

    c0028 UNSUBSCRIBE REQUESTADMIN "E-mail address no longer works."
    r0028 UNSUBSCRIBE OK

FLAGS

  Client form:
    FLAGS

  Server form params:
    FLAGS <list> - List of the actual flags set on the account

  Notes:
    FLAGS is useful for MLMs (Listar, Listserv) that allow you to
    set subscription flags.  Flags given here are Listar ones. ;)

  Examples:
    c0008 FLAGS
    r0008 FLAGS OK : FLAGS (ACKPOST DIGEST VACATION)

FLAGLIST

  Client form:
    FLAGLIST

  Server form params:
    USERFLAGS <list of lists> - Flags available for users to set.
    ADMINFLAGS <list of lists> - Flags available for admins to set.

  Notes:
    The reason both admin and user flags are provided is so the client
    software can get the descriptions of them for displaying subscription
    information.  User flags are settable by users (or admins), while
    admin flags are only settable/unsettable by admins (examples of this
    would be the Listar 'MODERATOR' flag or 'MODPOST' flag, and the
    Listserv 'REVIEW' flag).

  Examples:
    c0009 FLAGLIST
    r0009 FLAGLIST OK : USERFLAGS ((VACATION "User is on vacation")
       (ACKPOST "User recieves a notice when their posts are approved."))
       ADMINFLAGS ((ADMIN "User is an administrator.") (MODERATOR "User is
       a moderator."))

    c0013 FLAGLIST
    r0013 FLAGLIST ERROR "Majordomo doesn't support subscription flags."

FLAGS

  Client form:
    FLAGS

  Server form params:
    FLAGS <list> - List of flags on current account

  Notes:
    FLAGS lists the current flags set on your subscription, for MLMs
    that allow subscription flags.

  Examples:
    c0018 FLAGS
    r0018 FLAGS OK : FLAGS (ADMIN ACKPOST VACATION)

    c0013 FLAGS
    r0013 FLAGS ERROR "Majordomo doesn't support flags."

SETFLAG
    
    Client form:
      SETFLAG <flag> <on|off>

    Server form params:
      <none>

    Notes:
      SETFLAG is how you set or unset a subscription flag.

    Examples:
      c0019 SETFLAG ACKPOST ON
      r0019 SETFLAG OK

      c0028 SETFLAG FOOBAR OFF
      r0019 SETFLAG ERROR "No such flag 'FOOBAR'."

      c0014 SETFLAG ADMIN ON
      r0014 SETFLAG ERROR "That flag is not settable by users."

      c0017 SETFLAG DIGEST ON
      r0017 SETFLAG ERROR "Majordomo does not support subscription flags."

PUBFILES

  Client form:
    PUBFILES

  Server form params:
    FILES <list of lists> - List of publically viewable files associated
                            with a list.

  Notes:
    This is useful for retrieving a list of what files are available for
    a list, such as 'intro', 'info', 'faq', etc.

  Examples:
    c0008 PUBFILES
    r0008 PUBFILES OK : FILES ((INTRO "List introduction.") (FAQ "List FAQ"))

PUBFILE

  Client form:
    PUBFILE <file>

  Server form params:
    FILE <name>      - The file this applies to.
    TEXT <textblock> - The content of the file for the list.

  Notes:
    This provides a way to view the files given in the PUBFILES command
    above.

  Examples:
    c0008 PUBFILE intro
    r0008 PUBFILE OK : NAME intro TEXT { 
    Welcome to the test1 mailing list.

    This is the intro textfile.  Whee.
    Isn't that special?
    }




Indexed By Date Previous: Lists and Contact Database Integration
From: "Steven Clift" <slc @ publicus . net>
Next: Re: eGroups.com: You have been added to the list-managers eGroup.
From: "David W. Tamkin" <dattier @ Mcs . Net>
Indexed By Thread Previous: Re: Mass non-bulk mailing
From: "Nathan J. Mehl" <memory @ blank . org>
Next: Tag Lines
From: majorhost @ p-trader . net

Google
 
Search Internet Search www.greatcircle.com