src/dnsc

Search:
Group by:

Types

DnsClient = object
Contains information about the DNS server. 
DnsResponseError = object of CatchableError
  rcode*: RCode
Raised if the DNS response contains an error (rcode != NoError). 
IsNotAnResponseError = object of CatchableError
Raised if not a response (!= QR.Response). 
OpCodeNotEqualError = object of CatchableError
Raised if the OpCode is different between the query and the response. 
ResponseIdNotEqualError = object of CatchableError
Raised if the query ID does not match the response ID. 
UnexpectedDisconnectionError = object of CatchableError
Raised if an unexpected disconnect occurs (only TCP).

Consts

dnscDnsServerIp {.strdefine.} = "8.8.8.8"
Default dns server ip for queries. You can change by compiling with -d:dnscDnsServerIp=1.1.1.1.

Procs

proc dnsQuery(client: DnsClient; msg: Message;
              timeout: Duration = 500.milliseconds; retransmit = false;
              tcpTimeout: Duration = 5000.milliseconds): Future[Message] {.
    ...stackTrace: false, raises: [], gcsafe, tags: [RootEffect], forbids: [].}

Returns a Message of the DNS query response performed using the UDP protocol.

Parameters

  • client is a DnsClient object that contains the IP and Port of the DNS server.
  • msg is a Message object that contains the DNS query.
  • timeout is the maximum waiting time, in milliseconds, to receive the response from the DNS server. When it is negative (less than 0), it will try to receive the response for an unlimited time.
  • retransmit when true, determine the retransmission of the query to TCP protocol when the received response is truncated (header.flags.tc == true).
  • tcpTimeout is the maximum waiting time for TCP fallback when retransmit is true. Defaults to 5000ms since TCP connections typically need more time than UDP.

Note: This proc does not check the response rcode. The caller should inspect result.header.flags.rcode to handle DNS errors (e.g., NXDomain, ServFail). For automatic rcode checking, use the high-level resolveIpv4, resolveIpv6, or resolveRDns procs instead.

proc dnsTcpQuery(client: DnsClient; msg: Message;
                 timeout: Duration = 5000.milliseconds): Future[Message] {.
    ...stackTrace: false, raises: [], gcsafe, tags: [RootEffect], forbids: [].}

Returns a Message of the DNS query response performed using the TCP protocol

Parameters

  • client is a DnsClient object that contains the IP and Port of the DNS server.
  • msg is a Message object that contains the DNS query.
  • timeout is the maximum waiting time, in milliseconds, to connect to the DNS server. When it is negative (less than 0), it will try to connect for an unlimited time.

Note: This proc does not check the response rcode. The caller should inspect result.header.flags.rcode to handle DNS errors (e.g., NXDomain, ServFail). For automatic rcode checking, use the high-level resolveIpv4, resolveIpv6, or resolveRDns procs instead.

proc getIp(client: DnsClient): string {....raises: [], tags: [], forbids: [].}
Returns the IP defined in the client. 
proc getPort(client: DnsClient): Port {....raises: [], tags: [], forbids: [].}
Returns the port defined in the client. 
proc getUpdatedSystemDnsClient(port: Port = Port(53)): DnsClient {.
    ...raises: [OSError, OSError], tags: [], forbids: [].}

Returns a DnsClient reflecting the current system DNS server.

On Linux/BSD, this leverages cached file metadata detection, so repeated calls are cheap when /etc/resolv.conf hasn't changed. On Windows, this queries the system API each time.

If the system DNS server cannot be determined, falls back to dnscDnsServerIp.

This is useful for long-lived applications that need to track system DNS configuration changes.

proc initDnsClient(strIp: string = ""; port: Port = Port(53)): DnsClient {.
    ...raises: [OSError, ValueError], tags: [], forbids: [].}

Returns a created DnsClient object.

If strIp is empty (default), uses the system DNS server. If the system DNS server cannot be determined, falls back to dnscDnsServerIp.

Parameters

  • strIp is a DNS server IP. It can be IPv4 or IPv6. It cannot be a domain name. If empty, the system DNS server is used.
  • port is a DNS server listening port.

Currently system DNS detection is implemented for:

