@mark1russell7/service 0.4.1 → 0.5.1

package/build/builder-QVxu1WcL.d.ts

@@ -0,0 +1,204 @@
+import { n as Clock } from "./clock-D-38uH_z.js";
+import { B as Gate, 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, d as TransportImpl, k as Trace, n as HealthServer, nt as OperationOf, o as PhaseWork, pt as ProcessTrigger, r as Lifecycle, s as RunOptions, st as ExitTrigger, t as DependencyHandle, x as Health, xt as Operation } from "./lifecycle-DtJZW09J.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+//#region src/profiles.d.ts
+/**
+ * A profile is a part of a declaration as data: policies, phases and the rules of the shutdown.
+ * `svc.profile(profile)` declares each field, as its method does. The runtime has no defaults, and
+ * a profile is not a default, because the caller gives it. The caller can change each field with a
+ * spread. `describe()` then shows the values of the profile.
+ *
+ *     svc.profile({ ...kubernetes({ grace: s(60), preStop: s(5) }), onRepeatSignal: "exit" });
+ */
+interface Profile {
+  readonly readiness?: Timing | undefined;
+  readonly liveness?: Timing | undefined;
+  readonly startup?: Quantity | undefined;
+  readonly couplings?: readonly Coupling[] | undefined;
+  /** These are the phases of the shutdown, in their sequence. */
+  readonly phases?: readonly Phase[] | undefined;
+  readonly cooperativeWindow?: Extent | undefined;
+  readonly cooperativeFloor?: CooperativeFloor | undefined;
+  readonly onRepeatSignal?: RepeatSignal | undefined;
+  readonly triggers?: readonly ProcessTrigger[] | undefined;
+  /** These messages of the IPC channel start the shutdown, as `svc.trigger("ipc-message", message)` declares each one. */
+  readonly messages?: readonly MessageTrigger[] | undefined;
+  readonly exitCodes?: ExitCodes | undefined;
+}
+/**
+ * This profile is for a service on the computer of a developer. No load balancer routes to it,
+ * thus it has no readiness hold. Its caps sum to 10 s, and a second signal exits at once. It
+ * declares no checks, thus the caller declares readiness, liveness and the startup budget.
+ */
+declare const localDev: Profile;
+/**
+ * This profile is for a background host on the computer of a developer, under a supervisor or a
+ * command that stops it. It has the caps of `localDev`. A repeat signal has no effect, thus the
+ * host ends its drain. It has no process trigger: a background host has no parent on stdin.
+ */
+declare const daemon: Profile;
+/**
+ * This profile is for a small process: a command that runs one time, or a child process on stdio.
+ * It has no checks and no probes, and its policies gate nothing. The cooperative abort occurs at the
+ * start of the drain, thus a first Ctrl-C stops the work at once. A second signal exits at once.
+ * The exit codes tell the shell how the process stopped: 130 for SIGINT, 143 for SIGTERM and 131
+ * for SIGQUIT. A stdio child also declares `triggers: ["stdin-close"]`.
+ */
+declare const ephemeral: Profile;
+/** These are the settings of a pod that the profile `kubernetes` derives its caps from. */
+interface PodTiming {
+  /** This time is `terminationGracePeriodSeconds`: from the deletion of the pod to SIGKILL. */
+  readonly grace: Quantity;
+  /** This time is the preStop sleep, or 0 for no preStop hook. SIGTERM comes after it. */
+  readonly preStop: Quantity;
+}
+/**
+ * This function gives the profile of a pod in Kubernetes. The budget is the grace less the preStop
+ * sleep: the time from SIGTERM to SIGKILL. Each stage gets a part of the budget, rounded down to
+ * the millisecond.
+ * - The parts in thirtieths are 2, 5, 15, 2, 1, 2 and 1, in the sequence of the stages. Thus 2
+ *   thirtieths of the budget stay as a margin before SIGKILL.
+ * - The cooperative window is 5 thirtieths of the budget.
+ * - The kubelet sends SIGTERM one time, thus a repeat signal has no effect.
+ *
+ * At the defaults of Kubernetes (a grace of 30 s and no preStop hook), the caps are 2, 5, 15, 2, 1,
+ * 2 and 1 s. Thus the sum of the caps and the preStop sleep fits in the grace (O10). The window is
+ * shorter than the drain, which is shorter than the budget (O16).
+ */
+declare const kubernetes: (pod: PodTiming) => Profile;
+//#endregion
+//#region src/watchdog.d.ts
+/**
+ * A watchdog spec declares a watchdog of the event loop. The service declares it as a check whose
+ * function the watchdog gives: the process's own wedge, which a liveness window reads.
+ */
+interface WatchdogSpec {
+  readonly name: string;
+  /** This time is the interval of the tick of the watchdog. */
+  readonly tick: Quantity;
+  /** This time is the most that a tick can be late before the loop counts as blocked. */
+  readonly threshold: Quantity;
+  /** This gate is the policy that the check controls, or null for a check that only reports. */
+  readonly gates: Gate | null;
+  readonly poll: Poll;
+}
+/**
+ * A watchdog measures how late its own tick comes. A blocked event loop delays each timer, thus a
+ * tick that comes later than the threshold shows the block. Its states are `watching`, `blocked`
+ * and `stopped`.
+ */
+interface Watchdog {
+  /** This function is the check: it fails when a tick since the last poll came late, or the loop is still blocked. */
+  readonly check: () => Outcome;
+  /** This time is the most that a tick was late, in milliseconds, since the start. */
+  readonly worst: number;
+  readonly blocked: boolean;
+  stop(): void;
+}
+/** This function starts a watchdog on a clock. */
+declare const watchdog: (clock: Clock, spec: WatchdogSpec, trace?: Trace) => Watchdog;
+//#endregion
+//#region src/builder.d.ts
+/**
+ * A service is composed with plain method uses before it starts. The builder is imperative, and
+ * it holds static knowledge. The service does not use an `init` function that gives registrations.
+ *
+ *     const svc = service("app");
+ *     svc.dependency("weather", {
+ *       system: null,
+ *       knobs: { request_timeout },
+ *       operations: { "GET /v1/forecast": { idempotent: true } },
+ *     });
+ *     svc.controller("forecast").requires("weather").route("GET /api/forecast", { idempotent: true });
+ *     svc.check({ name: "weather.round-trip", dependency: "weather", … }, roundTrip);
+ *     svc.describe(); // the whole graph as data, with nothing started
+ *     const health = await svc.start();
+ *
+ * The graph has one source, thus its parts cannot disagree. A dependency or a check can join
+ * after the start. It starts tripped, and the export is partial. The runtime has no defaults of
+ * its own. Thus `describe()` refuses a service that does not declare a policy, its startup budget
+ * or its shutdown, and it tells which. The shutdown includes what a repeat signal does.
+ *
+ * `start()` starts only the health runtime. `run()` starts the whole lifecycle: the startup in its
+ * sequence, the exit signals, the capped phases of the shutdown, and the exit of the process.
+ */
+interface ControllerBuilder {
+  /** This method declares the dependencies that its routes need. The controller is ready only while they are ready. */
+  requires(...dependencies: string[]): ControllerBuilder;
+  /** This method declares a route that the controller serves, and if its callers can send it again. */
+  route(route: string, operation: Operation): ControllerBuilder;
+  /**
+   * This method declares a route pattern, the operations that its requests can be, and the function
+   * that picks the operation of each request. A pattern with one operation needs no function.
+   */
+  pattern(pattern: string, operations: Readonly<Record<string, Operation>>, operationOf?: OperationOf): ControllerBuilder;
+}
+/** A service builder composes a service, gives it as data, and starts it. */
+interface ServiceBuilder {
+  readonly name: string;
+  /** This method declares a dependency, and the handle that connects to it and closes it, if it has one. */
+  dependency(name: string, spec: Omit<Dependency, "name">, handle?: DependencyHandle): ServiceBuilder;
+  /** This method declares a server, and its implementation. `run()` needs the implementation. */
+  server(name: string, knobs: Readonly<Record<string, Extent>>, impl?: TransportImpl): ServiceBuilder;
+  consumer(name: string, knobs: Readonly<Record<string, Extent>>, impl?: TransportImpl): ServiceBuilder;
+  worker(name: string, knobs: Readonly<Record<string, Extent>>, impl?: TransportImpl): ServiceBuilder;
+  /** This method gives the server of the probes. It starts first and closes last. */
+  healthServer(server: HealthServer): ServiceBuilder;
+  /** This method adds work to a declared phase of the shutdown: the owner of the work registers it. */
+  onPhase(phase: string, work: PhaseWork): ServiceBuilder;
+  /** This method declares a watchdog of the event loop, as a check on the state of the process. */
+  watchdog(spec: WatchdogSpec): ServiceBuilder;
+  controller(name: string): ControllerBuilder;
+  /** This method declares a check, and the function that measures its step. `start()` needs the function. */
+  check(check: Check, run?: CheckFn): ServiceBuilder;
+  readiness(timing: Timing): ServiceBuilder;
+  liveness(timing: Timing): ServiceBuilder;
+  startup(budget: Quantity): ServiceBuilder;
+  couple(coupling: Coupling): ServiceBuilder;
+  phase(name: string, cap: Quantity): ServiceBuilder;
+  cooperativeWindow(window: Extent): ServiceBuilder;
+  /** This method declares the earliest time of the cooperative abort: half the cap of the drain, or no floor. */
+  cooperativeFloor(floor: CooperativeFloor): ServiceBuilder;
+  /** This method declares what an exit signal does while the shutdown runs: nothing, or an exit at once. */
+  onRepeatSignal(policy: RepeatSignal): ServiceBuilder;
+  /** This method declares process triggers that start the shutdown, in addition to the exit signals. */
+  trigger(...triggers: ProcessTrigger[]): ServiceBuilder;
+  /**
+   * This method declares a message of the IPC channel that starts the shutdown, as data. With `as`,
+   * the message is that exit signal: `svc.trigger("ipc-message", { match: "shutdown", as: "SIGTERM" })`.
+   */
+  trigger(trigger: "ipc-message", message: MessageTrigger): ServiceBuilder;
+  /** This method declares the exit code of a clean shutdown that a trigger starts, in place of 0. */
+  exitCode(trigger: ExitTrigger, code: number): ServiceBuilder;
+  /** This method declares each field of a profile, as the method of that field does. */
+  profile(profile: Profile): ServiceBuilder;
+  /** This method gives the service as data, and it starts nothing. */
+  describe(): ServiceDescription;
+  /**
+   * This method closes the composition, starts the health runtime, and gives it after one warm-up
+   * sweep of each check. A part that joins after it starts tripped, and it makes the export
+   * partial. A second use gives the same runtime.
+   */
+  start(options?: StartOptions): Promise<Health>;
+  /**
+   * This method starts the whole lifecycle and gives it when its startup ends: the service operates,
+   * or its startup failed and it shuts down. It refuses a declaration that it cannot start: a transport
+   * without its implementation, or a stage with work and no declared phase.
+   */
+  run(options?: RunOptions): Promise<Lifecycle>;
+  /**
+   * This value is the health runtime from the time that `start()` begins, or null before. Thus the
+   * probes can answer during the warm-up sweep: the startup probe fails until the sweep ends.
+   */
+  readonly health: Health | null;
+  /**
+   * This value is the lifecycle from the time that `run()` begins, or null before. Its request
+   * tracking operates while the transports start, before `run()` gives it.
+   */
+  readonly lifecycle: Lifecycle | null;
+}
+/** This function starts the composition of a service. */
+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-QVxu1WcL.d.ts.map

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-DtJZW09J.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