Skip to content

Commit

Permalink
prepare for release 3.2
Browse files Browse the repository at this point in the history
  • Loading branch information
@Tieske
Tieske committed Mar 7, 2017
1 parent 552ed0e commit 9a9fe65
Show file tree
Hide file tree
Showing 7 changed files with 155 additions and 115 deletions.
9 changes: 8 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,14 @@ use the `rbusted` script.
History
=======

###0.3.1 (22-Feb-2017) Bugfix
###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
Expand Down
2 changes: 1 addition & 1 deletion docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ <h2>Topics</h2>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2017-02-22 13:40:23 </i>
<i style="float:right;">Last updated 2017-03-06 15:17:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
57 changes: 28 additions & 29 deletions docs/modules/resty.dns.balancer.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ <h1>Module <code>resty.dns.balancer</code></h1>
target, only then the check is done whether the record is stale, and if so
it is updated. The one exception is the failed dns queries (because they
have no slots assigned, and hence will never be hit by <a href="../modules/resty.dns.balancer.html#getPeer">getPeer</a>), which will
be actively refreshed using a timer. </p>
be actively refreshed using a timer.</p>

<p> Whenever dns resolution fails for a hostname, the host will relinguish all
the slots it owns, and they will be reassigned to other targets.
Expand Down Expand Up @@ -149,7 +149,7 @@ <h2 class="section-header "><a name="Functions"></a>Functions</h2>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">hostname</span>
hostname to add (note: not validated, as long as it's a
hostname to add (note: not validated, as long as it&rsquo;s a
string it will be accepted, but remain unresolved!)
</li>
<li><span class="parameter">port</span>
Expand Down Expand Up @@ -214,8 +214,7 @@ <h3>Returns:</h3>
<strong>new (opts)</strong>
</dt>
<dd>

<p>Creates a new balancer. The balancer is based on a wheel with slots. The
<p>Creates a new balancer. The balancer is based on a wheel with slots. The
slots will be randomly distributed over the targets. The number of slots
assigned will be relative to the weight.</p>

Expand All @@ -226,30 +225,30 @@ <h3>Returns:</h3>
<p> The options table has the following fields;</p>

<ul>
<li><code>hosts</code> (optional) containing hostnames, ports and weights. If omitted,
ports and weights default respectively to 80 and 10. The list will be sorted
before being added, so the order of entry is deterministic.</li>
<li><code>wheelSize</code> (optional) for total number of slots in the balancer, if omitted
the size of <code>order</code> is used, or 1000 if <code>order</code> is not provided. It is important
to have enough slots to keep the ring properly randomly distributed. If there
are to few slots for the number of targets then the load distribution might
become to coarse. Consider the maximum number of targets expected, as new
hosts can be dynamically added, and dns renewals might yield larger record
sets. The <code>wheelSize</code> cannot be altered, only a new wheel can be created, but
then all consistency would be lost. On a similar note; making it too big,
will have a performance impact when the wheel is modified as too many slots
will have to be moved between targets. A value of 50 to 200 slots per entry
seems about right.</li>
<li><code>order</code> (optional) if given, a list of random numbers, size <code>wheelSize</code>, used to
randomize the wheel. This entry is solely to support multiple servers with
the same consistency, as it allows to use the same randomization on each
server, and hence the same slot assignment. Duplicates are not allowed in
the list.</li>
<li><code>dns</code> (required) a configured <a href="../modules/resty.dns.client.html">dns.client</a> object for querying the dns server.</li>
<li><code>requery</code> (optional) interval of requerying the dns server for previously
failed queries. Defaults to 1 if omitted (in seconds)</li>
<li><code>ttl0</code> (optional) Maximum lifetime for records inserted with ttl=0, to verify
the ttl is still 0. Defaults to 60 if omitted (in seconds)</li>
<li><code>hosts</code> (optional) containing hostnames, ports and weights. If omitted,
ports and weights default respectively to 80 and 10. The list will be sorted
before being added, so the order of entry is deterministic.</li>
<li><code>wheelSize</code> (optional) for total number of slots in the balancer, if omitted
the size of <code>order</code> is used, or 1000 if <code>order</code> is not provided. It is important
to have enough slots to keep the ring properly randomly distributed. If there
are to few slots for the number of targets then the load distribution might
become to coarse. Consider the maximum number of targets expected, as new
hosts can be dynamically added, and dns renewals might yield larger record
sets. The <code>wheelSize</code> cannot be altered, only a new wheel can be created, but
then all consistency would be lost. On a similar note; making it too big,
will have a performance impact when the wheel is modified as too many slots
will have to be moved between targets. A value of 50 to 200 slots per entry
seems about right.</li>
<li><code>order</code> (optional) if given, a list of random numbers, size <code>wheelSize</code>, used to
randomize the wheel. This entry is solely to support multiple servers with
the same consistency, as it allows to use the same randomization on each
server, and hence the same slot assignment. Duplicates are not allowed in
the list.</li>
<li><code>dns</code> (required) a configured <a href="../modules/resty.dns.client.html">dns.client</a> object for querying the dns server.</li>
<li><code>requery</code> (optional) interval of requerying the dns server for previously
failed queries. Defaults to 1 if omitted (in seconds)</li>
<li><code>ttl0</code> (optional) Maximum lifetime for records inserted with ttl=0, to verify
the ttl is still 0. Defaults to 60 if omitted (in seconds)</li>
</ul>


Expand Down Expand Up @@ -320,7 +319,7 @@ <h3>Returns:</h3>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2017-02-22 13:40:23 </i>
<i style="float:right;">Last updated 2017-03-06 15:17:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
86 changes: 41 additions & 45 deletions docs/modules/resty.dns.client.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,23 +55,20 @@ <h2>Topics</h2>

<h1>Module <code>resty.dns.client</code></h1>
<p>DNS client.</p>
<p>
<p><p> Works with OpenResty only. Requires the <a href="https://github.com/openresty/lua-resty-dns"><code>lua-resty-dns</code></a> module.</p>


<p> Works with OpenResty only. Requires the <a href="https://github.com/openresty/lua-resty-dns"><code>lua-resty-dns</code></a> module.</p>

<p> <em>NOTES</em>: </p>
<p> <em>NOTES</em>:</p>

<ol>
<li>parsing the config files upon initialization uses blocking i/o, so use with
care. See <a href="../modules/resty.dns.client.html#init">init</a> for details.</li>
<li>All returned records are directly from the cache. <em>So do not modify them!</em>
If you need to, copy them first.</li>
<li>TTL for records is the TTL returned by the server at the time of fetching
and won't be updated while the client serves the records from its cache.</li>
<li>resolving IPv4 (A-type) and IPv6 (AAAA-type) addresses is explicitly supported. If
the hostname to be resolved is a valid IP address, it will be cached with a ttl of
10 years. So the user doesn't have to check for ip adresses.</li>
<li>parsing the config files upon initialization uses blocking i/o, so use with
care. See <a href="../modules/resty.dns.client.html#init">init</a> for details.</li>
<li>All returned records are directly from the cache. <em>So do not modify them!</em>
If you need to, copy them first.</li>
<li>TTL for records is the TTL returned by the server at the time of fetching
and won&rsquo;t be updated while the client serves the records from its cache.</li>
<li>resolving IPv4 (A-type) and IPv6 (AAAA-type) addresses is explicitly supported. If
the hostname to be resolved is a valid IP address, it will be cached with a ttl of
10 years. So the user doesn&rsquo;t have to check for ip adresses.</li>
</ol>
</p>
<h3>Info:</h3>
Expand Down Expand Up @@ -141,7 +138,7 @@ <h2 class="section-header has-description"><a name="Caching"></a>Caching </h2>
Cleanup the DNS client cache. Items will be checked on TTL only upon
retrieval from the cache. So items inserted, but never used again will
never be removed from the cache automatically. So unless you have a very
restricted fixed set of hostnames you're resolving, you should occasionally
restricted fixed set of hostnames you&rsquo;re resolving, you should occasionally
purge the cache.


Expand Down Expand Up @@ -250,8 +247,7 @@ <h3>Usage:</h3>
<strong>resolve (qname, r_opts, dnsCacheOnly, r)</strong>
</dt>
<dd>

<p>Resolve a name. <br/>
<p>Resolve a name.<br/>
If <code>r_opts.qtype</code> is given, then it will fetch that specific type only. If
<code>r_opts.qtype</code> is not provided, then it will try to resolve
the name using the record types, in the order as provided to <a href="../modules/resty.dns.client.html#init">init</a>.</p>
Expand All @@ -263,24 +259,24 @@ <h3>Usage:</h3>
it (the first time) as;</p>

<ul>
<li>SRV, </li>
<li>then A, </li>
<li>then AAAA (success),</li>
<li>then CNAME (after AAAA success, this will not be tried)</li>
<li>SRV,</li>
<li>then A,</li>
<li>then AAAA (success),</li>
<li>then CNAME (after AAAA success, this will not be tried)</li>
</ul>


<p> A second lookup will now try (assuming the cached entry expired);</p>

<ul>
<li>AAAA (as it was the last successful lookup),</li>
<li>then SRV, </li>
<li>then A,</li>
<li>then CNAME.</li>
<li>AAAA (as it was the last successful lookup),</li>
<li>then SRV,</li>
<li>then A,</li>
<li>then CNAME.</li>
</ul>




<h3>Parameters:</h3>
<ul>
<li><span class="parameter">qname</span>
Expand All @@ -291,7 +287,7 @@ <h3>Parameters:</h3>
<a href="https://github.com/openresty/lua-resty-dns">OpenResty docs</a> for more options.
</li>
<li><span class="parameter">dnsCacheOnly</span>
Only check the cache, won't do server lookups
Only check the cache, won&rsquo;t do server lookups
(will not invalidate any ttl expired data and will hence possibly return
expired data)
</li>
Expand Down Expand Up @@ -325,7 +321,7 @@ <h3>Returns:</h3>
A server error table is returned as <code>nil+error+r</code> (where <a href="https://www.lua.org/manual/5.1/manual.html#pdf-error">error</a> is a string
extracted from the server error table).
An empty response is returned as <code>response+error+r</code> (where <a href="https://www.lua.org/manual/5.1/manual.html#pdf-error">error</a> is
'dns query returned no results').
&lsquo;dns query returned no results&rsquo;).



