@mark1russell7/service 0.2.0 → 0.4.0

package/README.md

@@ -14,6 +14,7 @@ This release has the declaration, its export, the law, the health runtime and th
 - **Keyed operations.** A keyed operation has the window that the server keeps its key for. `mayReissue` answers from the declaration of an operation. An operation without a declaration does not go again.
 - **The law.** `evaluate` and `verdictOf` decide one rule of the timer-ordering law on one binding. A rule is data: linear inequalities over `symbol@hop`, with a margin. A verdict is `holds`, `violated`, `unbounded` (it holds only because a timer is absent) or `depends` (nothing is bound).
 - **The linter.** `lint(description, scenario, rules)` applies the service rules (`SERVICE_RULES`) to a declaration. The declaration binds the symbols of the service: the polls of its checks, the windows of its policies, its drain. The scenario binds the symbols of the platform and of each dependency. A `depends` finding names the symbols that have no bound.
+- **The hold.** The cap of the `fail readiness` phase binds `readiness_hold@process`, and a service without that phase holds for zero. The hold keeps the listener open after the signal, as a preStop sleep does. Thus O04 can compare the sum of the two with the propagation of the endpoints.
 
 The format of a description is `mark1russell7.service/1`.
 
@@ -50,10 +51,49 @@ The format of a description is `mark1russell7.service/1`.
 
 ## The machines
 
-The machines of the runtime are `mark1russell7.machine/1` documents, which `@mark1russell7/algebra` reads. They are the gate, the latch (a debounce), the window, the poller, the exit manager and the watchdog. `drainMachine(description)` gives the drain of a declaration, with one state for each phase. Each machine gives its transitions to `run({ record })` or `start({ record })`. `replay(doc, events)` gives each transition that the document does not permit.
+The machines of the runtime are `mark1russell7.machine/1` documents, which `@mark1russell7/algebra` reads. They are the gate, the latch (a debounce), the window, the poller, the exit manager and the watchdog. `drainMachine(description)` gives the drain of a declaration, with one state for each phase. Each machine gives its transitions to `run({ record })` or `start({ record })`. `replay(doc, events)` gives each transition that the document does not permit. It is the replay of `@mark1russell7/algebra`, which reads a machine of any name.
 
 The tests replay the real runtime against each document. They also compare each timer of the documents, from the algebra, with the time that the runtime keeps.
 
+## The timers
+
+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.
+
+| Entry | Exports |
+| --- | --- |
+| `@mark1russell7/service/clock` | `Clock`, `Cancel`, `realClock`, `platformClock` |
+| `@mark1russell7/service/heartbeat` | `heartbeat`, `detectionTime` |
+| `@mark1russell7/service/backoff` | `backoffDelay`, `backoffBand`, `backoffProblems` |
+
+- **The clock.** `platformClock({ unref })` gives a clock on `performance.now()` and `setTimeout`. With `unref: true`, its timers do not keep a Node process alive. `realClock` is that clock. Each cancel also has `unref`, for one timer.
+- **The heartbeat.** `heartbeat(options)` sends a ping each interval, and a timeout bounds each ping. A ping without an answer at its timeout is a miss. The last of `misses` misses in sequence starts `onDead`.
+- **Two kinds of ping.** A ping gives its answer as a promise, as a request and its reply do. Or the answer comes later through `answer()`, as a pong message does.
+- **The hooks of a heartbeat.** At each tick, `due` tells if the tick sends a ping. `live` tells if a miss counts. `turn` waits one turn of the event loop before the heartbeat counts. Without `overlap`, the heartbeat sends one ping at a time.
+- **The detection time.** `detectionTime(interval, timeout, misses)` gives the most time to find a silent peer: `misses` intervals plus a timeout. `heartbeatDetection` gives that time as an amount for the law.
+- **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.
+- **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.
+- **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.
+- **Milliseconds.** These functions take times in milliseconds, as the clock does. The declaration and the law keep their amounts (`Quantity`).
+
+```ts
+import { backoffDelay } from "@mark1russell7/service/backoff";
+import { heartbeat } from "@mark1russell7/service/heartbeat";
+
+const beat = heartbeat({
+  interval: 30_000,
+  timeout: 10_000,
+  misses: 2,
+  ping: () => socket.send(JSON.stringify({ type: "ping" })),
+  onDead: () => socket.close(),
+});
+socket.addEventListener("message", (event) => {
+  if (JSON.parse(event.data).type === "pong") beat.answer();
+});
+
+// full jitter: a random time from 0 to the backoff
+const delay = backoffDelay({ base: 1000, factor: 1.5, cap: 30_000, jitter: { kind: "subtract", fraction: 1 } }, attempt);
+```
+
 ## The testing subpath
 
 `@mark1russell7/service/testing` has the seams that a test of a service needs:
@@ -71,10 +111,11 @@ The tests replay the real runtime against each document. They also compare each
 
 - **The declaration.** `redisClient(name, spec)` declares its knobs by the names of the ordering law: `connect_bound`, `request_timeout`, `driver_writeoff_time`, `heartbeat_interval`, `client_retry_window` and others. Each knob is necessary, and a bound that nobody gives is "infinite". The client derives `heartbeat_detection_time` from its watchdog. Thus `lint()` evaluates the rules of the client (O13, O15, O17, O21, O27) on the declaration.
 - **The settings of ioredis.** The client gives ioredis each timer from the declaration. It turns off the offline queue, and it does not let ioredis send a command again. Thus a command while the client is not ready fails at once, and the command did not leave the client.
+- **The retry strategy.** `retryBackoff(knobs)` gives the backoff of the tries to connect: from `retry_base`, doubling to `retry_cap`, each delay with a jitter up to the base. The tries stop at the end of `client_retry_window`.
 - **Three outcomes.** `send(command, args)` gives `ok`, `error` or `indeterminate`. An error is a reply of the server, or a command that did not leave the client. An indeterminate command can have reached the server. When its connection closes, each command in flight becomes indeterminate at once, not at its timeout.
 - **Idempotency for each command.** A table declares the idempotency of each common command, and a declaration can change it. The client sends an idempotent command again one time at most, in the bound of the request. It does not send again a command that is not idempotent, or that the table does not name.
 - **The join.** At each `ready`, the client records `CLIENT ID` and the socket of the connection (`joins`). The prober joins its kernel records to the view of the server with it.
-- **The watchdog.** A `PING` on the connection of the application, each interval. An error reply is an answer. After the misses of the declaration, the watchdog closes the connection, and the client connects again. The watchdog acts only on a ready connection, and it starts again a client whose retry window ended.
+- **The watchdog.** A `heartbeat` of `PING` commands on the connection of the application, each interval. An error reply is an answer. After the misses of the declaration, the watchdog closes the connection, and the client connects again. The watchdog acts only on a ready connection, and it starts again a client whose retry window ended.
 - **The checks.** `checks({ poll, steps })` gives a check for each step: `local-state`, `round-trip` (a `PING` on the connection of the application) and `dial` (a new connection). Each one controls readiness, liveness or nothing. `attach(svc, options)` declares the dependency, its handle and its checks.
 - **The close.** At the shutdown, the client sends `QUIT`, and it disconnects at its `close_bound`. Thus a silent server cannot hold the phase past its cap.
 - **The manifestations.** `meets` lists the manifestations that the client can meet, and the detectors of each, with their times from the knobs. `unwatched(meets)` lists each manifestation and situation that no detector finds.
