Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pycares/__init__.py: 33%

1 

2from ._cares import ffi as _ffi, lib as _lib 

3import _cffi_backend # hint for bundler tools 

4 

5if _lib.ARES_SUCCESS != _lib.ares_library_init(_lib.ARES_LIB_INIT_ALL) or _ffi is None: 

6 raise RuntimeError('Could not initialize c-ares') 

7 

8if not _lib.ares_threadsafety(): 

9 raise RuntimeError("c-ares is not built with thread safety") 

10 

11from . import errno 

12from .utils import ascii_bytes, maybe_str, parse_name 

13from ._version import __version__ 

14 

15import math 

16import socket 

17import threading 

18from collections.abc import Callable, Iterable 

19from dataclasses import dataclass 

20from typing import Any, Callable, Literal, Optional, Dict, Union 

21from queue import SimpleQueue 

22 

23IP4 = tuple[str, int] 

24IP6 = tuple[str, int, int, int] 

25 

26# Flag values 

27ARES_FLAG_USEVC = _lib.ARES_FLAG_USEVC 

28ARES_FLAG_PRIMARY = _lib.ARES_FLAG_PRIMARY 

29ARES_FLAG_IGNTC = _lib.ARES_FLAG_IGNTC 

30ARES_FLAG_NORECURSE = _lib.ARES_FLAG_NORECURSE 

31ARES_FLAG_STAYOPEN = _lib.ARES_FLAG_STAYOPEN 

32ARES_FLAG_NOSEARCH = _lib.ARES_FLAG_NOSEARCH 

33ARES_FLAG_NOALIASES = _lib.ARES_FLAG_NOALIASES 

34ARES_FLAG_NOCHECKRESP = _lib.ARES_FLAG_NOCHECKRESP 

35ARES_FLAG_EDNS = _lib.ARES_FLAG_EDNS 

36ARES_FLAG_NO_DFLT_SVR = _lib.ARES_FLAG_NO_DFLT_SVR 

37 

38# Nameinfo flag values 

39ARES_NI_NOFQDN = _lib.ARES_NI_NOFQDN 

40ARES_NI_NUMERICHOST = _lib.ARES_NI_NUMERICHOST 

41ARES_NI_NAMEREQD = _lib.ARES_NI_NAMEREQD 

42ARES_NI_NUMERICSERV = _lib.ARES_NI_NUMERICSERV 

43ARES_NI_DGRAM = _lib.ARES_NI_DGRAM 

44ARES_NI_TCP = _lib.ARES_NI_TCP 

45ARES_NI_UDP = _lib.ARES_NI_UDP 

46ARES_NI_SCTP = _lib.ARES_NI_SCTP 

47ARES_NI_DCCP = _lib.ARES_NI_DCCP 

48ARES_NI_NUMERICSCOPE = _lib.ARES_NI_NUMERICSCOPE 

49ARES_NI_LOOKUPHOST = _lib.ARES_NI_LOOKUPHOST 

50ARES_NI_LOOKUPSERVICE = _lib.ARES_NI_LOOKUPSERVICE 

51ARES_NI_IDN = _lib.ARES_NI_IDN 

52ARES_NI_IDN_ALLOW_UNASSIGNED = _lib.ARES_NI_IDN_ALLOW_UNASSIGNED 

53ARES_NI_IDN_USE_STD3_ASCII_RULES = _lib.ARES_NI_IDN_USE_STD3_ASCII_RULES 

54 

55# Bad socket 

56ARES_SOCKET_BAD = _lib.ARES_SOCKET_BAD 

57 

58# Query types 

59QUERY_TYPE_A = _lib.ARES_REC_TYPE_A 

60QUERY_TYPE_AAAA = _lib.ARES_REC_TYPE_AAAA 

61QUERY_TYPE_ANY = _lib.ARES_REC_TYPE_ANY 

62QUERY_TYPE_CAA = _lib.ARES_REC_TYPE_CAA 

63QUERY_TYPE_CNAME = _lib.ARES_REC_TYPE_CNAME 

64QUERY_TYPE_MX = _lib.ARES_REC_TYPE_MX 

65QUERY_TYPE_NAPTR = _lib.ARES_REC_TYPE_NAPTR 

66QUERY_TYPE_NS = _lib.ARES_REC_TYPE_NS 

67QUERY_TYPE_PTR = _lib.ARES_REC_TYPE_PTR 

