@mark1russell7/service 0.6.0 → 0.6.2

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 (48) hide show
  1. package/README.md +42 -3
  2. package/build/{builder-BNAkpeTT.d.ts → builder-0OlfomVU.d.ts} +2 -2
  3. package/build/{core-CWsGgr9J.d.ts → core-Iy9rIXOT.d.ts} +3 -3
  4. package/build/{dial-JEJavY0U.d.ts → dial-DLT7bTlA.d.ts} +2 -2
  5. package/build/grpc.d.ts +3 -3
  6. package/build/grpc.js +1 -1
  7. package/build/http-client.d.ts +3 -3
  8. package/build/http-client.js +1 -1
  9. package/build/http.d.ts +17 -3
  10. package/build/http.js +53 -10
  11. package/build/http.js.map +1 -1
  12. package/build/index.d.ts +48 -131
  13. package/build/index.js +98 -13
  14. package/build/index.js.map +1 -1
  15. package/build/{lifecycle-CCDLvXLF.d.ts → lifecycle-DXK880vG.d.ts} +44 -3
  16. package/build/{limiter-B0849Vhp.d.ts → limiter-BoZkXIxk.d.ts} +2 -2
  17. package/build/{limiter-pkBZUp-t.js → limiter-CmC4vCjk.js} +21 -13
  18. package/build/limiter-CmC4vCjk.js.map +1 -0
  19. package/build/limiter.d.ts +3 -3
  20. package/build/limiter.js +1 -1
  21. package/build/{machine-DZMb_QEU.js → machine-Dq2OlzCG.js} +7 -20
  22. package/build/machine-Dq2OlzCG.js.map +1 -0
  23. package/build/mongodb.d.ts +3 -3
  24. package/build/mongodb.js +1 -1
  25. package/build/pg.d.ts +2 -2
  26. package/build/pg.js +1 -1
  27. package/build/{queue-eLs5IruM.d.ts → queue-CvBNNZZJ.d.ts} +2 -2
  28. package/build/rabbitmq.d.ts +4 -4
  29. package/build/rabbitmq.js +1 -1
  30. package/build/redis.d.ts +3 -3
  31. package/build/redis.js +1 -1
  32. package/build/retrier-CRda6z9G.js +73 -0
  33. package/build/retrier-CRda6z9G.js.map +1 -0
  34. package/build/rules-BBRopO1e.d.ts +145 -0
  35. package/build/rules.d.ts +2 -0
  36. package/build/rules.js +128 -0
  37. package/build/rules.js.map +1 -0
  38. package/build/{store-D5HLgBnW.d.ts → store-Cwuepb-z.d.ts} +14 -3
  39. package/build/testing.d.ts +4 -2
  40. package/build/testing.js +12 -1
  41. package/build/testing.js.map +1 -1
  42. package/build/websocket.d.ts +3 -3
  43. package/build/websocket.js +1 -1
  44. package/package.json +7 -3
  45. package/build/limiter-pkBZUp-t.js.map +0 -1
  46. package/build/machine-DZMb_QEU.js.map +0 -1
  47. package/build/operation-DL5RxFds.js +0 -25
  48. package/build/operation-DL5RxFds.js.map +0 -1
package/README.md CHANGED
@@ -78,6 +78,10 @@ The format of a description is `mark1russell7.service/1`.
78
78
  - **The answers that did not go.** The event of that cap (`phase.cap`) gives the cause and the count, for example `answers not flushed: 2`. The close of the transports then destroys those sockets.
79
79
  - **Work that did not end.** A call whose end did not come, a transport that did not end its drain, or a step of an owner still fails the phase. The exit code is then 1, as before.
80
80
  - **Only the work of the drain.** The drain waits only for the streams that `life.request` of its lifecycle made, because only its cut ends them. A stream of another lifecycle, or of none, does not hold the drain. The record of the drain gives their count, for example `streams outside the lifecycle: 1`. Thus each exit code is the exit code of 0.5.4.
81
+ - **Uncaught errors.** `run({ uncaught: { exitCode, ignore } })` adds a handler for `uncaughtException` and `unhandledRejection` from the start to the exit. Without the option, the runtime adds no handler, as before.
82
+ - **An uncaught error starts the shutdown.** The error is an error of the lifecycle, and the logger gets it at `error`, with its stack. Then the staged shutdown starts with `exitCode`, as a signal does. The default code is 1.
83
+ - **Skipped errors.** `ignore(error, origin)` tells if the runtime skips an error, for example an `ECONNRESET` or an `EPIPE` of a peer socket. The logger gets a skipped error at `warn`, and the service continues.
84
+ - **The port of the errors.** The runtime adds the handler through `ProcessPort.onUncaught`, an optional method. `embeddedProcess()` does not have it, because the owner of the process keeps its errors.
81
85
  - **Exit codes.** `life.shutdown(cause, { code })` gives the exit code of the work, a whole number from 0 to 255. The first request with a code sets it. `svc.exitCode(trigger, code)` gives the code of a shutdown that a trigger starts, for example 130 for SIGINT. A code that is not 0 stays after an error. A code of 0, or no code, becomes 1 after an error.