@@ -171,6 +212,8 @@ const outcome = await life.request("orders", "POST /orders", (signal) => createO
 - **The contract.** The contract of a sample declaration passes. The contract also finds a blind dependency, a check whose timeout is too short, and a check that names the wrong dependency.
 - **The Redis client.** These tests use a fake ioredis and a fake clock. They cover the declaration, the three outcomes, and the commands that the client sends again or not. They also cover the join, the backoff, the watchdog, the close, the checks and the manifestations. Five scenarios replay against the document of the client.
 - **F6 for Redis.** The fault matrix crosses each manifestation (a refusal, a frozen process, a black hole, a death without a close, and an app stall), each gating posture, two timings and two jitters. That is 60 cases on the fake. Each case holds the trip and the release of its policy to `failSpan` and `recoverSpan`. Five more cases shut the service down during each manifestation, and each one exits 0.
+- **The timers.** These tests use a fake clock, and they cover the hooks of the heartbeat and its two kinds of ping. A property test holds the death of a silent peer to `detectionTime` in 300 seeded cases. Another one compares the heartbeat with a WebSocket heartbeat that sends one ping at a time, on 300 schedules of pongs. The backoff gives the delays of three earlier backoffs, number for number, and each delay is in its band.
+- **The entries.** The timer entries reach no other package, no `node:` module and no zod.
 - **Against a real Redis.** `REDIS_IT=1` starts the tests of the client against Redis 7.4. `REDIS_F6=1` starts the F6 matrix in the VM of Docker. The injector of `@mark1russell7/harness` makes the network faults, and an agent in the namespaces of Redis makes the process faults. All of them use one monotonic clock.
 
 `pnpm --filter @mark1russell7/service build` writes the package for npm into `build/`.

package/build/backoff-B-jGWVDm.d.ts

@@ -0,0 +1,48 @@
+//#region src/backoff.d.ts
+/**
+ * A jitter is the random part of each delay. The random number `r` is from 0 up to 1.
+ * - `none`: the delay is the backoff.
+ * - `subtract`: the delay is `backoff × (1 − fraction × r)`. A fraction of 1 is the full jitter: a delay from 0 to the backoff.
+ * - `add`: the delay is `backoff + amount × r`, with the amount in milliseconds.
+ */
+type Jitter = {
+  readonly kind: "none";
+} | {
+  readonly kind: "subtract";
+  readonly fraction: number;
+} | {
+  readonly kind: "add";
+  readonly amount: number;
+};
+/** A backoff policy gives the delay before each try. Each time is in milliseconds. */
+interface Backoff {
+  /** This time is the backoff of the first try. */
+  readonly base: number;
+  /** This number multiplies the backoff from one try to the next. The default is 2. */
+  readonly factor?: number | undefined;
+  /** This time is the most that a backoff can be, before its jitter. The default is no limit. */
+  readonly cap?: number | undefined;
+  /** This jitter gives the random part of each delay. The default is `none`. */
+  readonly jitter?: Jitter | undefined;
+}
+/** A band is the least and the most delay that a policy gives, in milliseconds. */
+interface DelayBand {
+  readonly low: number;
+  readonly high: number;
+}
+/**
+ * This function gives the delay before a try, in milliseconds. The first try is 1. The delay is
+ * the backoff of the try with its jitter, and not below zero. The `random` function gives numbers from 0 up to 1.
+ */
+declare const backoffDelay: (policy: Backoff, attempt: number, random?: () => number) => number;
+/**
+ * This function gives the band of the delay before a try: the least and the most delay that the
+ * jitter can give. Without a try, the band covers each try. The ordering law reads the most delay
+ * of a policy from it.
+ */
+declare const backoffBand: (policy: Backoff, attempt?: number) => DelayBand;
+/** This function gives the problems of a policy: each value that the delays cannot use. */
+declare const backoffProblems: (policy: Backoff) => string[];
+//#endregion
+export { backoffDelay as a, backoffBand as i, DelayBand as n, backoffProblems as o, Jitter as r, Backoff as t };
+//# sourceMappingURL=backoff-B-jGWVDm.d.ts.map

package/build/backoff.d.ts

@@ -0,0 +1,2 @@
+import { a as backoffDelay, i as backoffBand, n as DelayBand, o as backoffProblems, r as Jitter, t as Backoff } from "./backoff-B-jGWVDm.js";
+export { Backoff, DelayBand, Jitter, backoffBand, backoffDelay, backoffProblems };

package/build/backoff.js

@@ -0,0 +1,70 @@
+//#region src/backoff.ts
+const NONE = { kind: "none" };
+/** This function gives the backoff of a try, before its jitter: `base × factor^(attempt − 1)`, at most the cap. */
+const backoffOf = (policy, attempt) => {
+	const grown = policy.base === 0 ? 0 : policy.base * (policy.factor ?? 2) ** (attempt - 1);
+	return Math.min(grown, policy.cap ?? Number.POSITIVE_INFINITY);
+};
+/** This function gives the band of one backoff after its jitter. */
+const jittered = (backoff, jitter) => {
+	if (jitter.kind === "subtract") return {
+		low: backoff * (1 - jitter.fraction),
+		high: backoff
+	};
+	if (jitter.kind === "add") return {
+		low: backoff,
+		high: backoff + jitter.amount
+	};
+	return {
+		low: backoff,
+		high: backoff
+	};
+};
+const tryNumber = (attempt) => {
+	if (!Number.isInteger(attempt) || attempt < 1) throw new RangeError(`a try is a whole number from 1, not ${attempt}`);
+	return attempt;
+};
+/**
+* This function gives the delay before a try, in milliseconds. The first try is 1. The delay is
+* the backoff of the try with its jitter, and not below zero. The `random` function gives numbers from 0 up to 1.
+*/
+const backoffDelay = (policy, attempt, random = Math.random) => {
+	const backoff = backoffOf(policy, tryNumber(attempt));
+	const jitter = policy.jitter ?? NONE;
+	if (jitter.kind === "subtract") return Math.max(0, backoff * (1 - jitter.fraction * random()));
+	if (jitter.kind === "add") return Math.max(0, backoff + random() * jitter.amount);
+	return Math.max(0, backoff);
+};
+/**
+* This function gives the band of the delay before a try: the least and the most delay that the
+* jitter can give. Without a try, the band covers each try. The ordering law reads the most delay
+* of a policy from it.
+*/
+const backoffBand = (policy, attempt) => {
+	const jitter = policy.jitter ?? NONE;
+	if (attempt !== void 0) return jittered(backoffOf(policy, tryNumber(attempt)), jitter);
+	const factor = policy.factor ?? 2;
+	const first = backoffOf(policy, 1);
+	const most = factor > 1 && policy.base > 0 ? policy.cap ?? Number.POSITIVE_INFINITY : first;
+	return {
+		low: jittered(factor < 1 ? 0 : first, jitter).low,
+		high: jittered(most, jitter).high
+	};
+};
+/** This function gives the problems of a policy: each value that the delays cannot use. */
+const backoffProblems = (policy) => {
+	const problems = [];
+	const factor = policy.factor ?? 2;
+	const cap = policy.cap ?? Number.POSITIVE_INFINITY;
+	if (!(Number.isFinite(policy.base) && policy.base >= 0)) problems.push(`the base ${policy.base} is not a time of zero or more`);
+	if (!(Number.isFinite(factor) && factor >= 1)) problems.push(`the factor ${factor} is not a number of 1 or more`);
+	if (!(cap >= policy.base)) problems.push(`the cap ${cap} is below the base ${policy.base}`);
+	const jitter = policy.jitter ?? NONE;
+	if (jitter.kind === "subtract" && !(jitter.fraction >= 0 && jitter.fraction <= 1)) problems.push(`the fraction ${jitter.fraction} of the jitter is not from 0 to 1`);
+	if (jitter.kind === "add" && !(Number.isFinite(jitter.amount) && jitter.amount >= 0)) problems.push(`the amount ${jitter.amount} of the jitter is not a time of zero or more`);
+	return problems;
+};
+//#endregion
+export { backoffBand, backoffDelay, backoffProblems };
+
+//# sourceMappingURL=backoff.js.map

package/build/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","names":[],"sources":["../src/backoff.ts"],"sourcesContent":["// @mark1russell7/service/backoff: the delays of an exponential backoff with a jitter, and their\n// band for the ordering law, with no other part of the package. The entry imports nothing. Thus a\n// client in a browser can use it.\n\n/**\n * A jitter is the random part of each delay. The random number `r` is from 0 up to 1.\n * - `none`: the delay is the backoff.\n * - `subtract`: the delay is `backoff × (1 − fraction × r)`. A fraction of 1 is the full jitter: a delay from 0 to the backoff.\n * - `add`: the delay is `backoff + amount × r`, with the amount in milliseconds.\n */\nexport type Jitter =\n  | { readonly kind: \"none\" }\n  | { readonly kind: \"subtract\"; readonly fraction: number }\n  | { readonly kind: \"add\"; readonly amount: number };\n\n/** A backoff policy gives the delay before each try. Each time is in milliseconds. */\nexport interface Backoff {\n  /** This time is the backoff of the first try. */\n  readonly base: number;\n  /** This number multiplies the backoff from one try to the next. The default is 2. */\n  readonly factor?: number | undefined;\n  /** This time is the most that a backoff can be, before its jitter. The default is no limit. */\n  readonly cap?: number | undefined;\n  /** This jitter gives the random part of each delay. The default is `none`. */\n  readonly jitter?: Jitter | undefined;\n}\n\n/** A band is the least and the most delay that a policy gives, in milliseconds. */\nexport interface DelayBand {\n  readonly low: number;\n  readonly high: number;\n}\n\nconst NONE: Jitter = { kind: \"none\" };\n\n/** This function gives the backoff of a try, before its jitter: `base × factor^(attempt − 1)`, at most the cap. */\nconst backoffOf = (policy: Backoff, attempt: number): number => {\n  const grown = policy.base === 0 ? 0 : policy.base * (policy.factor ?? 2) ** (attempt - 1);\n  return Math.min(grown, policy.cap ?? Number.POSITIVE_INFINITY);\n};\n\n/** This function gives the band of one backoff after its jitter. */\nconst jittered = (backoff: number, jitter: Jitter): DelayBand => {\n  if (jitter.kind === \"subtract\") return { low: backoff * (1 - jitter.fraction), high: backoff };\n  if (jitter.kind === \"add\") return { low: backoff, high: backoff + jitter.amount };\n  return { low: backoff, high: backoff };\n};\n\nconst tryNumber = (attempt: number): number => {\n  if (!Number.isInteger(attempt) || attempt < 1) throw new RangeError(`a try is a whole number from 1, not ${attempt}`);\n  return attempt;\n};\n\n/**\n * This function gives the delay before a try, in milliseconds. The first try is 1. The delay is\n * the backoff of the try with its jitter, and not below zero. The `random` function gives numbers from 0 up to 1.\n */\nexport const backoffDelay = (policy: Backoff, attempt: number, random: () => number = Math.random): number => {\n  const backoff = backoffOf(policy, tryNumber(attempt));\n  const jitter = policy.jitter ?? NONE;\n  if (jitter.kind === \"subtract\") return Math.max(0, backoff * (1 - jitter.fraction * random()));\n  if (jitter.kind === \"add\") return Math.max(0, backoff + random() * jitter.amount);\n  return Math.max(0, backoff);\n};\n\n/**\n * This function gives the band of the delay before a try: the least and the most delay that the\n * jitter can give. Without a try, the band covers each try. The ordering law reads the most delay\n * of a policy from it.\n */\nexport const backoffBand = (policy: Backoff, attempt?: number): DelayBand => {\n  const jitter = policy.jitter ?? NONE;\n  if (attempt !== undefined) return jittered(backoffOf(policy, tryNumber(attempt)), jitter);\n  // a factor above 1 grows the backoff to the cap, a factor of 1 keeps it, and a factor below 1 shrinks it to zero\n  const factor = policy.factor ?? 2;\n  const first = backoffOf(policy, 1);\n  const most = factor > 1 && policy.base > 0 ? (policy.cap ?? Number.POSITIVE_INFINITY) : first;\n  const least = factor < 1 ? 0 : first;\n  return { low: jittered(least, jitter).low, high: jittered(most, jitter).high };\n};\n\n/** This function gives the problems of a policy: each value that the delays cannot use. */\nexport const backoffProblems = (policy: Backoff): string[] => {\n  const problems: string[] = [];\n  const factor = policy.factor ?? 2;\n  const cap = policy.cap ?? Number.POSITIVE_INFINITY;\n  if (!(Number.isFinite(policy.base) && policy.base >= 0)) problems.push(`the base ${policy.base} is not a time of zero or more`);\n  if (!(Number.isFinite(factor) && factor >= 1)) problems.push(`the factor ${factor} is not a number of 1 or more`);\n  if (!(cap >= policy.base)) problems.push(`the cap ${cap} is below the base ${policy.base}`);\n  const jitter = policy.jitter ?? NONE;\n  if (jitter.kind === \"subtract\" && !(jitter.fraction >= 0 && jitter.fraction <= 1))\n    problems.push(`the fraction ${jitter.fraction} of the jitter is not from 0 to 1`);\n  if (jitter.kind === \"add\" && !(Number.isFinite(jitter.amount) && jitter.amount >= 0))\n    problems.push(`the amount ${jitter.amount} of the jitter is not a time of zero or more`);\n  return problems;\n};\n"],"mappings":";AAiCA,MAAM,OAAe,EAAE,MAAM,OAAO;;AAGpC,MAAM,aAAa,QAAiB,YAA4B;CAC9D,MAAM,QAAQ,OAAO,SAAS,IAAI,IAAI,OAAO,QAAQ,OAAO,UAAU,OAAO,UAAU;CACvF,OAAO,KAAK,IAAI,OAAO,OAAO,OAAO,OAAO,iBAAiB;AAC/D;;AAGA,MAAM,YAAY,SAAiB,WAA8B;CAC/D,IAAI,OAAO,SAAS,YAAY,OAAO;EAAE,KAAK,WAAW,IAAI,OAAO;EAAW,MAAM;CAAQ;CAC7F,IAAI,OAAO,SAAS,OAAO,OAAO;EAAE,KAAK;EAAS,MAAM,UAAU,OAAO;CAAO;CAChF,OAAO;EAAE,KAAK;EAAS,MAAM;CAAQ;AACvC;AAEA,MAAM,aAAa,YAA4B;CAC7C,IAAI,CAAC,OAAO,UAAU,OAAO,KAAK,UAAU,GAAG,MAAM,IAAI,WAAW,uCAAuC,SAAS;CACpH,OAAO;AACT;;;;;AAMA,MAAa,gBAAgB,QAAiB,SAAiB,SAAuB,KAAK,WAAmB;CAC5G,MAAM,UAAU,UAAU,QAAQ,UAAU,OAAO,CAAC;CACpD,MAAM,SAAS,OAAO,UAAU;CAChC,IAAI,OAAO,SAAS,YAAY,OAAO,KAAK,IAAI,GAAG,WAAW,IAAI,OAAO,WAAW,OAAO,EAAE;CAC7F,IAAI,OAAO,SAAS,OAAO,OAAO,KAAK,IAAI,GAAG,UAAU,OAAO,IAAI,OAAO,MAAM;CAChF,OAAO,KAAK,IAAI,GAAG,OAAO;AAC5B;;;;;;AAOA,MAAa,eAAe,QAAiB,YAAgC;CAC3E,MAAM,SAAS,OAAO,UAAU;CAChC,IAAI,YAAY,KAAA,GAAW,OAAO,SAAS,UAAU,QAAQ,UAAU,OAAO,CAAC,GAAG,MAAM;CAExF,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,QAAQ,UAAU,QAAQ,CAAC;CACjC,MAAM,OAAO,SAAS,KAAK,OAAO,OAAO,IAAK,OAAO,OAAO,OAAO,oBAAqB;CAExF,OAAO;EAAE,KAAK,SADA,SAAS,IAAI,IAAI,OACD,MAAM,CAAC,CAAC;EAAK,MAAM,SAAS,MAAM,MAAM,CAAC,CAAC;CAAK;AAC/E;;AAGA,MAAa,mBAAmB,WAA8B;CAC5D,MAAM,WAAqB,CAAC;CAC5B,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,MAAM,OAAO,OAAO,OAAO;CACjC,IAAI,EAAE,OAAO,SAAS,OAAO,IAAI,KAAK,OAAO,QAAQ,IAAI,SAAS,KAAK,YAAY,OAAO,KAAK,+BAA+B;CAC9H,IAAI,EAAE,OAAO,SAAS,MAAM,KAAK,UAAU,IAAI,SAAS,KAAK,cAAc,OAAO,8BAA8B;CAChH,IAAI,EAAE,OAAO,OAAO,OAAO,SAAS,KAAK,WAAW,IAAI,qBAAqB,OAAO,MAAM;CAC1F,MAAM,SAAS,OAAO,UAAU;CAChC,IAAI,OAAO,SAAS,cAAc,EAAE,OAAO,YAAY,KAAK,OAAO,YAAY,IAC7E,SAAS,KAAK,gBAAgB,OAAO,SAAS,kCAAkC;CAClF,IAAI,OAAO,SAAS,SAAS,EAAE,OAAO,SAAS,OAAO,MAAM,KAAK,OAAO,UAAU,IAChF,SAAS,KAAK,cAAc,OAAO,OAAO,6CAA6C;CACzF,OAAO;AACT"}

package/build/{builder-BFxOuULH.d.ts → builder-DnfUDW9u.d.ts}

@@ -1,3 +1,4 @@
+import { n as Clock } from "./clock-D-38uH_z.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
 //#region src/timing.d.ts
 /**
@@ -57,6 +58,11 @@ declare const recoverSpan: (timing: Timing, poll: Poll) => Span;
 declare const asWindow: (timing: Timing) => Timing;
 /** This function gives the debounce that approximates a window on a poll: the polls that fit, rounded up. */
 declare const asDebounce: (timing: Timing, poll: Poll) => Timing;
+/**
+ * This function gives the most time that a heartbeat takes to find a silent peer, as an amount
+ * for the ordering law (`detectionTime`). An interval of "infinite" is a heartbeat that is off.
+ */
+declare const heartbeatDetection: (interval: Extent, timeout: Quantity, misses: number) => Extent;
 //#endregion
 //#region src/operation.d.ts
 /**
@@ -182,26 +188,6 @@ interface ServiceDescription {
   };
 }
 //#endregion
-//#region src/clock.d.ts
-/** This function stops a timer that `Clock.after` started. A second use does nothing. */
-type Cancel = () => void;
-/**
- * A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The
- * runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of
- * the runtime is then exact and repeatable.
- */
-interface Clock {
-  /** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */
-  now(): number;
-  /** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */
-  after(ms: number, run: () => void): Cancel;
-}
-/**
- * This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
- * process alive, thus a timer that is not stopped cannot stop the exit of the process.
- */
-declare const realClock: Clock;
-//#endregion
 //#region src/events.d.ts
 /**
  * A machine name names one machine of the runtime. Each machine has a document in `machines.ts`,
@@ -603,5 +589,5 @@ interface ServiceBuilder {
 /** This function starts the composition of a service. */
 declare const service: (name: string) => ServiceBuilder;
 //#endregion
-export { FailsBy as $, StartOptions as A, Check as B, ProcessPort as C, HealthVerdict as D, Health as E, MachineName as F, Gate as G, Coupling as H, Recorder as I, Step as J, Phase as K, Cancel as L, Outcome as M, Result as N, ProbeAnswer as O, LifecycleEvent as P, mayReissue as Q, Clock as R, ExitSignal as S, CheckVerdict as T, Dependency as U, Controller as V, FORMAT as W, Idempotency as X, Transport as Y, Operation as Z, cooperativeAbortAt as _, WatchdogSpec as a, failSpan as at, RequestOutcome as b, HealthServer as c, PhaseContext as d, Poll as et, PhaseWork as f, TransportImpl as g, Stage as h, Watchdog as i, asWindow as it, CheckFn as j, ProbeKind as k, Lifecycle as l, STAGES as m, ServiceBuilder as n, Timing as nt, watchdog as o, recoverSpan as ot, RunOptions as p, ServiceDescription as q, service as r, asDebounce as rt, DependencyHandle as s, ControllerBuilder as t, Span as tt, LifecycleState as u, stageRank as v, nodeProcess as w, EXIT_SIGNALS as x, RequestFn as y, realClock as z };
-//# sourceMappingURL=builder-BFxOuULH.d.ts.map
+export { Timing as $, StartOptions as A, Dependency as B, ProcessPort as C, HealthVerdict as D, Health as E, MachineName as F, Step as G, Gate as H, Recorder as I, Operation as J, Transport as K, Check as L, Outcome as M, Result as N, ProbeAnswer as O, LifecycleEvent as P, Span as Q, Controller as R, ExitSignal as S, CheckVerdict as T, Phase as U, FORMAT as V, ServiceDescription as W, FailsBy as X, mayReissue as Y, Poll as Z, cooperativeAbortAt as _, WatchdogSpec as a, RequestOutcome as b, HealthServer as c, PhaseContext as d, asDebounce as et, PhaseWork as f, TransportImpl as g, Stage as h, Watchdog as i, recoverSpan as it, CheckFn as j, ProbeKind as k, Lifecycle as l, STAGES as m, ServiceBuilder as n, failSpan as nt, watchdog as o, RunOptions as p, Idempotency as q, service as r, heartbeatDetection as rt, DependencyHandle as s, ControllerBuilder as t, asWindow as tt, LifecycleState as u, stageRank as v, nodeProcess as w, EXIT_SIGNALS as x, RequestFn as y, Coupling as z };
+//# sourceMappingURL=builder-DnfUDW9u.d.ts.map

package/build/clock-D-38uH_z.d.ts

@@ -0,0 +1,37 @@
+//#region src/clock.d.ts
+/**
+ * This function stops a timer that `Clock.after` started. A second use does nothing. A clock of
+ * the platform also gives `unref`: after it, the timer does not keep a Node process alive.
+ */
+type Cancel = (() => void) & {
+  readonly unref?: (() => void) | undefined;
+};
+/**
+ * A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The
+ * runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of
+ * the runtime is then exact and repeatable.
+ */
+interface Clock {
+  /** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */
+  now(): number;
+  /** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */
+  after(ms: number, run: () => void): Cancel;
+}
+/** These options make a clock of the platform. */
+interface PlatformClockOptions {
+  /** True makes each timer not keep a Node process alive. The default is false, as with `setTimeout`. */
+  readonly unref?: boolean | undefined;
+}
+/**
+ * This function makes a clock of the platform: `performance.now()` and `setTimeout`. Each cancel
+ * that it gives also has `unref`.
+ */
+declare const platformClock: (options?: PlatformClockOptions) => Clock;
+/**
+ * This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
+ * process alive, thus a timer that is not stopped cannot stop the exit of the process.
+ */
+declare const realClock: Clock;
+//#endregion
+export { realClock as a, platformClock as i, Clock as n, PlatformClockOptions as r, Cancel as t };
+//# sourceMappingURL=clock-D-38uH_z.d.ts.map

package/build/clock.d.ts

@@ -0,0 +1,2 @@
+import { a as realClock, i as platformClock, n as Clock, r as PlatformClockOptions, t as Cancel } from "./clock-D-38uH_z.js";
+export { Cancel, Clock, PlatformClockOptions, platformClock, realClock };

package/build/clock.js

@@ -0,0 +1,30 @@
+//#region src/clock.ts
+/** This function gives the monotonic time: `performance.now()`, or `Date.now()` on a platform without `performance`. */
+const monotonic = () => {
+	const performance = globalThis.performance;
+	return performance === void 0 ? Date.now() : performance.now();
+};
+/**
+* This function makes a clock of the platform: `performance.now()` and `setTimeout`. Each cancel
+* that it gives also has `unref`.
+*/
+const platformClock = (options = {}) => ({
+	now: monotonic,
+	after(ms, run) {
+		const timer = setTimeout(run, Math.max(0, ms));
+		const unref = () => {
+			timer.unref?.();
+		};
+		if (options.unref === true) unref();
+		return Object.assign(() => clearTimeout(timer), { unref });
+	}
+});
+/**
+* This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
+* process alive, thus a timer that is not stopped cannot stop the exit of the process.
+*/
+const realClock = /* @__PURE__ */ platformClock({ unref: true });
+//#endregion
+export { platformClock, realClock };
+
+//# sourceMappingURL=clock.js.map

package/build/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","names":[],"sources":["../src/clock.ts"],"sourcesContent":["// @mark1russell7/service/clock: the clock of the runtime, with no other part of the package. It\n// imports no `node:` module and no zod. Thus a client in a browser can use it.\n\n/**\n * This function stops a timer that `Clock.after` started. A second use does nothing. A clock of\n * the platform also gives `unref`: after it, the timer does not keep a Node process alive.\n */\nexport type Cancel = (() => void) & { readonly unref?: (() => void) | undefined };\n\n/**\n * A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The\n * runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of\n * the runtime is then exact and repeatable.\n */\nexport interface Clock {\n  /** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */\n  now(): number;\n  /** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */\n  after(ms: number, run: () => void): Cancel;\n}\n\n/** These options make a clock of the platform. */\nexport interface PlatformClockOptions {\n  /** True makes each timer not keep a Node process alive. The default is false, as with `setTimeout`. */\n  readonly unref?: boolean | undefined;\n}\n\n/** This function gives the monotonic time: `performance.now()`, or `Date.now()` on a platform without `performance`. */\nconst monotonic = (): number => {\n  const performance = (globalThis as { performance?: { now(): number } }).performance;\n  return performance === undefined ? Date.now() : performance.now();\n};\n\n/**\n * This function makes a clock of the platform: `performance.now()` and `setTimeout`. Each cancel\n * that it gives also has `unref`.\n */\nexport const platformClock = (options: PlatformClockOptions = {}): Clock => ({\n  now: monotonic,\n  after(ms, run) {\n    const timer = setTimeout(run, Math.max(0, ms));\n    const unref = (): void => {\n      (timer as { unref?: () => void }).unref?.();\n    };\n    if (options.unref === true) unref();\n    return Object.assign(() => clearTimeout(timer), { unref });\n  },\n});\n\n/**\n * This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node\n * process alive, thus a timer that is not stopped cannot stop the exit of the process.\n */\nexport const realClock: Clock = /* @__PURE__ */ platformClock({ unref: true });\n"],"mappings":";;AA4BA,MAAM,kBAA0B;CAC9B,MAAM,cAAe,WAAmD;CACxE,OAAO,gBAAgB,KAAA,IAAY,KAAK,IAAI,IAAI,YAAY,IAAI;AAClE;;;;;AAMA,MAAa,iBAAiB,UAAgC,CAAC,OAAc;CAC3E,KAAK;CACL,MAAM,IAAI,KAAK;EACb,MAAM,QAAQ,WAAW,KAAK,KAAK,IAAI,GAAG,EAAE,CAAC;EAC7C,MAAM,cAAoB;GACxB,MAAkC,QAAQ;EAC5C;EACA,IAAI,QAAQ,UAAU,MAAM,MAAM;EAClC,OAAO,OAAO,aAAa,aAAa,KAAK,GAAG,EAAE,MAAM,CAAC;CAC3D;AACF;;;;;AAMA,MAAa,YAAmC,8BAAc,EAAE,OAAO,KAAK,CAAC"}

package/build/heartbeat.d.ts

@@ -0,0 +1,70 @@
+import { n as Clock } from "./clock-D-38uH_z.js";
+//#region src/heartbeat.d.ts
+/** These options make a heartbeat. Each time is in milliseconds on the clock. */
+export interface HeartbeatOptions {
+  /**
+   * This time is the interval of the ticks, from the start of one tick to the start of the next.
+   * A time that is not finite starts no tick.
+   */
+  readonly interval: number;
+  /** This time bounds each ping. A time that is not finite gives a ping without a timeout. */
+  readonly timeout: number;
+  /** This count is the number of misses in sequence that make the peer dead. It is a whole number above zero. */
+  readonly misses: number;
+  /**
+   * This function sends one ping. The signal aborts at the timeout of the ping and at `stop()`.
+   * - A promise gives the answer: true when the peer answered, and false when it did not.
+   * - No value tells that the answer comes later through `answer()`, for example as a pong message.
+   * - A throw or a rejection is a miss.
+   */
+  readonly ping: (signal: AbortSignal) => Promise<boolean> | void;
+  /** This function receives the death of the peer: the last of `misses` misses in sequence. The count of misses is then zero again. */
+  readonly onDead: () => void;
+  /** This function receives each miss, with the count of misses in sequence. */
+  readonly onMiss?: ((misses: number) => void) | undefined;
+  /**
+   * This function operates at each tick, before the ping. The tick sends a ping only when it gives
+   * true. A client can also act at the tick, for example to connect again. Without it, each tick sends a ping.
+   */
+  readonly due?: (() => boolean) | undefined;
+  /** This function tells if a miss counts. A miss does not count while it gives false. Without it, each miss counts. */
+  readonly live?: (() => boolean) | undefined;
+  /** True lets a tick send a ping while an earlier ping waits for its answer. The default is false: one ping at a time. */
+  readonly overlap?: boolean | undefined;
+  /**
+   * This function waits one turn of the event loop. The heartbeat waits it before it counts an
+   * answer or a miss, thus it reads a reply that is in the socket first. Without it, the heartbeat counts at once.
+   */
+  readonly turn?: (() => Promise<void>) | undefined;
+  /** This clock gives the ticks and the timeouts. The default is `realClock`. */
+  readonly clock?: Clock | undefined;
+}
+/** A heartbeat is a loop of pings that runs until `stop()`. */
+export interface Heartbeat {
+  /** This method tells the heartbeat that the peer answered. Each ping that waits gets its answer, and the count of misses is zero. */
+  answer(): void;
+  /** This method stops the ticks and the timeouts, and it aborts each ping that waits. A second use does nothing. */
+  stop(): void;
+  /** This count is the number of misses in the current sequence. */
+  readonly misses: number;
+  /** This count is the number of pings that wait for their answer. */
+  readonly waiting: number;
+  readonly stopped: boolean;
+}
+/**
+ * This function starts a heartbeat. The first tick comes one interval after the start. Each tick
+ * starts the next one first, thus the ticks keep their interval while a ping waits. A ping that has
+ * no answer at its timeout is a miss. The last miss of `misses` in sequence starts `onDead`.
+ */
+export declare const heartbeat: (options: HeartbeatOptions) => Heartbeat;
+/**
+ * This function gives the most time that a heartbeat takes to find a silent peer, in milliseconds.
+ * The first ping without an answer starts one interval after the silence at the latest. The last
+ * of `misses` pings then fails at its timeout: `misses` intervals plus a timeout. An interval that
+ * is not finite gives infinity.
+ *
+ * The time holds when each tick sends a ping: with `overlap`, or with a timeout below the interval.
+ */
+export declare const detectionTime: (interval: number, timeout: number, misses: number) => number;
+//#endregion
+//# sourceMappingURL=heartbeat.d.ts.map

package/build/heartbeat.js

@@ -0,0 +1,103 @@
+import { realClock } from "./clock.js";
+//#region src/heartbeat.ts
+/**
+* This function starts a heartbeat. The first tick comes one interval after the start. Each tick
+* starts the next one first, thus the ticks keep their interval while a ping waits. A ping that has
+* no answer at its timeout is a miss. The last miss of `misses` in sequence starts `onDead`.
+*/
+const heartbeat = (options) => {
+	const { interval, timeout, misses: limit, clock = realClock } = options;
+	if (!Number.isInteger(limit) || limit < 1) throw new RangeError(`a heartbeat needs a count of misses that is a whole number above zero, not ${limit}`);
+	let misses = 0;
+	let stopped = false;
+	let next = null;
+	const pings = /* @__PURE__ */ new Set();
+	const count = (answered) => {
+		if (stopped) return;
+		if (answered) {
+			misses = 0;
+			return;
+		}
+		if (options.live !== void 0 && !options.live()) return;
+		misses += 1;
+		options.onMiss?.(misses);
+		if (misses >= limit) {
+			misses = 0;
+			options.onDead();
+		}
+	};
+	const send = () => {
+		const controller = new AbortController();
+		const entry = {
+			controller,
+			timer: null,
+			settle: (answered) => {
+				if (!pings.delete(entry)) return;
+				entry.timer?.();
+				const done = () => count(answered);
+				if (options.turn === void 0) done();
+				else options.turn().then(done, done);
+			}
+		};
+		pings.add(entry);
+		if (Number.isFinite(timeout)) entry.timer = clock.after(timeout, () => {
+			entry.settle(false);
+			controller.abort();
+		});
+		let result;
+		try {
+			result = options.ping(controller.signal);
+		} catch {
+			entry.settle(false);
+			return;
+		}
+		if (result !== void 0) result.then((answered) => entry.settle(answered === true), () => entry.settle(false));
+	};
+	const tick = () => {
+		next = clock.after(interval, tick);
+		if (options.due !== void 0 && !options.due()) return;
+		if (stopped || options.overlap !== true && pings.size > 0) return;
+		send();
+	};
+	if (Number.isFinite(interval)) next = clock.after(interval, tick);
+	return {
+		answer() {
+			if (stopped) return;
+			misses = 0;
+			for (const entry of [...pings]) entry.settle(true);
+		},
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			next?.();
+			next = null;
+			for (const entry of [...pings]) {
+				pings.delete(entry);
+				entry.timer?.();
+				entry.controller.abort();
+			}
+		},
+		get misses() {
+			return misses;
+		},
+		get waiting() {
+			return pings.size;
+		},
+		get stopped() {
+			return stopped;
+		}
+	};
+};
+/**
+* This function gives the most time that a heartbeat takes to find a silent peer, in milliseconds.
+* The first ping without an answer starts one interval after the silence at the latest. The last
+* of `misses` pings then fails at its timeout: `misses` intervals plus a timeout. An interval that
+* is not finite gives infinity.
+*
+* The time holds when each tick sends a ping: with `overlap`, or with a timeout below the interval.
+*/
+const detectionTime = (interval, timeout, misses) => Number.isFinite(interval) ? misses * interval + timeout : Number.POSITIVE_INFINITY;
+//#endregion
+export { detectionTime, heartbeat };
+
+//# sourceMappingURL=heartbeat.js.map

