Skip to content

Commit

Permalink
release 3.1.0 (#163)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bungle
bungle authored Jun 19, 2024
1 parent 3da3591 commit ab2efa7
Show file tree
Hide file tree
Showing 4 changed files with 278 additions and 214 deletions.
4 changes: 4 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,10 @@ Versioning is strictly based on [Semantic Versioning](https://semver.org/)
* push commit and tag
* upload rock to luarocks: `luarocks upload rockspecs/[name] --api-key=abc`

### 3.1.0 (19-Jun-2024)

* Feat: remove version check of resty.events [#162](https://github.com/Kong/lua-resty-healthcheck/pull/162)

### 3.0.2 (16-May-2024)

* Fix: avoid creating multiple timers to run the same active check [#157](https://github.com/Kong/lua-resty-healthcheck/pull/157)
Expand Down
128 changes: 63 additions & 65 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,25 +53,23 @@ <h2>Topics</h2>

<h1>Module <code>resty.healthcheck</code></h1>
<p>Healthcheck library for OpenResty.</p>
<p>


<p> Some notes on the usage of this library:</p>
<p><p> Some notes on the usage of this library:</p>

<ul>
<li><p>Each target will have 4 counters, 1 success counter and 3 failure
counters ('http', 'tcp', and 'timeout'). Any failure will <em>only</em> reset the
success counter, but a success will reset <em>all three</em> failure counters.</p></li>
<li><p>All targets are uniquely identified by their IP address and port number
combination, most functions take those as arguments.</p></li>
<li><p>All keys in the SHM will be namespaced by the healthchecker name as
provided to the <a href="index.html#new">new</a> function. Hence no collissions will occur on shm-keys
as long as the <code>name</code> is unique.</p></li>
<li><p>Active healthchecks will be synchronized across workers, such that only
a single active healthcheck runs.</p></li>
<li><p>Events will be raised in every worker, see <a href="https://github.com/Kong/lua-resty-worker-events">lua-resty-worker-events</a>
for details.</p></li>
<li><p>Each target will have 4 counters, 1 success counter and 3 failure
counters (&lsquo;http&rsquo;, &lsquo;tcp&rsquo;, and &lsquo;timeout&rsquo;). Any failure will <em>only</em> reset the
success counter, but a success will reset <em>all three</em> failure counters.</p></li>
<li><p>All targets are uniquely identified by their IP address and port number
combination, most functions take those as arguments.</p></li>
<li><p>All keys in the SHM will be namespaced by the healthchecker name as
provided to the <a href="index.html#new">new</a> function. Hence no collissions will occur on shm-keys
as long as the <code>name</code> is unique.</p></li>
<li><p>Active healthchecks will be synchronized across workers, such that only
a single active healthcheck runs.</p></li>
<li><p>Events will be raised in every worker, see <a href="https://github.com/Kong/lua-resty-worker-events">lua-resty-worker-events</a>
for details.</p></li>
</ul>

</p>
<h3>Info:</h3>
<ul>
Expand All @@ -87,7 +85,7 @@ <h2><a href="#Functions">Functions</a></h2>
<td class="name" nowrap><a href="#run_locked">run_locked (self, key, fn, ...)</a></td>
<td class="summary">Acquire a lock and run a function</p>

<p> The function call itself is wrapped with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-pcall">pcall</a> to protect against
<p> The function call itself is wrapped with <a href="https://www.lua.org/manual/5.1/manual.html#pdf-pcall">pcall</a> to protect against
exception.</td>
</tr>
</table>
Expand Down Expand Up @@ -180,21 +178,20 @@ <h2 class="section-header "><a name="Functions"></a>Functions</h2>
<strong>run_locked (self, key, fn, ...)</strong>
</dt>
<dd>
<p>Acquire a lock and run a function</p>

<p>Acquire a lock and run a function</p>

<p> The function call itself is wrapped with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-pcall">pcall</a> to protect against
<p> The function call itself is wrapped with <a href="https://www.lua.org/manual/5.1/manual.html#pdf-pcall">pcall</a> to protect against
exception. </p>

<p> This function exhibits some special behavior when called during a
non-yieldable phase such as <code>init_worker</code> or <code>log</code>:</p>

<ol>
<li>The lock timeout is set to 0 to ensure that <code>resty.lock</code> does not
attempt to sleep/yield</li>
<li>If acquiring the lock fails due to a timeout, <a href="index.html#run_locked">run_locked</a>
(this function) is re-scheduled to run in a timer. In this case,
the function returns <code>&quot;scheduled&quot;</code></li>
<li>The lock timeout is set to 0 to ensure that <code>resty.lock</code> does not
attempt to sleep/yield</li>
<li>If acquiring the lock fails due to a timeout, <a href="index.html#run_locked">run_locked</a>
(this function) is re-scheduled to run in a timer. In this case,
the function returns <code>&quot;scheduled&quot;</code></li>
</ol>


Expand Down Expand Up @@ -258,12 +255,12 @@ <h3>Fields:</h3>
</li>
<li><span class="parameter">mostly_healthy</span>
This event is raised when the target status is
still healthy but it started to receive "unhealthy" updates via active or
still healthy but it started to receive &ldquo;unhealthy&rdquo; updates via active or
passive checks.
</li>
<li><span class="parameter">mostly_unhealthy</span>
This event is raised when the target status is
still unhealthy but it started to receive "healthy" updates via active or
still unhealthy but it started to receive &ldquo;healthy&rdquo; updates via active or
passive checks.
</li>
</ul>
Expand Down Expand Up @@ -459,8 +456,8 @@ <h2 class="section-header has-description"><a name="Health_management"></a>Healt
<dd>
Report a health failure.
Reports a health failure which will count against the number of occurrences
required to make a target "fall". The type of healthchecker,
"tcp" or "http" (see <a href="index.html#new">new</a>) determines against which counter the occurence goes.
required to make a target &ldquo;fall&rdquo;. The type of healthchecker,
&ldquo;tcp&rdquo; or &ldquo;http&rdquo; (see <a href="index.html#new">new</a>) determines against which counter the occurence goes.
If <code>unhealthy.tcp_failures</code> (for TCP failures) or <code>unhealthy.http_failures</code>
is set to zero in the configuration, this function is a no-op
and returns <code>true</code>.
Expand All @@ -478,7 +475,7 @@ <h3>Parameters:</h3>
(optional) hostname of the target being checked.
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either "passive" or "active", default "passive".
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
</li>
</ul>

Expand Down Expand Up @@ -521,7 +518,7 @@ <h3>Parameters:</h3>
the http statuscode, or nil to report an invalid http response.
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either "passive" or "active", default "passive".
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
</li>
</ul>

Expand All @@ -543,7 +540,7 @@ <h3>Returns:</h3>
<dd>
Report a health success.
Reports a health success which will count against the number of occurrences
required to make a target "rise".
required to make a target &ldquo;rise&rdquo;.
If <code>healthy.successes</code> is set to zero in the configuration,
this function is a no-op and returns <code>true</code>.

Expand All @@ -560,7 +557,7 @@ <h3>Parameters:</h3>
(optional) hostname of the target being checked.
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either "passive" or "active", default "passive".
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
</li>
</ul>

Expand Down Expand Up @@ -597,13 +594,13 @@ <h3>Parameters:</h3>
</li>
<li><span class="parameter">operation</span>
The socket operation that failed:
"connect", "send" or "receive".
&ldquo;connect&rdquo;, &ldquo;send&rdquo; or &ldquo;receive&rdquo;.
TODO check what kind of information we get from the OpenResty layer
in order to tell these error conditions apart
https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md#get<em>last</em>failure
https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md#get_last_failure
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either "passive" or "active", default "passive".
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
</li>
</ul>

Expand Down Expand Up @@ -639,7 +636,7 @@ <h3>Parameters:</h3>
(optional) hostname of the target being checked.
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either "passive" or "active", default "passive".
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
</li>
</ul>

Expand Down Expand Up @@ -772,7 +769,7 @@ <h3>Returns:</h3>
It will be started upon creation.</p>

<p> <em>NOTE</em>: the returned <code>checker</code> object must be anchored, if not it will be
removed by Lua's garbage collector and the healthchecks will cease to run.
removed by Lua&rsquo;s garbage collector and the healthchecks will cease to run.


<h3>Parameters:</h3>
Expand All @@ -781,34 +778,35 @@ <h3>Parameters:</h3>
table with checker options. Options are:</p>

<ul>
<li><code>name</code>: name of the health checker</li>
<li><code>shm_name</code>: the name of the <code>lua_shared_dict</code> specified in the Nginx configuration to use</li>
<li><code>ssl_cert</code>: certificate for mTLS connections (string or parsed object)</li>
<li><code>ssl_key</code>: key for mTLS connections (string or parsed object)</li>
<li><code>checks.active.type</code>: "http", "https" or "tcp" (default is "http")</li>
<li><code>checks.active.timeout</code>: socket timeout for active checks (in seconds)</li>
<li><code>checks.active.concurrency</code>: number of targets to check concurrently</li>
<li><code>checks.active.http_path</code>: path to use in <code>GET</code> HTTP request to run on active checks</li>
<li><code>checks.active.https_sni</code>: SNI server name incase of HTTPS</li>
<li><code>checks.active.https_verify_certificate</code>: boolean indicating whether to verify the HTTPS certificate</li>
<li><code>checks.active.headers</code>: one or more lists of values indexed by header name</li>
<li><code>checks.active.healthy.interval</code>: interval between checks for healthy targets (in seconds)</li>
<li><code>checks.active.healthy.http_statuses</code>: which HTTP statuses to consider a success</li>
<li><code>checks.active.healthy.successes</code>: number of successes to consider a target healthy</li>
<li><code>checks.active.unhealthy.interval</code>: interval between checks for unhealthy targets (in seconds)</li>
<li><code>checks.active.unhealthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
<li><code>checks.active.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
<li><code>checks.active.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
<li><code>checks.active.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
<li><code>checks.passive.type</code>: "http", "https" or "tcp" (default is "http"; for passive checks, "http" and "https" are equivalent)</li>
<li><code>checks.passive.healthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
<li><code>checks.passive.healthy.successes</code>: number of successes to consider a target healthy</li>
<li><code>checks.passive.unhealthy.http_statuses</code>: which HTTP statuses to consider a success</li>
<li><code>checks.passive.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
<li><code>checks.passive.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
<li><code>checks.passive.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
<li><code>name</code>: name of the health checker</li>
<li><code>shm_name</code>: the name of the <code>lua_shared_dict</code> specified in the Nginx configuration to use</li>
<li><code>ssl_cert</code>: certificate for mTLS connections (string or parsed object)</li>
<li><code>ssl_key</code>: key for mTLS connections (string or parsed object)</li>
<li><code>checks.active.type</code>: &ldquo;http&rdquo;, &ldquo;https&rdquo; or &ldquo;tcp&rdquo; (default is &ldquo;http&rdquo;)</li>
<li><code>checks.active.timeout</code>: socket timeout for active checks (in seconds)</li>
<li><code>checks.active.concurrency</code>: number of targets to check concurrently</li>
<li><code>checks.active.http_path</code>: path to use in <code>GET</code> HTTP request to run on active checks</li>
<li><code>checks.active.https_sni</code>: SNI server name incase of HTTPS</li>
<li><code>checks.active.https_verify_certificate</code>: boolean indicating whether to verify the HTTPS certificate</li>
<li><code>checks.active.headers</code>: one or more lists of values indexed by header name</li>
<li><code>checks.active.healthy.interval</code>: interval between checks for healthy targets (in seconds)</li>
<li><code>checks.active.healthy.http_statuses</code>: which HTTP statuses to consider a success</li>
<li><code>checks.active.healthy.successes</code>: number of successes to consider a target healthy</li>
<li><code>checks.active.unhealthy.interval</code>: interval between checks for unhealthy targets (in seconds)</li>
<li><code>checks.active.unhealthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
<li><code>checks.active.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
<li><code>checks.active.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
<li><code>checks.active.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
<li><code>checks.passive.type</code>: &ldquo;http&rdquo;, &ldquo;https&rdquo; or &ldquo;tcp&rdquo; (default is &ldquo;http&rdquo;; for passive checks, &ldquo;http&rdquo; and &ldquo;https&rdquo; are equivalent)</li>
<li><code>checks.passive.healthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
<li><code>checks.passive.healthy.successes</code>: number of successes to consider a target healthy</li>
<li><code>checks.passive.unhealthy.http_statuses</code>: which HTTP statuses to consider a success</li>
<li><code>checks.passive.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
<li><code>checks.passive.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
<li><code>checks.passive.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
</ul>


<p> If any of the health counters above (e.g. <code>checks.passive.unhealthy.timeouts</code>)
is set to zero, the according category of checks is not taken to account.
This way active or passive health checks can be disabled selectively.
Expand All @@ -832,7 +830,7 @@ <h3>Returns:</h3>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-05-16 13:54:05 </i>
<i style="float:right;">Last updated 2024-06-19 21:43:00 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
Loading

0 comments on commit ab2efa7

Please sign in to comment.