82
86
  - **The output.** The stage `flush the output` comes last. The owners of the phase write their last output first, for example a log or a trace exporter. Then the `ProcessPort` writes the buffered output of stdout and stderr, in the cap of the stage. Without this phase, the process exits without a wait, as in 0.4.
83
87
  - **The hold.** The lifecycle holds its process from its start to its exit, through `ProcessPort.hold`, as a listening socket does. The hold is one timer of the event loop, and the exit releases it. The other timers of the runtime still do not keep the process alive (A14).
@@ -86,6 +90,7 @@ The format of a description is `mark1russell7.service/1`.
86
90
  - **The logger.** `run({ logger })` and `start({ logger })` give each transition of the machines to a logger, as an entry with a level and fields. The logger is one sink of the same stream as `record` (`logEvents`).
87
91
  - **The levels.** Each step of the startup, each phase with its cap, its outcome and its duration, and the exit code are `info`. A phase at its cap is `warn`, and an error of the lifecycle is `error`. The polls are `debug`.
88
92
  - **The logger port.** A `Logger` has one method, `log(level, message, fields)`, thus an adapter to another logger is a few lines. `consoleLogger({ level })` writes to the console at `info` and above by default.
93
+ - **Lines of JSON.** `consoleLogger({ level, format: "json" })` writes one line of JSON for each entry, with `level`, `message` and each field. An error field gives its name, its message and its stack. The default format is `text`, as before.
89
94
  - **No logger.** Without a logger, the runtime writes no log, as before. `testLogger()` of `@mark1russell7/service/testing` keeps each entry, thus a test can examine the log.
90
95
 
91
96
  ## The machines
