Software zum Installieren eines Smart-Mirror Frameworks , zum Nutzen von hochschulrelevanten Informationen, auf einem Raspberry-Pi.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 7.5KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. # cacheable-lookup
  2. > A cacheable [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) that respects TTL :tada:
  3. [![Node CI](https://github.com/szmarczak/cacheable-lookup/workflows/Node%20CI/badge.svg)](https://github.com/szmarczak/cacheable-lookup/actions)
  4. [![Coverage Status](https://coveralls.io/repos/github/szmarczak/cacheable-lookup/badge.svg?branch=master)](https://coveralls.io/github/szmarczak/cacheable-lookup?branch=master)
  5. [![npm](https://img.shields.io/npm/dm/cacheable-lookup.svg)](https://www.npmjs.com/package/cacheable-lookup)
  6. [![install size](https://packagephobia.now.sh/badge?p=cacheable-lookup)](https://packagephobia.now.sh/result?p=cacheable-lookup)
  7. Making lots of HTTP requests? You can save some time by caching DNS lookups :zap:
  8. ## Usage
  9. ### Using the `lookup` option
  10. ```js
  11. const http = require('http');
  12. const CacheableLookup = require('cacheable-lookup');
  13. const cacheable = new CacheableLookup();
  14. http.get('http://example.com', {lookup: cacheable.lookup}, response => {
  15. // Handle the response here
  16. });
  17. ```
  18. ### Attaching CacheableLookup to an Agent
  19. ```js
  20. const http = require('http');
  21. const CacheableLookup = require('cacheable-lookup');
  22. const cacheable = new CacheableLookup();
  23. cacheable.install(http.globalAgent);
  24. http.get('http://example.com', response => {
  25. // Handle the response here
  26. });
  27. ```
  28. ## API
  29. ### new CacheableLookup(options)
  30. Returns a new instance of `CacheableLookup`.
  31. #### options
  32. Type: `object`<br>
  33. Default: `{}`
  34. Options used to cache the DNS lookups.
  35. ##### cache
  36. Type: `Map` | [`Keyv`](https://github.com/lukechilds/keyv/)<br>
  37. Default: `new Map()`
  38. Custom cache instance. If `undefined`, it will create a new one.
  39. **Note**: If you decide to use Keyv instead of the native implementation, the performance will drop by 10x. Memory leaks may occur as it doesn't provide any way to remove all the deprecated values at once.
  40. **Tip**: [`QuickLRU`](https://github.com/sindresorhus/quick-lru) is fully compatible with the Map API, you can use it to limit the amount of cached entries. Example:
  41. ```js
  42. const http = require('http');
  43. const CacheableLookup = require('cacheable-lookup');
  44. const QuickLRU = require('quick-lru');
  45. const cacheable = new CacheableLookup({
  46. cache: new QuickLRU({maxSize: 1000})
  47. });
  48. http.get('http://example.com', {lookup: cacheable.lookup}, response => {
  49. // Handle the response here
  50. });
  51. ```
  52. ##### options.maxTtl
  53. Type: `number`<br>
  54. Default: `Infinity`
  55. The maximum lifetime of the entries received from the specifed DNS server (TTL in seconds).
  56. If set to `0`, it will make a new DNS query each time.
  57. **Pro Tip**: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than `0.01`.
  58. ##### options.fallbackDuration
  59. Type: `number`<br>
  60. Default: `3600` (1 hour)
  61. When the DNS server responds with `ENOTFOUND` or `ENODATA` and the OS reports that the entry is available, it will use `dns.lookup(...)` directly for the requested hostnames for the specified amount of time (in seconds).
  62. If you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this value to `0`.
  63. ##### options.errorTtl
  64. Type: `number`<br>
  65. Default: `0.15`
  66. The time how long it needs to remember queries that threw `ENOTFOUND` or `ENODATA` (TTL in seconds).
  67. **Note**: This option is independent, `options.maxTtl` does not affect this.
  68. **Pro Tip**: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than `0.01`.
  69. ##### options.resolver
  70. Type: `dns.Resolver | dns.promises.Resolver`<br>
  71. Default: [`new dns.promises.Resolver()`](https://nodejs.org/api/dns.html#dns_class_dns_resolver)
  72. An instance of [DNS Resolver](https://nodejs.org/api/dns.html#dns_class_dns_resolver) used to make DNS queries.
  73. ##### options.lookup
  74. Type: `Function`<br>
  75. Default: [`dns.lookup`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)
  76. The fallback function to use when the DNS server responds with `ENOTFOUND` or `ENODATA`.
  77. **Note**: This has no effect if the `fallbackDuration` option is less than `1`.
  78. ### Entry object
  79. Type: `object`
  80. #### address
  81. Type: `string`
  82. The IP address (can be an IPv4 or IPv6 address).
  83. #### family
  84. Type: `number`
  85. The IP family (`4` or `6`).
  86. ##### expires
  87. Type: `number`
  88. **Note**: This is not present when falling back to `dns.lookup(...)`!
  89. The timestamp (`Date.now() + ttl * 1000`) when the entry expires.
  90. #### ttl
  91. **Note**: This is not present when falling back to `dns.lookup(...)`!
  92. The time in seconds for its lifetime.
  93. ### Entry object (callback-style)
  94. When `options.all` is `false`, then `callback(error, address, family, expires, ttl)` is called. <br>
  95. When `options.all` is `true`, then `callback(error, entries)` is called.
  96. ### CacheableLookup instance
  97. #### servers
  98. Type: `Array`
  99. The DNS servers used to make queries. Can be overridden - doing so will clear the cache.
  100. #### [lookup(hostname, options, callback)](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)
  101. #### lookupAsync(hostname, options)
  102. The asynchronous version of `dns.lookup(…)`.
  103. Returns an [entry object](#entry-object).<br>
  104. If `options.all` is true, returns an array of entry objects.
  105. ##### hostname
  106. Type: `string`
  107. ##### options
  108. Type: `object`
  109. The same as the [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) options.
  110. #### query(hostname)
  111. An asynchronous function which returns cached DNS lookup entries.<br>
  112. This is the base for `lookupAsync(hostname, options)` and `lookup(hostname, options, callback)`.
  113. **Note**: This function has no options.
  114. Returns an array of objects with `address`, `family`, `ttl` and `expires` properties.
  115. #### queryAndCache(hostname)
  116. An asynchronous function which makes two DNS queries: A and AAAA. The result is cached.<br>
  117. This is used by `query(hostname)` if no entry in the database is present.
  118. Returns an array of objects with `address`, `family`, `ttl` and `expires` properties.
  119. #### updateInterfaceInfo()
  120. Updates interface info. For example, you need to run this when you plug or unplug your WiFi driver.
  121. **Note:** Running `updateInterfaceInfo()` will trigger `clear()` only on network interface removal.
  122. #### clear(hostname?)
  123. Clears the cache for the given hostname. If the hostname argument is not present, the entire cache will be emptied.
  124. ## High performance
  125. Performed on:
  126. - Query: `example.com`
  127. - CPU: i7-7700k
  128. - CPU governor: performance
  129. ```
  130. CacheableLookup#lookupAsync x 2,896,251 ops/sec ±1.07% (85 runs sampled)
  131. CacheableLookup#lookupAsync.all x 2,842,664 ops/sec ±1.11% (88 runs sampled)
  132. CacheableLookup#lookupAsync.all.ADDRCONFIG x 2,598,283 ops/sec ±1.21% (88 runs sampled)
  133. CacheableLookup#lookup x 2,565,913 ops/sec ±1.56% (85 runs sampled)
  134. CacheableLookup#lookup.all x 2,609,039 ops/sec ±1.01% (86 runs sampled)
  135. CacheableLookup#lookup.all.ADDRCONFIG x 2,416,242 ops/sec ±0.89% (85 runs sampled)
  136. dns#lookup x 7,272 ops/sec ±0.36% (86 runs sampled)
  137. dns#lookup.all x 7,249 ops/sec ±0.40% (86 runs sampled)
  138. dns#lookup.all.ADDRCONFIG x 5,693 ops/sec ±0.28% (85 runs sampled)
  139. Fastest is CacheableLookup#lookupAsync.all
  140. ```
  141. ## Related
  142. - [cacheable-request](https://github.com/lukechilds/cacheable-request) - Wrap native HTTP requests with RFC compliant cache support
  143. ## License
  144. MIT