@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
@@ -0,0 +1,451 @@
1
+ // src/machines.ts
2
+ /**
3
+ * The machines of the runtime as `mark1russell7.machine/1` documents. The documents are the
4
+ * specification, and TypeScript implements them. A test records the transitions of the runtime
5
+ * and replays them against each document (`replay` of `@mark1russell7/algebra`), thus the code and
6
+ * the documents cannot disagree.
7
+ */
8
+ const SOURCE = [{
9
+ ref: "packages/service/src (the runtime implements this document)",
10
+ rung: "implemented"
11
+ }];
12
+ const base = (id, title) => ({
13
+ format: "mark1russell7.machine/1",
14
+ id: `service.machine.${id}`,
15
+ title,
16
+ layer: "self",
17
+ version: "0.2.0",
18
+ sources: SOURCE
19
+ });
20
+ const t = (id, from, on, to, extra = {}) => ({
21
+ id,
22
+ from,
23
+ on,
24
+ to,
25
+ ...extra
26
+ });
27
+ /**
28
+ * The startup gate opens one time. The lifecycle moves it from `closed` to `starting` while its
29
+ * components start. Then one warm-up sweep of each check opens it. A component that does not start
30
+ * fails it for good.
31
+ */
32
+ const GATE_MACHINE = {
33
+ ...base("gate", "The startup gate"),
34
+ states: {
35
+ closed: { initial: true },
36
+ starting: { note: "the health server, then the dependencies, then the transports" },
37
+ sweeping: { note: "one bounded warm-up sweep of each check" },
38
+ open: { final: true },
39
+ failed: { final: true }
40
+ },
41
+ events: {
42
+ "startup.begin": { kind: "local" },
43
+ "component.started": { kind: "local" },
44
+ "mark-ready": { kind: "local" },
45
+ "sweep.done": { kind: "local" },
46
+ "startup.fail": { kind: "local" },
47
+ "startup.over-budget": { kind: "timer" }
48
+ },
49
+ knobs: { startup: {
50
+ key: "policies.startup",
51
+ scope: "service",
52
+ unit: "s",
53
+ default: null
54
+ } },
55
+ timers: { startup_budget: {
56
+ duration: {
57
+ knob: "startup",
58
+ unit: "s"
59
+ },
60
+ arms: ["enter:closed"],
61
+ cancels: ["sweep.done", "startup.fail"],
62
+ fires: "startup.over-budget",
63
+ note: "the gate says that it is over its budget, and the startup probe of the platform acts on it"
64
+ } },
65
+ transitions: [
66
+ t("begin", "closed", "startup.begin", "starting"),
67
+ t("component", "starting", "component.started", "starting"),
68
+ t("mark-ready", ["closed", "starting"], "mark-ready", "sweeping"),
69
+ t("open", "sweeping", "sweep.done", "open"),
70
+ t("fail", [
71
+ "closed",
72
+ "starting",
73
+ "sweeping"
74
+ ], "startup.fail", "failed"),
75
+ t("over-budget-closed", "closed", "startup.over-budget", "closed", { timer: "startup_budget" }),
76
+ t("over-budget-starting", "starting", "startup.over-budget", "starting", { timer: "startup_budget" }),
77
+ t("over-budget-sweeping", "sweeping", "startup.over-budget", "sweeping", { timer: "startup_budget" })
78
+ ]
79
+ };
80
+ /** A debounce latch counts the polls of its check in sequence. A readiness latch starts tripped. */
81
+ const LATCH_MACHINE = {
82
+ ...base("latch", "The latch of a policy, as a debounce"),
83
+ states: {
84
+ tripped: {
85
+ initial: true,
86
+ note: "a readiness latch starts here; a liveness latch starts released"
87
+ },
88
+ released: {}
89
+ },
90
+ events: {
91
+ "poll.ok": { kind: "local" },
92
+ "poll.fail": { kind: "local" }
93
+ },
94
+ knobs: {
95
+ fail_after: {
96
+ key: "policies.<gate>.failAfter",
97
+ scope: "check",
98
+ unit: "count",
99
+ default: null
100
+ },
101
+ recover_after: {
102
+ key: "policies.<gate>.recoverAfter",
103
+ scope: "check",
104
+ unit: "count",
105
+ default: null
106
+ }
107
+ },
108
+ timers: {},
109
+ transitions: [
110
+ t("pass", "released", "poll.ok", "released"),
111
+ t("fail-count", "released", "poll.fail", "released", { guard: "failures in sequence < fail_after" }),
112
+ t("trip", "released", "poll.fail", "tripped", { guard: "failures in sequence >= fail_after" }),
113
+ t("fail", "tripped", "poll.fail", "tripped"),
114
+ t("pass-count", "tripped", "poll.ok", "tripped", { guard: "passes in sequence < recover_after" }),
115
+ t("release", "tripped", "poll.ok", "released", { guard: "passes in sequence >= recover_after" })
116
+ ]
117
+ };
118
+ /**
119
+ * A window latch measures time on the monotonic clock from the first failure of a sequence, and
120
+ * from the first pass after a trip.
121
+ */
122
+ const WINDOW_MACHINE = {
123
+ ...base("window", "The latch of a policy, as a window"),
124
+ states: {
125
+ released: {
126
+ initial: true,
127
+ note: "a liveness latch starts here; a readiness latch starts tripped"
128
+ },
129
+ failing: { note: "the fail window runs" },
130
+ tripped: {},
131
+ recovering: { note: "the recover window runs" }
132
+ },
133
+ events: {
134
+ "poll.ok": { kind: "local" },
135
+ "poll.fail": { kind: "local" },
136
+ "window.failed": { kind: "timer" },
137
+ "window.recovered": { kind: "timer" }
138
+ },
139
+ knobs: {
140
+ fail_after: {
141
+ key: "policies.<gate>.failAfter",
142
+ scope: "check",
143
+ unit: "s",
144
+ default: null
145
+ },
146
+ recover_after: {
147
+ key: "policies.<gate>.recoverAfter",
148
+ scope: "check",
149
+ unit: "s",
150
+ default: null
151
+ }
152
+ },
153
+ timers: {
154
+ fail_window: {
155
+ duration: {
156
+ knob: "fail_after",
157
+ unit: "s"
158
+ },
159
+ arms: ["enter:failing"],
160
+ cancels: ["poll.ok"],
161
+ fires: "window.failed"
162
+ },
163
+ recover_window: {
164
+ duration: {
165
+ knob: "recover_after",
166
+ unit: "s"
167
+ },
168
+ arms: ["enter:recovering"],
169
+ cancels: ["poll.fail"],
170
+ fires: "window.recovered"
171
+ }
172
+ },
173
+ transitions: [
174
+ t("pass", "released", "poll.ok", "released"),
175
+ t("start-failing", "released", "poll.fail", "failing", { guard: "fail_after > 0" }),
176
+ t("trip-at-once", "released", "poll.fail", "tripped", { guard: "fail_after = 0" }),
177
+ t("still-failing", "failing", "poll.fail", "failing"),
178
+ t("stop-failing", "failing", "poll.ok", "released"),
179
+ t("trip", "failing", "window.failed", "tripped", { timer: "fail_window" }),
180
+ t("fail", "tripped", "poll.fail", "tripped"),
181
+ t("release-at-once", "tripped", "poll.ok", "released", { guard: "recover_after is absent or 0" }),
182
+ t("start-recovering", "tripped", "poll.ok", "recovering", { guard: "recover_after > 0" }),
183
+ t("still-recovering", "recovering", "poll.ok", "recovering"),
184
+ t("stop-recovering", "recovering", "poll.fail", "tripped"),
185
+ t("release", "recovering", "window.recovered", "released", { timer: "recover_window" })
186
+ ]
187
+ };
188
+ /**
189
+ * A poller starts one check on a jittered loop with a fixed delay. A call that outlives its timeout
190
+ * stays pending (`hung`), and the poller does not start the check again until the call settles.
191
+ */
192
+ const POLLER_MACHINE = {
193
+ ...base("poller", "The poller of a check"),
194
+ states: {
195
+ idle: {
196
+ initial: true,
197
+ note: "before the loop starts"
198
+ },
199
+ waiting: { note: "the loop timer runs, and no call is pending" },
200
+ calling: { note: "a call runs, in its timeout" },
201
+ hung: { note: "a call outlived its timeout, and it is still pending" },
202
+ stopped: { final: true }
203
+ },
204
+ events: {
205
+ start: { kind: "local" },
206
+ sweep: { kind: "local" },
207
+ tick: { kind: "timer" },
208
+ answer: { kind: "local" },
209
+ timeout: { kind: "timer" },
210
+ "late-answer": { kind: "local" },
211
+ stop: { kind: "local" }
212
+ },
213
+ knobs: {
214
+ interval: {
215
+ key: "checks.<name>.poll.interval",
216
+ scope: "check",
217
+ unit: "s",
218
+ default: null
219
+ },
220
+ timeout: {
221
+ key: "checks.<name>.poll.timeout",
222
+ scope: "check",
223
+ unit: "s",
224
+ default: null
225
+ }
226
+ },
227
+ timers: {
228
+ loop: {
229
+ duration: {
230
+ knob: "interval",
231
+ unit: "s"
232
+ },
233
+ arms: ["start", "tick"],
234
+ cancels: ["stop"],
235
+ fires: "tick",
236
+ note: "the interval, with its jitter: a fixed delay from the start of each poll"
237
+ },
238
+ poll_timeout: {
239
+ duration: {
240
+ knob: "timeout",
241
+ unit: "s"
242
+ },
243
+ arms: ["enter:calling"],
244
+ cancels: ["answer", "stop"],
245
+ fires: "timeout"
246
+ }
247
+ },
248
+ transitions: [
249
+ t("sweep", "idle", "sweep", "calling"),
250
+ t("start", "idle", "start", "waiting"),
251
+ t("start-while-calling", "calling", "start", "calling", { note: "a late check polls at once, then starts its loop" }),
252
+ t("start-while-hung", "hung", "start", "hung"),
253
+ t("tick", "waiting", "tick", "calling", { guard: "the force-fail list does not name the check" }),
254
+ t("tick-forced", "waiting", "tick", "waiting", { guard: "the force-fail list names the check" }),
255
+ t("tick-pending", "calling", "tick", "calling", { note: "the poll fails at once: its call is pending" }),
256
+ t("tick-hung", "hung", "tick", "hung", { note: "the poll fails at once: its call is pending" }),
257
+ t("answer-loop", "calling", "answer", "waiting", { guard: "the loop runs" }),
258
+ t("answer-sweep", "calling", "answer", "idle", { guard: "the loop has not started" }),
259
+ t("timeout", "calling", "timeout", "hung", { timer: "poll_timeout" }),
260
+ t("late-answer-loop", "hung", "late-answer", "waiting", { guard: "the loop runs" }),
261
+ t("late-answer-sweep", "hung", "late-answer", "idle", { guard: "the loop has not started" }),
262
+ t("stop", [
263
+ "idle",
264
+ "waiting",
265
+ "calling",
266
+ "hung"
267
+ ], "stop", "stopped"),
268
+ t("settle-after-stop", "stopped", [
269
+ "answer",
270
+ "late-answer",
271
+ "timeout"
272
+ ], "stopped")
273
+ ]
274
+ };
275
+ /**
276
+ * The exit manager is the only part that ends the process. The first exit request starts the
277
+ * shutdown. A later request has no effect, but a repeat signal exits at once when the declaration
278
+ * says `onRepeatSignal: "exit"`. The exit code is the code of the exit request, else 1 after an
279
+ * error, else 0.
280
+ */
281
+ const EXIT_MACHINE = {
282
+ ...base("exit", "The exit manager"),
283
+ states: {
284
+ running: { initial: true },
285
+ stopping: {},
286
+ exited: { final: true }
287
+ },
288
+ events: {
289
+ "exit.request": {
290
+ kind: "app",
291
+ note: "SIGINT, SIGTERM, SIGQUIT, a declared process trigger or shutdown()"
292
+ },
293
+ "exit.repeat": {
294
+ kind: "app",
295
+ note: "a trigger or shutdown() while the shutdown runs"
296
+ },
297
+ "startup.fail": { kind: "local" },
298
+ error: { kind: "local" },
299
+ "shutdown.done": { kind: "local" }
300
+ },
301
+ knobs: { on_repeat_signal: {
302
+ key: "shutdown.onRepeatSignal",
303
+ scope: "service",
304
+ unit: null,
305
+ default: null
306
+ } },
307
+ timers: {},
308
+ transitions: [
309
+ t("request", "running", "exit.request", "stopping"),
310
+ t("startup-fail", "running", "startup.fail", "stopping"),
311
+ t("error-running", "running", "error", "running"),
312
+ t("repeat", "stopping", "exit.repeat", "stopping", { guard: "a process trigger or shutdown() repeats, or a signal repeats and on_repeat_signal is not exit" }),
313
+ t("repeat-exit", "stopping", "exit.repeat", "exited", {
314
+ guard: "a signal repeats and on_repeat_signal is exit",
315
+ note: "the process exits at once with the code 1"
316
+ }),
317
+ t("startup-fail-stopping", "stopping", "startup.fail", "stopping"),
318
+ t("error", "stopping", "error", "stopping"),
319
+ t("exit", "stopping", "shutdown.done", "exited", { note: "the exit code is the code of the exit request, else 1 after an error, else 0" })
320
+ ]
321
+ };
322
+ /** A watchdog measures how late its own tick comes, and a late tick shows a blocked event loop. */
323
+ const WATCHDOG_MACHINE = {
324
+ ...base("watchdog", "The watchdog of the event loop"),
325
+ states: {
326
+ watching: { initial: true },
327
+ blocked: {},
328
+ stopped: { final: true }
329
+ },
330
+ events: {
331
+ tick: { kind: "timer" },
332
+ stop: { kind: "local" }
333
+ },
334
+ knobs: {
335
+ tick: {
336
+ key: "watchdog.tick",
337
+ scope: "process",
338
+ unit: "s",
339
+ default: null
340
+ },
341
+ threshold: {
342
+ key: "watchdog.threshold",
343
+ scope: "process",
344
+ unit: "s",
345
+ default: null
346
+ }
347
+ },
348
+ timers: { tick: {
349
+ duration: {
350
+ knob: "tick",
351
+ unit: "s"
352
+ },
353
+ arms: ["enter:watching", "tick"],
354
+ cancels: ["stop"],
355
+ fires: "tick"
356
+ } },
357
+ transitions: [
358
+ t("on-time", "watching", "tick", "watching", { guard: "lateness <= threshold" }),
359
+ t("block", "watching", "tick", "blocked", { guard: "lateness > threshold" }),
360
+ t("still-blocked", "blocked", "tick", "blocked", { guard: "lateness > threshold" }),
361
+ t("unblock", "blocked", "tick", "watching", { guard: "lateness <= threshold" }),
362
+ t("stop", ["watching", "blocked"], "stop", "stopped")
363
+ ]
364
+ };
365
+ /** This function gives the name of a knob for the cap of a phase: `drain` gives `drain_cap`. */
366
+ const capKnob = (phase) => `${phase.replace(/[^A-Za-z0-9]+/g, "_")}_cap`;
367
+ /**
368
+ * This function gives the drain of a declaration as a machine. It has one state for each declared
369
+ * phase, in its sequence, and each state has a timer at its cap. The drain also has the cooperative abort: the
370
+ * cap of the drain less the cooperative window. With the floor `half`, it is half that cap at the
371
+ * least. With the floor `none`, it is 0 at the least.
372
+ */
373
+ const drainMachine = (description) => {
374
+ const phases = description.shutdown.phases;
375
+ const states = { running: { initial: true } };
376
+ for (const phase of phases) states[phase.name] = {};
377
+ states["done"] = { final: true };
378
+ const knobs = Object.fromEntries([...phases.map((phase) => [capKnob(phase.name), {
379
+ key: `shutdown.phases.${phase.name}.cap`,
380
+ scope: "service",
381
+ unit: "s",
382
+ default: null
383
+ }]), ["cooperative_window", {
384
+ key: "shutdown.cooperativeWindow",
385
+ scope: "service",
386
+ unit: "s",
387
+ default: null
388
+ }]]);
389
+ const timers = {};
390
+ for (const phase of phases) timers[`${capKnob(phase.name)}_timer`] = {
391
+ duration: {
392
+ knob: capKnob(phase.name),
393
+ unit: "s"
394
+ },
395
+ arms: [`enter:${phase.name}`],
396
+ cancels: ["phase.done"],
397
+ fires: "phase.cap"
398
+ };
399
+ const floor = description.shutdown.cooperativeFloor === "none" ? "0" : "drain_cap / 2";
400
+ if (phases.some((phase) => phase.name === "drain")) timers["cooperative_abort"] = {
401
+ duration: {
402
+ expr: `max(drain_cap - cooperative_window, ${floor})`,
403
+ unit: "s"
404
+ },
405
+ arms: ["enter:drain"],
406
+ cancels: ["phase.done", "phase.cap"],
407
+ fires: "drain.cooperative-abort"
408
+ };
409
+ const transitions = [];
410
+ const order = [
411
+ "running",
412
+ ...phases.map((phase) => phase.name),
413
+ "done"
414
+ ];
415
+ for (let at = 0; at + 1 < order.length; at += 1) {
416
+ const from = order[at];
417
+ const to = order[at + 1];
418
+ transitions.push(at === 0 ? t(`begin`, from, "exit.request", to) : t(`after-${from}`, from, ["phase.done", "phase.cap"], to, {
419
+ timer: `${capKnob(from)}_timer`,
420
+ note: "phase.cap: the work of the phase did not end in its cap, and the exit code is 1"
421
+ }));
422
+ }
423
+ if (phases.some((phase) => phase.name === "drain")) transitions.push(t("cooperative-abort", "drain", "drain.cooperative-abort", "drain", { timer: "cooperative_abort" }));
424
+ for (const state of [...phases.map((phase) => phase.name), "done"]) transitions.push(t(`signal-abort-${state}`, state, "signal.abort", state));
425
+ return {
426
+ ...base("drain", `The drain of ${description.name}`),
427
+ states,
428
+ events: {
429
+ "exit.request": { kind: "app" },
430
+ "phase.done": { kind: "local" },
431
+ "phase.cap": { kind: "timer" },
432
+ "drain.cooperative-abort": { kind: "timer" },
433
+ "signal.abort": { kind: "local" }
434
+ },
435
+ knobs,
436
+ timers,
437
+ transitions
438
+ };
439
+ };
440
+ /** These are the static machines of the runtime, by the name that their events carry. */
441
+ const MACHINES = {
442
+ gate: GATE_MACHINE,
443
+ latch: LATCH_MACHINE,
444
+ window: WINDOW_MACHINE,
445
+ poller: POLLER_MACHINE,
446
+ exit: EXIT_MACHINE,
447
+ watchdog: WATCHDOG_MACHINE
448
+ };
449
+ export { EXIT_MACHINE, GATE_MACHINE, LATCH_MACHINE, MACHINES, POLLER_MACHINE, WATCHDOG_MACHINE, WINDOW_MACHINE, capKnob, drainMachine };
450
+
451
+ //# sourceMappingURL=machines.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"machines.js","names":[],"sources":["../src/machines.ts"],"sourcesContent":["import type { Machine, TransitionDef } from \"@mark1russell7/algebra\";\nimport type { ServiceDescription } from \"./description.ts\";\nimport type { MachineName } from \"./events.ts\";\n\n/**\n * The machines of the runtime as `mark1russell7.machine/1` documents. The documents are the\n * specification, and TypeScript implements them. A test records the transitions of the runtime\n * and replays them against each document (`replay` of `@mark1russell7/algebra`), thus the code and\n * the documents cannot disagree.\n */\n\nconst SOURCE = [{ ref: \"packages/service/src (the runtime implements this document)\", rung: \"implemented\" as const }];\nconst base = (id: string, title: string): Pick<Machine, \"format\" | \"id\" | \"title\" | \"layer\" | \"version\" | \"sources\"> => ({\n format: \"mark1russell7.machine/1\",\n id: `service.machine.${id}`,\n title,\n layer: \"self\",\n version: \"0.2.0\",\n sources: SOURCE,\n});\nconst t = (\n id: string,\n from: string | readonly string[],\n on: string | readonly string[],\n to: string,\n extra: Partial<TransitionDef> = {},\n): TransitionDef => ({ id, from, on, to, ...extra });\n\n/**\n * The startup gate opens one time. The lifecycle moves it from `closed` to `starting` while its\n * components start. Then one warm-up sweep of each check opens it. A component that does not start\n * fails it for good.\n */\nexport const GATE_MACHINE: Machine = {\n ...base(\"gate\", \"The startup gate\"),\n states: {\n closed: { initial: true },\n starting: { note: \"the health server, then the dependencies, then the transports\" },\n sweeping: { note: \"one bounded warm-up sweep of each check\" },\n open: { final: true },\n failed: { final: true },\n },\n events: {\n \"startup.begin\": { kind: \"local\" },\n \"component.started\": { kind: \"local\" },\n \"mark-ready\": { kind: \"local\" },\n \"sweep.done\": { kind: \"local\" },\n \"startup.fail\": { kind: \"local\" },\n \"startup.over-budget\": { kind: \"timer\" },\n },\n knobs: { startup: { key: \"policies.startup\", scope: \"service\", unit: \"s\", default: null } },\n timers: {\n startup_budget: {\n duration: { knob: \"startup\", unit: \"s\" },\n arms: [\"enter:closed\"],\n cancels: [\"sweep.done\", \"startup.fail\"],\n fires: \"startup.over-budget\",\n note: \"the gate says that it is over its budget, and the startup probe of the platform acts on it\",\n },\n },\n transitions: [\n t(\"begin\", \"closed\", \"startup.begin\", \"starting\"),\n t(\"component\", \"starting\", \"component.started\", \"starting\"),\n t(\"mark-ready\", [\"closed\", \"starting\"], \"mark-ready\", \"sweeping\"),\n t(\"open\", \"sweeping\", \"sweep.done\", \"open\"),\n t(\"fail\", [\"closed\", \"starting\", \"sweeping\"], \"startup.fail\", \"failed\"),\n // the budget timer leaves each state where it is\n t(\"over-budget-closed\", \"closed\", \"startup.over-budget\", \"closed\", { timer: \"startup_budget\" }),\n t(\"over-budget-starting\", \"starting\", \"startup.over-budget\", \"starting\", { timer: \"startup_budget\" }),\n t(\"over-budget-sweeping\", \"sweeping\", \"startup.over-budget\", \"sweeping\", { timer: \"startup_budget\" }),\n ],\n};\n\n/** A debounce latch counts the polls of its check in sequence. A readiness latch starts tripped. */\nexport const LATCH_MACHINE: Machine = {\n ...base(\"latch\", \"The latch of a policy, as a debounce\"),\n states: {\n tripped: { initial: true, note: \"a readiness latch starts here; a liveness latch starts released\" },\n released: {},\n },\n events: { \"poll.ok\": { kind: \"local\" }, \"poll.fail\": { kind: \"local\" } },\n knobs: {\n fail_after: { key: \"policies.<gate>.failAfter\", scope: \"check\", unit: \"count\", default: null },\n recover_after: { key: \"policies.<gate>.recoverAfter\", scope: \"check\", unit: \"count\", default: null },\n },\n timers: {},\n transitions: [\n t(\"pass\", \"released\", \"poll.ok\", \"released\"),\n t(\"fail-count\", \"released\", \"poll.fail\", \"released\", { guard: \"failures in sequence < fail_after\" }),\n t(\"trip\", \"released\", \"poll.fail\", \"tripped\", { guard: \"failures in sequence >= fail_after\" }),\n t(\"fail\", \"tripped\", \"poll.fail\", \"tripped\"),\n t(\"pass-count\", \"tripped\", \"poll.ok\", \"tripped\", { guard: \"passes in sequence < recover_after\" }),\n t(\"release\", \"tripped\", \"poll.ok\", \"released\", { guard: \"passes in sequence >= recover_after\" }),\n ],\n};\n\n/**\n * A window latch measures time on the monotonic clock from the first failure of a sequence, and\n * from the first pass after a trip.\n */\nexport const WINDOW_MACHINE: Machine = {\n ...base(\"window\", \"The latch of a policy, as a window\"),\n states: {\n released: { initial: true, note: \"a liveness latch starts here; a readiness latch starts tripped\" },\n failing: { note: \"the fail window runs\" },\n tripped: {},\n recovering: { note: \"the recover window runs\" },\n },\n events: {\n \"poll.ok\": { kind: \"local\" },\n \"poll.fail\": { kind: \"local\" },\n \"window.failed\": { kind: \"timer\" },\n \"window.recovered\": { kind: \"timer\" },\n },\n knobs: {\n fail_after: { key: \"policies.<gate>.failAfter\", scope: \"check\", unit: \"s\", default: null },\n recover_after: { key: \"policies.<gate>.recoverAfter\", scope: \"check\", unit: \"s\", default: null },\n },\n timers: {\n fail_window: {\n duration: { knob: \"fail_after\", unit: \"s\" },\n arms: [\"enter:failing\"],\n cancels: [\"poll.ok\"],\n fires: \"window.failed\",\n },\n recover_window: {\n duration: { knob: \"recover_after\", unit: \"s\" },\n arms: [\"enter:recovering\"],\n cancels: [\"poll.fail\"],\n fires: \"window.recovered\",\n },\n },\n transitions: [\n t(\"pass\", \"released\", \"poll.ok\", \"released\"),\n t(\"start-failing\", \"released\", \"poll.fail\", \"failing\", { guard: \"fail_after > 0\" }),\n t(\"trip-at-once\", \"released\", \"poll.fail\", \"tripped\", { guard: \"fail_after = 0\" }),\n t(\"still-failing\", \"failing\", \"poll.fail\", \"failing\"),\n t(\"stop-failing\", \"failing\", \"poll.ok\", \"released\"),\n t(\"trip\", \"failing\", \"window.failed\", \"tripped\", { timer: \"fail_window\" }),\n t(\"fail\", \"tripped\", \"poll.fail\", \"tripped\"),\n t(\"release-at-once\", \"tripped\", \"poll.ok\", \"released\", { guard: \"recover_after is absent or 0\" }),\n t(\"start-recovering\", \"tripped\", \"poll.ok\", \"recovering\", { guard: \"recover_after > 0\" }),\n t(\"still-recovering\", \"recovering\", \"poll.ok\", \"recovering\"),\n t(\"stop-recovering\", \"recovering\", \"poll.fail\", \"tripped\"),\n t(\"release\", \"recovering\", \"window.recovered\", \"released\", { timer: \"recover_window\" }),\n ],\n};\n\n/**\n * A poller starts one check on a jittered loop with a fixed delay. A call that outlives its timeout\n * stays pending (`hung`), and the poller does not start the check again until the call settles.\n */\nexport const POLLER_MACHINE: Machine = {\n ...base(\"poller\", \"The poller of a check\"),\n states: {\n idle: { initial: true, note: \"before the loop starts\" },\n waiting: { note: \"the loop timer runs, and no call is pending\" },\n calling: { note: \"a call runs, in its timeout\" },\n hung: { note: \"a call outlived its timeout, and it is still pending\" },\n stopped: { final: true },\n },\n events: {\n start: { kind: \"local\" },\n sweep: { kind: \"local\" },\n tick: { kind: \"timer\" },\n answer: { kind: \"local\" },\n timeout: { kind: \"timer\" },\n \"late-answer\": { kind: \"local\" },\n stop: { kind: \"local\" },\n },\n knobs: {\n interval: { key: \"checks.<name>.poll.interval\", scope: \"check\", unit: \"s\", default: null },\n timeout: { key: \"checks.<name>.poll.timeout\", scope: \"check\", unit: \"s\", default: null },\n },\n timers: {\n loop: {\n duration: { knob: \"interval\", unit: \"s\" },\n arms: [\"start\", \"tick\"],\n cancels: [\"stop\"],\n fires: \"tick\",\n note: \"the interval, with its jitter: a fixed delay from the start of each poll\",\n },\n poll_timeout: {\n duration: { knob: \"timeout\", unit: \"s\" },\n arms: [\"enter:calling\"],\n cancels: [\"answer\", \"stop\"],\n fires: \"timeout\",\n },\n },\n transitions: [\n t(\"sweep\", \"idle\", \"sweep\", \"calling\"),\n t(\"start\", \"idle\", \"start\", \"waiting\"),\n t(\"start-while-calling\", \"calling\", \"start\", \"calling\", { note: \"a late check polls at once, then starts its loop\" }),\n t(\"start-while-hung\", \"hung\", \"start\", \"hung\"),\n t(\"tick\", \"waiting\", \"tick\", \"calling\", { guard: \"the force-fail list does not name the check\" }),\n t(\"tick-forced\", \"waiting\", \"tick\", \"waiting\", { guard: \"the force-fail list names the check\" }),\n t(\"tick-pending\", \"calling\", \"tick\", \"calling\", { note: \"the poll fails at once: its call is pending\" }),\n t(\"tick-hung\", \"hung\", \"tick\", \"hung\", { note: \"the poll fails at once: its call is pending\" }),\n t(\"answer-loop\", \"calling\", \"answer\", \"waiting\", { guard: \"the loop runs\" }),\n t(\"answer-sweep\", \"calling\", \"answer\", \"idle\", { guard: \"the loop has not started\" }),\n t(\"timeout\", \"calling\", \"timeout\", \"hung\", { timer: \"poll_timeout\" }),\n t(\"late-answer-loop\", \"hung\", \"late-answer\", \"waiting\", { guard: \"the loop runs\" }),\n t(\"late-answer-sweep\", \"hung\", \"late-answer\", \"idle\", { guard: \"the loop has not started\" }),\n t(\"stop\", [\"idle\", \"waiting\", \"calling\", \"hung\"], \"stop\", \"stopped\"),\n t(\"settle-after-stop\", \"stopped\", [\"answer\", \"late-answer\", \"timeout\"], \"stopped\"),\n ],\n};\n\n/**\n * The exit manager is the only part that ends the process. The first exit request starts the\n * shutdown. A later request has no effect, but a repeat signal exits at once when the declaration\n * says `onRepeatSignal: \"exit\"`. The exit code is the code of the exit request, else 1 after an\n * error, else 0.\n */\nexport const EXIT_MACHINE: Machine = {\n ...base(\"exit\", \"The exit manager\"),\n states: { running: { initial: true }, stopping: {}, exited: { final: true } },\n events: {\n \"exit.request\": { kind: \"app\", note: \"SIGINT, SIGTERM, SIGQUIT, a declared process trigger or shutdown()\" },\n \"exit.repeat\": { kind: \"app\", note: \"a trigger or shutdown() while the shutdown runs\" },\n \"startup.fail\": { kind: \"local\" },\n error: { kind: \"local\" },\n \"shutdown.done\": { kind: \"local\" },\n },\n knobs: {\n on_repeat_signal: { key: \"shutdown.onRepeatSignal\", scope: \"service\", unit: null, default: null },\n },\n timers: {},\n transitions: [\n t(\"request\", \"running\", \"exit.request\", \"stopping\"),\n t(\"startup-fail\", \"running\", \"startup.fail\", \"stopping\"),\n t(\"error-running\", \"running\", \"error\", \"running\"),\n t(\"repeat\", \"stopping\", \"exit.repeat\", \"stopping\", {\n guard: \"a process trigger or shutdown() repeats, or a signal repeats and on_repeat_signal is not exit\",\n }),\n t(\"repeat-exit\", \"stopping\", \"exit.repeat\", \"exited\", {\n guard: \"a signal repeats and on_repeat_signal is exit\",\n note: \"the process exits at once with the code 1\",\n }),\n t(\"startup-fail-stopping\", \"stopping\", \"startup.fail\", \"stopping\"),\n t(\"error\", \"stopping\", \"error\", \"stopping\"),\n t(\"exit\", \"stopping\", \"shutdown.done\", \"exited\", {\n note: \"the exit code is the code of the exit request, else 1 after an error, else 0\",\n }),\n ],\n};\n\n/** A watchdog measures how late its own tick comes, and a late tick shows a blocked event loop. */\nexport const WATCHDOG_MACHINE: Machine = {\n ...base(\"watchdog\", \"The watchdog of the event loop\"),\n states: { watching: { initial: true }, blocked: {}, stopped: { final: true } },\n events: { tick: { kind: \"timer\" }, stop: { kind: \"local\" } },\n knobs: {\n tick: { key: \"watchdog.tick\", scope: \"process\", unit: \"s\", default: null },\n threshold: { key: \"watchdog.threshold\", scope: \"process\", unit: \"s\", default: null },\n },\n timers: {\n tick: { duration: { knob: \"tick\", unit: \"s\" }, arms: [\"enter:watching\", \"tick\"], cancels: [\"stop\"], fires: \"tick\" },\n },\n transitions: [\n t(\"on-time\", \"watching\", \"tick\", \"watching\", { guard: \"lateness <= threshold\" }),\n t(\"block\", \"watching\", \"tick\", \"blocked\", { guard: \"lateness > threshold\" }),\n t(\"still-blocked\", \"blocked\", \"tick\", \"blocked\", { guard: \"lateness > threshold\" }),\n t(\"unblock\", \"blocked\", \"tick\", \"watching\", { guard: \"lateness <= threshold\" }),\n t(\"stop\", [\"watching\", \"blocked\"], \"stop\", \"stopped\"),\n ],\n};\n\n/** This function gives the name of a knob for the cap of a phase: `drain` gives `drain_cap`. */\nexport const capKnob = (phase: string): string => `${phase.replace(/[^A-Za-z0-9]+/g, \"_\")}_cap`;\n\n/**\n * This function gives the drain of a declaration as a machine. It has one state for each declared\n * phase, in its sequence, and each state has a timer at its cap. The drain also has the cooperative abort: the\n * cap of the drain less the cooperative window. With the floor `half`, it is half that cap at the\n * least. With the floor `none`, it is 0 at the least.\n */\nexport const drainMachine = (description: ServiceDescription): Machine => {\n const phases = description.shutdown.phases;\n const states: Record<string, { initial?: boolean; final?: boolean; note?: string }> = {\n running: { initial: true },\n };\n for (const phase of phases) states[phase.name] = {};\n states[\"done\"] = { final: true };\n const knobs: Machine[\"knobs\"] = Object.fromEntries([\n ...phases.map((phase) => [\n capKnob(phase.name),\n { key: `shutdown.phases.${phase.name}.cap`, scope: \"service\", unit: \"s\", default: null },\n ]),\n [\"cooperative_window\", { key: \"shutdown.cooperativeWindow\", scope: \"service\", unit: \"s\", default: null }],\n ]);\n const timers: Record<string, Machine[\"timers\"][string]> = {};\n for (const phase of phases)\n timers[`${capKnob(phase.name)}_timer`] = {\n duration: { knob: capKnob(phase.name), unit: \"s\" },\n arms: [`enter:${phase.name}`],\n cancels: [\"phase.done\"],\n fires: \"phase.cap\",\n };\n // the floor of the cooperative abort is half the cap, or 0 for a declaration without a floor\n const floor = description.shutdown.cooperativeFloor === \"none\" ? \"0\" : \"drain_cap / 2\";\n if (phases.some((phase) => phase.name === \"drain\"))\n timers[\"cooperative_abort\"] = {\n duration: { expr: `max(drain_cap - cooperative_window, ${floor})`, unit: \"s\" },\n arms: [\"enter:drain\"],\n cancels: [\"phase.done\", \"phase.cap\"],\n fires: \"drain.cooperative-abort\",\n };\n const transitions: TransitionDef[] = [];\n const order = [\"running\", ...phases.map((phase) => phase.name), \"done\"];\n for (let at = 0; at + 1 < order.length; at += 1) {\n const from = order[at]!;\n const to = order[at + 1]!;\n transitions.push(\n at === 0\n ? t(`begin`, from, \"exit.request\", to)\n : t(`after-${from}`, from, [\"phase.done\", \"phase.cap\"], to, {\n timer: `${capKnob(from)}_timer`,\n note: \"phase.cap: the work of the phase did not end in its cap, and the exit code is 1\",\n }),\n );\n }\n if (phases.some((phase) => phase.name === \"drain\"))\n transitions.push(t(\"cooperative-abort\", \"drain\", \"drain.cooperative-abort\", \"drain\", { timer: \"cooperative_abort\" }));\n // the signal of the service aborts when the sequence passes the poller, or at the end: it leaves\n // the drain where it is\n for (const state of [...phases.map((phase) => phase.name), \"done\"])\n transitions.push(t(`signal-abort-${state}`, state, \"signal.abort\", state));\n return {\n ...base(\"drain\", `The drain of ${description.name}`),\n states,\n events: {\n \"exit.request\": { kind: \"app\" },\n \"phase.done\": { kind: \"local\" },\n \"phase.cap\": { kind: \"timer\" },\n \"drain.cooperative-abort\": { kind: \"timer\" },\n \"signal.abort\": { kind: \"local\" },\n },\n knobs,\n timers,\n transitions,\n };\n};\n\n/** These are the static machines of the runtime, by the name that their events carry. */\nexport const MACHINES: Readonly<Record<Exclude<MachineName, \"drain\" | \"client\">, Machine>> = {\n gate: GATE_MACHINE,\n latch: LATCH_MACHINE,\n window: WINDOW_MACHINE,\n poller: POLLER_MACHINE,\n exit: EXIT_MACHINE,\n watchdog: WATCHDOG_MACHINE,\n};\n"],"mappings":"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"}
@@ -0,0 +1,53 @@
1
+ import "./description.js";
2
+ import "./latch.js";
3
+ /**
4
+ * A histogram of durations counts the polls of a check by how long each one took (B18). Each bound
5
+ * is a fraction of the timeout of the poll, thus the last bound is the timeout. A poll that failed
6
+ * at its timeout goes into `timedOut`, not into a bucket. Thus the histogram marks the timeouts.
7
+ */
8
+ export interface DurationHistogram {
9
+ /** These bounds are in milliseconds, from the smallest. A bucket counts each poll that took more than the bound before it, up to its own bound. */
10
+ readonly le: readonly number[];
11
+ /** These counts are not cumulative: one count for each bound. */
12
+ readonly counts: readonly number[];
13
+ readonly timedOut: number;
14
+ }
15
+ /** An episode of failure starts at the first error of a sequence, and ends at the next pass (B18). */
16
+ export interface Episode {
17
+ /** This time is the first error, in milliseconds on the monotonic clock. */
18
+ readonly start: number;
19
+ /** This time is the pass that ended the episode, or null while the episode continues. */
20
+ readonly end: number | null;
21
+ /** This count is the polls that failed in the episode. */
22
+ readonly failures: number;
23
+ /** This cause is the cause of the first error, with each secret removed. */
24
+ readonly cause: string | null;
25
+ }
26
+ /** The metrics of one check: the count of each outcome, its durations and its last episodes. */
27
+ export interface CheckMetrics {
28
+ readonly outcomes: {
29
+ readonly ok: number;
30
+ readonly error: number;
31
+ readonly indeterminate: number;
32
+ };
33
+ readonly thrown: number;
34
+ readonly forced: number;
35
+ readonly durations: DurationHistogram;
36
+ /** These are the last episodes, from the oldest. The runtime keeps `EPISODES_KEPT` of them. */
37
+ readonly episodes: readonly Episode[];
38
+ }
39
+ /** The metrics of a health runtime. Nothing in them starts a check. */
40
+ export interface HealthMetrics {
41
+ readonly checks: Readonly<Record<string, CheckMetrics>>;
42
+ /** Each count is the transitions of one machine of the runtime, by the key `machine instance from -> to`. */
43
+ readonly transitions: Readonly<Record<string, number>>;
44
+ }
45
+ /** These fractions of the timeout of a poll are the bounds of its histogram. */
46
+ export declare const DURATION_FRACTIONS: readonly number[];
47
+ /** The runtime keeps this many episodes of each check. */
48
+ export declare const EPISODES_KEPT = 8;
49
+ /**
50
+ * This function removes the secrets that a cause can hold. These are the user and the password of a
51
+ * URL, and the value of a key, for example `password=`. A driver error can hold a connection string.
52
+ */
53
+ export declare const redact: (cause: string) => string;
@@ -0,0 +1,111 @@
1
+ import { valueIn } from "@mark1russell7/quantity";
2
+ // src/metrics.ts
3
+ /** These fractions of the timeout of a poll are the bounds of its histogram. */
4
+ const DURATION_FRACTIONS = [
5
+ .05,
6
+ .1,
7
+ .25,
8
+ .5,
9
+ .75,
10
+ 1
11
+ ];
12
+ /** The runtime keeps this many episodes of each check. */
13
+ const EPISODES_KEPT = 8;
14
+ /**
15
+ * This function removes the secrets that a cause can hold. These are the user and the password of a
16
+ * URL, and the value of a key, for example `password=`. A driver error can hold a connection string.
17
+ */
18
+ const redact = (cause) => cause.replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]*@/gi, "$1***@").replace(/\b(password|passwd|pwd|secret|token|api[_-]?key|auth)(\s*[=:]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi, "$1$2***");
19
+ /** This function makes a meter. */
20
+ const meter = () => {
21
+ const checks = /* @__PURE__ */ new Map();
22
+ const transitions = /* @__PURE__ */ new Map();
23
+ const add = (check) => {
24
+ if (checks.has(check.name)) return;
25
+ const timeout = valueIn(check.poll.timeout, "ms");
26
+ checks.set(check.name, {
27
+ ok: 0,
28
+ error: 0,
29
+ indeterminate: 0,
30
+ thrown: 0,
31
+ forced: 0,
32
+ le: DURATION_FRACTIONS.map((fraction) => fraction * timeout),
33
+ counts: DURATION_FRACTIONS.map(() => 0),
34
+ timedOut: 0,
35
+ episodes: [],
36
+ open: null
37
+ });
38
+ };
39
+ const close = (counted, end) => {
40
+ if (counted.open === null) return null;
41
+ return {
42
+ start: counted.open.start,
43
+ end,
44
+ failures: counted.open.failures,
45
+ cause: counted.open.cause
46
+ };
47
+ };
48
+ const poll = (check, result) => {
49
+ add(check);
50
+ const counted = checks.get(check.name);
51
+ counted[result.outcome] += 1;
52
+ if (result.thrown) counted.thrown += 1;
53
+ if (result.forced) counted.forced += 1;
54
+ if (result.timedOut) counted.timedOut += 1;
55
+ else {
56
+ const at = counted.le.findIndex((bound) => result.took <= bound);
57
+ const bucket = at === -1 ? counted.counts.length - 1 : at;
58
+ counted.counts[bucket] = (counted.counts[bucket] ?? 0) + 1;
59
+ }
60
+ if (result.outcome === "error") {
61
+ if (counted.open === null) counted.open = {
62
+ start: result.at,
63
+ failures: 0,
64
+ cause: result.cause === null ? null : redact(result.cause)
65
+ };
66
+ counted.open.failures += 1;
67
+ } else if (result.outcome === "ok" && counted.open !== null) {
68
+ counted.episodes.push(close(counted, result.at));
69
+ counted.open = null;
70
+ if (counted.episodes.length > 8) counted.episodes.shift();
71
+ }
72
+ };
73
+ const event = (event) => {
74
+ const key = `${event.machine} ${event.instance} ${event.from} -> ${event.to}`;
75
+ transitions.set(key, (transitions.get(key) ?? 0) + 1);
76
+ };
77
+ const metrics = () => {
78
+ const out = {};
79
+ for (const [name, counted] of checks) {
80
+ const open = close(counted, null);
81
+ out[name] = {
82
+ outcomes: {
83
+ ok: counted.ok,
84
+ error: counted.error,
85
+ indeterminate: counted.indeterminate
86
+ },
87
+ thrown: counted.thrown,
88
+ forced: counted.forced,
89
+ durations: {
90
+ le: [...counted.le],
91
+ counts: [...counted.counts],
92
+ timedOut: counted.timedOut
93
+ },
94
+ episodes: open === null ? [...counted.episodes] : [...counted.episodes, open].slice(-8)
95
+ };
96
+ }
97
+ return {
98
+ checks: out,
99
+ transitions: Object.fromEntries(transitions)
100
+ };
101
+ };
102
+ return {
103
+ add,
104
+ poll,
105
+ event,
106
+ metrics
107
+ };
108
+ };
109
+ export { DURATION_FRACTIONS, EPISODES_KEPT, meter, redact };
110
+
111
+ //# sourceMappingURL=metrics.js.map