Mail::...rapper(3pm)

💖 Mail::Milter::ContextWrapper 💖

okay so bestie, welcome to Mail::Milter::ContextWrapper, a lil Perl extension that wrappers the milter context (yes, "wrapper" as a verb, we're doing that today 💅). It lives in the Mail::...rapper(3pm) page of the User Contributed Perl Documentation, and it's about to become your new hyperfixation.

---

✨ NAME ✨

Mail::Milter::ContextWrapper — a Perl extension for wrappering the milter context. literally what it says on the tin, no cap.

---

🌸 SYNOPSIS 🌸

use Mail::Milter::ContextWrapper;

my $oldctx = ($ctx from callback);

# in the connect_callback
$oldctx->setpriv(new Mail::Milter::ContextWrapper($ctx,
    { methodname => \&methodimpl[, ...] }));

# in all callbacks
my $newctx = $ctx->getpriv();

# in the close_callback
$oldctx->setpriv(undef);

look at that. iconic. we love a tidy lifecycle. 🦋

---

🎀 DESCRIPTION 🎀

So Mail::Milter::ContextWrapper wraps the milter context with replacement methods defined by the caller. Translation bestie: you get to intercept what the context object does and then mess with it from inside a Mail::Milter::Wrapper. main character energy fr fr. 👑

Now, because the wrappering has to happen on every single callback (every one, no skipping, periodt), this implementation suggests you embed the wrapper inside the private data of the milter itself. And the way it stays compatible with existing milters is by giving you its own separate setpriv and getpriv methods inside the wrapper — and those do not propagate up to the embedded context object. sneaky? no. intentional. 💅

---

💜 METHODS 💜

new(CTX, { NAME => &SUB[, ...] })

Creates a Mail::Milter::ContextWrapper object. Call this from the "connect" callback and then hand it right back over to "setpriv()". 🫶

The NAMEs are the names of the methods you wanna override inside the wrapper. Those methods get called with the wrapper as the first argument — just like a normal object method, because it is one, bestie.

getpriv()

Returns a private data item that was set by "setpriv()". Peep Sendmail::Milter if you want more lore on that. This implementation stores the datum in the wrapper, which is exactly what lets the parent context keep a reference to the wrapper itself. cute, right? 🌸

This method cannot be overridden by the user. hands off, bestie. 🙈

get_ctx()

Returns the parent context object stored inside this wrapper. Typically used by your method overrides so they can defer back to the real method. very "i'm just gonna pass this along to the original, no drama" of you. ✨

This method cannot be overridden by the user. 🙈

get_key(NAME)

Get a keyed data item, separate from the "getpriv" private data. It's out-of-band data storage, so you don't have to clobber the single "priv" data item that most milters use. one slot for you, one slot for your stuff. balance. 🧚

getpriv()

Sets a private data item to be returned by "getpriv()". See Sendmail::Milter for more information. This implementation stores the datum in the wrapper, thus allowing the parent context to store a reference to the wrapper itself.

This method cannot be overridden by the user. 🙈 (and yeah, the page really does say getpriv() twice here — we are keeping it exactly as printed, bestie. not me fixing the typo, no ma'am. 💀)

set_key(NAME, VALUE)

set_key(NAME => VALUE)

Set a keyed data item, separate from the "getpriv" private data. Again: out-of-band storage, so you never gotta clobber that single "priv" data item most milters are hogging. two ways to call it, both slay. 🔥

---

👑 AUTHOR 👑

Todd Vierling, <tv@duh.org> <tv@pobox.com> — the legend who wrote all this. we stan. 💖

---

🌈 SEE ALSO 🌈

• Mail::Milter
• Sendmail::Milter

---

and that's the whole page, bestie!! 🎀 this was perl v5.36.0, dated 2023-01-22, filed under Mail::...rapper(3pm) — go forth and wrapper your contexts, ily, bye 🦋💅✨