@mark1russell7/service 0.5.11 → 0.5.13

package/build/grpc.d.ts

@@ -0,0 +1,307 @@
+import { Y as Poll, wt as Operation } 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 } from "./core-BPLRDcUJ.js";
+import { t as Judge } from "./dial-DA8vJfh2.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/grpc/connection.d.ts
+/** A state is the connectivity state of a channel of grpc-js, by the names of its enum `connectivityState`. */
+type GrpcState = "IDLE" | "CONNECTING" | "READY" | "TRANSIENT_FAILURE" | "SHUTDOWN";
+/** These states are in the sequence of the enum of grpc-js: the index of a state is its value. */
+export declare const GRPC_STATES: readonly GrpcState[];
+/** A status is the end of one call: its code (0 is OK) and its details. */
+interface GrpcStatus {
+  readonly code: number;
+  readonly details: string;
+}
+/** A call handle stops one call in flight. The grpc-js driver then writes RST_STREAM with the code CANCEL. */
+interface GrpcCallHandle {
+  cancel(): void;
+}
+/**
+ * A channel is the part of a `Client` of grpc-js 1.14 that the wrapper uses. A fake for tests has
+ * each part too. Thus the package depends on no type of grpc-js.
+ */
+interface GrpcChannel {
+  /** This method gives the state of the channel. True also starts a connect when the channel is IDLE. */
+  state(connect: boolean): GrpcState;
+  /** This method starts `changed` one time, when the state of the channel is no longer `current`. */
+  watch(current: GrpcState, changed: () => void): void;
+  /**
+   * This method sends one unary call: the method path and the bytes of its request message. `done`
+   * gets the status of the call, and the bytes of the response message when the status is OK. The
+   * call ends at `timeout` milliseconds with DEADLINE_EXCEEDED, and grpc-js sends the header `grpc-timeout`.
+   */
+  unary(method: string, request: Buffer, metadata: Readonly<Record<string, string>>, timeout: number, done: (status: GrpcStatus, response: Buffer | undefined) => void): GrpcCallHandle;
+  /** This method closes the channel. Its state becomes SHUTDOWN, and it does not connect again. */
+  close(): void;
+}
+/**
+ * These are the options of the channel that the wrapper gives `new Client(target, credentials, options)`.
+ * Each time comes from the declaration, in milliseconds.
+ */
+interface GrpcChannelOptions {
+  /** The wrapper turns off the retries of grpc-js, the transparent retry too. Only the core decides a second send. */
+  readonly "grpc.enable_retries": 0;
+  /** The wrapper reads no service config from the resolver. Thus no record of DNS changes the policy of a call. */
+  readonly "grpc.service_config_disable_resolution": 1;
+  /** This time is the interval of the HTTP/2 PING of keepalive. Without it, grpc-js sends no PING. */
+  readonly "grpc.keepalive_time_ms"?: number | undefined;
+  /** This time bounds the ACK of each PING. Without an ACK in this time, grpc-js ends the transport. */
+  readonly "grpc.keepalive_timeout_ms": number;
+  /** 1 sends the PING with no call in flight too. The server must permit that, or it answers with GOAWAY too_many_pings (O26). */
+  readonly "grpc.keepalive_permit_without_calls": 0 | 1;
+  /** This time with no call puts the channel in IDLE, and closes its connection. */
+  readonly "grpc.client_idle_timeout_ms": number;
+  /** This time is the first delay of grpc-js before a new try to connect. */
+  readonly "grpc.initial_reconnect_backoff_ms": number;
+  /** This time is the most that one delay of grpc-js can be, before its jitter of 20 %. */
+  readonly "grpc.max_reconnect_backoff_ms": number;
+}
+/** These are the arguments of `new Client(target, credentials, options)`. The credentials are insecure: the client speaks h2c. */
+interface GrpcConnectOptions {
+  readonly target: string;
+  readonly options: GrpcChannelOptions;
+}
+/** A channel factory makes one channel from its options. The channel connects later, when the wrapper asks it. */
+type GrpcFactory = Factory<GrpcConnectOptions, GrpcChannel>;
+/** This type is the part of a `Client` of grpc-js 1.14 that the adapter uses. */
+interface GrpcDriverClient {
+  getChannel(): {
+    getConnectivityState(connect: boolean): number;
+    watchConnectivityState(current: number, deadline: number, callback: (error?: Error) => void): void;
+  };
+  makeUnaryRequest(method: string, serialize: (value: Buffer) => Buffer, deserialize: (bytes: Buffer) => Buffer, argument: Buffer, metadata: unknown, options: {
+    readonly deadline: number;
+  }, callback: (error: {
+    readonly code?: number;
+    readonly details?: string;
+    readonly message?: string;
+  } | null, value?: Buffer) => void): GrpcCallHandle;
+  close(): void;
+}
+/** This type is the part of the module of grpc-js that the adapter uses. */
+interface GrpcDriver {
+  readonly Client: new (target: string, credentials: unknown, options: GrpcChannelOptions) => GrpcDriverClient;
+  readonly credentials: {
+    createInsecure(): unknown;
+  };
+  readonly Metadata: new () => {
+    add(key: string, value: string): void;
+  };
+}
+/**
+ * This function adapts a `Client` of grpc-js to a channel. The deadline of grpc-js is a time of the
+ * wall clock, thus the adapter adds the timeout to `Date.now()`.
+ */
+export declare const adaptGrpc: (grpc: GrpcDriver, client: GrpcDriverClient) => GrpcChannel;
+/**
+ * This factory makes a `Client` of grpc-js. It loads grpc-js only when a client connects, thus a
+ * service that does not use gRPC does not need it. The specifier is a value, thus the package needs no types of grpc-js.
+ */
+export declare const nodeGrpc: GrpcFactory;
+//#endregion
+//#region src/grpc/client.d.ts
+/**
+ * These are the knobs of the client, each a time, by the names of the ordering law and of the gRPC
+ * cells. The runtime has no defaults, thus each knob is necessary. The constant
+ * `GRPC_CLIENT_STARTING_KNOBS` gives a declaration from the gRPC cells. The knobs that each client has come from the core.
+ */
+interface GrpcKnobs extends ClientKnobs, RetryKnobs {
+  /** This time bounds the wait of the startup for a ready channel. The grpc-js driver has no connect timeout, and the wrapper cannot stop one connect. */
+  readonly connect_bound: Quantity;
+  /** This time is the deadline of each call, from its start. A second try ends in the same bound. The grpc-js driver sends it as `grpc-timeout`. */
+  readonly request_timeout: Quantity;
+  /** This time is the interval of the HTTP/2 PING of keepalive (`grpc.keepalive_time_ms`). "infinite" sends no PING, as grpc-js does at its defaults. */
+  readonly keepalive_time: Extent;
+  /** This time bounds the ACK of each PING (`grpc.keepalive_timeout_ms`). With no ACK, grpc-js ends the transport. */
+  readonly keepalive_timeout: Quantity;
+  /** This time with no call puts the channel in IDLE and closes its connection (`grpc.client_idle_timeout_ms`). The client then connects again. */
+  readonly client_idle_timeout: Quantity;
+  /**
+   * This time is the shortest interval of the PING that the server permits: `MinTime` of the
+   * enforcement policy of grpc-go. A shorter keepalive gets GOAWAY too_many_pings (O26). It is a fact of the server, not a knob of the client.
+   */
+  readonly server_keepalive_min_time: Quantity;
+  /** This time is when the server or a proxy ends an idle connection with GOAWAY, or "infinite". The client must close first (O01). */
+  readonly server_idle_close: Extent;
+  /** This time is the first delay of grpc-js before a new try to connect (`grpc.initial_reconnect_backoff_ms`). */
+  readonly retry_base: Quantity;
+  /** This time is the most that one delay of grpc-js can be, before its jitter of 20 % (`grpc.max_reconnect_backoff_ms`). */
+  readonly retry_cap: Quantity;
+  /** The grpc-js driver sets no TCP keepalive on its socket: the PING of `keepalive_time` is its keepalive. Thus this knob must be "infinite". */
+  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 at the shutdown: the calls in flight. At the bound, the client cancels each call, then closes the channel. */
+  readonly close_bound: Quantity;
+}
+/** A gRPC client spec is the declaration of one gRPC client: where it connects, and its knobs. */
+interface GrpcClientSpec extends ClientSpec<GrpcKnobs> {
+  /**
+   * True sends the PING of keepalive with no call in flight too (`grpc.keepalive_permit_without_calls`).
+   * The server must permit that (`PermitWithoutStream` of grpc-go), or it answers with GOAWAY too_many_pings (O26).
+   */
+  readonly keepaliveWithoutCalls: boolean;
+  /** These headers go with each call, for example `authorization`. The metadata of a call adds to them. */
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+  /** This name is the service that the round-trip check asks the health service about. The default is "", the whole server. */
+  readonly healthService?: string | undefined;
+  /**
+   * These operations are the methods of the service, by their full path, with their idempotency. The
+   * client sends again only a method that this table names as idempotent. `grpcOperations` makes the
+   * table from the `idempotency_level` of each method in its proto.
+   */
+  readonly operations?: ClientSpec<GrpcKnobs>["operations"];
+}
+/** These options make a client. Without them, it uses grpc-js, the real clock, and a dial with the HTTP/2 preface. */
+type GrpcClientOptions = ClientOptions<GrpcFactory>;
+/**
+ * A join is one generation of the client: each time that its channel becomes READY (D1, D2). The
+ * grpc-js driver gives no socket of its transport, thus the ends of the socket are null.
+ */
+interface GrpcJoin extends ClientJoin {
+  /** This text is the target of the channel. */
+  readonly target: string;
+}
+/** These options tell how the client sends one call. */
+interface GrpcCallOptions extends SendOptions {
+  /** These headers go with this call, after the metadata of the spec. */
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+/** A serving status is the status of a HealthCheckResponse of the health service (grpc.health.v1). */
+type GrpcServingStatus = "UNKNOWN" | "SERVING" | "NOT_SERVING" | "SERVICE_UNKNOWN";
+/** A gRPC client is a dependency of a service: its declaration, its handle, its checks and its calls. */
+interface GrpcClient extends Client<ClientStep, GrpcJoin> {
+  /** This text is the state of the client, as `GRPC_CLIENT_MACHINE` names it. */
+  readonly status: string;
+  /**
+   * This method sends one unary call, and waits for its status. `request` holds the bytes of the
+   * request message, and an OK status gives the bytes of the response message. The client sends again
+   * only an idempotent method, one time at most, after an outcome that is not certain.
+   */
+  call(method: string, request: Buffer, options?: GrpcCallOptions): Promise<Sent<Buffer>>;
+  /** This method sends one Check of the health service (grpc.health.v1), and gives the serving status of the reply. */
+  health(service?: string, options?: SendOptions): Promise<Sent<GrpcServingStatus>>;
+}
+/** The names of the status codes of gRPC, by their value. */
+export declare const GRPC_CODES: readonly ["OK", "CANCELLED", "UNKNOWN", "INVALID_ARGUMENT", "DEADLINE_EXCEEDED", "NOT_FOUND", "ALREADY_EXISTS", "PERMISSION_DENIED", "RESOURCE_EXHAUSTED", "FAILED_PRECONDITION", "ABORTED", "OUT_OF_RANGE", "UNIMPLEMENTED", "INTERNAL", "UNAVAILABLE", "DATA_LOSS", "UNAUTHENTICATED"];
+/** This function gives the name of a status code, for example "UNAVAILABLE". */
+export declare const codeName: (code: number) => string;
+/**
+ * This function gives the outcome of one call from its status:
+ * - OK is `ok`.
+ * - A code that tells that the server refused the call is a certain error: `reply` is true.
+ * - A status that tells that the call did not leave the client is a certain error with `reply` false.
+ * - Each other status is indeterminate: CANCELLED, UNKNOWN, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED,
+ *   INTERNAL, UNAVAILABLE and DATA_LOSS can come after the server applied the call.
+ */
+export declare const grpcOutcome: (status: GrpcStatus, response: Buffer | undefined) => Attempt<Buffer>;
+/** This method is the Check of the health service. Its request names a service, and its response gives a serving status. */
+export declare const HEALTH_CHECK = "/grpc.health.v1.Health/Check";
+/** These operations are in each table: the Check of the health service has no side effects. */
+export declare const GRPC_OPERATIONS: Readonly<Record<string, Operation>>;
+/** An idempotency level is the option `idempotency_level` of a method in its proto (descriptor.proto). */
+type GrpcIdempotencyLevel = "IDEMPOTENCY_UNKNOWN" | "NO_SIDE_EFFECTS" | "IDEMPOTENT";
+/**
+ * This function makes a table of operations from the idempotency level of each method, by its full
+ * path. NO_SIDE_EFFECTS and IDEMPOTENT are idempotent. IDEMPOTENCY_UNKNOWN, the default of a proto, is not.
+ */
+export declare const grpcOperations: (levels: Readonly<Record<string, GrpcIdempotencyLevel>>) => Record<string, Operation>;
+/** This function gives the bytes of a HealthCheckRequest. The service "" is the whole server, and its message is empty. */
+export declare const healthRequest: (service: string) => Buffer;
+/** This function gives the status of a HealthCheckResponse, or null when the bytes are not one. An empty message is UNKNOWN. */
+export declare const healthStatus: (bytes: Buffer) => GrpcServingStatus | null;
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+export declare const specProblems: (name: string, spec: GrpcClientSpec) => string[];
+/** This function gives the target of a channel from a spec: the host and the port, for the DNS resolver of grpc-js. */
+export declare const grpcTarget: (spec: Pick<GrpcClientSpec, "host" | "port">) => string;
+/**
+ * This function gives the arguments of `new Client` from a spec. Each timer of grpc-js comes from the
+ * declaration. The retries of grpc-js are off, and the resolver gives no service config.
+ */
+export declare const grpcOptions: (spec: GrpcClientSpec) => GrpcConnectOptions;
+/** These are the bytes of the dial: the connection preface of the client (RFC 9113 §3.4), and a SETTINGS frame with no setting. */
+export declare const HTTP2_PREFACE: Buffer;
+/**
+ * This judge reads the first frame of the server. Only a SETTINGS frame on stream 0, with no ACK,
+ * passes: RFC 9113 §3.4 makes it the first frame of an HTTP/2 server. An HTTP/1.1 server answers with a status line.
+ */
+export declare const settingsJudge: Judge;
+/** This dial opens a new TCP connection, sends the HTTP/2 preface, and waits for the SETTINGS frame of the server. The dial then destroys its socket. */
+export declare const grpcDial: DialFn;
+/**
+ * This function makes a gRPC client, a dependency of a service over grpc-js 1.14.
+ * - It has one channel for its life. Each time that the channel becomes READY is one generation.
+ * - The grpc-js driver connects again by itself, after its own backoff. The client connects an IDLE channel again at once.
+ * - A call is one unary call, until its status. Its deadline is the time that is left in `request_timeout`.
+ * - It tells the outcome of a call in three values from its status code (C8).
+ * - The retries of grpc-js are off, thus only the core sends a call again.
+ * - Its keepalive is the HTTP/2 PING of grpc-js. It records the target of each generation (D1).
+ *
+ * These parts come from the core of the clients: the outcomes, the second try and the wait for a ready client.
+ * The calls in flight, the bounded close and the checks come from the core too. This entry gives what grpc-js does in its own way.
+ */
+export declare const grpcClient: (name: string, spec: GrpcClientSpec, options?: GrpcClientOptions) => GrpcClient;
+//#endregion
+//#region src/grpc/machine.d.ts
+/**
+ * The gRPC client of the service as a `mark1russell7.machine/1` document. It is one channel of
+ * grpc-js 1.14 for the life of the client. Each READY of the channel is one generation. The states:
+ * - `ready`: the channel is READY, and the client sends each call. The keepalive sends a PING each keepalive_time.
+ * - `idle`: the transport ended, or the channel had no call in client_idle_timeout. The client connects again at once.
+ * - `failing`: the channel is in TRANSIENT_FAILURE. The grpc-js driver connects again after its backoff.
+ * - `closing`: the calls in flight, in `close_bound`. At the bound, each call gets RST_STREAM CANCEL.
+ *
+ * A test records the transitions of the client and replays them against this document.
+ */
+export declare const GRPC_CLIENT_MACHINE: Machine;
+//#endregion
+//#region src/grpc/meets.d.ts
+/**
+ * This function gives the manifestations that a gRPC client can meet, and the detectors of each,
+ * from its knobs. The gRPC cells measured them on grpc-js 1.14.6:
+ * - At its defaults, grpc-js has no detector: no keepalive, no deadline, and no TCP keepalive.
+ * - A reset gave each call ECONNRESET in 1.1 ms to 1.4 ms. The FIN of a stopped server ended an idle connection in 43 µs.
+ * - The keepalive ended a silent transport at keepalive_time + keepalive_timeout: 80.012 s at 60 s
+ *   against etcd, and 320.005 s at 300 s against grpc-go (DP24).
+ * - Without `keepaliveWithoutCalls`, grpc-js sends a PING only with a call in flight.
+ * - At client_idle_timeout, the channel goes IDLE, and the client connects again. A server that does
+ *   not answer then keeps the channel out of READY.
+ */
+export declare const grpcMeetings: (name: string, knobs: GrpcKnobs, withoutCalls: boolean) => Meeting[];
+//#endregion
+//#region src/grpc/starting.d.ts
+/**
+ * This poll is the poll of the checks that `GRPC_CLIENT_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 GRPC_CLIENT_STARTING_POLL: Poll;
+/**
+ * This value tells if the keepalive sends a PING with no call in flight, to start from: false. The
+ * grpc-go server refuses such a PING at its defaults (`PermitWithoutStream` false). It answers with GOAWAY too_many_pings (O26).
+ */
+export declare const GRPC_CLIENT_STARTING_WITHOUT_CALLS: boolean;
+/**
+ * These knobs are a declaration to start from, from what the gRPC cells measured on grpc-js 1.14.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 grpc-js driver has no connect timeout, thus this bounds the wait of the startup.
+ * - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13). In DP44 a deadline of 4 s ended each
+ *   call at 4.003 s to 4.004 s. The race of the two deadlines gave CANCELLED to 2 to 4 calls of 11.
+ * - `keepalive_time` 300 s and `keepalive_timeout` 20 s: DP24. The PING must not come before the
+ *   `MinTime` of the server, 5 min at the defaults of grpc-go (O26). The transport ended at 320.005 s.
+ *   Against etcd, with a `MinTime` of 5 s, 60 s ended it at 80.012 s. A PING each 4 s against 5 s got GOAWAY at the 4th PING.
+ * - `server_keepalive_min_time` 300 s: the `MinTime` of grpc-go v1.84.0 at its defaults.
+ * - `client_idle_timeout` 60 s and `server_idle_close` 75 s: the proxies of the cells sent GOAWAY to an idle connection.
+ *   They did that at 75 s (nginx), 180 s (Traefik), 300 s (Caddy) and 1 h (Envoy). The client closes first (O01).
+ *   The default of grpc-js is 30 min.
+ * - `retry_base` 1 s: the first backoff of grpc-js in T07, with no jitter. `retry_cap` 4 s: the most
+ *   delay is 4.8 s with the jitter of 20 %, in the slowest poll of 10 s. The default of grpc-js is 120 s.
+ * - `keepalive_idle` "infinite": grpc-js sets no TCP keepalive, and the PING is its keepalive.
+ * - `max_connection_age` "infinite": the client does not replace its connection at an age.
+ * - `close_bound` 2 s: the calls in flight, then RST_STREAM CANCEL for each call that stays.
+ * - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`.
+ */
+export declare const GRPC_CLIENT_STARTING_KNOBS: GrpcKnobs;
+//#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, type GrpcCallHandle, type GrpcCallOptions, type GrpcChannel, type GrpcChannelOptions, type GrpcClient, type GrpcClientOptions, type GrpcClientSpec, type GrpcConnectOptions, type GrpcFactory, type GrpcIdempotencyLevel, type GrpcJoin, type GrpcKnobs, type GrpcServingStatus, type GrpcState, type GrpcStatus, type Judge, MANIFESTATIONS, type Manifestation, type Meeting, type ReadyWait, type RetryKnobs, STARTING_POLL, type SendOptions, type Sent, type Situation, firstDetector, readyWait, retryProblems, unwatched };
+//# sourceMappingURL=grpc.d.ts.map