Notes:

  • If your platform is not listed above and uses a resolver configuration file, compile with -d:dnscUseResolver.
  • It just creates a DnsClient object with the IP used by the system. Does not use the system's native DNS resolution implementation unless the system provides a proxy.
proc prepareDnsBL(strIp, dnsbl: string): string {....raises: [ValueError],
    tags: [], forbids: [].}

Returns a domain name for DnsBL query.

Parameters

  • ip is the IP address you want to query. It can be an IPv4 or IPv6. It cannot be a domain name.
  • dnsbl is the domain name that maintains the blacklist.
proc prepareRDns(strIp: string): string {....raises: [ValueError], tags: [],
    forbids: [].}

Returns a domain name for reverse DNS lookup.

Parameters

  • ip is the IP address you want to query. It can be an IPv4 or IPv6. It cannot be a domain name.
proc randId(): uint16 {....raises: [], tags: [], forbids: [].}
Returns a uint16, randomly generated, to be used as an id. 
proc resolveDnsBL(client: DnsClient; strIp, dnsbl: string;
                  timeout: Duration = 500.milliseconds): Future[seq[string]] {.
    ...stackTrace: false, raises: [], gcsafe, tags: [RootEffect], forbids: [].}

Returns IPv4 addresses. Usually the loopback address (127.0.0.0/24), in which the last octet of IPv4 represents something on the black list.

Parameters

  • client is a DnsClient object that contains the IP and Port of the DNS server.
  • ip is the IPv4 or IPv6 address that you want to know if it is blacklisted.
  • dnsbl is the domain name for DnsBL queries.
  • timeout is the maximum waiting time, in milliseconds, to connect to the DNS server or to receive the response from the DNS server. When it is negative (less than 0), it will try to connect for an unlimited time or to receive the response for an unlimited time.

Note: Returns an empty seq when the IP is not blacklisted (NXDOMAIN). Other DNS errors still raise DnsResponseError.

proc resolveIpv4(client: DnsClient; domain: string;
                 timeout: Duration = 500.milliseconds): Future[seq[string]] {.
    ...stackTrace: false, raises: [], gcsafe, tags: [RootEffect], forbids: [].}

Returns all IPv4 addresses, in a seq[string], that have been resolved from domain. The seq[string] can be empty.

Parameters

  • client is a DnsClient object that contains the IP and Port of the DNS server.
  • domain is the domain name that you wish to obtain IPv4 addresses.
  • timeout is the maximum waiting time, in milliseconds, to connect to the DNS server or to receive the response from the DNS server. When it is negative (less than 0), it will try to connect for an unlimited time or to receive the response for an unlimited time.
proc resolveIpv6(client: DnsClient; domain: string;
                 timeout: Duration = 500.milliseconds): Future[seq[string]] {.
    ...stackTrace: false, raises: [], gcsafe, tags: [RootEffect], forbids: [].}

Returns all IPv6 addresses, in a seq[string], that have been resolved from domain. The seq[string] can be empty.

Parameters

  • client is a DnsClient object that contains the IP and Port of the DNS server.
  • domain is the domain name that you wish to obtain IPv6 addresses.
  • timeout is the maximum waiting time, in milliseconds, to connect to the DNS server or to receive the response from the DNS server. When it is negative (less than 0), it will try to connect for an unlimited time or to receive the response for an unlimited time.
proc resolveRDns(client: DnsClient; strIp: string;
                 timeout: Duration = 500.milliseconds): Future[seq[string]] {.
    ...stackTrace: false, raises: [], gcsafe, tags: [RootEffect], forbids: [].}

Returns all domain names, in a seq[string], which is obtained by the "reverse" query of ip. The seq[string] can be empty.

Parameters

  • client is a DnsClient object that contains the IP and Port of the DNS server.
  • ip is the IPv4 or IPv6 address that is intended to obtain the domain name, which represents the reverse address.
  • timeout is the maximum waiting time, in milliseconds, to connect to the DNS server or to receive the response from the DNS server. When it is negative (less than 0), it will try to connect for an unlimited time or to receive the response for an unlimited time.

Made with Nim. Generated: 2026-04-03 07:56:20 UTC