@mark1russell7/service 0.8.18 → 0.8.20

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 (332) hide show
  1. package/README.md +19 -0
  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/{core-BSzt4RI2.d.ts → client/core.d.ts} +32 -61
  9. package/build/{machine-BhVeHr_m.js → client/core.js} +4 -153
  10. package/build/client/core.js.map +1 -0
  11. package/build/{dial-ChwIcvd4.d.ts → client/dial.d.ts} +3 -4
  12. package/build/client/dial.js +52 -0
  13. package/build/client/dial.js.map +1 -0
  14. package/build/client/machine.js +29 -0
  15. package/build/client/machine.js.map +1 -0
  16. package/build/client/meets.d.ts +35 -0
  17. package/build/client/meets.js +78 -0
  18. package/build/client/meets.js.map +1 -0
  19. package/build/clock.d.ts +1 -1
  20. package/build/conformance.d.ts +122 -0
  21. package/build/conformance.js +470 -0
  22. package/build/conformance.js.map +1 -0
  23. package/build/contract.d.ts +28 -0
  24. package/build/contract.js +184 -0
  25. package/build/contract.js.map +1 -0
  26. package/build/description.d.ts +161 -0
  27. package/build/description.js +11 -0
  28. package/build/description.js.map +1 -0
  29. package/build/drains.js +35 -0
  30. package/build/drains.js.map +1 -0
  31. package/build/events.d.ts +25 -0
  32. package/build/fakes.d.ts +43 -0
  33. package/build/fakes.js +93 -0
  34. package/build/fakes.js.map +1 -0
  35. package/build/grpc/client.d.ts +153 -0
  36. package/build/grpc/client.js +474 -0
  37. package/build/grpc/client.js.map +1 -0
  38. package/build/grpc/connection.d.ts +97 -0
  39. package/build/grpc/connection.js +59 -0
  40. package/build/grpc/connection.js.map +1 -0
  41. package/build/grpc/machine.d.ts +12 -0
  42. package/build/grpc/machine.js +149 -0
  43. package/build/grpc/machine.js.map +1 -0
  44. package/build/grpc/meets.d.ts +14 -0
  45. package/build/grpc/meets.js +105 -0
  46. package/build/grpc/meets.js.map +1 -0
  47. package/build/grpc/starting.d.ts +33 -0
  48. package/build/grpc/starting.js +89 -0
  49. package/build/grpc/starting.js.map +1 -0
  50. package/build/grpc.d.ts +9 -303
  51. package/build/grpc.js +7 -854
  52. package/build/health.d.ts +93 -0
  53. package/build/health.js +223 -0
  54. package/build/health.js.map +1 -0
  55. package/build/heartbeat.d.ts +1 -1
  56. package/build/host/discovery.d.ts +61 -0
  57. package/build/host/discovery.js +113 -0
  58. package/build/host/discovery.js.map +1 -0
  59. package/build/host/env.d.ts +14 -0
  60. package/build/host/env.js +57 -0
  61. package/build/host/env.js.map +1 -0
  62. package/build/host/fakes.d.ts +82 -0
  63. package/build/host/fakes.js +239 -0
  64. package/build/host/fakes.js.map +1 -0
  65. package/build/host/group.d.ts +142 -0
  66. package/build/host/group.js +517 -0
  67. package/build/host/group.js.map +1 -0
  68. package/build/host/install.d.ts +96 -0
  69. package/build/host/install.js +330 -0
  70. package/build/host/install.js.map +1 -0
  71. package/build/host/lock.d.ts +78 -0
  72. package/build/host/lock.js +190 -0
  73. package/build/host/lock.js.map +1 -0
  74. package/build/host/logs.d.ts +26 -0
  75. package/build/host/logs.js +48 -0
  76. package/build/host/logs.js.map +1 -0
  77. package/build/host/node.d.ts +14 -0
  78. package/build/host/node.js +309 -0
  79. package/build/host/node.js.map +1 -0
  80. package/build/{ports-B1ayTL-j.d.ts → host/ports.d.ts} +15 -16
  81. package/build/host/ports.js +17 -0
  82. package/build/host/ports.js.map +1 -0
  83. package/build/host/probes.d.ts +51 -0
  84. package/build/host/probes.js +139 -0
  85. package/build/host/probes.js.map +1 -0
  86. package/build/host/processes.d.ts +32 -0
  87. package/build/host/processes.js +63 -0
  88. package/build/host/processes.js.map +1 -0
  89. package/build/host/render.d.ts +84 -0
  90. package/build/host/render.js +235 -0
  91. package/build/host/render.js.map +1 -0
  92. package/build/host/watch.d.ts +90 -0
  93. package/build/host/watch.js +165 -0
  94. package/build/host/watch.js.map +1 -0
  95. package/build/host.d.ts +13 -671
  96. package/build/host.js +12 -2126
  97. package/build/http/answers.js +29 -0
  98. package/build/http/answers.js.map +1 -0
  99. package/build/http/fake-server.js +61 -0
  100. package/build/http/fake-server.js.map +1 -0
  101. package/build/http/outcome.d.ts +115 -0
  102. package/build/http/outcome.js +325 -0
  103. package/build/http/outcome.js.map +1 -0
  104. package/build/http/probes.d.ts +83 -0
  105. package/build/http/probes.js +232 -0
  106. package/build/http/probes.js.map +1 -0
  107. package/build/http/transport.d.ts +165 -0
  108. package/build/http/transport.js +517 -0
  109. package/build/http/transport.js.map +1 -0
  110. package/build/http-client/client.d.ts +121 -0
  111. package/build/http-client/client.js +330 -0
  112. package/build/http-client/client.js.map +1 -0
  113. package/build/http-client/connection.d.ts +78 -0
  114. package/build/http-client/connection.js +54 -0
  115. package/build/http-client/connection.js.map +1 -0
  116. package/build/http-client/machine.d.ts +14 -0
  117. package/build/http-client/machine.js +109 -0
  118. package/build/http-client/machine.js.map +1 -0
  119. package/build/http-client/meets.d.ts +11 -0
  120. package/build/http-client/meets.js +74 -0
  121. package/build/http-client/meets.js.map +1 -0
  122. package/build/http-client/session.d.ts +87 -0
  123. package/build/http-client/session.js +99 -0
  124. package/build/http-client/session.js.map +1 -0
  125. package/build/http-client/starting.d.ts +25 -0
  126. package/build/http-client/starting.js +65 -0
  127. package/build/http-client/starting.js.map +1 -0
  128. package/build/http-client.d.ts +9 -330
  129. package/build/http-client.js +8 -707
  130. package/build/http.d.ts +5 -353
  131. package/build/http.js +3 -1086
  132. package/build/identity.d.ts +16 -0
  133. package/build/identity.js +44 -0
  134. package/build/identity.js.map +1 -0
  135. package/build/index.d.ts +35 -412
  136. package/build/index.js +24 -3277
  137. package/build/knobs.d.ts +1 -0
  138. package/build/{knobs-BJcz6m01.js → knobs.js} +2 -34
  139. package/build/knobs.js.map +1 -0
  140. package/build/latch.d.ts +29 -0
  141. package/build/latch.js +122 -0
  142. package/build/latch.js.map +1 -0
  143. package/build/{rules-HyFCBStQ.d.ts → law.d.ts} +19 -37
  144. package/build/law.js +149 -0
  145. package/build/law.js.map +1 -0
  146. package/build/lifecycle.d.ts +144 -0
  147. package/build/lifecycle.js +411 -0
  148. package/build/lifecycle.js.map +1 -0
  149. package/build/limiter/machine.d.ts +40 -0
  150. package/build/limiter/machine.js +279 -0
  151. package/build/limiter/machine.js.map +1 -0
  152. package/build/{policy-CBcK2XGg.d.ts → limiter/policy.d.ts} +28 -29
  153. package/build/{policy-UYALkqVq.js → limiter/policy.js} +10 -9
  154. package/build/limiter/policy.js.map +1 -0
  155. package/build/{limiter-Cm8nC-Gd.d.ts → limiter/quota.d.ts} +50 -76
  156. package/build/{limiter-Bgy6Gmvl.js → limiter/quota.js} +32 -425
  157. package/build/limiter/quota.js.map +1 -0
  158. package/build/{store-DFwFKrsB.d.ts → limiter/store.d.ts} +10 -11
  159. package/build/limiter/store.js +145 -0
  160. package/build/limiter/store.js.map +1 -0
  161. package/build/limiter.d.ts +4 -3
  162. package/build/limiter.js +4 -2
  163. package/build/lint.d.ts +152 -0
  164. package/build/lint.js +576 -0
  165. package/build/lint.js.map +1 -0
  166. package/build/logger.d.ts +71 -0
  167. package/build/logger.js +183 -0
  168. package/build/logger.js.map +1 -0
  169. package/build/machines.d.ts +41 -0
  170. package/build/machines.js +451 -0
  171. package/build/machines.js.map +1 -0
  172. package/build/metrics.d.ts +53 -0
  173. package/build/metrics.js +111 -0
  174. package/build/metrics.js.map +1 -0
  175. package/build/mongodb/client.d.ts +131 -0
  176. package/build/mongodb/client.js +388 -0
  177. package/build/mongodb/client.js.map +1 -0
  178. package/build/mongodb/connection.d.ts +112 -0
  179. package/build/mongodb/connection.js +12 -0
  180. package/build/mongodb/connection.js.map +1 -0
  181. package/build/mongodb/machine.d.ts +14 -0
  182. package/build/mongodb/machine.js +122 -0
  183. package/build/mongodb/machine.js.map +1 -0
  184. package/build/mongodb/meets.d.ts +15 -0
  185. package/build/mongodb/meets.js +103 -0
  186. package/build/mongodb/meets.js.map +1 -0
  187. package/build/mongodb/starting.d.ts +29 -0
  188. package/build/mongodb/starting.js +77 -0
  189. package/build/mongodb/starting.js.map +1 -0
  190. package/build/mongodb.d.ts +8 -296
  191. package/build/mongodb.js +7 -682
  192. package/build/operation.d.ts +27 -0
  193. package/build/{operation-DF73RZOI.js → operation.js} +2 -2
  194. package/build/operation.js.map +1 -0
  195. package/build/otel.d.ts +2 -2
  196. package/build/pg/client.d.ts +96 -0
  197. package/build/pg/client.js +277 -0
  198. package/build/pg/client.js.map +1 -0
  199. package/build/pg/connection.d.ts +75 -0
  200. package/build/pg/connection.js +11 -0
  201. package/build/pg/connection.js.map +1 -0
  202. package/build/pg/machine.d.ts +13 -0
  203. package/build/pg/machine.js +111 -0
  204. package/build/pg/machine.js.map +1 -0
  205. package/build/pg/meets.d.ts +14 -0
  206. package/build/pg/meets.js +83 -0
  207. package/build/pg/meets.js.map +1 -0
  208. package/build/pg/starting.d.ts +26 -0
  209. package/build/pg/starting.js +62 -0
  210. package/build/pg/starting.js.map +1 -0
  211. package/build/pg.d.ts +8 -219
  212. package/build/pg.js +7 -525
  213. package/build/poller.d.ts +9 -0
  214. package/build/poller.js +152 -0
  215. package/build/poller.js.map +1 -0
  216. package/build/process.d.ts +114 -0
  217. package/build/process.js +170 -0
  218. package/build/process.js.map +1 -0
  219. package/build/profiles.d.ts +68 -0
  220. package/build/profiles.js +120 -0
  221. package/build/profiles.js.map +1 -0
  222. package/build/{queue-DXdw1vLO.d.ts → queue.d.ts} +16 -29
  223. package/build/queue.js +279 -0
  224. package/build/queue.js.map +1 -0
  225. package/build/rabbitmq/client.d.ts +144 -0
  226. package/build/rabbitmq/client.js +426 -0
  227. package/build/rabbitmq/client.js.map +1 -0
  228. package/build/rabbitmq/connection.d.ts +91 -0
  229. package/build/rabbitmq/connection.js +15 -0
  230. package/build/rabbitmq/connection.js.map +1 -0
  231. package/build/rabbitmq/machine.d.ts +13 -0
  232. package/build/rabbitmq/machine.js +159 -0
  233. package/build/rabbitmq/machine.js.map +1 -0
  234. package/build/rabbitmq/meets.d.ts +12 -0
  235. package/build/rabbitmq/meets.js +96 -0
  236. package/build/rabbitmq/meets.js.map +1 -0
  237. package/build/rabbitmq/starting.d.ts +27 -0
  238. package/build/rabbitmq/starting.js +67 -0
  239. package/build/rabbitmq/starting.js.map +1 -0
  240. package/build/rabbitmq.d.ts +8 -283
  241. package/build/rabbitmq.js +7 -742
  242. package/build/redis/client.d.ts +86 -0
  243. package/build/redis/client.js +285 -0
  244. package/build/redis/client.js.map +1 -0
  245. package/build/redis/connection.d.ts +57 -0
  246. package/build/redis/connection.js +11 -0
  247. package/build/redis/connection.js.map +1 -0
  248. package/build/redis/limiter.d.ts +43 -0
  249. package/build/redis/limiter.js +164 -0
  250. package/build/redis/limiter.js.map +1 -0
  251. package/build/redis/machine.d.ts +12 -0
  252. package/build/redis/machine.js +144 -0
  253. package/build/redis/machine.js.map +1 -0
  254. package/build/redis/meets.d.ts +11 -0
  255. package/build/redis/meets.js +75 -0
  256. package/build/redis/meets.js.map +1 -0
  257. package/build/redis/operations.d.ts +5 -0
  258. package/build/redis/operations.js +114 -0
  259. package/build/redis/operations.js.map +1 -0
  260. package/build/redis.d.ts +10 -207
  261. package/build/redis.js +9 -771
  262. package/build/requests.d.ts +66 -0
  263. package/build/requests.js +279 -0
  264. package/build/requests.js.map +1 -0
  265. package/build/retrier.d.ts +62 -0
  266. package/build/{retrier-Dnjhvxol.js → retrier.js} +2 -2
  267. package/build/retrier.js.map +1 -0
  268. package/build/routes.d.ts +35 -0
  269. package/build/routes.js +77 -0
  270. package/build/routes.js.map +1 -0
  271. package/build/rules.d.ts +19 -2
  272. package/build/stops.d.ts +51 -0
  273. package/build/stops.js +86 -0
  274. package/build/stops.js.map +1 -0
  275. package/build/testing.d.ts +8 -270
  276. package/build/testing.js +4 -1027
  277. package/build/testing.js.map +1 -1
  278. package/build/timing.d.ts +63 -0
  279. package/build/{timing-DZl36uXs.js → timing.js} +2 -2
  280. package/build/timing.js.map +1 -0
  281. package/build/units.d.ts +17 -0
  282. package/build/units.js +236 -0
  283. package/build/units.js.map +1 -0
  284. package/build/watchdog.d.ts +34 -0
  285. package/build/watchdog.js +53 -0
  286. package/build/watchdog.js.map +1 -0
  287. package/build/websocket/client.d.ts +136 -0
  288. package/build/websocket/client.js +422 -0
  289. package/build/websocket/client.js.map +1 -0
  290. package/build/websocket/connection.d.ts +83 -0
  291. package/build/websocket/connection.js +57 -0
  292. package/build/websocket/connection.js.map +1 -0
  293. package/build/websocket/machine.d.ts +12 -0
  294. package/build/websocket/machine.js +155 -0
  295. package/build/websocket/machine.js.map +1 -0
  296. package/build/websocket/meets.d.ts +14 -0
  297. package/build/websocket/meets.js +92 -0
  298. package/build/websocket/meets.js.map +1 -0
  299. package/build/websocket/starting.d.ts +25 -0
  300. package/build/websocket/starting.js +69 -0
  301. package/build/websocket/starting.js.map +1 -0
  302. package/build/websocket.d.ts +9 -264
  303. package/build/websocket.js +8 -774
  304. package/build/worker.d.ts +92 -0
  305. package/build/worker.js +153 -0
  306. package/build/worker.js.map +1 -0
  307. package/package.json +4 -3
  308. package/build/backoff-QTRGfkEK.d.ts +0 -45
  309. package/build/clock-DpVgpY4h.d.ts +0 -2
  310. package/build/grpc.js.map +0 -1
  311. package/build/host.js.map +0 -1
  312. package/build/http-client.js.map +0 -1
  313. package/build/http.js.map +0 -1
  314. package/build/index.js.map +0 -1
  315. package/build/knobs-BJcz6m01.js.map +0 -1
  316. package/build/lifecycle-D0J-zwZF.d.ts +0 -374
  317. package/build/limiter-Bgy6Gmvl.js.map +0 -1
  318. package/build/logger-B6drv9w0.d.ts +0 -488
  319. package/build/machine-BhVeHr_m.js.map +0 -1
  320. package/build/mongodb.js.map +0 -1
  321. package/build/operation-DF73RZOI.js.map +0 -1
  322. package/build/pg.js.map +0 -1
  323. package/build/policy-UYALkqVq.js.map +0 -1
  324. package/build/process-7R9M29wN.js +0 -437
  325. package/build/process-7R9M29wN.js.map +0 -1
  326. package/build/rabbitmq.js.map +0 -1
  327. package/build/redis.js.map +0 -1
  328. package/build/requests-DD2ALv0_.js +0 -583
  329. package/build/requests-DD2ALv0_.js.map +0 -1
  330. package/build/retrier-Dnjhvxol.js.map +0 -1
  331. package/build/timing-DZl36uXs.js.map +0 -1
  332. package/build/websocket.js.map +0 -1
