User Tools

Site Tools


devel:blueprints:mailin

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
devel:blueprints:mailin [2009/01/30 10:43]
morten
devel:blueprints:mailin [2009/01/30 11:57]
morten
Line 15: Line 15:
   * The payload will be offered in turn to each registered plugin.   * The payload will be offered in turn to each registered plugin.
     * Once a plugin accepts the payload, MailIn core will not offer it to any other plugin.     * Once a plugin accepts the payload, MailIn core will not offer it to any other plugin.
-    * MailIn core asks the selected ​plugin to authorize the payload. +    * MailIn core verifies that the plugin ​offers its own ''​authorize''​ function. ​ If it doesn'​t,​ MailIn core attempts ​to authorize the payload ​according to global rules
-      * The plugin will check its authorization configuration,​ to see whether the email is allowed to generate an event. ​ Typically, the headers are inspected to find the source of the email.+      * When the plugin offers its own authorize function, this is called.  ​The plugin will check its authorization configuration,​ to see whether the email is allowed to generate an event. ​ Typically, the headers are inspected to find the source of the email.
     * If authorized, MailIn core will ask the plugin to process the payload.     * If authorized, MailIn core will ask the plugin to process the payload.
       * The plugin will process the payload in whatever manner it sees fit, and using the ''​nav.event''​ API, one or more events should be generated and posted to the event queue.       * The plugin will process the payload in whatever manner it sees fit, and using the ''​nav.event''​ API, one or more events should be generated and posted to the event queue.
Line 29: Line 29:
  
 The plugin must expect the ''​payload''​ object to be a message object from [[http://​docs.python.org/​library/​email.html|Python'​s standard email library]]. The plugin must expect the ''​payload''​ object to be a message object from [[http://​docs.python.org/​library/​email.html|Python'​s standard email library]].
 +
 +==== Loading plugins ====
 +  * MailIn core will load plugin modules according to its configuration file.
 +  * All plugin modules must be listed in a specific configuration option, separated by spaces or colons.
 +    * suffix wildcards should be allowed, such that specifying ''"​nav.mailin.plugins.*"''​ will result in the loading of all modules in the ''​nav.mailin.plugins''​ package.
 +  * A plugin module that fails to import into the Python interpreter shall be ignored by the core, and an exception logged (including a full traceback).
 +
 +==== Configuration =====
 +Example configuration file:
 +<​code>​
 +[mailin]
 +# What plugins to load
 +plugins = nav.mailin.plugins.*
 +
 +# Global authorization check (header regexp pattern)
 +# check to see that uit.no is in the Received headers
 +authorization = ^Received:​.*uit\.no
 +
 +# Plugin specific options
 +[nav.mailin.plugins.whatsup]
 +plugin_specific_value=foo
 +</​code>​
 +
 +===== API usage =====
 +The following Python / NAV libraries should be used for various aspects of the program:
 +^ api           ^ for what  ^
 +| ''​email'' ​    | Parsing email payloads into Python objects that will be passed around internally |
 +| ''​logging'' ​  | Any logging should be performed using named loggers from Python'​s logging library |
 +| ''​nav.event''​ | Creating and posting events to NAV's event queue |
 +
 +As of this writing, there is no API to create custom event type and alert type hierarchies in the NAV database. ​ This will be added as a separate blueprint in Launchpad.
devel/blueprints/mailin.txt · Last modified: 2009/02/02 12:08 by morten