@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
@@ -1,25 +1,13 @@
1
- import { n as Clock } from "./clock-DpVgpY4h.js";
2
- import { k as ServiceDescription } from "./logger-B6drv9w0.js";
3
- import { d as TransportImpl, r as Lifecycle } from "./lifecycle-D0J-zwZF.js";
1
+ import { Clock } from "./clock.js";
2
+ import { ServiceDescription } from "./description.js";
3
+ import { Lifecycle, TransportImpl } from "./lifecycle.js";
4
+ import { UnitRequest } from "./units.js";
4
5
  import { Extent, Quantity } from "@mark1russell7/quantity";
5
- /**
6
- * A unit request names the route of each unit of work in the request tracking of the service. Then
7
- * the service admits, counts, drains and cuts each unit as it does each request (`life.request`).
8
- * The controller declares the route, thus its idempotency tells if a cut unit can go again.
9
- */
10
- interface UnitRequest<U> {
11
- /** This name is the controller that declares the route. */
12
- readonly controller: string;
13
- /** This name is the route of each unit, or a function that gives it from the unit. A route can match a route pattern. */
14
- readonly route: string | ((unit: U) => string);
15
- /** This function gives the detail of a unit, for the function of a route pattern. */
16
- readonly detail?: ((unit: U) => unknown) | undefined;
17
- }
18
6
  /**
19
7
  * These are the knobs of a queue drain, by the names of the ordering law where the law has them.
20
8
  * The drain has no defaults, thus each knob is necessary. A bound that nobody gives is "infinite".
21
9
  */
