@aws-sdk/util-dns 3.271.0 → 3.274.0

package/dist-cjs/DnsCache.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/NodeDnsLookupHostResolver.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeDnsLookupHostResolver = void 0;
 const types_1 = require("@aws-sdk/types");
 const dns_1 = require("dns");
+const HostEntryTable_1 = require("./util/HostEntryTable");
 const NODE_DNS_FAMILY_TO_HOST_ADDRESS_TYPE = {
     4: types_1.HostAddressType.A,
     6: types_1.HostAddressType.AAAA,
@@ -13,9 +14,59 @@ const DNS_LOOKUP_OPTIONS = {
     verbatim: true,
 };
 class NodeDnsLookupHostResolver {
+    constructor({ ttlMs = NodeDnsLookupHostResolver.DEFAULT_TTL_MS, cache = NodeDnsLookupHostResolver.createDefaultCacheProvider(), nodeDnsLookup = NodeDnsLookupHostResolver.DEFAULT_NODE_DNS_LOOKUP, } = {}) {
+        this.ttlMs = ttlMs;
+        this.cache = cache;
+        this.nodeDnsLookup = nodeDnsLookup;
+    }
     async resolveAddress(args) {
+        const possibleHostEntry = this.cache.get(args.hostName);
+        const newNextTimestampToUpdateMs = Date.now() + this.ttlMs;
+        if (possibleHostEntry === undefined) {
+            const addresses = await this.nodeDnsLookupResolveAddress(args);
+            this.cache.set(args, addresses, newNextTimestampToUpdateMs);
+        }
+        const hostEntry = this.cache.get(args.hostName);
+        if (possibleHostEntry !== undefined && Date.now() >= hostEntry.nextTimestampToUpdateMs) {
+            try {
+                const addresses = await this.nodeDnsLookupResolveAddress(args);
+                hostEntry.updateRecords(addresses, newNextTimestampToUpdateMs);
+            }
+            catch (error) {
+                console.error(`Could not update DNS address cache for "${args.hostName}": ${error}`);
+            }
+        }
+        hostEntry.processRecords();
+        const result = [];
+        if (hostEntry.aRecords.length > 0) {
+            result.push(hostEntry.aRecords.cycle());
+        }
+        if (hostEntry.aaaaRecords.length > 0) {
+            result.push(hostEntry.aaaaRecords.cycle());
+        }
+        if (result.length === 0) {
+            throw new Error(`Could not resolve addresses for "${args.hostName}"`);
+        }
+        return result;
+    }
+    reportFailureOnAddress(addr) {
+        const hostEntry = this.cache.get(addr.hostName);
+        if (hostEntry === undefined) {
+            throw new Error(`Could not find cached host name "${addr.hostName}"`);
+        }
+        hostEntry.failAddressInRecords(addr);
+    }
+    purgeCache(args) {
+        if (args === null || args === void 0 ? void 0 : args.hostName) {
+            this.cache.delete(args.hostName);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    async nodeDnsLookupResolveAddress(args) {
         const addresses = [];
-        const ipEntries = await dns_1.promises.lookup(args.hostName, DNS_LOOKUP_OPTIONS);
+        const ipEntries = await this.nodeDnsLookup(args.hostName, DNS_LOOKUP_OPTIONS);
         for (const { address, family } of ipEntries) {
             const addressType = NODE_DNS_FAMILY_TO_HOST_ADDRESS_TYPE[family];
             if (addressType === undefined) {
@@ -30,11 +81,8 @@ class NodeDnsLookupHostResolver {
         }
         return addresses;
     }
-    reportFailureOnAddress(addr) {
-        throw new Error("reportFailureOnAddress(addr) is not implemented");
-    }
-    purgeCache(args) {
-        throw new Error("purgeCache(args?) is not implemented");
-    }
 }
 exports.NodeDnsLookupHostResolver = NodeDnsLookupHostResolver;
+NodeDnsLookupHostResolver.DEFAULT_TTL_MS = 30000;
+NodeDnsLookupHostResolver.createDefaultCacheProvider = () => new HostEntryTable_1.HostEntryTable();
+NodeDnsLookupHostResolver.DEFAULT_NODE_DNS_LOOKUP = dns_1.promises.lookup;

package/dist-cjs/util/HostAddressEntryCollection.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostAddressEntryCollection = void 0;
+class HostAddressEntryCollection {
+    constructor() {
+        this.data = [];
+    }
+    get length() {
+        return this.data.length;
+    }
+    cycle(collection) {
+        if (this.data.length === 0) {
+            throw new Error("Cannot cycle an empty collection");
+        }
+        const entry = this.data.shift();
+        (collection || this).append(entry);
+        return entry;
+    }
+    append(entry) {
+        this.data.push(entry);
+    }
+    remove(entry) {
+        if (this.length === 0) {
+            throw new Error("Cannot remove from an empty collection");
+        }
+        const index = this.data.findIndex((e) => e.address === entry.address);
+        const removedEntry = this.data[index];
+        this.data.splice(index, 1);
+        return removedEntry;
+    }
+    [Symbol.iterator]() {
+        return this.data[Symbol.iterator]();
+    }
+}
+exports.HostAddressEntryCollection = HostAddressEntryCollection;

package/dist-cjs/util/HostEntry.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostEntry = void 0;
+const types_1 = require("@aws-sdk/types");
+const HostAddressEntryCollection_1 = require("./HostAddressEntryCollection");
+class HostEntry {
+    constructor(nextTimestampToProcessMs) {
+        this.aaaaRecords = new HostAddressEntryCollection_1.HostAddressEntryCollection();
+        this.aRecords = new HostAddressEntryCollection_1.HostAddressEntryCollection();
+        this.failedAaaaRecords = new HostAddressEntryCollection_1.HostAddressEntryCollection();
+        this.failedARecords = new HostAddressEntryCollection_1.HostAddressEntryCollection();
+        this.nextTimestampToUpdateMs = nextTimestampToProcessMs;
+    }
+    updateRecords(addresses, expirationTtlMs) {
+        this.nextTimestampToUpdateMs = expirationTtlMs;
+        const addressesToAppend = [];
+        for (const freshAddress of addresses) {
+            const hostAddressEntry = this.findAddress(freshAddress);
+            if (hostAddressEntry !== undefined) {
+                hostAddressEntry.expirationTtlMs = expirationTtlMs;
+                continue;
+            }
+            addressesToAppend.push(freshAddress);
+        }
+        for (const addressToAppend of addressesToAppend) {
+            const hostAddressEntry = this.findAddress(addressToAppend);
+            if (hostAddressEntry !== undefined) {
+                continue;
+            }
+            const successRecords = this.getGoodRecords(addressToAppend);
+            successRecords.append(Object.assign(addressToAppend, {
+                expirationTtlMs,
+            }));
+        }
+    }
+    processRecords() {
+        this.processRecordsAddressType(this.aRecords, this.failedARecords);
+        this.processRecordsAddressType(this.aaaaRecords, this.failedAaaaRecords);
+    }
+    failAddressInRecords(address) {
+        const successRecords = this.getGoodRecords(address);
+        const failedRecords = this.getFailedRecords(address);
+        const recordsToRemove = [];
+        for (const hostAddressEntry of successRecords) {
+            if (hostAddressEntry.address === address.address) {
+                recordsToRemove.push(hostAddressEntry);
+                failedRecords.append(hostAddressEntry);
+            }
+        }
+        for (const recordToRemove of recordsToRemove) {
+            successRecords.remove(recordToRemove);
+        }
+    }
+    findAddress(address) {
+        const successRecords = this.getGoodRecords(address);
+        for (const hostAddressEntry of successRecords) {
+            if (address.address === hostAddressEntry.address) {
+                return hostAddressEntry;
+            }
+        }
+        const failedRecords = this.getFailedRecords(address);
+        for (const hostAddressEntry of failedRecords) {
+            if (address.address === hostAddressEntry.address) {
+                return hostAddressEntry;
+            }
+        }
+        return undefined;
+    }
+    processRecordsAddressType(successRecords, failedRecords) {
+        const successRecordsToRemove = [];
+        let successIndex = 0;
+        for (const hostAddressEntry of successRecords) {
+            if (successIndex === successRecords.length - 1) {
+                break;
+            }
+            if (Date.now() >= hostAddressEntry.expirationTtlMs) {
+                successRecordsToRemove.push(hostAddressEntry);
+            }
+            successIndex++;
+        }
+        for (const recordToRemove of successRecordsToRemove) {
+            successRecords.remove(recordToRemove);
+        }
+        const failedRecordsToRemove = [];
+        let failedIndex = 0;
+        for (const hostAddressEntry of failedRecords) {
+            if (failedIndex === failedRecords.length - 1) {
+                break;
+            }
+            if (Date.now() >= hostAddressEntry.expirationTtlMs) {
+                failedRecordsToRemove.push(hostAddressEntry);
+            }
+            failedIndex++;
+        }
+        for (const recordToRemove of failedRecordsToRemove) {
+            failedRecords.remove(recordToRemove);
+        }
+        if (successRecords.length === 0) {
+            let hostAddressEntryToPromote = undefined;
+            for (const hostAddressEntry of failedRecords) {
+                if (Date.now() >= hostAddressEntry.expirationTtlMs) {
+                    continue;
+                }
+                hostAddressEntryToPromote = hostAddressEntry;
+                break;
+            }
+            if (hostAddressEntryToPromote !== undefined) {
+                failedRecords.remove(hostAddressEntryToPromote);
+                successRecords.append(hostAddressEntryToPromote);
+            }
+        }
+    }
+    getGoodRecords(address) {
+        return address.addressType === types_1.HostAddressType.AAAA ? this.aaaaRecords : this.aRecords;
+    }
+    getFailedRecords(address) {
+        return address.addressType === types_1.HostAddressType.AAAA ? this.failedAaaaRecords : this.failedARecords;
+    }
+}
+exports.HostEntry = HostEntry;

package/dist-cjs/util/HostEntryTable.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostEntryTable = void 0;
+const HostEntry_1 = require("./HostEntry");
+class HostEntryTable {
+    constructor() {
+        this.map = new Map();
+    }
+    set(args, addresses, nextTimestampToProcessMs) {
+        const hostEntry = new HostEntry_1.HostEntry(nextTimestampToProcessMs);
+        hostEntry.updateRecords(addresses, nextTimestampToProcessMs);
+        this.map.set(args.hostName, hostEntry);
+    }
+    get(hostName) {
+        return this.map.get(hostName);
+    }
+    delete(hostName) {
+        this.map.delete(hostName);
+    }
+    clear() {
+        this.map.clear();
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+exports.HostEntryTable = HostEntryTable;

package/dist-es/DnsCache.js

@@ -0,0 +1 @@
+export {};

package/dist-es/NodeDnsLookupHostResolver.js

@@ -1,5 +1,6 @@
 import { HostAddressType } from "@aws-sdk/types";
 import { ALL, promises as dnsPromises, V4MAPPED } from "dns";
+import { HostEntryTable } from "./util/HostEntryTable";
 const NODE_DNS_FAMILY_TO_HOST_ADDRESS_TYPE = {
     4: HostAddressType.A,
     6: HostAddressType.AAAA,
@@ -10,9 +11,59 @@ const DNS_LOOKUP_OPTIONS = {
     verbatim: true,
 };
 export class NodeDnsLookupHostResolver {
+    constructor({ ttlMs = NodeDnsLookupHostResolver.DEFAULT_TTL_MS, cache = NodeDnsLookupHostResolver.createDefaultCacheProvider(), nodeDnsLookup = NodeDnsLookupHostResolver.DEFAULT_NODE_DNS_LOOKUP, } = {}) {
+        this.ttlMs = ttlMs;
+        this.cache = cache;
+        this.nodeDnsLookup = nodeDnsLookup;
+    }
     async resolveAddress(args) {
+        const possibleHostEntry = this.cache.get(args.hostName);
+        const newNextTimestampToUpdateMs = Date.now() + this.ttlMs;
+        if (possibleHostEntry === undefined) {
+            const addresses = await this.nodeDnsLookupResolveAddress(args);
+            this.cache.set(args, addresses, newNextTimestampToUpdateMs);
+        }
+        const hostEntry = this.cache.get(args.hostName);
+        if (possibleHostEntry !== undefined && Date.now() >= hostEntry.nextTimestampToUpdateMs) {
+            try {
+                const addresses = await this.nodeDnsLookupResolveAddress(args);
+                hostEntry.updateRecords(addresses, newNextTimestampToUpdateMs);
+            }
+            catch (error) {
+                console.error(`Could not update DNS address cache for "${args.hostName}": ${error}`);
+            }
+        }
+        hostEntry.processRecords();
+        const result = [];
+        if (hostEntry.aRecords.length > 0) {
+            result.push(hostEntry.aRecords.cycle());
+        }
+        if (hostEntry.aaaaRecords.length > 0) {
+            result.push(hostEntry.aaaaRecords.cycle());
+        }
+        if (result.length === 0) {
+            throw new Error(`Could not resolve addresses for "${args.hostName}"`);
+        }
+        return result;
+    }
+    reportFailureOnAddress(addr) {
+        const hostEntry = this.cache.get(addr.hostName);
+        if (hostEntry === undefined) {
+            throw new Error(`Could not find cached host name "${addr.hostName}"`);
+        }
+        hostEntry.failAddressInRecords(addr);
+    }
+    purgeCache(args) {
+        if (args?.hostName) {
+            this.cache.delete(args.hostName);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    async nodeDnsLookupResolveAddress(args) {
         const addresses = [];
-        const ipEntries = await dnsPromises.lookup(args.hostName, DNS_LOOKUP_OPTIONS);
+        const ipEntries = await this.nodeDnsLookup(args.hostName, DNS_LOOKUP_OPTIONS);
         for (const { address, family } of ipEntries) {
             const addressType = NODE_DNS_FAMILY_TO_HOST_ADDRESS_TYPE[family];
             if (addressType === undefined) {
@@ -27,10 +78,7 @@ export class NodeDnsLookupHostResolver {
         }
         return addresses;
     }
-    reportFailureOnAddress(addr) {
-        throw new Error("reportFailureOnAddress(addr) is not implemented");
-    }
-    purgeCache(args) {
-        throw new Error("purgeCache(args?) is not implemented");
-    }
 }
+NodeDnsLookupHostResolver.DEFAULT_TTL_MS = 30000;
+NodeDnsLookupHostResolver.createDefaultCacheProvider = () => new HostEntryTable();
+NodeDnsLookupHostResolver.DEFAULT_NODE_DNS_LOOKUP = dnsPromises.lookup;

package/dist-es/util/HostAddressEntryCollection.js

@@ -0,0 +1,31 @@
+export class HostAddressEntryCollection {
+    constructor() {
+        this.data = [];
+    }
+    get length() {
+        return this.data.length;
+    }
+    cycle(collection) {
+        if (this.data.length === 0) {
+            throw new Error("Cannot cycle an empty collection");
+        }
+        const entry = this.data.shift();
+        (collection || this).append(entry);
+        return entry;
+    }
+    append(entry) {
+        this.data.push(entry);
+    }
+    remove(entry) {
+        if (this.length === 0) {
+            throw new Error("Cannot remove from an empty collection");
+        }
+        const index = this.data.findIndex((e) => e.address === entry.address);
+        const removedEntry = this.data[index];
+        this.data.splice(index, 1);
+        return removedEntry;
+    }
+    [Symbol.iterator]() {
+        return this.data[Symbol.iterator]();
+    }
+}

package/dist-es/util/HostEntry.js

@@ -0,0 +1,116 @@
+import { HostAddressType } from "@aws-sdk/types";
+import { HostAddressEntryCollection } from "./HostAddressEntryCollection";
+export class HostEntry {
+    constructor(nextTimestampToProcessMs) {
+        this.aaaaRecords = new HostAddressEntryCollection();
+        this.aRecords = new HostAddressEntryCollection();
+        this.failedAaaaRecords = new HostAddressEntryCollection();
+        this.failedARecords = new HostAddressEntryCollection();
+        this.nextTimestampToUpdateMs = nextTimestampToProcessMs;
+    }
+    updateRecords(addresses, expirationTtlMs) {
+        this.nextTimestampToUpdateMs = expirationTtlMs;
+        const addressesToAppend = [];
+        for (const freshAddress of addresses) {
+            const hostAddressEntry = this.findAddress(freshAddress);
+            if (hostAddressEntry !== undefined) {
+                hostAddressEntry.expirationTtlMs = expirationTtlMs;
+                continue;
+            }
+            addressesToAppend.push(freshAddress);
+        }
+        for (const addressToAppend of addressesToAppend) {
+            const hostAddressEntry = this.findAddress(addressToAppend);
+            if (hostAddressEntry !== undefined) {
+                continue;
+            }
+            const successRecords = this.getGoodRecords(addressToAppend);
+            successRecords.append(Object.assign(addressToAppend, {
+                expirationTtlMs,
+            }));
+        }
+    }
+    processRecords() {
+        this.processRecordsAddressType(this.aRecords, this.failedARecords);
+        this.processRecordsAddressType(this.aaaaRecords, this.failedAaaaRecords);
+    }
+    failAddressInRecords(address) {
+        const successRecords = this.getGoodRecords(address);
+        const failedRecords = this.getFailedRecords(address);
+        const recordsToRemove = [];
+        for (const hostAddressEntry of successRecords) {
+            if (hostAddressEntry.address === address.address) {
+                recordsToRemove.push(hostAddressEntry);
+                failedRecords.append(hostAddressEntry);
+            }
+        }
+        for (const recordToRemove of recordsToRemove) {
+            successRecords.remove(recordToRemove);
+        }
+    }
+    findAddress(address) {
+        const successRecords = this.getGoodRecords(address);
+        for (const hostAddressEntry of successRecords) {
+            if (address.address === hostAddressEntry.address) {
+                return hostAddressEntry;
+            }
+        }
+        const failedRecords = this.getFailedRecords(address);
+        for (const hostAddressEntry of failedRecords) {
+            if (address.address === hostAddressEntry.address) {
+                return hostAddressEntry;
+            }
+        }
+        return undefined;
+    }
+    processRecordsAddressType(successRecords, failedRecords) {
+        const successRecordsToRemove = [];
+        let successIndex = 0;
+        for (const hostAddressEntry of successRecords) {
+            if (successIndex === successRecords.length - 1) {
+                break;
+            }
+            if (Date.now() >= hostAddressEntry.expirationTtlMs) {
+                successRecordsToRemove.push(hostAddressEntry);
+            }
+            successIndex++;
+        }
+        for (const recordToRemove of successRecordsToRemove) {
+            successRecords.remove(recordToRemove);
+        }
+        const failedRecordsToRemove = [];
+        let failedIndex = 0;
+        for (const hostAddressEntry of failedRecords) {
+            if (failedIndex === failedRecords.length - 1) {
+                break;
+            }
+            if (Date.now() >= hostAddressEntry.expirationTtlMs) {
+                failedRecordsToRemove.push(hostAddressEntry);
+            }
+            failedIndex++;
+        }
+        for (const recordToRemove of failedRecordsToRemove) {
+            failedRecords.remove(recordToRemove);
+        }
+        if (successRecords.length === 0) {
+            let hostAddressEntryToPromote = undefined;
+            for (const hostAddressEntry of failedRecords) {
+                if (Date.now() >= hostAddressEntry.expirationTtlMs) {
+                    continue;
+                }
+                hostAddressEntryToPromote = hostAddressEntry;
+                break;
+            }
+            if (hostAddressEntryToPromote !== undefined) {
+                failedRecords.remove(hostAddressEntryToPromote);
+                successRecords.append(hostAddressEntryToPromote);
+            }
+        }
+    }
+    getGoodRecords(address) {
+        return address.addressType === HostAddressType.AAAA ? this.aaaaRecords : this.aRecords;
+    }
+    getFailedRecords(address) {
+        return address.addressType === HostAddressType.AAAA ? this.failedAaaaRecords : this.failedARecords;
+    }
+}

package/dist-es/util/HostEntryTable.js

@@ -0,0 +1,23 @@
+import { HostEntry } from "./HostEntry";
+export class HostEntryTable {
+    constructor() {
+        this.map = new Map();
+    }
+    set(args, addresses, nextTimestampToProcessMs) {
+        const hostEntry = new HostEntry(nextTimestampToProcessMs);
+        hostEntry.updateRecords(addresses, nextTimestampToProcessMs);
+        this.map.set(args.hostName, hostEntry);
+    }
+    get(hostName) {
+        return this.map.get(hostName);
+    }
+    delete(hostName) {
+        this.map.delete(hostName);
+    }
+    clear() {
+        this.map.clear();
+    }
+    get size() {
+        return this.map.size;
+    }
+}

package/dist-types/DnsCache.d.ts

@@ -0,0 +1,122 @@
+import { HostAddress, HostResolverArguments } from "@aws-sdk/types";
+/**
+ * DNS cache used by a {@link HostResolver} which maps:
+ * host name (string) -> {@link DnsCacheEntry}
+ * @internal
+ */
+export interface DnsCache {
+    /**
+     * Maps a host name to a {@link DnsCacheEntry} in the cache
+     * @param args host resolver arguments which include host name
+     * @param addresses addresses to set into the cache entry
+     * @param nextTimestampToProcessMs timestamp for both cache entry processed and addresses' expiration
+     */
+    set(args: HostResolverArguments, addresses: HostAddress[], nextTimestampToProcessMs: number): void;
+    /**
+     * Gets the corresponding cache entry for hostName, otherwise undefined
+     * @param hostName key to get cache entry
+     */
+    get(hostName: string): DnsCacheEntry | undefined;
+    /**
+     * Deletes the corresponding cache entry for hostName
+     * @param hostName key to delete cache entry
+     */
+    delete(hostName: string): void;
+    /**
+     * Deletes all cache entries
+     */
+    clear(): void;
+    /**
+     * Gets the size of the cache
+     */
+    size: number;
+}
+/**
+ * Entry for a host name, mapped to in {@link DnsCache}
+ * @internal
+ */
+export interface DnsCacheEntry {
+    /**
+     * Collection of good IPv6 records for an address
+     */
+    aaaaRecords: DnsCacheEntryCollection;
+    /**
+     * Collection of good IPv4 records for an address
+     */
+    aRecords: DnsCacheEntryCollection;
+    /**
+     * Collection of failed IPv6 records for an address
+     */
+    failedAaaaRecords: DnsCacheEntryCollection;
+    /**
+     * Collection of failed IPv4 records for an address
+     */
+    failedARecords: DnsCacheEntryCollection;
+    /**
+     * Timestamp for when to next process the entry
+     */
+    nextTimestampToUpdateMs: number;
+    /**
+     * Updates the entry given the new set of addresses and a new expiration
+     * timestamp:
+     * - If an address is already in the entry, the expiration timestamp is updated.
+     * - If an address is not in the entry, then it is added to the good records.
+     * @param addresses list of addresses used to update entry records
+     * @param expirationTtlMs expiration timestamp for new or updated addresses
+     */
+    updateRecords(addresses: HostAddress[], expirationTtlMs: number): void;
+    /**
+     * Removes expired records from records (except 1 in case of DNS outages).
+     * In the case that good records are empty, should attempt to promote 1
+     * non-expired failed address to the good records.
+     */
+    processRecords(): void;
+    /**
+     * Moves the address from good records to failed records
+     * @param address address to move to failed records
+     */
+    failAddressInRecords(address: HostAddress): void;
+}
+/**
+ * Collection which is used to manage {@link DnsCacheHostAddressEntry}
+ * @internal
+ */
+export interface DnsCacheEntryCollection {
+    /**
+     * Get length / size of the collection
+     */
+    length: number;
+    /**
+     * Moves a {@link DnsCacheHostAddressEntry} from the beginning of the
+     * collection to the end of itself, and returns the host address entry
+     * that was cycled.
+     * If another collection is provided, it will move the host address entry
+     * to the end of that collection.
+     * @param collection optional collection to cycle to.
+     */
+    cycle(collection?: DnsCacheEntryCollection): DnsCacheHostAddressEntry;
+    /**
+     * Appends an element to the end of the collection
+     * @param element element to append to the collection
+     */
+    append(element: DnsCacheHostAddressEntry): void;
+    /**
+     * Removes an element from the collection, and returns that element.
+     * @param element element to remove and return from the collection
+     */
+    remove(element: DnsCacheHostAddressEntry): DnsCacheHostAddressEntry;
+    /**
+     * Implements iterator for the collection
+     */
+    [Symbol.iterator](): Iterator<DnsCacheHostAddressEntry>;
+}
+/**
+ * Captures cached {@link HostAddress} information
+ * @internal
+ */
+export interface DnsCacheHostAddressEntry extends HostAddress {
+    /**
+     * Timestamp for when the entry expires
+     */
+    expirationTtlMs: number;
+}

package/dist-types/NodeDnsLookupHostResolver.d.ts

@@ -1,16 +1,103 @@
+/// <reference types="node" />
 import { HostAddress, HostResolver as IHostResolver, HostResolverArguments } from "@aws-sdk/types";
+import { LookupAddress, LookupAllOptions } from "dns";
+import { DnsCache } from "./DnsCache";
+/**
+ * Node.js dns.lookup() function type used in {@link NodeDnsLookupHostResolver}
+ * @internal
+ */
+interface NodeDnsLookupFn {
+    (hostname: string, options: LookupAllOptions): Promise<LookupAddress[]>;
+}
+/**
+ * Configuration options for {@link NodeDnsLookupHostResolver}
+ * @internal
+ */
+export interface NodeDnsLookupHostResolverConfig {
+    /**
+     * Cache for holding address entries
+     * @internal
+     */
+    cache?: DnsCache;
+    /**
+     * TTL offset in MS when generating expiration TTLs
+     * @internal
+     */
+    ttlMs?: number;
+    /**
+     * Pluggable Node.js dns.lookup() function
+     * @internal
+     */
+    nodeDnsLookup?: NodeDnsLookupFn;
+}
 /**
  * {@link HostResolver} implementation that uses the Node.js dns.lookup() API.
- * TODO(dns): implement cache
  */
 export declare class NodeDnsLookupHostResolver implements IHostResolver {
     /**
-     * Node.js resolveAddress() using the dns.lookup() APIs.
-     * @see https://nodejs.org/api/dns.html#dnspromiseslookuphostname-options
+     * Default TTL in ms
+     * @internal
+     */
+    private static DEFAULT_TTL_MS;
+    /**
+     * Provider that returns a default {@link DnsCache}
+     * @returns DnsCache implementation
+     * @internal
+     */
+    private static createDefaultCacheProvider;
+    /**
+     * Default Node.js dns.lookup() function
+     * @internal
+     */
+    private static DEFAULT_NODE_DNS_LOOKUP;
+    /**
+     * TTL in ms
+     * @internal
+     */
+    private ttlMs;
+    /**
+     * {@link DnsCache} which maps {@link HostAddress.hostName} to {@link DnsCacheEntry}
+     * @internal
+     */
+    private cache;
+    /**
+     * Node.js dns.lookup() API implementation
+     * @internal
+     */
+    private nodeDnsLookup;
+    constructor({ ttlMs, cache, nodeDnsLookup, }?: NodeDnsLookupHostResolverConfig);
+    /**
+     * Resolves the address(es) for {@link HostResolverArguments} and returns a
+     * list of addresses with (most likely) two addresses, one {@link HostAddressType.AAAA}
+     * and one {@link HostAddressType.A}. Calls to this function will likely alter
+     * the cache so that if there's multiple addresses, a different set will be
+     * returned on the next call.
+     * In the case of multi-answer, still only a maximum of two records should be
+     * returned.
      * @param args arguments with host name query addresses for
      * @returns promise with a list of {@link HostAddress}
+     * @see https://github.com/awslabs/aws-c-io/blob/f2ff573c191e1c4ea0248af5c08161356be3bc78/source/host_resolver.c#L964
      */
     resolveAddress(args: HostResolverArguments): Promise<HostAddress[]>;
+    /**
+     * Reports a failure on a {@link HostAddress} so that the cache can
+     * accomodate the failure and likely not return the address until it recovers.
+     * @param addr host address to report a failure on
+     */
     reportFailureOnAddress(addr: HostAddress): void;
+    /**
+     * Empties the cache for a {@link HostResolverArguments.hostName}.
+     * If {@link HostResolverArguments.hostName} is not provided, the cache
+     * is emptied for all host names.
+     * @param args optional arguments to empty the cache for
+     */
     purgeCache(args?: HostResolverArguments): void;
+    /**
+     * Node.js resolveAddress() using the dns.lookup() APIs.
+     * @see https://nodejs.org/api/dns.html#dnspromiseslookuphostname-options
+     * @param args arguments with host name query addresses for
+     * @returns promise with a list of {@link HostAddress}
+     */
+    private nodeDnsLookupResolveAddress;
 }
+export {};

package/dist-types/ts3.4/DnsCache.d.ts

@@ -0,0 +1,32 @@
+import { HostAddress, HostResolverArguments } from "@aws-sdk/types";
+export interface DnsCache {
+  set(
+    args: HostResolverArguments,
+    addresses: HostAddress[],
+    nextTimestampToProcessMs: number
+  ): void;
+  get(hostName: string): DnsCacheEntry | undefined;
+  delete(hostName: string): void;
+  clear(): void;
+  size: number;
+}
+export interface DnsCacheEntry {
+  aaaaRecords: DnsCacheEntryCollection;
+  aRecords: DnsCacheEntryCollection;
+  failedAaaaRecords: DnsCacheEntryCollection;
+  failedARecords: DnsCacheEntryCollection;
+  nextTimestampToUpdateMs: number;
+  updateRecords(addresses: HostAddress[], expirationTtlMs: number): void;
+  processRecords(): void;
+  failAddressInRecords(address: HostAddress): void;
+}
+export interface DnsCacheEntryCollection {
+  length: number;
+  cycle(collection?: DnsCacheEntryCollection): DnsCacheHostAddressEntry;
+  append(element: DnsCacheHostAddressEntry): void;
+  remove(element: DnsCacheHostAddressEntry): DnsCacheHostAddressEntry;
+  [Symbol.iterator](): Iterator<DnsCacheHostAddressEntry>;
+}
+export interface DnsCacheHostAddressEntry extends HostAddress {
+  expirationTtlMs: number;
+}

package/dist-types/ts3.4/NodeDnsLookupHostResolver.d.ts

@@ -3,8 +3,31 @@ import {
   HostResolver as IHostResolver,
   HostResolverArguments,
 } from "@aws-sdk/types";
+import { LookupAddress, LookupAllOptions } from "dns";
+import { DnsCache } from "./DnsCache";
+interface NodeDnsLookupFn {
+  (hostname: string, options: LookupAllOptions): Promise<LookupAddress[]>;
+}
+export interface NodeDnsLookupHostResolverConfig {
+  cache?: DnsCache;
+  ttlMs?: number;
+  nodeDnsLookup?: NodeDnsLookupFn;
+}
 export declare class NodeDnsLookupHostResolver implements IHostResolver {
+  private static DEFAULT_TTL_MS;
+  private static createDefaultCacheProvider;
+  private static DEFAULT_NODE_DNS_LOOKUP;
+  private ttlMs;
+  private cache;
+  private nodeDnsLookup;
+  constructor({
+    ttlMs,
+    cache,
+    nodeDnsLookup,
+  }?: NodeDnsLookupHostResolverConfig);
   resolveAddress(args: HostResolverArguments): Promise<HostAddress[]>;
   reportFailureOnAddress(addr: HostAddress): void;
   purgeCache(args?: HostResolverArguments): void;
+  private nodeDnsLookupResolveAddress;
 }
+export {};

package/dist-types/ts3.4/util/HostAddressEntryCollection.d.ts

@@ -0,0 +1,12 @@
+import { DnsCacheEntryCollection } from "../DnsCache";
+import { HostAddressEntry } from "./HostEntry";
+export declare class HostAddressEntryCollection
+  implements DnsCacheEntryCollection
+{
+  data: HostAddressEntry[];
+  readonly length: number;
+  cycle(collection?: HostAddressEntryCollection): HostAddressEntry;
+  append(entry: HostAddressEntry): void;
+  remove(entry: HostAddressEntry): HostAddressEntry;
+  [Symbol.iterator](): Iterator<HostAddressEntry>;
+}

package/dist-types/ts3.4/util/HostEntry.d.ts

@@ -0,0 +1,19 @@
+import { HostAddress } from "@aws-sdk/types";
+import { DnsCacheEntry, DnsCacheHostAddressEntry } from "../DnsCache";
+import { HostAddressEntryCollection } from "./HostAddressEntryCollection";
+export interface HostAddressEntry extends DnsCacheHostAddressEntry {}
+export declare class HostEntry implements DnsCacheEntry {
+  aaaaRecords: HostAddressEntryCollection;
+  aRecords: HostAddressEntryCollection;
+  failedAaaaRecords: HostAddressEntryCollection;
+  failedARecords: HostAddressEntryCollection;
+  nextTimestampToUpdateMs: number;
+  constructor(nextTimestampToProcessMs: number);
+  updateRecords(addresses: HostAddress[], expirationTtlMs: number): void;
+  processRecords(): void;
+  failAddressInRecords(address: HostAddress): void;
+  private findAddress;
+  private processRecordsAddressType;
+  private getGoodRecords;
+  private getFailedRecords;
+}

package/dist-types/ts3.4/util/HostEntryTable.d.ts

@@ -0,0 +1,16 @@
+import { HostAddress, HostResolverArguments } from "@aws-sdk/types";
+import { DnsCache } from "../DnsCache";
+import { HostEntry } from "./HostEntry";
+export declare class HostEntryTable implements DnsCache {
+  private map;
+  constructor();
+  set(
+    args: HostResolverArguments,
+    addresses: HostAddress[],
+    nextTimestampToProcessMs: number
+  ): void;
+  get(hostName: string): HostEntry | undefined;
+  delete(hostName: string): void;
+  clear(): void;
+  readonly size: number;
+}

package/dist-types/util/HostAddressEntryCollection.d.ts

@@ -0,0 +1,29 @@
+import { DnsCacheEntryCollection } from "../DnsCache";
+import { HostAddressEntry } from "./HostEntry";
+/**
+ * Collection using an Array as the underlying data structure
+ * @internal
+ */
+export declare class HostAddressEntryCollection implements DnsCacheEntryCollection {
+    data: HostAddressEntry[];
+    get length(): number;
+    /**
+     * Removes and appends the first entry to the end, e.g. 2 cycles:
+     * [A, B, C] -> [B, C, A] -> [C, A, B]
+     * @param collection optional collection to append the cycled entry to
+     * @returns entry cycled
+     */
+    cycle(collection?: HostAddressEntryCollection): HostAddressEntry;
+    /**
+     * Adds entry to the end of the collection.
+     * @param entry entry to add
+     */
+    append(entry: HostAddressEntry): void;
+    /**
+     * Removes an entry from the collection
+     * @param entry entry to remove
+     * @returns the removed entry
+     */
+    remove(entry: HostAddressEntry): HostAddressEntry;
+    [Symbol.iterator](): Iterator<HostAddressEntry>;
+}

package/dist-types/util/HostEntry.d.ts

@@ -0,0 +1,87 @@
+import { HostAddress } from "@aws-sdk/types";
+import { DnsCacheEntry, DnsCacheHostAddressEntry } from "../DnsCache";
+import { HostAddressEntryCollection } from "./HostAddressEntryCollection";
+/**
+ * Interface used in {@link HostEntry} records
+ * @internal
+ */
+export interface HostAddressEntry extends DnsCacheHostAddressEntry {
+}
+/**
+ * {@link DnsCacheEntry} implementation that uses {@link LinkedList} for
+ * {@link DnsCacheEntryCollection}.
+ * @internal
+ */
+export declare class HostEntry implements DnsCacheEntry {
+    /**
+     * {@link LinkedList} of good IPv6 records for an address
+     */
+    aaaaRecords: HostAddressEntryCollection;
+    /**
+     * {@link LinkedList} of good IPv4 records for an address
+     */
+    aRecords: HostAddressEntryCollection;
+    /**
+     * {@link LinkedList} of failed IPv6 records for an address
+     */
+    failedAaaaRecords: HostAddressEntryCollection;
+    /**
+     * {@link LinkedList} of failed IPv4 records for an address
+     */
+    failedARecords: HostAddressEntryCollection;
+    /**
+     * Timestamp for when to next process the entry
+     */
+    nextTimestampToUpdateMs: number;
+    constructor(nextTimestampToProcessMs: number);
+    /**
+     * Updates the entry given the new set of addresses and a new expiration
+     * timestamp:
+     * - If an address is already in the entry, the expiration timestamp is updated.
+     * - If an address is not in the entry, then it is added to the good records.
+     * @param addresses list of addresses used to update entry records
+     * @param expirationTtlMs expiration timestamp for new or updated addresses
+     * @see https://github.com/awslabs/aws-c-io/blob/f2ff573c191e1c4ea0248af5c08161356be3bc78/source/host_resolver.c#L703
+     */
+    updateRecords(addresses: HostAddress[], expirationTtlMs: number): void;
+    /**
+     * Removes expired records from records (except 1 in case of DNS outages).
+     * In the case that good records are empty, should attempt to promote 1
+     * non-expired failed address to the good records.
+     * Uses {@link processRecordsAddressType} for each {@link HostAddressType}
+     * @see https://github.com/awslabs/aws-c-io/blob/f2ff573c191e1c4ea0248af5c08161356be3bc78/source/host_resolver.c#L475
+     */
+    processRecords(): void;
+    /**
+     * Moves the address from good records to failed records
+     * @param address address to move to failed records
+     */
+    failAddressInRecords(address: HostAddress): void;
+    /**
+     * Find the corresponding {@link HostAddressEntry} for a {@link HostAddress} in
+     * a {@link HostEntry}'s records, or return undefined.
+     * @param address address to search for
+     * @returns host address entry if found, otherwise undefined
+     */
+    private findAddress;
+    /**
+     * Removes expired records from records (except 1 in case of DNS outages).
+     * In the case that good records are empty, should attempt to promote 1
+     * non-expired failed address to the good records.
+     * @param successRecords good records in cache to update
+     * @param failedRecords bad records in cache to update
+     */
+    private processRecordsAddressType;
+    /**
+     * Gets the good records for an address based on {@link HostAddressType}
+     * @param address address used to get the {@link HostAddressType}
+     * @returns good records for an address
+     */
+    private getGoodRecords;
+    /**
+     * Gets the failed records for an address based on {@link HostAddressType}
+     * @param address address used to get the {@link HostAddressType}
+     * @returns failed records for an address
+     */
+    private getFailedRecords;
+}

package/dist-types/util/HostEntryTable.d.ts

@@ -0,0 +1,41 @@
+import { HostAddress, HostResolverArguments } from "@aws-sdk/types";
+import { DnsCache } from "../DnsCache";
+import { HostEntry } from "./HostEntry";
+/**
+ * Host entry table which implements {@link DnsCache}, mapping:
+ * host name (string) -> {@link HostEntry}
+ * @internal
+ */
+export declare class HostEntryTable implements DnsCache {
+    /**
+     * Internal map as the host name level cache
+     */
+    private map;
+    constructor();
+    /**
+     * Maps a host name to a {@link HostEntry} in the cache, and uses
+     * {@link HostEntry.updateRecords} to initialize address records.
+     * @param args host resolver arguments which include host name
+     * @param addresses addresses to set into the cache entry
+     * @param nextTimestampToProcessMs timestamp for both cache entry processed and addresses' expiration
+     */
+    set(args: HostResolverArguments, addresses: HostAddress[], nextTimestampToProcessMs: number): void;
+    /**
+     * Gets the corresponding {@link HostEntry} for hostName, otherwise undefined
+     * @param hostName key to get cache entry
+     */
+    get(hostName: string): HostEntry | undefined;
+    /**
+     * Deletes the corresponding {@link HostEntry} for hostName
+     * @param hostName key to delete cache entry
+     */
+    delete(hostName: string): void;
+    /**
+     * Deletes all {@link HostEntry} mappings
+     */
+    clear(): void;
+    /**
+     * Gets the size of the cache
+     */
+    get size(): number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-sdk/util-dns",
-  "version": "3.271.0",
+  "version": "3.274.0",
   "description": "Implementations of DNS host resolvers.",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",
@@ -26,7 +26,7 @@
     "tslib": "^2.3.1"
   },
   "devDependencies": {
-    "@aws-sdk/types": "3.271.0",
+    "@aws-sdk/types": "3.272.0",
     "@tsconfig/recommended": "1.0.1",
     "@types/node": "^14.14.31",
     "concurrently": "7.0.0",