<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library\mail;
use seekquarry\yioop\configs as C;
use seekquarry\yioop\library as L;
/**
* Looks up Domain Name System (DNS) records without freezing the mail
* server while it waits for an answer. The mail daemon runs every
* connection through one cooperative event loop, so the ordinary PHP
* dns_get_record call is dangerous there: it blocks until the network
* answers, and a spam sender whose domain has slow or dead DNS can
* stall the whole server on a single lookup. This resolver instead
* sends the query itself over a non-blocking socket and, while it
* waits, hands the event loop a turn (the same cooperative yield the
* mail server already uses for contended file locks) so other
* connections keep moving. Every lookup is bounded by a timeout, after
* which it gives up and reports no records, so a lookup that never
* answers can never wedge the loop. Outside the event loop (command
* line tools and unit tests, where there is no fiber) it simply waits
* on the socket up to the same timeout, so those callers behave as
* before.
*
* The query and answer wire format is the standard one (RFC 1035, the
* base DNS specification), with an Extension Mechanisms for DNS
* (EDNS0, RFC 6891) option attached to each query that raises the
* answer-size limit so a large TXT record such as a DomainKeys
* Identified Mail (DKIM) public key arrives in one datagram instead
* of being truncated.
*/
class AsyncDnsResolver
{
/**
* Address record type: an Internet Protocol version 4 address
* (RFC 1035). Answers carry an "ip" field.
*/
const TYPE_A = 1;
/**
* Mail exchanger record type (RFC 1035): the servers that accept
* mail for a domain. Answers carry "pri" and "target" fields.
*/
const TYPE_MX = 15;
/**
* Text record type (RFC 1035), used here for DKIM public keys,
* Sender Policy Framework (SPF) records, and DMARC policies.
* Answers carry a "txt" field.
*/
const TYPE_TXT = 16;
/**
* Address record type: an Internet Protocol version 6 address
* (RFC 3596). Answers carry an "ipv6" field.
*/
const TYPE_AAAA = 28;
/**
* Pseudo record type that carries the EDNS0 option block
* (RFC 6891). It is never requested on its own; one is added to
* the additional section of every query we send.
*/
const TYPE_OPT = 41;
/**
* The Internet record class (RFC 1035); the only class used for
* ordinary mail lookups.
*/
const CLASS_INTERNET = 1;
/**
* The well known User Datagram Protocol port that name servers
* listen on.
*/
const DNS_PORT = 53;
/**
* Answer size in bytes we advertise through EDNS0. A plain DNS
* datagram is capped at 512 bytes, which truncates many DKIM
* keys; 1232 is the community-recommended safe size that avoids
* fragmentation on the public Internet while comfortably holding
* a normal key.
*/
const UDP_BUFFER = 1232;
/**
* The largest a single name label (the part between dots) may be,
* in bytes (RFC 1035). A longer one marks a malformed name.
*/
const MAX_LABEL_LENGTH = 63;
/**
* Upper bound on how many labels and compression jumps a name may
* take while being read, so a hand-crafted packet that points a
* name at itself cannot spin forever.
*/
const MAX_NAME_HOPS = 128;
/**
* The two high bits set in a length byte mark it as a compression
* pointer rather than a label length (RFC 1035 section 4.1.4).
*/
const COMPRESSION_MASK = 0xC0;
/**
* Mask for the low six bits of the first byte of a compression
* pointer, which are the high bits of the offset it points to.
*/
const COMPRESSION_OFFSET_HIGH = 0x3F;
/**
* The query flag that asks the name server to do the recursive
* work of chasing the answer (RFC 1035): recursion desired.
*/
const FLAG_RECURSION_DESIRED = 0x0100;
/**
* The answer flag that says the reply did not fit and was cut
* short (RFC 1035): the truncation bit.
*/
const FLAG_TRUNCATED = 0x0200;
/**
* Mask for the four low bits of the answer flags, the response
* code that says whether the lookup succeeded (RFC 1035).
*/
const RCODE_MASK = 0x000F;
/**
* Length in bytes of the fixed header at the front of every DNS
* message (RFC 1035).
*/
const HEADER_LENGTH = 12;
/**
* Largest value a sixteen-bit query identifier can take, used to
* pick a random id for each query.
*/
const QUERY_ID_MAX = 0xFFFF;
/**
* Number of microseconds in one second, for splitting a
* fractional timeout into the whole and fractional parts
* stream_select wants.
*/
const MICROSECONDS_PER_SECOND = 1000000;
/**
* Name server addresses read once from the system resolver file,
* kept so the file is not reread on every lookup.
* @var array
*/
public static $servers = null;
/**
* Looks up records of one type for a name and returns them in the
* same array-of-arrays shape the built-in dns_get_record gives, so
* callers need no other change. Returns an empty array when the
* name does not resolve, when the answer says there are no such
* records, or when no name server answers within the timeout; all
* of those mean the same thing to the mail checks, namely treat
* the domain as having no such record.
*
* @param string $name the domain name to look up
* @param int $type one of the TYPE_ constants for the record kind
* @param int $timeout seconds to wait in total before giving up;
* when null the configured MAIL_DNS_TIMEOUT is used
* @return array a list of records, each an associative array with
* the fields for its type, or an empty list
*/
public static function query($name, $type, $timeout = null)
{
$name = trim((string) $name, " \t\n\r\0.");
if ($name === '') {
return [];
}
if ($timeout === null) {
$timeout = C\MAIL_DNS_TIMEOUT;
}
list($id, $packet) = self::buildQuery($name, $type);
if ($packet === '') {
return [];
}
$deadline = microtime(true) + $timeout;
foreach (self::nameservers() as $server) {
$records = self::queryServer($server, $packet, $id, $type,
$deadline);
if ($records !== null) {
return $records;
}
if (microtime(true) >= $deadline) {
break;
}
}
/* No name server answered in time. The lookup is abandoned so
the loop is not held up, but a name that never resolves is
worth a line: it is how a recurrence of the stalled-loop
trouble would show up before it could do harm. */
L\crawlLog("MailDns: no name server answered for " . $name .
" within " . $timeout . "s");
return [];
}
/**
* Builds the raw bytes of a query for one name and record type,
* including the EDNS0 option that raises the answer size limit.
*
* @param string $name the domain name to ask about
* @param int $type one of the TYPE_ constants
* @return array a pair of the random query id and the packet
* bytes; the bytes are empty when the name cannot be encoded
*/
public static function buildQuery($name, $type)
{
$question = self::encodeName($name);
if ($question === '') {
return [0, ''];
}
$id = random_int(0, self::QUERY_ID_MAX);
/* one question, no answers, no authority records, and one
additional record which is the EDNS0 option below */
$header = pack('n6', $id, self::FLAG_RECURSION_DESIRED, 1, 0, 0,
1);
$question .= pack('n2', $type, self::CLASS_INTERNET);
return [$id, $header . $question . self::ednsOption()];
}
/**
* Encodes a domain name into the wire form: each dot-separated
* label written as a length byte then its bytes, ended by a zero
* byte for the root.
*
* @param string $name the domain name
* @return string the encoded name, or an empty string when a
* label is empty or too long to be valid
*/
public static function encodeName($name)
{
$name = trim((string) $name, '.');
if ($name === '') {
return "\x00";
}
$encoded = '';
foreach (explode('.', $name) as $label) {
$length = strlen($label);
if ($length === 0 || $length > self::MAX_LABEL_LENGTH) {
return '';
}
$encoded .= chr($length) . $label;
}
return $encoded . "\x00";
}
/**
* Reads a domain name starting at a given offset in a message,
* following compression pointers, and advances the offset past the
* name as it appeared here (not past any pointer target). Names
* are returned lowercased and dot-joined.
*
* @param string $data the whole message bytes
* @param int &$offset position to start at; updated to just after
* the name in place
* @return string the decoded name, possibly empty for the root
*/
public static function readName($data, &$offset)
{
$labels = [];
$jumped = false;
$after_pointer = 0;
$hops = 0;
$length = strlen($data);
while ($hops < self::MAX_NAME_HOPS) {
$hops++;
if ($offset < 0 || $offset >= $length) {
break;
}
$marker = ord($data[$offset]);
if (($marker & self::COMPRESSION_MASK) ===
self::COMPRESSION_MASK) {
if ($offset + 1 >= $length) {
break;
}
$pointer = (($marker & self::COMPRESSION_OFFSET_HIGH)
<< 8) | ord($data[$offset + 1]);
if (!$jumped) {
$after_pointer = $offset + 2;
$jumped = true;
}
$offset = $pointer;
continue;
}
if ($marker === 0) {
$offset++;
break;
}
$labels[] = strtolower(substr($data, $offset + 1, $marker));
$offset += 1 + $marker;
}
if ($jumped) {
$offset = $after_pointer;
}
return implode('.', $labels);
}
/**
* Parses a reply, returning the records in the answer section that
* match the type asked for, in the dns_get_record array shape. A
* reply whose id does not match the query, whose response code
* reports an error, or that was truncated yields an empty list, so
* a bad or partial answer reads as no records.
*
* @param string $data the reply bytes
* @param int $expected_id the id of the query this answers
* @param int $type one of the TYPE_ constants asked for
* @return array the matching records, each an associative array
*/
public static function parseResponse($data, $expected_id, $type)
{
if (strlen($data) < self::HEADER_LENGTH) {
return [];
}
$header = unpack('nid/nflags/nqd/nan/nns/nar',
substr($data, 0, self::HEADER_LENGTH));
if ($header['id'] !== $expected_id) {
return [];
}
if (($header['flags'] & self::FLAG_TRUNCATED) !== 0) {
return [];
}
if (($header['flags'] & self::RCODE_MASK) !== 0) {
return [];
}
$offset = self::HEADER_LENGTH;
for ($i = 0; $i < $header['qd']; $i++) {
self::readName($data, $offset);
$offset += 4;
}
$records = [];
for ($i = 0; $i < $header['an']; $i++) {
$record = self::readAnswer($data, $offset, $type);
if ($record !== null) {
$records[] = $record;
}
}
return $records;
}
/**
* Reads one answer record at the offset and advances the offset
* past it. Returns the record as an associative array when it is
* of the wanted type, or null when it is some other type (still
* advancing past it).
*
* @param string $data the whole reply bytes
* @param int &$offset position of the record; updated past it
* @param int $type the TYPE_ constant the caller wants
* @return array|null the record, or null to skip it
*/
private static function readAnswer($data, &$offset, $type)
{
self::readName($data, $offset);
if ($offset + 10 > strlen($data)) {
$offset = strlen($data);
return null;
}
$meta = unpack('ntype/nclass/Nttl/nlength',
substr($data, $offset, 10));
$offset += 10;
$rdata_start = $offset;
$offset += $meta['length'];
if ($meta['type'] !== $type) {
return null;
}
$ttl = $meta['ttl'];
if ($type === self::TYPE_TXT) {
return ['type' => 'TXT', 'ttl' => $ttl,
'txt' => self::readText($data, $rdata_start,
$meta['length'])];
}
if ($type === self::TYPE_A) {
$address = @inet_ntop(substr($data, $rdata_start, 4));
if ($address === false) {
return null;
}
return ['type' => 'A', 'ttl' => $ttl, 'ip' => $address];
}
if ($type === self::TYPE_AAAA) {
$address = @inet_ntop(substr($data, $rdata_start, 16));
if ($address === false) {
return null;
}
return ['type' => 'AAAA', 'ttl' => $ttl,
'ipv6' => $address];
}
if ($type === self::TYPE_MX) {
$priority = unpack('n',
substr($data, $rdata_start, 2))[1];
$target_offset = $rdata_start + 2;
$target = self::readName($data, $target_offset);
return ['type' => 'MX', 'ttl' => $ttl, 'pri' => $priority,
'target' => $target];
}
return null;
}
/**
* Reads a text record's data, which is one or more runs each of a
* length byte then that many bytes, and joins the runs into one
* string (a long key is often split into several runs).
*
* @param string $data the whole reply bytes
* @param int $start where this record's data begins
* @param int $length how many bytes the record's data spans
* @return string the joined text
*/
private static function readText($data, $start, $length)
{
$text = '';
$position = $start;
$end = $start + $length;
while ($position < $end) {
$run = ord($data[$position]);
$position++;
if ($run > 0) {
$text .= substr($data, $position, $run);
$position += $run;
}
}
return $text;
}
/**
* Sends the query to one name server and waits, cooperatively when
* inside the event loop, for its reply up to the shared deadline.
* Returns the parsed records (possibly an empty list for a valid
* "no records" answer) or null when this server did not answer in
* time, which tells the caller to try the next server.
*
* @param string $server the name server address
* @param string $packet the query bytes to send
* @param int $id the query id to match the reply against
* @param int $type the TYPE_ constant asked for
* @param float $deadline microtime after which to give up
* @return array|null the records, or null on no timely answer
*/
private static function queryServer($server, $packet, $id, $type,
$deadline)
{
$errno = 0;
$errstr = '';
$socket = @stream_socket_client('udp://' . $server . ':' .
self::DNS_PORT, $errno, $errstr, 0,
STREAM_CLIENT_CONNECT);
if (!$socket) {
return null;
}
stream_set_blocking($socket, false);
@fwrite($socket, $packet);
if (!self::awaitReadable($socket, $deadline)) {
@fclose($socket);
return null;
}
$reply = @fread($socket, self::UDP_BUFFER);
@fclose($socket);
if ($reply === false || $reply === '') {
return null;
}
return self::parseResponse($reply, $id, $type);
}
/**
* Waits until a socket has data to read or the deadline passes.
* Inside the event loop (a fiber) it peeks without blocking and,
* finding nothing yet, yields the loop a turn before trying again,
* so waiting on the network never freezes other connections.
* Outside a fiber it blocks on the socket up to the remaining
* time. Returns whether the socket became readable.
*
* @param resource $socket the open, non-blocking socket
* @param float $deadline microtime after which to give up
* @return bool true if the socket is readable, false on timeout
*/
private static function awaitReadable($socket, $deadline)
{
$in_fiber = (\Fiber::getCurrent() !== null);
while (true) {
$remaining = $deadline - microtime(true);
if ($remaining <= 0) {
return false;
}
$reads = [$socket];
$writes = [];
$excepts = [];
if ($in_fiber) {
$ready = @stream_select($reads, $writes, $excepts, 0,
0);
if ($ready === false) {
return false;
}
if ($ready > 0) {
return true;
}
\Fiber::suspend();
continue;
}
$seconds = (int) floor($remaining);
$micro = (int) (($remaining - $seconds) *
self::MICROSECONDS_PER_SECOND);
$ready = @stream_select($reads, $writes, $excepts,
$seconds, $micro);
if ($ready === false || $ready === 0) {
return false;
}
return true;
}
}
/**
* Builds the EDNS0 additional record that advertises the larger
* answer size we can accept. It is an OPT pseudo-record on the
* root name with the buffer size in the class field and an empty
* data section.
*
* @return string the encoded option record bytes
*/
private static function ednsOption()
{
/* root name, OPT type, our buffer size in place of a class,
a zero extended-rcode-and-flags word, and no option data */
return "\x00" . pack('n2', self::TYPE_OPT, self::UDP_BUFFER) .
pack('N', 0) . pack('n', 0);
}
/**
* Returns the name server addresses to ask, read once from the
* system resolver configuration (/etc/resolv.conf) so the mail
* server uses the same servers the rest of the machine does. When
* that file names none, the configured fallback server is used.
*
* @return array the name server addresses in order of preference
*/
private static function nameservers()
{
if (self::$servers !== null) {
return self::$servers;
}
$servers = [];
$path = '/etc/resolv.conf';
if (is_readable($path)) {
$lines = @file($path, FILE_IGNORE_NEW_LINES |
FILE_SKIP_EMPTY_LINES);
if (is_array($lines)) {
foreach ($lines as $line) {
$line = trim($line);
if (stripos($line, 'nameserver ') === 0) {
$address = trim(substr($line, strlen(
'nameserver ')));
if ($address !== '') {
$servers[] = $address;
}
}
}
}
}
if (empty($servers)) {
$servers[] = C\MAIL_DNS_FALLBACK_SERVER;
}
self::$servers = $servers;
return $servers;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software