22
- interface QueueKnobs {
10
+ export interface QueueKnobs {
23
11
  /** This time is the wait after a take that gives no job, before the next take. A time without a bound waits for `wake()`. */
24
12
  readonly queue_poll_interval: Extent;
25
13
  /**
@@ -44,31 +32,31 @@ interface QueueKnobs {
44
32
  * - An async iterable gives the jobs in sequence. The drain asks for the next job only when it has a free slot.
45
33
  * At the stop of the intake, the drain ends the iterator through `return()`.
46
34
  */
47
- type JobSource<J> = ((signal: AbortSignal) => J | null | undefined | PromiseLike<J | null | undefined>) | AsyncIterable<J>;
35
+ export type JobSource<J> = ((signal: AbortSignal) => J | null | undefined | PromiseLike<J | null | undefined>) | AsyncIterable<J>;
48
36
  /**
49
37
  * A job action is what the drain does with a job that failed:
50
38
  * - `requeue`: the job goes back on the queue.
51
39
  * - `reject`: the job leaves the queue without a success, for example to the dead-letter route of the queue.
52
40
  * - `ack`: the job leaves the queue, as a poison message does.
53
41
  */
54
- type JobAction = "requeue" | "reject" | "ack";
42
+ export type JobAction = "requeue" | "reject" | "ack";
55
43
  /** A job failure is a job whose handler failed, with the count of its deliveries, 1 at the first. */
56
- interface JobFailure<J> {
44
+ export interface JobFailure<J> {
57
45
  readonly job: J;
58
46
  readonly error: unknown;
59
47
  readonly delivery: number;
60
48
  }
61
49
  /** A redelivery policy gives the action for a job that failed. The queue declares it, and it has no default (S6 A11). */
62
- type RedeliveryPolicy<J> = (failure: JobFailure<J>) => JobAction;
50
+ export type RedeliveryPolicy<J> = (failure: JobFailure<J>) => JobAction;
63
51
  /**
64
52
  * A requeue cause tells why a job goes back on the queue:
65
53
  * - `failed`: the redelivery policy sent it back after a failure.
66
54
  * - `unstarted`: the drain took the job and did not start it, because its intake stopped or the service refused it.
67
55
  * - `cut`: the shutdown cut the job, and its route declares that it can go again.
68
56
  */
69
- type RequeueCause = "failed" | "unstarted" | "cut";
57
+ export type RequeueCause = "failed" | "unstarted" | "cut";
70
58
  /** A job settle is how the drain tells the queue the end of each job. Each function can give a promise. */
71
- interface JobSettle<J> {
59
+ export interface JobSettle<J> {
72
60
  /** This function removes the job from the queue: a success, or the action `ack`. */
73
61
  ack(job: J): void | PromiseLike<void>;
74
62
  /** This function puts the job back on the queue, or hands it back to the queue at the stop. */
@@ -83,7 +71,7 @@ interface JobSettle<J> {
83
71
  delivery(job: J): number;
84
72
  }
85
73
  /** A job context is what the drain gives the handler of each job. */
86
- interface JobContext {
74
+ export interface JobContext {
87
75
  /** This signal aborts at the cooperative abort of the drain, at the bound of the job, and at the close. */
88
76
  readonly signal: AbortSignal;
89
77
  /** This signal aborts when the intake stops. */
@@ -94,7 +82,7 @@ interface JobContext {
94
82
  readonly life: Lifecycle;
95
83
  }
96
84
  /** These options make a queue drain. Each function can give a promise. */
97
- interface QueueDrainOptions<J> {
85
+ export interface QueueDrainOptions<J> {
98
86
  readonly source: JobSource<J>;
99
87
  /** This function does one job. A throw is a failure, and the redelivery policy then gives its action. */
100
88
  readonly handle: (job: J, context: JobContext) => unknown;
@@ -119,7 +107,7 @@ interface QueueDrainOptions<J> {
119
107
  readonly onError?: ((error: unknown, job: J | undefined) => void) | undefined;
120
108
  }
121
109
  /** A queue drain is a transport of the lifecycle whose work is the jobs of a queue (S6 A11). */
122
- interface QueueDrain extends TransportImpl {
110
+ export interface QueueDrain extends TransportImpl {
123
111
  /** These knobs go to the declaration of the consumer: `svc.consumer(name, drain.knobs, drain)`. */
124
112
  readonly knobs: QueueKnobs;
125
113
  /** This method ends the wait of a poll at once, for example when a job comes. It gives false after the intake stops. */
@@ -132,7 +120,7 @@ interface QueueDrain extends TransportImpl {
132
120
  * goes back on the queue after its first failure, one time. After a later failure, `then` gives the
133
121
  * action: the declared policy of the queue.
134
122
  */
135
- declare const redeliverOnce: <J>(then: JobAction | RedeliveryPolicy<J>, poison?: (error: unknown, job: J) => boolean) => RedeliveryPolicy<J>;
123
+ export declare const redeliverOnce: <J>(then: JobAction | RedeliveryPolicy<J>, poison?: (error: unknown, job: J) => boolean) => RedeliveryPolicy<J>;
136
124
  /**
137
125
  * This function makes a queue drain as a transport (S6 A11). One taker takes the jobs from the
138
126
  * source while a slot is free, and each job operates in its slot.
@@ -142,5 +130,4 @@ declare const redeliverOnce: <J>(then: JobAction | RedeliveryPolicy<J>, poison?:
142
130
  * - `close` aborts each job, waits for its end, and closes the source, all in `close_bound`. A job
143
131
  * that does not end in the bound gets `reject`.
144
132
  */
145
- declare const queueDrain: <J>(knobs: QueueKnobs, options: QueueDrainOptions<J>) => QueueDrain;
146
- export { JobSource as a, QueueKnobs as c, queueDrain as d, redeliverOnce as f, JobSettle as i, RedeliveryPolicy as l, JobContext as n, QueueDrain as o, UnitRequest as p, JobFailure as r, QueueDrainOptions as s, JobAction as t, RequeueCause as u };
133
+ export declare const queueDrain: <J>(knobs: QueueKnobs, options: QueueDrainOptions<J>) => QueueDrain;
package/build/queue.js ADDED
@@ -0,0 +1,279 @@
1
+ import { backoffDelay } from "./backoff.js";
2
+ import { realClock } from "./clock.js";
3
+ import { boundedMillisecondsOf, countOf, millisecondsOf } from "./knobs.js";
4
+ import { boundProblems, flights, retryOf, runUnit, settleWithin, sleeper, untilAbort } from "./units.js";
5
+ // src/queue.ts
6
+ /**
7
+ * This function gives the redelivery policy of S6 A11. A poison message gets `ack`. Each other job
8
+ * goes back on the queue after its first failure, one time. After a later failure, `then` gives the
9
+ * action: the declared policy of the queue.
10
+ */
11
+ const redeliverOnce = (then, poison) => (failure) => {
12
+ if (poison?.(failure.error, failure.job) === true) return "ack";
13
+ if (failure.delivery <= 1) return "requeue";
14
+ return typeof then === "function" ? then(failure) : then;
15
+ };
16
+ const OWNER = "queueDrain";
17
+ const ACTIONS = [
18
+ "requeue",
19
+ "reject",
20
+ "ack"
21
+ ];
22
+ const STOPPED = Symbol("the intake stopped");
23
+ const isAsyncIterable = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value[Symbol.asyncIterator] === "function";
24
+ /**
25
+ * This function makes a queue drain as a transport (S6 A11). One taker takes the jobs from the
26
+ * source while a slot is free, and each job operates in its slot.
27
+ * - A success gets `ack`. A failure gets the action of the redelivery policy.
28
+ * - `stopIntake` takes no new job, and a job that the drain took and did not start goes back (`requeue`, `unstarted`).
29
+ * - `drain` waits for each job in flight until the deadline, and gives it the cooperative abort.
30
+ * - `close` aborts each job, waits for its end, and closes the source, all in `close_bound`. A job
31
+ * that does not end in the bound gets `reject`.
32
+ */
33
+ const queueDrain = (knobs, options) => {
34
+ const poll = millisecondsOf(knobs, "queue_poll_interval", OWNER);
35
+ const bound = millisecondsOf(knobs, "unit_processing_time", OWNER);
36
+ const backoff = retryOf(knobs, OWNER);
37
+ const closeBound = boundedMillisecondsOf(knobs, "close_bound", OWNER);
38
+ const concurrency = countOf(knobs, "concurrency", OWNER);
39
+ const { settle } = options;
40
+ const clock = options.clock ?? realClock;
41
+ const random = options.random ?? Math.random;
42
+ const running = flights(clock);
43
+ const rests = sleeper(clock);
44
+ const intake = new AbortController();
45
+ const pending = /* @__PURE__ */ new Set();
46
+ const active = /* @__PURE__ */ new Set();
47
+ let refusals = 0;
48
+ let pausedUntil = Number.NEGATIVE_INFINITY;
49
+ let cancelSource = () => {};
50
+ let started = false;
51
+ let closing = null;
52
+ const report = (error, job) => {
53
+ try {
54
+ options.onError?.(error, job);
55
+ } catch {}
56
+ };
57
+ const keep = (work) => {
58
+ pending.add(work);
59
+ const forget = () => {
60
+ pending.delete(work);
61
+ };
62
+ work.then(forget, forget);
63
+ };
64
+ /** This function tells the queue the end of a job, one time. A throw of the queue is a failure. */
65
+ const once = async (unit, tell) => {
66
+ if (unit.settled) return;
67
+ unit.settled = true;
68
+ try {
69
+ await tell();
70
+ } catch (error) {
71
+ report(error, unit.job);
72
+ }
73
+ };
74
+ const handBack = (job) => keep((async () => {
75
+ try {
76
+ await settle.requeue(job, "unstarted");
77
+ } catch (error) {
78
+ report(error, job);
79
+ }
80
+ })());
81
+ /** This function gives the action of the policy for a failed job. A policy that throws, or that gives no action, rejects the job. */
82
+ const actionOf = (job, error, delivery) => {
83
+ try {
84
+ const action = options.redelivery({
85
+ job,
86
+ error,
87
+ delivery
88
+ });
89
+ if (ACTIONS.includes(action)) return action;
90
+ report(/* @__PURE__ */ new Error(`the redelivery policy gave ${String(action)}, not requeue, reject or ack`), job);
91
+ } catch (thrown) {
92
+ report(thrown, job);
93
+ }
94
+ return "reject";
95
+ };
96
+ const settleEnd = (unit, end, delivery) => {
97
+ const { job } = unit;
98
+ if (end.kind === "done") return once(unit, () => settle.ack(job));
99
+ if (end.kind === "refused") {
100
+ report(/* @__PURE__ */ new Error(`the service refused the job: ${end.cause}`), job);
101
+ return once(unit, () => settle.requeue(job, "unstarted"));
102
+ }
103
+ if (end.kind === "cut") {
104
+ if (end.retryable) return once(unit, () => settle.requeue(job, "cut"));
105
+ const cut = new Error(end.cause);
106
+ return once(unit, () => settle.reject(job, cut));
107
+ }
108
+ const { error } = end;
109
+ report(error, job);
110
+ const action = actionOf(job, error, delivery);
111
+ if (action === "requeue") return once(unit, () => settle.requeue(job, "failed"));
112
+ return once(unit, () => action === "ack" ? settle.ack(job) : settle.reject(job, error));
113
+ };
114
+ /** This function starts one job in a slot. The slot stays in flight until the queue has the end of the job. */
115
+ const runJob = (job, life) => {
116
+ const unit = {
117
+ job,
118
+ settled: false
119
+ };
120
+ active.add(unit);
121
+ const abort = new AbortController();
122
+ const remove = running.add(abort);
123
+ let delivery;
124
+ try {
125
+ delivery = settle.delivery(job);
126
+ } catch (error) {
127
+ report(error, job);
128
+ delivery = Number.POSITIVE_INFINITY;
129
+ }
130
+ keep((async () => {
131
+ const end = await runUnit({
132
+ clock,
133
+ bound,
134
+ abort,
135
+ life,
136
+ request: options.request,
137
+ unit: job,
138
+ work: (signal) => options.handle(job, {
139
+ signal,
140
+ intake: intake.signal,
141
+ delivery,
142
+ life
143
+ })
144
+ });
145
+ if (end.kind === "refused") {
146
+ refusals += 1;
147
+ pausedUntil = clock.now() + backoffDelay(backoff, refusals, random);
148
+ } else refusals = 0;
149
+ await settleEnd(unit, end, delivery);
150
+ })().finally(() => {
151
+ active.delete(unit);
152
+ remove();
153
+ }));
154
+ };
155
+ /** This function gives the take of the source. */
156
+ const takeOf = () => {
157
+ const source = options.source;
158
+ if (isAsyncIterable(source)) {
159
+ const iterator = source[Symbol.asyncIterator]();
160
+ cancelSource = () => {
161
+ try {
162
+ Promise.resolve(iterator.return?.()).catch(() => {});
163
+ } catch {}
164
+ };
165
+ return async () => {
166
+ const step = await iterator.next();
167
+ return step.done === true ? { kind: "end" } : {
168
+ kind: "job",
169
+ job: step.value
170
+ };
171
+ };
172
+ }
173
+ const pull = source;
174
+ return () => new Promise((resolve) => resolve(pull(intake.signal))).then((job) => job === null || job === void 0 ? { kind: "none" } : {
175
+ kind: "job",
176
+ job
177
+ });
178
+ };
179
+ /** This function is the taker: it takes a job while a slot is free, until the intake stops or the source ends. */
180
+ const taker = async (life) => {
181
+ const take = takeOf();
182
+ let failures = 0;
183
+ for (;;) {
184
+ if (intake.signal.aborted) return;
185
+ if (running.size >= concurrency) {
186
+ await running.less();
187
+ continue;
188
+ }
189
+ const pause = pausedUntil - clock.now();
190
+ if (pause > 0) {
191
+ await rests.backoff(pause);
192
+ continue;
193
+ }
194
+ const since = rests.wakes;
195
+ const taking = take().catch((error) => ({
196
+ kind: "error",
197
+ error
198
+ }));
199
+ const first = await untilAbort(taking, intake.signal, STOPPED);
200
+ if (first === STOPPED || intake.signal.aborted) {
201
+ if (first === STOPPED) taking.then((late) => {
202
+ if (late.kind === "job") handBack(late.job);
203
+ });
204
+ else if (first.kind === "job") handBack(first.job);
205
+ return;
206
+ }
207
+ if (first.kind === "error") {
208
+ failures += 1;
209
+ report(first.error, void 0);
210
+ await rests.backoff(backoffDelay(backoff, failures, random));
211
+ continue;
212
+ }
213
+ failures = 0;
214
+ if (first.kind === "end") {
215
+ report(/* @__PURE__ */ new Error(`the source of ${OWNER} ended while its intake was open: it takes no more jobs`), void 0);
216
+ return;
217
+ }
218
+ if (first.kind === "none") {
219
+ await rests.sleep(poll, since);
220
+ continue;
221
+ }
222
+ runJob(first.job, life);
223
+ }
224
+ };
225
+ const stopTaking = (cause) => {
226
+ if (intake.signal.aborted) return;
227
+ intake.abort(new Error(cause));
228
+ rests.stop();
229
+ running.release();
230
+ cancelSource();
231
+ };
232
+ return {
233
+ knobs: { ...knobs },
234
+ start(_signal, life) {
235
+ if (closing !== null) throw new Error(`${OWNER}: a closed drain does not start again`);
236
+ if (started) throw new Error(`${OWNER}: the drain started already`);
237
+ started = true;
238
+ life.started.then(() => {
239
+ if (intake.signal.aborted || life.state !== "running") return;
240
+ taker(life).catch((error) => report(error, void 0));
241
+ });
242
+ },
243
+ stopIntake() {
244
+ stopTaking(`${OWNER} stopped its intake`);
245
+ },
246
+ drain(deadline, signal) {
247
+ return running.drain(deadline, signal);
248
+ },
249
+ inFlight: () => running.size,
250
+ wake() {
251
+ if (intake.signal.aborted) return false;
252
+ rests.wake();
253
+ return true;
254
+ },
255
+ close() {
256
+ if (closing !== null) return closing;
257
+ stopTaking(`${OWNER} closed`);
258
+ running.abort(/* @__PURE__ */ new Error(`${OWNER} closed`));
259
+ running.clear();
260
+ closing = (async () => {
261
+ const began = clock.now();
262
+ const ended = await settleWithin(clock, closeBound, Promise.allSettled([...pending]));
263
+ if (ended.kind === "bound") for (const unit of [...active]) once(unit, () => settle.reject(unit.job, /* @__PURE__ */ new Error(`${OWNER} closed with the job in flight`)));
264
+ const shut = options.close;
265
+ const down = await settleWithin(clock, Math.max(0, closeBound - (clock.now() - began)), shut === void 0 ? Promise.resolve() : (async () => shut())());
266
+ if (ended.kind === "bound") throw new Error(`${OWNER}: a job did not end in the close_bound of ${closeBound} ms after its abort`);
267
+ if (down.kind === "failed") throw down.error;
268
+ if (down.kind === "bound") throw new Error(`${OWNER}: the close of the source did not end in the close_bound of ${closeBound} ms`);
269
+ })();
270
+ return closing;
271
+ },
272
+ problems(description) {
273
+ return boundProblems(OWNER, description);
274
+ }
275
+ };
276
+ };
277
+ export { queueDrain, redeliverOnce };
278
+
279
+ //# sourceMappingURL=queue.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"queue.js","names":[],"sources":["../src/queue.ts"],"sourcesContent":["import type { Extent, Quantity } from \"@mark1russell7/quantity\";\nimport { backoffDelay } from \"./backoff.ts\";\nimport type { Clock } from \"./clock.ts\";\nimport { realClock } from \"./clock.ts\";\nimport type { ServiceDescription } from \"./description.ts\";\nimport { boundedMillisecondsOf, countOf, millisecondsOf } from \"./knobs.ts\";\nimport type { Lifecycle, TransportImpl } from \"./lifecycle.ts\";\nimport type { UnitEnd, UnitRequest } from \"./units.ts\";\nimport { boundProblems, flights, retryOf, runUnit, settleWithin, sleeper, untilAbort } from \"./units.ts\";\n\n/**\n * These are the knobs of a queue drain, by the names of the ordering law where the law has them.\n * The drain has no defaults, thus each knob is necessary. A bound that nobody gives is \"infinite\".\n */\nexport interface QueueKnobs {\n /** This time is the wait after a take that gives no job, before the next take. A time without a bound waits for `wake()`. */\n readonly queue_poll_interval: Extent;\n /**\n * This time is the most that one job can take. At it, the drain aborts the signal of the job, and\n * a throw after it is a failure. The law reads it as `unit_processing_time@consumer` (O20).\n */\n readonly unit_processing_time: Extent;\n /** This time is the delay after the first failed take in sequence, or after a refusal of the service. The delay is two times longer after each one. */\n readonly retry_base: Quantity;\n /** This time is the most that one delay can be, before its jitter. */\n readonly retry_cap: Quantity;\n /** This time bounds the close: the end of the jobs after their abort, and then the close of the source. */\n readonly close_bound: Quantity;\n /** This count (the unit `count`) is the most jobs in flight at one time. A count without a bound takes each job that comes. */\n readonly concurrency: Extent;\n /** The other knobs go to the declaration, for example `lease_duration@broker`. The drain does not read them. */\n readonly [knob: string]: Extent;\n}\n\n/**\n * A job source gives the jobs of a queue drain:\n * - A function takes the next job, or gives null when no job is ready. Its signal aborts when the intake stops.\n * - An async iterable gives the jobs in sequence. The drain asks for the next job only when it has a free slot.\n * At the stop of the intake, the drain ends the iterator through `return()`.\n */\nexport type JobSource<J> = ((signal: AbortSignal) => J | null | undefined | PromiseLike<J | null | undefined>) | AsyncIterable<J>;\n\n/**\n * A job action is what the drain does with a job that failed:\n * - `requeue`: the job goes back on the queue.\n * - `reject`: the job leaves the queue without a success, for example to the dead-letter route of the queue.\n * - `ack`: the job leaves the queue, as a poison message does.\n */\nexport type JobAction = \"requeue\" | \"reject\" | \"ack\";\n\n/** A job failure is a job whose handler failed, with the count of its deliveries, 1 at the first. */\nexport interface JobFailure<J> {\n readonly job: J;\n readonly error: unknown;\n readonly delivery: number;\n}\n\n/** A redelivery policy gives the action for a job that failed. The queue declares it, and it has no default (S6 A11). */\nexport type RedeliveryPolicy<J> = (failure: JobFailure<J>) => JobAction;\n\n/**\n * A requeue cause tells why a job goes back on the queue:\n * - `failed`: the redelivery policy sent it back after a failure.\n * - `unstarted`: the drain took the job and did not start it, because its intake stopped or the service refused it.\n * - `cut`: the shutdown cut the job, and its route declares that it can go again.\n */\nexport type RequeueCause = \"failed\" | \"unstarted\" | \"cut\";\n\n/** A job settle is how the drain tells the queue the end of each job. Each function can give a promise. */\nexport interface JobSettle<J> {\n /** This function removes the job from the queue: a success, or the action `ack`. */\n ack(job: J): void | PromiseLike<void>;\n /** This function puts the job back on the queue, or hands it back to the queue at the stop. */\n requeue(job: J, cause: RequeueCause): void | PromiseLike<void>;\n /** This function removes the job from the queue without a success: the action `reject`, or a cut job that cannot go again. */\n reject(job: J, error: unknown): void | PromiseLike<void>;\n /**\n * This function gives the count of deliveries of a job from the queue, 1 at the first. The queue\n * knows it, for example `x-delivery-count` of RabbitMQ or `ApproximateReceiveCount` of SQS. A\n * queue in memory counts for itself. The drain has no default, because a broker gives a new object at each delivery.\n */\n delivery(job: J): number;\n}\n\n/** A job context is what the drain gives the handler of each job. */\nexport interface JobContext {\n /** This signal aborts at the cooperative abort of the drain, at the bound of the job, and at the close. */\n readonly signal: AbortSignal;\n /** This signal aborts when the intake stops. */\n readonly intake: AbortSignal;\n /** This count is the delivery of the job, 1 at the first. */\n readonly delivery: number;\n /** This lifecycle is the lifecycle that the drain got at its start. */\n readonly life: Lifecycle;\n}\n\n/** These options make a queue drain. Each function can give a promise. */\nexport interface QueueDrainOptions<J> {\n readonly source: JobSource<J>;\n /** This function does one job. A throw is a failure, and the redelivery policy then gives its action. */\n readonly handle: (job: J, context: JobContext) => unknown;\n readonly settle: JobSettle<J>;\n /** This policy gives the action for each failed job. `redeliverOnce` gives the policy of S6 A11. */\n readonly redelivery: RedeliveryPolicy<J>;\n /** This function closes the source at the close, after the jobs end: for example, it closes a channel. */\n readonly close?: (() => void | PromiseLike<void>) | undefined;\n /** This clock is the clock of the lifecycle. The polls, the backoffs and the bounds use it. The default is `realClock`. */\n readonly clock?: Clock | undefined;\n /** This function gives the random numbers of the jitter, from 0 up to 1. The default is `Math.random`. */\n readonly random?: (() => number) | undefined;\n /**\n * This route puts each job through `life.request`: the service then admits it, counts it, drains\n * it and can cut it. The idempotency of the route tells if a cut job goes back on the queue.\n */\n readonly request?: UnitRequest<J> | undefined;\n /**\n * This function receives each failure: of a take, of a job, of a settle and of a policy. It also\n * receives the end of a source while the intake is open. The job is undefined for a take and for that end.\n */\n readonly onError?: ((error: unknown, job: J | undefined) => void) | undefined;\n}\n\n/** A queue drain is a transport of the lifecycle whose work is the jobs of a queue (S6 A11). */\nexport interface QueueDrain extends TransportImpl {\n /** These knobs go to the declaration of the consumer: `svc.consumer(name, drain.knobs, drain)`. */\n readonly knobs: QueueKnobs;\n /** This method ends the wait of a poll at once, for example when a job comes. It gives false after the intake stops. */\n wake(): boolean;\n /** This method gives the problems of a declaration: each phase that the drain needs and that it does not give. `lint()` compares the bounds with the caps. */\n problems(description: ServiceDescription): string[];\n}\n\n/**\n * This function gives the redelivery policy of S6 A11. A poison message gets `ack`. Each other job\n * goes back on the queue after its first failure, one time. After a later failure, `then` gives the\n * action: the declared policy of the queue.\n */\nexport const redeliverOnce =\n <J>(then: JobAction | RedeliveryPolicy<J>, poison?: (error: unknown, job: J) => boolean): RedeliveryPolicy<J> =>\n (failure) => {\n if (poison?.(failure.error, failure.job) === true) return \"ack\";\n if (failure.delivery <= 1) return \"requeue\";\n return typeof then === \"function\" ? then(failure) : then;\n };\n\nconst OWNER = \"queueDrain\";\nconst ACTIONS: readonly string[] = [\"requeue\", \"reject\", \"ack\"];\nconst STOPPED: unique symbol = Symbol(\"the intake stopped\");\n\ntype Taken<J> = { readonly kind: \"job\"; readonly job: J } | { readonly kind: \"none\" } | { readonly kind: \"end\" } | { readonly kind: \"error\"; readonly error: unknown };\n\ninterface Active<J> {\n readonly job: J;\n settled: boolean;\n}\n\nconst isAsyncIterable = (value: unknown): value is AsyncIterable<unknown> =>\n value !== null &&\n (typeof value === \"object\" || typeof value === \"function\") &&\n typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === \"function\";\n\n/**\n * This function makes a queue drain as a transport (S6 A11). One taker takes the jobs from the\n * source while a slot is free, and each job operates in its slot.\n * - A success gets `ack`. A failure gets the action of the redelivery policy.\n * - `stopIntake` takes no new job, and a job that the drain took and did not start goes back (`requeue`, `unstarted`).\n * - `drain` waits for each job in flight until the deadline, and gives it the cooperative abort.\n * - `close` aborts each job, waits for its end, and closes the source, all in `close_bound`. A job\n * that does not end in the bound gets `reject`.\n */\nexport const queueDrain = <J>(knobs: QueueKnobs, options: QueueDrainOptions<J>): QueueDrain => {\n const poll = millisecondsOf(knobs, \"queue_poll_interval\", OWNER);\n const bound = millisecondsOf(knobs, \"unit_processing_time\", OWNER);\n const backoff = retryOf(knobs, OWNER);\n const closeBound = boundedMillisecondsOf(knobs, \"close_bound\", OWNER);\n const concurrency = countOf(knobs, \"concurrency\", OWNER);\n const { settle } = options;\n const clock = options.clock ?? realClock;\n const random = options.random ?? Math.random;\n const running = flights(clock);\n const rests = sleeper(clock);\n const intake = new AbortController();\n // each job until its settle ends, and each job that goes back: the close waits for them\n const pending = new Set<Promise<unknown>>();\n const active = new Set<Active<J>>();\n let refusals = 0;\n let pausedUntil = Number.NEGATIVE_INFINITY;\n let cancelSource: () => void = () => {};\n let started = false;\n let closing: Promise<void> | null = null;\n\n const report = (error: unknown, job: J | undefined): void => {\n try {\n options.onError?.(error, job);\n } catch {\n // an error of the hook does not stop the drain\n }\n };\n const keep = (work: Promise<unknown>): void => {\n pending.add(work);\n const forget = (): void => {\n pending.delete(work);\n };\n work.then(forget, forget);\n };\n /** This function tells the queue the end of a job, one time. A throw of the queue is a failure. */\n const once = async (unit: Active<J>, tell: () => void | PromiseLike<void>): Promise<void> => {\n if (unit.settled) return;\n unit.settled = true;\n try {\n await tell();\n } catch (error) {\n report(error, unit.job);\n }\n };\n const handBack = (job: J): void =>\n keep(\n (async () => {\n try {\n await settle.requeue(job, \"unstarted\");\n } catch (error) {\n report(error, job);\n }\n })(),\n );\n\n /** This function gives the action of the policy for a failed job. A policy that throws, or that gives no action, rejects the job. */\n const actionOf = (job: J, error: unknown, delivery: number): JobAction => {\n try {\n const action = options.redelivery({ job, error, delivery });\n if (ACTIONS.includes(action)) return action;\n report(new Error(`the redelivery policy gave ${String(action)}, not requeue, reject or ack`), job);\n } catch (thrown) {\n report(thrown, job);\n }\n return \"reject\";\n };\n\n const settleEnd = (unit: Active<J>, end: UnitEnd, delivery: number): Promise<void> => {\n const { job } = unit;\n if (end.kind === \"done\") return once(unit, () => settle.ack(job));\n if (end.kind === \"refused\") {\n report(new Error(`the service refused the job: ${end.cause}`), job);\n return once(unit, () => settle.requeue(job, \"unstarted\"));\n }\n if (end.kind === \"cut\") {\n // a cut is not a failure. Only a route that can go again puts the job back (S6 A12)\n if (end.retryable) return once(unit, () => settle.requeue(job, \"cut\"));\n const cut = new Error(end.cause);\n return once(unit, () => settle.reject(job, cut));\n }\n const { error } = end;\n report(error, job);\n const action = actionOf(job, error, delivery);\n if (action === \"requeue\") return once(unit, () => settle.requeue(job, \"failed\"));\n return once(unit, () => (action === \"ack\" ? settle.ack(job) : settle.reject(job, error)));\n };\n\n /** This function starts one job in a slot. The slot stays in flight until the queue has the end of the job. */\n const runJob = (job: J, life: Lifecycle): void => {\n const unit: Active<J> = { job, settled: false };\n active.add(unit);\n const abort = new AbortController();\n const remove = running.add(abort);\n let delivery: number;\n try {\n delivery = settle.delivery(job);\n } catch (error) {\n // a count that the queue cannot give is not a first delivery: the job does not go back for free\n report(error, job);\n delivery = Number.POSITIVE_INFINITY;\n }\n keep(\n (async () => {\n const end = await runUnit({\n clock,\n bound,\n abort,\n life,\n request: options.request,\n unit: job,\n work: (signal) => options.handle(job, { signal, intake: intake.signal, delivery, life }),\n });\n // a refusal of the service stops the takes for a backoff, thus a controller that is not ready does not get each job\n if (end.kind === \"refused\") {\n refusals += 1;\n pausedUntil = clock.now() + backoffDelay(backoff, refusals, random);\n } else refusals = 0;\n await settleEnd(unit, end, delivery);\n })().finally(() => {\n active.delete(unit);\n remove();\n }),\n );\n };\n\n /** This function gives the take of the source. */\n const takeOf = (): (() => Promise<Taken<J>>) => {\n const source = options.source;\n if (isAsyncIterable(source)) {\n const iterator = (source as AsyncIterable<J>)[Symbol.asyncIterator]();\n cancelSource = () => {\n try {\n void Promise.resolve(iterator.return?.()).catch(() => {});\n } catch {\n // an iterator whose return() throws has ended\n }\n };\n return async () => {\n const step = await iterator.next();\n return step.done === true ? { kind: \"end\" } : { kind: \"job\", job: step.value };\n };\n }\n const pull = source as (signal: AbortSignal) => J | null | undefined | PromiseLike<J | null | undefined>;\n return () =>\n new Promise<J | null | undefined>((resolve) => resolve(pull(intake.signal))).then(\n (job): Taken<J> => (job === null || job === undefined ? { kind: \"none\" } : { kind: \"job\", job }),\n );\n };\n\n /** This function is the taker: it takes a job while a slot is free, until the intake stops or the source ends. */\n const taker = async (life: Lifecycle): Promise<void> => {\n const take = takeOf();\n let failures = 0;\n for (;;) {\n if (intake.signal.aborted) return;\n if (running.size >= concurrency) {\n await running.less();\n continue;\n }\n const pause = pausedUntil - clock.now();\n if (pause > 0) {\n await rests.backoff(pause);\n continue;\n }\n const since = rests.wakes;\n const taking = take().catch((error: unknown): Taken<J> => ({ kind: \"error\", error }));\n // Each take waits for the stop with a listener of its own, thus a long drain keeps no job that it took.\n const first = await untilAbort(taking, intake.signal, STOPPED);\n if (first === STOPPED || intake.signal.aborted) {\n // a take that ends after the stop gives a job that the drain does not start: it goes back\n if (first === STOPPED)\n void taking.then((late) => {\n if (late.kind === \"job\") handBack(late.job);\n });\n else if (first.kind === \"job\") handBack(first.job);\n return;\n }\n if (first.kind === \"error\") {\n failures += 1;\n report(first.error, undefined);\n await rests.backoff(backoffDelay(backoff, failures, random));\n continue;\n }\n failures = 0;\n if (first.kind === \"end\") {\n // the source ended while the intake is open: the drain takes no more jobs, thus it says so\n report(new Error(`the source of ${OWNER} ended while its intake was open: it takes no more jobs`), undefined);\n return;\n }\n if (first.kind === \"none\") {\n await rests.sleep(poll, since);\n continue;\n }\n runJob(first.job, life);\n }\n };\n\n const stopTaking = (cause: string): void => {\n if (intake.signal.aborted) return;\n intake.abort(new Error(cause));\n rests.stop();\n running.release();\n cancelSource();\n };\n\n return {\n knobs: { ...knobs },\n start(_signal, life) {\n if (closing !== null) throw new Error(`${OWNER}: a closed drain does not start again`);\n if (started) throw new Error(`${OWNER}: the drain started already`);\n started = true;\n // the first take waits for the end of the startup, because a request before it gets a refusal\n void life.started.then(() => {\n if (intake.signal.aborted || life.state !== \"running\") return;\n // the taker catches each failure of the source: a rejection here is a defect, and it does not end the process (A5)\n taker(life).catch((error: unknown) => report(error, undefined));\n });\n },\n stopIntake() {\n stopTaking(`${OWNER} stopped its intake`);\n },\n drain(deadline, signal) {\n return running.drain(deadline, signal);\n },\n inFlight: () => running.size,\n wake() {\n if (intake.signal.aborted) return false;\n rests.wake();\n return true;\n },\n close() {\n if (closing !== null) return closing;\n stopTaking(`${OWNER} closed`);\n running.abort(new Error(`${OWNER} closed`));\n running.clear();\n closing = (async () => {\n const began = clock.now();\n const ended = await settleWithin(clock, closeBound, Promise.allSettled([...pending]));\n if (ended.kind === \"bound\")\n for (const unit of [...active])\n void once(unit, () => settle.reject(unit.job, new Error(`${OWNER} closed with the job in flight`)));\n const shut = options.close;\n const down = await settleWithin(\n clock,\n Math.max(0, closeBound - (clock.now() - began)),\n shut === undefined ? Promise.resolve() : (async () => shut())(),\n );\n if (ended.kind === \"bound\") throw new Error(`${OWNER}: a job did not end in the close_bound of ${closeBound} ms after its abort`);\n if (down.kind === \"failed\") throw down.error;\n if (down.kind === \"bound\") throw new Error(`${OWNER}: the close of the source did not end in the close_bound of ${closeBound} ms`);\n })();\n return closing;\n },\n problems(description) {\n return boundProblems(OWNER, description);\n },\n };\n};\n"],"mappings":"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"}
@@ -0,0 +1,144 @@
1
+ import { Attempt, Client, ClientJoin, ClientKnobs, ClientOptions, ClientSpec, ClientStep, DialFn, RetryKnobs, SendOptions, Sent } from "../client/core.js";
2
+ import { Judge } from "../client/dial.js";
3
+ import { JobSettle } from "../queue.js";
4
+ import { RabbitConnectOptions, RabbitFactory, RabbitMessage, RabbitPublishOptions } from "./connection.js";
5
+ import { Extent, Quantity } from "@mark1russell7/quantity";
6
+ /**
7
+ * These are the knobs of the client, each a time, by the names of the ordering law where the law
8
+ * has them. The runtime has no defaults, thus each knob is necessary. A bound that nobody gives is
9
+ * "infinite", not zero. The constant `RABBIT_STARTING_KNOBS` gives a declaration from the cells of R3. The knobs
10
+ * that each client has come from the core.
11
+ */
12
+ export interface RabbitKnobs extends ClientKnobs, RetryKnobs {
13
+ /**
14
+ * This time bounds the TCP connect and the handshake (`socketOptions.timeout`). The client also
15
+ * bounds the open of its channel with it. The timer of amqplib stops when the connection opens.
16
+ */
17
+ readonly connect_bound: Quantity;
18
+ /** This time bounds each call: a publish until its confirm, and an RPC until its reply. The wrapper has this timer, because amqplib has none. */
19
+ readonly request_timeout: Quantity;
20
+ /**
21
+ * This time is the heartbeat that the client asks for (`heartbeat` in the URL), in whole seconds.
22
+ * The connection uses the smaller of this value and the value of the broker. The value "infinite" asks for no heartbeat.
23
+ */
24
+ readonly heartbeat_interval: Extent;
25
+ /** This time is the first delay before a new try to connect. The delay doubles after each try. */
26
+ readonly retry_base: Quantity;
27
+ /** This time is the most that one delay can be, before its jitter. */
28
+ readonly retry_cap: Quantity;
29
+ /** This time is the idle time of TCP keepalive (`keepAliveDelay`), in whole seconds. The value "infinite" turns keepalive off, as amqplib does by default. */
30
+ readonly keepalive_idle: Extent;
31
+ /** The client does not replace its connection at an age, thus this knob must be "infinite". */
32
+ readonly max_connection_age: Extent;
33
+ /** This time bounds the close of the client at the shutdown: `connection.close`, then a destroy of the socket. */
34
+ readonly close_bound: Quantity;
35
+ }
36
+ /** A seed is one more node of the cluster. The client connects to the next node after each failure, in sequence. */
37
+ export interface RabbitSeed {
38
+ readonly host: string;
39
+ readonly port: number;
40
+ }
41
+ /** A RabbitMQ client spec is the declaration of one RabbitMQ client: where it connects, and its knobs. */
42
+ export interface RabbitClientSpec extends ClientSpec<RabbitKnobs> {
43
+ /** This name is the virtual host. The default of the broker is "/". */
44
+ readonly vhost?: string | undefined;
45
+ /** This name is the user. Without it, amqplib connects as the user "guest". */
46
+ readonly username?: string | undefined;
47
+ /** These nodes are more nodes of the cluster, after `host` and `port`. */
48
+ readonly seeds?: readonly RabbitSeed[] | undefined;
49
+ /**
50
+ * These operations are the calls of the service, by name, with their idempotency. A message does
51
+ * not tell if a consumer removes its duplicates. Thus the client sends again only a call that this table names.
52
+ */
53
+ readonly operations?: ClientSpec<RabbitKnobs>["operations"];
54
+ }
55
+ /** These options make a client. Without them, it uses amqplib, the real clock, `Math.random`, and a dial with the protocol header. */
56
+ export interface RabbitClientOptions extends ClientOptions<RabbitFactory> {
57
+ readonly random?: (() => number) | undefined;
58
+ }
59
+ /**
60
+ * A join is one generation of the client: one connection and its channel, when the channel is open
61
+ * (D1, D2). The prober joins its kernel records to the view of the broker through it.
62
+ */
63
+ export interface RabbitJoin extends ClientJoin {
64
+ /** This text is the node of the connection, as `host:port`. */
65
+ readonly address: string;
66
+ /** This text is the name of the connection in the broker, `local:port -> remote:port`, or null when the socket gives no addresses. */
67
+ readonly connectionName: string | null;
68
+ }
69
+ /** A publish is one message to an exchange. A string content goes as UTF-8. */
70
+ export interface RabbitPublish {
71
+ readonly exchange: string;
72
+ readonly routingKey: string;
73
+ readonly content: Buffer | string;
74
+ /** These properties go to amqplib, for example `persistent`, `messageId` and `headers`. */
75
+ readonly properties?: RabbitPublishOptions | undefined;
76
+ }
77
+ /** A delivery is one message that the client took from a queue. It stays on the channel of its generation until a settle. */
78
+ export interface RabbitDelivery {
79
+ readonly message: RabbitMessage;
80
+ /** This number is the generation of the channel that holds the message. */
81
+ readonly generation: number;
82
+ /** This count is the delivery of the message, 1 at the first, from `x-delivery-count` or `redelivered`. */
83
+ readonly delivery: number;
84
+ }
85
+ /** These are the source and the settle of a queue drain on one queue: `queueDrain({ source, settle, ... })`. */
86
+ export interface RabbitJobs {
87
+ /** This function takes one job, or gives null when the queue is empty. It is a `JobSource` of the drain. */
88
+ readonly source: (signal: AbortSignal) => Promise<RabbitDelivery | null>;
89
+ readonly settle: JobSettle<RabbitDelivery>;
90
+ }
91
+ /** A RabbitMQ client is a dependency of a service: its declaration, its handle, its checks and its calls. */
92
+ export interface RabbitClient extends Client<ClientStep, RabbitJoin> {
93
+ /** This text is the state of the client, as `RABBIT_CLIENT_MACHINE` names it. */
94
+ readonly status: string;
95
+ /**
96
+ * This method publishes one message, and waits for its confirm. An ack is `ok`. The client sends
97
+ * again only an idempotent operation, one time at most, after an outcome that is not certain.
98
+ */
99
+ publish(operation: string, message: RabbitPublish, options?: SendOptions): Promise<Sent<void>>;
100
+ /** This method takes one message from a queue (`basic.get`), or gives null when the queue is empty. */
101
+ get(operation: string, queue: string, options?: SendOptions): Promise<Sent<RabbitDelivery | null>>;
102
+ /** This method gives the source and the settle of a queue drain. The source takes each job with `get`. */
103
+ jobs(operation: string, queue: string): RabbitJobs;
104
+ }
105
+ /** This function gives the problems of a spec: the knobs that the client cannot use. */
106
+ export declare const specProblems: (name: string, spec: RabbitClientSpec) => string[];
107
+ /**
108
+ * This function gives the arguments of `connect` for one node of a spec. Each timer of amqplib
109
+ * comes from the declaration. The heartbeat goes in the URL, and "infinite" is 0, no heartbeat.
110
+ */
111
+ export declare const rabbitOptions: (name: string, spec: RabbitClientSpec, index?: number) => RabbitConnectOptions;
112
+ /** The bytes of the protocol header of AMQP 0-9-1. A broker answers it with `connection.start`, before the authentication. */
113
+ export declare const AMQP_HEADER: Uint8Array;
114
+ /**
115
+ * This judge reads the answer to the protocol header. A broker that takes the version sends a method
116
+ * frame on channel 0: `connection.start`, class 10 and method 10. A broker that refuses the version
117
+ * sends its own protocol header, and closes the socket.
118
+ */
119
+ export declare const startJudge: Judge;
120
+ /** This dial function opens a TCP connection, sends the protocol header, and waits for `connection.start`. It needs no password. */
121
+ export declare const amqpDial: DialFn;
122
+ /**
123
+ * This function gives the outcome of a failure of amqplib. The library names few classes of error.
124
+ * Thus the wrapper reads the fields:
125
+ * - A throw before the write (`IllegalOperationError`: the channel is closed or closing) is certain: the call did not leave the client.
126
+ * - A reply code of the broker, from the close of the channel, is certain. The broker refused the call, or a call before it.
127
+ * - A nack, and an end of the channel before the reply or the confirm, are not certain.
128
+ */
129
+ export declare const failureOutcome: (error: unknown) => Attempt<never>;
130
+ /** This function gives the count of deliveries of a message, 1 at the first. A quorum queue counts in `x-delivery-count`. */
131
+ export declare const deliveryCount: (message: RabbitMessage) => number;
132
+ /**
133
+ * This function makes a RabbitMQ client, a dependency of a service over amqplib 2.
134
+ * - It has one connection and one confirm channel, as one generation. The end of either one ends
135
+ * the generation. The client then connects again by itself, to the next node, after a backoff.
136
+ * - It sets each timer of amqplib from the declaration. The built-in recovery of amqplib stays off.
137
+ * - Its call is a confirmed publish, or an RPC with a reply. Each call has a timer of the wrapper, because amqplib has none.
138
+ * - It tells the outcome of a call in three values, and it settles each call in flight at the end of its generation (C8, C10).
139
+ * - It records the node and the name of each connection at the open of its channel (D1).
140
+ *
141
+ * These parts come from the core of the clients: the outcomes, the second try, the wait for a ready client and the backoff.
142
+ * The calls in flight, the bounded close and the checks also come from the core. This entry gives what amqplib does in its own way.
143
+ */
144
+ export declare const rabbitClient: (name: string, spec: RabbitClientSpec, options?: RabbitClientOptions) => RabbitClient;