Mail::...esolver(3pm)

🦋 NAME 🦋

hey bestie, welcome to Mail::SpamAssassin::DnsResolver — it's the DNS resolution engine ✨ (that's the 3pm perl manual page for it, btw, no cap)

---

💖 DESCRIPTION 💖

okay so listen. this is a DNS resolution engine for SpamAssassin, and the whole reason it exists is tea: it was implemented in order to reduce file descriptor usage by Net::DNS and also to avoid a response collision bug in that module. like, they built a whole engine because Net::DNS was doing too much 💀. iconic behavior honestly.

---

🎀 METHODS 🎀

• $res->load_resolver() — loads up the Net::DNS::Resolver object. returns 0 if Net::DNS cannot be used, and 1 if it is available. so basically a vibe check on Net::DNS 🌸
• $resolver = $res->get_resolver() — hands you back the Net::DNS::Resolver object. that's it, that's the whole thing 🫶
• $res->configured_nameservers() — gets you a list of nameservers as configured by dns_server directives, or as provided by Net::DNS — typically straight from /etc/resolv.conf 📜
• $res->available_nameservers() — get or set a list of currently available nameservers. typically this is a known-to-be-good subset of the configured nameservers, like the ones that aren't flaking on you 🙈
• $res->connect_sock() — re-connects to the first nameserver listed in /etc/resolv.conf or a similar platform-dependent source, as provided by Net::DNS 🔌
• $res->get_sock() — returns the IO::Socket::INET object that's used to talk to the nameserver 💬
• $packet = new_dns_packet ($domain, $type, $class) — a wrapper for Net::DNS::Packet::new() that traps a die thrown by it. very protective gf energy 🛡️

to use this, you change calls to Net::DNS::Resolver::bgsend from:

$res->bgsend($domain, $type);

to:

$res->bgsend(Mail::SpamAssassin::DnsResolver::new_dns_packet($domain, $type, $class));

• $id = $res->bgsend($domain, $type, $class, $cb) — DIRECT USE DISCOURAGED, please use bgsend_and_start_lookup in plugins 🚫 (bestie, they're literally asking you nicely)

it's quite similar to Net::DNS::Resolver::bgsend, except that when a reply packet eventually arrives, and poll_responses gets called, the callback sub reference $cb will be called 🎯

note that $type and $class may be undef, in which case they will default to A and IN, respectively. (defaults, we love her ✨)

the callback sub will be called with three arguments — the packet that was delivered, and an id string that fingerprints the query packet and the expected reply. the third argument is a timestamp (Unix time, floating point), captured at the time the packet was collected. it is expected that a closure callback be used, like so:

my $id = $self->{resolver}->bgsend($domain, $type, undef, sub {
      my ($reply, $reply_id, $timestamp) = @_;
      $self->got_a_reply($reply, $reply_id);
    });

the callback can ignore the reply as an invalid packet sent to the listening port if the reply id does not match the return value from bgsend 👀

• $id = $res->bgread() — similar to Net::DNS::Resolver::bgread. reads a DNS packet from a supplied socket, decodes it, and returns a Net::DNS::Packet object if successful. dies on error 😭 (dramatic but true)
• $nfound = $res->poll_responses() — checks whether there are any bgsend reply packets ready, and returns the number of such packets delivered to their callbacks 🔔
• $res->bgabort() — call this to release pending requests from memory, when aborting backgrounded requests, or when the scan is complete. Mail::SpamAssassin::PerMsgStatus::check calls this before returning. it's giving cleanup crew 🧹
• $packet = $res->send($name, $type, $class) — emulates Net::DNS::Resolver::send().

warning bestie: this subroutine is a simple synchronous leftover from SpamAssassin version 3.3 and does not participate in packet query caching and callback grouping as implemented by AsyncLoop::bgsend_and_start_lookup(). as such it should be avoided for mainstream usage. 👑 currently used through Mail::SPF::Server by the SPF plugin. (so like, it's still employed, just not for the cool stuff)

• $res->errorstring() — little more than a stub for callers expecting this from Net::DNS::Resolver.

if called immediately after a call to $res->send this will return query timed out if the $res->send DNS query timed out. otherwise unknown error or no error will be returned. 🙃

no other errors are reported. that's it, that's the whole error menu.

• $res->finish_socket() — resets the socket when you're done with it 🚿
• $res->finish() — cleans up for destruction 💅

---

and that's the page, bestie 🫶 this was perl v5.40.1, dated 2026-07-23, pulled from the 3pm User Contributed Perl Documentation section. slay, go resolve some DNS 🌈💖