@mark1russell7/service 0.1.0 → 0.2.0

package/build/redis.d.ts

@@ -0,0 +1,294 @@
+import { B as Check, G as Gate, I as Recorder, J as Step, R as Clock, U as Dependency, Z as Operation, et as Poll, j as CheckFn, n as ServiceBuilder, q as ServiceDescription, s as DependencyHandle } from "./builder-BFxOuULH.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/redis/connection.d.ts
+/**
+ * A Redis connection is the part of an ioredis client that the wrapper uses. An ioredis 6 client has
+ * each part. A fake for tests has them too. Thus the package depends on no type of ioredis.
+ */
+interface RedisConnection {
+  /** This text is the state of the client: wait, connecting, connect, ready, close, reconnecting or end. */
+  readonly status: string;
+  /** This socket is the socket of the current connection, when there is one. */
+  readonly stream?: RedisSocket | undefined;
+  connect(): Promise<void>;
+  /** This method sends one command, and gives the reply. */
+  call(command: string, ...args: Array<string | number>): Promise<unknown>;
+  quit(): Promise<unknown>;
+  /** This method closes the connection at once. With `true`, the client then connects again. */
+  disconnect(reconnect?: boolean): void;
+  on(event: string, listener: (...args: unknown[]) => void): unknown;
+  off(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+/** A Redis socket is the part of the socket of a connection that the join of the prober reads. */
+interface RedisSocket {
+  readonly localAddress?: string | undefined;
+  readonly localPort?: number | undefined;
+  readonly remoteAddress?: string | undefined;
+  readonly remotePort?: number | undefined;
+  /** This method closes the socket at once. A disconnect only half-closes it, and a silent peer does not answer that. */
+  destroy?(): void;
+}
+/**
+ * These are the options that the wrapper gives ioredis. Each one comes from the declaration. The
+ * wrapper sets each option that has an effect on a timer or on a send again, thus no default of
+ * ioredis decides one.
+ */
+interface RedisConnectionOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly db?: number | undefined;
+  readonly username?: string | undefined;
+  readonly password?: string | undefined;
+  /** The wrapper connects in its own step of the startup. */
+  readonly lazyConnect: true;
+  readonly connectTimeout: number;
+  readonly commandTimeout: number;
+  /** This time destroys a socket that gives no data while a command waits. Undefined is no bound. */
+  readonly socketTimeout: number | undefined;
+  /** This time is the idle time of TCP keepalive. False is no keepalive. */
+  readonly keepAlive: number | false;
+  /** A command while the client is not ready fails at once: it did not reach the server. */
+  readonly enableOfflineQueue: false;
+  /** The client does not send again a command that can have reached the server. */
+  readonly autoResendUnfulfilledCommands: false;
+  readonly maxRetriesPerRequest: null;
+  readonly enableReadyCheck: true;
+  readonly connectionName: string;
+  /** This function gives the delay before the next try to connect, or null to stop. */
+  readonly retryStrategy: (times: number) => number | null;
+}
+/** A connection factory makes the connection of the client from its options. */
+type ConnectionFactory = (options: RedisConnectionOptions) => RedisConnection | Promise<RedisConnection>;
+/**
+ * This factory makes an ioredis client. It loads ioredis only when a client connects, thus a
+ * service that does not use Redis does not need ioredis.
+ */
+export declare const ioredis: ConnectionFactory;
+//#endregion
+//#region src/redis/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[];
+}
+/**
+ * This function gives the manifestations that a Redis client can meet, and the detectors of each, from
+ * its knobs. A reset or a FIN arrives on the next segment. A black hole and a host that is gone give
+ * no answer at all. A frozen process and a stalled server keep a kernel that acknowledges each
+ * segment. Thus TCP keepalive does not fire on them, and only the client's own timers find them.
+ */
+export declare const meetings: (name: string, knobs: RedisKnobs, heartbeat: Extent) => Meeting[];
+/** This function gives the first detector of a manifestation in a situation, or null when no detector has an end (C3). */
+export 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). */
+export declare const unwatched: (meets: readonly Meeting[]) => Array<{
+  readonly manifestation: string;
+  readonly situation: Situation;
+}>;
+//#endregion
+//#region src/redis/client.d.ts
+/**
+ * These are the knobs of the client, each a time, by the names of the ordering law where the law
+ * has them. The runtime has no defaults, thus each knob is necessary, and a bound that nobody gives
+ * is "infinite", not zero.
+ */
+interface RedisKnobs {
+  /** This time bounds a try to connect, until the TCP connection exists (`connectTimeout`). */
+  readonly connect_bound: Quantity;
+  /** This time bounds each command, the handshake commands too (`commandTimeout`). */
+  readonly request_timeout: Quantity;
+  /** This time destroys a socket that gives no data while a command waits (`socketTimeout`). */
+  readonly driver_writeoff_time: Extent;
+  /** 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 interval of the in-band watchdog: a PING on the connection of the application. */
+  readonly heartbeat_interval: Extent;
+  /** This time bounds each PING of the watchdog. */
+  readonly heartbeat_timeout: Quantity;
+  /** This time is how long the client tries to connect again before it stops. The watchdog then starts it again. */
+  readonly client_retry_window: Extent;
+  /** 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 time bounds the close of the client at the shutdown: a QUIT, then a disconnect. */
+  readonly close_bound: Quantity;
+  /** This time is the age at which the client replaces its connection. The client supports only "infinite". */
+  readonly max_connection_age: Extent;
+  /**
+   * 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 Redis client spec is the declaration of one Redis client: where it connects, and its knobs. */
+interface RedisClientSpec {
+  readonly host: string;
+  readonly port: number;
+  readonly db?: number | undefined;
+  readonly username?: string | undefined;
+  readonly password?: string | undefined;
+  /** This identifier is the component in the corpus (`systems.component.redis`), or null. */
+  readonly system: string | null;
+  readonly knobs: RedisKnobs;
+  /** This count is the number of PINGs in sequence without an answer that make the watchdog connect again. */
+  readonly heartbeatMisses: number;
+  /** These operations add to the table of the client, or change it. */
+  readonly operations?: Readonly<Record<string, Operation>> | undefined;
+}
+/** A dial function opens a new TCP connection, sends one PING, and reads the reply. The `dial` check uses it. */
+type DialFn = (host: string, port: number, signal: AbortSignal) => Promise<void>;
+/** These options make a client. Without them, it uses ioredis, the real clock and `Math.random`. */
+interface RedisClientOptions {
+  readonly create?: ConnectionFactory | undefined;
+  readonly clock?: Clock | undefined;
+  readonly random?: (() => number) | undefined;
+  /** This function receives each transition of the client, for the prober (D3). */
+  readonly record?: Recorder | undefined;
+  readonly dial?: DialFn | undefined;
+  /**
+   * This function waits one turn of the event loop. The watchdog waits it before it counts a miss,
+   * thus a reply that is in the socket is read first. Without it, the client uses `setImmediate`.
+   */
+  readonly turn?: (() => Promise<void>) | undefined;
+}
+/**
+ * A join is one generation of the connection, at its `ready` (D1, D2). The prober joins its kernel
+ * records to the server's view of the connection through it. A join holds the server's id of the
+ * connection, and the local address and port of the socket.
+ */
+interface Join {
+  readonly generation: number;
+  /** This time is when the connection became ready, in milliseconds on the monotonic clock. */
+  readonly at: number;
+  /** This number is the reply of CLIENT ID, or null when the server gave none. */
+  readonly clientId: number | null;
+  readonly localAddress: string | null;
+  readonly localPort: number | null;
+  readonly remoteAddress: string | null;
+  readonly remotePort: number | null;
+}
+/**
+ * A sent result is the outcome of a command, in three values (C8):
+ * - `ok`: the server answered.
+ * - `error`: the command did not apply. The server answered with an error (`reply`), or the command
+ *   did not leave the client.
+ * - `indeterminate`: the command 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;
+};
+/** Send options tell how the client sends one command. */
+interface SendOptions {
+  /** This signal abandons the command. A command that left the client is then indeterminate. */
+  readonly signal?: AbortSignal | undefined;
+  /** False stops the client: it does not send the command again. A check that must fail at once uses it. */
+  readonly reissue?: boolean | undefined;
+}
+/** The steps of a connection that the client gives a check for (B14). */
+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 {
+  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<ClientStep, Gate | null>>;
+}
+/** A Redis client is a dependency of a service: its declaration, its handle, its checks and its commands. */
+interface RedisClient {
+  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 detector of each (E9). */
+  readonly meets: readonly Meeting[];
+  /** This text is the state of the connection, as ioredis names it, or "none" before the connect. */
+  readonly status: string;
+  /** These are the generations of the connection, the latest last. */
+  readonly joins: readonly Join[];
+  /**
+   * This method sends a command, and gives its outcome in three values. The client sends again
+   * only an idempotent operation, one time at most, after an outcome that is not certain. The
+   * second try stays in the bound of the request. The client does not send again an operation that
+   * the table does not name.
+   */
+  send<T = unknown>(command: string, args?: ReadonlyArray<string | number>, options?: SendOptions): Promise<Sent<T>>;
+  /** This method gives the checks of the client and their functions, for `svc.check(check, run)`. */
+  checks(options: CheckOptions): ReadonlyArray<readonly [Check, CheckFn]>;
+  /** This method declares the client in a service: its dependency, its handle and its checks. */
+  attach(svc: ServiceBuilder, options: CheckOptions): 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[];
+}
+/**
+ * This function gives the time that the watchdog takes to find a silent server, at the most. A PING
+ * starts each interval, from the start of the one before. Each one fails at its timeout, and the
+ * last of `misses` failures in sequence closes the connection: `misses` intervals plus a timeout.
+ */
+export declare const heartbeatDetection: (interval: Extent, timeout: Quantity, misses: number) => Extent;
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+export declare const specProblems: (name: string, spec: RedisClientSpec) => string[];
+/** This dial function opens a TCP connection, sends an inline PING, and waits for +PONG. */
+export declare const tcpDial: DialFn;
+/**
+ * This function makes a Redis client. It is a dependency of a service, with ioredis under it:
+ * - It sets each timer of ioredis from the declaration, and it does not let ioredis send a command
+ *   again (R5 §8).
+ * - It tells the outcome of a command in three values, and it settles each command in flight as
+ *   indeterminate when its connection closes (C8, C10).
+ * - It records the server's id of each connection at `ready` (D1).
+ * - A watchdog sends a PING in the band of the connection, and it connects again after the misses
+ *   of the declaration. It also starts a client that stopped (principle 19).
+ */
+export declare const redisClient: (name: string, spec: RedisClientSpec, options?: RedisClientOptions) => RedisClient;
+//#endregion
+//#region src/redis/machine.d.ts
+/**
+ * The Redis client as a `mark1russell7.machine/1` document. Its states are the states of ioredis.
+ * The wrapper adds its own events: the join at each `ready`, and the misses of its watchdog. It also
+ * adds a command that it sends again, and the bound of its close. A test records the transitions of the
+ * client and replays them against this document.
+ *
+ * The state `ready` hides states that the client cannot see (D4). In a black hole, ioredis stays
+ * `ready` while the kernel retransmits, until `driver_writeoff_time` or the watchdog ends that
+ * hidden interval. A timer of this document bounds each hidden interval.
+ */
+export declare const REDIS_CLIENT_MACHINE: Machine;
+//#endregion
+//#region src/redis/operations.d.ts
+/** These are the operations of the client: the idempotency of each command that the table names. */
+export declare const REDIS_OPERATIONS: Readonly<Record<string, Operation>>;
+/** This function gives the name of a command as the table writes it: upper case, and CLIENT ID with its subcommand. */
+export declare const commandName: (command: string, args: readonly unknown[]) => string;
+//#endregion
+export type { CheckOptions, ClientStep, ConnectionFactory, Detector, DialFn, Join, Meeting, RedisClient, RedisClientOptions, RedisClientSpec, RedisConnection, RedisConnectionOptions, RedisKnobs, RedisSocket, Sent, Situation };
+//# sourceMappingURL=redis.d.ts.map