The Yet-To-Come POP3Lite API ============================ Last updated: <2001/04/26 10:53:47 algernon> Preface ------- In this document I'll try to outline my ideas about the new POP3Lite module system. These ideas may well be a bit unclear, I really need to sit down and do a design someday. Anyway, I hope this'll make some sense... Basic framework --------------- The most notable thing I'd like to do is to make POP3Lite event-driven. It should sit in a loop waiting for events, and if one occurs, call the appropriate event handler (details later). So, modules would be like a collection of event handlers and helper routines. This would allow great flexibility. Now the details: I plan to have a library called libmdk (mdk stands for MadHouse Daemon Kit), which would implement the event driven environment, some basic event handlers and a bunch of other stuff. The thing I imagine is to have the program sit in a loop. When the user types something, an input_event occurs. When this happens, the handler-manager will try to find the handler for input_event. Then it will call that one. The input_event handler may trigger some other event, and so on. Of course, the events should be stackable, so it should be possible to have more than one input_event handler. This would make error reporting a bit complex, but not much. For example, imagine that we have two maildrop handlers (retr_event handler or something like that). The first one operates 4 messages in a mailbox, the second on 3 messages in a maildir. When the client issues a `RETR 5' command, the first handler would probably try to report that there is no such message. However, there is, but it is handled by another module. So, this should be done by calling p3l_error_defer(...), which will place the error message into a buffer, replacing its previous value. This way, only the last error message would be printed (but setting the loglevel to debug would send the errors to the logger module). input_handler ------------- The input_handler would parse the input into a GList, something like argv, but as a GList. Then, it should trigger the event associated with the received command (say, _event or something). That's the only job it should do. output_handler -------------- The output handler should output the message set by p3l_error_defer or p3l_message_defer or any other function of the like, format it to POP3-style, and echo it to the client. Modules ------- Modules would simply register new event handlers, and because these handlers could be stacked, they could quite easily co-operate. They may also declare dependency or a conflict on HANDLERS. Configuration syntax -------------------- In the configuration file, we should have three different types of... well... whatever. The first one is a section indicator, the second is a command and the third is a variable. Each module should have it's own section in the configuration file, and the main section should assign the modules to different parts of the system. To make it clear, here is an imagined example: pam: sys.auth.pam set service_name pop3lite main-mailbox: maildrop.mailbox set mailbox_path \ /var/mail/${sys.user.group}/${sys.user.username} set mailbox_type mbox bulletin-box: maildrop.mailbox set mailbox_path /var/spool/pop3lite/bulletins set mailbox_type mmdf group-letter-box: maildrop.mailbox set mailbox_path /var/mail/$(substring ${sys.user.group},1,1) .MAIN: pam &sys.auth.system &cmd.auth.user-pass main-mailbox \ bulletin-box group-letter-box This would mean the following: First, we'll have a section named `pam', which will load the sys.auth.pam module, and set the PAM service name to `pop3lite'. Quite like make rules. The next section (main-mailbox) would load the maildrop.mailbox module, set the mailbox_path and mailbox_type. ${} should be substituted run-time with the variable. The third section is almost similar to the previous one, the one new thing is that it sets mailbox_type to `mmdf'. It is important to note that functionalities that share some common code should be implemented in the same module. In this case `mbox' and `mmdf' only differ in the message separator, nothing else, so both can be read by the same code, only a few lines should be added. The `group-letter-box' section introduces functions (inspired by GNU Make). $( ,,...) should call with the given parameters, and the result should be substituted. The main section is called .MAIN, its dependencies are the modules to load. Internal storage and accessibility of configuration --------------------------------------------------- When we read the configuration file, each option, command, whatever should be stored as
.., where is the type of the option: command, option, or something else. We'll see how it'll develop. The handlers that are registered for the same event should share the same data area, so this should be taken into account to. This way they could co-operate together better. However, they must not share the same configuration are! Planned modules --------------- sys.auth.system System authentication This would provide a sys.auth event handler. sys.auth.pam PAM-based authentication, should provide a sys.auth event handler. sys.auth.sql SQL-based authentication, common code, should not be used directly. sys.auth.sql.{postgresql,mysql} SQL-based authentication for postgresql/mysql sys.auth.cmd.apop APOP-based authentication, should register an apop_event. It should not provide a sys.auth handler, for that is for USER/PASS only. sys.auth.cmd.pass USER/PASS based authentication module. Should register an user_event and pass_event, and it must depend on sys.auth. sys.log.syslog Syslog-based logging, should provide sys.log handler sys.log.filelog Logging to a file, should provide sys.log handler hooks.log.connectlog Connection logging, should provide a sys.log handler hooks.disable Command disabler, what it provides is determined at run-time. Because of the nature of the stack-like handler calling convention, this should be the last module loaded. maildrop.mailbox mbox and mmdf mailbox support, should provide maildrop.retr and friends maildrop.maildir maildir and mh support, should provide maildrop.retr and friends. cmd.all.capa the CAPABILITIES command, should provide a cmd.all.capa event handler, and register capa_event. maildrop.hooks.expire mail expiration hooks, should provide maildrop.retr and friends maildrop.hooks.sabotage Leave-mail-on-server sabotage hooks, should provide maildrop.retr and friends hooks.auth.alias User alias support hooks.auth.vhost IP-less virtual host support hooks.auth.userconf Per-user configuration support Gergely Nagy \ mhp/|8] Local variables: mode: text End: