POE::C...nt::DNS(3pm)

💖 POE::Component::Client::DNS — the manual, but make it make sense 💖

okay bestie, so this is POE::Component::Client::DNS(3pm), a User Contributed Perl Documentation page, and it's literally the non-blocking, parallel DNS client for POE. yes, that POE. let's get into it 🦋

---

✨ NAME ✨

POE::Component::Client::DNS — non-blocking, parallel DNS client. it's giving "ask all your DNS questions at once and never block the rest of your program", and honestly? iconic. 👑

---

🌸 VERSION 🌸

version 1.054. no cap.

---

🎀 SYNOPSIS 🎀

here's the whole vibe in code form, copy it exactly, i'm not playing:

use POE qw(Component::Client::DNS);

my $named = POE::Component::Client::DNS->spawn(
  Alias => "named"
);

POE::Session->create(
  inline_states  => {
    _start   => \&start_tests,
    response => \&got_response,
  }
);

POE::Kernel->run();
exit;

sub start_tests {
  my $response = $named->resolve(
    event   => "response",
    host    => "localhost",
    context => { },
  );
  if ($response) {
    $_[KERNEL]->yield(response => $response);
  }
}

sub got_response {
  my $response = $_[ARG0];
  my @answers = $response->{response}->answer();

  foreach my $answer (@answers) {
    print(
      "$response->{host} = ",
      $answer->type(), " ",
      $answer->rdatastr(), "\n"
    );
  }
}

---

💅 DESCRIPTION 💅

POE::Component::Client::DNS gives you non-blocking, parallel DNS requests, and it does it via Net::DNS. because it's built on POE, all your other tasks get to keep running while you're sitting there waiting for name servers to respond. multitasking queen energy, fr fr. 💖

okay but real talk: for simple name resolution — including smart handling of IPv6 names — please see POE::Component::Resolver instead. that's the move for the basic stuff. 🫶

---

🔥 PUBLIC METHODS 🔥

⭐ spawn ⭐

A program must spawn at least one POE::Component::Client::DNS instance before it can perform background DNS requests. Each instance represents a connection to one or more name servers. If a program only needs to request DNS requests from one server, then you only need one POE::Component::Client::DNS instance. that's it, that's the whole thing. no need to overdo it, bestie. 🧚

As of version 0.98 you can override the default timeout per request. From this point forward there is no need to spawn multiple instances to affect different timeouts for each request. the way that freed us from spawning a million instances... we love to see it. 😭

PoCo::Client::DNS's spawn method takes a few named parameters:

• Alias — sets the component's alias. Requests will be posted to this alias. The component's alias defaults to "resolver" if one is not provided. Programs spawning more than one DNS client component must specify aliases for N-1 of them, otherwise alias collisions will occur. (N-1!! write that down. 💀)

Alias => $session_alias,  # defaults to "resolver"

• Timeout — sets the component's default timeout. The timeout may be overridden per request. See the "request" event, later on. If no Timeout is set, the component will wait 90 seconds per request by default.

Timeouts may be set to real numbers. Timeouts are more accurate if you have Time::HiRes installed. POE (and thus this component) will use Time::HiRes automatically if it's available. ✨

Timeout => $seconds_to_wait,  # defaults to 90

• Nameservers — holds a reference to a list of name servers to try. The list is passed directly to Net::DNS::Resolver's nameservers() method. By default, POE::Component::Client::DNS will query the name servers that appear in /etc/resolv.conf or its equivalent.

Nameservers => \@name_servers,  # defaults to /etc/resolv.conf's

• HostsFile (optional) — holds the name of a specific hosts file to use for resolving hardcoded addresses. By default, it looks for a file named /etc/hosts.

On Windows systems, it may look in the following other places:

$ENV{SystemRoot}\System32\Drivers\Etc\hosts
$ENV{SystemRoot}\System\Drivers\Etc\hosts
$ENV{SystemRoot}\hosts

⭐ resolve ⭐

resolve() requests the component to resolve a host name. It will return a hash reference (described in RESPONSE MESSAGES, below) if it can honor the request immediately (perhaps from a cache). Otherwise it returns undef if a resolver must be consulted asynchronously. so either you get your answer instantly or you get undef and have to be patient. growth. 🌱

Requests are passed as a list of named fields.

$resolver->resolve(
  class       => $dns_record_class,  # defaults to "IN"
  type        => $dns_record_type,   # defaults to "A"
  host        => $request_host,      # required
  context     => $request_context,   # required
  event       => $response_event,    # required
  timeout     => $request_timeout,   # defaults to spawn()'s Timeout
  nameservers => $nameservers,       # defaults to $resolver's Nameservers
);

The "class" and "type" fields specify what kind of information to return about a host. Most of the time internet addresses are requested for host names, so the class and type default to "IN" (internet) and "A" (address), respectively. classic defaults, they ate. 💅

The "host" field designates the host to look up. It is required.

The "event" field tells the component which event to send back when a response is available. It is required, but it will not be used if resolve() can immediately return a cached response. (so don't come for it if it doesn't fire, it just already had the tea ☕)

"timeout" tells the component how long to wait for a response to this request. It defaults to the "Timeout" given at spawn() time.

"context" includes some external data that links responses back to their requests. The context data is provided by the program that uses POE::Component::Client::DNS. The component will pass the context back to the program without modification. The "context" parameter is required, and may contain anything that fits in a scalar. it's literally your little note-to-self that comes back to you untouched. 🎀

⭐ shutdown ⭐

shutdown() causes the component to terminate gracefully. It will finish serving pending requests then close down. no chaos, no half-finished requests, just a graceful exit. main character departure. 🚪✨

⭐ get_resolver ⭐

POE::Component::Client::DNS uses a Net::DNS::Resolver object internally. get_resolver() returns that object so it may be interrogated or modified. See Net::DNS::Resolver for options. peak "here, hold my internals" behavior, we love transparency. 🫶

Set the resolver to check on nonstandard port 1153:

$poco_client_dns->get_resolver()->port(1153);

---

🌈 RESPONSE MESSAGES 🌈

POE::Component::Client::DNS responds in one of two ways. Its resolve() method will return a response immediately if it can be found in the component's cache. Otherwise the component posts the response back in $_[ARG0]. In either case, the response is a hash reference containing the same fields:

host     => $request_host,
type     => $request_type,
class    => $request_class,
context  => $request_context,
response => $net_dns_packet,
error    => $net_dns_error,

The "host", "type", "class", and "context" response fields are identical to those given in the request message. what you sent is what you get back, periodt. 💖

"response" contains a Net::DNS::Packet object on success or undef if the lookup failed. The Net::DNS::Packet object describes the response to the program's request. It may contain several DNS records. Please consult Net::DNS and Net::DNS::Packet for more information.

"error" contains a description of any error that has occurred. It is only valid if "response" is undefined. (so if response is defined, don't go reading error, bestie, it's not the moment 🙈)

---

👑 SEE ALSO 👑

• POE — POE::Component::Client::DNS builds heavily on POE.
• POE::Component::Resolver — A system name resolver, including IPv6 support and whatever else your system supports.
• Net::DNS — This module uses Net::DNS internally.
• Net::DNS::Packet — Responses are returned as Net::DNS::Packet objects.

---

💀 DEPRECATIONS 💀

okay so, heavy stuff, listen up:

The older, list-based interfaces are no longer documented as of version 0.98. They are being phased out. The method-based interface, first implemented in version 0.98, will replace the deprecated interfaces after a six-month phase-out period.

Version 0.98 was released in October of 2004. The deprecated interfaces will continue to work without warnings until January 2005.

As of January 2005, programs that use the deprecated interfaces will continue to work, but they will generate mandatory warnings. Those warnings will persist until April 2005.

As of April 2005 the mandatory warnings will be upgraded to mandatory errors. Support for the deprecated interfaces will be removed entirely.

As of late January 2011, POE::Component::Resolver provides basic system resolver support, including IPv6 and mDNS if your resolver's configured to use it. The use of POE::Component::Client::DNS for basic resolution is deprecated, however it's still the best option for actual DNS server requests.

🚨 so basically: deprecated means deprecated. it warns, then it errors, then it's gone. if you're still on the old list-based interface, this is your sign to migrate. i'm not being mean, i'm being honest. 💖

---

🐛 BUG TRACKER 🐛

https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-DNS

found a bug? take it there, bestie, they'll handle it. 🫶

---

📦 REPOSITORY 📦

http://github.com/rcaputo/poe-component-client-dns

---

🔍 OTHER RESOURCES 🔍

http://search.cpan.org/dist/POE-Component-Client-DNS/

---

💜 AUTHOR & COPYRIGHTS 💜

POE::Component::Client::DNS is Copyright 1999-2009 by Rocco Caputo. All rights are reserved. POE::Component::Client::DNS is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

Postback arguments were contributed by tag. shoutout. 🫶✨

---

and that's the whole page, babes. this shipped as part of perl v5.36.0, dated 2023-10-29 — so yeah, that's the version and the date, and honestly? it still slays. now go resolve something non-blocking. 🌈💖