68QUERY_TYPE_SOA = _lib.ARES_REC_TYPE_SOA 

69QUERY_TYPE_SRV = _lib.ARES_REC_TYPE_SRV 

70QUERY_TYPE_TXT = _lib.ARES_REC_TYPE_TXT 

71QUERY_TYPE_TLSA = _lib.ARES_REC_TYPE_TLSA 

72QUERY_TYPE_HTTPS = _lib.ARES_REC_TYPE_HTTPS 

73QUERY_TYPE_URI = _lib.ARES_REC_TYPE_URI 

74 

75# Query classes 

76QUERY_CLASS_IN = _lib.ARES_CLASS_IN 

77QUERY_CLASS_CHAOS = _lib.ARES_CLASS_CHAOS 

78QUERY_CLASS_HS = _lib.ARES_CLASS_HESOID 

79QUERY_CLASS_NONE = _lib.ARES_CLASS_NONE 

80QUERY_CLASS_ANY = _lib.ARES_CLASS_ANY 

81 

82ARES_VERSION = maybe_str(_ffi.string(_lib.ares_version(_ffi.NULL))) 

83PYCARES_ADDRTTL_SIZE = 256 

84 

85 

86class AresError(Exception): 

87 pass 

88 

89 

90# callback helpers 

91 

92_handle_to_channel: Dict[Any, "Channel"] = {} # Maps handle to channel to prevent use-after-free 

93 

94 

95@_ffi.def_extern() 

96def _sock_state_cb(data, socket_fd, readable, writable): 

97 # Note: sock_state_cb handle is not tracked in _handle_to_channel 

98 # because it has a different lifecycle (tied to the channel, not individual queries) 

99 sock_state_cb = _ffi.from_handle(data) 

100 sock_state_cb(socket_fd, readable, writable) 

101 

102@_ffi.def_extern() 

103def _host_cb(arg, status, timeouts, hostent): 

104 # Get callback data without removing the reference yet 

105 if arg not in _handle_to_channel: 

106 return 

107 

108 callback = _ffi.from_handle(arg) 

109 

110 if status != _lib.ARES_SUCCESS: 

111 result = None 

112 else: 

113 result = parse_hostent(hostent) 

114 status = None 

115 

116 callback(result, status) 

117 _handle_to_channel.pop(arg, None) 

118 

119@_ffi.def_extern() 

120def _nameinfo_cb(arg, status, timeouts, node, service): 

121 # Get callback data without removing the reference yet 

122 if arg not in _handle_to_channel: 

123 return 

124 

125 callback = _ffi.from_handle(arg) 

126 

127 if status != _lib.ARES_SUCCESS: 

128 result = None 

129 else: 

130 result = parse_nameinfo(node, service) 

131 status = None 

132 

133 callback(result, status) 

134 _handle_to_channel.pop(arg, None) 

135 

136@_ffi.def_extern() 

137def _query_dnsrec_cb(arg, status, timeouts, dnsrec): 

138 """Callback for new DNS record API queries""" 

139 # Get callback data without removing the reference yet 

140 if arg not in _handle_to_channel: 

141 return 

142 

143 callback = _ffi.from_handle(arg) 

144 

145 if status != _lib.ARES_SUCCESS: 

146 result = None 

147 else: 

148 result, parse_status = parse_dnsrec(dnsrec) 

149 if parse_status is not None: 

150 status = parse_status 

151 else: 

152 # Success - set status to None 

153 status = None 

154 

155 callback(result, status) 

156 _handle_to_channel.pop(arg, None) 

157 

158 

159@_ffi.def_extern() 

160def _addrinfo_cb(arg, status, timeouts, res): 

161 # Get callback data without removing the reference yet 

162 if arg not in _handle_to_channel: 

163 return 

164 

165 callback = _ffi.from_handle(arg) 

166 

167 if status != _lib.ARES_SUCCESS: 

168 result = None 

169 else: 

170 result = parse_addrinfo(res) 

171 status = None 

172 

173 callback(result, status) 

174 _handle_to_channel.pop(arg, None) 

175 

176 

177def _extract_opt_params(rr, key): 

178 """Extract OPT params as list of (key, value) tuples for HTTPS/SVCB records.""" 

179 opt_cnt = _lib.ares_dns_rr_get_opt_cnt(rr, key) 

180 if opt_cnt == 0: 

181 return [] 

182 # Collect all options as a list of (key, value) tuples 

183 params = [] 

184 for i in range(opt_cnt): 

