1 /*
2 * Copyright 2017 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.resolver.dns;
17
18 import io.netty5.handler.codec.dns.DnsQuestion;
19 import io.netty5.handler.codec.dns.DnsRecordType;
20 import io.netty5.handler.codec.dns.DnsResponseCode;
21 import io.netty5.util.concurrent.Future;
22
23 import java.net.InetSocketAddress;
24 import java.util.List;
25
26 /**
27 * This interface provides visibility into individual DNS queries. The lifecycle of an objects is as follows:
28 * <ol>
29 * <li>Object creation</li>
30 * <li>{@link #queryCancelled(int)}</li>
31 * </ol>
32 * OR
33 * <ol>
34 * <li>Object creation</li>
35 * <li>{@link #queryWritten(InetSocketAddress, Future)}</li>
36 * <li>{@link #queryRedirected(List)} or {@link #queryCNAMEd(DnsQuestion)} or
37 * {@link #queryNoAnswer(DnsResponseCode)} or {@link #queryCancelled(int)} or
38 * {@link #queryFailed(Throwable)} or {@link #querySucceed()}</li>
39 * </ol>
40 * <p>
41 * This interface can be used to track metrics for individual DNS servers. Methods which may lead to another DNS query
42 * return an object of type {@link DnsQueryLifecycleObserver}. Implementations may use this to build a query tree to
43 * understand the "sub queries" generated by a single query.
44 */
45 public interface DnsQueryLifecycleObserver {
46 /**
47 * The query has been written.
48 * @param dnsServerAddress The DNS server address which the query was sent to.
49 * @param future The future which represents the status of the write operation for the DNS query.
50 */
51 void queryWritten(InetSocketAddress dnsServerAddress, Future<Void> future);
52
53 /**
54 * The query may have been written but it was cancelled at some point.
55 * @param queriesRemaining The number of queries remaining.
56 */
57 void queryCancelled(int queriesRemaining);
58
59 /**
60 * The query has been redirected to another list of DNS servers.
61 * @param nameServers The name servers the query has been redirected to.
62 * @return An observer for the new query which we may issue.
63 */
64 DnsQueryLifecycleObserver queryRedirected(List<InetSocketAddress> nameServers);
65
66 /**
67 * The query returned a CNAME which we may attempt to follow with a new query.
68 * <p>
69 * Note that multiple queries may be encountering a CNAME. For example a if both {@link DnsRecordType#AAAA} and
70 * {@link DnsRecordType#A} are supported we may query for both.
71 * @param cnameQuestion the question we would use if we issue a new query.
72 * @return An observer for the new query which we may issue.
73 */
74 DnsQueryLifecycleObserver queryCNAMEd(DnsQuestion cnameQuestion);
75
76 /**
77 * The response to the query didn't provide the expected response code, but it didn't return
78 * {@link DnsResponseCode#NXDOMAIN} so we may try to query again.
79 * @param code the unexpected response code.
80 * @return An observer for the new query which we may issue.
81 */
82 DnsQueryLifecycleObserver queryNoAnswer(DnsResponseCode code);
83
84 /**
85 * The following criteria are possible:
86 * <ul>
87 * <li>IO Error</li>
88 * <li>Server responded with an invalid DNS response</li>
89 * <li>Server responded with a valid DNS response, but it didn't progress the resolution</li>
90 * </ul>
91 * @param cause The cause which for the failure.
92 */
93 void queryFailed(Throwable cause);
94
95 /**
96 * The query received the expected results.
97 */
98 void querySucceed();
99 }