package/build/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","names":[],"sources":["../src/heartbeat.ts"],"sourcesContent":["// @mark1russell7/service/heartbeat: a heartbeat on a clock, with no other part of the package. A\n// ping starts each interval, each ping has a timeout, and a count of misses in sequence finds a\n// dead peer. The entry imports no `node:` module and no zod. Thus a client in a browser can use it.\n\nimport type { Cancel, Clock } from \"./clock.ts\";\nimport { realClock } from \"./clock.ts\";\n\n/** These options make a heartbeat. Each time is in milliseconds on the clock. */\nexport interface HeartbeatOptions {\n  /**\n   * This time is the interval of the ticks, from the start of one tick to the start of the next.\n   * A time that is not finite starts no tick.\n   */\n  readonly interval: number;\n  /** This time bounds each ping. A time that is not finite gives a ping without a timeout. */\n  readonly timeout: number;\n  /** This count is the number of misses in sequence that make the peer dead. It is a whole number above zero. */\n  readonly misses: number;\n  /**\n   * This function sends one ping. The signal aborts at the timeout of the ping and at `stop()`.\n   * - A promise gives the answer: true when the peer answered, and false when it did not.\n   * - No value tells that the answer comes later through `answer()`, for example as a pong message.\n   * - A throw or a rejection is a miss.\n   */\n  readonly ping: (signal: AbortSignal) => Promise<boolean> | void;\n  /** This function receives the death of the peer: the last of `misses` misses in sequence. The count of misses is then zero again. */\n  readonly onDead: () => void;\n  /** This function receives each miss, with the count of misses in sequence. */\n  readonly onMiss?: ((misses: number) => void) | undefined;\n  /**\n   * This function operates at each tick, before the ping. The tick sends a ping only when it gives\n   * true. A client can also act at the tick, for example to connect again. Without it, each tick sends a ping.\n   */\n  readonly due?: (() => boolean) | undefined;\n  /** This function tells if a miss counts. A miss does not count while it gives false. Without it, each miss counts. */\n  readonly live?: (() => boolean) | undefined;\n  /** True lets a tick send a ping while an earlier ping waits for its answer. The default is false: one ping at a time. */\n  readonly overlap?: boolean | undefined;\n  /**\n   * This function waits one turn of the event loop. The heartbeat waits it before it counts an\n   * answer or a miss, thus it reads a reply that is in the socket first. Without it, the heartbeat counts at once.\n   */\n  readonly turn?: (() => Promise<void>) | undefined;\n  /** This clock gives the ticks and the timeouts. The default is `realClock`. */\n  readonly clock?: Clock | undefined;\n}\n\n/** A heartbeat is a loop of pings that runs until `stop()`. */\nexport interface Heartbeat {\n  /** This method tells the heartbeat that the peer answered. Each ping that waits gets its answer, and the count of misses is zero. */\n  answer(): void;\n  /** This method stops the ticks and the timeouts, and it aborts each ping that waits. A second use does nothing. */\n  stop(): void;\n  /** This count is the number of misses in the current sequence. */\n  readonly misses: number;\n  /** This count is the number of pings that wait for their answer. */\n  readonly waiting: number;\n  readonly stopped: boolean;\n}\n\ninterface Waiting {\n  readonly settle: (answered: boolean) => void;\n  readonly controller: AbortController;\n  timer: Cancel | null;\n}\n\n/**\n * This function starts a heartbeat. The first tick comes one interval after the start. Each tick\n * starts the next one first, thus the ticks keep their interval while a ping waits. A ping that has\n * no answer at its timeout is a miss. The last miss of `misses` in sequence starts `onDead`.\n */\nexport const heartbeat = (options: HeartbeatOptions): Heartbeat => {\n  const { interval, timeout, misses: limit, clock = realClock } = options;\n  if (!Number.isInteger(limit) || limit < 1)\n    throw new RangeError(`a heartbeat needs a count of misses that is a whole number above zero, not ${limit}`);\n  let misses = 0;\n  let stopped = false;\n  let next: Cancel | null = null;\n  const pings = new Set<Waiting>();\n\n  const count = (answered: boolean): void => {\n    if (stopped) return;\n    if (answered) {\n      misses = 0;\n      return;\n    }\n    if (options.live !== undefined && !options.live()) return;\n    misses += 1;\n    options.onMiss?.(misses);\n    if (misses >= limit) {\n      misses = 0;\n      options.onDead();\n    }\n  };\n\n  const send = (): void => {\n    const controller = new AbortController();\n    const entry: Waiting = {\n      controller,\n      timer: null,\n      settle: (answered) => {\n        if (!pings.delete(entry)) return;\n        entry.timer?.();\n        const done = (): void => count(answered);\n        if (options.turn === undefined) done();\n        else void options.turn().then(done, done);\n      },\n    };\n    pings.add(entry);\n    if (Number.isFinite(timeout))\n      entry.timer = clock.after(timeout, () => {\n        entry.settle(false);\n        controller.abort();\n      });\n    let result: Promise<boolean> | void;\n    try {\n      result = options.ping(controller.signal);\n    } catch {\n      entry.settle(false);\n      return;\n    }\n    if (result !== undefined)\n      result.then(\n        (answered) => entry.settle(answered === true),\n        () => entry.settle(false),\n      );\n  };\n\n  const tick = (): void => {\n    next = clock.after(interval, tick);\n    if (options.due !== undefined && !options.due()) return;\n    if (stopped || (options.overlap !== true && pings.size > 0)) return;\n    send();\n  };\n  if (Number.isFinite(interval)) next = clock.after(interval, tick);\n\n  return {\n    answer() {\n      if (stopped) return;\n      misses = 0;\n      for (const entry of [...pings]) entry.settle(true);\n    },\n    stop() {\n      if (stopped) return;\n      stopped = true;\n      next?.();\n      next = null;\n      for (const entry of [...pings]) {\n        pings.delete(entry);\n        entry.timer?.();\n        entry.controller.abort();\n      }\n    },\n    get misses() {\n      return misses;\n    },\n    get waiting() {\n      return pings.size;\n    },\n    get stopped() {\n      return stopped;\n    },\n  };\n};\n\n/**\n * This function gives the most time that a heartbeat takes to find a silent peer, in milliseconds.\n * The first ping without an answer starts one interval after the silence at the latest. The last\n * of `misses` pings then fails at its timeout: `misses` intervals plus a timeout. An interval that\n * is not finite gives infinity.\n *\n * The time holds when each tick sends a ping: with `overlap`, or with a timeout below the interval.\n */\nexport const detectionTime = (interval: number, timeout: number, misses: number): number =>\n  Number.isFinite(interval) ? misses * interval + timeout : Number.POSITIVE_INFINITY;\n"],"mappings":";;;;;;;AAuEA,MAAa,aAAa,YAAyC;CACjE,MAAM,EAAE,UAAU,SAAS,QAAQ,OAAO,QAAQ,cAAc;CAChE,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,GACtC,MAAM,IAAI,WAAW,8EAA8E,OAAO;CAC5G,IAAI,SAAS;CACb,IAAI,UAAU;CACd,IAAI,OAAsB;CAC1B,MAAM,wBAAQ,IAAI,IAAa;CAE/B,MAAM,SAAS,aAA4B;EACzC,IAAI,SAAS;EACb,IAAI,UAAU;GACZ,SAAS;GACT;EACF;EACA,IAAI,QAAQ,SAAS,KAAA,KAAa,CAAC,QAAQ,KAAK,GAAG;EACnD,UAAU;EACV,QAAQ,SAAS,MAAM;EACvB,IAAI,UAAU,OAAO;GACnB,SAAS;GACT,QAAQ,OAAO;EACjB;CACF;CAEA,MAAM,aAAmB;EACvB,MAAM,aAAa,IAAI,gBAAgB;EACvC,MAAM,QAAiB;GACrB;GACA,OAAO;GACP,SAAS,aAAa;IACpB,IAAI,CAAC,MAAM,OAAO,KAAK,GAAG;IAC1B,MAAM,QAAQ;IACd,MAAM,aAAmB,MAAM,QAAQ;IACvC,IAAI,QAAQ,SAAS,KAAA,GAAW,KAAK;SAChC,QAAa,KAAK,CAAC,CAAC,KAAK,MAAM,IAAI;GAC1C;EACF;EACA,MAAM,IAAI,KAAK;EACf,IAAI,OAAO,SAAS,OAAO,GACzB,MAAM,QAAQ,MAAM,MAAM,eAAe;GACvC,MAAM,OAAO,KAAK;GAClB,WAAW,MAAM;EACnB,CAAC;EACH,IAAI;EACJ,IAAI;GACF,SAAS,QAAQ,KAAK,WAAW,MAAM;EACzC,QAAQ;GACN,MAAM,OAAO,KAAK;GAClB;EACF;EACA,IAAI,WAAW,KAAA,GACb,OAAO,MACJ,aAAa,MAAM,OAAO,aAAa,IAAI,SACtC,MAAM,OAAO,KAAK,CAC1B;CACJ;CAEA,MAAM,aAAmB;EACvB,OAAO,MAAM,MAAM,UAAU,IAAI;EACjC,IAAI,QAAQ,QAAQ,KAAA,KAAa,CAAC,QAAQ,IAAI,GAAG;EACjD,IAAI,WAAY,QAAQ,YAAY,QAAQ,MAAM,OAAO,GAAI;EAC7D,KAAK;CACP;CACA,IAAI,OAAO,SAAS,QAAQ,GAAG,OAAO,MAAM,MAAM,UAAU,IAAI;CAEhE,OAAO;EACL,SAAS;GACP,IAAI,SAAS;GACb,SAAS;GACT,KAAK,MAAM,SAAS,CAAC,GAAG,KAAK,GAAG,MAAM,OAAO,IAAI;EACnD;EACA,OAAO;GACL,IAAI,SAAS;GACb,UAAU;GACV,OAAO;GACP,OAAO;GACP,KAAK,MAAM,SAAS,CAAC,GAAG,KAAK,GAAG;IAC9B,MAAM,OAAO,KAAK;IAClB,MAAM,QAAQ;IACd,MAAM,WAAW,MAAM;GACzB;EACF;EACA,IAAI,SAAS;GACX,OAAO;EACT;EACA,IAAI,UAAU;GACZ,OAAO,MAAM;EACf;EACA,IAAI,UAAU;GACZ,OAAO;EACT;CACF;AACF;;;;;;;;;AAUA,MAAa,iBAAiB,UAAkB,SAAiB,WAC/D,OAAO,SAAS,QAAQ,IAAI,SAAS,WAAW,UAAU,OAAO"}

