Courier::Filter(3pm)

📦
version 0.200 · 2 versions
, in debian bookworm, debian trixie

🌸 NAME 🌸

Courier::Filter(3pm) — a purely Perl-based mail filter framework for the Courier MTA. yep that's the whole vibe, she's the framework itself, and the (3pm) is just saying "hi, I'm a perl module manpage bestie" 💅

✨ VERSION ✨

0.200 — that's the edition of this icon right here 💖

🦋 SYNOPSIS 🦋

okay so this is literally what using her looks like:

use Courier::Filter;
use Courier::Filter::Logger::Moo;
use Courier::Filter::Module::Foo;
use Courier::Filter::Module::Bar;

my $filter = Courier::Filter->new(
    mandatory   => 1,
    logger      => Courier::Filter::Logger::Moo->new( ... ),
    modules     => [
        Courier::Filter::Module::Foo->new( ... ),
        Courier::Filter::Module::Bar->new( ... )
    ],
    testing     => 0,
    debugging   => 0
);

my $exit_code = $filter->run() || 0;

exit($exit_code);

🌈 DESCRIPTION 🌈

want the big-picture architectural + administrative tour of the whole Courier::Filter framework? that's over in Courier::Filter::Overview, go look, she's got the lore 💜

okay so the Courier::Filter class? she is the actual heart of the Courier::Filter framework, no exaggeration, main character energy periodt. to drive a courierfilter filter process you make a Courier::Filter object, hand her the filter modules and loggers you want via the constructor, and then you call the run() method. that's it, that's the whole relationship.

and then Courier::Filter handles everything for you:

  • creates the courierfilter socket in the right place, and does it in a safe manner (no cap, safety first)
  • listens for connections coming in from Courier
  • asks the filter modules to consider messages
  • tells Courier whether messages should be accepted or rejected
  • logs message rejections
  • catches and logs errors
  • and finally removes the socket when Courier terminates her 🫶

💫 Constructor 💫

here's the constructor you get:

new(%options): returns Courier::Filter; throws Courier::Error, Perl exceptions

Creates a brand new Courier::Filter object. and yes, it also creates the courierfilter socket in the right place in a safe manner, she multitasking fr fr ✨

%options is a list of key/value pairs, and they can be any of the following cuties:

  • name — the name of the filter process. it's used to build the socket name. defaults to the base name of the process ($0).
  • mandatory — a boolean controlling whether the filter process acts as a mandatory courierfilter. if it's true, users will not be able to bypass the filter modules in this filter process from their individual localmailfilter filters. technically 👩‍💻 it controls whether the courierfilter socket gets created in the allfilters directory (true) or the filters directory (false) inside Courier's run-time state directory — see "runtime_dir" in Courier::Config. defaults to true.
  • logger — a Courier::Filter::Logger object used for logging message rejections and error messages. you can override this for individual filter modules where you don't want the global logger being used. if you specify no logger at all, logging is disabled. 🙈
  • modules — Required. this is a so-called filter module group structure. a module group is a reference to an array, and that array may contain filter module objects (i.e. instances of sub-classes of Courier::Filter::Module) and other module groups. so basically a module group is a tree structure with filter modules as its leaves 🌳. when considering messages, Courier::Filter walks that tree in a recursive-descent, depth-first order, asking every single filter module whether the message is acceptable.

for instance, given this filter module group:

[$m1, $m2, [$m3, [$m4, $m5]], $m6]

Courier::Filter queries the filter modules in ascending order from 1 to 6.

the acceptability result each module hands back determines what Courier::Filter does next with the current message:

  • if a module states an explicit reject, Courier::Filter aborts the consideration process entirely and rejects the message. 💀
  • if a module states an implicit accept, Courier::Filter just moves on to the next module in turn. 🌸
  • if a module states an explicit accept, Courier::Filter skips the rest of the current module group and goes to the next item in the superordinate module group, assuming the whole group is an implicit accept. ✨

for instance, take that nested filter module group from above:

