@mark1russell7/service 0.8.19 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (335) hide show
  1. package/README.md +6 -2
  2. package/build/backoff.d.ts +44 -2
  3. package/build/{builder-zO48Vgoj.d.ts → builder.d.ts} +14 -101
  4. package/build/builder.js +499 -0
  5. package/build/builder.js.map +1 -0
  6. package/build/{call-context-DDhcVvn5.d.ts → call-context.d.ts} +3 -4
  7. package/build/channel.d.ts +1 -1
  8. package/build/channel.js.map +1 -1
  9. package/build/{core-BSzt4RI2.d.ts → client/core.d.ts} +32 -61
  10. package/build/{machine-BhVeHr_m.js → client/core.js} +4 -153
  11. package/build/client/core.js.map +1 -0
  12. package/build/{dial-ChwIcvd4.d.ts → client/dial.d.ts} +3 -4
  13. package/build/client/dial.js +52 -0
  14. package/build/client/dial.js.map +1 -0
  15. package/build/client/machine.js +29 -0
  16. package/build/client/machine.js.map +1 -0
  17. package/build/client/meets.d.ts +35 -0
  18. package/build/client/meets.js +78 -0
  19. package/build/client/meets.js.map +1 -0
  20. package/build/clock.d.ts +2 -2
  21. package/build/clock.js +1 -1
  22. package/build/conformance.d.ts +122 -0
  23. package/build/conformance.js +469 -0
  24. package/build/conformance.js.map +1 -0
  25. package/build/contract.d.ts +28 -0
  26. package/build/contract.js +184 -0
  27. package/build/contract.js.map +1 -0
  28. package/build/description.d.ts +161 -0
  29. package/build/description.js +11 -0
  30. package/build/description.js.map +1 -0
  31. package/build/drains.js +35 -0
  32. package/build/drains.js.map +1 -0
  33. package/build/events.d.ts +25 -0
  34. package/build/fakes.d.ts +43 -0
  35. package/build/fakes.js +93 -0
  36. package/build/fakes.js.map +1 -0
  37. package/build/grpc/client.d.ts +153 -0
  38. package/build/grpc/client.js +474 -0
  39. package/build/grpc/client.js.map +1 -0
  40. package/build/grpc/connection.d.ts +97 -0
  41. package/build/grpc/connection.js +59 -0
  42. package/build/grpc/connection.js.map +1 -0
  43. package/build/grpc/machine.d.ts +12 -0
  44. package/build/grpc/machine.js +149 -0
  45. package/build/grpc/machine.js.map +1 -0
  46. package/build/grpc/meets.d.ts +14 -0
  47. package/build/grpc/meets.js +105 -0
  48. package/build/grpc/meets.js.map +1 -0
  49. package/build/grpc/starting.d.ts +33 -0
  50. package/build/grpc/starting.js +89 -0
  51. package/build/grpc/starting.js.map +1 -0
  52. package/build/grpc.d.ts +9 -303
  53. package/build/grpc.js +7 -854
  54. package/build/health.d.ts +93 -0
  55. package/build/health.js +225 -0
  56. package/build/health.js.map +1 -0
  57. package/build/heartbeat.d.ts +6 -2
  58. package/build/heartbeat.js.map +1 -1
  59. package/build/host/discovery.d.ts +61 -0
  60. package/build/host/discovery.js +113 -0
  61. package/build/host/discovery.js.map +1 -0
  62. package/build/host/env.d.ts +14 -0
  63. package/build/host/env.js +57 -0
  64. package/build/host/env.js.map +1 -0
  65. package/build/host/fakes.d.ts +82 -0
  66. package/build/host/fakes.js +239 -0
  67. package/build/host/fakes.js.map +1 -0
  68. package/build/host/group.d.ts +142 -0
  69. package/build/host/group.js +524 -0
  70. package/build/host/group.js.map +1 -0
  71. package/build/host/install.d.ts +96 -0
  72. package/build/host/install.js +330 -0
  73. package/build/host/install.js.map +1 -0
  74. package/build/host/lock.d.ts +78 -0
  75. package/build/host/lock.js +190 -0
  76. package/build/host/lock.js.map +1 -0
  77. package/build/host/logs.d.ts +26 -0
  78. package/build/host/logs.js +48 -0
  79. package/build/host/logs.js.map +1 -0
  80. package/build/host/node.d.ts +14 -0
  81. package/build/host/node.js +309 -0
  82. package/build/host/node.js.map +1 -0
  83. package/build/{ports-B1ayTL-j.d.ts → host/ports.d.ts} +15 -16
  84. package/build/host/ports.js +17 -0
  85. package/build/host/ports.js.map +1 -0
  86. package/build/host/probes.d.ts +51 -0
  87. package/build/host/probes.js +139 -0
  88. package/build/host/probes.js.map +1 -0
  89. package/build/host/processes.d.ts +32 -0
  90. package/build/host/processes.js +63 -0
  91. package/build/host/processes.js.map +1 -0
  92. package/build/host/render.d.ts +84 -0
  93. package/build/host/render.js +235 -0
  94. package/build/host/render.js.map +1 -0
  95. package/build/host/watch.d.ts +90 -0
  96. package/build/host/watch.js +165 -0
  97. package/build/host/watch.js.map +1 -0
  98. package/build/host.d.ts +13 -671
  99. package/build/host.js +12 -2126
  100. package/build/http/answers.js +29 -0
  101. package/build/http/answers.js.map +1 -0
  102. package/build/http/fake-server.js +61 -0
  103. package/build/http/fake-server.js.map +1 -0
  104. package/build/http/outcome.d.ts +115 -0
  105. package/build/http/outcome.js +325 -0
  106. package/build/http/outcome.js.map +1 -0
  107. package/build/http/probes.d.ts +83 -0
  108. package/build/http/probes.js +232 -0
  109. package/build/http/probes.js.map +1 -0
  110. package/build/http/transport.d.ts +165 -0
  111. package/build/http/transport.js +518 -0
  112. package/build/http/transport.js.map +1 -0
  113. package/build/http-client/client.d.ts +121 -0
  114. package/build/http-client/client.js +330 -0
  115. package/build/http-client/client.js.map +1 -0
  116. package/build/http-client/connection.d.ts +78 -0
  117. package/build/http-client/connection.js +54 -0
  118. package/build/http-client/connection.js.map +1 -0
  119. package/build/http-client/machine.d.ts +14 -0
  120. package/build/http-client/machine.js +109 -0
  121. package/build/http-client/machine.js.map +1 -0
  122. package/build/http-client/meets.d.ts +11 -0
  123. package/build/http-client/meets.js +74 -0
  124. package/build/http-client/meets.js.map +1 -0
  125. package/build/http-client/session.d.ts +87 -0
  126. package/build/http-client/session.js +99 -0
  127. package/build/http-client/session.js.map +1 -0
  128. package/build/http-client/starting.d.ts +25 -0
  129. package/build/http-client/starting.js +65 -0
  130. package/build/http-client/starting.js.map +1 -0
  131. package/build/http-client.d.ts +9 -330
  132. package/build/http-client.js +8 -707
  133. package/build/http.d.ts +5 -353
  134. package/build/http.js +3 -1086
  135. package/build/identity.d.ts +16 -0
  136. package/build/identity.js +44 -0
  137. package/build/identity.js.map +1 -0
  138. package/build/index.d.ts +35 -412
  139. package/build/index.js +25 -3278
  140. package/build/knobs.d.ts +1 -0
  141. package/build/{knobs-BJcz6m01.js → knobs.js} +2 -34
  142. package/build/knobs.js.map +1 -0
  143. package/build/latch.d.ts +29 -0
  144. package/build/latch.js +122 -0
  145. package/build/latch.js.map +1 -0
  146. package/build/{rules-HyFCBStQ.d.ts → law.d.ts} +19 -37
  147. package/build/law.js +149 -0
  148. package/build/law.js.map +1 -0
  149. package/build/lifecycle.d.ts +144 -0
  150. package/build/lifecycle.js +411 -0
  151. package/build/lifecycle.js.map +1 -0
  152. package/build/limiter/machine.d.ts +40 -0
  153. package/build/limiter/machine.js +279 -0
  154. package/build/limiter/machine.js.map +1 -0
  155. package/build/{policy-CBcK2XGg.d.ts → limiter/policy.d.ts} +28 -29
  156. package/build/{policy-UYALkqVq.js → limiter/policy.js} +10 -9
  157. package/build/limiter/policy.js.map +1 -0
  158. package/build/{limiter-BNKnwzeY.d.ts → limiter/quota.d.ts} +32 -74
  159. package/build/{limiter-DrM0PQV9.js → limiter/quota.js} +3 -418
  160. package/build/limiter/quota.js.map +1 -0
  161. package/build/{store-DFwFKrsB.d.ts → limiter/store.d.ts} +10 -11
  162. package/build/limiter/store.js +145 -0
  163. package/build/limiter/store.js.map +1 -0
  164. package/build/limiter.d.ts +4 -3
  165. package/build/limiter.js +4 -2
  166. package/build/lint.d.ts +152 -0
  167. package/build/lint.js +576 -0
  168. package/build/lint.js.map +1 -0
  169. package/build/logger.d.ts +71 -0
  170. package/build/logger.js +183 -0
  171. package/build/logger.js.map +1 -0
  172. package/build/machines.d.ts +41 -0
  173. package/build/machines.js +451 -0
  174. package/build/machines.js.map +1 -0
  175. package/build/metrics.d.ts +53 -0
  176. package/build/metrics.js +111 -0
  177. package/build/metrics.js.map +1 -0
  178. package/build/mongodb/client.d.ts +131 -0
  179. package/build/mongodb/client.js +388 -0
  180. package/build/mongodb/client.js.map +1 -0
  181. package/build/mongodb/connection.d.ts +112 -0
  182. package/build/mongodb/connection.js +12 -0
  183. package/build/mongodb/connection.js.map +1 -0
  184. package/build/mongodb/machine.d.ts +14 -0
  185. package/build/mongodb/machine.js +122 -0
  186. package/build/mongodb/machine.js.map +1 -0
  187. package/build/mongodb/meets.d.ts +15 -0
  188. package/build/mongodb/meets.js +103 -0
  189. package/build/mongodb/meets.js.map +1 -0
  190. package/build/mongodb/starting.d.ts +29 -0
  191. package/build/mongodb/starting.js +77 -0
  192. package/build/mongodb/starting.js.map +1 -0
  193. package/build/mongodb.d.ts +8 -296
  194. package/build/mongodb.js +7 -682
  195. package/build/operation.d.ts +27 -0
  196. package/build/{operation-DF73RZOI.js → operation.js} +2 -2
  197. package/build/operation.js.map +1 -0
  198. package/build/otel.d.ts +2 -2
  199. package/build/pg/client.d.ts +96 -0
  200. package/build/pg/client.js +277 -0
  201. package/build/pg/client.js.map +1 -0
  202. package/build/pg/connection.d.ts +75 -0
  203. package/build/pg/connection.js +11 -0
  204. package/build/pg/connection.js.map +1 -0
  205. package/build/pg/machine.d.ts +13 -0
  206. package/build/pg/machine.js +111 -0
  207. package/build/pg/machine.js.map +1 -0
  208. package/build/pg/meets.d.ts +14 -0
  209. package/build/pg/meets.js +83 -0
  210. package/build/pg/meets.js.map +1 -0
  211. package/build/pg/starting.d.ts +26 -0
  212. package/build/pg/starting.js +62 -0
  213. package/build/pg/starting.js.map +1 -0
  214. package/build/pg.d.ts +8 -219
  215. package/build/pg.js +7 -525
  216. package/build/poller.d.ts +9 -0
  217. package/build/poller.js +154 -0
  218. package/build/poller.js.map +1 -0
  219. package/build/process.d.ts +114 -0
  220. package/build/process.js +170 -0
  221. package/build/process.js.map +1 -0
  222. package/build/profiles.d.ts +68 -0
  223. package/build/profiles.js +120 -0
  224. package/build/profiles.js.map +1 -0
  225. package/build/{queue-DXdw1vLO.d.ts → queue.d.ts} +16 -29
  226. package/build/queue.js +279 -0
  227. package/build/queue.js.map +1 -0
  228. package/build/rabbitmq/client.d.ts +144 -0
  229. package/build/rabbitmq/client.js +426 -0
  230. package/build/rabbitmq/client.js.map +1 -0
  231. package/build/rabbitmq/connection.d.ts +91 -0
  232. package/build/rabbitmq/connection.js +15 -0
  233. package/build/rabbitmq/connection.js.map +1 -0
  234. package/build/rabbitmq/machine.d.ts +13 -0
  235. package/build/rabbitmq/machine.js +159 -0
  236. package/build/rabbitmq/machine.js.map +1 -0
  237. package/build/rabbitmq/meets.d.ts +12 -0
  238. package/build/rabbitmq/meets.js +96 -0
  239. package/build/rabbitmq/meets.js.map +1 -0
  240. package/build/rabbitmq/starting.d.ts +27 -0
  241. package/build/rabbitmq/starting.js +67 -0
  242. package/build/rabbitmq/starting.js.map +1 -0
  243. package/build/rabbitmq.d.ts +8 -283
  244. package/build/rabbitmq.js +7 -742
  245. package/build/redis/client.d.ts +86 -0
  246. package/build/redis/client.js +285 -0
  247. package/build/redis/client.js.map +1 -0
  248. package/build/redis/connection.d.ts +57 -0
  249. package/build/redis/connection.js +11 -0
  250. package/build/redis/connection.js.map +1 -0
  251. package/build/redis/limiter.d.ts +43 -0
  252. package/build/redis/limiter.js +164 -0
  253. package/build/redis/limiter.js.map +1 -0
  254. package/build/redis/machine.d.ts +12 -0
  255. package/build/redis/machine.js +144 -0
  256. package/build/redis/machine.js.map +1 -0
  257. package/build/redis/meets.d.ts +11 -0
  258. package/build/redis/meets.js +75 -0
  259. package/build/redis/meets.js.map +1 -0
  260. package/build/redis/operations.d.ts +5 -0
  261. package/build/redis/operations.js +114 -0
  262. package/build/redis/operations.js.map +1 -0
  263. package/build/redis.d.ts +10 -207
  264. package/build/redis.js +9 -771
  265. package/build/requests.d.ts +66 -0
  266. package/build/requests.js +279 -0
  267. package/build/requests.js.map +1 -0
  268. package/build/retrier.d.ts +62 -0
  269. package/build/{retrier-Dnjhvxol.js → retrier.js} +2 -2
  270. package/build/retrier.js.map +1 -0
  271. package/build/routes.d.ts +35 -0
  272. package/build/routes.js +77 -0
  273. package/build/routes.js.map +1 -0
  274. package/build/rules.d.ts +19 -2
  275. package/build/stops.d.ts +51 -0
  276. package/build/stops.js +86 -0
  277. package/build/stops.js.map +1 -0
  278. package/build/testing.d.ts +8 -270
  279. package/build/testing.js +4 -1027
  280. package/build/testing.js.map +1 -1
  281. package/build/timing.d.ts +63 -0
  282. package/build/{timing-DZl36uXs.js → timing.js} +2 -2
  283. package/build/timing.js.map +1 -0
  284. package/build/units.d.ts +17 -0
  285. package/build/units.js +236 -0
  286. package/build/units.js.map +1 -0
  287. package/build/watchdog.d.ts +38 -0
  288. package/build/watchdog.js +57 -0
  289. package/build/watchdog.js.map +1 -0
  290. package/build/websocket/client.d.ts +136 -0
  291. package/build/websocket/client.js +422 -0
  292. package/build/websocket/client.js.map +1 -0
  293. package/build/websocket/connection.d.ts +83 -0
  294. package/build/websocket/connection.js +57 -0
  295. package/build/websocket/connection.js.map +1 -0
  296. package/build/websocket/machine.d.ts +12 -0
  297. package/build/websocket/machine.js +155 -0
  298. package/build/websocket/machine.js.map +1 -0
  299. package/build/websocket/meets.d.ts +14 -0
  300. package/build/websocket/meets.js +92 -0
  301. package/build/websocket/meets.js.map +1 -0
  302. package/build/websocket/starting.d.ts +25 -0
  303. package/build/websocket/starting.js +69 -0
  304. package/build/websocket/starting.js.map +1 -0
  305. package/build/websocket.d.ts +9 -264
  306. package/build/websocket.js +8 -774
  307. package/build/worker.d.ts +92 -0
  308. package/build/worker.js +153 -0
  309. package/build/worker.js.map +1 -0
  310. package/package.json +5 -4
  311. package/build/backoff-QTRGfkEK.d.ts +0 -45
  312. package/build/clock-DpVgpY4h.d.ts +0 -2
  313. package/build/grpc.js.map +0 -1
  314. package/build/host.js.map +0 -1
  315. package/build/http-client.js.map +0 -1
  316. package/build/http.js.map +0 -1
  317. package/build/index.js.map +0 -1
  318. package/build/knobs-BJcz6m01.js.map +0 -1
  319. package/build/lifecycle-D0J-zwZF.d.ts +0 -374
  320. package/build/limiter-DrM0PQV9.js.map +0 -1
  321. package/build/logger-B6drv9w0.d.ts +0 -488
  322. package/build/machine-BhVeHr_m.js.map +0 -1
  323. package/build/mongodb.js.map +0 -1
  324. package/build/operation-DF73RZOI.js.map +0 -1
  325. package/build/pg.js.map +0 -1
  326. package/build/policy-UYALkqVq.js.map +0 -1
  327. package/build/process-7R9M29wN.js +0 -437
  328. package/build/process-7R9M29wN.js.map +0 -1
  329. package/build/rabbitmq.js.map +0 -1
  330. package/build/redis.js.map +0 -1
  331. package/build/requests-DD2ALv0_.js +0 -583
  332. package/build/requests-DD2ALv0_.js.map +0 -1
  333. package/build/retrier-Dnjhvxol.js.map +0 -1
  334. package/build/timing-DZl36uXs.js.map +0 -1
  335. package/build/websocket.js.map +0 -1
