1Mail::SpamAssassin::PluUgsienr(3C)ontributed Perl DocumeMnatialt:i:oSnpamAssassin::Plugin(3)
2
6 Mail::SpamAssassin::Plugin - SpamAssassin plugin base class
7
9 SpamAssassin configuration:
10 loadplugin MyPlugin /path/to/myplugin.pm
12 Perl code:
14 package MyPlugin;
16 use Mail::SpamAssassin::Plugin;
18 our @ISA = qw(Mail::SpamAssassin::Plugin);
19 sub new {
21 my ($class, $mailsa) = @_;
22 # the usual perlobj boilerplate to create a subclass object
24 $class = ref($class) ⎪⎪ $class;
25 my $self = $class->SUPER::new($mailsa);
26 bless ($self, $class);
27 # then register an eval rule, if desired...
29 $self->register_eval_rule ("check_for_foo");
30 # and return the new plugin object
32 return $self;
33 }
34 ...methods...
36 1;
38
40 This is the base class for SpamAssassin plugins; all plugins must be
41 objects that implement this class.
42 This class provides no-op stub methods for all the callbacks that a
44 plugin can receive. It is expected that your plugin will override one
45 or more of these stubs to perform its actions.
46 SpamAssassin implements a plugin chain; each callback event is passed
48 to each of the registered plugin objects in turn. Any plugin can call
49 "$self->inhibit_further_callbacks()" to block delivery of that event to
50 later plugins in the chain. This is useful if the plugin has handled
51 the event, and there will be no need for later plugins to handle it as
52 well.
53 If you're looking to write a simple eval rule, skip straight to "regis‐
55 ter_eval_rule()", below.
56
58 In all the plugin APIs below, "options" refers to a reference to a hash
59 containing name-value pairs. This is used to ensure future-compati‐
60 bility, in that we can add new options in future without affecting
61 objects built to an earlier version of the API.
62 For example, here would be how to print out the "line" item in a
64 "parse_config()" method:
65 sub parse_config {
67 my ($self, $opts) = @_;
68 print "MyPlugin: parse_config got ".$opts->{line}."\n";
69 }
70
72 The following methods can be overridden by subclasses to handle events
73 that SpamAssassin will call back to:
74 $plugin = MyPluginClass->new ($mailsaobject)
76 Constructor. Plugins that need to register themselves will need to
77 define their own; the default super-class constructor will work
78 fine for plugins that just override a method.
79 Note that subclasses must provide the $mailsaobject to the super‐
81 class constructor, like so:
82 my $self = $class->SUPER::new($mailsaobject);
84 Lifecycle note: plugins that will need to store per-scan state
86 should not store that on the Plugin object; see "check_start()"
87 below. It is also likewise recommended that configuration settings
88 be stored on the Conf object; see "parse_config()".
89 $plugin->parse_config ( { options ... } )
91 Parse a configuration line that hasn't already been handled.
92 "options" is a reference to a hash containing these options:
93 line
95 The line of configuration text to parse. This has leading and
96 trailing whitespace, and comments, removed.
97 key The configuration key; ie. the first "word" on the line.
99 value
101 The configuration value; everything after the first "word" and
102 any whitespace after that.
103 conf
105 The "Mail::SpamAssassin::Conf" object on which the configura‐
106 tion data should be stored.
107 user_config
109 A boolean: 1 if reading a user's configuration, 0 if reading
110 the system-wide configuration files.
111 If the configuration line was a setting that is handled by this
113 plugin, the method implementation should call "$self->inhibit_fur‐
114 ther_callbacks()".
115 If the setting is not handled by this plugin, the method should
117 return 0 so that a later plugin may handle it, or so that SpamAs‐
118 sassin can output a warning message to the user if no plugin under‐
119 stands it.
120 Lifecycle note: it is suggested that configuration be stored on the
122 "Mail::SpamAssassin::Conf" object in use, instead of the plugin
123 object itself. That can be found as "$plugin->{main}->{conf}".
124 This allows per-user and system-wide configuration to be dealt with
125 correctly, with per-user overriding system-wide.
126 $plugin->finish_parsing_end ( { options ... } )
128 Signals that the system-wide configuration parsing has just fin‐
129 ished, and SpamAssassin is nearly ready to check messages.
130 "options" is a reference to a hash containing these options:
132 conf
134 The "Mail::SpamAssassin::Conf" object on which the configura‐
135 tion data should be stored.
136 Note: there are no guarantees that the internal data structures of
138 SpamAssassin will not change from release to release. In particu‐
139 lar to this plugin hook, if you modify the rules data structures in
140 a third-party plugin, all bets are off until such time that an API
141 is present for modifying that configuration data.
142 $plugin->user_conf_parsing_end ( { options ... } )
144 Signals that the per-user configuration parsing has just finished,
145 and SpamAssassin is nearly ready to check messages. If
146 "allow_user_rules" is enabled in the configuration, it is possible
147 that additional rules have been added in the user configuration
148 file, since the "finish_parsing_end" plugin hook invocation was
149 called.
150 "options" is a reference to a hash containing these options:
152 conf
154 The "Mail::SpamAssassin::Conf" object on which the configura‐
155 tion data should be stored.
156 $plugin->signal_user_changed ( { options ... } )
158 Signals that the current user has changed for a new one.
159 username
161 The new user's username.
162 user_dir
164 The new user's home directory. (equivalent to "~".)
165 userstate_dir
167 The new user's storage directory. (equivalent to "~/.spamassas‐
168 sin".)
169 $plugin->services_authorized_for_username ( { options ... } )
171 Validates that a given username is authorized to use certain ser‐
172 vices.
173 In order to authorize a user, the plugin should first check that it
175 can handle any of the services passed into the method and then set
176 the value for each allowed service to true (or any non-negative
177 value).
178 The current supported services are: bayessql
180 username
182 A username
183 services
185 Reference to a hash containing the services you want to check.
186 {
188 'bayessql' => 0
190 }
192 conf
194 The "Mail::SpamAssassin::Conf" object on which the configura‐
195 tion data should be stored.
196 $plugin->compile_now_start ( { options ... } )
198 This is called at the beginning of Mail::SpamAssassin::com‐
199 pile_now() so plugins can do any necessary initialization for
200 multi-process SpamAssassin (such as spamd or mass-check -j).
201 use_user_prefs
203 The value of $use_user_prefs option in compile_now().
204 keep_userstate
206 The value of $keep_userstate option in compile_now().
207 $plugin->compile_now_finish ( { options ... } )
209 This is called at the end of Mail::SpamAssassin::compile_now() so
210 plugins can do any necessary initialization for multi-process Spa‐
211 mAssassin (such as spamd or mass-check -j).
212 use_user_prefs
214 The value of $use_user_prefs option in compile_now().
215 keep_userstate
217 The value of $keep_userstate option in compile_now().
218 $plugin->check_start ( { options ... } )
220 Signals that a message check operation is starting.
221 permsgstatus
223 The "Mail::SpamAssassin::PerMsgStatus" context object for this
224 scan.
225 Lifecycle note: it is recommended that rules that need to track
227 test state on a per-scan basis should store that state on this
228 object, not on the plugin object itself, since the plugin
229 object will be shared between all active scanners.
230 The message being scanned is accessible through the "$perms‐
232 gstatus->get_message()" API; there are a number of other public
233 APIs on that object, too. See "Mail::SpamAssassin::PerMsgSta‐
234 tus" perldoc.
235 $plugin->check_main ( { options ... } )
237 Signals that a message should be checked. Note that implementa‐
238 tions of this hook should return 1.
239 permsgstatus
241 The "Mail::SpamAssassin::PerMsgStatus" context object for this
242 scan.
243 $plugin->check_tick ( { options ... } )
245 Called periodically during a message check operation. A callback
246 set for this method is a good place to run through an event loop
247 dealing with network events triggered in a "parse_metadata" method,
248 for example.
249 permsgstatus
251 The "Mail::SpamAssassin::PerMsgStatus" context object for this
252 scan.
253 $plugin->check_post_dnsbl ( { options ... } )
255 Called after the DNSBL results have been harvested. This is a good
256 place to harvest your own asynchronously-started network lookups.
257 permsgstatus
259 The "Mail::SpamAssassin::PerMsgStatus" context object for this
260 scan.
261 $plugin->check_post_learn ( { options ... } )
263 Called after auto-learning may (or may not) have taken place. If
264 you wish to perform additional learning, whether or not auto-learn‐
265 ing happens, this is the place to do it.
266 permsgstatus
268 The "Mail::SpamAssassin::PerMsgStatus" context object for this
269 scan.
270 $plugin->check_end ( { options ... } )
272 Signals that a message check operation has just finished, and the
273 results are about to be returned to the caller.
274 permsgstatus
276 The "Mail::SpamAssassin::PerMsgStatus" context object for this
277 scan. The current score, names of rules that hit, etc. can be
278 retrieved using the public APIs on this object.
279 $plugin->finish_tests ( { options ... } )
281 Called via SpamAssassin::finish and should clear up any tests that
282 a plugin has added to the namespace.
283 In certain circumstances, plugins may find it useful to compile
285 perl functions from the ruleset, on the fly. It is important to
286 remove these once the "Mail::SpamAssassin" object is deleted, how‐
287 ever, and this API allows this.
288 Each plugin is responsible for its own generated perl functions.
290 conf
292 The "Mail::SpamAssassin::Conf" object on which the configura‐
293 tion data should be stored.
294 $plugin->extract_metadata ( { options ... } )
296 Signals that a message is being mined for metadata. Some plug‐
297 ins may wish to add their own metadata as well.
298 msg The "Mail::SpamAssassin::Message" object for this message.
300 $plugin->parsed_metadata ( { options ... } )
302 Signals that a message's metadata has been parsed, and can now
303 be accessed by the plugin.
304 permsgstatus
306 The "Mail::SpamAssassin::PerMsgStatus" context object for
307 this scan.
308 $plugin->start_rules ( { options ... } )
310 Called before testing a set of rules of a given type and prior‐
311 ity.
312 permsgstatus
314 The "Mail::SpamAssassin::PerMsgStatus" context object for
315 this scan.
316 ruletype
318 The type of the rules about to be performed.
319 priority
321 The priority level of the rules about to be performed.
322 $plugin->hit_rule ( { options ... } )
324 Called when a rule fires.
325 permsgstatus
327 The "Mail::SpamAssassin::PerMsgStatus" context object for
328 this scan.
329 ruletype
331 The type of the rule that fired.
332 rulename
334 The name of the rule that fired.
335 score
337 The rule's score in the active scoreset.
338 $plugin->ran_rule ( { options ... } )
340 Called after a rule has been tested, whether or not it fired.
341 When the rule fires, the hit_rule callback is always called
342 before this.
343 permsgstatus
345 The "Mail::SpamAssassin::PerMsgStatus" context object for
346 this scan.
347 ruletype
349 The type of the rule that was tested.
350 rulename
352 The name of the rule that was tested.
353 $plugin->autolearn_discriminator ( { options ... } )
355 Control whether a just-scanned message should be learned as
356 either spam or ham. This method should return one of 1 to
357 learn the message as spam, 0 to learn as ham, or "undef" to not
358 learn from the message at all.
359 permsgstatus
361 The "Mail::SpamAssassin::PerMsgStatus" context object for
362 this scan.
363 $plugin->autolearn ( { options ... } )
365 Signals that a message is about to be auto-learned as either
366 ham or spam.
367 permsgstatus
369 The "Mail::SpamAssassin::PerMsgStatus" context object for
370 this scan.
371 isspam
373 1 if the message is spam, 0 if ham.
374 $plugin->per_msg_finish ( { options ... } )
376 Signals that a "Mail::SpamAssassin::PerMsgStatus" object is
377 being destroyed, and any per-scan context held on that object
378 by this plugin should be destroyed as well.
379 Normally, any member variables on the "PerMsgStatus" object
381 will be cleaned up automatically -- but if your plugin has made
382 a circular reference on that object, this is the place to break
383 them so that garbage collection can operate correctly.
384 permsgstatus
386 The "Mail::SpamAssassin::PerMsgStatus" context object for
387 this scan.
388 $plugin->have_shortcircuited ( { options ... } )
390 Has the current scan operation 'short-circuited'? In other
391 words, can further scanning be skipped, since the message is
392 already definitively classified as either spam or ham?
393 Plugins should return 0 to indicate that scanning should con‐
395 tinue, or 1 to indicate that short-circuiting has taken effect.
396 permsgstatus
398 The "Mail::SpamAssassin::PerMsgStatus" context object for
399 this scan.
400 $plugin->bayes_learn ( { options ... } )
402 Called at the end of a bayes learn operation.
403 This phase is the best place to map the raw (original) token
405 value to the SHA1 hashed value.
406 toksref
408 Reference to hash returned by call to tokenize. The hash
409 takes the format of:
410 {
412 'SHA1 Hash Value' => 'raw (original) value'
414 }
416 NOTE: This data structure has changed since it was origi‐
418 nally introduced in version 3.0.0. The values are no
419 longer perl anonymous hashes, they are a single string con‐
420 taining the raw token value. You can test for backwards
421 compatability by checking to see if the value for a key is
422 a reference to a perl HASH, for instance:
423 if (ref($toksref->{$sometokenkey}) eq 'HASH') {...
425 If it is, then you are using the old interface, otherwise
427 you are using the current interface.
428 isspam
430 Boolean value stating what flavor of message the tokens
431 represent, if true then message was specified as spam,
432 false is nonspam. Note, when function is scan then isspam
433 value is not valid.
434 msgid
436 Generated message id of the message just learned.
437 msgatime
439 Received date of the current message or current time if
440 received date could not be determined. In addition, if the
441 receive date is more than 24 hrs into the future it will be
442 reset to current datetime.
443 $plugin->bayes_forget ( { options ... } )
445 Called at the end of a bayes forget operation.
446 toksref
448 Reference to hash returned by call to tokenize. See
449 bayes_learn documentation for additional information on the
450 format.
451 isspam
453 Boolean value stating what flavor of message the tokens
454 represent, if true then message was specified as spam,
455 false is nonspam. Note, when function is scan then isspam
456 value is not valid.
457 msgid
459 Generated message id of the message just forgotten.
460 $plugin->bayes_scan ( { options ... } )
462 Called at the end of a bayes scan operation. NOTE: Will not be
463 called in case of error or if the message is otherwise skipped.
464 toksref
466 Reference to hash returned by call to tokenize. See
467 bayes_learn documentation for additional information on the
468 format.
469 probsref
471 Reference to hash of calculated probabilities for tokens
472 found in the database.
473 {
475 'SHA1 Hash Value' => {
477 'prob' => 'calculated probability',
479 'spam_count' => 'Total number of spam msgs w/ token',
481 'ham_count' => 'Total number of ham msgs w/ token',
483 'atime' => 'Atime value for token in database'
485 }
487 }
489 score
491 Score calculated for this particular message.
492 msgatime
494 Calculated atime of the message just learned, note it may
495 have been adjusted if it was determined to be too far into
496 the future.
497 significant_tokens
499 Array ref of the tokens found to be significant in deter‐
500 mining the score for this message.
501 $plugin->plugin_report ( { options ... } )
503 Called if the message is to be reported as spam. If the
504 reporting system is available, the variable
505 "$options-<gt"{report}-><gt>report_available}> should be set to
506 1; if the reporting system successfully reported the message,
507 the variable "$options-<gt"{report}-><gt>report_return}> should
508 be set to 1.
509 report
511 Reference to the Reporter object ("$options-<gt"{report}>
512 in the paragraph above.)
513 text
515 Reference to a markup removed copy of the message in scalar
516 string format.
517 msg Reference to the original message object.
519 $plugin->plugin_revoke ( { options ... } )
521 Called if the message is to be reported as ham (revokes a spam
522 report). If the reporting system is available, the variable
523 "$options-<gt"{revoke}-><gt>revoke_available}> should be set to
524 1; if the reporting system successfully revoked the message,
525 the variable "$options-<gt"{revoke}-><gt>revoke_return}> should
526 be set to 1.
527 revoke
529 Reference to the Reporter object ("$options-<gt"{revoke}>
530 in the paragraph above.)
531 text
533 Reference to a markup removed copy of the message in scalar
534 string format.
535 msg Reference to the original message object.
537 $plugin->whitelist_address( { options ... } )
539 Called when a request is made to add an address to a persistent
540 address list.
541 address
543 Address you wish to add.
544 $plugin->blacklist_address( { options ... } )
546 Called when a request is made to add an address to a persistent
547 address list.
548 address
550 Address you wish to add.
551 $plugin->remove_address( { options ... } )
553 Called when a request is made to remove an address to a persis‐
554 tent address list.
555 address
557 Address you wish to remove.
558 $plugin->spamd_child_init ()
560 Called when a new child starts up under spamd.
561 $plugin->log_scan_result ( { options ... } )
563 Called when spamd has completed scanning a message. Currently,
564 only spamd calls this API.
565 result
567 The 'result: ...' line for this scan. Format is as
568 described at http://wiki.apache.org/spamassassin/SpamdSys‐
569 logFormat.
570 $plugin->spamd_child_post_connection_close ()
572 Called when child returns from handling a connection.
573 If there was an accept failure, the child will die and this
575 code will not be called.
576 $plugin->finish ()
578 Called when the "Mail::SpamAssassin" object is destroyed.
579
581 These methods provide an API for plugins to register themselves to
582 receive specific events, or control the callback chain behaviour.
583 $plugin->register_eval_rule ($nameofevalsub)
585 Plugins that implement an eval test will need to call this, so that
586 SpamAssassin calls into the object when that eval test is encoun‐
587 tered. See the REGISTERING EVAL RULES section for full details.
588 $plugin->register_generated_rule_method ($nameofsub)
590 In certain circumstances, plugins may find it useful to compile
591 perl functions from the ruleset, on the fly. It is important to
592 remove these once the "Mail::SpamAssassin" object is deleted, how‐
593 ever, and this API allows this.
594 Once the method $nameofsub has been generated, call this API with
596 the name of the method (including full package scope). This indi‐
597 cates that it's a temporary piece of generated code, built from the
598 SpamAssassin ruleset, and when "Mail::SpamAssassin::finish()" is
599 called, the method will be destroyed.
600 This API was added in SpamAssassin 3.2.0.
602 $plugin->register_method_priority($methodname, $priority)
604 Indicate that the method named $methodname on the current object
605 has a callback priority of $priority.
606 This is used by the plugin handler to determine the relative order
608 of callbacks; plugins with lower-numbered priorities are called
609 before plugins with higher-numbered priorities. Each method can
610 have a different priority value. The default value is 0. The
611 ordering of callbacks to methods with equal priority is undefined.
612 Typically, you only need to worry about this if you need to ensure
614 your plugin's method is called before another plugin's implementa‐
615 tion of that method. It should be called from your plugin's con‐
616 structor.
617 This API was added in SpamAssassin 3.2.0.
619 $plugin->inhibit_further_callbacks()
621 Tells the plugin handler to inhibit calling into other plugins in
622 the plugin chain for the current callback. Frequently used when
623 parsing configuration settings using "parse_config()".
624 dbg($message)
626 Output a debugging message $message, if the SpamAssassin object is
627 running with debugging turned on.
628 NOTE: This function is not available in the package namespace of
630 general plugins and can't be called via $self->dbg(). If a plugin
631 wishes to output debug information, it should call "Mail::SpamAs‐
632 sassin::Plugin::dbg($msg)".
633 info($message)
635 Output an informational message $message, if the SpamAssassin
636 object is running with informational messages turned on.
637 NOTE: This function is not available in the package namespace of
639 general plugins and can't be called via $self->info(). If a plugin
640 wishes to output debug information, it should call "Mail::SpamAs‐
641 sassin::Plugin::info($msg)".
642
644 Plugins that implement an eval test must register the methods that can
645 be called from rules in the configuration files, in the plugin class'
646 constructor.
647 For example,
649 $plugin->register_eval_rule ('check_for_foo')
651 will cause "$plugin->check_for_foo()" to be called for this SpamAssas‐
653 sin rule:
654 header FOO_RULE eval:check_for_foo()
656 Note that eval rules are passed the following arguments:
658 - The plugin object itself
660 - The "Mail::SpamAssassin::PerMsgStatus" object calling the rule
661 - standard arguments for the rule type in use
662 - any and all arguments as specified in the configuration file
663 In other words, the eval test method should look something like
665 this:
666 sub check_for_foo {
668 my ($self, $permsgstatus, ...arguments...) = @_;
669 ...code returning 0 or 1
670 }
671 Note that the headers can be accessed using the "get()" method on
673 the "Mail::SpamAssassin::PerMsgStatus" object, and the body by
674 "get_decoded_stripped_body_text_array()" and other similar methods.
675 Similarly, the "Mail::SpamAssassin::Conf" object holding the cur‐
676 rent configuration may be accessed through "$permsgsta‐
677 tus->{main}->{conf}".
678 The eval rule should return 1 for a hit, or 0 if the rule is not
680 hit.
681 State for a single message being scanned should be stored on the
683 $checker object, not on the $self object, since $self persists
684 between scan operations. See the 'lifecycle note' on the
685 "check_start()" method above.
686
688 Plugins will be called with the same arguments as a standard EvalTest.
689 Different rule types receive different information by default:
690 - header tests: no extra arguments
692 - body tests: fully rendered message as array reference
693 - rawbody tests: fully decoded message as array reference
694 - full tests: pristine message as scalar reference
695 The configuration file arguments will be passed in after the stan‐
697 dard arguments.
698
700 Note that if you write a plugin and need to determine if a particular
701 helper method is supported on "Mail::SpamAssassin::Plugin", you can do
702 this:
703 if ($self->can("name_of_method")) {
705 eval {
706 $self->name_of_method(); # etc.
707 }
708 } else {
709 # take fallback action
710 }
711 The same applies for the public APIs on objects of other types, such as
713 "Mail::SpamAssassin::PerMsgStatus".
714
716 "Mail::SpamAssassin"
717 "Mail::SpamAssassin::PerMsgStatus"
719 http://wiki.apache.org/spamassassin/PluginWritingTips
721 http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163
723perl v5.8.8 2008-01-05 Mail::SpamAssassin::Plugin(3)