@mark1russell7/service 0.8.19 → 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 (331) hide show
  1. package/build/backoff.d.ts +44 -2
  2. package/build/{builder-zO48Vgoj.d.ts → builder.d.ts} +14 -101
  3. package/build/builder.js +499 -0
  4. package/build/builder.js.map +1 -0
  5. package/build/{call-context-DDhcVvn5.d.ts → call-context.d.ts} +3 -4
  6. package/build/channel.d.ts +1 -1
  7. package/build/{core-BSzt4RI2.d.ts → client/core.d.ts} +32 -61
  8. package/build/{machine-BhVeHr_m.js → client/core.js} +4 -153
  9. package/build/client/core.js.map +1 -0
  10. package/build/{dial-ChwIcvd4.d.ts → client/dial.d.ts} +3 -4
  11. package/build/client/dial.js +52 -0
  12. package/build/client/dial.js.map +1 -0
  13. package/build/client/machine.js +29 -0
  14. package/build/client/machine.js.map +1 -0
  15. package/build/client/meets.d.ts +35 -0
  16. package/build/client/meets.js +78 -0
  17. package/build/client/meets.js.map +1 -0
  18. package/build/clock.d.ts +1 -1
  19. package/build/conformance.d.ts +122 -0
  20. package/build/conformance.js +470 -0
  21. package/build/conformance.js.map +1 -0
  22. package/build/contract.d.ts +28 -0
  23. package/build/contract.js +184 -0
  24. package/build/contract.js.map +1 -0
  25. package/build/description.d.ts +161 -0
  26. package/build/description.js +11 -0
  27. package/build/description.js.map +1 -0
  28. package/build/drains.js +35 -0
  29. package/build/drains.js.map +1 -0
  30. package/build/events.d.ts +25 -0
  31. package/build/fakes.d.ts +43 -0
  32. package/build/fakes.js +93 -0
  33. package/build/fakes.js.map +1 -0
  34. package/build/grpc/client.d.ts +153 -0
  35. package/build/grpc/client.js +474 -0
  36. package/build/grpc/client.js.map +1 -0
  37. package/build/grpc/connection.d.ts +97 -0
  38. package/build/grpc/connection.js +59 -0
  39. package/build/grpc/connection.js.map +1 -0
  40. package/build/grpc/machine.d.ts +12 -0
  41. package/build/grpc/machine.js +149 -0
  42. package/build/grpc/machine.js.map +1 -0
  43. package/build/grpc/meets.d.ts +14 -0
  44. package/build/grpc/meets.js +105 -0
  45. package/build/grpc/meets.js.map +1 -0
  46. package/build/grpc/starting.d.ts +33 -0
  47. package/build/grpc/starting.js +89 -0
  48. package/build/grpc/starting.js.map +1 -0
  49. package/build/grpc.d.ts +9 -303
  50. package/build/grpc.js +7 -854
  51. package/build/health.d.ts +93 -0
  52. package/build/health.js +223 -0
  53. package/build/health.js.map +1 -0
  54. package/build/heartbeat.d.ts +1 -1
  55. package/build/host/discovery.d.ts +61 -0
  56. package/build/host/discovery.js +113 -0
  57. package/build/host/discovery.js.map +1 -0
  58. package/build/host/env.d.ts +14 -0
  59. package/build/host/env.js +57 -0
  60. package/build/host/env.js.map +1 -0
  61. package/build/host/fakes.d.ts +82 -0
  62. package/build/host/fakes.js +239 -0
  63. package/build/host/fakes.js.map +1 -0
  64. package/build/host/group.d.ts +142 -0
  65. package/build/host/group.js +517 -0
  66. package/build/host/group.js.map +1 -0
  67. package/build/host/install.d.ts +96 -0
  68. package/build/host/install.js +330 -0
  69. package/build/host/install.js.map +1 -0
  70. package/build/host/lock.d.ts +78 -0
  71. package/build/host/lock.js +190 -0
  72. package/build/host/lock.js.map +1 -0
  73. package/build/host/logs.d.ts +26 -0
  74. package/build/host/logs.js +48 -0
  75. package/build/host/logs.js.map +1 -0
  76. package/build/host/node.d.ts +14 -0
  77. package/build/host/node.js +309 -0
  78. package/build/host/node.js.map +1 -0
  79. package/build/{ports-B1ayTL-j.d.ts → host/ports.d.ts} +15 -16
  80. package/build/host/ports.js +17 -0
  81. package/build/host/ports.js.map +1 -0
  82. package/build/host/probes.d.ts +51 -0
  83. package/build/host/probes.js +139 -0
  84. package/build/host/probes.js.map +1 -0
  85. package/build/host/processes.d.ts +32 -0
  86. package/build/host/processes.js +63 -0
  87. package/build/host/processes.js.map +1 -0
  88. package/build/host/render.d.ts +84 -0
  89. package/build/host/render.js +235 -0
  90. package/build/host/render.js.map +1 -0
  91. package/build/host/watch.d.ts +90 -0
  92. package/build/host/watch.js +165 -0
  93. package/build/host/watch.js.map +1 -0
  94. package/build/host.d.ts +13 -671
  95. package/build/host.js +12 -2126
  96. package/build/http/answers.js +29 -0
  97. package/build/http/answers.js.map +1 -0
  98. package/build/http/fake-server.js +61 -0
  99. package/build/http/fake-server.js.map +1 -0
  100. package/build/http/outcome.d.ts +115 -0
  101. package/build/http/outcome.js +325 -0
  102. package/build/http/outcome.js.map +1 -0
  103. package/build/http/probes.d.ts +83 -0
  104. package/build/http/probes.js +232 -0
  105. package/build/http/probes.js.map +1 -0
  106. package/build/http/transport.d.ts +165 -0
  107. package/build/http/transport.js +517 -0
  108. package/build/http/transport.js.map +1 -0
  109. package/build/http-client/client.d.ts +121 -0
  110. package/build/http-client/client.js +330 -0
  111. package/build/http-client/client.js.map +1 -0
  112. package/build/http-client/connection.d.ts +78 -0
  113. package/build/http-client/connection.js +54 -0
  114. package/build/http-client/connection.js.map +1 -0
  115. package/build/http-client/machine.d.ts +14 -0
  116. package/build/http-client/machine.js +109 -0
  117. package/build/http-client/machine.js.map +1 -0
  118. package/build/http-client/meets.d.ts +11 -0
  119. package/build/http-client/meets.js +74 -0
  120. package/build/http-client/meets.js.map +1 -0
  121. package/build/http-client/session.d.ts +87 -0
  122. package/build/http-client/session.js +99 -0
  123. package/build/http-client/session.js.map +1 -0
  124. package/build/http-client/starting.d.ts +25 -0
  125. package/build/http-client/starting.js +65 -0
  126. package/build/http-client/starting.js.map +1 -0
  127. package/build/http-client.d.ts +9 -330
  128. package/build/http-client.js +8 -707
  129. package/build/http.d.ts +5 -353
  130. package/build/http.js +3 -1086
  131. package/build/identity.d.ts +16 -0
  132. package/build/identity.js +44 -0
  133. package/build/identity.js.map +1 -0
  134. package/build/index.d.ts +35 -412
  135. package/build/index.js +24 -3277
  136. package/build/knobs.d.ts +1 -0
  137. package/build/{knobs-BJcz6m01.js → knobs.js} +2 -34
  138. package/build/knobs.js.map +1 -0
  139. package/build/latch.d.ts +29 -0
  140. package/build/latch.js +122 -0
  141. package/build/latch.js.map +1 -0
  142. package/build/{rules-HyFCBStQ.d.ts → law.d.ts} +19 -37
  143. package/build/law.js +149 -0
  144. package/build/law.js.map +1 -0
  145. package/build/lifecycle.d.ts +144 -0
  146. package/build/lifecycle.js +411 -0
  147. package/build/lifecycle.js.map +1 -0
  148. package/build/limiter/machine.d.ts +40 -0
  149. package/build/limiter/machine.js +279 -0
  150. package/build/limiter/machine.js.map +1 -0
  151. package/build/{policy-CBcK2XGg.d.ts → limiter/policy.d.ts} +28 -29
  152. package/build/{policy-UYALkqVq.js → limiter/policy.js} +10 -9
  153. package/build/limiter/policy.js.map +1 -0
  154. package/build/{limiter-BNKnwzeY.d.ts → limiter/quota.d.ts} +32 -74
  155. package/build/{limiter-DrM0PQV9.js → limiter/quota.js} +3 -418
  156. package/build/limiter/quota.js.map +1 -0
  157. package/build/{store-DFwFKrsB.d.ts → limiter/store.d.ts} +10 -11
  158. package/build/limiter/store.js +145 -0
  159. package/build/limiter/store.js.map +1 -0
  160. package/build/limiter.d.ts +4 -3
  161. package/build/limiter.js +4 -2
  162. package/build/lint.d.ts +152 -0
  163. package/build/lint.js +576 -0
  164. package/build/lint.js.map +1 -0
  165. package/build/logger.d.ts +71 -0
  166. package/build/logger.js +183 -0
  167. package/build/logger.js.map +1 -0
  168. package/build/machines.d.ts +41 -0
  169. package/build/machines.js +451 -0
  170. package/build/machines.js.map +1 -0
  171. package/build/metrics.d.ts +53 -0
  172. package/build/metrics.js +111 -0
  173. package/build/metrics.js.map +1 -0
  174. package/build/mongodb/client.d.ts +131 -0
  175. package/build/mongodb/client.js +388 -0
  176. package/build/mongodb/client.js.map +1 -0
  177. package/build/mongodb/connection.d.ts +112 -0
  178. package/build/mongodb/connection.js +12 -0
  179. package/build/mongodb/connection.js.map +1 -0
  180. package/build/mongodb/machine.d.ts +14 -0
  181. package/build/mongodb/machine.js +122 -0
  182. package/build/mongodb/machine.js.map +1 -0
  183. package/build/mongodb/meets.d.ts +15 -0
  184. package/build/mongodb/meets.js +103 -0
  185. package/build/mongodb/meets.js.map +1 -0
  186. package/build/mongodb/starting.d.ts +29 -0
  187. package/build/mongodb/starting.js +77 -0
  188. package/build/mongodb/starting.js.map +1 -0
  189. package/build/mongodb.d.ts +8 -296
  190. package/build/mongodb.js +7 -682
  191. package/build/operation.d.ts +27 -0
  192. package/build/{operation-DF73RZOI.js → operation.js} +2 -2
  193. package/build/operation.js.map +1 -0
  194. package/build/otel.d.ts +2 -2
  195. package/build/pg/client.d.ts +96 -0
  196. package/build/pg/client.js +277 -0
  197. package/build/pg/client.js.map +1 -0
  198. package/build/pg/connection.d.ts +75 -0
  199. package/build/pg/connection.js +11 -0
  200. package/build/pg/connection.js.map +1 -0
  201. package/build/pg/machine.d.ts +13 -0
  202. package/build/pg/machine.js +111 -0
  203. package/build/pg/machine.js.map +1 -0
  204. package/build/pg/meets.d.ts +14 -0
  205. package/build/pg/meets.js +83 -0
  206. package/build/pg/meets.js.map +1 -0
  207. package/build/pg/starting.d.ts +26 -0
  208. package/build/pg/starting.js +62 -0
  209. package/build/pg/starting.js.map +1 -0
  210. package/build/pg.d.ts +8 -219
  211. package/build/pg.js +7 -525
  212. package/build/poller.d.ts +9 -0
  213. package/build/poller.js +152 -0
  214. package/build/poller.js.map +1 -0
  215. package/build/process.d.ts +114 -0
  216. package/build/process.js +170 -0
  217. package/build/process.js.map +1 -0
  218. package/build/profiles.d.ts +68 -0
  219. package/build/profiles.js +120 -0
  220. package/build/profiles.js.map +1 -0
  221. package/build/{queue-DXdw1vLO.d.ts → queue.d.ts} +16 -29
  222. package/build/queue.js +279 -0
  223. package/build/queue.js.map +1 -0
  224. package/build/rabbitmq/client.d.ts +144 -0
  225. package/build/rabbitmq/client.js +426 -0
  226. package/build/rabbitmq/client.js.map +1 -0
  227. package/build/rabbitmq/connection.d.ts +91 -0
  228. package/build/rabbitmq/connection.js +15 -0
  229. package/build/rabbitmq/connection.js.map +1 -0
  230. package/build/rabbitmq/machine.d.ts +13 -0
  231. package/build/rabbitmq/machine.js +159 -0
  232. package/build/rabbitmq/machine.js.map +1 -0
  233. package/build/rabbitmq/meets.d.ts +12 -0
  234. package/build/rabbitmq/meets.js +96 -0
  235. package/build/rabbitmq/meets.js.map +1 -0
  236. package/build/rabbitmq/starting.d.ts +27 -0
  237. package/build/rabbitmq/starting.js +67 -0
  238. package/build/rabbitmq/starting.js.map +1 -0
  239. package/build/rabbitmq.d.ts +8 -283
  240. package/build/rabbitmq.js +7 -742
  241. package/build/redis/client.d.ts +86 -0
  242. package/build/redis/client.js +285 -0
  243. package/build/redis/client.js.map +1 -0
  244. package/build/redis/connection.d.ts +57 -0
  245. package/build/redis/connection.js +11 -0
  246. package/build/redis/connection.js.map +1 -0
  247. package/build/redis/limiter.d.ts +43 -0
  248. package/build/redis/limiter.js +164 -0
  249. package/build/redis/limiter.js.map +1 -0
  250. package/build/redis/machine.d.ts +12 -0
  251. package/build/redis/machine.js +144 -0
  252. package/build/redis/machine.js.map +1 -0
  253. package/build/redis/meets.d.ts +11 -0
  254. package/build/redis/meets.js +75 -0
  255. package/build/redis/meets.js.map +1 -0
  256. package/build/redis/operations.d.ts +5 -0
  257. package/build/redis/operations.js +114 -0
  258. package/build/redis/operations.js.map +1 -0
  259. package/build/redis.d.ts +10 -207
  260. package/build/redis.js +9 -771
  261. package/build/requests.d.ts +66 -0
  262. package/build/requests.js +279 -0
  263. package/build/requests.js.map +1 -0
  264. package/build/retrier.d.ts +62 -0
  265. package/build/{retrier-Dnjhvxol.js → retrier.js} +2 -2
  266. package/build/retrier.js.map +1 -0
  267. package/build/routes.d.ts +35 -0
  268. package/build/routes.js +77 -0
  269. package/build/routes.js.map +1 -0
  270. package/build/rules.d.ts +19 -2
  271. package/build/stops.d.ts +51 -0
  272. package/build/stops.js +86 -0
  273. package/build/stops.js.map +1 -0
  274. package/build/testing.d.ts +8 -270
  275. package/build/testing.js +4 -1027
  276. package/build/testing.js.map +1 -1
  277. package/build/timing.d.ts +63 -0
  278. package/build/{timing-DZl36uXs.js → timing.js} +2 -2
  279. package/build/timing.js.map +1 -0
  280. package/build/units.d.ts +17 -0
  281. package/build/units.js +236 -0
  282. package/build/units.js.map +1 -0
  283. package/build/watchdog.d.ts +34 -0
  284. package/build/watchdog.js +53 -0
  285. package/build/watchdog.js.map +1 -0
  286. package/build/websocket/client.d.ts +136 -0
  287. package/build/websocket/client.js +422 -0
  288. package/build/websocket/client.js.map +1 -0
  289. package/build/websocket/connection.d.ts +83 -0
  290. package/build/websocket/connection.js +57 -0
  291. package/build/websocket/connection.js.map +1 -0
  292. package/build/websocket/machine.d.ts +12 -0
  293. package/build/websocket/machine.js +155 -0
  294. package/build/websocket/machine.js.map +1 -0
  295. package/build/websocket/meets.d.ts +14 -0
  296. package/build/websocket/meets.js +92 -0
  297. package/build/websocket/meets.js.map +1 -0
  298. package/build/websocket/starting.d.ts +25 -0
  299. package/build/websocket/starting.js +69 -0
  300. package/build/websocket/starting.js.map +1 -0
  301. package/build/websocket.d.ts +9 -264
  302. package/build/websocket.js +8 -774
  303. package/build/worker.d.ts +92 -0
  304. package/build/worker.js +153 -0
  305. package/build/worker.js.map +1 -0
  306. package/package.json +4 -3
  307. package/build/backoff-QTRGfkEK.d.ts +0 -45
  308. package/build/clock-DpVgpY4h.d.ts +0 -2
  309. package/build/grpc.js.map +0 -1
  310. package/build/host.js.map +0 -1
  311. package/build/http-client.js.map +0 -1
  312. package/build/http.js.map +0 -1
  313. package/build/index.js.map +0 -1
  314. package/build/knobs-BJcz6m01.js.map +0 -1
  315. package/build/lifecycle-D0J-zwZF.d.ts +0 -374
  316. package/build/limiter-DrM0PQV9.js.map +0 -1
  317. package/build/logger-B6drv9w0.d.ts +0 -488
  318. package/build/machine-BhVeHr_m.js.map +0 -1
  319. package/build/mongodb.js.map +0 -1
  320. package/build/operation-DF73RZOI.js.map +0 -1
  321. package/build/pg.js.map +0 -1
  322. package/build/policy-UYALkqVq.js.map +0 -1
  323. package/build/process-7R9M29wN.js +0 -437
  324. package/build/process-7R9M29wN.js.map +0 -1
  325. package/build/rabbitmq.js.map +0 -1
  326. package/build/redis.js.map +0 -1
  327. package/build/requests-DD2ALv0_.js +0 -583
  328. package/build/requests-DD2ALv0_.js.map +0 -1
  329. package/build/retrier-Dnjhvxol.js.map +0 -1
  330. package/build/timing-DZl36uXs.js.map +0 -1
  331. package/build/websocket.js.map +0 -1