185 val_ptr = _ffi.new("unsigned char **") 

186 val_len = _ffi.new("size_t *") 

187 opt_key = _lib.ares_dns_rr_get_opt(rr, key, i, val_ptr, val_len) 

188 if val_ptr[0] != _ffi.NULL: 

189 val = bytes(_ffi.buffer(val_ptr[0], val_len[0])) 

190 else: 

191 val = b'' 

192 params.append((opt_key, val)) 

193 return params 

194 

195 

196def extract_record_data(rr, record_type): 

197 """Extract type-specific data from a DNS resource record and return appropriate dataclass""" 

198 if record_type == _lib.ARES_REC_TYPE_A: 

199 addr = _lib.ares_dns_rr_get_addr(rr, _lib.ARES_RR_A_ADDR) 

200 buf = _ffi.new("char[]", _lib.INET6_ADDRSTRLEN) 

201 _lib.ares_inet_ntop(socket.AF_INET, addr, buf, _lib.INET6_ADDRSTRLEN) 

202 return ARecordData(addr=maybe_str(_ffi.string(buf))) 

203 

204 elif record_type == _lib.ARES_REC_TYPE_AAAA: 

205 addr = _lib.ares_dns_rr_get_addr6(rr, _lib.ARES_RR_AAAA_ADDR) 

206 buf = _ffi.new("char[]", _lib.INET6_ADDRSTRLEN) 

207 _lib.ares_inet_ntop(socket.AF_INET6, addr, buf, _lib.INET6_ADDRSTRLEN) 

208 return AAAARecordData(addr=maybe_str(_ffi.string(buf))) 

209 

210 elif record_type == _lib.ARES_REC_TYPE_MX: 

211 priority = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_MX_PREFERENCE) 

212 exchange = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_MX_EXCHANGE) 

213 return MXRecordData(priority=priority, exchange=maybe_str(_ffi.string(exchange))) 

214 

215 elif record_type == _lib.ARES_REC_TYPE_TXT: 

216 # TXT records use ABIN (array of binary) for chunks 

217 cnt = _lib.ares_dns_rr_get_abin_cnt(rr, _lib.ARES_RR_TXT_DATA) 

218 chunks = [] 

219 for i in range(cnt): 

220 length = _ffi.new("size_t *") 

221 data = _lib.ares_dns_rr_get_abin(rr, _lib.ARES_RR_TXT_DATA, i, length) 

222 if data != _ffi.NULL: 

223 chunks.append(_ffi.buffer(data, length[0])[:]) 

224 return TXTRecordData(data=b''.join(chunks)) 

225 

226 elif record_type == _lib.ARES_REC_TYPE_CAA: 

227 critical = _lib.ares_dns_rr_get_u8(rr, _lib.ARES_RR_CAA_CRITICAL) 

228 tag = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_CAA_TAG) 

229 length = _ffi.new("size_t *") 

230 value = _lib.ares_dns_rr_get_bin(rr, _lib.ARES_RR_CAA_VALUE, length) 

231 value_str = maybe_str(_ffi.buffer(value, length[0])[:]) 

232 return CAARecordData(critical=critical, tag=maybe_str(_ffi.string(tag)), value=value_str) 

233 

234 elif record_type == _lib.ARES_REC_TYPE_CNAME: 

235 cname = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_CNAME_CNAME) 

236 return CNAMERecordData(cname=maybe_str(_ffi.string(cname))) 

237 

238 elif record_type == _lib.ARES_REC_TYPE_NAPTR: 

239 order = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_NAPTR_ORDER) 

240 preference = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_NAPTR_PREFERENCE) 

241 flags = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_NAPTR_FLAGS) 

242 service = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_NAPTR_SERVICES) 

243 regexp = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_NAPTR_REGEXP) 

244 replacement = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_NAPTR_REPLACEMENT) 

245 return NAPTRRecordData( 

246 order=order, 

247 preference=preference, 

248 flags=maybe_str(_ffi.string(flags)), 

249 service=maybe_str(_ffi.string(service)), 

250 regexp=maybe_str(_ffi.string(regexp)), 

251 replacement=maybe_str(_ffi.string(replacement)) 

252 ) 

253 

254 elif record_type == _lib.ARES_REC_TYPE_NS: 

255 nsdname = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_NS_NSDNAME) 

256 return NSRecordData(nsdname=maybe_str(_ffi.string(nsdname))) 

257 

258 elif record_type == _lib.ARES_REC_TYPE_PTR: 

259 dname = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_PTR_DNAME) 

260 return PTRRecordData(dname=maybe_str(_ffi.string(dname))) 

261 

262 elif record_type == _lib.ARES_REC_TYPE_SOA: 

263 mname = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_SOA_MNAME) 

264 rname = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_SOA_RNAME) 

265 serial = _lib.ares_dns_rr_get_u32(rr, _lib.ARES_RR_SOA_SERIAL) 

266 refresh = _lib.ares_dns_rr_get_u32(rr, _lib.ARES_RR_SOA_REFRESH) 

267 retry = _lib.ares_dns_rr_get_u32(rr, _lib.ARES_RR_SOA_RETRY) 

268 expire = _lib.ares_dns_rr_get_u32(rr, _lib.ARES_RR_SOA_EXPIRE) 

269 minimum = _lib.ares_dns_rr_get_u32(rr, _lib.ARES_RR_SOA_MINIMUM) 

270 return SOARecordData( 

271 mname=maybe_str(_ffi.string(mname)), 

272 rname=maybe_str(_ffi.string(rname)), 

273 serial=serial, 

274 refresh=refresh, 

275 retry=retry, 

276 expire=expire, 

277 minimum=minimum 

278 ) 

279 

280 elif record_type == _lib.ARES_REC_TYPE_SRV: 

281 priority = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_SRV_PRIORITY) 

282 weight = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_SRV_WEIGHT) 

283 port = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_SRV_PORT) 

284 target = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_SRV_TARGET) 

285 return SRVRecordData( 

286 priority=priority, 

287 weight=weight, 

288 port=port, 

289 target=maybe_str(_ffi.string(target)) 

290 ) 

291 

292 elif record_type == _lib.ARES_REC_TYPE_TLSA: 

293 cert_usage = _lib.ares_dns_rr_get_u8(rr, _lib.ARES_RR_TLSA_CERT_USAGE) 

294 selector = _lib.ares_dns_rr_get_u8(rr, _lib.ARES_RR_TLSA_SELECTOR) 

295 matching_type = _lib.ares_dns_rr_get_u8(rr, _lib.ARES_RR_TLSA_MATCH) 

296 data_len = _ffi.new("size_t *") 

297 data_ptr = _lib.ares_dns_rr_get_bin(rr, _lib.ARES_RR_TLSA_DATA, data_len) 

298 cert_data = bytes(_ffi.buffer(data_ptr, data_len[0])) if data_ptr != _ffi.NULL else b'' 

299 return TLSARecordData( 

300 cert_usage=cert_usage, 

301 selector=selector, 

302 matching_type=matching_type, 

303 cert_association_data=cert_data 

304 ) 

305 

306 elif record_type == _lib.ARES_REC_TYPE_HTTPS: 

307 priority = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_HTTPS_PRIORITY) 

308 target = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_HTTPS_TARGET) 

309 params = _extract_opt_params(rr, _lib.ARES_RR_HTTPS_PARAMS) 

310 return HTTPSRecordData( 

311 priority=priority, 

312 target=maybe_str(_ffi.string(target)), 

313 params=params 

314 ) 

315 

316 elif record_type == _lib.ARES_REC_TYPE_URI: 

317 priority = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_URI_PRIORITY) 

318 weight = _lib.ares_dns_rr_get_u16(rr, _lib.ARES_RR_URI_WEIGHT) 

319 target = _lib.ares_dns_rr_get_str(rr, _lib.ARES_RR_URI_TARGET) 

320 return URIRecordData( 

321 priority=priority, 

322 weight=weight, 

323 target=maybe_str(_ffi.string(target)) 

324 ) 

325 

326 else: 

327 # Unknown record type - return None or raise error 

328 raise ValueError(f"Unsupported DNS record type: {record_type}") 

329 

330 

331def parse_dnsrec(dnsrec): 

332 """Parse ares_dns_record_t into DNSResult with all sections""" 

333 if dnsrec == _ffi.NULL: 

334 return None, _lib.ARES_EBADRESP 

335 

336 answer_records = [] 

337 authority_records = [] 

338 additional_records = [] 

339 

340 # Parse answer section 

341 answer_count = _lib.ares_dns_record_rr_cnt(dnsrec, _lib.ARES_SECTION_ANSWER) 

342 for i in range(answer_count): 

343 rr = _lib.ares_dns_record_rr_get_const(dnsrec, _lib.ARES_SECTION_ANSWER, i) 

344 if rr != _ffi.NULL: 

345 name = maybe_str(_ffi.string(_lib.ares_dns_rr_get_name(rr))) 

346 rec_type = _lib.ares_dns_rr_get_type(rr) 

347 rec_class = _lib.ares_dns_rr_get_class(rr) 

348 ttl = _lib.ares_dns_rr_get_ttl(rr) 

349 

350 try: 

351 data = extract_record_data(rr, rec_type) 

352 answer_records.append(DNSRecord( 

353 name=name, 

354 type=rec_type, 

355 record_class=rec_class, 

356 ttl=ttl, 

357 data=data 

358 )) 

359 except (ValueError, Exception): 

360 # Skip unsupported record types 

361 pass 

362 

363 # Parse authority section 

364 authority_count = _lib.ares_dns_record_rr_cnt(dnsrec, _lib.ARES_SECTION_AUTHORITY) 

365 for i in range(authority_count): 

366 rr = _lib.ares_dns_record_rr_get_const(dnsrec, _lib.ARES_SECTION_AUTHORITY, i) 

367 if rr != _ffi.NULL: 

368 name = maybe_str(_ffi.string(_lib.ares_dns_rr_get_name(rr))) 

369 rec_type = _lib.ares_dns_rr_get_type(rr) 

370 rec_class = _lib.ares_dns_rr_get_class(rr) 

371 ttl = _lib.ares_dns_rr_get_ttl(rr) 

372 

373 try: 

374 data = extract_record_data(rr, rec_type) 

375 authority_records.append(DNSRecord( 

376 name=name, 

377 type=rec_type, 

378 record_class=rec_class, 

379 ttl=ttl, 

380 data=data 

381 )) 

382 except (ValueError, Exception): 

383 # Skip unsupported record types 

384 pass 

385 

386 # Parse additional section 

387 additional_count = _lib.ares_dns_record_rr_cnt(dnsrec, _lib.ARES_SECTION_ADDITIONAL) 

388 for i in range(additional_count): 

389 rr = _lib.ares_dns_record_rr_get_const(dnsrec, _lib.ARES_SECTION_ADDITIONAL, i) 

390 if rr != _ffi.NULL: 

391 name = maybe_str(_ffi.string(_lib.ares_dns_rr_get_name(rr))) 

392 rec_type = _lib.ares_dns_rr_get_type(rr) 

393 rec_class = _lib.ares_dns_rr_get_class(rr) 

394 ttl = _lib.ares_dns_rr_get_ttl(rr) 

395 

396 try: 

397 data = extract_record_data(rr, rec_type) 

398 additional_records.append(DNSRecord( 

399 name=name, 

400 type=rec_type, 

401 record_class=rec_class, 

402 ttl=ttl, 

403 data=data 

404 )) 

405 except (ValueError, Exception): 

406 # Skip unsupported record types 

407 pass 

408 

409 result = DNSResult( 

410 answer=answer_records, 

411 authority=authority_records, 

412 additional=additional_records 

413 ) 

414 

415 return result, None 

416 

417 

418class _ChannelShutdownManager: 

419 """Manages channel destruction in a single background thread using SimpleQueue.""" 

420 

421 def __init__(self) -> None: 

422 self._queue: SimpleQueue = SimpleQueue() 

423 self._thread: Optional[threading.Thread] = None 

424 self._start_lock = threading.Lock() 

425 

426 def _run_safe_shutdown_loop(self) -> None: 

427 """Process channel destruction requests from the queue.""" 

428 while True: 

429 # Block forever until we get a channel to destroy 

430 channel, _ = self._queue.get() 

431 

432 # Cancel all pending queries - this will trigger callbacks with ARES_ECANCELLED 

433 _lib.ares_cancel(channel[0]) 

434 

435 # Wait for all queries to finish 

436 _lib.ares_queue_wait_empty(channel[0], -1) 

437 

438 # Destroy the channel 

439 if channel is not None: 

440 _lib.ares_destroy(channel[0]) 

441 

442 def start(self) -> None: 

443 """Start the background thread if not already started.""" 

444 if self._thread is not None: 

445 return 

446 with self._start_lock: 

447 if self._thread is not None: 

448 # Started by another thread while waiting for the lock 

449 return 

450 self._thread = threading.Thread(target=self._run_safe_shutdown_loop, daemon=True) 

451 self._thread.start() 

452 