package/README.md CHANGED
@@ -317,11 +317,15 @@ The clock, the heartbeat and the backoff have their own entries. Each entry impo
317
317
 
318
318
  | Entry | Exports |
319
319
  | --- | --- |
320
- | `@mark1russell7/service/clock` | `Clock`, `Cancel`, `realClock`, `platformClock` |
320
+ | `@mark1russell7/service/clock` | `Clock`, `Cancel`, `realClock`, `platformClock`, `unrefClock` |
321
321
  | `@mark1russell7/service/heartbeat` | `heartbeat`, `detectionTime` |
322
322
  | `@mark1russell7/service/backoff` | `backoffDelay`, `backoffBand`, `backoffProblems` |
323
323
 
324
- - **The clock.** `platformClock({ unref })` gives a clock on `performance.now()` and `setTimeout`. With `unref: true`, its timers do not keep a Node process alive. `realClock` is that clock. Each cancel also has `unref`, for one timer.
324
+ - **The clock.** `platformClock({ unref })` gives a clock on `performance.now()` and `setTimeout`. With `unref: true`, its timers do not keep a Node process alive. `realClock` is `platformClock()`: its timers keep the process alive, as `setTimeout` does. Each cancel also has `unref`, for one timer.
325
+ - **The rule of `unref`.** The service uses the `unref` of a timer only when a socket, a child process or the hold of the lifecycle keeps the process alive. Each other timer stays referenced. Thus a wait that a caller awaits, for example `retry` or `within`, ends before the process exits.
326
+ - **The timers that do not keep the process alive.** These timers only watch other work. Examples are the heartbeat of a connection, the checks and the watchdog of a service, and the sweep of a listener. The timers of a supervisor for a live child are also examples. `unrefClock(clock)` gives a part such a clock.
327
+ - **The timers that keep the process alive.** These timers are work, or they bound work that a caller awaits. Examples are a retry, a ticker, the sleeps of a worker loop and the polls of `watchTargets`. The owner stops each one.
328
+ - **Before 0.9.0.** The default clock did not keep the process alive. Thus a command-line tool ended in the wait of a retry, with the code 0 and lost work.
325
329
  - **The home of the clock.** The clock lives in `@mark1russell7/algebra/clock`, beside its fake. This entry gives the same functions. Thus a package that the service imports, for example collections, can use the clock with no cycle.