package/build/lint.js ADDED
@@ -0,0 +1,576 @@
1
+ import { backoffBand } from "./backoff.js";
2
+ import { compression, evaluate, symbolsOf, verdictOf } from "./law.js";
3
+ import { idleSpan, longestRetryAfter, retryAfterSeconds } from "./limiter/policy.js";
4
+ import { failSpan } from "./timing.js";
5
+ import { convertExact, convertible, rationals } from "@mark1russell7/quantity";
6
+ // src/lint.ts
7
+ /** The law binds this statistic of a distribution. */
8
+ const LAW_STATISTIC = "p99";
9
+ /** These are the identifiers of the rules that each declaration gets. */
10
+ const SERVICE_RULES = [
11
+ "O04",
12
+ "O09",
13
+ "O10",
14
+ "O11",
15
+ "O12",
16
+ "O13",
17
+ "O14",
18
+ "O15",
19
+ "O16",
20
+ "O17",
21
+ "O18",
22
+ "O19",
23
+ "O20",
24
+ "O21",
25
+ "O22",
26
+ "O23",
27
+ "O27",
28
+ "O29",
29
+ "O30"
30
+ ];
31
+ /**
32
+ * These are the two rules of the law for a keyed limiter, as data. The caller of `lint()` gives
33
+ * them, as it gives each other rule. Each one applies one time for each limiter.
34
+ * - O29: the longest `Retry-After` of a limiter is at most the retry window of its caller. Its
35
+ * second inequality applies the same bound to a new key at the cap of keys.
36
+ * Otherwise the caller stops before the limit lets its call in, and a refusal becomes a failure.
37
+ * - O30: the least delay of a caller before it sends a refused call again is at least the longest
38
+ * `Retry-After` of the policy. Otherwise a caller that does not read the header sends again too
39
+ * early, and the limiter refuses each early call again.
40
+ *
41
+ * The identifiers O29 and O30 are provisional. The private corpus of the law (R3, track B) has 28
42
+ * rules, O01 to O28. It does not have these two rules yet, thus they take the next two identifiers.
43
+ */
44
+ const LIMITER_RULES = [{
45
+ id: "O29",
46
+ rule: "the longest Retry-After of a limiter, at its cap of keys too, is at most the retry window of its caller",
47
+ window: "the caller stops before the limit lets its call in, thus a refusal becomes a failure",
48
+ expr: {
49
+ lhs: { terms: [{
50
+ knob: "retry_after",
51
+ coef: 1,
52
+ at: "limiter"
53
+ }] },
54
+ op: "<=",
55
+ rhs: { terms: [{
56
+ knob: "client_retry_window",
57
+ coef: 1,
58
+ at: "caller"
59
+ }] },
60
+ margin: 0
61
+ },
62
+ expr_more: [{
63
+ lhs: { terms: [{
64
+ knob: "retry_after_at_cap",
65
+ coef: 1,
66
+ at: "limiter"
67
+ }] },
68
+ op: "<=",
69
+ rhs: { terms: [{
70
+ knob: "client_retry_window",
71
+ coef: 1,
72
+ at: "caller"
73
+ }] },
74
+ margin: 0
75
+ }]
76
+ }, {
77
+ id: "O30",
78
+ rule: "the least delay of a caller before it sends a refused call again is at least the longest Retry-After of the limiter",
79
+ window: "a caller that does not read Retry-After sends again too early, and the limiter refuses each early call again",
80
+ expr: {
81
+ lhs: { terms: [{
82
+ knob: "retry_delay",
83
+ coef: 1,
84
+ at: "caller"
85
+ }] },
86
+ op: ">=",
87
+ rhs: { terms: [{
88
+ knob: "retry_after",
89
+ coef: 1,
90
+ at: "limiter"
91
+ }] },
92
+ margin: 0
93
+ }
94
+ }];
95
+ /** This function gives a finite amount in seconds. */
96
+ const secondsOf = (amount) => rationals.toNumber(convertExact(rationals.fromNumber(amount.value), amount.unit, "s"));
97
+ /** This function gives an amount, or no bound, as the law binds it. */
98
+ const boundOf = (amount) => amount.value === "infinite" ? "inf" : secondsOf(amount);
99
+ /**
100
+ * This function gives a value of the scenario as the law binds it, with its epoch. A distribution
101
+ * binds its p99. A distribution without a p99 binds nothing, thus each rule that reads it depends.
102
+ */
103
+ const claimOf = (value) => {
104
+ if (!("epoch" in value)) return {
105
+ bound: boundOf(value),
106
+ epoch: null
107
+ };
108
+ if ("value" in value) return {
109
+ bound: boundOf(value.value),
110
+ epoch: value.epoch
111
+ };
112
+ const statistic = value.distribution["p99"];
113
+ return {
114
+ bound: statistic === void 0 ? void 0 : secondsOf(statistic),
115
+ epoch: value.epoch
116
+ };
117
+ };
118
+ /** This function binds each value of a part of the scenario, at the symbol that `at` gives, and records its epoch. */
119
+ const bindScenario = (values, at, bind, epochs) => {
120
+ for (const [symbol, value] of Object.entries(values)) {
121
+ const claim = claimOf(value);
122
+ const key = at(symbol);
123
+ epochs[key] = claim.epoch;
124
+ if (claim.bound !== void 0) bind[key] = claim.bound;
125
+ else delete bind[key];
126
+ }
127
+ };
128
+ /** This function tells if a unit is a time. A unit that the package does not know is not a time. */
129
+ const isTime = (unit) => {
130
+ try {
131
+ return convertible(unit, "s");
132
+ } catch {
133
+ return false;
134
+ }
135
+ };
136
+ /** This function gives the largest of some numbers of seconds, or undefined when there are none. */
137
+ const most = (values) => values.length === 0 ? void 0 : Math.max(...values);
138
+ /** This function gives what the declaration tells about the service, as symbols of the law, and the source of each. */
139
+ const serviceBindings = (svc, scenario) => {
140
+ const bind = {};
141
+ const from = {};
142
+ const epochs = {};
143
+ const set = (symbol, bound, said) => {
144
+ if (bound === void 0) return;
145
+ bind[symbol] = bound;
146
+ from[symbol] = said;
147
+ };
148
+ const gating = svc.checks.filter((check) => check.gates !== null);
149
+ const readinessChecks = gating.filter((check) => check.gates === "readiness");
150
+ const livenessChecks = gating.filter((check) => check.gates === "liveness");
151
+ set("check_poll_interval@service", most(gating.map((check) => secondsOf(check.poll.interval))), "the slowest gating check's interval");
152
+ set("check_timeout@service", most(gating.map((check) => secondsOf(check.poll.timeout))), "the longest gating check's timeout");
153
+ set("slowest_poll@service", most(gating.map((check) => secondsOf(check.poll.timeout) + secondsOf(check.poll.interval) * (1 + check.poll.jitter))), "a check's timeout plus one jittered interval, at its slowest");
154
+ const windowOf = (checks, policy) => most(checks.map((check) => secondsOf(failSpan(svc.policies[policy], check.poll, "timeout").max)));
155
+ const readiness = windowOf(readinessChecks, "readiness");
156
+ const liveness = windowOf(livenessChecks, "liveness");
157
+ set("readiness_detection_window@service", readiness, "the readiness latch, failing by timeout");
158
+ if (readiness !== void 0) set("readiness_detection_window@pod", readiness + secondsOf(scenario.probes.readiness), "the readiness latch, then the kubelet's probe");
159
+ if (liveness !== void 0) set("liveness_detection_window@pod", liveness + secondsOf(scenario.probes.liveness), "the liveness window, then the kubelet's probe");
160
+ set("startup_budget@pod", secondsOf(svc.policies.startup), "the declared startup budget");
161
+ set("process_drain_time@process", svc.shutdown.phases.reduce((total, phase) => total + secondsOf(phase.cap), 0), `the shutdown phases' caps, summed (${svc.shutdown.phases.map((phase) => phase.name).join(", ")})`);
162
+ set("cooperative_window@process", boundOf(svc.shutdown.cooperativeWindow), "the declared cooperative window");
163
+ const hold = svc.shutdown.phases.find((phase) => phase.name === "fail readiness");
164
+ set("readiness_hold@process", hold === void 0 ? 0 : secondsOf(hold.cap), hold === void 0 ? "no fail readiness phase: the intake stops at once after the signal" : "the cap of the fail readiness phase, which holds while the endpoints update");
165
+ const capOf = (name) => {
166
+ const phase = svc.shutdown.phases.find((each) => each.name === name);
167
+ return phase === void 0 ? void 0 : secondsOf(phase.cap);
168
+ };
169
+ set("drain_phase_cap@process", capOf("drain"), "the cap of the drain phase alone");
170
+ set("close_phase_cap@process", capOf("close transports"), "the cap of the close transports phase alone");
171
+ bindScenario(scenario.platform, (symbol) => symbol, bind, epochs);
172
+ for (const [symbol, epoch] of Object.entries(epochs)) if (bind[symbol] === void 0) delete from[symbol];
173
+ else from[symbol] = epoch === null ? "the scenario" : `the scenario, for ${epoch}`;
174
+ return {
175
+ bind,
176
+ from,
177
+ epochs
178
+ };
179
+ };
180
+ /** This function gives the client knobs of a dependency at @client, and the values of the scenario at its own hops. */
181
+ const dependencyBindings = (dependency, scenario) => {
182
+ const bind = {};
183
+ const epochs = {};
184
+ for (const [knob, amount] of Object.entries(dependency.knobs)) bind[`${knob}@client`] = boundOf(amount);
185
+ bindScenario(scenario.dependencies?.[dependency.name] ?? {}, (symbol) => symbol.includes("@") ? symbol : `${symbol}@dependency`, bind, epochs);
186
+ return {
187
+ bind,
188
+ epochs
189
+ };
190
+ };
191
+ /**
192
+ * These are the hops of the law at which the knobs of a transport bind, by its kind. A worker does
193
+ * its units as a consumer does, thus both bind at `consumer` (O20). A server binds at `server`, in a
194
+ * scope of its own. In the scope of a dependency, `@server` is the server of that dependency. Thus
195
+ * the knobs of a server of the service do not bind there, or O19 pairs the wrong two sides.
196
+ */
197
+ const TRANSPORT_HOPS = {
198
+ server: "server",
199
+ consumer: "consumer",
200
+ worker: "consumer"
201
+ };
202
+ /**
203
+ * This function gives the time knobs of a transport at the hop of its kind, and the values of the
204
+ * scenario for the transport. These values are of the source of a consumer, or of the clients of a
205
+ * server. A knob with a hop in its name binds at that hop. A count binds no symbol.
206
+ */
207
+ const transportBindings = (transport, hop, scenario) => {
208
+ const bind = {};
209
+ const epochs = {};
210
+ for (const [knob, amount] of Object.entries(transport.knobs)) {
211
+ if (!isTime(amount.unit)) continue;
212
+ bind[knob.includes("@") ? knob : `${knob}@${hop}`] = boundOf(amount);
213
+ }
214
+ bindScenario(scenario.transports?.[transport.name] ?? {}, (symbol) => symbol, bind, epochs);
215
+ return {
216
+ bind,
217
+ epochs
218
+ };
219
+ };
220
+ /**
221
+ * This function gives the symbols of a limiter, and the values of the scenario for its callers.
222
+ * - `retry_after@limiter` is the longest `Retry-After` of a refusal by the policy, in whole seconds.
223
+ * It is one interval of the bucket, or one window, as the HTTP edge sends it.
224
+ * - `retry_after_at_cap@limiter` is the longest `Retry-After` of a new key at the cap of keys. It is
225
+ * the idle span, `burst / rate` or one window.
226
+ */
227
+ const limiterBindings = (limiter, scenario) => {
228
+ const bind = {
229
+ "retry_after@limiter": retryAfterSeconds(longestRetryAfter(limiter.policy)),
230
+ "retry_after_at_cap@limiter": retryAfterSeconds(idleSpan(limiter.policy))
231
+ };
232
+ const epochs = {};
233
+ bindScenario(scenario.limiters?.[limiter.name] ?? {}, (symbol) => symbol.includes("@") ? symbol : `${symbol}@caller`, bind, epochs);
234
+ return {
235
+ bind,
236
+ epochs
237
+ };
238
+ };
239
+ const SCOPED = /@(client|dependency|server)$/;
240
+ const SERVER_SCOPED = /@server$/;
241
+ const TRANSPORT_SCOPED = /@consumer$/;
242
+ const LIMITER_SCOPED = /@(limiter|caller)$/;
243
+ /** This identifier is the rule of the findings about a field that the declaration does not give. */
244
+ const DECLARATION_RULE = "declaration";
245
+ /**
246
+ * This function gives a finding for each field of the shutdown that a description does not give.
247
+ * `describe()` refuses such a declaration. A description from another source, for example the
248
+ * JSON of 0.4, can lack the field. The verdict is `depends`, and `unbound` names the field.
249
+ */
250
+ const declarationFindings = (svc) => svc.shutdown.onRepeatSignal === void 0 ? [{
251
+ rule: DECLARATION_RULE,
252
+ scope: svc.name,
253
+ verdict: "depends",
254
+ statement: "the declaration tells what a signal does while the shutdown runs: ignore or exit",
255
+ window: "a repeat signal has no declared effect",
256
+ evaluated: [],
257
+ unbound: ["shutdown.onRepeatSignal"]
258
+ }] : [];
259
+ /** This identifier is the rule of the findings for two parts that have one name in the scopes of a rule. */
260
+ const NAME_RULE = "unique-names";
261
+ /**
262
+ * This function gives a finding for each name that two parts share in one set of scopes. A rule
263
+ * about a client applies to each dependency and each server transport. A rule about a consumer
264
+ * applies to each consumer and each worker, and a rule about a limiter to each limiter. Two parts
265
+ * with one name in a set give findings with one scope, thus a reader cannot tell them apart.
266
+ */
267
+ const nameFindings = (svc) => {
268
+ return [
269
+ ["the dependencies and the server transports", [...svc.dependencies.map((each) => each.name), ...svc.transports.filter((each) => each.kind === "server").map((each) => each.name)]],
270
+ ["the consumers and the workers", svc.transports.filter((each) => each.kind !== "server").map((each) => each.name)],
271
+ ["the limiters", (svc.limiters ?? []).map((each) => each.name)]
272
+ ].flatMap(([set, names]) => [...new Set(names.filter((name, index) => names.indexOf(name) !== index))].map((name) => ({
273
+ rule: NAME_RULE,
274
+ scope: name,
275
+ verdict: "violated",
276
+ statement: `each of ${set} has a name of its own`,
277
+ window: `two parts have the name ${name}, thus their findings have one scope`,
278
+ evaluated: [],
279
+ unbound: []
280
+ })));
281
+ };
282
+ /** This identifier is the rule of the findings about the stall time of a progress check (`Check.marks`). */
283
+ const PROGRESS_RULE = "progress";
284
+ /**
285
+ * This rule compares the stall time of a progress check with the longest gap between two marks of
286
+ * the slowest loop that it names. A shorter stall time trips the check while each loop turns on time.
287
+ */
288
+ const PROGRESS_LAW = {
289
+ id: PROGRESS_RULE,
290
+ rule: "the stall time of a progress check is at least the longest gap between two marks of the slowest loop that it names",
291
+ window: "a loop that turns on time can trip the check",
292
+ expr: {
293
+ lhs: { terms: [{
294
+ knob: "stall",
295
+ coef: 1,
296
+ at: "check"
297
+ }] },
298
+ op: ">=",
299
+ rhs: { terms: [{
300
+ knob: "mark_gap",
301
+ coef: 1,
302
+ at: "loop"
303
+ }] },
304
+ margin: 0
305
+ }
306
+ };
307
+ /** These are the knobs of a worker that bound the gap between two of its marks. */
308
+ const WORKER_GAP_KNOBS = [
309
+ "worker_sleep",
310
+ "unit_processing_time",
311
+ "retry_base",
312
+ "retry_cap"
313
+ ];
314
+ /**
315
+ * This function gives the longest gap between two marks of each loop with a name. The rule counts
316
+ * a mark at the end of each turn of the loop, also a turn that fails.
317
+ * - A check polls on a fixed delay from the start of each poll, and each poll ends at its timeout
318
+ * at the latest. Thus the gap is `interval × (1 + jitter) + timeout`.
319
+ * - After an iteration, a lane of a worker waits its sleep, or its backoff after a failure. The
320
+ * longest backoff is `retry_cap` plus its jitter of up to `retry_base`. The next iteration then
321
+ * takes up to `unit_processing_time`. Thus the gap is the longer wait plus that bound.
322
+ *
323
+ * A sleep or a bound without a limit gives a gap without a limit. An iteration that does not end
324
+ * at its abort can take more time, and the rule does not bound it.
325
+ */
326
+ const gapsOf = (svc, loop) => {
327
+ const gaps = svc.checks.filter((check) => check.name === loop).map((check) => ({
328
+ loop,
329
+ seconds: secondsOf(check.poll.interval) * (1 + check.poll.jitter) + secondsOf(check.poll.timeout),
330
+ unbound: []
331
+ }));
332
+ for (const worker of svc.transports) {
333
+ if (worker.kind !== "worker" || worker.name !== loop) continue;
334
+ const knob = (name) => {
335
+ const amount = worker.knobs[name];
336
+ if (amount === void 0 || !isTime(amount.unit)) return void 0;
337
+ return amount.value === "infinite" ? Infinity : secondsOf(amount);
338
+ };
339
+ const unbound = WORKER_GAP_KNOBS.filter((name) => knob(name) === void 0).map((name) => `${loop}.${name}`);
340
+ if (unbound.length > 0) {
341
+ gaps.push({
342
+ loop,
343
+ seconds: void 0,
344
+ unbound
345
+ });
346
+ continue;
347
+ }
348
+ const [sleep, unit, base, cap] = WORKER_GAP_KNOBS.map((name) => knob(name));
349
+ const backoff = Number.isFinite(base) && Number.isFinite(cap) ? backoffBand({
350
+ base,
351
+ factor: 2,
352
+ cap,
353
+ jitter: {
354
+ kind: "add",
355
+ amount: base
356
+ }
357
+ }).high : Infinity;
358
+ gaps.push({
359
+ loop,
360
+ seconds: Math.max(sleep, backoff) + unit,
361
+ unbound: []
362
+ });
363
+ }
364
+ return gaps;
365
+ };
366
+ /**
367
+ * This function gives the findings of each check that names the loops that mark it. A name that is
368
+ * not a check or a worker of the service gets a finding of its own, with the verdict `depends`.
369
+ * Without `marks`, a check gets no finding.
370
+ */
371
+ const progressFindings = (svc) => {
372
+ const findings = [];
373
+ const finding = (check, fields) => ({
374
+ rule: PROGRESS_RULE,
375
+ scope: check.name,
376
+ statement: PROGRESS_LAW.rule,
377
+ window: PROGRESS_LAW.window,
378
+ ...fields
379
+ });
380
+ for (const check of svc.checks) {
381
+ const marks = check.marks;
382
+ if (marks === void 0) continue;
383
+ const gaps = [];
384
+ for (const loop of marks.loops) {
385
+ const found = gapsOf(svc, loop);
386
+ if (found.length > 0) gaps.push(...found);
387
+ else findings.push(finding(check, {
388
+ verdict: "depends",
389
+ statement: "each loop that a progress check names is a check or a worker of the service",
390
+ window: `the check waits for the marks of ${loop}, and the service has no loop with that name`,
391
+ evaluated: [],
392
+ unbound: [loop]
393
+ }));
394
+ }
395
+ if (gaps.length === 0) continue;
396
+ const unbound = [...isTime(marks.stall.unit) ? [] : [`${check.name}.marks.stall`], ...gaps.flatMap((gap) => gap.unbound)];
397
+ const slowest = gaps.reduce((worst, gap) => (gap.seconds ?? -Infinity) > (worst.seconds ?? -Infinity) ? gap : worst);
398
+ const bind = {};
399
+ if (isTime(marks.stall.unit)) bind["stall@check"] = boundOf(marks.stall);
400
+ if (unbound.length === 0 && slowest.seconds !== void 0) bind["mark_gap@loop"] = Number.isFinite(slowest.seconds) ? slowest.seconds : "inf";
401
+ const evaluated = evaluate(PROGRESS_LAW, bind);
402
+ findings.push(finding(check, {
403
+ verdict: verdictOf(PROGRESS_LAW, bind, evaluated),
404
+ ...unbound.length === 0 ? { statement: `${PROGRESS_LAW.rule} (${slowest.loop})` } : {},
405
+ evaluated,
406
+ unbound
407
+ }));
408
+ }
409
+ return findings;
410
+ };
411
+ /** This identifier is the rule of the findings about the bound of a unit against the cap of the `drain` phase. */
412
+ const UNIT_BOUND_RULE = "unit-bound";
413
+ /** This identifier is the rule of the findings about the close bound against the cap of the `close transports` phase. */
414
+ const CLOSE_BOUND_RULE = "close-bound";
415
+ /**
416
+ * These are the rules of the bounds of a loop. Each one applies one time for each consumer and
417
+ * each worker (S6 A10, A11). `lint()` gives them, as it gives `PROGRESS_RULE`.
418
+ * - unit-bound: `unit_processing_time` is less than the cap of the `drain` phase. Otherwise the
419
+ * drain can cut a unit that ends in its bound. A unit without a bound violates the rule.
420
+ * - close-bound: `close_bound` is less than the cap of the `close transports` phase. Otherwise the
421
+ * phase can end before the loop closes.
422
+ *
423
+ * The corpus of the law (R3) does not have these rules, thus they have identifiers of the service,
424
+ * not O-numbers. The symbols `drain_phase_cap@process` and `close_phase_cap@process` are the caps of
425
+ * one phase. `process_drain_time@process` is the sum of the caps of all the phases. A phase that the
426
+ * declaration does not give binds no symbol, thus its finding is `depends`.
427
+ */
428
+ const BOUND_RULES = [{
429
+ id: UNIT_BOUND_RULE,
430
+ rule: "the bound of one unit of a consumer or a worker is less than the cap of the drain phase",
431
+ window: "the drain can cut a unit that ends in its bound",
432
+ expr: {
433
+ lhs: { terms: [{
434
+ knob: "unit_processing_time",
435
+ coef: 1,
436
+ at: "consumer"
437
+ }] },
438
+ op: "<",
439
+ rhs: { terms: [{
440
+ knob: "drain_phase_cap",
441
+ coef: 1,
442
+ at: "process"
443
+ }] },
444
+ margin: 0
445
+ }
446
+ }, {
447
+ id: CLOSE_BOUND_RULE,
448
+ rule: "the close bound of a consumer or a worker is less than the cap of the close transports phase",
449
+ window: "the phase can end before the loop closes",
450
+ expr: {
451
+ lhs: { terms: [{
452
+ knob: "close_bound",
453
+ coef: 1,
454
+ at: "consumer"
455
+ }] },
456
+ op: "<",
457
+ rhs: { terms: [{
458
+ knob: "close_phase_cap",
459
+ coef: 1,
460
+ at: "process"
461
+ }] },
462
+ margin: 0
463
+ }
464
+ }];
465
+ /**
466
+ * This function gives the scopes of a rule that reads these symbols: the service, each client, each
467
+ * consumer and worker, or each limiter. A rule that reads a symbol at `server` applies to each client
468
+ * and to each server transport. In the scope of a server, the scenario gives the client side.
469
+ */
470
+ const scopesOf = (svc, scenario, service, symbols) => {
471
+ const within = (name, scoped) => {
472
+ const bind = {
473
+ ...service.bind,
474
+ ...scoped.bind
475
+ };
476
+ for (const symbol of Object.keys(scoped.epochs)) if (!(symbol in scoped.bind)) delete bind[symbol];
477
+ return [
478
+ name,
479
+ bind,
480
+ {
481
+ ...service.epochs,
482
+ ...scoped.epochs
483
+ }
484
+ ];
485
+ };
486
+ const transports = (hop) => svc.transports.filter((transport) => TRANSPORT_HOPS[transport.kind] === hop).map((transport) => within(transport.name, transportBindings(transport, hop, scenario)));
487
+ return symbols.some((symbol) => LIMITER_SCOPED.test(symbol)) ? (svc.limiters ?? []).map((limiter) => within(limiter.name, limiterBindings(limiter, scenario))) : symbols.some((symbol) => TRANSPORT_SCOPED.test(symbol)) ? transports("consumer") : symbols.some((symbol) => SCOPED.test(symbol)) ? [...svc.dependencies.map((dependency) => within(dependency.name, dependencyBindings(dependency, scenario))), ...symbols.some((symbol) => SERVER_SCOPED.test(symbol)) ? transports("server") : []] : [[
488
+ svc.name,
489
+ service.bind,
490
+ service.epochs
491
+ ]];
492
+ };
493
+ /** This function gives the epochs of the symbols of a rule that the scenario binds. */
494
+ const epochsOf = (symbols, epochs) => Object.fromEntries(symbols.flatMap((symbol) => symbol in epochs ? [[symbol, epochs[symbol] ?? null]] : []));
495
+ /**
496
+ * These are the marks of the timers of the platform (E10). Kubernetes takes the probe period, the
497
+ * preStop sleep and the termination grace in whole seconds, thus each is stepped by 1 s. The
498
+ * cluster sets the propagation of the endpoints, thus a compression of the service cannot scale it.
499
+ */
500
+ const PLATFORM_MARKS = {
501
+ "probe_period@pod": {
502
+ kind: "stepped",
503
+ step: 1
504
+ },
505
+ "prestop_sleep@pod": {
506
+ kind: "stepped",
507
+ step: 1
508
+ },
509
+ "termination_grace@pod": {
510
+ kind: "stepped",
511
+ step: 1
512
+ },
513
+ "propagation_bound@cluster": { kind: "fixed" }
514
+ };
515
+ /**
516
+ * This function tells which findings of `lint` a compression by k changes (E10). It scales the
517
+ * bindings of each scope by the marks. Thus a harness that runs the service k times faster learns
518
+ * the orderings that its run breaks. The unmarked symbols are the symbols of the rules with no mark.
519
+ * It reads the rules that `lint` applies with their bindings: the service rules and `BOUND_RULES`.
520
+ */
521
+ const compressionOf = (svc, scenario, rules, k, marks) => {
522
+ const service = serviceBindings(svc, scenario);
523
+ const changed = [];
524
+ const unmarked = /* @__PURE__ */ new Set();
525
+ for (const rule of [...rules.filter((each) => SERVICE_RULES.includes(each.id)), ...BOUND_RULES]) for (const [scope, bind] of scopesOf(svc, scenario, service, symbolsOf(rule))) {
526
+ const result = compression([rule], bind, k, marks);
527
+ for (const change of result.changed) changed.push({
528
+ ...change,
529
+ scope
530
+ });
531
+ for (const symbol of result.unmarked) unmarked.add(symbol);
532
+ }
533
+ return {
534
+ changed,
535
+ unmarked: [...unmarked]
536
+ };
537
+ };
538
+ /** This function gives the findings of one rule, one for each scope of the rule. */
539
+ const findingsOf = (svc, scenario, service, rule) => {
540
+ const symbols = symbolsOf(rule);
541
+ return scopesOf(svc, scenario, service, symbols).map(([scope, bind, all]) => {
542
+ const evaluated = evaluate(rule, bind);
543
+ const epochs = epochsOf(symbols, all);
544
+ return {
545
+ rule: rule.id,
546
+ scope,
547
+ verdict: verdictOf(rule, bind, evaluated),
548
+ statement: rule.rule,
549
+ ...rule.window !== void 0 ? { window: rule.window } : {},
550
+ evaluated,
551
+ unbound: symbols.filter((symbol) => bind[symbol] === void 0),
552
+ ...Object.values(epochs).some((epoch) => epoch !== null) ? { epochs } : {}
553
+ };
554
+ });
555
+ };
556
+ /**
557
+ * This function applies each service rule to a declaration and a scenario. A rule applies one time
558
+ * for the service, for each client, for each consumer and worker, or for each limiter. It also
559
+ * gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
560
+ * It gives a finding for each name that two parts share in the scopes of a rule (`NAME_RULE`). Each progress check
561
+ * that names its loops also gets its findings (`PROGRESS_RULE`). The findings of the bounds of each
562
+ * consumer and each worker come last (`BOUND_RULES`).
563
+ */
564
+ const lint = (svc, scenario, rules) => {
565
+ const service = serviceBindings(svc, scenario);
566
+ return [
567
+ ...declarationFindings(svc),
568
+ ...nameFindings(svc),
569
+ ...progressFindings(svc),
570
+ ...rules.filter((rule) => SERVICE_RULES.includes(rule.id)).flatMap((rule) => findingsOf(svc, scenario, service, rule)),
571
+ ...BOUND_RULES.flatMap((rule) => findingsOf(svc, scenario, service, rule))
572
+ ];
573
+ };
574
+ export { BOUND_RULES, CLOSE_BOUND_RULE, DECLARATION_RULE, LAW_STATISTIC, LIMITER_RULES, NAME_RULE, PLATFORM_MARKS, PROGRESS_RULE, SERVICE_RULES, UNIT_BOUND_RULE, compressionOf, lint, serviceBindings };
575
+
576
+ //# sourceMappingURL=lint.js.map