453 def destroy_channel(self, channel, sock_state_cb_handle) -> None: 

454 """ 

455 Schedule channel destruction on the background thread. 

456 

457 The socket state callback handle is passed along to ensure it remains 

458 alive until the channel is destroyed. 

459 

460 Thread Safety and Synchronization: 

461 This method uses SimpleQueue which is thread-safe for putting items 

462 from multiple threads. The background thread processes channels 

463 sequentially waiting for queries to end before each destruction. 

464 """ 

465 self._queue.put((channel, sock_state_cb_handle)) 

466 

467 

468# Global shutdown manager instance 

469_shutdown_manager = _ChannelShutdownManager() 

470 

471 

472class Channel: 

473 __qtypes__ = (_lib.ARES_REC_TYPE_A, _lib.ARES_REC_TYPE_AAAA, _lib.ARES_REC_TYPE_ANY, _lib.ARES_REC_TYPE_CAA, _lib.ARES_REC_TYPE_CNAME, _lib.ARES_REC_TYPE_HTTPS, _lib.ARES_REC_TYPE_MX, _lib.ARES_REC_TYPE_NAPTR, _lib.ARES_REC_TYPE_NS, _lib.ARES_REC_TYPE_PTR, _lib.ARES_REC_TYPE_SOA, _lib.ARES_REC_TYPE_SRV, _lib.ARES_REC_TYPE_TLSA, _lib.ARES_REC_TYPE_TXT, _lib.ARES_REC_TYPE_URI) 

474 __qclasses__ = (_lib.ARES_CLASS_IN, _lib.ARES_CLASS_CHAOS, _lib.ARES_CLASS_HESOID, _lib.ARES_CLASS_NONE, _lib.ARES_CLASS_ANY) 

475 

476 def __init__(self, 

477 *, 

478 flags: Optional[int] = None, 

479 timeout: Optional[float] = None, 

480 tries: Optional[int] = None, 

481 ndots: Optional[int] = None, 

482 tcp_port: Optional[int] = None, 

483 udp_port: Optional[int] = None, 

484 servers: Optional[Iterable[Union[str, bytes]]] = None, 

485 domains: Optional[Iterable[Union[str, bytes]]] = None, 

486 lookups: Union[str, bytes, None] = None, 

487 sock_state_cb: Optional[Callable[[int, bool, bool], None]] = None, 

488 socket_send_buffer_size: Optional[int] = None, 

489 socket_receive_buffer_size: Optional[int] = None, 

490 rotate: bool = False, 

491 local_ip: Union[str, bytes, None] = None, 

492 local_dev: Optional[str] = None, 

493 resolvconf_path: Union[str, bytes, None] = None) -> None: 

494 

495 # Initialize _channel to None first to ensure __del__ doesn't fail 

496 self._channel = None 

497 

498 # Store flags for later use (default is 0 if not specified) 

499 self._flags = flags if flags is not None else 0 

500 

501 channel = _ffi.new("ares_channel *") 

502 options = _ffi.new("struct ares_options *") 

503 optmask = 0 

504 

505 if flags is not None: 

506 options.flags = flags 

507 optmask = optmask | _lib.ARES_OPT_FLAGS 

508 

509 if timeout is not None: 

510 options.timeout = int(timeout * 1000) 

511 optmask = optmask | _lib.ARES_OPT_TIMEOUTMS 

512 

513 if tries is not None: 

514 options.tries = tries 

515 optmask = optmask | _lib.ARES_OPT_TRIES 

516 

517 if ndots is not None: 

518 options.ndots = ndots 

519 optmask = optmask | _lib.ARES_OPT_NDOTS 

520 

521 if tcp_port is not None: 

522 options.tcp_port = tcp_port 

523 optmask = optmask | _lib.ARES_OPT_TCP_PORT 

524 

525 if udp_port is not None: 

526 options.udp_port = udp_port 

527 optmask = optmask | _lib.ARES_OPT_UDP_PORT 

528 

529 if socket_send_buffer_size is not None: 

530 options.socket_send_buffer_size = socket_send_buffer_size 

531 optmask = optmask | _lib.ARES_OPT_SOCK_SNDBUF 

532 

533 if socket_receive_buffer_size is not None: 

534 options.socket_receive_buffer_size = socket_receive_buffer_size 

535 optmask = optmask | _lib.ARES_OPT_SOCK_RCVBUF 

536 

537 if sock_state_cb: 