package/build/index.d.ts

@@ -1,5 +1,9 @@
-import { $ as FailsBy, A as StartOptions, B as Check, C as ProcessPort, D as HealthVerdict, E as Health, F as MachineName, G as Gate, H as Coupling, I as Recorder, J as Step, K as Phase, L as Cancel, M as Outcome, N as Result, O as ProbeAnswer, P as LifecycleEvent, Q as mayReissue, R as Clock, S as ExitSignal, T as CheckVerdict, U as Dependency, V as Controller, W as FORMAT, X as Idempotency, Y as Transport, Z as Operation, _ as cooperativeAbortAt, a as WatchdogSpec, at as failSpan, b as RequestOutcome, c as HealthServer, d as PhaseContext, et as Poll, f as PhaseWork, g as TransportImpl, h as Stage, i as Watchdog, it as asWindow, j as CheckFn, k as ProbeKind, l as Lifecycle, m as STAGES, n as ServiceBuilder, nt as Timing, o as watchdog, ot as recoverSpan, p as RunOptions, q as ServiceDescription, r as service, rt as asDebounce, s as DependencyHandle, t as ControllerBuilder, tt as Span, u as LifecycleState, v as stageRank, w as nodeProcess, x as EXIT_SIGNALS, y as RequestFn, z as realClock } from "./builder-BFxOuULH.js";
+import { a as backoffDelay, i as backoffBand, n as DelayBand, o as backoffProblems, r as Jitter, t as Backoff } from "./backoff-B-jGWVDm.js";
+import { a as realClock, i as platformClock, n as Clock, r as PlatformClockOptions, t as Cancel } from "./clock-D-38uH_z.js";
+import { Heartbeat, HeartbeatOptions, detectionTime, heartbeat } from "./heartbeat.js";
+import { $ as Timing, A as StartOptions, B as Dependency, C as ProcessPort, D as HealthVerdict, E as Health, F as MachineName, G as Step, H as Gate, I as Recorder, J as Operation, K as Transport, L as Check, M as Outcome, N as Result, O as ProbeAnswer, P as LifecycleEvent, Q as Span, R as Controller, S as ExitSignal, T as CheckVerdict, U as Phase, V as FORMAT, W as ServiceDescription, X as FailsBy, Y as mayReissue, Z as Poll, _ as cooperativeAbortAt, a as WatchdogSpec, b as RequestOutcome, c as HealthServer, d as PhaseContext, et as asDebounce, f as PhaseWork, g as TransportImpl, h as Stage, i as Watchdog, it as recoverSpan, j as CheckFn, k as ProbeKind, l as Lifecycle, m as STAGES, n as ServiceBuilder, nt as failSpan, o as watchdog, p as RunOptions, q as Idempotency, r as service, rt as heartbeatDetection, s as DependencyHandle, t as ControllerBuilder, tt as asWindow, u as LifecycleState, v as stageRank, w as nodeProcess, x as EXIT_SIGNALS, y as RequestFn, z as Coupling } from "./builder-DnfUDW9u.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
+import { replay } from "@mark1russell7/algebra/replay";
 import { Machine } from "@mark1russell7/algebra";
 //#region src/law.d.ts
 /**
@@ -156,13 +160,6 @@ export declare const capKnob: (phase: string) => string;
 export declare const drainMachine: (description: ServiceDescription) => Machine;
 /** These are the static machines of the runtime, by the name that their events carry. */
 export declare const MACHINES: Readonly<Record<Exclude<MachineName, "drain" | "client">, Machine>>;