326
330
  - **The heartbeat.** `heartbeat(options)` sends a ping each interval, and a timeout bounds each ping. A ping without an answer at its timeout is a miss. The last of `misses` misses in sequence starts `onDead`.
327
331
  - **Two kinds of ping.** A ping gives its answer as a promise, as a request and its reply do. Or the answer comes later through `answer()`, as a pong message does.
@@ -1,2 +1,44 @@
1
- import { a as backoffDelay, i as backoffBand, n as DelayBand, o as backoffProblems, r as Jitter, t as Backoff } from "./backoff-QTRGfkEK.js";
2
- export { Backoff, DelayBand, Jitter, backoffBand, backoffDelay, backoffProblems };
1
+ /**
2
+ * A jitter is the random part of each delay. The random number `r` is from 0 up to 1.
3
+ * - `none`: the delay is the backoff.
4
+ * - `subtract`: the delay is `backoff × (1 − fraction × r)`. A fraction of 1 is the full jitter: a delay from 0 to the backoff.
5
+ * - `add`: the delay is `backoff + amount × r`, with the amount in milliseconds.
6
+ */
7
+ export type Jitter = {
8
+ readonly kind: "none";
9
+ } | {
10
+ readonly kind: "subtract";
11
+ readonly fraction: number;
12
+ } | {
13
+ readonly kind: "add";
14
+ readonly amount: number;
15
+ };
16
+ /** A backoff policy gives the delay before each try. Each time is in milliseconds. */
17
+ export interface Backoff {
18
+ /** This time is the backoff of the first try. */
19
+ readonly base: number;
20
+ /** This number multiplies the backoff from one try to the next. The default is 2. */
21
+ readonly factor?: number | undefined;
22
+ /** This time is the most that a backoff can be, before its jitter. The default is no limit. */
23
+ readonly cap?: number | undefined;
24
+ /** This jitter gives the random part of each delay. The default is `none`. */
25
+ readonly jitter?: Jitter | undefined;
26
+ }
27
+ /** A band is the least and the most delay that a policy gives, in milliseconds. */
28
+ export interface DelayBand {
29
+ readonly low: number;
30
+ readonly high: number;
31
+ }
32
+ /**
33
+ * This function gives the delay before a try, in milliseconds. The first try is 1. The delay is
34
+ * the backoff of the try with its jitter, and not below zero. The `random` function gives numbers from 0 up to 1.
35
+ */
36
+ export declare const backoffDelay: (policy: Backoff, attempt: number, random?: () => number) => number;
37
+ /**
38
+ * This function gives the band of the delay before a try: the least and the most delay that the
39
+ * jitter can give. Without a try, the band covers each try. The ordering law reads the most delay
40
+ * of a policy from it.
41
+ */
42
+ export declare const backoffBand: (policy: Backoff, attempt?: number) => DelayBand;
43
+ /** This function gives the problems of a policy: each value that the delays cannot use. */
44
+ export declare const backoffProblems: (policy: Backoff) => string[];
@@ -1,101 +1,15 @@
1
- import { $ as ProcessTrigger, E as Phase, F as Timing, N as Poll, O as RepeatSignal, S as ExitCodes, T as MessageTrigger, V as OperationOf, _ as Check, b as Coupling, k as ServiceDescription, q as ExitTrigger, ut as Operation, w as Gate, x as Dependency, y as CooperativeFloor } from "./logger-B6drv9w0.js";
2
- import { D as CheckFn, E as StartOptions, F as Outcome, L as Trace, S as Health, d as TransportImpl, n as HealthServer, o as PhaseWork, r as Lifecycle, s as RunOptions, t as DependencyHandle } from "./lifecycle-D0J-zwZF.js";
3
- import { l as LimiterSpec } from "./policy-CBcK2XGg.js";
4
- import { n as Clock } from "./clock-DpVgpY4h.js";
1
+ import { Check, CooperativeFloor, Coupling, Dependency, MessageTrigger, RepeatSignal, ServiceDescription } from "./description.js";
2
+ import { Health, StartOptions } from "./health.js";
3
+ import { LimiterSpec } from "./limiter/policy.js";
4
+ import { DependencyHandle, HealthServer, Lifecycle, PhaseWork, RunOptions, TransportImpl } from "./lifecycle.js";
5
+ import { Operation } from "./operation.js";
6
+ import { CheckFn } from "./poller.js";
7
+ import { ExitTrigger, ProcessTrigger } from "./process.js";
8
+ import { Profile } from "./profiles.js";
9
+ import { OperationOf } from "./routes.js";
10
+ import { Timing } from "./timing.js";
11
+ import { WatchdogSpec } from "./watchdog.js";
5
12
  import { Extent, Quantity } from "@mark1russell7/quantity";
