@mark1russell7/service 0.5.11 → 0.5.13

package/README.md

@@ -15,6 +15,9 @@ This release has the declaration, its export, the law, the health runtime, the l
 - **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 scopes of a rule.** A rule about a client applies one time for each dependency. A rule about a consumer, for example O20, applies one time for each consumer and each worker.
+- **The loops of a progress check.** A check of the step `progress` can name the loops that mark it, with its stall time: `marks: { loops, stall }`. Each loop is a check or a worker of the service.
+- **The stall time.** `lint()` compares the stall time with the longest gap between two marks of the slowest loop (`PROGRESS_RULE`). A loop marks at the end of each turn, also a turn that fails. The gap of a check is `interval × (1 + jitter) + timeout`. The gap of a worker is its sleep or its longest backoff, the longer one, plus `unit_processing_time`. At 300 s ± 20 % and a timeout of 10 s, a poll gives 370 s.
+- **A name that is not a loop.** A name that is not a check or a worker gets a `depends` finding. Without `marks`, a check gets no finding of this rule.
 - **Keyed limiters.** `svc.limiter(name, spec)` declares a rate limit for each key, as data. `keyedLimiter` makes its runtime on a store ([The keyed limiter](#the-keyed-limiter)).
 - **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.
 
@@ -510,13 +513,117 @@ const life = await app.run(); // the process exits after SIGTERM, with 0 or 1
 - **Redis Cluster.** The names of the keys put the limiter in braces, a hash tag. Thus the state and the index of a limiter are in one slot. The prefix has no braces.
 - **The test clock.** With `{ clock }`, the script uses the time of that clock in place of `TIME`. The tests use it to compare each decision of Redis with `decide`.
 
+## The PostgreSQL client
+
+`@mark1russell7/service/pg` is the PostgreSQL client of the service, over a pool of node-postgres 8. This entry is a prototype of S6. pg is an optional peer dependency. The client loads it only when it connects.
+
+- **The declaration.** `pgClient(name, spec)` declares `connect_bound`, `request_timeout`, `statement_timeout`, `pool_idle_expiry`, `keepalive_idle`, `max_connection_age`, `close_bound` and `retrans_giveup_time`. Each knob is necessary, and a bound that nobody gives is "infinite". `specProblems` refuses a knob that pg cannot use, for example a zero, which pg reads as no timer.
+- **The starting knobs.** `PG_STARTING_KNOBS` and `PG_STARTING_POLL` are a declaration from the cells of S1. Each value has its measured reason in its doc comment.
+- **Three outcomes.** `query(operation, text, values)` gives `ok`, `error` or `indeterminate`. An ERROR of the server is certain. A FATAL, a reset or a query timeout is not certain. The client then gives the connection back with an error, thus the pool ends the orphaned query.
+- **Idempotency for each operation.** SQL text does not tell if a statement changes a state. Thus the client sends again only an idempotent operation that its table names, one time at most, in the bound of the request.
+- **The join.** At each connect, the client records the process id of the backend and the socket (`joins`).
+- **No unheard error.** The client listens to the errors of the pool and of each client that it holds. In Node, an error with no listener ends the process.
+- **The checks.** `checks({ poll, steps })` gives `local-state`, `checkout`, `round-trip` (a `SELECT 1` through the pool) and `dial` (an SSLRequest on a new connection).
+- **The close.** At the shutdown, the client ends the pool, and it destroys each socket that stays at its `close_bound`.
+- **The manifestations and the machine.** `meets` lists the manifestations and their detectors. `PG_CLIENT_MACHINE` is the client as a `mark1russell7.machine/1` document, and the tests replay the client against it.
+
+## The MongoDB client
+
+`@mark1russell7/service/mongodb` is the MongoDB client of the service, over a `MongoClient` of the driver 7. This entry is a part of S6. mongodb is an optional peer dependency. The client loads it only when it connects.
+
+- **The declaration.** `mongoClient(name, spec)` declares `connect_bound`, `request_timeout`, `statement_timeout`, `heartbeat_interval`, `client_retry_window`, `checkout_timeout`, `pool_idle_expiry`, `keepalive_idle`, `max_connection_age`, `close_bound` and `retrans_giveup_time`. The client derives `driver_writeoff_time` from the connect bound and the heartbeat.
+- **The problems of a spec.** `specProblems` refuses a knob that the driver cannot use. Examples are a zero, which the driver reads as no timer, a heartbeat below 500 ms, and a finite connection age.
+- **The starting knobs.** `MONGO_STARTING_KNOBS` and `MONGO_STARTING_POLL` are a declaration from the cells of S1. Each value has its measured reason in its doc comment.
+- **The settings of the driver.** The client turns off the retries of the driver, thus the core decides each second send. The client also writes `maxTimeMS` in each command, because `db.command` does not add it.
+- **Three outcomes.** `command(operation, document)` gives `ok`, `error` or `indeterminate`. A server error is certain, except an interruption and a write concern error. A failed selection or a closed pool did not send the command.
+- **Idempotency for each operation.** A command document does not tell if it changes a state. Thus the client sends again only an idempotent operation that its table names. The second send waits for a writable server in `client_retry_window`.
+- **The join.** At each new connection, the client records the connection id of the server (`joins`). The driver gives no local socket, thus the local end is null.
+- **No unheard error.** The client listens to the error event of the driver. In Node, an error with no listener ends the process.
+- **The checks.** `checks({ poll, steps })` gives `local-state` (the view of the topology), `round-trip` (a `ping` on the connection of the application) and `dial` (a hello on a new connection).
+- **The close.** At the shutdown, the client closes the driver, and it records `close.bound` at its `close_bound`. The driver gives no socket to destroy, thus its close goes on in the background.
+- **The manifestations and the machine.** `meets` lists the manifestations and their detectors. `MONGO_CLIENT_MACHINE` is the client as a `mark1russell7.machine/1` document, and the tests replay the client against it.
+
+## The RabbitMQ client
+
+`@mark1russell7/service/rabbitmq` is the RabbitMQ client of the service, over amqplib 2. This entry is a part of S6. The peer dependency amqplib is optional. The client loads it only when it connects.
+
+- **The declaration.** `rabbitClient(name, spec)` declares `connect_bound`, `request_timeout`, `heartbeat_interval`, `retry_base`, `retry_cap`, `keepalive_idle`, `max_connection_age`, `close_bound` and `retrans_giveup_time`. The client derives `heartbeat_detection_time` (3 heartbeats) and `idle_refresh_interval` (a half heartbeat).
+- **The problems of a spec.** `specProblems` refuses a knob that amqplib cannot use. Examples are a zero, which amqplib reads as no timer, a heartbeat that is not a whole number of seconds, and a finite connection age.
+- **The starting knobs.** `RABBIT_STARTING_KNOBS` and `RABBIT_STARTING_POLL` are a declaration from the cells of R3. Each value has its measured reason in its doc comment.
+- **A call.** A call is a publish on a confirm channel until its confirm, or an RPC until its reply, for example `basic.get`. The client ends each call at `request_timeout`, because amqplib has no timer for them.
+- **Three outcomes.** `publish(operation, message)` and `get(operation, queue)` give `ok`, `error` or `indeterminate`. An ack is `ok`. A reply code of the broker is certain. A nack, a timeout and the end of the channel before the confirm are not certain. A call while the client is not ready, or while a resource alarm blocks it, did not leave the client.
+- **Idempotency for each operation.** A message does not tell if its consumers remove duplicates. Thus the client sends again only an idempotent operation that its table names. The second send waits for a ready client, in the bound of the call.
+- **One generation.** The client has one connection and one confirm channel. The end of either one ends the generation. The client then connects again by itself, to the next node, after a backoff from `retry_base` to `retry_cap`. The built-in recovery of amqplib stays off.
+- **The join.** At each generation, the client records the node and the name of the connection, `local:port -> remote:port` (`joins`).
+- **The jobs of a queue drain.** `jobs(operation, queue)` gives the source and the settle of `queueDrain`. The count of deliveries comes from `x-delivery-count`. A message that arrives after its call ended goes back to its queue at once.
+- **No unheard error.** The client listens to the error events of the connection and of the channel. In Node, an error with no listener ends the process.
+- **The checks.** `checks({ poll, steps })` gives `local-state`, `round-trip` (a passive declare of `amq.direct` on the channel of the application) and `dial` (the protocol header on a new connection, with no login).
+- **The close.** At the shutdown, the client sends `connection.close`, and it destroys the socket at its `close_bound`.
+- **The manifestations and the machine.** `meets` lists the manifestations and their detectors. `RABBIT_CLIENT_MACHINE` is the client as a `mark1russell7.machine/1` document, and the tests replay the client against it.
+
+## The HTTP client
+
+`@mark1russell7/service/http-client` is the HTTP client of the service, over an `http.Agent` of Node with keep-alive. This entry is a part of S6. The entry `./http` is the server edge of a service, thus the client has its own name. `node:http` is a built-in, thus the entry has no peer dependency. The client loads `node:http` only when it connects.
+
+- **The declaration.** `httpClient(name, spec)` declares `connect_bound`, `request_timeout`, `pool_idle_expiry`, `hint_buffer`, `keepalive_idle`, `max_connection_age`, `close_bound` and `retrans_giveup_time`. Keepalive is also the `idle_refresh_interval`, because the agent sends nothing on a free socket.
+- **The idle close of the server.** The knob `server_idle_close` is not in the declaration, because the scenario binds the close of the server. `problems` compares it with `pool_idle_expiry` (O01).
+- **The problems of a spec.** `specProblems` refuses a knob that the agent cannot use. An example is a free socket timer of 0, which the agent reads as no timer. Others are a keepalive that is not a whole number of seconds, and a finite connection age.
+- **The options of the agent.** `agentOptions(spec)` gives `timeout`, `agentKeepAliveTimeoutBuffer`, `keepAliveMsecs`, `maxSockets` and `maxFreeSockets` from the declaration, and `scheduling: "lifo"`.
+- **The starting knobs.** `HTTP_CLIENT_STARTING_KNOBS` and `HTTP_CLIENT_STARTING_POLL` are a declaration from the HTTP cells. Each value has its measured reason in its doc comment.
+- **A call.** A call is one request until the end of the body of its response. The client ends each call at `request_timeout`, and each connect of a new socket at `connect_bound`, because the agent has no timer for them.
+- **Three outcomes.** `request(call)` gives `ok`, `error` or `indeterminate`. Each whole response is `ok`, with its status: RFC 9110 does not say that a 5xx did not apply. A request that did not get a connected socket did not leave the client. A failure after that is not certain.
+- **Idempotency for each method.** The table names each method by RFC 9110. GET, HEAD, OPTIONS, TRACE, PUT and DELETE are idempotent, and POST and PATCH are not. A spec can name a keyed operation, for example a POST with an `Idempotency-Key`.
+- **The keep-alive race.** A server can close a free socket while a request goes on it. The client then sends again only an idempotent operation, one time, on a new socket. It records `reuse.failed`.
+- **The join.** At each new socket, the client records the ends of the socket (`joins`). HTTP gives no id of a connection.
+- **The checks.** `checks({ poll, steps })` gives `local-state`, `round-trip` (the check request through the pool, which fails at a status of 500 or more) and `dial` (`OPTIONS *` on a new connection). The check request is `OPTIONS *`, or the `check` of the spec.
+- **The close.** At the shutdown, the client waits for its calls in flight. At its `close_bound`, it destroys each socket of the agent, and each call that stays is indeterminate.
+- **The manifestations and the machine.** `meets` lists the manifestations and their detectors. `HTTP_CLIENT_MACHINE` is the client as a `mark1russell7.machine/1` document, and the tests replay the client against it.
+
+## The WebSocket client
+
+`@mark1russell7/service/websocket` is the WebSocket client of the service, over ws 8. This entry is a part of S6. The peer dependency ws is optional. The client loads it only when it connects.
+
+- **The declaration.** `wsClient(name, spec)` declares `connect_bound`, `request_timeout`, `heartbeat_interval`, `heartbeat_timeout`, `retry_base`, `retry_cap`, `keepalive_idle`, `max_connection_age`, `close_bound` and `retrans_giveup_time`. The client derives `heartbeat_detection_time` and `idle_refresh_interval` (the heartbeat).
+- **The problems of a spec.** `specProblems` refuses a knob that ws cannot use. Examples are a zero heartbeat, a keepalive that is not a whole number of seconds, and a finite connection age. It also refuses a password: give the credentials in `headers`.
+- **The starting knobs.** `WS_CLIENT_STARTING_KNOBS`, `WS_CLIENT_STARTING_MISSES` and `WS_CLIENT_STARTING_POLL` are a declaration from the WS cells. Each value has its measured reason in its doc comment.
+- **A call.** A call is a request message until its reply, or a ping frame until its pong. WebSocket has no reply of its own, thus `replies` of the spec reads the id of a reply in a message. The client ends each call at `request_timeout`.
+- **Three outcomes.** `request(operation, { id, data })` and `ping()` give `ok`, `error` or `indeterminate`. A reply that carries an error is certain. A failed write, a timeout and the end of the generation are not certain. A call while the client is not ready did not leave the client.
+- **Messages with no reply.** `send(data)` writes a message, and it is not a call. `onMessage(listener)` gets each message that answers no request.
+- **Idempotency for each operation.** A message does not tell its idempotency. Thus the client sends again only an idempotent operation that its table names. `WS_OPERATIONS` names `ping`. The second send waits for a ready client.
+- **The heartbeat.** The client sends a ping frame at each `heartbeat_interval`, one at a time. After `heartbeatMisses` pings with no pong in `heartbeat_timeout`, `terminate()` destroys the socket.
+- **One generation.** The generation is one connection after its upgrade. At its end, the client connects again by itself, after a backoff from `retry_base` to `retry_cap`.
+- **The join.** At each generation, the client records the URL, the subprotocol and the ends of the socket (`joins`). WebSocket gives no id of a connection.
+- **The checks.** `checks({ poll, steps })` gives `local-state`, `round-trip` (a ping on the connection of the application) and `dial` (the upgrade GET on a new connection, which must get 101).
+- **The close.** At the shutdown, the client waits for its calls in flight, then it sends a close frame. At its `close_bound`, `terminate()` destroys the socket, and each call that stays is indeterminate.
+- **The manifestations and the machine.** `meets` lists the manifestations and their detectors. `WS_CLIENT_MACHINE` is the client as a `mark1russell7.machine/1` document, and the tests replay the client against it.
+
+## The gRPC client
+
+`@mark1russell7/service/grpc` is the gRPC client of the service, over grpc-js 1.14. This entry is a part of S6. The peer dependency `@grpc/grpc-js` is optional. The client loads it only when it connects.
+
+- **The declaration.** `grpcClient(name, spec)` declares `connect_bound`, `request_timeout`, `keepalive_time`, `keepalive_timeout`, `client_idle_timeout`, `retry_base`, `retry_cap`, `keepalive_idle`, `max_connection_age`, `close_bound` and `retrans_giveup_time`. The client derives `heartbeat_detection_time` (the PING) and `idle_refresh_interval`.
+- **The facts of the server.** The knobs `server_keepalive_min_time` and `server_idle_close` are not in the declaration. `problems` compares them with `keepalive_time` (O26) and `client_idle_timeout` (O01).
+- **The problems of a spec.** `specProblems` refuses a knob that grpc-js cannot use. Examples are a zero keepalive, a timer that is not a whole number of milliseconds, and an idle timeout below 1 s. A timer above the longest timer of Node is a problem too. It also refuses a TCP keepalive and a password: give the credentials in `metadata`.
+- **The options of the channel.** `grpcOptions(spec)` gives the target and each timer of grpc-js from the declaration. It also turns the retries of grpc-js off, and the service config of the resolver.
+- **The starting knobs.** `GRPC_CLIENT_STARTING_KNOBS`, `GRPC_CLIENT_STARTING_WITHOUT_CALLS` and `GRPC_CLIENT_STARTING_POLL` are a declaration from the gRPC cells. Each value has its measured reason in its doc comment.
+- **A call.** A call is one unary call until its status. `request` and the response are the bytes of the messages, thus the caller encodes them. A stream is not a call. The deadline of a call is the time that is left in `request_timeout`, and grpc-js sends it as `grpc-timeout`.
+- **Three outcomes.** `call(method, request)` gives `ok`, `error` or `indeterminate` from the status code (`grpcOutcome`). A code that tells a refusal is certain. A status that tells that the call did not leave the client is not sent. Each other status is not certain.
+- **Idempotency for each method.** `grpcOperations` makes the table from the `idempotency_level` of each method in its proto. The client sends again only an idempotent method, one time, after it is ready again. `GRPC_OPERATIONS` names the Check of the health service.
+- **One channel.** The client has one channel for its life, and each READY is one generation. The grpc-js driver connects again by itself after its backoff. The client connects an IDLE channel again at once.
+- **The join.** At each generation, the client records the target (`joins`). The grpc-js driver gives no socket, thus the ends of the socket are null.
+- **The checks.** `checks({ poll, steps })` gives `local-state`, `round-trip` (a Check of the health service on the channel of the application, which passes only for SERVING) and `dial` (the HTTP/2 preface on a new connection, which must get a SETTINGS frame).
+- **The close.** At the shutdown, the client waits for its calls in flight. At its `close_bound`, it cancels each call that stays, which is then indeterminate. Then it closes the channel.
+- **The manifestations and the machine.** `meets` lists the manifestations and their detectors. `GRPC_CLIENT_MACHINE` is the client as a `mark1russell7.machine/1` document, and the tests replay the client against it.
+
 ## Installation
 
 ```sh
 pnpm add @mark1russell7/service
 ```
 
-For the Redis client, the application also installs `ioredis@6`.
+For the Redis client, the application also installs `ioredis@6`. For the PostgreSQL client, it installs `pg@8`. For the MongoDB client, it installs `mongodb@7`. For the RabbitMQ client, it installs `amqplib@2`. For the WebSocket client, it installs `ws@8`.
+
+For the gRPC client, it installs `@grpc/grpc-js@1`. The HTTP client needs no other package.
 
 The package uses [`@mark1russell7/quantity`](https://www.npmjs.com/package/@mark1russell7/quantity) for each amount. No entry of the service loads `zod` at run time, thus `zod` is an optional peer dependency. An application that validates amounts with the schemas of `quantity` installs `zod`.
 
@@ -627,6 +734,8 @@ for await (const event of stream) {
 - **The machines.** Each document is valid, consistent and readable by the algebra. Eight scenarios replay against the documents and reach each state. The timers of the documents give the times of the runtime. The ordering law (O16) agrees with the clamp of the cooperative abort.
 - **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.
+- **The HTTP client.** These tests use a fake agent and a fake clock. They cover the declaration, the three outcomes, the methods that the client sends again or not, and the keep-alive race. They also cover the free socket timer, the close, the checks and the manifestations. Five scenarios replay against the document of the client. One test sends requests through the agent of Node to a server of the loopback.
+- **The gRPC client.** These tests use a fake channel and a fake clock. They cover the declaration, the outcome of each status code, the methods that the client sends again or not, the keepalive and the IDLE channel. They also cover a GOAWAY, the close, the checks and the manifestations. Seven scenarios replay against the document of the client. One test sends calls through grpc-js to a server of the loopback.
 - **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. No entry of the service reaches zod, also through `quantity` and the replay of the algebra. The root reaches no `node:` module. The HTTP edge reaches only `node:http`, `node:net` and `quantity`. The worker loop and the queue drain reach only `quantity`.

package/build/{builder-Dn0cby6Q.d.ts → builder-DawJhq4p.d.ts}

@@ -1,6 +1,6 @@
 import { n as Clock } from "./clock-mVqhXD0b.js";
 import { c as LimiterSpec } from "./policy-G4QJ1ZZq.js";
-import { B as Gate, Ct as Operation, D as Outcome, E as CheckFn, F as CooperativeFloor, H as Phase, I as Coupling, J as Poll, L as Dependency, N as Check, R as ExitCodes, T as StartOptions, U as RepeatSignal, V as MessageTrigger, W as ServiceDescription, X as Timing, ct as ExitTrigger, d as TransportImpl, k as Trace, mt as ProcessTrigger, n as HealthServer, nt as OperationOf, o as PhaseWork, r as Lifecycle, s as RunOptions, t as DependencyHandle, x as Health } from "./lifecycle-CGEegMI0.js";
+import { B as Gate, D as Outcome, E as CheckFn, F as CooperativeFloor, G as ServiceDescription, H as Phase, I as Coupling, L as Dependency, N as Check, R as ExitCodes, T as StartOptions, V as MessageTrigger, W as RepeatSignal, Y as Poll, Z as Timing, d as TransportImpl, ht as ProcessTrigger, k as Trace, lt as ExitTrigger, n as HealthServer, o as PhaseWork, r as Lifecycle, rt as OperationOf, s as RunOptions, t as DependencyHandle, wt as Operation, x as Health } from "./lifecycle-fgYfxrHK.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
 //#region src/profiles.d.ts
 /**
@@ -208,4 +208,4 @@ interface ServiceBuilder {
 declare const service: (name: string) => ServiceBuilder;
 //#endregion
 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 };
-//# sourceMappingURL=builder-Dn0cby6Q.d.ts.map
+//# sourceMappingURL=builder-DawJhq4p.d.ts.map

package/build/core-BPLRDcUJ.d.ts

@@ -0,0 +1,226 @@
+import { t as Backoff } from "./backoff-B-jGWVDm.js";
+import { n as Clock } from "./clock-mVqhXD0b.js";
+import { B as Gate, E as CheckFn, G as ServiceDescription, K as Step, L as Dependency, M as Recorder, N as Check, Y as Poll, t as DependencyHandle, wt as Operation } from "./lifecycle-fgYfxrHK.js";
+import { n as ServiceBuilder } from "./builder-DawJhq4p.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+//#region src/client/meets.d.ts
+/** A situation is what the connection did when the failure started: a command in flight, or idle. */
+type Situation = "in flight" | "idle";
+/** A detector is a mechanism that finds a failure, and the most time that it takes. */
+interface Detector {
+  /** This name identifies the mechanism: a knob of the declaration, or the kernel. */
+  readonly by: string;
+  /** This time is the most that the detector takes, after the failure starts. "infinite" tells that it does not find the failure. */
+  readonly within: Extent;
+  readonly situation: Situation;
+  /** This text tells what the detector does, for example that it fails a command without a change of state. */
+  readonly effect: string;
+}
+/**
+ * A meeting is a manifestation that the client can meet, and its detectors (E9). The names of the
+ * manifestations are the names of the vocabulary of the harness and the corpus. `app-stall` is a
+ * server whose process is alive and does not answer, a proposal of the vocabulary.
+ */
+interface Meeting {
+  readonly manifestation: string;
+  /** This text tells the failure in words. */
+  readonly what: string;
+  readonly detectors: readonly Detector[];
+}
+/** These are the manifestations that each client gives a meeting for, in this sequence. */
+declare const MANIFESTATIONS: readonly ["rst", "fin", "blackhole", "freeze-host", "freeze-process", "app-stall"];
+/** A manifestation is one name of `MANIFESTATIONS`. */
+type Manifestation = (typeof MANIFESTATIONS)[number];
+/** This function gives the first detector of a manifestation in a situation, or null when no detector has an end (C3). */
+declare const firstDetector: (meeting: Meeting, situation: Situation) => Detector | null;
+/** This function gives each manifestation and situation that no detector of the client finds: the standing rule, as a query (C3, E9). */
+declare const unwatched: (meets: readonly Meeting[]) => Array<{
+  readonly manifestation: string;
+  readonly situation: Situation;
+}>;
+//#endregion
+//#region src/client/core.d.ts
+/**
+ * A sent result is the outcome of a call, in three values (C8):
+ * - `ok`: the server answered.
+ * - `error`: the call did not apply. The server answered with an error (`reply`), or the call did
+ *   not leave the client.
+ * - `indeterminate`: the call can have reached the server, and nothing tells if it applied.
+ */
+type Sent<T> = {
+  readonly outcome: "ok";
+  readonly value: T;
+  readonly attempts: number;
+} | {
+  readonly outcome: "error";
+  readonly error: string;
+  readonly reply: boolean;
+  readonly attempts: number;
+} | {
+  readonly outcome: "indeterminate";
+  readonly error: string;
+  readonly attempts: number;
+};
+/** This type is the outcome of one try of a call, before the core counts the tries. */
+type Attempt<T = unknown> = {
+  readonly outcome: "ok";
+  readonly value: T;
+} | {
+  readonly outcome: "error";
+  readonly error: string;
+  readonly reply: boolean;
+} | {
+  readonly outcome: "indeterminate";
+  readonly error: string;
+};
+/** Send options tell how the client sends one call. */
+interface SendOptions {
+  /** This signal abandons the call. A call that left the client is then indeterminate. */
+  readonly signal?: AbortSignal | undefined;
+  /** False stops the client: it does not send the call again. A check that must fail at once uses it. */
+  readonly reissue?: boolean | undefined;
+}
+/** A dial function opens a new connection to the server, and reads one reply of the protocol. The `dial` check uses it. */
+type DialFn = (host: string, port: number, signal: AbortSignal) => Promise<void>;
+/** The steps of a connection that each client gives a check for (B14). A client can add more steps. */
+type ClientStep = Extract<Step, "dial" | "round-trip" | "local-state">;
+/** Check options tell which checks the client gives the health runtime, and which policy each one controls. */
+interface CheckOptions<S extends Step = ClientStep> {
+  readonly poll: Poll;
+  /** For each step, the policy that its check controls, or null for a check that only reports. A step that is absent has no check. */
+  readonly steps: Partial<Record<S, Gate | null>>;
+}
+/**
+ * These are the knobs that each client has, by the names of the ordering law. Each driver adds its
+ * own knobs. The comments of each driver tell which option of the driver a knob sets.
+ */
+interface ClientKnobs {
+  /** This time bounds a new connection. */
+  readonly connect_bound: Quantity;
+  /** This time bounds each call on the connection of the application. */
+  readonly request_timeout: Quantity;
+  /** This time is the idle time of TCP keepalive. Node then sends 10 probes 1 s apart. */
+  readonly keepalive_idle: Extent;
+  /** This time is the age at which the client replaces a connection. */
+  readonly max_connection_age: Extent;
+  /** This time bounds the close of the client at the shutdown. */
+  readonly close_bound: Quantity;
+  /**
+   * This time is when the kernel gives up a segment that it retransmits. Node cannot set it, thus
+   * the declaration states it for the ordering law (O17), from the platform.
+   */
+  readonly retrans_giveup_time: Extent;
+}
+/** A client spec is the declaration of one client: where it connects, and its knobs. Each driver adds its own fields. */
+interface ClientSpec<K extends ClientKnobs = ClientKnobs> {
+  readonly host: string;
+  readonly port: number;
+  readonly password?: string | undefined;
+  /** This identifier is the component in the corpus, for example `systems.component.redis`, or null. */
+  readonly system: string | null;
+  readonly knobs: K;
+  /** These operations add to the table of the client, or change it. */
+  readonly operations?: Readonly<Record<string, Operation>> | undefined;
+}
+/** A factory makes the connection or the pool of a client from the options of its driver. */
+type Factory<O, C> = (options: O) => C | Promise<C>;
+/** These options make a client. Without them, a client uses its driver, the real clock, and the dial of its protocol. */
+interface ClientOptions<F> {
+  readonly create?: F | undefined;
+  readonly clock?: Clock | undefined;
+  /** This function receives each transition of the client, for the prober (D3). */
+  readonly record?: Recorder | undefined;
+  readonly dial?: DialFn | undefined;
+}
+/** A client socket is the part of the socket of a connection that the join of the prober and the bounded close read. */
+interface ClientSocket {
+  readonly localAddress?: string | undefined;
+  readonly localPort?: number | undefined;
+  readonly remoteAddress?: string | undefined;
+  readonly remotePort?: number | undefined;
+  /** This method closes the socket at once. A close of the driver only half-closes it, and a silent peer does not answer that. */
+  destroy?(): void;
+}
+/**
+ * A client join is one connection, at the time when it can serve (D1, D2). The prober joins its
+ * kernel records to the server's view of the connection through it. Each driver adds the server's id of the connection.
+ */
+interface ClientJoin {
+  readonly generation: number;
+  /** This time is when the connection became ready, in milliseconds on the monotonic clock. */
+  readonly at: number;
+  readonly localAddress: string | null;
+  readonly localPort: number | null;
+  readonly remoteAddress: string | null;
+  readonly remotePort: number | null;
+}
+/** A client is a dependency of a service: its declaration, its handle and its checks. Each driver adds the method that sends a call. */
+interface Client<S extends Step = ClientStep, J extends ClientJoin = ClientJoin> {
+  readonly name: string;
+  /** This declaration goes to `svc.dependency(name, declaration, handle)`. */
+  readonly declaration: Omit<Dependency, "name">;
+  readonly handle: DependencyHandle;
+  /** These are the manifestations that the client can meet, and the detectors of each (E9). */
+  readonly meets: readonly Meeting[];
+  /** This text is the state of the client, as the machine document of the client names it. */
+  readonly status: string;
+  /** These are the connections of the client, the latest last. */
+  readonly joins: readonly J[];
+  /** This method gives the checks of the client and their functions, for `svc.check(check, run)`. */
+  checks(options: CheckOptions<S>): ReadonlyArray<readonly [Check, CheckFn]>;
+  /** This method declares the client in a service: its dependency, its handle and its checks. */
+  attach(svc: ServiceBuilder, options: CheckOptions<S>): ServiceBuilder;
+  /** This method gives the problems of the client in a description: a close that does not fit in its phase, for example. */
+  problems(description: ServiceDescription): string[];
+}
+/**
+ * A ready wait holds the calls that wait for a ready connection before their second try. A client
+ * that connects again by itself uses it: Redis and RabbitMQ.
+ */
+interface ReadyWait {
+  /** This method waits until the client is ready, for `within` milliseconds at most. It gives true when the client is ready. */
+  wait(within: number, signal?: AbortSignal): Promise<boolean>;
+  /** This method ends each wait with true. The client uses it when its connection is ready. */
+  wake(): void;
+}
+/** This function makes the ready wait of a client. The function `ready` tells if the client is ready. */
+declare const readyWait: (clock: Clock, ready: () => boolean) => ReadyWait;
+/** These are the knobs of a client that connects again by itself, after a delay that doubles. */
+interface RetryKnobs {
+  /** This time is the first delay before a new try to connect. The delay doubles after each try. */
+  readonly retry_base: Quantity;
+  /** This time is the most that one delay can be, before its jitter. */
+  readonly retry_cap: Quantity;
+}
+/**
+ * This function gives the backoff of the tries to connect: from `retry_base`, doubling to
+ * `retry_cap`, each with a jitter up to the base. The client rounds each delay to a whole millisecond.
+ */
+declare const retryBackoff: (knobs: RetryKnobs) => Backoff;
+/**
+ * A retry schedule holds the next try to connect, for a client that connects again by itself. It
+ * counts the tries since the last join. Each delay comes from the backoff, rounded to a whole millisecond.
+ */
+interface RetrySchedule {
+  /** This count is the number of tries since the last reset. */
+  readonly tries: number;
+  /** This method counts one more try, and starts `due` after the delay of that try. It stops a try that waits. */
+  schedule(due: () => void): void;
+  /** This method stops the try that waits. The close uses it. */
+  cancel(): void;
+  /** This method sets the count of tries to zero. The client uses it at each join. */
+  reset(): void;
+}
+/** This function makes the retry schedule of a client, from its backoff and its random numbers. RabbitMQ and WebSocket use it. */
+declare const retrySchedule: (clock: Clock, backoff: Backoff, random: () => number) => RetrySchedule;
+/** This function gives the problems of the retry knobs: the cap must not be below the base. */
+declare const retryProblems: (name: string, knobs: RetryKnobs) => string[];
+/**
+ * This poll is a poll of the checks to start from: each 5 s with a jitter of 20 %, and a timeout of
+ * 4 s (B6, O12). Its slowest poll is 4 s + 5 s × 1.2 = 10 s, the slowest poll of the cells of O13.
+ * It does not depend on a driver. The starting knobs of each driver fit it.
+ */
+declare const STARTING_POLL: Poll;
+//#endregion
+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 };
+//# sourceMappingURL=core-BPLRDcUJ.d.ts.map

package/build/dial-DA8vJfh2.d.ts

@@ -0,0 +1,16 @@
+import "./core-BPLRDcUJ.js";
+//#region src/client/dial.d.ts
+/**
+ * A judge reads the bytes that the server sent so far. It gives null for a good answer, an error for
+ * a bad answer, or "more" when it must wait for more bytes.
+ */
+type Judge = (received: Buffer) => Error | null | "more";
+/**
+ * This function makes a judge of the status line of an HTTP/1.1 answer. The judge waits for the end
+ * of the line, in the first 8 KiB. Then `accept` reads the status code, and gives null for a good status or an error.
+ * The HTTP client accepts each status. The WebSocket client accepts only 101.
+ */
+declare const statusLineJudge: (accept: (status: number, line: string) => Error | null) => Judge;
+//#endregion
+export { statusLineJudge as n, Judge as t };
+//# sourceMappingURL=dial-DA8vJfh2.d.ts.map