Since the original one got eaten (probably by the majordomo administrivia filters, in hindsight... you know, it really should inform the poster when it rejects a message on that criteria, instead of silently eating it), I'm going to try again. Wherever it says 'S*BSCRIBE', you can assume the '*" is a 'U', likewise with 'UNS*BSCRIBE'. I will assume that the actual occurances of the commands themselves for the protocol occur far enough down that it should not be a problem in teh administrivia filters. --Loki [EMAIL PROTECTED] / [EMAIL PROTECTED] / [EMAIL PROTECTED] ---------- Forwarded message ---------- Date: Thu, 8 Jul 1999 11:47:18 -0700 (PDT) From: Jeremy Blackman <[EMAIL PROTECTED]> To: [EMAIL PROTECTED] Subject: MLMAP Draft 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 (s*bscribe, uns*bscribe, change account settings, 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] with a subject of s*bscribe: mailto:[EMAIL PROTECTED]?subject=s%75bscribe 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. Lists can contain multiple values, and are enclosed in (). 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] r0002 LOGIN OK c0002 LOGIN [EMAIL PROTECTED] r0002 LOGIN ERROR "Password required." c0002 LOGIN [EMAIL PROTECTED] 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 "[EMAIL PROTECTED]" 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? }