6
- /**
7
- * A profile is a part of a declaration as data: policies, phases and the rules of the shutdown.
8
- * `svc.profile(profile)` declares each field, as its method does. The runtime has no defaults, and
9
- * a profile is not a default, because the caller gives it. The caller can change each field with a
10
- * spread. `describe()` then shows the values of the profile.
11
- *
12
- * svc.profile({ ...kubernetes({ grace: s(60), preStop: s(5) }), onRepeatSignal: "exit" });
13
- */
14
- interface Profile {
15
- readonly readiness?: Timing | undefined;
16
- readonly liveness?: Timing | undefined;
17
- readonly startup?: Quantity | undefined;
18
- readonly couplings?: readonly Coupling[] | undefined;
19
- /** These are the phases of the shutdown, in their sequence. */
20
- readonly phases?: readonly Phase[] | undefined;
21
- readonly cooperativeWindow?: Extent | undefined;
22
- readonly cooperativeFloor?: CooperativeFloor | undefined;
23
- readonly onRepeatSignal?: RepeatSignal | undefined;
24
- readonly triggers?: readonly ProcessTrigger[] | undefined;
25
- /** These messages of the IPC channel start the shutdown, as `svc.trigger("ipc-message", message)` declares each one. */
26
- readonly messages?: readonly MessageTrigger[] | undefined;
27
- readonly exitCodes?: ExitCodes | undefined;
28
- }
29
- /**
30
- * This profile is for a service on the computer of a developer. No load balancer routes to it,
31
- * thus it has no readiness hold. Its caps sum to 10 s, and a second signal exits at once. It
32
- * declares no checks, thus the caller declares readiness, liveness and the startup budget.
33
- */
34
- declare const localDev: Profile;
35
- /**
36
- * This profile is for a background host on the computer of a developer, under a supervisor or a
37
- * command that stops it. It has the caps of `localDev`. A repeat signal has no effect, thus the
38
- * host ends its drain. It has no process trigger: a background host has no parent on stdin.
39
- */
40
- declare const daemon: Profile;
41
- /**
42
- * This profile is for a small process: a command that runs one time, or a child process on stdio.
43
- * It has no checks and no probes, and its policies gate nothing. The cooperative abort occurs at the
44
- * start of the drain, thus a first Ctrl-C stops the work at once. A second signal exits at once.
45
- * The exit codes tell the shell how the process stopped: 130 for SIGINT, 143 for SIGTERM and 131
46
- * for SIGQUIT. A stdio child also declares `triggers: ["stdin-close"]`.
47
- */
48
- declare const ephemeral: Profile;
49
- /** These are the settings of a pod that the profile `kubernetes` derives its caps from. */
50
- interface PodTiming {
51
- /** This time is `terminationGracePeriodSeconds`: from the deletion of the pod to SIGKILL. */
52
- readonly grace: Quantity;
53
- /** This time is the preStop sleep, or 0 for no preStop hook. SIGTERM comes after it. */
54
- readonly preStop: Quantity;
55
- }
56
- /**
57
- * This function gives the profile of a pod in Kubernetes. The budget is the grace less the preStop
58
- * sleep: the time from SIGTERM to SIGKILL. Each stage gets a part of the budget, rounded down to
59
- * the millisecond.
60
- * - The parts in thirtieths are 2, 5, 15, 2, 1, 2 and 1, in the sequence of the stages. Thus 2
61
- * thirtieths of the budget stay as a margin before SIGKILL.
62
- * - The cooperative window is 5 thirtieths of the budget.
63
- * - The kubelet sends SIGTERM one time, thus a repeat signal has no effect.
64
- *
65
- * At the defaults of Kubernetes (a grace of 30 s and no preStop hook), the caps are 2, 5, 15, 2, 1,
66
- * 2 and 1 s. Thus the sum of the caps and the preStop sleep fits in the grace (O10). The window is
67
- * shorter than the drain, which is shorter than the budget (O16).
68
- */
69
- declare const kubernetes: (pod: PodTiming) => Profile;
70
- /**
71
- * A watchdog spec declares a watchdog of the event loop. The service declares it as a check whose
72
- * function the watchdog gives: the process's own wedge, which a liveness window reads.
73
- */
74
- interface WatchdogSpec {
75
- readonly name: string;
76
- /** This time is the interval of the tick of the watchdog. */
77
- readonly tick: Quantity;
78
- /** This time is the most that a tick can be late before the loop counts as blocked. */
79
- readonly threshold: Quantity;
80
- /** This gate is the policy that the check controls, or null for a check that only reports. */
81
- readonly gates: Gate | null;
82
- readonly poll: Poll;
83
- }
84
- /**
85
- * A watchdog measures how late its own tick comes. A blocked event loop delays each timer, thus a
86
- * tick that comes later than the threshold shows the block. Its states are `watching`, `blocked`
87
- * and `stopped`.
88
- */
89
- interface Watchdog {
90
- /** This function is the check: it fails when a tick since the last poll came late, or the loop is still blocked. */
91
- readonly check: () => Outcome;
92
- /** This time is the most that a tick was late, in milliseconds, since the start. */
93
- readonly worst: number;
94
- readonly blocked: boolean;
95
- stop(): void;
96
- }
97
- /** This function starts a watchdog on a clock. */
98
- declare const watchdog: (clock: Clock, spec: WatchdogSpec, trace?: Trace) => Watchdog;
99
13
  /**
100
14
  * The caller composes a service with plain method uses before it starts. The builder is imperative, and
101
15
  * it holds static knowledge. The service does not use an `init` function that gives registrations.
@@ -119,7 +33,7 @@ declare const watchdog: (clock: Clock, spec: WatchdogSpec, trace?: Trace) => Wat
119
33
  * `start()` starts only the health runtime. `run()` starts the whole lifecycle: the startup in its
120
34
  * sequence, the exit signals, the capped phases of the shutdown, and the exit of the process.
121
35
  */
