Skip to content

Commit ab2efa7

Browse files
bunglebungle
authored
release 3.1.0 (#163)
1 parent 3da3591 commit ab2efa7

File tree

4 files changed

+278
-214
lines changed

4 files changed

+278
-214
lines changed

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,10 @@ Versioning is strictly based on [Semantic Versioning](https://semver.org/)
103103
* push commit and tag
104104
* upload rock to luarocks: `luarocks upload rockspecs/[name] --api-key=abc`
105105

106+
### 3.1.0 (19-Jun-2024)
107+
108+
* Feat: remove version check of resty.events [#162](https://github.com/Kong/lua-resty-healthcheck/pull/162)
109+
106110
### 3.0.2 (16-May-2024)
107111

108112
* Fix: avoid creating multiple timers to run the same active check [#157](https://github.com/Kong/lua-resty-healthcheck/pull/157)

‎docs/index.html

+63-65
Original file line numberDiff line numberDiff line change
@@ -53,25 +53,23 @@ <h2>Topics</h2>
5353

5454
<h1>Module <code>resty.healthcheck</code></h1>
5555
<p>Healthcheck library for OpenResty.</p>
56-
<p>
57-
58-
59-
<p> Some notes on the usage of this library:</p>
56+
<p><p> Some notes on the usage of this library:</p>
6057

6158
<ul>
62-
<li><p>Each target will have 4 counters, 1 success counter and 3 failure
63-
counters ('http', 'tcp', and 'timeout'). Any failure will <em>only</em> reset the
64-
success counter, but a success will reset <em>all three</em> failure counters.</p></li>
65-
<li><p>All targets are uniquely identified by their IP address and port number
66-
combination, most functions take those as arguments.</p></li>
67-
<li><p>All keys in the SHM will be namespaced by the healthchecker name as
68-
provided to the <a href="index.html#new">new</a> function. Hence no collissions will occur on shm-keys
69-
as long as the <code>name</code> is unique.</p></li>
70-
<li><p>Active healthchecks will be synchronized across workers, such that only
71-
a single active healthcheck runs.</p></li>
72-
<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>
73-
for details.</p></li>
59+
<li><p>Each target will have 4 counters, 1 success counter and 3 failure
60+
counters (&lsquo;http&rsquo;, &lsquo;tcp&rsquo;, and &lsquo;timeout&rsquo;). Any failure will <em>only</em> reset the
61+
success counter, but a success will reset <em>all three</em> failure counters.</p></li>
62+
<li><p>All targets are uniquely identified by their IP address and port number
63+
combination, most functions take those as arguments.</p></li>
64+
<li><p>All keys in the SHM will be namespaced by the healthchecker name as
65+
provided to the <a href="index.html#new">new</a> function. Hence no collissions will occur on shm-keys
66+
as long as the <code>name</code> is unique.</p></li>
67+
<li><p>Active healthchecks will be synchronized across workers, such that only
68+
a single active healthcheck runs.</p></li>
69+
<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>
70+
for details.</p></li>
7471
</ul>
72+
7573
</p>
7674
<h3>Info:</h3>
7775
<ul>
@@ -87,7 +85,7 @@ <h2><a href="#Functions">Functions</a></h2>
8785
<td class="name" nowrap><a href="#run_locked">run_locked (self, key, fn, ...)</a></td>
8886
<td class="summary">Acquire a lock and run a function</p>
8987

90-
<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
88+
<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
9189
exception.</td>
9290
</tr>
9391
</table>
@@ -180,21 +178,20 @@ <h2 class="section-header "><a name="Functions"></a>Functions</h2>
180178
<strong>run_locked (self, key, fn, ...)</strong>
181179
</dt>
182180
<dd>
181+
<p>Acquire a lock and run a function</p>
183182

184-
<p>Acquire a lock and run a function</p>
185-
186-
<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
183+
<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
187184
exception. </p>
188185

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

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

200197

@@ -258,12 +255,12 @@ <h3>Fields:</h3>
258255
</li>
259256
<li><span class="parameter">mostly_healthy</span>
260257
This event is raised when the target status is
261-
still healthy but it started to receive "unhealthy" updates via active or
258+
still healthy but it started to receive &ldquo;unhealthy&rdquo; updates via active or
262259
passive checks.
263260
</li>
264261
<li><span class="parameter">mostly_unhealthy</span>
265262
This event is raised when the target status is
266-
still unhealthy but it started to receive "healthy" updates via active or
263+
still unhealthy but it started to receive &ldquo;healthy&rdquo; updates via active or
267264
passive checks.
268265
</li>
269266
</ul>
@@ -459,8 +456,8 @@ <h2 class="section-header has-description"><a name="Health_management"></a>Healt
459456
<dd>
460457
Report a health failure.
461458
Reports a health failure which will count against the number of occurrences
462-
required to make a target "fall". The type of healthchecker,
463-
"tcp" or "http" (see <a href="index.html#new">new</a>) determines against which counter the occurence goes.
459+
required to make a target &ldquo;fall&rdquo;. The type of healthchecker,
460+
&ldquo;tcp&rdquo; or &ldquo;http&rdquo; (see <a href="index.html#new">new</a>) determines against which counter the occurence goes.
464461
If <code>unhealthy.tcp_failures</code> (for TCP failures) or <code>unhealthy.http_failures</code>
465462
is set to zero in the configuration, this function is a no-op
466463
and returns <code>true</code>.
@@ -478,7 +475,7 @@ <h3>Parameters:</h3>
478475
(optional) hostname of the target being checked.
479476
</li>
480477
<li><span class="parameter">check</span>
481-
(optional) the type of check, either "passive" or "active", default "passive".
478+
(optional) the type of check, either &ldquo;passive&rdquo; or &ldquo;active&rdquo;, default &ldquo;passive&rdquo;.
482479
</li>
483480
</ul>
484481

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

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

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

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

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

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

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

777774

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

783780
<ul>
784-
<li><code>name</code>: name of the health checker</li>
785-
<li><code>shm_name</code>: the name of the <code>lua_shared_dict</code> specified in the Nginx configuration to use</li>
786-
<li><code>ssl_cert</code>: certificate for mTLS connections (string or parsed object)</li>
787-
<li><code>ssl_key</code>: key for mTLS connections (string or parsed object)</li>
788-
<li><code>checks.active.type</code>: "http", "https" or "tcp" (default is "http")</li>
789-
<li><code>checks.active.timeout</code>: socket timeout for active checks (in seconds)</li>
790-
<li><code>checks.active.concurrency</code>: number of targets to check concurrently</li>
791-
<li><code>checks.active.http_path</code>: path to use in <code>GET</code> HTTP request to run on active checks</li>
792-
<li><code>checks.active.https_sni</code>: SNI server name incase of HTTPS</li>
793-
<li><code>checks.active.https_verify_certificate</code>: boolean indicating whether to verify the HTTPS certificate</li>
794-
<li><code>checks.active.headers</code>: one or more lists of values indexed by header name</li>
795-
<li><code>checks.active.healthy.interval</code>: interval between checks for healthy targets (in seconds)</li>
796-
<li><code>checks.active.healthy.http_statuses</code>: which HTTP statuses to consider a success</li>
797-
<li><code>checks.active.healthy.successes</code>: number of successes to consider a target healthy</li>
798-
<li><code>checks.active.unhealthy.interval</code>: interval between checks for unhealthy targets (in seconds)</li>
799-
<li><code>checks.active.unhealthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
800-
<li><code>checks.active.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
801-
<li><code>checks.active.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
802-
<li><code>checks.active.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
803-
<li><code>checks.passive.type</code>: "http", "https" or "tcp" (default is "http"; for passive checks, "http" and "https" are equivalent)</li>
804-
<li><code>checks.passive.healthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
805-
<li><code>checks.passive.healthy.successes</code>: number of successes to consider a target healthy</li>
806-
<li><code>checks.passive.unhealthy.http_statuses</code>: which HTTP statuses to consider a success</li>
807-
<li><code>checks.passive.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
808-
<li><code>checks.passive.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
809-
<li><code>checks.passive.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
781+
<li><code>name</code>: name of the health checker</li>
782+
<li><code>shm_name</code>: the name of the <code>lua_shared_dict</code> specified in the Nginx configuration to use</li>
783+
<li><code>ssl_cert</code>: certificate for mTLS connections (string or parsed object)</li>
784+
<li><code>ssl_key</code>: key for mTLS connections (string or parsed object)</li>
785+
<li><code>checks.active.type</code>: &ldquo;http&rdquo;, &ldquo;https&rdquo; or &ldquo;tcp&rdquo; (default is &ldquo;http&rdquo;)</li>
786+
<li><code>checks.active.timeout</code>: socket timeout for active checks (in seconds)</li>
787+
<li><code>checks.active.concurrency</code>: number of targets to check concurrently</li>
788+
<li><code>checks.active.http_path</code>: path to use in <code>GET</code> HTTP request to run on active checks</li>
789+
<li><code>checks.active.https_sni</code>: SNI server name incase of HTTPS</li>
790+
<li><code>checks.active.https_verify_certificate</code>: boolean indicating whether to verify the HTTPS certificate</li>
791+
<li><code>checks.active.headers</code>: one or more lists of values indexed by header name</li>
792+
<li><code>checks.active.healthy.interval</code>: interval between checks for healthy targets (in seconds)</li>
793+
<li><code>checks.active.healthy.http_statuses</code>: which HTTP statuses to consider a success</li>
794+
<li><code>checks.active.healthy.successes</code>: number of successes to consider a target healthy</li>
795+
<li><code>checks.active.unhealthy.interval</code>: interval between checks for unhealthy targets (in seconds)</li>
796+
<li><code>checks.active.unhealthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
797+
<li><code>checks.active.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
798+
<li><code>checks.active.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
799+
<li><code>checks.active.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
800+
<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>
801+
<li><code>checks.passive.healthy.http_statuses</code>: which HTTP statuses to consider a failure</li>
802+
<li><code>checks.passive.healthy.successes</code>: number of successes to consider a target healthy</li>
803+
<li><code>checks.passive.unhealthy.http_statuses</code>: which HTTP statuses to consider a success</li>
804+
<li><code>checks.passive.unhealthy.tcp_failures</code>: number of TCP failures to consider a target unhealthy</li>
805+
<li><code>checks.passive.unhealthy.timeouts</code>: number of timeouts to consider a target unhealthy</li>
806+
<li><code>checks.passive.unhealthy.http_failures</code>: number of HTTP failures to consider a target unhealthy</li>
810807
</ul>
811808

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

0 commit comments

Comments
 (0)