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
devel:blueprints:mailin [2009/01/30 11:27]
morten
devel:blueprints:mailin [2009/02/02 13:08] (current)
morten add link to another blueprint
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.
  
 ==== Plugin API ==== ==== Plugin API ====
-  * A MailIn plugin consists of a Python module, which must provide three functions: +A MailIn plugin consists of a Python module, which should ​provide three functions:
-    - ''​accept(payload)''​ +
-    - ''​authorize(payload)''​ +
-    - ''​process(payload)''​+
  
 +^ function ​              ^ required ^ description ^
 +| ''​accept(payload)'' ​   |    yes   | Must return a true value if the payload can be processed by this plugin. |
 +| ''​authorize(payload)''​ |    no    | Must return a true value if the payload is authorized to generate an event, according to  plugin-internal rules/​configuration. ​ If this function is not supplied by the plugin, the MailIn core must use a global authorize function to perform authorization according to globally configured rules. |
 +| ''​process(payload)'' ​  ​| ​   yes   | Process the payload, generate and post a single or multiple events. ​ Return a true value if successful. |
 +
 +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 [[https://​blueprints.launchpad.net/​nav/​+spec/​event-type-creation-api|a separate blueprint in Launchpad]].
devel/blueprints/mailin.1233311267.txt.gz · Last modified: 2009/01/30 11:27 by morten