io.netty.resolver.dns.DnsQueryLifecycleObserver Maven / Gradle / Ivy
/*
* Copyright 2017 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
package io.netty.resolver.dns;
import io.netty.channel.ChannelFuture;
import io.netty.handler.codec.dns.DnsQuestion;
import io.netty.handler.codec.dns.DnsRecordType;
import io.netty.handler.codec.dns.DnsResponseCode;
import io.netty.util.internal.UnstableApi;
import java.net.InetSocketAddress;
import java.util.List;
/**
* This interface provides visibility into individual DNS queries. The lifecycle of an objects is as follows:
*
* - Object creation
* - {@link #queryCancelled(int)}
*
* OR
*
* - Object creation
* - {@link #queryWritten(InetSocketAddress, ChannelFuture)}
* - {@link #queryRedirected(List)} or {@link #queryCNAMEd(DnsQuestion)} or
* {@link #queryNoAnswer(DnsResponseCode)} or {@link #queryCancelled(int)} or
* {@link #queryFailed(Throwable)} or {@link #querySucceed()}
*
*
* This interface can be used to track metrics for individual DNS servers. Methods which may lead to another DNS query
* return an object of type {@link DnsQueryLifecycleObserver}. Implementations may use this to build a query tree to
* understand the "sub queries" generated by a single query.
*/
@UnstableApi
public interface DnsQueryLifecycleObserver {
/**
* The query has been written.
* @param dnsServerAddress The DNS server address which the query was sent to.
* @param future The future which represents the status of the write operation for the DNS query.
*/
void queryWritten(InetSocketAddress dnsServerAddress, ChannelFuture future);
/**
* The query may have been written but it was cancelled at some point.
* @param queriesRemaining The number of queries remaining.
*/
void queryCancelled(int queriesRemaining);
/**
* The query has been redirected to another list of DNS servers.
* @param nameServers The name servers the query has been redirected to.
* @return An observer for the new query which we may issue.
*/
DnsQueryLifecycleObserver queryRedirected(List nameServers);
/**
* The query returned a CNAME which we may attempt to follow with a new query.
*
* Note that multiple queries may be encountering a CNAME. For example a if both {@link DnsRecordType#AAAA} and
* {@link DnsRecordType#A} are supported we may query for both.
* @param cnameQuestion the question we would use if we issue a new query.
* @return An observer for the new query which we may issue.
*/
DnsQueryLifecycleObserver queryCNAMEd(DnsQuestion cnameQuestion);
/**
* The response to the query didn't provide the expected response code, but it didn't return
* {@link DnsResponseCode#NXDOMAIN} so we may try to query again.
* @param code the unexpected response code.
* @return An observer for the new query which we may issue.
*/
DnsQueryLifecycleObserver queryNoAnswer(DnsResponseCode code);
/**
* The following criteria are possible:
*
* - IO Error
* - Server responded with an invalid DNS response
* - Server responded with a valid DNS response, but it didn't progress the resolution
*
* @param cause The cause which for the failure.
*/
void queryFailed(Throwable cause);
/**
* The query received the expected results.
*/
void querySucceed();
}