Skip to content

Commit bed3a9f

Browse files
clueclue
committed
Improve error messages for failed queries and improve documentation
1 parent d822cc5 commit bed3a9f

6 files changed

Lines changed: 176 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ easily be used to create a DNS server.
1313
* [Basic usage](#basic-usage)
1414
* [Caching](#caching)
1515
* [Custom cache adapter](#custom-cache-adapter)
16+
* [Resolver](#resolver)
17+
* [resolve()](#resolve)
1618
* [Advanced usage](#advanced-usage)
1719
* [UdpTransportExecutor](#udptransportexecutor)
1820
* [HostsFileExecutor](#hostsfileexecutor)
@@ -58,14 +60,6 @@ as above if none can be found.
5860
Ideally, this method should thus be executed only once before the loop starts
5961
and not repeatedly while it is running.
6062

61-
Pending DNS queries can be cancelled by cancelling its pending promise like so:
62-
63-
```php
64-
$promise = $resolver->resolve('reactphp.org');
65-
66-
$promise->cancel();
67-
```
68-
6963
But there's more.
7064

7165
## Caching
@@ -116,6 +110,42 @@ $dns = $factory->createCached('8.8.8.8', $loop, $cache);
116110

117111
See also the wiki for possible [cache implementations](https://github.com/reactphp/react/wiki/Users#cache-implementations).
118112

113+
## Resolver
114+
115+
### resolve()
116+
117+
The `resolve(string $domain): PromiseInterface<string,Exception>` method can be used to
118+
resolve the given $domain name to a single IPv4 address (type `A` query).
119+
120+
```php
121+
$resolver->resolve('reactphp.org')->then(function ($ip) {
122+
echo 'IP for reactphp.org is ' . $ip . PHP_EOL;
123+
});
124+
```
125+
126+
This is one of the main methods in this package. It sends a DNS query
127+
for the given $domain name to your DNS server and returns a single IP
128+
address on success.
129+
130+
If the DNS server sends a DNS response message that contains more than
131+
one IP address for this query, it will randomly pick one of the IP
132+
addresses from the response.
133+
134+
If the DNS server sends a DNS response message that indicated an error
135+
code, this method will reject with a `RecordNotFoundException`. Its
136+
message and code can be used to check for the response code.
137+
138+
If the DNS communication fails and the server does not respond with a
139+
valid response message, this message will reject with an `Exception`.
140+
141+
Pending DNS queries can be cancelled by cancelling its pending promise like so:
142+
143+
```php
144+
$promise = $resolver->resolve('reactphp.org');
145+
146+
$promise->cancel();
147+
```
148+
119149
## Advanced Usage
120150

121151
### UdpTransportExecutor

‎src/Model/Message.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,16 @@ public function getId()
137137
return $this->header->get('id');
138138
}
139139

140+
/**
141+
* Returns the response code (RCODE)
142+
*
143+
* @return int see self::RCODE_* constants
144+
*/
145+
public function getResponseCode()
146+
{
147+
return $this->header->get('rcode');
148+
}
149+
140150
public function prepare()
141151
{
142152
$this->header->populateCounts($this);

‎src/Resolver/Resolver.php‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
use React\Dns\Query\Query;
77
use React\Dns\RecordNotFoundException;
88
use React\Dns\Model\Message;
9+
use React\Promise\PromiseInterface;
910

1011
class Resolver
1112
{
@@ -18,6 +19,42 @@ public function __construct($nameserver, ExecutorInterface $executor)
1819
$this->executor = $executor;
1920
}
2021

22+
/**
23+
* Resolves the given $domain name to a single IPv4 address (type `A` query).
24+
*
25+
* ```php
26+
* $resolver->resolve('reactphp.org')->then(function ($ip) {
27+
* echo 'IP for reactphp.org is ' . $ip . PHP_EOL;
28+
* });
29+
* ```
30+
*
31+
* This is one of the main methods in this package. It sends a DNS query
32+
* for the given $domain name to your DNS server and returns a single IP
33+
* address on success.
34+
*
35+
* If the DNS server sends a DNS response message that contains more than
36+
* one IP address for this query, it will randomly pick one of the IP
37+
* addresses from the response.
38+
*
39+
* If the DNS server sends a DNS response message that indicated an error
40+
* code, this method will reject with a `RecordNotFoundException`. Its
41+
* message and code can be used to check for the response code.
42+
*
43+
* If the DNS communication fails and the server does not respond with a
44+
* valid response message, this message will reject with an `Exception`.
45+
*
46+
* Pending DNS queries can be cancelled by cancelling its pending promise like so:
47+
*
48+
* ```php
49+
* $promise = $resolver->resolve('reactphp.org');
50+
*
51+
* $promise->cancel();
52+
* ```
53+
*
54+
* @param string $domain
55+
* @return PromiseInterface Returns a promise which resolves with a single IP address on success or
56+
* rejects with an Exception on error.
57+
*/
2158
public function resolve($domain)
2259
{
2360
$query = new Query($domain, Message::TYPE_A, Message::CLASS_IN);
@@ -32,13 +69,42 @@ public function resolve($domain)
3269

3370
public function extractAddress(Query $query, Message $response)
3471
{
35-
$answers = $response->answers;
72+
// reject if response code indicates this is an error response message
73+
$code = $response->getResponseCode();
74+
if ($code !== Message::RCODE_OK) {
75+
switch ($code) {
76+
case Message::RCODE_FORMAT_ERROR:
77+
$message = 'Format Error';
78+
break;
79+
case Message::RCODE_SERVER_FAILURE:
80+
$message = 'Server Failure';
81+
break;
82+
case Message::RCODE_NAME_ERROR:
83+
$message = 'Non-Existent Domain / NXDOMAIN';
84+
break;
85+
case Message::RCODE_NOT_IMPLEMENTED:
86+
$message = 'Not Implemented';
87+
break;
88+
case Message::RCODE_REFUSED:
89+
$message = 'Refused';
90+
break;
91+
default:
92+
$message = 'Unknown error response code ' . $code;
93+
}
94+
throw new RecordNotFoundException(
95+
'DNS query for ' . $query->name . ' returned an error response (' . $message . ')',
96+
$code
97+
);
98+
}
3699

100+
$answers = $response->answers;
37101
$addresses = $this->resolveAliases($answers, $query->name);
38102

103+
// reject if we did not receive a valid answer (domain is valid, but no record for this type could be found)
39104
if (0 === count($addresses)) {
40-
$message = 'DNS Request did not return valid answer.';
41-
throw new RecordNotFoundException($message);
105+
throw new RecordNotFoundException(
106+
'DNS query for ' . $query->name . ' did not return a valid answer (NOERROR / NODATA)'
107+
);
42108
}
43109

44110
$address = $addresses[array_rand($addresses)];

‎tests/FunctionalResolverTest.php‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
namespace React\Tests\Dns;
44

5-
use React\Tests\Dns\TestCase;
65
use React\EventLoop\Factory as LoopFactory;
7-
use React\Dns\Resolver\Resolver;
86
use React\Dns\Resolver\Factory;
7+
use React\Dns\RecordNotFoundException;
8+
use React\Dns\Model\Message;
99

1010
class FunctionalTest extends TestCase
1111
{
@@ -41,16 +41,24 @@ public function testResolveGoogleResolves()
4141
*/
4242
public function testResolveInvalidRejects()
4343
{
44+
$ex = $this->callback(function ($param) {
45+
return ($param instanceof RecordNotFoundException && $param->getCode() === Message::RCODE_NAME_ERROR);
46+
});
47+
4448
$promise = $this->resolver->resolve('example.invalid');
45-
$promise->then($this->expectCallableNever(), $this->expectCallableOnce());
49+
$promise->then($this->expectCallableNever(), $this->expectCallableOnceWith($ex));
4650

4751
$this->loop->run();
4852
}
4953

5054
public function testResolveCancelledRejectsImmediately()
5155
{
56+
$ex = $this->callback(function ($param) {
57+
return ($param instanceof \RuntimeException && $param->getMessage() === 'DNS query for google.com has been cancelled');
58+
});
59+
5260
$promise = $this->resolver->resolve('google.com');
53-
$promise->then($this->expectCallableNever(), $this->expectCallableOnce());
61+
$promise->then($this->expectCallableNever(), $this->expectCallableOnceWith($ex));
5462
$promise->cancel();
5563

5664
$time = microtime(true);

‎tests/Model/MessageTest.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,5 +26,6 @@ public function testCreateResponseWithNoAnswers()
2626
$this->assertFalse($request->header->isQuery());
2727
$this->assertTrue($request->header->isResponse());
2828
$this->assertEquals(0, $request->header->get('anCount'));
29+
$this->assertEquals(Message::RCODE_OK, $request->getResponseCode());
2930
}
3031
}

‎tests/Resolver/ResolverTest.php‎

Lines changed: 46 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
use React\Dns\Model\Record;
99
use React\Promise;
1010
use React\Tests\Dns\TestCase;
11+
use React\Dns\RecordNotFoundException;
1112

1213
class ResolverTest extends TestCase
1314
{
@@ -76,8 +77,10 @@ public function resolveShouldFilterByName()
7677
$resolver->resolve('igor.io')->then($this->expectCallableNever(), $errback);
7778
}
7879

79-
/** @test */
80-
public function resolveWithNoAnswersShouldThrowException()
80+
/**
81+
* @test
82+
*/
83+
public function resolveWithNoAnswersShouldCallErrbackIfGiven()
8184
{
8285
$executor = $this->createExecutorMock();
8386
$executor
@@ -92,34 +95,70 @@ public function resolveWithNoAnswersShouldThrowException()
9295
return Promise\resolve($response);
9396
}));
9497

95-
$errback = $this->expectCallableOnceWith($this->isInstanceOf('React\Dns\RecordNotFoundException'));
98+
$errback = $this->expectCallableOnceWith($this->callback(function ($param) {
99+
return ($param instanceof RecordNotFoundException && $param->getCode() === 0 && $param->getMessage() === 'DNS query for igor.io did not return a valid answer (NOERROR / NODATA)');
100+
}));
96101

97102
$resolver = new Resolver('8.8.8.8:53', $executor);
98103
$resolver->resolve('igor.io')->then($this->expectCallableNever(), $errback);
99104
}
100105

106+
public function provideRcodeErrors()
107+
{
108+
return array(
109+
array(
110+
Message::RCODE_FORMAT_ERROR,
111+
'DNS query for example.com returned an error response (Format Error)',
112+
),
113+
array(
114+
Message::RCODE_SERVER_FAILURE,
115+
'DNS query for example.com returned an error response (Server Failure)',
116+
),
117+
array(
118+
Message::RCODE_NAME_ERROR,
119+
'DNS query for example.com returned an error response (Non-Existent Domain / NXDOMAIN)'
120+
),
121+
array(
122+
Message::RCODE_NOT_IMPLEMENTED,
123+
'DNS query for example.com returned an error response (Not Implemented)'
124+
),
125+
array(
126+
Message::RCODE_REFUSED,
127+
'DNS query for example.com returned an error response (Refused)'
128+
),
129+
array(
130+
99,
131+
'DNS query for example.com returned an error response (Unknown error response code 99)'
132+
)
133+
);
134+
}
135+
101136
/**
102137
* @test
138+
* @dataProvider provideRcodeErrors
103139
*/
104-
public function resolveWithNoAnswersShouldCallErrbackIfGiven()
140+
public function resolveWithRcodeErrorShouldCallErrbackIfGiven($code, $expectedMessage)
105141
{
106142
$executor = $this->createExecutorMock();
107143
$executor
108144
->expects($this->once())
109145
->method('query')
110146
->with($this->anything(), $this->isInstanceOf('React\Dns\Query\Query'))
111-
->will($this->returnCallback(function ($nameserver, $query) {
147+
->will($this->returnCallback(function ($nameserver, $query) use ($code) {
112148
$response = new Message();
113149
$response->header->set('qr', 1);
150+
$response->header->set('rcode', $code);
114151
$response->questions[] = new Record($query->name, $query->type, $query->class);
115152

116153
return Promise\resolve($response);
117154
}));
118155

119-
$errback = $this->expectCallableOnceWith($this->isInstanceOf('React\Dns\RecordNotFoundException'));
156+
$errback = $this->expectCallableOnceWith($this->callback(function ($param) use ($code, $expectedMessage) {
157+
return ($param instanceof RecordNotFoundException && $param->getCode() === $code && $param->getMessage() === $expectedMessage);
158+
}));
120159

121160
$resolver = new Resolver('8.8.8.8:53', $executor);
122-
$resolver->resolve('igor.io')->then($this->expectCallableNever(), $errback);
161+
$resolver->resolve('example.com')->then($this->expectCallableNever(), $errback);
123162
}
124163

125164
private function createExecutorMock()

0 commit comments

Comments
 (0)