538 if not callable(sock_state_cb): 

539 raise TypeError("sock_state_cb is not callable") 

540 

541 userdata = _ffi.new_handle(sock_state_cb) 

542 

543 # This must be kept alive while the channel is alive. 

544 self._sock_state_cb_handle = userdata 

545 

546 options.sock_state_cb = _lib._sock_state_cb 

547 options.sock_state_cb_data = userdata 

548 optmask = optmask | _lib.ARES_OPT_SOCK_STATE_CB 

549 else: 

550 self._sock_state_cb_handle = None 

551 optmask = optmask | _lib.ARES_OPT_EVENT_THREAD 

552 options.evsys = _lib.ARES_EVSYS_DEFAULT 

553 

554 if lookups: 

555 options.lookups = _ffi.new('char[]', ascii_bytes(lookups)) 

556 optmask = optmask | _lib.ARES_OPT_LOOKUPS 

557 

558 if domains: 

559 strs = [_ffi.new("char[]", ascii_bytes(i)) for i in domains] 

560 c = _ffi.new("char *[%d]" % (len(domains) + 1)) 

561 for i in range(len(domains)): 

562 c[i] = strs[i] 

563 

564 options.domains = c 

565 options.ndomains = len(domains) 

566 optmask = optmask | _lib.ARES_OPT_DOMAINS 

567 

568 if rotate: 

569 optmask = optmask | _lib.ARES_OPT_ROTATE 

570 

571 if resolvconf_path is not None: 

572 optmask = optmask | _lib.ARES_OPT_RESOLVCONF 

573 options.resolvconf_path = _ffi.new('char[]', ascii_bytes(resolvconf_path)) 

574 

575 r = _lib.ares_init_options(channel, options, optmask) 

576 if r != _lib.ARES_SUCCESS: 

577 raise AresError('Failed to initialize c-ares channel') 

578 

579 self._channel = channel 

580 if servers: 

581 self.servers = servers 

582 

583 if local_ip: 

584 self.set_local_ip(local_ip) 

585 

586 if local_dev: 

587 self.set_local_dev(local_dev) 

588 

589 # Ensure the shutdown thread is started 

590 _shutdown_manager.start() 

591 

592 def __del__(self) -> None: 

593 """Ensure the channel is destroyed when the object is deleted.""" 

594 self.close() 

595 

596 def _create_callback_handle(self, callback_data): 

597 """ 

598 Create a callback handle and register it for tracking. 

599 

600 This ensures that: 

601 1. The callback data is wrapped in a CFFI handle 

602 2. The handle is mapped to this channel to keep it alive 

603 

604 Args: 

605 callback_data: The data to pass to the callback (usually a callable or tuple) 

606 

607 Returns: 

608 The CFFI handle that can be passed to C functions 

609 

610 Raises: 

611 RuntimeError: If the channel is destroyed 

612 

613 """ 

614 if self._channel is None: 

615 raise RuntimeError("Channel is destroyed, no new queries allowed") 

616 

617 userdata = _ffi.new_handle(callback_data) 

618 _handle_to_channel[userdata] = self 

619 return userdata 

620 

621 def cancel(self) -> None: 

622 _lib.ares_cancel(self._channel[0]) 

623 

624 def reinit(self) -> None: 

625 r = _lib.ares_reinit(self._channel[0]) 

626 if r != _lib.ARES_SUCCESS: 

627 raise AresError(r, errno.strerror(r)) 

628 

629 @property 

630 def servers(self) -> list[str]: 

631 csv_str = _lib.ares_get_servers_csv(self._channel[0]) 

632 

633 if csv_str == _ffi.NULL: 

634 raise AresError(_lib.ARES_ENOMEM, errno.strerror(_lib.ARES_ENOMEM)) 

635 

636 server_list = [] 

637 csv_string = maybe_str(_ffi.string(csv_str)) 

638 _lib.ares_free_string(csv_str) 

639 server_list = [s.strip() for s in csv_string.split(',')] 

640 

641 return server_list 

642 

643 @servers.setter 

644 def servers(self, servers: Iterable[Union[str, bytes]]) -> None: 

645 server_list = [ascii_bytes(s).decode('ascii') if isinstance(s, bytes) else s for s in servers] 

646 csv_str = ','.join(server_list) 

647 

648 r = _lib.ares_set_servers_csv(self._channel[0], csv_str.encode('ascii')) 

649 if r != _lib.ARES_SUCCESS: 

