Provided by: mtpolicyd_2.05-1.1_all bug

NAME

       Mail::MtPolicyd::Cookbook::ExtendedModule - how to achieve certain tasks within a plugin

VERSION

       version 2.05

Extending your mtpolicyd plugin

       How to achieve common task within your plugin.

   Logging
       You can output log messages to the mail.log from within your plugin by calling:

         $self->log( $r, '<log message>' );

       The log() method is inherited from the Plugin base class.

       The default log_level used is 4.

       To debug your plugin you can overwrite the log_level in your plugins configuration:

         <Plugin hello-world>
           module = "HelloWorld"
           log_level = 2
         </Plugin>

       This will cause your plugin to log with an higher log_level of 2.

   Caching lookup results
       If your plugin is called from the smtpd_recipient_restrictions if will be called once for
       every recipient. If your plugin does an lookup (dns, database, ...) should cache the
       result.

       The Mail::MtPolicyd::Request object implements the method do_cached() to achieve this:

         my ( $ip_result, $info ) = $r->do_cached('rbl-'.$self->name.'-result',
           sub { $self->_rbl->check( $ip ) } );

       The first parameter is the key in the session to store the cached result. The second
       parameter is a function reference.

       It will check if there's already an result stored in the given key within the session. In
       this case it will return the cached result as an array. If there is no result it will
       execute the code reference, store the result within the session and will also return an
       array containing the return values of the result.

   Doing things only once per mail
       If your plugin is called from the smtpd_recipient_restrictions if will be called once for
       every recipient but some tasks should only be performed once per mail.

       The Mail::MtPolicyd::Request object implements the method is_already_done() to achieve
       this:

         if( defined $self->score && ! $r->is_already_done( $self->name.'-score' ) ) {
           $self->add_score($r, $self->name => $self->score);
         }

       The method takes the key in the session in which the flag is stored.

       The example above will add a new score to the scoring, but only once per mail since the
       session is persisted across different checks.

   Use scoring
       To add scoring to your plugin your plugin needs to consume the role
       Mail::MtPolicyd::Plugin::Role::Scoring.

       This will add the method add_score( $r, $key, $value ) to your plugin class.

       The $key is a name for the score you'll see when you display the detailed scores. eg. with
       the AddScoreHeader or ScoreAction plugin.

       The $value is positive or negative number. In most cases you want to make this value
       configurable.

       It is also recommended that you check that you add an score only once. See
       is_already_done() method above.

       Here is an example:

         with 'Mail::MtPolicyd::Plugin::Role::Scoring';

         has 'score' => ( is => 'rw', isa => 'Maybe[Num]' );

       And somewhere in your run() method:

         if( defined $self->score && ! $r->is_already_done( $self->name.'-score' ) ) {
           $self->add_score( $r, $self->name => $self->score );
         }

   Make a configuration value user-configurable
       To add user configurable parameters to your plugin the class must consume the
       Mail::MtPolicyd::Plugin::Role::UserConfig role.

         with 'Mail::MtPolicyd::Plugin::Role::UserConfig' => {
           'uc_attributes' => [ 'enabled', 'mode' ],
         };

       The regular attributes:

         has 'enabled' => ( is => 'rw', isa => 'Str', default => 'on' );
         has 'mode' => ( is => 'rw', isa => 'Str', default => 'reject' );

       The UserConfig role adds the get_uc( $session, $param ) method to your class. To retrieve
       the user-configurable values for this attributes use:

         my $session = $r->session;
         my $mode = $self->get_uc( $session, 'mode' );
         my $enabled = $self->get_uc( $session, 'enabled' );

       Per user configuration in mtpolicyd works like this:

       Retrieve configuration values and store them in the session
           A plugin like SqlUserConfig retrieves configuration values and stores them in the
           current session.

           For example it may set the following key value:

             hello_world_enabled = off

       A Plugin with user configurable parameters
           Our HelloWorld plugin may be configured like this:

             <Plugin hello-world>
                   module = "HelloWorld"
                   enabled = on
                   uc_enabled = "hello_world_enabled"
             </Plugin>

           If the key "hello_world_enabled" is defined in the session it will use its value for
           $mode.  If it is not defined it will fall back to value of the "enabled" attribute.

   Set a mail header
       The Mail::MtPolicyd::Plugin::Result object has an extra constructor for returning a
       PREPEND action for setting a header:

         Mail::MtPolicyd::Plugin::Result->new_header_once( $is_already_done, $header_name, $value );

       It could be used like this:

         return Mail::MtPolicyd::Plugin::Result->new_header_once(
           $r->is_already_done( $self->name.'-tag' ),
           $header_name, $value );

   Adding periodically scheduled tasks
       When mtpolicyd is called with the option --cron <task1,task2,...> it will execute all
       plugins that implement a cron() function.

       The function is expected to take the following parameters:

         $plugin->cron( $server, @tasks );

       By default mtpolicyd ships with a crontab that will execute the tasks hourly,daily,weekly
       and monthly.

       A plugin that implements a weekly task may look like this:

         sub cron {
           my $self = shift;
           my $server = shift;

           if( grep { $_ eq 'weekly' } @_ ) {
             # do some weekly tasks
             $server->log(3, 'i am a weekly task');
           }
         }

       The $server object could be used for logging.

       To see the output on the command line you may call mtpolicyd like this:

         mtpolicyd -f -l 4 --cron=weekly

AUTHOR

       Markus Benning <ich@markusbenning.de>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2014 by Markus Benning <ich@markusbenning.de>.

       This is free software, licensed under:

         The GNU General Public License, Version 2, June 1991

perl v5.36.0                                2022-10Mail::MtPolicyd::Cookbook::ExtendedPlugin(3pm)