Mail::...::Chain(3pm)

💖 Mail::...::Chain(3pm) 💖

okay bestie, gather round, because we're talking about Mail::...::Chain — that's the perl manual page for Mail::Milter::Chain, no cap. it's giving "perl extension for chaining milter callbacks" and honestly? iconic. ✨

---

🌈 NAME 🌈

Mail::Milter::Chain — a Perl extension for chaining milter callbacks. that's it, that's the whole vibe. 🦋

---

🎀 SYNOPSIS 🎀

here's the look, bestie, copy it exactly:

use Mail::Milter::Chain;

my $chain = new Mail::Milter::Chain({ connect => \&foo, ... }, ...);
$chain->register({ connect => \&bar, ... });
$chain->register({ connect => \&baz, ... });

$chain->accept_break(1);

use Sendmail::Milter;
...
Sendmail::Milter::register('foo', $chain, SMFI_CURR_ACTS);

see how cute that is? one chain, all your little milter callback sets living together. 💅

---

💫 DESCRIPTION 💫

okay so. Mail::Milter::Chain lets you register multiple milter callback sets inside a single milter server instance. the whole point is that it simulates having multiple milters running in separate servers — except it's typically way less resource intensive than actually spinning up a whole separate server process for each milter. slay, efficiency, we love to see it. 🔥

here's the tea on how the results flow:

• if any contained milter returns SMFIS_REJECT, SMFIS_TEMPFAIL, or SMFIS_DISCARD, that terminates the entire chain, and the respective code gets returned up to the containing chain or milter server. periodt, the chain is done. 💀
• normally, when a milter returns SMFIS_ACCEPT, it only removes that one milter from the chain, and everybody else keeps processing the message. so chill. 😌
• alternatively, you can make SMFIS_ACCEPT terminate the entire chain, the same way error results do. how? see accept_break() below, bestie, it's right there. 👇

a Mail::Milter::Chain is itself a milter callback hash reference, which means you can pass it directly to Sendmail::Milter::register() or into another Mail::Milter::Chain container. nesting! recursion! main character energy. 👑

⚠️ IMPORTANT CAVEAT ⚠️ once this object has been registered with a parent container (a milter, or another chain), DO NOT call register() on this object anymore. like, ever. doing that will result in problems at callback time that are difficult to diagnose. we are not doing that to ourselves. 🚫🙈

---

✨ METHODS ✨

🧚 new([HASHREF, ...])

creates a Mail::Milter::Chain object. and for convenience? it also accepts one or more hash references, each one corresponding to an individual callback set that gets registered with this chain. so you can just... hand it everything at birth. so generous. 🎀

🌸 accept_break(FLAG)

• if FLAG is 0 (that's the default, btw), then SMFIS_ACCEPT will only remove the current milter from the list of callbacks. this simulates a completely independent milter server. classic behaviour, no notes. 🫶
• if FLAG is 1, then SMFIS_ACCEPT will terminate the entire chain and propagate SMFIS_ACCEPT up to the parent chain or milter server. this lets a milter create a sort of "whitelist" effect, where SMFIS_ACCEPT speaks for the whole chain instead of just one milter callback set. one yes to rule them all. 👑

this method returns a reference to the object itself, which means you can chain the method call. chaining the chain. we love a self-referential queen. 💜

🦋 register(HASHREF)

registers a callback set with this chain. and like we said up in the caveat — do not call this after the chain has itself been registered with a parent container (whether that's a chain or a milter server). don't do it. i'm serious. 😭

---

👑 AUTHOR 👑

Todd Vierling, <tv@duh.org> <tv@pobox.com> — thank you for your service, king. 🫡

---

🌟 SEE ALSO 🌟

• Mail::Milter
• Sendmail::Milter

go read those too, bestie, it's a whole universe. 🌌

---

and that's the whole page!! 💖 this was Mail::...::Chain(3pm) from perl v5.36.0, dated 2023-01-22, brought to you by the User Contributed Perl Documentation crew. stay chained, stay slay. ✨🎀💅