122
- interface ControllerBuilder {
36
+ export interface ControllerBuilder {
123
37
  /** This method declares the dependencies that its routes need. The controller is ready only while they are ready. */
124
38
  requires(...dependencies: string[]): ControllerBuilder;
125
39
  /** This method declares a route that the controller serves, and if its callers can send it again. */
@@ -131,7 +45,7 @@ interface ControllerBuilder {
131
45
  pattern(pattern: string, operations: Readonly<Record<string, Operation>>, operationOf?: OperationOf): ControllerBuilder;
132
46
  }
133
47
  /** A service builder composes a service, gives it as data, and starts it. */
134
- interface ServiceBuilder {
48
+ export interface ServiceBuilder {
135
49
  readonly name: string;
136
50
  /** This method declares a dependency, and the handle that connects to it and closes it, if it has one. */
137
51
  dependency(name: string, spec: Omit<Dependency, "name">, handle?: DependencyHandle): ServiceBuilder;
@@ -201,5 +115,4 @@ interface ServiceBuilder {
201
115
  readonly lifecycle: Lifecycle | null;
202
116
  }
203
117
  /** This function starts the composition of a service. */
204
- declare const service: (name: string) => ServiceBuilder;
205
- export { WatchdogSpec as a, Profile as c, kubernetes as d, localDev as f, Watchdog as i, daemon as l, ServiceBuilder as n, watchdog as o, service as r, PodTiming as s, ControllerBuilder as t, ephemeral as u };
118
+ export declare const service: (name: string) => ServiceBuilder;