Skip to content

Commit

Permalink
release 1.6.4
Browse files Browse the repository at this point in the history
  • Loading branch information
@oowl
oowl committed Dec 27, 2023
1 parent 0a270bd commit 0ce1142
Show file tree
Hide file tree
Showing 6 changed files with 203 additions and 182 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build_and_test_with_resty_events.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,4 +135,4 @@ jobs:
run: |
eval `luarocks path`
eval $(perl -I $HOME/perl5/lib/perl5/ -Mlocal::lib)
TEST_NGINX_RANDOMIZE=1 prove -I. -r t/with_resty-events
TEST_NGINX_TIMEOUT=4 TEST_NGINX_RANDOMIZE=1 prove -I. -r t/with_resty-events
4 changes: 2 additions & 2 deletions .github/workflows/build_and_test_with_worker_events.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ jobs:
runs-on: ubuntu-20.04
strategy:
matrix:
openresty-version: [1.19.9.1, 1.21.4.1]
openresty-version: [1.21.4.1]

steps:
- name: Update and install OS dependencies
Expand Down Expand Up @@ -61,4 +61,4 @@ jobs:
run: |
eval `luarocks path`
eval $(perl -I $HOME/perl5/lib/perl5/ -Mlocal::lib)
TEST_NGINX_RANDOMIZE=1 prove -I. -r t/with_worker-events
TEST_NGINX_TIMEOUT=4 TEST_NGINX_RANDOMIZE=1 prove -I. -r t/with_worker-events
128 changes: 65 additions & 63 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,23 +53,25 @@ <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 (&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>
<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>
</ul>

</p>
<h3>Info:</h3>
<ul>
Expand All @@ -85,7 +87,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.1/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.4/manual.html#pdf-pcall">pcall</a> to protect against
exception.</td>
</tr>
</table>
Expand Down Expand Up @@ -178,20 +180,21 @@ <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> 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
<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
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 @@ -255,12 +258,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 &ldquo;unhealthy&rdquo; updates via active or
still healthy but it started to receive "unhealthy" 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 &ldquo;healthy&rdquo; updates via active or
still unhealthy but it started to receive "healthy" updates via active or
passive checks.
</li>
</ul>
Expand Down Expand Up @@ -456,8 +459,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 &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.
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.
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 @@ -475,7 +478,7 @@ <h3>Parameters:</h3>
(optional) hostname of the target being checked.
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
(optional) the type of check, either "passive" or "active", default "passive".
</li>
</ul>

Expand Down Expand Up @@ -518,7 +521,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 &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
(optional) the type of check, either "passive" or "active", default "passive".
</li>
</ul>

Expand All @@ -540,7 +543,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 &ldquo;rise&rdquo;.
required to make a target "rise".
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 @@ -557,7 +560,7 @@ <h3>Parameters:</h3>
(optional) hostname of the target being checked.
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
(optional) the type of check, either "passive" or "active", default "passive".
</li>
</ul>

Expand Down Expand Up @@ -594,13 +597,13 @@ <h3>Parameters:</h3>
</li>
<li><span class="parameter">operation</span>
The socket operation that failed:
&ldquo;connect&rdquo;, &ldquo;send&rdquo; or &ldquo;receive&rdquo;.
"connect", "send" or "receive".
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_last_failure
https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md#get<em>last</em>failure
</li>
<li><span class="parameter">check</span>
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
(optional) the type of check, either "passive" or "active", default "passive".
</li>
</ul>

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

Expand Down Expand Up @@ -769,7 +772,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&rsquo;s garbage collector and the healthchecks will cease to run.
removed by Lua's garbage collector and the healthchecks will cease to run.


<h3>Parameters:</h3>
Expand All @@ -778,35 +781,34 @@ <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>: &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>
<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>
</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 @@ -830,7 +832,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 2023-09-06 09:49:32 </i>
<i style="float:right;">Last updated 2023-12-27 15:06:12 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
Loading

0 comments on commit 0ce1142

Please sign in to comment.