dohdec/types/dnsUtils.d.ts

DNS over HTTPS and DNS over TLS

/**
 * @typedef {object} LookupOptions
 * @property {string} [name] Name to look up.
 * @property {packet.RecordType} [rrtype] The Resource Record type to retrive.
 * @property {number} [id] The 2-byte unsigned integer for the request.
 *   For DOH, should be 0 or undefined.
 * @property {boolean} [decode=true] Decode the response, either into JSON
 *   or an object representing the DNS format result.
 * @property {boolean} [stream=false] Encode for streaming, with the packet
 *   prefixed by a 2-byte big-endian integer of the number of bytes in the
 *   packet.
 * @property {boolean} [dnssec=false] Request DNSSec records.  Currently
 *   requires `json: false`.
 * @property {boolean} [dnssecCheckingDisabled=false] Disable DNSSEC
 */
/**
 * @typedef {import('stream').Writable & {isTTY?: boolean}} Writable
 */
/**
 * Extracted from node source.
 * Only exported for testing.
 *
 * @param {string} str
 * @param {util.Style} styleType
 * @returns {string}
 * @private
 */
export function stylizeWithColor(str: string, styleType: util.Style): string;
/**
 * Exported for testing only
 * @param {Writable} stream
 * @param {Buffer} buf
 * @returns {number}
 */
export function printableString(stream: Writable, buf: Buffer): number;
export class DNSutils extends EventEmitter<[never]> {
    /**
     * Encode a DNS query packet to a buffer.
     *
     * @param {object} opts Options for the query.
     * @param {string} [opts.name] The name to look up.
     * @param {number} [opts.id=0] ID for the query.  SHOULD be 0 for DOH.
     * @param {packet.RecordType} [opts.rrtype="A"] The record type to look up.
     * @param {boolean} [opts.dnssec=false] Request DNSSec information?
     * @param {boolean} [opts.dnssecCheckingDisabled=false] Disable DNSSec
     *   validation?
     * @param {string} [opts.ecsSubnet] Subnet to use for ECS.
     * @param {number} [opts.ecs] Number of ECS bits.  Defaults to 24 or 56
     *   (IPv4/IPv6).
     * @param {boolean} [opts.stream=false] Encode for streaming, with the packet
     *   prefixed by a 2-byte big-endian integer of the number of bytes in the
     *   packet.
     * @returns {Buffer} The encoded packet.
     */
    static makePacket(opts: {
        name?: string | undefined;
        id?: number | undefined;
        rrtype?: packet.RecordType | undefined;
        dnssec?: boolean | undefined;
        dnssecCheckingDisabled?: boolean | undefined;
        ecsSubnet?: string | undefined;
        ecs?: number | undefined;
        stream?: boolean | undefined;
    }): Buffer;
    /**
     * Normalize parameters into the lookup functions.
     *
     * @param {string|LookupOptions} [name] If string, lookup this name,
     *   otherwise it is options.  Has precedence over opts.name if string.
     * @param {string|LookupOptions} [opts] If string, rrtype.
     *   Otherwise options.
     * @param {object} [defaults] Defaults options.
     * @returns {LookupOptions} Normalized options, including punycode∑d
     *   options.name and upper-case options.rrtype.
     * @throws {Error} Invalid type for name.
     */
    static normalizeArgs(name?: string | LookupOptions, opts?: string | LookupOptions, defaults?: object): LookupOptions;
    /**
     * See [RFC 4648]{@link https://tools.ietf.org/html/rfc4648#section-5}.
     *
     * @param {Buffer} buf Buffer to encode.
     * @returns {string} The base64url string.
     */
    static base64urlEncode(buf: Buffer): string;
    /**
     * Recursively traverse an object, turning all of its properties that have
     * Buffer values into base64 representations of the buffer.
     *
     * @param {any} o The object to traverse.
     * @param {WeakSet<object>} [circular] WeakMap to prevent circular
     *   dependencies.
     * @returns {any} The converted object.
     */
    static buffersToB64(o: any, circular?: WeakSet<object>): any;
    /**
     * Calculate the reverse name to look up for an IP address.
     *
     * @param {string} addr The IPv[46] address to reverse.
     * @returns {string} Address ending in .in-addr.arpa or .ip6.arpa.
     * @throws {Error} Invalid IP Address.
     */
    static reverse(addr: string): string;
    /**
     * Creates an instance of DNSutils.
     *
     * @param {object} [opts={}] Options.
     * @param {number} [opts.verbose=0] How verbose do you want your logging?
     * @param {Writable} [opts.verboseStream=process.stderr]
     *   Where to write verbose output.
     */
    constructor(opts?: {
        verbose?: number | undefined;
        verboseStream?: Writable | undefined;
    });
    /** @type {Writable} */
    verboseStream: Writable;
    _verbose: number;
    /**
     * Output verbose logging information, if this.verbose is true.
     *
     * @param {number} level Print at this verbosity level or higher.
     * @param {any[]} args Same as onsole.log parameters.
     * @returns {boolean} True if output was written.
     */
    verbose(level: number, ...args: any[]): boolean;
    /**
     * Dump a nice hex representation of the given buffer to verboseStream,
     * if verbose is true.
     *
     * @param {number} level Print at this verbosity level or higher.
     * @param {Buffer} buf The buffer to dump.
     * @returns {boolean} True if output was written.
     */
    hexDump(level: number, buf: Buffer): boolean;
}
export class DNSError extends Error {
    /**
     * Factory to extract DNS error from packet, if one exists.
     *
     * @param {Record<string,any>} pkt
     * @returns {DNSError|undefined}
     */
    static getError(pkt: Record<string, any>): DNSError | undefined;
    /**
     * Create a DNS Error that wraps another error.
     * @param {Error} er
     * @param {packet.Packet} pkt
     */
    constructor(er: Error, pkt: packet.Packet);
    packet: packet.Packet;
    code: string;
}
export default DNSutils;
export type LookupOptions = {
    /**
     * Name to look up.
     */
    name?: string | undefined;
    /**
     * The Resource Record type to retrive.
     */
    rrtype?: packet.RecordType | undefined;
    /**
     * The 2-byte unsigned integer for the request.
     * For DOH, should be 0 or undefined.
     */
    id?: number | undefined;
    /**
     * Decode the response, either into JSON
     * or an object representing the DNS format result.
     */
    decode?: boolean | undefined;
    /**
     * Encode for streaming, with the packet
     * prefixed by a 2-byte big-endian integer of the number of bytes in the
     * packet.
     */
    stream?: boolean | undefined;
    /**
     * Request DNSSec records.  Currently
     * requires `json: false`.
     */
    dnssec?: boolean | undefined;
    /**
     * Disable DNSSEC
     */
    dnssecCheckingDisabled?: boolean | undefined;
};
export type Writable = import("stream").Writable & {
    isTTY?: boolean;
};
import util from 'node:util';
import { Buffer } from 'node:buffer';
import { EventEmitter } from 'node:events';
import * as packet from 'dns-packet';