@mark1russell7/service 0.5.12 → 0.5.13

package/build/rabbitmq.d.ts

@@ -0,0 +1,294 @@
+import { Y as Poll } from "./lifecycle-fgYfxrHK.js";
+import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, b as retryProblems, c as ClientSpec, d as Factory, f as ReadyWait, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, p as RetryKnobs, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as readyWait, w as Manifestation, y as retryBackoff } from "./core-BPLRDcUJ.js";
+import { t as Judge } from "./dial-DA8vJfh2.js";
+import { i as JobSettle } from "./queue-snRHK3Jm.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/rabbitmq/connection.d.ts
+/** A message is a message of the broker, as amqplib gives it from `get`. The wrapper reads only these fields. */
+interface RabbitMessage {
+  readonly content: Buffer;
+  readonly fields: {
+    readonly deliveryTag: number;
+    readonly redelivered: boolean;
+    readonly exchange: string;
+    readonly routingKey: string;
+    /** This count is the number of messages that stay on the queue after this one. */
+    readonly messageCount?: number | undefined;
+  };
+  readonly properties: {
+    readonly headers?: Readonly<Record<string, unknown>> | undefined;
+    readonly [property: string]: unknown;
+  };
+}
+/** These are the properties of a publish that amqplib takes, for example `persistent`, `messageId` and `headers`. */
+type RabbitPublishOptions = Readonly<Record<string, unknown>>;
+/** These are the events of a channel that the wrapper listens to. */
+type RabbitChannelEvent = "error" | "close";
+/**
+ * A channel is the part of a `ConfirmChannel` of amqplib 2 that the wrapper uses. A confirm channel
+ * gives one result to the callback of each publish. The result is null for a `basic.ack`. It is an
+ * error for a `basic.nack` and for the end of the channel.
+ */
+interface RabbitChannel {
+  /** This method writes one message. It throws when the channel is closed or closing. */
+  publish(exchange: string, routingKey: string, content: Buffer, options: RabbitPublishOptions, callback: (error: Error | null) => void): boolean;
+  /** This method takes one message (`basic.get`), or gives false when the queue is empty. It has no timer of its own. */
+  get(queue: string, options?: {
+    readonly noAck?: boolean | undefined;
+  }): Promise<RabbitMessage | false>;
+  /** This method declares an exchange in passive mode: an RPC that changes nothing. The round-trip check uses it. */
+  checkExchange(exchange: string): Promise<unknown>;
+  /** This method acknowledges one message. It is one frame, with no reply. */
+  ack(message: RabbitMessage): void;
+  /** This method gives one message back to the broker, to the queue or to its dead-letter route. It is one frame, with no reply. */
+  nack(message: RabbitMessage, allUpTo?: boolean, requeue?: boolean): void;
+  close(): Promise<void>;
+  on(event: RabbitChannelEvent, listener: (error?: Error) => void): unknown;
+  off(event: RabbitChannelEvent, listener: (error?: Error) => void): unknown;
+}
+/** These are the events of a connection that the wrapper listens to. The event `blocked` gives the reason of the broker. */
+type RabbitConnectionEvent = "error" | "close" | "blocked" | "unblocked";
+/**
+ * A connection is the part of a `ChannelModel` of amqplib 2 that the wrapper uses. A `ChannelModel`
+ * has each part. A fake for tests has them too. Thus the package depends on no type of amqplib.
+ */
+interface RabbitConnection {
+  /** This method opens a channel with confirms (`confirm.select`). */
+  createConfirmChannel(): Promise<RabbitChannel>;
+  /** This method sends `connection.close`, and waits for `connection.close-ok`. Behind a black hole, it waits with no bound. */
+  close(): Promise<void>;
+  on(event: RabbitConnectionEvent, listener: (detail?: unknown) => void): unknown;
+  off(event: RabbitConnectionEvent, listener: (detail?: unknown) => void): unknown;
+  /** This field holds the socket. The join reads its addresses, and the bounded close destroys it. */
+  readonly connection: {
+    readonly stream?: ClientSocket | undefined;
+  };
+}
+/**
+ * These are the socket options that the wrapper gives amqplib. Each one comes from the declaration.
+ * At its defaults, amqplib sets no connect timeout, no keepalive and no TCP_NODELAY.
+ */
+interface RabbitSocketOptions {
+  /** This time bounds the TCP connect and the handshake. The timer stops when the connection opens. A time of 0 is no bound. */
+  readonly timeout: number;
+  /** The library turns Nagle off only when the caller asks. A confirm and a reply then do not wait for a delayed ACK. */
+  readonly noDelay: true;
+  readonly keepAlive: boolean;
+  /** This time is the idle time of TCP keepalive, in milliseconds. Node truncates it to whole seconds. */
+  readonly keepAliveDelay?: number | undefined;
+  /** The broker shows `connection_name` in its management view and its log, thus the prober can join on it too. */
+  readonly clientProperties: {
+    readonly connection_name: string;
+  };
+}
+/** These are the arguments of `connect(url, socketOptions)`. The URL gives the host, the vhost, the user and the heartbeat. */
+interface RabbitConnectOptions {
+  readonly url: string;
+  readonly socketOptions: RabbitSocketOptions;
+}
+/** A connection factory makes one connection of amqplib from its options. A failure to open rejects. */
+type RabbitFactory = Factory<RabbitConnectOptions, RabbitConnection>;
+/**
+ * This factory opens a connection of amqplib. It loads amqplib only when a client connects, thus a
+ * service that does not use RabbitMQ does not need it. The specifier is a value, thus the package
+ * needs no types of amqplib. The built-in recovery of amqplib stays off, because the wrapper connects again by itself.
+ */
+export declare const nodeAmqp: RabbitFactory;
+//#endregion
+//#region src/rabbitmq/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. A bound that nobody gives is
+ * "infinite", not zero. The constant `RABBIT_STARTING_KNOBS` gives a declaration from the cells of R3. The knobs
+ * that each client has come from the core.
+ */
+interface RabbitKnobs extends ClientKnobs, RetryKnobs {
+  /**
+   * This time bounds the TCP connect and the handshake (`socketOptions.timeout`). The client also
+   * bounds the open of its channel with it. The timer of amqplib stops when the connection opens.
+   */
+  readonly connect_bound: Quantity;
+  /** This time bounds each call: a publish until its confirm, and an RPC until its reply. The wrapper has this timer, because amqplib has none. */
+  readonly request_timeout: Quantity;
+  /**
+   * This time is the heartbeat that the client asks for (`heartbeat` in the URL), in whole seconds.
+   * The connection uses the smaller of this value and the value of the broker. The value "infinite" asks for no heartbeat.
+   */
+  readonly heartbeat_interval: 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 is the idle time of TCP keepalive (`keepAliveDelay`), in whole seconds. The value "infinite" turns keepalive off, as amqplib does by default. */
+  readonly keepalive_idle: Extent;
+  /** The client does not replace its connection at an age, thus this knob must be "infinite". */
+  readonly max_connection_age: Extent;
+  /** This time bounds the close of the client at the shutdown: `connection.close`, then a destroy of the socket. */
+  readonly close_bound: Quantity;
+}
+/** A seed is one more node of the cluster. The client connects to the next node after each failure, in sequence. */
+interface RabbitSeed {
+  readonly host: string;
+  readonly port: number;
+}
+/** A RabbitMQ client spec is the declaration of one RabbitMQ client: where it connects, and its knobs. */
+interface RabbitClientSpec extends ClientSpec<RabbitKnobs> {
+  /** This name is the virtual host. The default of the broker is "/". */
+  readonly vhost?: string | undefined;
+  /** This name is the user. Without it, amqplib connects as the user "guest". */
+  readonly username?: string | undefined;
+  /** These nodes are more nodes of the cluster, after `host` and `port`. */
+  readonly seeds?: readonly RabbitSeed[] | undefined;
+  /**
+   * These operations are the calls of the service, by name, with their idempotency. A message does
+   * not tell if a consumer removes its duplicates. Thus the client sends again only a call that this table names.
+   */
+  readonly operations?: ClientSpec<RabbitKnobs>["operations"];
+}
+/** These options make a client. Without them, it uses amqplib, the real clock, `Math.random`, and a dial with the protocol header. */
+interface RabbitClientOptions extends ClientOptions<RabbitFactory> {
+  readonly random?: (() => number) | undefined;
+}
+/**
+ * A join is one generation of the client: one connection and its channel, when the channel is open
+ * (D1, D2). The prober joins its kernel records to the view of the broker through it.
+ */
+interface RabbitJoin extends ClientJoin {
+  /** This text is the node of the connection, as `host:port`. */
+  readonly address: string;
+  /** This text is the name of the connection in the broker, `local:port -> remote:port`, or null when the socket gives no addresses. */
+  readonly connectionName: string | null;
+}
+/** A publish is one message to an exchange. A string content goes as UTF-8. */
+interface RabbitPublish {
+  readonly exchange: string;
+  readonly routingKey: string;
+  readonly content: Buffer | string;
+  /** These properties go to amqplib, for example `persistent`, `messageId` and `headers`. */
+  readonly properties?: RabbitPublishOptions | undefined;
+}
+/** A delivery is one message that the client took from a queue. It stays on the channel of its generation until a settle. */
+interface RabbitDelivery {
+  readonly message: RabbitMessage;
+  /** This number is the generation of the channel that holds the message. */
+  readonly generation: number;
+  /** This count is the delivery of the message, 1 at the first, from `x-delivery-count` or `redelivered`. */
+  readonly delivery: number;
+}
+/** These are the source and the settle of a queue drain on one queue: `queueDrain({ source, settle, ... })`. */
+interface RabbitJobs {
+  /** This function takes one job, or gives null when the queue is empty. It is a `JobSource` of the drain. */
+  readonly source: (signal: AbortSignal) => Promise<RabbitDelivery | null>;
+  readonly settle: JobSettle<RabbitDelivery>;
+}
+/** A RabbitMQ client is a dependency of a service: its declaration, its handle, its checks and its calls. */
+interface RabbitClient extends Client<ClientStep, RabbitJoin> {
+  /** This text is the state of the client, as `RABBIT_CLIENT_MACHINE` names it. */
+  readonly status: string;
+  /**
+   * This method publishes one message, and waits for its confirm. An ack is `ok`. The client sends
+   * again only an idempotent operation, one time at most, after an outcome that is not certain.
+   */
+  publish(operation: string, message: RabbitPublish, options?: SendOptions): Promise<Sent<void>>;
+  /** This method takes one message from a queue (`basic.get`), or gives null when the queue is empty. */
+  get(operation: string, queue: string, options?: SendOptions): Promise<Sent<RabbitDelivery | null>>;
+  /** This method gives the source and the settle of a queue drain. The source takes each job with `get`. */
+  jobs(operation: string, queue: string): RabbitJobs;
+}
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+export declare const specProblems: (name: string, spec: RabbitClientSpec) => string[];
+/**
+ * This function gives the arguments of `connect` for one node of a spec. Each timer of amqplib
+ * comes from the declaration. The heartbeat goes in the URL, and "infinite" is 0, no heartbeat.
+ */
+export declare const rabbitOptions: (name: string, spec: RabbitClientSpec, index?: number) => RabbitConnectOptions;
+/** The bytes of the protocol header of AMQP 0-9-1. A broker answers it with `connection.start`, before the authentication. */
+export declare const AMQP_HEADER: Uint8Array;
+/**
+ * This judge reads the answer to the protocol header. A broker that takes the version sends a method
+ * frame on channel 0: `connection.start`, class 10 and method 10. A broker that refuses the version
+ * sends its own protocol header, and closes the socket.
+ */
+export declare const startJudge: Judge;
+/** This dial function opens a TCP connection, sends the protocol header, and waits for `connection.start`. It needs no password. */
+export declare const amqpDial: DialFn;
+/**
+ * This function gives the outcome of a failure of amqplib. The library names few classes of error.
+ * Thus the wrapper reads the fields:
+ * - A throw before the write (`IllegalOperationError`: the channel is closed or closing) is certain: the call did not leave the client.
+ * - A reply code of the broker, from the close of the channel, is certain. The broker refused the call, or a call before it.
+ * - A nack, and an end of the channel before the reply or the confirm, are not certain.
+ */
+export declare const failureOutcome: (error: unknown) => Attempt<never>;
+/** This function gives the count of deliveries of a message, 1 at the first. A quorum queue counts in `x-delivery-count`. */
+export declare const deliveryCount: (message: RabbitMessage) => number;
+/**
+ * This function makes a RabbitMQ client, a dependency of a service over amqplib 2.
+ * - It has one connection and one confirm channel, as one generation. The end of either one ends
+ *   the generation. The client then connects again by itself, to the next node, after a backoff.
+ * - It sets each timer of amqplib from the declaration. The built-in recovery of amqplib stays off.
+ * - Its call is a confirmed publish, or an RPC with a reply. Each call has a timer of the wrapper, because amqplib has none.
+ * - It tells the outcome of a call in three values, and it settles each call in flight at the end of its generation (C8, C10).
+ * - It records the node and the name of each connection at the open of its channel (D1).
+ *
+ * These parts come from the core of the clients: the outcomes, the second try, the wait for a ready client and the backoff.
+ * The calls in flight, the bounded close and the checks also come from the core. This entry gives what amqplib does in its own way.
+ */
+export declare const rabbitClient: (name: string, spec: RabbitClientSpec, options?: RabbitClientOptions) => RabbitClient;
+//#endregion
+//#region src/rabbitmq/machine.d.ts
+/**
+ * The RabbitMQ client of the service as a `mark1russell7.machine/1` document. It is one generation
+ * at a time: one connection of amqplib and its confirm channel. The machines `amqplib` and
+ * `rabbitmq-connection` of `@mark1russell7/machines` give the connection and its heartbeat. The states:
+ * - `ready`: the channel is open, and the client sends each call.
+ * - `blocked`: a resource alarm of the broker blocked the connection. Each call is not sent until the unblock.
+ * - `failing`: no generation is open. The client tries the next node after its backoff.
+ *
+ * The end of the channel or of the connection ends the generation. A test records the transitions
+ * of the client and replays them against this document.
+ */
+export declare const RABBIT_CLIENT_MACHINE: Machine;
+//#endregion
+//#region src/rabbitmq/meets.d.ts
+/**
+ * This function gives the manifestations that a RabbitMQ client can meet, and the detectors of each,
+ * from its knobs. The cells of R3 measured them on amqplib 2.2.0 against RabbitMQ 4.3.6:
+ * - The heartbeat ends a silent connection 2 to 3 heartbeats after the last data. The cells measured
+ *   180.009 s at 60 s, and 45.009 s at 15 s (O17). It finds a silent broker in flight and idle.
+ * - A stopped broker resets each client at once, because each socket of RabbitMQ has linger 0.
+ * - At `tcp_retries2 = 7`, the kernel gave up at 53.016 s.
+ * - A broker with a resource alarm blocks each connection that publishes, and it still sends its heartbeats.
+ */
+export declare const rabbitMeetings: (name: string, knobs: RabbitKnobs) => Meeting[];
+//#endregion
+//#region src/rabbitmq/starting.d.ts
+/**
+ * This poll is the poll of the checks that `RABBIT_STARTING_KNOBS` fits. It is `STARTING_POLL` of
+ * the core: each 5 s with a jitter of 20 %, and a timeout of 4 s (B6, O12). The poll does not depend on the driver.
+ */
+export declare const RABBIT_STARTING_POLL: Poll;
+/**
+ * These knobs are a declaration to start from, from what the cells of R3 measured on amqplib 2.2.0
+ * against RabbitMQ 4.3.6. The runtime has no defaults: a service gives these knobs, or its own.
+ * Each value holds the borders that the cells measured:
+ * - `connect_bound` 5 s: the connect timeout of DP44. The timer stops when the connection opens.
+ *   Thus it does not change a fault with a call in flight. At its defaults, amqplib has no connect timeout.
+ * - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13). After a loss of the leader of a quorum
+ *   queue, the first confirm came at 6.61 s, 6.68 s and 8.05 s (T11). A later confirm is indeterminate, not lost.
+ * - `heartbeat_interval` 15 s: the heartbeat ended a silent connection 45.009 s after the last data,
+ *   before the kernel gave up at 53.016 s (O17). The frames each 7.5 s keep a flow through a router
+ *   that forgets it at 30 s (O03). At the 60 s of the broker, the heartbeat came at 180.009 s.
+ * - `retry_base` 1 s: the cells connected to the next node 1 s after the end of a connection.
+ * - `retry_cap` 8 s: no cell measured it. With its jitter of 1 s, the most delay is 9 s, in the slowest poll of 10 s.
+ * - `keepalive_idle` "infinite": amqplib sets no keepalive, and the heartbeat refreshes an idle flow.
+ *   Linux sends no keepalive probe while data is in flight.
+ * - `max_connection_age` "infinite": the client does not replace its connection at an age.
+ * - `close_bound` 2 s: behind a black hole, `connection.close` waits for its close-ok with no bound.
+ * - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`.
+ */
+export declare const RABBIT_STARTING_KNOBS: RabbitKnobs;
+//#endregion
+export { type Attempt, type CheckOptions, type Client, type ClientJoin, type ClientKnobs, type ClientOptions, type ClientSocket, type ClientSpec, type ClientStep, type Detector, type DialFn, type Factory, MANIFESTATIONS, type Manifestation, type Meeting, type RabbitChannel, type RabbitChannelEvent, type RabbitClient, type RabbitClientOptions, type RabbitClientSpec, type RabbitConnectOptions, type RabbitConnection, type RabbitConnectionEvent, type RabbitDelivery, type RabbitFactory, type RabbitJobs, type RabbitJoin, type RabbitKnobs, type RabbitMessage, type RabbitPublish, type RabbitPublishOptions, type RabbitSeed, type RabbitSocketOptions, type ReadyWait, type RetryKnobs, STARTING_POLL, type SendOptions, type Sent, type Situation, firstDetector, readyWait, retryBackoff, retryProblems, unwatched };
+//# sourceMappingURL=rabbitmq.d.ts.map