Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <chrono>
       4             : #include <functional>
       5             : #include <list>
       6             : #include <memory>
       7             : #include <string>
       8             : 
       9             : #include "envoy/common/pure.h"
      10             : #include "envoy/network/address.h"
      11             : 
      12             : #include "absl/types/variant.h"
      13             : 
      14             : namespace Envoy {
      15             : namespace Network {
      16             : 
      17             : /**
      18             :  * An active async DNS query.
      19             :  */
      20             : class ActiveDnsQuery {
      21             : public:
      22           1 :   virtual ~ActiveDnsQuery() = default;
      23             : 
      24             :   enum class CancelReason {
      25             :     // The caller no longer needs the answer to the query.
      26             :     QueryAbandoned,
      27             :     // The query timed out from the perspective of the caller. The DNS implementation may take
      28             :     // a different action in this case (e.g., destroying existing DNS connections) in an effort
      29             :     // to get an answer to future queries.
      30             :     Timeout
      31             :   };
      32             : 
      33             :   /**
      34             :    * Cancel an outstanding DNS request.
      35             :    * @param reason supplies the cancel reason.
      36             :    */
      37             :   virtual void cancel(CancelReason reason) PURE;
      38             : };
      39             : 
      40             : /**
      41             :  * DNS A/AAAA record response.
      42             :  */
      43             : struct AddrInfoResponse {
      44             :   const Address::InstanceConstSharedPtr address_;
      45             :   const std::chrono::seconds ttl_;
      46             : };
      47             : 
      48             : /**
      49             :  * DNS SRV record response.
      50             :  */
      51             : struct SrvResponse {
      52             :   const std::string host_;
      53             :   const uint16_t port_;
      54             :   const uint16_t priority_;
      55             :   const uint16_t weight_;
      56             : };
      57             : 
      58             : enum class RecordType { A, AAAA, SRV };
      59             : 
      60             : enum class DnsLookupFamily { V4Only, V6Only, Auto, V4Preferred, All };
      61             : 
      62             : class DnsResponse {
      63             : public:
      64             :   DnsResponse(const Address::InstanceConstSharedPtr& address, const std::chrono::seconds ttl)
      65             :       : response_(AddrInfoResponse{
      66             :             address,
      67             :             std::chrono::seconds(std::min(std::chrono::seconds::rep(INT_MAX),
      68           0 :                                           std::max(ttl.count(), std::chrono::seconds::rep(0))))}) {}
      69             :   DnsResponse(const std::string& host, uint16_t port, uint16_t priority, uint16_t weight)
      70           0 :       : response_(SrvResponse{host, port, priority, weight}) {}
      71             : 
      72           0 :   const AddrInfoResponse& addrInfo() const { return absl::get<AddrInfoResponse>(response_); }
      73             : 
      74           0 :   const SrvResponse& srv() const { return absl::get<SrvResponse>(response_); }
      75             : 
      76             : private:
      77             :   absl::variant<AddrInfoResponse, SrvResponse> response_;
      78             : };
      79             : 
      80             : /**
      81             :  * An asynchronous DNS resolver.
      82             :  */
      83             : class DnsResolver {
      84             : public:
      85           1 :   virtual ~DnsResolver() = default;
      86             : 
      87             :   /**
      88             :    * Final status for a DNS resolution.
      89             :    */
      90             :   enum class ResolutionStatus { Success, Failure };
      91             : 
      92             :   /**
      93             :    * Called when a resolution attempt is complete.
      94             :    * @param status supplies the final status of the resolution.
      95             :    * @param response supplies the list of resolved IP addresses and TTLs.
      96             :    */
      97             :   using ResolveCb = std::function<void(ResolutionStatus status, std::list<DnsResponse>&& response)>;
      98             : 
      99             :   /**
     100             :    * Initiate an async DNS resolution.
     101             :    * @param dns_name supplies the DNS name to lookup.
     102             :    * @param dns_lookup_family the DNS IP version lookup policy.
     103             :    * @param callback supplies the callback to invoke when the resolution is complete.
     104             :    * @return if non-null, a handle that can be used to cancel the resolution.
     105             :    *         This is only valid until the invocation of callback or ~DnsResolver().
     106             :    */
     107             :   virtual ActiveDnsQuery* resolve(const std::string& dns_name, DnsLookupFamily dns_lookup_family,
     108             :                                   ResolveCb callback) PURE;
     109             : 
     110             :   /**
     111             :    * Tell the resolver to reset networking, typically in response to a network switch (e.g., from
     112             :    * WiFi to cellular). What the resolver does is resolver dependent but might involve creating
     113             :    * new resolver connections, re-reading resolver targets, etc.
     114             :    */
     115             :   virtual void resetNetworking() PURE;
     116             : };
     117             : 
     118             : using DnsResolverSharedPtr = std::shared_ptr<DnsResolver>;
     119             : 
     120             : } // namespace Network
     121             : } // namespace Envoy