-/**
- * This function replays the transitions of one machine of the runtime against its document. Each
- * instance starts in the state that its first transition leaves. Each transition must leave the
- * state where the replay is. The document must have a transition from that state, on that event,
- * to that state. The function gives each disagreement.
- */
-export declare const replay: (doc: Machine, events: readonly LifecycleEvent[]) => string[];
 //#endregion
-export { type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type Coupling, type Dependency, type DependencyHandle, EXIT_SIGNALS, type Evaluated, type ExitSignal, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Idempotency, type Inequality, type Lifecycle, type LifecycleEvent, type LifecycleState, type MachineName, type Operation, type Outcome, type Phase, type PhaseContext, type PhaseWork, type Poll, type ProbeAnswer, type ProbeKind, type ProcessPort, type Recorder, type RequestFn, type RequestOutcome, type Result, type Rule, type RunOptions, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type Side, type Span, type Stage, type StartOptions, type Step, type Term, type Timing, type Transport, type TransportImpl, type Verdict, type Watchdog, type WatchdogSpec, asDebounce, asWindow, cooperativeAbortAt, failSpan, mayReissue, nodeProcess, realClock, recoverSpan, service, stageRank, watchdog };
+export { type Backoff, type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type Coupling, type DelayBand, type Dependency, type DependencyHandle, EXIT_SIGNALS, type Evaluated, type ExitSignal, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type Idempotency, type Inequality, type Jitter, type Lifecycle, type LifecycleEvent, type LifecycleState, type MachineName, type Operation, type Outcome, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type Poll, type ProbeAnswer, type ProbeKind, type ProcessPort, type Recorder, type RequestFn, type RequestOutcome, type Result, type Rule, type RunOptions, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type Side, type Span, type Stage, type StartOptions, type Step, type Term, type Timing, type Transport, type TransportImpl, type Verdict, type Watchdog, type WatchdogSpec, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, detectionTime, failSpan, heartbeat, heartbeatDetection, mayReissue, nodeProcess, platformClock, realClock, recoverSpan, replay, service, stageRank, watchdog };
 //# sourceMappingURL=index.d.ts.map