LCOV - code coverage report
Current view: top level - disco/topo - fd_dns_resolve.h (source / functions) Hit Total Coverage
Test: cov.lcov Lines: 1 1 100.0 %
Date: 2026-11-15 04:25:17 Functions: 0 0 -

          Line data    Source code
       1             : #ifndef HEADER_fd_src_disco_topo_fd_dns_resolve_h
       2             : #define HEADER_fd_src_disco_topo_fd_dns_resolve_h
       3             : 
       4             : /* fd_dns_resolve provides blocking hostname->IPv4 resolution helpers
       5             :    for tile privileged_init and standalone commands.
       6             : 
       7             :    Except for fd_dns_peer_parse these block on the network (getaddrinfo
       8             :    or a drained fd_adns) and so must only be used before a tile enters
       9             :    its seccomp sandbox, never on the hot path.  For DNS inside the
      10             :    sandbox use fd_adns directly (src/waltz/resolv), see the snapct and
      11             :    bundle tiles. */
      12             : 
      13             : #include "../../util/net/fd_net_headers.h" /* fd_ip4_port_t */
      14             : #include "../../waltz/fd_fqdn.h"           /* FD_FQDN_BUF_MAX */
      15             : 
      16             : #include <netdb.h> /* struct addrinfo */
      17             : 
      18             : FD_PROTOTYPES_BEGIN
      19             : 
      20             : /* fd_dns_resolve_address resolves a single address to a single IPv4
      21             :    address.  If address is already a valid IPv4 dotted-quad it is parsed
      22             :    directly; otherwise it is resolved via DNS and the first IPv4 record
      23             :    is returned via *ip_addr (network byte order).  Returns 1 on success,
      24             :    0 on failure (a warning is logged on DNS failure). */
      25             : 
      26             : int
      27             : fd_dns_resolve_address( char const * address,
      28             :                         uint *       ip_addr );
      29             : 
      30             : /* fd_dns_resolve_addresses resolves a hostname to up to ip_addr_cnt
      31             :    IPv4 addresses, written into ip_addrs[].addr (network byte order;
      32             :    .port is left untouched).  hints may be NULL (defaults to AF_INET).
      33             :    Returns the number of addresses resolved (a warning is logged on DNS
      34             :    failure, returning 0). */
      35             : 
      36             : int
      37             : fd_dns_resolve_addresses( char const *            address,
      38             :                           struct addrinfo const * hints,
      39             :                           fd_ip4_port_t *         ip_addrs,
      40             :                           ulong                   ip_addr_cnt );
      41             : 
      42         201 : #define FD_DNS_RESOLVE_PEERS_MAX (32UL)
      43             : 
      44             : /* fd_dns_resolve_peers resolves peer_cnt (<=FD_DNS_RESOLVE_PEERS_MAX)
      45             :    peer strings, stored in fixed peer_stride byte cstr slots starting at
      46             :    peers, to one IPv4 address each in out[].  The lookups for all peers
      47             :    run concurrently on one socket (fd_adns) rather than head-of-line
      48             :    blocking on each name in turn, so the wall clock cost is that of the
      49             :    slowest single lookup.  All fds opened for resolution are closed
      50             :    again before returning (callers are headed into a sandbox).  Fatal
      51             :    on malformed entries or resolution failure. */
      52             : 
      53             : void
      54             : fd_dns_resolve_peers( char const *    peers,
      55             :                       ulong           peer_stride,
      56             :                       ulong           peer_cnt,
      57             :                       char const *    config_str,
      58             :                       fd_ip4_port_t * out );
      59             : 
      60             : /* fd_dns_peer_parse splits a peer string "[http(s)://]host[:port]"
      61             :    into hostname / port (network byte order; defaults to 443 for https
      62             :    when no port is given) / *is_https (may be NULL), without doing any
      63             :    DNS resolution.  Safe to call inside a seccomp sandbox.  Fatal on a
      64             :    malformed peer string (config_str names the offending config key). */
      65             : 
      66             : void
      67             : fd_dns_peer_parse( char const * peer,
      68             :                    char const * config_str,
      69             :                    char         hostname[ static FD_FQDN_BUF_MAX ],
      70             :                    ushort *     port,
      71             :                    int *        is_https );
      72             : 
      73             : FD_PROTOTYPES_END
      74             : 
      75             : #endif /* HEADER_fd_src_disco_topo_fd_dns_resolve_h */

Generated by: LCOV version 1.14