1 // 2 // 3 // Copyright 2016 gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 // 17 // 18 19 #ifndef GRPC_SRC_CORE_RESOLVER_DNS_C_ARES_GRPC_ARES_WRAPPER_H 20 #define GRPC_SRC_CORE_RESOLVER_DNS_C_ARES_GRPC_ARES_WRAPPER_H 21 22 #include <ares.h> 23 #include <grpc/support/port_platform.h> 24 #include <stddef.h> 25 26 #include <memory> 27 28 #include "absl/base/thread_annotations.h" 29 #include "absl/log/log.h" 30 #include "src/core/lib/debug/trace.h" 31 #include "src/core/lib/iomgr/closure.h" 32 #include "src/core/lib/iomgr/error.h" 33 #include "src/core/lib/iomgr/iomgr_fwd.h" 34 #include "src/core/resolver/endpoint_addresses.h" 35 #include "src/core/util/sync.h" 36 37 #define GRPC_DNS_ARES_DEFAULT_QUERY_TIMEOUT_MS 120000 38 39 typedef struct grpc_ares_ev_driver grpc_ares_ev_driver; 40 41 struct grpc_ares_request { 42 /// synchronizes access to this request, and also to associated 43 /// ev_driver and fd_node objects 44 grpc_core::Mutex mu; 45 /// indicates the DNS server to use, if specified 46 struct ares_addr_port_node dns_server_addr ABSL_GUARDED_BY(mu); 47 /// following members are set in grpc_resolve_address_ares_impl 48 /// closure to call when the request completes 49 grpc_closure* on_done ABSL_GUARDED_BY(mu) = nullptr; 50 /// the pointer to receive the resolved addresses 51 std::unique_ptr<grpc_core::EndpointAddressesList>* addresses_out 52 ABSL_GUARDED_BY(mu); 53 /// the pointer to receive the resolved balancer addresses 54 std::unique_ptr<grpc_core::EndpointAddressesList>* balancer_addresses_out 55 ABSL_GUARDED_BY(mu); 56 /// the pointer to receive the service config in JSON 57 char** service_config_json_out ABSL_GUARDED_BY(mu) = nullptr; 58 /// the event driver used by this request 59 grpc_ares_ev_driver* ev_driver ABSL_GUARDED_BY(mu) = nullptr; 60 /// number of ongoing queries 61 size_t pending_queries ABSL_GUARDED_BY(mu) = 0; 62 /// the errors explaining query failures, appended to in query callbacks 63 grpc_error_handle error ABSL_GUARDED_BY(mu); 64 }; 65 66 // Asynchronously resolve \a name (A/AAAA records only). 67 // It uses \a default_port if a port isn't designated in \a name, otherwise it 68 // uses the port in \a name. grpc_ares_init() must be called at least once 69 // before this function. The returned grpc_ares_request object is owned by the 70 // caller and it is safe to free after on_done is called back. 71 72 // Note on synchronization: \a as on_done might be called from another thread 73 //~immediately, access to the grpc_ares_request* return value must be 74 // synchronized by the caller. TODO(apolcyn): we should remove this requirement 75 // by changing this API to use two phase initialization - one API to create 76 // the grpc_ares_request* and another to start the async work. 77 extern grpc_ares_request* (*grpc_dns_lookup_hostname_ares)( 78 const char* dns_server, const char* name, const char* default_port, 79 grpc_pollset_set* interested_parties, grpc_closure* on_done, 80 std::unique_ptr<grpc_core::EndpointAddressesList>* addresses, 81 int query_timeout_ms); 82 83 // Asynchronously resolve a SRV record. 84 // See \a grpc_dns_lookup_hostname_ares for usage details and caveats. 85 extern grpc_ares_request* (*grpc_dns_lookup_srv_ares)( 86 const char* dns_server, const char* name, 87 grpc_pollset_set* interested_parties, grpc_closure* on_done, 88 std::unique_ptr<grpc_core::EndpointAddressesList>* balancer_addresses, 89 int query_timeout_ms); 90 91 // Asynchronously resolve a TXT record. 92 // See \a grpc_dns_lookup_hostname_ares for usage details and caveats. 93 extern grpc_ares_request* (*grpc_dns_lookup_txt_ares)( 94 const char* dns_server, const char* name, 95 grpc_pollset_set* interested_parties, grpc_closure* on_done, 96 char** service_config_json, int query_timeout_ms); 97 98 // Cancel the pending grpc_ares_request \a request 99 extern void (*grpc_cancel_ares_request)(grpc_ares_request* request); 100 101 // Initialize gRPC ares wrapper. Must be called at least once before 102 // grpc_resolve_address_ares(). 103 grpc_error_handle grpc_ares_init(void); 104 105 // Uninitialized gRPC ares wrapper. If there was more than one previous call to 106 // grpc_ares_init(), this function uninitializes the gRPC ares wrapper only if 107 // it has been called the same number of times as grpc_ares_init(). 108 void grpc_ares_cleanup(void); 109 110 // Indicates whether or not AAAA queries should be attempted. 111 // E.g., return false if ipv6 is known to not be available. 112 bool grpc_ares_query_ipv6(); 113 114 // Sorts destinations in lb_addrs according to RFC 6724. 115 void grpc_cares_wrapper_address_sorting_sort( 116 const grpc_ares_request* request, 117 grpc_core::EndpointAddressesList* addresses); 118 119 // Exposed in this header for C-core tests only 120 extern void (*grpc_ares_test_only_inject_config)(ares_channel* channel); 121 122 // Exposed in this header for C-core tests only 123 extern bool g_grpc_ares_test_only_force_tcp; 124 125 #endif // GRPC_SRC_CORE_RESOLVER_DNS_C_ARES_GRPC_ARES_WRAPPER_H 126