package/README.md CHANGED
@@ -478,6 +478,25 @@ const decision = await limiter.take(tenantOf(req));
478
478
  if (!decision.allowed) return limitedResponse(decision); // 429, with Retry-After from 1 to 60
479
479
  ```
480
480
 
481
+ ### The quota of a key
482
+
483
+ A quota is the limit of a provider of an API: at most `limit` units in each window. The window is a calendar window or a rolling window. The gate refuses a take over it before the provider does.
484
+
485
+ | Export | Function |
486
+ | --- | --- |
487
+ | `keyedQuota(name, spec, store, clock)` | The runtime of a quota on a store and a wall clock: `take`, `note`, `giveBack` and `state` for each key |
488
+ | `quotaStep(rule, stored, instant, event)` | The pure step of one key, for a store of your own |
489
+ | `quotaRule(name, spec)`, `quotaProblems(name, spec)` | The spec in numbers, and the problems of a spec that `keyedQuota` refuses |
490
+ | `memoryQuotaStore()` | The store of one process |
491
+ | `takeQuotas(parts, options?)` | A take of several quotas, all or none |
492
+
493
+ - **No defaults.** A spec has a limit, a reserve and a window. A rolling window has a span and a count of buckets. A calendar window has a unit (`day` or `month`), a time zone and a time of day that starts it.
494
+ - **A reading of the provider.** `note(key, reading)` adds what an answer of the provider tells. The count can only become larger. A reset with no units left blocks the key until the reset.
495
+ - **The longest block.** `maxBlock` in the spec is a time above zero, or `window`. A reading at the instant `t` blocks the key until `t` plus that time at the latest. With `window`, the block ends at the latest when the bucket of `t` stops counting.
496
+ - **Why a bound.** A provider can give a reset in a wrong form, for example milliseconds in a header of seconds. Without a bound, such a reset stops the key for hours or for centuries.
497
+ - **The step applies the bound.** `quotaStep` caps the block of the stored record before each event, and the block of a note after it. The store keeps the capped record. When `maxBlock` is absent, no block has a bound.
498
+ - **A gate of your own.** A part of `takeQuotas` needs only `sync`, `take` and `giveBack`. Thus a gate of your own with these members can be a part, next to a `KeyedQuota`.
499
+
481
500
  ## The HTTP edge
482
501
 
483
502
  `@mark1russell7/service/http` is the edge of a service in Node. Of the modules of Node, it imports only `node:http` and `node:net`. The root of the package does not import it. It is not a framework: it has no routing language, no body parser and no middleware.
@@ -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;