Expand All @@ -351,8 +347,7 @@ <h3>Usage:</h3>
<strong>toip (qname, port, dnsCacheOnly, r)</strong>
</dt>
<dd>

<p>Resolves to an IP and port number.
<p>Resolves to an IP and port number.
Builds on top of <a href="../modules/resty.dns.client.html#resolve">resolve</a>, but will also further dereference SRV type records.</p>

<p> When calling multiple times on cached records, it will apply load-balancing
Expand All @@ -363,34 +358,35 @@ <h3>Usage:</h3>

<p> <strong>Example</strong>;</p>

<p> SRV record for "my.domain.com", containing 2 entries (this is the 1st level);</p>
<p> SRV record for &ldquo;my.domain.com&rdquo;, containing 2 entries (this is the 1st level);</p>

<ul>
<li><code>target = 127.0.0.1, port = 80, weight = 10</code></li>
<li><code>target = &quot;other.domain.com&quot;, port = 8080, weight = 5</code></li>
<li> <code>target = 127.0.0.1, port = 80, weight = 10</code></li>
<li> <code>target = &quot;other.domain.com&quot;, port = 8080, weight = 5</code></li>
</ul>

<p> A record for "other.domain.com", containing 2 entries (this is the 2nd level);</p>

<p> A record for &ldquo;other.domain.com&rdquo;, containing 2 entries (this is the 2nd level);</p>

