Lua library containing a dns client, several utilities, and a load-balancer.
The module is currently OpenResty only, and builds on top of the `lua-resty-dns` library
resolves A, AAAA, CNAME and SRV records, including port
caches dns query results in memory
synchronizes requests (a single request for many requestors, eg. when cached ttl expires under heavy load)
toipapplies a local (weighted) round-robin scheme on the query results
ring-balancer for round-robin and consistent-hashing approaches
Copyright and license
Copyright: (c) 2016-2018 Kong, Inc.
Author: Thijs Schreijer
License: Apache 2.0
Tests are executed using
busted, but because they run inside the
resty cli tool, you must use the
Versioning is strictly based on Semantic Versioning
2.2.0 (28-Aug-2018) Fixes and a new option
Added: a new option
validTtlthat, if set, will forcefully override the
ttlvalue of any valid answer received. Issue 48.
Fix: remove multiline log entries, now encoded as single-line json. Issue 52.
Fix: always inject a
localhostvalue, even if not in
/etc/hosts. Issue 54.
Fix: added a workaround for Amazon Route 53 nameservers replying with a
ttl=0whilst the record has a non-0 ttl. Issue 56.
2.1.0 (21-May-2018) Fixes
Fix: the round robin scheme for the balanceer starts at a randomized position to prevent all workers from starting with the same peer.
Fix: the balancer no longer returns
port = 0for SRV records without a port, the default port is now returned.
Fix: ipv6 nameservers with a scope in their address are not supported. This fix will simply skip them instead of throwing errors upon resolving. Fixes issue 43.
Minor: improved logging in the balancer
Minor: relax requery default interval for failed dns queries from 1 to 30 seconds.
2.0.0 (22-Feb-2018) Major performance improvement (balancer) and bugfixes
BREAKING: improved performance and memory footprint for large balancers. 80-85% less memory will be used, while creation time dropped by 85-90%. Since the
host:getPeer()function signature changed, this is a breaking change.
Change: BREAKING the errors for cache-only lookup failures and empty records have been changed.
Fix: do not fail initialization without nameservers.
Fix: properly recognize IPv6 in square brackets from the /etc/hosts file.
Fix: do not set success-type to types we're not looking for. Fixes Kong issue #3210.
Fix: store records from the additional section in cache
Fix: do not overwrite stale data in the client cache with empty records
1.0.0 (14-Dec-2017) Fixes and IPv6
Change: BREAKING all IPv6 addresses are now returned with square brackets
Fix: properly recognize IPv6 addresses in square brackets
0.6.3 (27-Nov-2017) Fixes and flagging unhealthy peers
Added: flag to mark an address as failed/unhealthy, see
Added: callback to receive balancer updates; addresses added-to/removed-from the balancer (after DNS updates for example).
fix: SRV record entries with a weight 0 are now supported
fix: failure of the last hostname to resolve (balancer)
0.6.2 (04-Sep-2017) Fixes and refactor
Fix: balancer not returning hostname for named SRV entries. See issue #17
Fix: fix an occasionally failing test
Refactor: remove metadata from the records, instead store it in its own cache
0.6.1 (28-Jul-2017) Randomization adjusted
Change: use a different randomizer for the ring-balancer to predictably recreate the balancer in the exact same state (adds the
lrandomlibrary as a new dependency)
0.6.0 (14-Jun-2017) Rewritten resolver core to resolve async
Added: resolution will be done async whenever possible. For this to work a new setting has been introduced
staleTtlwhich determines for how long stale records will returned while a query is in progress in the background.
Change: BREAKING! several functions that previously returned and took a resolver object no longer do so.
Fix: no longer lookup ip adresses as names if the query type is not A or AAAA
Fix: normalize names to lowercase after query
Fix: set last-success types for hosts-file entries and ip-addresses
0.5.0 (25-Apr-2017) implement SEARCH and NDOTS
Removed: BREAKING! stdError function removed.
Added: implemented the
resolveno longer returns empty results or dns errors as a table but as lua errors (
nil + error).
resolve()have an extra result; history. A table with the list of tried names/types/results.
Fix: timeout and retrans options from
resolv.confwere ignored by the
Fix: nameservers with an ipv6 address would not be used properly. Also added a flag
false) to enable the useage of ipv6 nameservers.
0.4.1 (21-Apr-2017) Bugfix
Fix: cname record caching causing excessive dns queries, see Kong issue #2303.
0.4.0 (30-Mar-2017) Bugfixes
Change: BREAKING! modified hash treatment, must now be an integer > 0
Added: BREAKING! a retry counter to fall-through on hashed-retries (changes the
Fix: the MAXNS (3) was not honoured, so more than 3 nameservers would be parsed from the
resolv.conffile. Fixes Kong issue #2290.
Added: two convenience hash functions
Performance: some improvements (pre-allocated tables for the slot lists)
0.3.2 (6-Mar-2017) Bugfixes
Fix: Cleanup disabled addresses but did not delete them, causing errors when they were repeatedly added/removed
Fix: potential racecondition when re-querying dns records
Fix: potential memoryleak when a balancer object was released with a running timer
0.3.1 (22-Feb-2017) Bugfixes
Kubernetes dns returns an SRV record for individual nodes, where the target is the same name again (hence causing a recursive loop). Now those entries will be removed, and if nothing is left, it will fail the SRV lookup, causing a fall-through to the next record type.
Kubernetes tends to return a port of 0 if none is provided/set, hence the
toip()function now ignores a
port=0and falls back on the port passed in.
0.3.0 (8-Nov-2016) Major breaking update
breaking: renamed a lot of things; method names, module names, etc. pretty much breaks everything... also releasing under a new name
feature: udp function
fix: do not synchronize dns queries for ttl=0 requests (client)
fix: full test coverage and accompanying fixes (ring-balancer)
feature: auto-retry for failed dns queries (ring-balancer)
feature: updating weights is now supported without removing/re-adding (ring-balancer)
change: auto-retry interval configurable for failed dns queries (ring-balancer)
change: max life-time interval configurable for ttl=0 dns records (ring-balancer)
0.2.1 (24-Oct-2016) Bugfix
toip()failed on SRV records with only 1 entry
0.2 (18-Oct-2016) Added the balancer
fix: was creating resolver objects even if serving from cache
change: change resolver order (SRV is now first by default) for dns servers that create both SRV and A records for each entry
feature: make resolver order configurable
feature: ring-balancer (experimental, no full test coverage yet)
other: more test coverage for the dns client
0.1 (09-Sep-2016) Initial released version
lua-resty-dns-client-2.2.0 2019-04-16 11:03:02