@@ -286,6 +291,22 @@ await life.shutdown("the command ended", { code: end.kind === "done" ? items[0]
286
291
  - **The output.** The stage `flush the output` waits for stdout and stderr. Thus the last lines of a command are not cut.
287
292
  - **The dependencies.** The phase `tear down dependencies` caps the close of the dependencies at 2 s.
288
293
 
294
+ ## The drain rules
295
+
296
+ The caller of `lint()` and `lintStop()` gives the rules. `@mark1russell7/service/rules` gives the rules of the drain as data: `O04`, `O09`, `O10`, `O16` and the list `DRAIN_RULES`. The entry loads no module at run time. Thus it loads no Testcontainers, no `node:` module and no zod, and a service can import it in its tests. The root of the package also gives each rule, and `@mark1russell7/kind` gives the same objects.
297
+
298
+ - **O04.** The preStop sleep plus the hold of `fail readiness` is at least the propagation of the endpoints.
299
+ - **O09.** Readiness detection plus the propagation is no longer than liveness detection plus the preStop sleep.
300
+ - **O10.** The preStop sleep plus the drain of the process fits in the grace period.
301
+ - **O16.** The cooperative window is shorter than the drain, and the drain is shorter than the grace less the preStop sleep.
302
+
303
+ ```ts
304
+ import { lint } from "@mark1russell7/service";
305
+ import { DRAIN_RULES } from "@mark1russell7/service/rules";
306
+
307
+ const findings = lint(svc.describe(), scenario, DRAIN_RULES);
308
+ ```
309
+
289
310
  ## The timers
290
311
 
291
312
  The clock, the heartbeat and the backoff have their own entries. Each entry imports no `node:` module, no zod and no other package. Thus a client in a browser can use them. Each entry is less than 1 kB of gzip. The root of the package also gives each function.
@@ -304,9 +325,13 @@ The clock, the heartbeat and the backoff have their own entries. Each entry impo
304
325
  - **The backoff.** `backoffDelay(policy, attempt, random)` gives the delay before a try: `base × factor^(attempt − 1)`, at most `cap`, with a jitter. The first try is 1.
305
326
  - **The jitter.** The jitter `subtract` takes a random part of the delay away, and a fraction of 1 is the full jitter. The jitter `add` adds a random time up to an amount.
306
327
  - **The band.** `backoffBand(policy, attempt)` gives the least and the most delay of one try. Without a try, it covers each try. The law reads the most delay from it. `backoffProblems(policy)` names each value that the delays cannot use.
328
+ - **The retrier.** `retrier({ base, factor, cap, jitter, clock, signal })` starts a function again after the backoff of each try. The root of the package gives it, and the entry `./backoff` does not.
329
+ - **The calls of a retrier.** `schedule(run)` counts one more try, and starts `run` after the delay of that try, on the clock. It gives the delay, and `attempts` gives the count. A second `schedule` stops the retry that waits.
330
+ - **The end of a retrier.** `reset()` sets the count to 0, for example after a start that succeeded. `cancel()` stops the retry that waits. The abort of `signal` cancels the retrier, for example the `signal` of the lifecycle in the drain.
307
331
  - **Milliseconds.** These functions take times in milliseconds, as the clock does. The declaration and the law keep their amounts (`Quantity`).
308
332
 
309
333
  ```ts
334
+ import { retrier } from "@mark1russell7/service";
310
335
  import { backoffDelay } from "@mark1russell7/service/backoff";
311
336
  import { heartbeat } from "@mark1russell7/service/heartbeat";
312
337
 
@@ -323,6 +348,15 @@ socket.addEventListener("message", (event) => {
323
348
 
324
349
  // full jitter: a random time from 0 to the backoff
325
350
  const delay = backoffDelay({ base: 1000, factor: 1.5, cap: 30_000, jitter: { kind: "subtract", fraction: 1 } }, attempt);
351
+
352
+ // a watch that starts again after each failure, until the drain of the service
353
+ const rewatch = retrier({ base: 1000, factor: 2, cap: 30_000, jitter: { kind: "subtract", fraction: 1 }, signal: life.signal });
354
+ const watch = (): void => {
355
+ start().then(
356
+ () => rewatch.reset(),
357
+ () => rewatch.schedule(watch),
358
+ );
359
+ };
326
360
  ```
327
361
 
328
362
  ## The keyed limiter
@@ -332,7 +366,7 @@ A keyed limiter gives each key its own limit, for example each tenant or each pr
332
366
  | Export | Function |
333
367
  | --- | --- |
334
368
  | `svc.limiter(name, spec)` | The declaration of a limiter, as data. `describe()` shows it in `limiters`. |
335
- | `keyedLimiter(name, spec, store)` | The runtime of a limiter: `take(key)` gives a `Decision` |
369
+ | `keyedLimiter(name, spec, store)` | The runtime of a limiter: `take(key)` gives a `Decision`, and `tryTakeSync(key)` gives it at once on a memory store |
336
370
  | `memoryStore(clock)` | The store of one replica, on the injected monotonic clock |
337
371
  | `decide(rule, state, now)`, `limitRule(policy)`, `freeAt(rule, state)` | The arithmetic of each store, for a store of your own |
338
372
  | `idleSpan(policy)`, `longestRetryAfter(policy)`, `retryAfterSeconds(retryAfter)` | The times of a policy, and `Retry-After` in whole seconds |
@@ -346,6 +380,8 @@ A keyed limiter gives each key its own limit, for example each tenant or each pr
346
380
  - **A token bucket.** `{ type: "token-bucket", rate, burst }` gives a key `burst` takes at once, and then `rate` takes in each unit of time. The rate is a count for each unit of time, for example `count/s` or `count/min`.
347
381
  - **A sliding window.** `{ type: "sliding-window", limit, window }` gives a key at most `limit` takes in each window. Each take counts for one window from its time. Graph limits its writes with this policy.
348
382
  - **The decision.** `take(key)` gives `{ allowed: true, remaining }` or `{ allowed: false, retryAfter, cause }`. `retryAfter` is a `Quantity` above zero: the time until the limiter lets the same take in. The cause is `limit`, `cap` or `store`.
383
+ - **A take with no promise.** `tryTakeSync(key)` gives the same `Decision` at once. `keyedLimiter` on a `memoryStore` gives a `LocalLimiter`, whose type has it. On `KeyedLimiter`, it is optional.
384
+ - **Only a local store.** `tryTakeSync` throws for a shared store, before the take. It also throws for a local store whose take gives a promise. That take still counts, thus use `take()` with such a store.
349
385
  - **The clock.** `memoryStore(clock)` reads time only through its clock. Thus a step of the wall clock moves no count, and a fake clock gives exact decisions in a test.
350
386
  - **The store.** A `LimiterStore` decides each take in one atomic step, on its own clock. A store in another process does the arithmetic of `decide` in one step of its own. `redisLimiterStore` of `@mark1russell7/service/redis` is one script of Redis that reads `TIME`.
351
387
  - **No shared store.** With `{ kind: "local" }`, each replica keeps its own counts. For a limit L over N replicas, declare L / N on each replica.
@@ -398,8 +434,8 @@ if (!decision.allowed) return limitedResponse(decision); // 429, with Retry-Afte
398
434
  | Export | Function |
399
435
  | --- | --- |
400
436
  | `httpTransport(server, knobs, options)` | A server of `node:http` as a transport of the lifecycle, with a list of mounts |
401
- | `probeServer({ port, host, server_retry_after, kinds })` | A health server on a port of its own |
402
- | `probeHandler(health, { prefix, kinds })` | The probes as a request handler on the port of the application |
437
+ | `probeServer({ port, host, server_retry_after, kinds, paths })` | A health server on a port of its own |
438
+ | `probeHandler(health, { prefix, kinds, paths })` | The probes as a request handler on the port of the application |
403
439
  | `PROBE_KINDS` | The four probe kinds, the default of the option `kinds` |
404
440
  | `handle(controller, route, work, options)` | A request handler that does each request of a route through `life.request` |
405
441
  | `writeOutcome(res, stream, options)` | The stream of a request as a response of `node:http`, unary or a stream |
@@ -441,6 +477,9 @@ if (!decision.allowed) return limitedResponse(decision); // 429, with Retry-Afte
441
477
  - **The probe kinds.** The option `kinds` names the probes that answer, for example `["startup", "readiness", "liveness"]`. The default is all four of `PROBE_KINDS`.
442
478
  - **A kind that the list does not name.** Its path is not a probe. `probeHandler` gives it to the next handler, and `probeServer` answers it with 404. Thus a probe server can keep the report off its port.
443
479
  - **A bad list of kinds.** `probeHandler` and `probeServer` refuse an empty list, an unknown kind and a kind two times. The error names the bad part.
480
+ - **More probe paths.** The option `paths` gives more paths to a probe kind, for example `{ liveness: ["/livez", "/healthz"], readiness: ["/readyz"] }`. Each probe path of a kind still answers.
481
+ - **A more path is exact.** It is a whole path, and the prefix does not go before it. A more path of readiness has no controller after it. Without `paths`, the paths are the same as before.
482
+ - **A bad option `paths`.** The two functions refuse an unknown kind, a kind that `kinds` does not name and a path two times. They also refuse a path that is not a whole path, and a probe path of a kind.
444
483
  - **A route through the request tracking.** `handle(controller, route, work, options)` gives a request handler. Each request that it takes goes through `life.request`, thus the service admits it, counts it and can cut it.
445
484
  - **The route of a handler.** A route name takes a request whose method and path are that name, for example `POST /orders`. A function gives the name of a route or of a pattern (`controller.pattern`), or null for a request of another handler. `options.detail` gives the detail of a request for the function of a pattern.
446
485
  - **The work.** The work gets the request and a signal. The signal aborts when the shutdown cuts the request, at the cooperative abort, or when the client goes away.
@@ -1,6 +1,6 @@
1
1
  import { n as Clock } from "./clock-mVqhXD0b.js";
2
2
  import { c as LimiterSpec } from "./policy-G4QJ1ZZq.js";
3
- import { $ as Coupling, E as CheckFn, Et as ExitTrigger, K as Trace, Mt as ProcessTrigger, Q as CooperativeFloor, T as StartOptions, Vt as Operation, W as Outcome, X as Check, at as Phase, bt as OperationOf, ct as ServiceDescription, d as TransportImpl, et as Dependency, ft as Poll, it as MessageTrigger, mt as Timing, n as HealthServer, o as PhaseWork, r as Lifecycle, rt as Gate, s as RunOptions, st as RepeatSignal, t as DependencyHandle, tt as ExitCodes, x as Health } from "./lifecycle-CCDLvXLF.js";
3
+ import { D as CheckFn, E as StartOptions, Gt as Operation, J as Trace, K as Outcome, Ot as ExitTrigger, Pt as ProcessTrigger, Q as Check, S as Health, St as OperationOf, at as Gate, d as TransportImpl, et as CooperativeFloor, gt as Timing, lt as RepeatSignal, mt as Poll, n as HealthServer, nt as Dependency, o as PhaseWork, ot as MessageTrigger, r as Lifecycle, rt as ExitCodes, s as RunOptions, st as Phase, t as DependencyHandle, tt as Coupling, ut as ServiceDescription } from "./lifecycle-DXK880vG.js";
4
4
  import { Extent, Quantity } from "@mark1russell7/quantity";
5
5
  //#region src/profiles.d.ts
6
6
  /**
@@ -208,4 +208,4 @@ interface ServiceBuilder {
208
208
  declare const service: (name: string) => ServiceBuilder;
209
209
  //#endregion
210
210
  export { WatchdogSpec as a, Profile as c, kubernetes as d, localDev as f, Watchdog as i, daemon as l, ServiceBuilder as n, watchdog as o, service as r, PodTiming as s, ControllerBuilder as t, ephemeral as u };
211
- //# sourceMappingURL=builder-BNAkpeTT.d.ts.map
211
+ //# sourceMappingURL=builder-0OlfomVU.d.ts.map
@@ -1,7 +1,7 @@
1
1
  import { t as Backoff } from "./backoff-B-jGWVDm.js";
2
2
  import { n as Clock } from "./clock-mVqhXD0b.js";
3
- import { E as CheckFn, Vt as Operation, X as Check, Y as Recorder, ct as ServiceDescription, et as Dependency, ft as Poll, lt as Step, rt as Gate, t as DependencyHandle } from "./lifecycle-CCDLvXLF.js";
4
- import { n as ServiceBuilder } from "./builder-BNAkpeTT.js";
3
+ import { D as CheckFn, Gt as Operation, Q as Check, Z as Recorder, at as Gate, dt as Step, mt as Poll, nt as Dependency, t as DependencyHandle, ut as ServiceDescription } from "./lifecycle-DXK880vG.js";
4
+ import { n as ServiceBuilder } from "./builder-0OlfomVU.js";
5
5
  import { Extent, Quantity } from "@mark1russell7/quantity";
6
6
  //#region src/client/meets.d.ts
7
7
  /** A situation is what the connection did when the failure started: a command in flight, or idle. */
@@ -230,4 +230,4 @@ declare const retryProblems: (name: string, knobs: RetryKnobs) => string[];
230
230
  declare const STARTING_POLL: Poll;
231
231
  //#endregion
232
232
  export { MANIFESTATIONS as C, firstDetector as D, Situation as E, unwatched as O, Detector as S, Meeting as T, Sent as _, ClientKnobs as a, retryProblems as b, ClientSpec as c, Factory as d, ReadyWait as f, SendOptions as g, STARTING_POLL as h, ClientJoin as i, ClientStep as l, RetrySchedule as m, CheckOptions as n, ClientOptions as o, RetryKnobs as p, Client as r, ClientSocket as s, Attempt as t, DialFn as u, readyWait as v, Manifestation as w, retrySchedule as x, retryBackoff as y };
233
- //# sourceMappingURL=core-CWsGgr9J.d.ts.map
233
+ //# sourceMappingURL=core-Iy9rIXOT.d.ts.map
@@ -1,4 +1,4 @@
1
- import "./core-CWsGgr9J.js";
1
+ import "./core-Iy9rIXOT.js";
2
2
  //#region src/client/dial.d.ts
3
3
  /**
4
4
  * A judge reads the bytes that the server sent so far. It gives null for a good answer, an error for
@@ -13,4 +13,4 @@ type Judge = (received: Buffer) => Error | null | "more";
13
13
  declare const statusLineJudge: (accept: (status: number, line: string) => Error | null) => Judge;
14
14
  //#endregion
15
15
  export { statusLineJudge as n, Judge as t };
16
- //# sourceMappingURL=dial-JEJavY0U.d.ts.map
16
+ //# sourceMappingURL=dial-DLT7bTlA.d.ts.map
package/build/grpc.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { Vt as Operation, ft as Poll } from "./lifecycle-CCDLvXLF.js";
2
- import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, b as retryProblems, c as ClientSpec, d as Factory, f as ReadyWait, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, p as RetryKnobs, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as readyWait, w as Manifestation } from "./core-CWsGgr9J.js";
3
- import { t as Judge } from "./dial-JEJavY0U.js";
1
+ import { Gt as Operation, mt as Poll } from "./lifecycle-DXK880vG.js";
2
+ import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, b as retryProblems, c as ClientSpec, d as Factory, f as ReadyWait, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, p as RetryKnobs, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as readyWait, w as Manifestation } from "./core-Iy9rIXOT.js";
3
+ import { t as Judge } from "./dial-DLT7bTlA.js";
4
4
  import { Extent, Quantity } from "@mark1russell7/quantity";
5
5
  import { Machine } from "@mark1russell7/algebra";
6
6
  //#region src/grpc/connection.d.ts
package/build/grpc.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { realClock } from "./clock.js";
2
2
  import { i as heartbeatDetection } from "./timing-DGRi3XCI.js";
3
- import { B as zeroProblems, C as notSent, D as readyWait, F as timeProblems, G as immediate, H as NEVER, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, h as finiteMs, i as authority, j as roundTripCheck, k as retryProblems, l as attachClient, m as dialCheck, n as closeTimer, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-DZMb_QEU.js";
3
+ import { B as zeroProblems, C as notSent, D as readyWait, F as timeProblems, G as immediate, H as NEVER, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, h as finiteMs, i as authority, j as roundTripCheck, k as retryProblems, l as attachClient, m as dialCheck, n as closeTimer, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-Dq2OlzCG.js";
4
4
  //#region src/grpc/connection.ts
5
5
  /** These states are in the sequence of the enum of grpc-js: the index of a state is its value. */
6
6
  const GRPC_STATES = [
@@ -1,7 +1,7 @@
1
1
  import { n as Clock } from "./clock-mVqhXD0b.js";
2
- import { Vt as Operation, ft as Poll } from "./lifecycle-CCDLvXLF.js";
3
- import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, c as ClientSpec, d as Factory, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, r as Client, s as ClientSocket, t as Attempt, u as DialFn, w as Manifestation } from "./core-CWsGgr9J.js";
4
- import { t as Judge } from "./dial-JEJavY0U.js";
2
+ import { Gt as Operation, mt as Poll } from "./lifecycle-DXK880vG.js";
3
+ import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, c as ClientSpec, d as Factory, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, r as Client, s as ClientSocket, t as Attempt, u as DialFn, w as Manifestation } from "./core-Iy9rIXOT.js";
4
+ import { t as Judge } from "./dial-DLT7bTlA.js";
5
5
  import { Extent, Quantity } from "@mark1russell7/quantity";
6
6
  import { Machine } from "@mark1russell7/algebra";
7
7
  //#region src/http-client/connection.d.ts
@@ -1,6 +1,6 @@
1
1
  import { realClock } from "./clock.js";
2
2
  import { heartbeat } from "./heartbeat.js";
3
- import { B as zeroProblems, C as notSent, E as poolProblems, F as timeProblems, G as immediate, I as trackWithTimer, J as keepaliveSilent, K as keepaliveAnswered, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, i as authority, j as roundTripCheck, l as attachClient, m as dialCheck, n as closeTimer, o as statusLineJudge, q as keepaliveReset, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, v as keepaliveOnProblems, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-DZMb_QEU.js";
3
+ import { B as zeroProblems, C as notSent, E as poolProblems, F as timeProblems, G as immediate, I as trackWithTimer, J as keepaliveSilent, K as keepaliveAnswered, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, i as authority, j as roundTripCheck, l as attachClient, m as dialCheck, n as closeTimer, o as statusLineJudge, q as keepaliveReset, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, v as keepaliveOnProblems, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-Dq2OlzCG.js";
4
4
  import { quantity } from "@mark1russell7/quantity";
5
5
  //#region src/http-client/connection.ts
6
6
  /**
package/build/http.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { n as Clock } from "./clock-mVqhXD0b.js";
2
2
  import { d as Refused } from "./policy-G4QJ1ZZq.js";
3
- import { d as TransportImpl, m as RequestEnd, n as HealthServer, r as Lifecycle, v as RequestStream, w as ProbeKind, x as Health, y as RequestWork } from "./lifecycle-CCDLvXLF.js";
3
+ import { S as Health, T as ProbeKind, b as RequestWork, d as TransportImpl, h as RequestEnd, n as HealthServer, r as Lifecycle, y as RequestStream } from "./lifecycle-DXK880vG.js";
4
4
  import { Extent, Quantity } from "@mark1russell7/quantity";
5
5
  import { ListenOptions } from "node:net";
6
6
  import { IncomingMessage, Server, ServerEventMap, ServerResponse } from "node:http";
@@ -161,13 +161,20 @@ type HealthSource = Health | (() => Health | null | undefined);
161
161
  * answer all four, unless their option `kinds` names fewer.
162
162
  */
163
163
  export declare const PROBE_KINDS: readonly ProbeKind[];
164
+ /**
165
+ * Probe paths are more paths for each probe kind, for example `{ liveness: ["/livez", "/healthz"] }`.
166
+ * Each path is a whole path, and the prefix does not go before it. The paths of `PROBE_KINDS` still answer.
167
+ */
168
+ type ProbePaths = Partial<Readonly<Record<ProbeKind, readonly string[]>>>;
164
169
  /**
165
170
  * This function gives the response of a probe path from the cache of the health runtime. For a path
166
171
  * that is not a probe, it gives null. The paths are `/startup`, `/readiness`, `/liveness` and
167
172
  * `/report` after the prefix. `/readiness/<controller>` gives the readiness of one controller.
168
173
  * `kinds` names the probes that answer. The path of a kind that it does not name is not a probe.
174
+ *
175
+ * `aliases` gives the probe kind of each more path. A more path of readiness has no controller.
169
176
  */
170
- export declare const probeResponse: (health: Health | null | undefined, method: string | undefined, path: string, prefix?: string, kinds?: readonly ProbeKind[]) => ProbeResponse | null;
177
+ export declare const probeResponse: (health: Health | null | undefined, method: string | undefined, path: string, prefix?: string, kinds?: readonly ProbeKind[], aliases?: ReadonlyMap<string, ProbeKind>) => ProbeResponse | null;
171
178
  /** These options mount the probes on the port of the application. */
172
179
  interface ProbeHandlerOptions {
173
180
  /** This path goes before each probe path, for example `/health`. It starts with `/`, or it is empty. */
@@ -177,6 +184,11 @@ interface ProbeHandlerOptions {
177
184
  * path of a kind that the list does not name goes to the next handler.
178
185
  */
179
186
  readonly kinds?: readonly ProbeKind[] | undefined;
187
+ /**
188
+ * These are more paths for each probe kind, for example `{ liveness: ["/livez", "/healthz"] }`. Each is
189
+ * a whole path, with no prefix. Without them, the handler answers only the paths of `PROBE_KINDS`.
190
+ */
191
+ readonly paths?: ProbePaths | undefined;
180
192
  }
181
193
  /**
182
194
  * This function gives a request handler that answers the probes on the port of the application. It
@@ -200,6 +212,8 @@ interface ProbeServerOptions extends ListenOptions {
200
212
  * of a kind that the list does not name gets 404, as each other path.
201
213
  */
202
214
  readonly kinds?: readonly ProbeKind[] | undefined;
215
+ /** These are more paths for each probe kind, as the option `paths` of `probeHandler`. */
216
+ readonly paths?: ProbePaths | undefined;
203
217
  }
204
218
  /** A probe server is a health server on its own port. Its server is visible for the address of the port. */
205
219
  interface ProbeServer extends HealthServer {
@@ -322,5 +336,5 @@ interface HandleOptions<T> extends Omit<OutcomeOptions<T>, "keepAlive" | "retryA
322
336
  */
323
337
  export declare const handle: <T>(controller: string, route: HandledRoute, work: HandledWork<T>, options?: HandleOptions<T>) => RequestHandler;
324
338
  //#endregion
325
- export type { EdgeServer, HandleOptions, HandledRoute, HandledWork, HealthSource, HttpKnobs, HttpTransport, HttpTransportKnobs, HttpTransportOptions, MountContext, MountOptions, MountStage, OutcomeOptions, OutcomeResponse, ProbeHandlerOptions, ProbeKind, ProbeResponse, ProbeServer, ProbeServerOptions, RequestHandler, ResponsePart, StreamFormat, UpgradeHandler, UpgradeMatch, UpgradeSocket };
339
+ export type { EdgeServer, HandleOptions, HandledRoute, HandledWork, HealthSource, HttpKnobs, HttpTransport, HttpTransportKnobs, HttpTransportOptions, MountContext, MountOptions, MountStage, OutcomeOptions, OutcomeResponse, ProbeHandlerOptions, ProbeKind, ProbePaths, ProbeResponse, ProbeServer, ProbeServerOptions, RequestHandler, ResponsePart, StreamFormat, UpgradeHandler, UpgradeMatch, UpgradeSocket };
326
340
  //# sourceMappingURL=http.d.ts.map
package/build/http.js CHANGED
@@ -545,6 +545,48 @@ const kindsOf = (kinds) => {
545
545
  }
546
546
  return Object.freeze([...kinds]);
547
547
  };
548
+ const NO_ALIASES = /* @__PURE__ */ new Map();
549
+ /**
550
+ * This function gives the probe kind of each more path of an option `paths`. It refuses a key that is
551
+ * not a probe kind, and a kind that `kinds` does not name. It refuses a path that does not start
552
+ * with `/`, or ends with `/`. It also refuses a path two times, and a path of `PROBE_KINDS` after the prefix.
553
+ */
554
+ const aliasesOf = (paths, kinds, prefix) => {
555
+ if (paths === void 0) return NO_ALIASES;
556
+ if (paths === null || typeof paths !== "object" || Array.isArray(paths)) throw new Error(`the probe paths ${JSON.stringify(paths)} are not an object of probe kinds`);
557
+ const aliases = /* @__PURE__ */ new Map();
558
+ for (const [key, list] of Object.entries(paths)) {
559
+ const kind = key;
560
+ if (!PROBE_KINDS.includes(kind)) throw new Error(`the probe paths name ${JSON.stringify(key)}, which is not one of ${named}`);
561
+ if (!kinds.includes(kind)) throw new Error(`the probe paths name "${kind}", but the probe kinds do not`);
562
+ if (!Array.isArray(list)) throw new Error(`the probe paths of "${kind}" are not a list`);
563
+ for (const path of list) {
564
+ if (typeof path !== "string" || !path.startsWith("/") || path.length < 2 || path.endsWith("/") || /[?#]/.test(path)) throw new Error(`the probe path ${JSON.stringify(path)} of "${kind}" does not start with "/", ends with "/", or has a query`);
565
+ if (aliases.has(path)) throw new Error(`the probe path "${path}" is two times in the probe paths`);
566
+ if (PROBE_KINDS.some((each) => path === `${prefix}/${each}` || path.startsWith(`${prefix}/${each}/`))) throw new Error(`the probe path "${path}" is a path of a probe kind after the prefix "${prefix}"`);
567
+ aliases.set(path, kind);
568
+ }
569
+ }
570
+ return aliases;
571
+ };
572
+ /** This function gives the probe kind and the controller of a path, or null for a path that is not a probe. */
573
+ const probeTarget = (path, prefix, kinds, aliases) => {
574
+ const alias = aliases.get(path);
575
+ if (alias !== void 0) return {
576
+ kind: alias,
577
+ controller: void 0
578
+ };
579
+ if (!path.startsWith(`${prefix}/`)) return null;
580
+ const parts = path.slice(prefix.length + 1).split("/");
581
+ const kind = PROBE_KINDS.find((each) => each === parts[0] && kinds.includes(each));
582
+ if (kind === void 0) return null;
583
+ const controller = parts[1];
584
+ if (parts.length > 2 || controller !== void 0 && (kind !== "readiness" || controller === "")) return null;
585
+ return {
586
+ kind,
587
+ controller
588
+ };
589
+ };
548
590
  const prefixProblem = (prefix) => prefix === "" || prefix.startsWith("/") && !prefix.endsWith("/") ? null : `the probe prefix "${prefix}" does not start with "/", or it ends with "/"`;
549
591
  /** These escapes replace `<`, `>` and `&` in a JSON body. The JSON stays valid, with the same value, and no part of it is markup. */
550
592
  const ESCAPES = {
@@ -569,14 +611,13 @@ const json = (status, body) => ({
569
611
  * that is not a probe, it gives null. The paths are `/startup`, `/readiness`, `/liveness` and
570
612
  * `/report` after the prefix. `/readiness/<controller>` gives the readiness of one controller.
571
613
  * `kinds` names the probes that answer. The path of a kind that it does not name is not a probe.
614
+ *
615
+ * `aliases` gives the probe kind of each more path. A more path of readiness has no controller.
572
616
  */
573
- const probeResponse = (health, method, path, prefix = "", kinds = PROBE_KINDS) => {
574
- if (!path.startsWith(`${prefix}/`)) return null;
575
- const parts = path.slice(prefix.length + 1).split("/");
576
- const kind = PROBE_KINDS.find((each) => each === parts[0] && kinds.includes(each));
577
- if (kind === void 0) return null;
578
- const controller = parts[1];
579
- if (parts.length > 2 || controller !== void 0 && (kind !== "readiness" || controller === "")) return null;
617
+ const probeResponse = (health, method, path, prefix = "", kinds = PROBE_KINDS, aliases = NO_ALIASES) => {
618
+ const target = probeTarget(path, prefix, kinds, aliases);
619
+ if (target === null) return null;
620
+ const { kind, controller } = target;
580
621
  if (method !== "GET" && method !== "HEAD") return {
581
622
  status: 405,
582
623
  headers: {
@@ -630,9 +671,10 @@ const probeHandler = (health, options) => {
630
671
  const problem = prefixProblem(options.prefix);
631
672
  if (problem !== null) throw new Error(problem);
632
673
  const kinds = kindsOf(options.kinds);
674
+ const aliases = aliasesOf(options.paths, kinds, options.prefix);
633
675
  const handler = (req, res, context) => {
634
676
  const runtime = typeof health === "function" ? health() : health;
635
- const response = probeResponse(runtime, req.method, pathOf(req.url), options.prefix, kinds);
677
+ const response = probeResponse(runtime, req.method, pathOf(req.url), options.prefix, kinds, aliases);
636
678
  if (response === null) return false;
637
679
  const retryAfter = context?.retryAfter === void 0 ? void 0 : retryAfterOf({ server_retry_after: context.retryAfter }, "probeHandler");
638
680
  write(req, res, response, retryAfter);
@@ -646,11 +688,12 @@ const probeHandler = (health, options) => {
646
688
  * each 503 gets the `Retry-After` of `server_retry_after`.
647
689
  */
648
690
  const probeServer = (options) => {
649
- const { prefix = "", server = createServer(), server_retry_after, kinds: chosen, ...listen } = options;
691
+ const { prefix = "", server = createServer(), server_retry_after, kinds: chosen, paths, ...listen } = options;
650
692
  const retryAfter = retryAfterOf({ server_retry_after }, "probeServer");
651
693
  const problem = prefixProblem(prefix);
652
694
  if (problem !== null) throw new Error(problem);
653
695
  const kinds = kindsOf(chosen);
696
+ const aliases = aliasesOf(paths, kinds, prefix);
654
697
  if (server.listenerCount("request") > 0) throw new Error("the probe server has a request listener of its own");
655
698
  let health = null;
656
699
  let closing = null;
@@ -660,7 +703,7 @@ const probeServer = (options) => {
660
703
  socket.once("close", () => sockets.delete(socket));
661
704
  });
662
705
  server.on("request", (req, res) => {
663
- const response = probeResponse(health, req.method, pathOf(req.url), prefix, kinds);
706
+ const response = probeResponse(health, req.method, pathOf(req.url), prefix, kinds, aliases);
664
707
  write(req, res, response ?? {
665
708
  status: 404,
666
709
  headers: { "content-type": "text/plain; charset=utf-8" },