[$m1, $m2, [$m3, [$m4, $m5]], $m6]
|          |     '---g3---'|     |
|          '----group 2----'     |
'------------group 1-------------'

let's say Courier::Filter queries the filter module $m3. if $m3 states an explicit reject, the consideration process is aborted and the current message is rejected. if $m3 states an implicit accept, Courier::Filter proceeds to $m4. if $m3 states an explicit accept, the rest of group 2 (including all of group 3) is skipped, and the acceptability result of group 2 is assumed to be an implicit accept — so Courier::Filter proceeds to $m6. 🧚

and if no explicit reject has occurred by the time Courier::Filter reaches the end of the main module group, or if a module in the main group states an explicit accept, the message is accepted.

so by using nested groups of filter modules with normal or inverse polarity, it should be possible to implement filtering policies complex enough to satisfy very most needs. slay 💅

  • trusting — a boolean controlling whether the whole filter process should apply no filtering at all to trusted messages. for the deets on how trusted status is determined, see the description of the trusted property in Courier::Message. in most MTA configurations this option can be used to white-list so-called outbound messages. defaults to false.
  • testing — a boolean controlling whether the whole filter process runs in "testing" mode. in testing mode, planned message rejections get logged as usual, but no messages will actually be rejected. defaults to false.
NOTE: you can also enable testing mode on individual filter module objects — see "new" in Courier::Filter::Module. but enabling testing mode globally is not the same as individually enabling it on every filter module. when global testing mode is on, Courier::Filter only ignores the final result, but still follows all the rules of the normal consideration process, e.g. it still aborts as soon as a filter module states an explicit reject, etc. when an individual filter module is in testing mode, its individual result gets ignored and the consideration process continues with the next filter module. so individually enabling testing mode on all filter modules lets you thoroughly test the correctness and performance of every installed filter module — or even gather stochastically indepent statistics on the hit/miss rates of your filter modules. obsessed. 🔥
  • debugging — a boolean controlling whether extra debugging information should be logged by Courier::Filter. defaults to false. and heads up: you need to enable debugging mode for filter modules separately. 🙈

💅 Instance methods 💅

here are the instance methods, she's got range:

run: throws Courier::Error, Perl exceptions

Runs the Courier::Filter. listens for connections from Courier on the courierfilter socket, asks the configured filter modules to consider messages, notifies Courier whether messages should be accepted or rejected, and logs message rejections. and when Courier requests termination of the courierfilter, she removes the socket and returns. clean exit, iconic. 👑

name: returns string

Returns the name of the filter process, as set through the constructor's name option.

mandatory: returns boolean

Returns a boolean indicating whether the filter process is a mandatory courierfilter, as set through the constructor's mandatory option.

logger: returns Courier::Filter::Logger logger($logger): returns Courier::Filter::Logger

if $logger is specified, installs a new global logger. returns the (newly) configured global logger.

modules: returns array-ref modules(\@modules): returns array-ref

if \@modules is specified, installs a new filter module group structure. returns the (newly) configured filter modules group structure.

trusting: returns boolean

Returns a boolean indicating the trusting mode, as set through the constructor's trusting option.

testing: returns boolean

Returns a boolean indicating the global testing mode, as set through the constructor's testing option.

debugging: returns boolean debugging($debugging): returns boolean

if $debugging is specified, sets the global debugging mode. returns a boolean indicating the (newly) configured global debugging mode.

⭐ SEE ALSO ⭐

  • courier-filter-perl
  • Courier::Filter::Overview
  • Courier::Filter::Module
  • Courier::Filter::Logger

and for AVAILABILITY, SUPPORT, and LICENSE information? go see Courier::Filter::Overview. iykyk 💜

💜 REFERENCES 💜

🎀 AUTHOR 🎀

Julian Mehnle <julian@mehnle.net> — thank you for your service bestie 🫶

and that's the whole page!! 💖 this was perl v5.34.0 flavor, dated 2022-10-21, and yeah it's Courier::Filter(3pm) — go filter some mail, you got this, bye bestieee 🦋✨🎀

📦 where this page comes from