Skip to content

Commit

Permalink
release 1.6.3
Browse files Browse the repository at this point in the history
  • Loading branch information
@bungle
bungle committed Sep 6, 2023
1 parent 88ad1b4 commit 67446c4
Show file tree
Hide file tree
Showing 5 changed files with 225 additions and 171 deletions.
130 changes: 65 additions & 65 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
<h1>lua-resty-healthcheck</h1>



<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
Expand All @@ -52,29 +53,27 @@ <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>
<li><strong>Copyright</strong>: 2017 Kong Inc.</li>
<li><strong>Copyright</strong>: 2017-2023 Kong Inc.</li>
<li><strong>License</strong>: Apache 2.0</li>
<li><strong>Author</strong>: Hisham Muhammad, Thijs Schreijer</li>
</ul>
Expand Down Expand Up @@ -179,8 +178,7 @@ <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.1/manual.html#pdf-pcall">pcall</a> to protect against
exception. </p>
Expand All @@ -189,11 +187,11 @@ <h2 class="section-header "><a name="Functions"></a>Functions</h2>
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 @@ -257,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 All @@ -286,7 +284,7 @@ <h3>Usage:</h3>
<span class="keyword">end</span>
<span class="keyword">end</span>

worker_events.register(event_callback, my_checker.EVENT_SOURCE)</pre>
worker_events.<span class="function-name">register</span>(event_callback, my_checker.EVENT_SOURCE)</pre>
</ul>

</dd>
Expand Down Expand Up @@ -458,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 @@ -477,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 @@ -520,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 @@ -542,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 @@ -559,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 @@ -596,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 @@ -638,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 @@ -771,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 @@ -780,33 +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>checks.active.type</code>: "http", "https" or "tcp" (default is "http")</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.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_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 @@ -829,8 +829,8 @@ <h3>Returns:</h3>
</div> <!-- id="content" -->
</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 2022-11-17 14:30:53 </i>
<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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
Loading

0 comments on commit 67446c4

Please sign in to comment.