@mark1russell7/service 0.4.0 → 0.5.0

package/build/http.d.ts

@@ -0,0 +1,277 @@
+import { n as Clock } from "./clock-D-38uH_z.js";
+import { d as TransportImpl, m as RequestEnd, n as HealthServer, r as Lifecycle, v as RequestStream, x as Health, y as RequestWork } from "./lifecycle-DIj4YGmO.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { ListenOptions } from "node:net";
+import { IncomingMessage, Server, ServerEventMap, ServerResponse } from "node:http";
+//#region src/http/transport.d.ts
+/**
+ * These are the knobs of an HTTP transport, by the names of the ordering law. The transport has no
+ * defaults, thus each knob is necessary. The declaration of the server gets the same record.
+ */
+interface HttpKnobs {
+  /**
+   * This time is the real idle close of the server, which O01 compares with the idle time of a
+   * client. Node closes an idle connection at `keepAliveTimeout` plus `keepAliveTimeoutBuffer`.
+   * Thus the transport sets `keepAliveTimeout` to this time less the buffer of the server.
+   * A time without a bound stops the timer.
+   */
+  readonly server_idle_close: Extent;
+  /**
+   * This time is the interval of the sweep of idle connections, from the stop of the intake until the
+   * close. A time without a bound gives one sweep, at the stop of the intake.
+   */
+  readonly server_idle_sweep_interval: Extent;
+  /** This time goes in the `Retry-After` of each 503 that the transport gives after its intake stops. */
+  readonly server_retry_after: Quantity;
+  /** The other knobs of the server go to the declaration. The transport does not read them. */
+  readonly [knob: string]: Extent;
+}
+/**
+ * These are the knobs that the transport gives the declaration: the knobs of the caller, and the two
+ * times that the transport found. Thus the declaration shows the three times of the idle close.
+ */
+interface HttpTransportKnobs extends HttpKnobs {
+  /** This time is the hint that each response sends (`Keep-Alive: timeout=…`), in whole seconds. A time without a bound tells that no hint goes. */
+  readonly server_idle_close_hint: Extent;
+  /** This time is the `keepAliveTimeoutBuffer` of the server, which Node adds to the timer and not to the hint. */
+  readonly server_idle_close_buffer: Quantity;
+}
+/** A mount stage is the stage of the shutdown at which a mount stops: the stop of the intake, or the close. */
+type MountStage = "stop intake" | "close transports";
+/** A mount context gives each handler the signals of the shutdown, the lifecycle and the time of a retry. */
+interface MountContext {
+  /** This signal aborts when the intake stops. A long stream ends in its own protocol at it. */
+  readonly intake: AbortSignal;
+  /** This signal aborts at the cooperative abort of the drain, or at the close. The work in flight stops at it. */
+  readonly signal: AbortSignal;
+  /** This lifecycle is the lifecycle that the transport got at its start, or null before the start. */
+  readonly life: Lifecycle | null;
+  /** This time is the knob `server_retry_after`: the `Retry-After` of each 503 of the handlers. */
+  readonly retryAfter: Quantity;
+}
+/**
+ * A request handler answers a request and gives true, or it gives false and does not touch the
+ * response. Then the next handler gets the request. `until` tells when the handler stops.
+ */
+interface RequestHandler {
+  (req: IncomingMessage, res: ServerResponse, context: MountContext): boolean | Promise<boolean>;
+  readonly until?: MountStage | undefined;
+}
+type UpgradeArgs = ServerEventMap["upgrade"];
+/** An upgrade socket is the stream of an upgraded connection, as the `upgrade` event of Node gives it. */
+type UpgradeSocket = UpgradeArgs[1];
+/** An upgrade handler takes an upgraded connection, for example a WebSocket server in its `noServer` mode. */
+interface UpgradeHandler {
+  (req: IncomingMessage, socket: UpgradeSocket, head: UpgradeArgs[2], context: MountContext): void;
+  readonly until?: MountStage | undefined;
+}
+/** An upgrade match is a path, without its query, or a function that tells if a handler takes a request. */
+type UpgradeMatch = string | ((req: IncomingMessage) => boolean);
+/** These options change one mount. */
+interface MountOptions {
+  /**
+   * This stage is when the mount stops. Without it, the stage of the handler applies, and then
+   * `stop intake`. A mount until `close transports` keeps the listener open through the drain.
+   */
+  readonly until?: MountStage | undefined;
+}
+/** These options make an HTTP transport. */
+interface HttpTransportOptions {
+  /**
+   * These are the listen options of `start()`, or a function that makes the server listen. Without
+   * them, `start()` takes a server that listens already.
+   */
+  readonly listen?: ListenOptions | ((server: Server) => Promise<void> | void) | undefined;
+  /** This clock is the clock of the lifecycle. The deadline of the drain and the sweep use it. */
+  readonly clock?: Clock | undefined;
+  /**
+   * This function tells if a response can keep its connection open. Without it, the transport reads
+   * `life.keepAlive()` of the lifecycle of its start. The transport reads it when the headers of
+   * each response go, and false gives `Connection: close`.
+   */
+  readonly keepAlive?: (() => boolean) | undefined;
+  /** This function receives each error of a handler. The transport then answers 500, or it destroys the response. */
+  readonly onError?: ((error: unknown, req: IncomingMessage) => void) | undefined;
+}
+/** An HTTP transport is a server of `node:http` as a transport of the lifecycle, with a list of mounts on its listener. */
+interface HttpTransport extends TransportImpl {
+  readonly server: Server;
+  /** These knobs go to the declaration of the server: the knobs of the caller, the hint and the buffer. */
+  readonly knobs: HttpTransportKnobs;
+  /** This method adds a request handler at the end of the list, and gives the function that removes it. */
+  mount(handler: RequestHandler, options?: MountOptions): () => void;
+  /** This method adds an upgrade handler for a path, and gives the function that removes it. */
+  upgrade(match: UpgradeMatch, handler: UpgradeHandler, options?: MountOptions): () => void;
+  /** This count is the number of open connections, idle connections and upgraded connections too. */
+  readonly connections: number;
+  /** This flag tells if the transport stopped its intake. */
+  readonly intakeStopped: boolean;
+}
+/** This function gives the path of a request target, without its query and fragment. */
+export declare const pathOf: (url: string | undefined) => string;
+/**
+ * This function makes a server of `node:http` a transport of the lifecycle (S6 A8 and A13). It is not
+ * a framework: it has no routes, no body parser and no middleware.
+ * - The count of work in flight comes from events: each response until its `close`, and each upgraded
+ *   connection until its `close`.
+ * - `stopIntake` closes the listener, and new connections get a refusal. It closes the idle connections
+ *   at once and at each `server_idle_sweep_interval`. Each later response gets `Connection: close`.
+ * - `drain` waits until no work is in flight, or until the deadline. It gives the cooperative abort to
+ *   the handlers through their context.
+ * - `close` destroys each connection. A second close gives the same promise.
+ * - The mounts share one port. The first request handler that gives true answers. After the stop of
+ *   the intake, only the mounts until `close transports` answer, and each other request gets a 503.
+ */
+export declare const httpTransport: (server: Server, knobs: HttpKnobs, options?: HttpTransportOptions) => HttpTransport;
+//#endregion
+//#region src/http/probes.d.ts
+/** A probe response is the status, the headers and the body of one probe, for any HTTP framework or none. */
+interface ProbeResponse {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+/** A health source is the health runtime, or a function that gives it when it exists. */
+type HealthSource = Health | (() => Health | null | undefined);
+/**
+ * This function gives the response of a probe path from the cache of the health runtime. For a path
+ * that is not a probe, it gives null. The paths are `/startup`, `/readiness`, `/liveness` and
+ * `/report` after the prefix. `/readiness/<controller>` gives the readiness of one controller.
+ */
+export declare const probeResponse: (health: Health | null | undefined, method: string | undefined, path: string, prefix?: string) => ProbeResponse | null;
+/** These options mount the probes on the port of the application. */
+interface ProbeHandlerOptions {
+  /** This path goes before each probe path, for example `/health`. It starts with `/`, or it is empty. */
+  readonly prefix: string;
+}
+/**
+ * This function gives a request handler that answers the probes on the port of the application. It
+ * answers until `close transports`, thus its mount keeps the listener open through the drain. A path
+ * that is not a probe goes to the next handler. Each 503 gets the `Retry-After` of the context.
+ */
+export declare const probeHandler: (health: HealthSource, options: ProbeHandlerOptions) => RequestHandler;
+/** These options make a probe server: the listen options of its port, the prefix of its paths, and the time of a retry. */
+interface ProbeServerOptions extends ListenOptions {
+  /**
+   * This time goes in the `Retry-After` of each 503 of a probe, as on the port of the application.
+   * The probe server has no defaults, thus the knob is necessary.
+   */
+  readonly server_retry_after: Quantity;
+  /** This path goes before each probe path. The default is no prefix, because the port has only the probes. */
+  readonly prefix?: string | undefined;
+  /** This server answers the probes. Without it, the probe server makes a server of `node:http`. */
+  readonly server?: Server | undefined;
+}
+/** A probe server is a health server on its own port. Its server is visible for the address of the port. */
+interface ProbeServer extends HealthServer {
+  readonly server: Server;
+}
+/**
+ * This function makes a health server on a port of its own (S6 decision D5). It starts first and
+ * closes last, thus the probes answer through the whole drain. Each probe answers from the cache, and
+ * each 503 gets the `Retry-After` of `server_retry_after`.
+ */
+export declare const probeServer: (options: ProbeServerOptions) => ProbeServer;
+//#endregion
+//#region src/http/outcome.d.ts
+/** An outcome response is the status, the headers and the body of a request, for any HTTP framework or none. */
+interface OutcomeResponse {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string | Uint8Array;
+}
+/** A response part is what a hook gives for one value or one failure. The parts that it does not give keep the values of the mapping. */
+interface ResponsePart {
+  readonly status?: number | undefined;
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly body?: string | Uint8Array | undefined;
+}
+/**
+ * A stream format writes the items of a stream and its end in the body, as they come. An end after
+ * the first item goes in the body, because the status went with the first item.
+ */
+interface StreamFormat<T = unknown> {
+  readonly contentType: string;
+  /** This function gives the bytes of one item. */
+  item(value: T): string | Uint8Array;
+  /** This function gives the bytes of the end, the last part of the body. */
+  end(end: RequestEnd): string | Uint8Array;
+}
+/** These options map a request to a response. */
+interface OutcomeOptions<T> {
+  /**
+   * This value tells if the response can keep its connection open, as `life.keepAlive()` does. False
+   * gives `Connection: close`. A function is read when the headers go.
+   */
+  readonly keepAlive: boolean | (() => boolean);
+  /** This time goes in the `Retry-After` of each 503, in whole seconds, rounded up. It is the knob `server_retry_after`. */
+  readonly retryAfter: Quantity;
+  /**
+   * This function gives the response of the value of a unary request. Without it, the mapping gives
+   * 200 and the value as JSON, or 204 for no value.
+   */
+  readonly done?: ((value: T) => ResponsePart) | undefined;
+  /**
+   * This function gives the response of a failure of the route before the first byte. Without it,
+   * the mapping gives 500 with no detail, because an error can hold private data.
+   */
+  readonly failed?: ((error: unknown) => ResponsePart) | undefined;
+  /**
+   * This format makes the response a stream: the status and each item go as they come, and the end
+   * goes in the body. Without it, the response is unary: one status and the one value.
+   */
+  readonly stream?: StreamFormat<T> | undefined;
+}
+/**
+ * This function gives an end as a record for a body: its kind and the count of its items. A cut and
+ * a refusal also give their cause, and if the caller can send the request again. A failure gives
+ * no detail.
+ */
+export declare const endRecord: (end: RequestEnd) => Readonly<Record<string, unknown>>;
+/** This format writes each item and the end as one line of JSON (NDJSON). */
+export declare const ndjson: StreamFormat;
+/** This format writes each item as an event of server-sent events, and the end as the event `end`. */
+export declare const sse: StreamFormat;
+/**
+ * This function maps a unary request to its response, from its items and its end (S6 A12 and A13).
+ * - One value and the end `done`: 200 with the value, or the response of the `done` hook.
+ * - No value and the end `done`: 204. More than one value: 500, because the route is not a stream.
+ * - `refused`: 503. The work did not start, thus the caller can send it again. The service did not
+ *   start, it stopped its intake, or a controller is not ready.
+ * - `cut`: 503 for a route whose callers can send it again (S6 A12), and 500 for each other route.
+ * - `failed`: 500 with no detail, or the response of the `failed` hook. A failure of the route is not a 503.
+ *
+ * Each 503 gets `Retry-After` (RFC 9110), and a 500 gets none. Each response gets `Connection: close`
+ * while the service cannot keep the connection.
+ */
+export declare const outcomeResponse: <T>(items: readonly T[], end: RequestEnd, options: OutcomeOptions<T>) => OutcomeResponse;
+/**
+ * This function writes the stream of a request to a response of `node:http`, and gives its end. It
+ * gives null when the client closed the connection first. Then the work stops through `return()`.
+ * - Unary (no format): it waits for the end, and it writes the status and the body of `outcomeResponse`.
+ * - Stream: the status 200 goes with the first item, then each item goes as it comes, then the end
+ *   goes in the body (in-band). The next item waits until the client reads, thus a slow client
+ *   slows the work. An end before the first item gets a status, as a unary end does.
+ */
+export declare const writeOutcome: <T>(res: ServerResponse, stream: RequestStream<T>, options: OutcomeOptions<T>) => Promise<RequestEnd | null>;
+/** A route of a handler is the name of the route that a controller declares, or a function that gives it from the request. */
+type HandledRoute = string | ((req: IncomingMessage) => string | null);
+/** A handled work does the work of one request of `node:http`. Its signal aborts when the shutdown or the client stops the request. */
+type HandledWork<T> = (req: IncomingMessage, signal: AbortSignal) => RequestWork<T>;
+/** These options bind a request of `node:http` to the request tracking of the service. */
+interface HandleOptions<T> extends Omit<OutcomeOptions<T>, "keepAlive" | "retryAfter"> {
+  /** This function gives the detail of a request, for the function of a route pattern. */
+  readonly detail?: ((req: IncomingMessage) => unknown) | undefined;
+}
+/**
+ * This function gives a request handler that does each request of a route through `life.request`
+ * (S6 A12 and A13). The transport gives the lifecycle and `server_retry_after` through the context.
+ * - A route name takes a request whose method and path are that name, for example `POST /orders`.
+ *   A function gives the name of a route or of a pattern, or null for a request of another handler.
+ * - Before the start of the transport, each request gets a retryable 503.
+ * - The response is unary, or a stream with the option `stream`, as `writeOutcome` writes it.
+ */
+export declare const handle: <T>(controller: string, route: HandledRoute, work: HandledWork<T>, options?: HandleOptions<T>) => RequestHandler;
+//#endregion
+export type { HandleOptions, HandledRoute, HandledWork, HealthSource, HttpKnobs, HttpTransport, HttpTransportKnobs, HttpTransportOptions, MountContext, MountOptions, MountStage, OutcomeOptions, OutcomeResponse, ProbeHandlerOptions, ProbeResponse, ProbeServer, ProbeServerOptions, RequestHandler, ResponsePart, StreamFormat, UpgradeHandler, UpgradeMatch, UpgradeSocket };
+//# sourceMappingURL=http.d.ts.map