<ul>
<li><code>ip = 127.0.0.2</code></li>
<li><code>ip = 127.0.0.3</code></li>
<li> <code>ip = 127.0.0.2</code></li>
<li> <code>ip = 127.0.0.3</code></li>
</ul>


<p> Now calling <code>local ip, port = toip(&quot;my.domain.com&quot;, 123)</code> in a row 6 times will result in;</p>

<ul>
<li><code>127.0.0.1, 80</code></li>
<li><code>127.0.0.2, 8080</code> (port from SRV, 1st IP from A record)</li>
<li><code>127.0.0.1, 80</code> (completes WRR 1st level, 1st run)</li>
<li><code>127.0.0.3, 8080</code> (port from SRV, 2nd IP from A record, completes RR 2nd level)</li>
<li><code>127.0.0.1, 80</code></li>
<li><code>127.0.0.1, 80</code> (completes WRR 1st level, 2nd run, with different order as WRR is randomized)</li>
<li> <code>127.0.0.1, 80</code></li>
<li> <code>127.0.0.2, 8080</code> (port from SRV, 1st IP from A record)</li>
<li> <code>127.0.0.1, 80</code> (completes WRR 1st level, 1st run)</li>
<li> <code>127.0.0.3, 8080</code> (port from SRV, 2nd IP from A record, completes RR 2nd level)</li>
<li> <code>127.0.0.1, 80</code></li>
<li> <code>127.0.0.1, 80</code> (completes WRR 1st level, 2nd run, with different order as WRR is randomized)</li>
</ul>




<h3>Parameters:</h3>
<ul>
<li><span class="parameter">qname</span>
Expand All @@ -401,7 +397,7 @@ <h3>Parameters:</h3>
the lookup chain (only SRV records carry port information, SRV with <code>port=0</code> will be ignored)
</li>
<li><span class="parameter">dnsCacheOnly</span>
Only check the cache, won't do server lookups (will
Only check the cache, won&rsquo;t do server lookups (will
not invalidate any ttl expired data and will hence possibly return expired data)
</li>
<li><span class="parameter">r</span>
Expand Down Expand Up @@ -504,7 +500,7 @@ <h3>Returns:</h3>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2017-02-22 13:40:23 </i>
<i style="float:right;">Last updated 2017-03-06 15:17:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
6 changes: 2 additions & 4 deletions docs/modules/resty.dns.utils.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,8 @@ <h2>Topics</h2>

<h1>Module <code>resty.dns.utils</code></h1>
<p>DNS utility module.</p>
<p> </p>

<p> Parses the <code>/etc/hosts</code> and <code>/etc/resolv.conf</code> configuration files, caches them,
and provides some utility functions. </p>
and provides some utility functions.</p>

<p> <em>NOTE</em>: parsing the files is done using blocking i/o file operations.</p>
<h3>Info:</h3>
Expand Down Expand Up @@ -403,7 +401,7 @@ <h3>Usage:</h3>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2017-02-22 13:40:23 </i>
<i style="float:right;">Last updated 2017-03-06 15:17:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
Loading

0 comments on commit 9a9fe65

Please sign in to comment.