Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

release 3.1.0 #163

Merged
merged 1 commit into from
Jun 19, 2024
Merged

release 3.1.0 #163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
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
Open in desktop
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
Loading