650 raise AresError(r, errno.strerror(r)) 

651 

652 def process_fd(self, read_fd: int, write_fd: int) -> None: 

653 _lib.ares_process_fd(self._channel[0], _ffi.cast("ares_socket_t", read_fd), _ffi.cast("ares_socket_t", write_fd)) 

654 

655 def process_read_fd(self, read_fd:int) -> None: 

656 _lib.ares_process_fd(self._channel[0], _ffi.cast("ares_socket_t", read_fd), _ffi.cast("ares_socket_t", ARES_SOCKET_BAD)) 

657 

658 def process_write_fd(self, write_fd:int) -> None: 

659 _lib.ares_process_fd(self._channel[0], _ffi.cast("ares_socket_t", ARES_SOCKET_BAD), _ffi.cast("ares_socket_t", write_fd)) 

660 

661 def timeout(self, t = None): 

662 maxtv = _ffi.NULL 

663 tv = _ffi.new("struct timeval*") 

664 

665 if t is not None: 

666 if t >= 0.0: 

667 maxtv = _ffi.new("struct timeval*") 

668 maxtv.tv_sec = int(math.floor(t)) 

669 maxtv.tv_usec = int(math.fmod(t, 1.0) * 1000000) 

670 else: 

671 raise ValueError("timeout needs to be a positive number or None") 

672 

673 _lib.ares_timeout(self._channel[0], maxtv, tv) 

674 

675 if tv == _ffi.NULL: 

676 return 0.0 

677 

678 return (tv.tv_sec + tv.tv_usec / 1000000.0) 

679 

680 def gethostbyaddr(self, addr: str, *, callback: Callable[[Any, int], None]) -> None: 

681 if not callable(callback): 

682 raise TypeError("a callable is required") 

683 

684 addr4 = _ffi.new("struct in_addr*") 

685 addr6 = _ffi.new("struct ares_in6_addr*") 

686 if _lib.ares_inet_pton(socket.AF_INET, ascii_bytes(addr), (addr4)) == 1: 

687 address = addr4 

688 family = socket.AF_INET 

689 elif _lib.ares_inet_pton(socket.AF_INET6, ascii_bytes(addr), (addr6)) == 1: 

690 address = addr6 

691 family = socket.AF_INET6 

692 else: 

693 raise ValueError("invalid IP address") 

694 

695 userdata = self._create_callback_handle(callback) 

696 _lib.ares_gethostbyaddr(self._channel[0], address, _ffi.sizeof(address[0]), family, _lib._host_cb, userdata) 

697 

698 def getaddrinfo( 

699 self, 

700 host: str, 

701 port: Optional[int], 

702 *, 

703 family: socket.AddressFamily = 0, 

704 type: int = 0, 

705 proto: int = 0, 

706 flags: int = 0, 

707 callback: Callable[[Any, int], None] 

708 ) -> None: 

709 if not callable(callback): 

710 raise TypeError("a callable is required") 

711 

712 if port is None: 

713 service = _ffi.NULL 

714 elif isinstance(port, int): 

715 service = str(port).encode('ascii') 

716 else: 

717 service = ascii_bytes(port) 

718 

719 userdata = self._create_callback_handle(callback) 

720 

721 hints = _ffi.new('struct ares_addrinfo_hints*') 

722 hints.ai_flags = flags 

723 hints.ai_family = family 

724 hints.ai_socktype = type 

725 hints.ai_protocol = proto 

726 _lib.ares_getaddrinfo(self._channel[0], parse_name(host), service, hints, _lib._addrinfo_cb, userdata) 

727 

728 def query(self, name: str, query_type: int, *, query_class: int = QUERY_CLASS_IN, callback: Callable[[Any, int], None]) -> None: 

729 """ 

730 Perform a DNS query. 

731 

732 Args: 

733 name: Domain name to query 

734 query_type: Type of query (e.g., QUERY_TYPE_A, QUERY_TYPE_AAAA, etc.) 

735 query_class: Query class (default: QUERY_CLASS_IN) 

736 callback: Callback function that receives (result, errno) 

737 

738 The callback will receive a DNSResult object containing answer, authority, and additional sections. 

739 """ 

740 if not callable(callback): 

741 raise TypeError('a callable is required') 

742 

743 if query_type not in self.__qtypes__: 

744 raise ValueError('invalid query type specified') 

745 

746 if query_class not in self.__qclasses__: 

747 raise ValueError('invalid query class specified')