@mark1russell7/service 0.4.1 → 0.5.1

package/build/knobs-BxG-c7Zb.js

@@ -0,0 +1,39 @@
+import { convertible, valueIn } from "@mark1russell7/quantity";
+//#region src/knobs.ts
+/**
+* This function gives a time knob in milliseconds, or infinity for a time without a bound. The
+* runtime has no defaults, thus a knob that is absent throws. A knob that is not a time, or that is
+* less than zero, also throws.
+*/
+const millisecondsOf = (knobs, name, owner) => {
+	const amount = knobs[name];
+	if (amount === void 0) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);
+	if (!convertible(amount.unit, "s")) throw new Error(`the knob ${name} is not a time`);
+	if (amount.value === "infinite") return Number.POSITIVE_INFINITY;
+	const value = valueIn(amount, "ms");
+	if (!(value >= 0)) throw new Error(`the knob ${name} is less than zero`);
+	return value;
+};
+/** This function gives a time knob in milliseconds, and it throws for a time without a bound. */
+const boundedMillisecondsOf = (knobs, name, owner) => {
+	const value = millisecondsOf(knobs, name, owner);
+	if (!Number.isFinite(value)) throw new Error(`the knob ${name} of ${owner} has no bound: it needs a time`);
+	return value;
+};
+/**
+* This function gives a count knob (the unit `count`) as a whole number above zero, or infinity
+* for a count without a bound. A knob that is absent, not a count, or not a whole number above zero throws.
+*/
+const countOf = (knobs, name, owner) => {
+	const amount = knobs[name];
+	if (amount === void 0) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);
+	if (!convertible(amount.unit, "count")) throw new Error(`the knob ${name} is not a count`);
+	if (amount.value === "infinite") return Number.POSITIVE_INFINITY;
+	const value = valueIn(amount, "count");
+	if (!(Number.isInteger(value) && value >= 1)) throw new Error(`the knob ${name} is ${value}, not a whole number above zero`);
+	return value;
+};
+//#endregion
+export { countOf as n, millisecondsOf as r, boundedMillisecondsOf as t };
+
+//# sourceMappingURL=knobs-BxG-c7Zb.js.map

package/build/knobs-BxG-c7Zb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knobs-BxG-c7Zb.js","names":[],"sources":["../src/knobs.ts"],"sourcesContent":["import type { Extent } from \"@mark1russell7/quantity\";\nimport { convertible, valueIn } from \"@mark1russell7/quantity\";\n\n/** A knob record is the knobs of a part, by name. A knob that is absent is undefined. */\nexport type KnobRecord = Readonly<Record<string, Extent | undefined>>;\n\n/**\n * This function gives a time knob in milliseconds, or infinity for a time without a bound. The\n * runtime has no defaults, thus a knob that is absent throws. A knob that is not a time, or that is\n * less than zero, also throws.\n */\nexport const millisecondsOf = (knobs: KnobRecord, name: string, owner: string): number => {\n  const amount = knobs[name];\n  if (amount === undefined) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);\n  if (!convertible(amount.unit, \"s\")) throw new Error(`the knob ${name} is not a time`);\n  if (amount.value === \"infinite\") return Number.POSITIVE_INFINITY;\n  const value = valueIn(amount, \"ms\");\n  if (!(value >= 0)) throw new Error(`the knob ${name} is less than zero`);\n  return value;\n};\n\n/** This function gives a time knob in milliseconds, and it throws for a time without a bound. */\nexport const boundedMillisecondsOf = (knobs: KnobRecord, name: string, owner: string): number => {\n  const value = millisecondsOf(knobs, name, owner);\n  if (!Number.isFinite(value)) throw new Error(`the knob ${name} of ${owner} has no bound: it needs a time`);\n  return value;\n};\n\n/**\n * This function gives a count knob (the unit `count`) as a whole number above zero, or infinity\n * for a count without a bound. A knob that is absent, not a count, or not a whole number above zero throws.\n */\nexport const countOf = (knobs: KnobRecord, name: string, owner: string): number => {\n  const amount = knobs[name];\n  if (amount === undefined) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);\n  if (!convertible(amount.unit, \"count\")) throw new Error(`the knob ${name} is not a count`);\n  if (amount.value === \"infinite\") return Number.POSITIVE_INFINITY;\n  const value = valueIn(amount, \"count\");\n  if (!(Number.isInteger(value) && value >= 1)) throw new Error(`the knob ${name} is ${value}, not a whole number above zero`);\n  return value;\n};\n"],"mappings":";;;;;;;AAWA,MAAa,kBAAkB,OAAmB,MAAc,UAA0B;CACxF,MAAM,SAAS,MAAM;CACrB,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,GAAG,MAAM,kBAAkB,KAAK,qBAAqB;CAC/F,IAAI,CAAC,YAAY,OAAO,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,YAAY,KAAK,eAAe;CACpF,IAAI,OAAO,UAAU,YAAY,OAAO,OAAO;CAC/C,MAAM,QAAQ,QAAQ,QAAQ,IAAI;CAClC,IAAI,EAAE,SAAS,IAAI,MAAM,IAAI,MAAM,YAAY,KAAK,mBAAmB;CACvE,OAAO;AACT;;AAGA,MAAa,yBAAyB,OAAmB,MAAc,UAA0B;CAC/F,MAAM,QAAQ,eAAe,OAAO,MAAM,KAAK;CAC/C,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,MAAM,YAAY,KAAK,MAAM,MAAM,+BAA+B;CACzG,OAAO;AACT;;;;;AAMA,MAAa,WAAW,OAAmB,MAAc,UAA0B;CACjF,MAAM,SAAS,MAAM;CACrB,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,GAAG,MAAM,kBAAkB,KAAK,qBAAqB;CAC/F,IAAI,CAAC,YAAY,OAAO,MAAM,OAAO,GAAG,MAAM,IAAI,MAAM,YAAY,KAAK,gBAAgB;CACzF,IAAI,OAAO,UAAU,YAAY,OAAO,OAAO;CAC/C,MAAM,QAAQ,QAAQ,QAAQ,OAAO;CACrC,IAAI,EAAE,OAAO,UAAU,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,MAAM,YAAY,KAAK,MAAM,MAAM,gCAAgC;CAC3H,OAAO;AACT"}

package/build/{builder-DnfUDW9u.d.ts → lifecycle-DtJZW09J.d.ts}

@@ -1,5 +1,157 @@
 import { n as Clock } from "./clock-D-38uH_z.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
+//#region src/operation.d.ts
+/**
+ * This type tells if an operation can go again after a failure. It is a property of the
+ * operation, not of the dependency. One Redis client sends a GET, which is safe to send again. It
+ * also sends an INCR, which counts two times when it goes again after a timeout. Each operation
+ * declares its idempotency:
+ * - `true`: a second issue has the same effect. Examples are an HTTP GET or PUT, a SELECT, a
+ *   Redis GET or SET, and a write that the server removes when it is a copy.
+ * - `false`: the client does not send it again after it can have reached the server.
+ * - keyed: the server keeps a key for a window, as with an `Idempotency-Key` header, and it
+ *   ignores a copy in that window. A copy after the window is a second operation. Thus the
+ *   window is a timer, and it must be longer than all retries of the operation.
+ */
+type Idempotency = boolean | {
+  readonly key: string;
+  readonly window: Extent;
+};
+/** An operation is an endpoint that the service calls or serves, a command, or a query. */
+interface Operation {
+  readonly idempotent: Idempotency;
+}
+/**
+ * This function tells if an operation can go again `since` its first issue. An idempotent
+ * operation can always go again, and other operations cannot. A keyed operation can go again
+ * while the server keeps its key.
+ */
+declare const mayReissue: (operation: Operation, since: Quantity) => boolean;
+//#endregion
+//#region src/process.d.ts
+/** An exit signal is a signal that asks the process to stop: each one starts the shutdown. */
+type ExitSignal = "SIGINT" | "SIGTERM" | "SIGQUIT";
+/** These are the signals that the runtime handles. */
+declare const EXIT_SIGNALS: readonly ExitSignal[];
+/**
+ * A process trigger is an event of the process, other than a signal, that starts the shutdown. A
+ * declaration opts in to each one (`svc.trigger`):
+ * - `stdin-close`: the standard input ends or closes, as when the parent of a stdio child goes away.
+ *   The process must read its input, as a stdio transport does, or Node does not see the end.
+ * - `ipc-close`: the IPC channel to the parent process closes.
+ * - `ipc-message`: a message on the IPC channel matches a declared shape. Windows cannot give a
+ *   child a SIGTERM that the child can catch, thus a parent sends a message.
+ */
+type ProcessTrigger = "stdin-close" | "ipc-close" | "ipc-message";
+/** These are the process triggers that a declaration can opt in to. */
+declare const PROCESS_TRIGGERS: readonly ProcessTrigger[];
+/** An exit trigger is an event that starts the shutdown: an exit signal, or a declared process trigger. */
+type ExitTrigger = ExitSignal | ProcessTrigger;
+/** This function tells if a number is an exit code of a process: a whole number from 0 to 255. */
+declare const isExitCode: (code: number) => boolean;
+/** This function tells if a trigger is an exit signal. A repeat signal obeys `onRepeatSignal`. */
+declare const isExitSignal: (trigger: string) => trigger is ExitSignal;
+/**
+ * A message shape is a value of JSON that a message of the IPC channel can match. A string, a
+ * number, a boolean or null matches an equal message. An object matches a message that has each of
+ * its fields, and each value of the field matches. An array matches an array of the same length, item by item.
+ */
+type MessageShape = string | number | boolean | null | readonly MessageShape[] | {
+  readonly [field: string]: MessageShape;
+};
+/** This function tells if a value is a message shape: a value of JSON, with no function and no undefined. */
+declare const isMessageShape: (value: unknown) => value is MessageShape;
+/** This function tells if a message of the IPC channel matches a shape. */
+declare const matchesMessage: (shape: MessageShape, message: unknown) => boolean;
+/**
+ * A process port is the part of the process that the runtime uses: its exit triggers, its output
+ * and its exit. The runtime owns the handlers, because Node as PID 1 without a handler ignores
+ * SIGTERM. Only the runtime ends the process, and library code does not. A test gives a fake port,
+ * sends triggers, and reads the exit code.
+ */
+interface ProcessPort {
+  /**
+   * This method adds a handler for a trigger, and gives the function that removes it. The runtime
+   * asks for a process trigger only when the declaration opts in to it. For `ipc-message`, the
+   * handler gets each message of the IPC channel, and the runtime matches it.
+   */
+  on(trigger: ExitTrigger, handler: (message?: unknown) => void): () => void;
+  /**
+   * This method writes each buffered line of the output, and its promise ends when the output is
+   * written. The stage `flush the output` uses it, in the cap of that stage.
+   */
+  flush?(): Promise<void> | void;
+  /**
+   * This method keeps the process alive, and gives the function that releases it. The lifecycle
+   * holds its process from its start to its exit, as a listening socket does. Thus a process whose
+   * timers do not keep it alive does not end in the middle of its work. It keeps its teardown and its exit code.
+   */
+  hold?(): () => void;
+  /** This method ends the process with a code: the code of the exit request, 1 after an error, or 0. */
+  exit(code: number): void;
+}
+/** A host stream is the part of a stream of Node that the port uses. */
+interface HostStream {
+  readonly writable?: boolean;
+  readonly destroyed?: boolean;
+  readonly readableEnded?: boolean;
+  write(chunk: string, done: (error?: unknown) => void): boolean;
+  on(event: string, handler: () => void): unknown;
+  off(event: string, handler: () => void): unknown;
+}
+/** A process host is the part of the process of Node that the port uses. Its event `message` gives the message of the IPC channel. */
+interface ProcessHost {
+  on(signal: string, handler: (message?: unknown) => void): unknown;
+  off(signal: string, handler: (message?: unknown) => void): unknown;
+  exit(code: number): unknown;
+  readonly stdin?: HostStream | undefined;
+  readonly stdout?: HostStream | undefined;
+  readonly stderr?: HostStream | undefined;
+}
+/**
+ * This function makes a process port on a host. `find` gives the host at each use, or undefined
+ * when the platform has no process. Then the use throws.
+ */
+declare const processPortOf: (find: () => ProcessHost | undefined) => ProcessPort;
+/** This port is the process of Node. */
+declare const nodeProcess: ProcessPort;
+//#endregion
+//#region src/routes.d.ts
+/**
+ * A route pattern matches the routes of a controller that its exact routes do not name. A
+ * registry that changes while the service operates, for example a registry of procedures, thus
+ * needs no list of routes before the start. The syntax of a pattern:
+ * - `*` matches each text, also an empty text and a text with `/`. The pattern `*` alone matches
+ *   each route.
+ * - `:name` matches a text of one character or more without `/`, and gives it in `params.name`.
+ * - Each other character matches itself.
+ *
+ * The declaration names the operations that a request of the pattern can be. Each operation
+ * declares its idempotency, as a route does. A function picks the operation of each request.
+ */
+interface RoutePattern {
+  readonly pattern: string;
+  /** These are the operations that a request of the pattern can be, by name. */
+  readonly operations: Readonly<Record<string, Operation>>;
+}
+/** A route request is what the function of a pattern gets for one request. */
+interface RouteRequest {
+  readonly controller: string;
+  readonly route: string;
+  /** These are the texts of the `:name` parts of the pattern, by name. */
+  readonly params: Readonly<Record<string, string>>;
+  /** These are the texts of the `*` parts of the pattern, in their sequence. */
+  readonly wildcards: readonly string[];
+  /** This value is the detail that the transport gives with the request, or undefined. */
+  readonly detail: unknown;
+}
+/**
+ * An operation choice gives the name of the operation of one request: one of the operations that
+ * the pattern declares. Thus the function decides the idempotency of each request, and the
+ * declaration keeps each window of a keyed operation as data.
+ */
+type OperationOf = (request: RouteRequest) => string;
+//#endregion
 //#region src/timing.d.ts
 /**
  * All policies have the same timing shape. A timing is a count of polls (a debounce) or a
@@ -64,34 +216,6 @@ declare const asDebounce: (timing: Timing, poll: Poll) => Timing;
  */
 declare const heartbeatDetection: (interval: Extent, timeout: Quantity, misses: number) => Extent;
 //#endregion
-//#region src/operation.d.ts
-/**
- * This type tells if an operation can go again after a failure. It is a property of the
- * operation, not of the dependency. One Redis client sends a GET, which is safe to send again. It
- * also sends an INCR, which counts two times when it goes again after a timeout. Each operation
- * declares its idempotency:
- * - `true`: a second issue has the same effect. Examples are an HTTP GET or PUT, a SELECT, a
- *   Redis GET or SET, and a write that the server removes when it is a copy.
- * - `false`: the client does not send it again after it can have reached the server.
- * - keyed: the server keeps a key for a window, as with an `Idempotency-Key` header, and it
- *   ignores a copy in that window. A copy after the window is a second operation. Thus the
- *   window is a timer, and it must be longer than all retries of the operation.
- */
-type Idempotency = boolean | {
-  readonly key: string;
-  readonly window: Extent;
-};
-/** An operation is an endpoint that the service calls or serves, a command, or a query. */
-interface Operation {
-  readonly idempotent: Idempotency;
-}
-/**
- * This function tells if an operation can go again `since` its first issue. An idempotent
- * operation can always go again, and other operations cannot. A keyed operation can go again
- * while the server keeps its key.
- */
-declare const mayReissue: (operation: Operation, since: Quantity) => boolean;
-//#endregion
 //#region src/description.d.ts
 /**
  * This is the format of a service as data: what `describe()` exports, and nothing starts. The
@@ -152,6 +276,12 @@ interface Controller {
   readonly name: string;
   readonly requires: readonly string[];
   readonly routes: Readonly<Record<string, Operation>>;
+  /**
+   * These patterns match the routes that `routes` does not name, in their sequence: the first
+   * pattern that matches a route gives its operations. Without a declaration, the controller has
+   * no patterns.
+   */
+  readonly patterns?: readonly RoutePattern[] | undefined;
 }
 /** A coupling is a declared edge between two policies. The algebra checks its margin. */
 interface Coupling {
@@ -164,6 +294,31 @@ interface Phase {
   readonly name: string;
   readonly cap: Quantity;
 }
+/**
+ * A repeat signal policy tells what an exit signal does while the shutdown runs:
+ * - `ignore`: the signal has no effect, and the shutdown continues.
+ * - `exit`: the process exits with the code 1 at once, as a second Ctrl-C does in a terminal.
+ */
+type RepeatSignal = "ignore" | "exit";
+/**
+ * A cooperative floor is the earliest time of the cooperative abort in the drain:
+ * - `half`: half the cap of the drain. The work in flight gets half the drain at the least.
+ * - `none`: no floor. A window of the whole cap or more aborts the work at the start of the drain.
+ */
+type CooperativeFloor = "half" | "none";
+/** These exit codes replace the code 0 of a clean shutdown, by the trigger of the shutdown. */
+type ExitCodes = Readonly<Partial<Record<ExitTrigger, number>>>;
+/**
+ * A message trigger is a message of the IPC channel that starts the shutdown, for the trigger
+ * `ipc-message`. With `as`, the message is that exit signal: it has its exit code and the policy of a
+ * repeat signal. Without `as`, the message is the trigger `ipc-message`.
+ */
+interface MessageTrigger {
+  /** This shape is the message that starts the shutdown, for example `"shutdown"`. */
+  readonly match: MessageShape;
+  /** This signal is the exit signal that the message replaces, for example `SIGTERM` on Windows. */
+  readonly as?: ExitSignal | undefined;
+}
 /** A service description is the whole graph of a service, as data. */
 interface ServiceDescription {
   readonly format: typeof FORMAT;
@@ -185,6 +340,16 @@ interface ServiceDescription {
     readonly phases: readonly Phase[];
     /** This window is how long before the end of the drain the cooperative abort occurs, or no bound. */
     readonly cooperativeWindow: Extent;
+    /** This floor is the earliest time of the cooperative abort. Without a declaration, the floor is `half`. */
+    readonly cooperativeFloor?: CooperativeFloor | undefined;
+    /** This policy tells what a signal does while the shutdown runs. Each declaration gives it, because the runtime has no defaults. */
+    readonly onRepeatSignal: RepeatSignal;
+    /** These triggers start the shutdown, in addition to the exit signals. Each one is opt-in. */
+    readonly triggers?: readonly ProcessTrigger[] | undefined;
+    /** These messages of the IPC channel start the shutdown. The trigger `ipc-message` needs one at the least. */
+    readonly messages?: readonly MessageTrigger[] | undefined;
+    /** These codes replace the exit code 0 by the trigger. Without a code, a clean shutdown exits 0. */
+    readonly exitCodes?: ExitCodes | undefined;
   };
 }
 //#endregion
@@ -330,57 +495,70 @@ interface Health {
   stop(): void;
 }
 //#endregion
-//#region src/process.d.ts
-/** An exit signal is a signal that asks the process to stop: each one starts the shutdown. */
-type ExitSignal = "SIGINT" | "SIGTERM" | "SIGQUIT";
-/** These are the signals that the runtime handles. */
-declare const EXIT_SIGNALS: readonly ExitSignal[];
-/**
- * A process port is the part of the process that the runtime uses: its exit signals and its exit.
- * The runtime owns the handlers, because Node as PID 1 without a handler ignores SIGTERM. Only the
- * runtime ends the process, and library code does not. A test gives a fake port, sends signals,
- * and reads the exit code.
- */
-interface ProcessPort {
-  /** This method adds a handler for a signal, and gives the function that removes it. */
-  on(signal: ExitSignal, handler: () => void): () => void;
-  /** This method ends the process with a code: 0 after a clean shutdown, and 1 after an error. */
-  exit(code: number): void;
-}
-/** This port is the process of Node. */
-declare const nodeProcess: ProcessPort;
-//#endregion
 //#region src/requests.d.ts
 /**
- * A request outcome is what a request of a controller came to, for any HTTP framework or none:
- * - `done`: the work gave a value.
- * - `failed`: the work failed for a cause of its own. The adapter answers it as it answers any
- *   error of the route.
+ * A request end is the one final result of the stream of a request. Its count `delivered` is the
+ * number of items that the stream gave before it. An end after the first item is in-band. The
+ * transport sent its answer, thus it writes the end as the last line of the stream, not as a status.
+ * - `done`: the work gave each of its items.
+ * - `failed`: the work failed for a cause of its own. Before the first item, the adapter answers it
+ *   as it answers any error of the route.
  * - `refused`: the service did not admit the request. A refused request did not start, thus its
  *   caller can send it again: 503, retryable.
- * - `cut`: the shutdown stopped the request. A route whose callers can send it again answers 503,
- *   retryable. Each other route answers 500, not retryable, because the work can have had its
- *   effect.
+ * - `cut`: the shutdown stopped the request. Before the first item, a route whose callers can send
+ *   it again answers 503, retryable, and each other route answers 500. After the first item, the
+ *   status is null, and the end is in-band.
  */
-type RequestOutcome<T> = {
+type RequestEnd = {
   readonly kind: "done";
-  readonly value: T;
+  readonly delivered: number;
 } | {
   readonly kind: "failed";
   readonly error: unknown;
+  readonly delivered: number;
 } | {
   readonly kind: "refused";
   readonly status: 503;
   readonly retryable: true;
   readonly cause: string;
+  readonly delivered: 0;
 } | {
   readonly kind: "cut";
-  readonly status: 503 | 500;
+  readonly status: 503 | 500 | null;
   readonly retryable: boolean;
   readonly cause: string;
+  readonly delivered: number;
 };
+/** A request event is one event of the stream of a request: an item, or the one end, which comes last. */
+type RequestEvent<T> = {
+  readonly kind: "item";
+  readonly value: T;
+} | RequestEnd;
+/**
+ * A request stream is what a request comes to: its items, then one end. A unary work gives a stream
+ * of one item. The stream gives an item only when its reader asks for the next event. Thus a slow
+ * reader slows the work, and the request stays in flight until the work ends. When the reader
+ * stops before the end, the work gets its abort and the `return()` of its iterator.
+ */
+interface RequestStream<T> extends AsyncIterable<RequestEvent<T>> {
+  /** This method reads the whole stream, and gives its items and its end. */
+  collect(): Promise<{
+    readonly items: readonly T[];
+    readonly end: RequestEnd;
+  }>;
+}
+/**
+ * A request work is what a request function gives: one value, or a stream of values. A work that
+ * gives an async iterable is a stream, also through a promise. Each other value is a stream of one.
+ */
+type RequestWork<T> = T | PromiseLike<T> | AsyncIterable<T> | PromiseLike<AsyncIterable<T>>;
 /** A request function does the work of one request. It receives a signal that the shutdown aborts. */
-type RequestFn<T> = (signal: AbortSignal) => Promise<T> | T;
+type RequestFn<T> = (signal: AbortSignal) => RequestWork<T>;
+/** These options go with one request. */
+interface RequestOptions {
+  /** This value goes to the function of a route pattern, for example the metadata of a procedure. */
+  readonly detail?: unknown;
+}
 //#endregion
 //#region src/lifecycle.d.ts
 /**
@@ -389,7 +567,13 @@ type RequestFn<T> = (signal: AbortSignal) => Promise<T> | T;
  * and it closes. A second close has no effect.
  */
 interface TransportImpl {
-  start(signal: AbortSignal): Promise<void> | void;
+  /**
+   * This method starts the transport. The lifecycle is the object that `run()` gives at the end of
+   * the startup. Its request tracking operates from the start: a request before the startup ends
+   * gets a retryable refusal, and `keepAlive()` is false. Do not wait for `life.started` here,
+   * because the startup waits for this method.
+   */
+  start(signal: AbortSignal, life: Lifecycle): Promise<void> | void;
   stopIntake(): Promise<void> | void;
   /**
    * This method lets the work in flight end until `deadline` (milliseconds on the monotonic
@@ -434,22 +618,32 @@ type PhaseWork = (context: PhaseContext) => Promise<void> | void;
  * - `close transports`: each transport closes.
  * - `stop the poller`: each check and watchdog stops. Then the signal of the service aborts.
  * - `tear down dependencies`: each dependency closes, in the reverse sequence of its connection.
- * - `close the health server`: the probes stop last.
+ * - `close the health server`: the probes stop.
+ * - `flush the output`: the work of the owners of this phase ends, and then the process port
+ *   writes the buffered output. Without this phase, the process exits without a wait.
  */
-declare const STAGES: readonly ["fail readiness", "stop intake", "drain", "close transports", "stop the poller", "tear down dependencies", "close the health server"];
+declare const STAGES: readonly ["fail readiness", "stop intake", "drain", "close transports", "stop the poller", "tear down dependencies", "close the health server", "flush the output"];
 type Stage = (typeof STAGES)[number];
 /** This function gives the place of a stage in the sequence, or -1 for a phase of another name. */
 declare const stageRank: (name: string) => number;
 /**
  * This function gives the time of the cooperative abort, in milliseconds after the drain starts. It
- * is the cap less the cooperative window, and not less than half the cap. A window without a bound
- * gives half the cap.
+ * is the cap less the cooperative window. With the floor `half`, it is not less than half the cap,
+ * and a window without a bound gives half the cap. With the floor `none`, it is not less than 0.
  */
-declare const cooperativeAbortAt: (cap: number, window: Extent) => number;
+declare const cooperativeAbortAt: (cap: number, window: Extent, floor?: CooperativeFloor) => number;
 /** These options run the lifecycle. Without them, it uses the real clock and the process of Node. */
 interface RunOptions extends StartOptions {
   readonly process?: ProcessPort | undefined;
 }
+/** These options go with a request for the shutdown. */
+interface ShutdownOptions {
+  /**
+   * This code is the exit code that the work of the process gives, a whole number from 0 to 255. The
+   * first exit request with a code sets it. A code of 0 lets an error make the exit code 1.
+   */
+  readonly code?: number | undefined;
+}
 /** A lifecycle state tells where the service is in its life. */
 type LifecycleState = "starting" | "running" | "draining" | "exited";
 /** The lifecycle of a running service. */
@@ -458,7 +652,7 @@ interface Lifecycle {
   readonly state: LifecycleState;
   /** This code is the exit code, or null before the exit. */
   readonly exitCode: number | null;
-  /** These texts are the errors that make the exit code 1. */
+  /** These texts are the errors of the lifecycle. An error makes the exit code 1, unless an exit request gives another code. */
   readonly errors: readonly string[];
   /** This promise ends when the startup ends: the service runs, or its startup failed. */
   readonly started: Promise<void>;
@@ -466,13 +660,18 @@ interface Lifecycle {
   readonly done: Promise<number>;
   /** This signal aborts after the poller stops: the background work of the service stops with it. */
   readonly signal: AbortSignal;
-  /** This method asks for the shutdown, as an exit signal does. A second request has no effect. */
-  shutdown(cause?: string): Promise<number>;
   /**
-   * This method does one request of a controller, on a route that the controller declares. The
-   * service refuses it while it cannot take new work, and the shutdown can cut it.
+   * This method asks for the shutdown, as an exit signal does. A second request does not start a
+   * second shutdown. It can give the exit code, when no request gave one before.
+   */
+  shutdown(cause?: string, options?: ShutdownOptions): Promise<number>;
+  /**
+   * This method does one request of a controller, on a route or a route pattern that the controller
+   * declares. It gives the stream of the request: each item of the work, then one end. The service
+   * refuses the request while it cannot take new work, and the shutdown can cut it. An undeclared
+   * route throws, because it has no idempotency.
    */
-  request<T>(controller: string, route: string, work: RequestFn<T>): Promise<RequestOutcome<T>>;
+  request<T>(controller: string, route: string, work: RequestFn<T>, options?: RequestOptions): RequestStream<T>;
   inFlight(controller?: string): number;
   /**
    * This method tells if a response can keep its connection open. It is false while the service is
@@ -481,113 +680,5 @@ interface Lifecycle {
   keepAlive(): boolean;
 }
 //#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.
- *
- * `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;
-}
-/** 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 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 function starts the composition of a service. */
-declare const service: (name: string) => ServiceBuilder;
-//#endregion
-export { Timing as $, StartOptions as A, Dependency as B, ProcessPort as C, HealthVerdict as D, Health as E, MachineName as F, Step as G, Gate as H, Recorder as I, Operation as J, Transport as K, Check as L, Outcome as M, Result as N, ProbeAnswer as O, LifecycleEvent as P, Span as Q, Controller as R, ExitSignal as S, CheckVerdict as T, Phase as U, FORMAT as V, ServiceDescription as W, FailsBy as X, mayReissue as Y, Poll as Z, cooperativeAbortAt as _, WatchdogSpec as a, RequestOutcome as b, HealthServer as c, PhaseContext as d, asDebounce as et, PhaseWork as f, TransportImpl as g, Stage as h, Watchdog as i, recoverSpan as it, CheckFn as j, ProbeKind as k, Lifecycle as l, STAGES as m, ServiceBuilder as n, failSpan as nt, watchdog as o, RunOptions as p, Idempotency as q, service as r, heartbeatDetection as rt, DependencyHandle as s, ControllerBuilder as t, asWindow as tt, LifecycleState as u, stageRank as v, nodeProcess as w, EXIT_SIGNALS as x, RequestFn as y, Coupling as z };
-//# sourceMappingURL=builder-DnfUDW9u.d.ts.map
+export { failSpan as $, LifecycleEvent as A, Gate as B, ProbeAnswer as C, Outcome as D, CheckFn as E, CooperativeFloor as F, Step as G, Phase as H, Coupling as I, Poll as J, Transport as K, Dependency as L, Recorder as M, Check as N, Result as O, Controller as P, asWindow as Q, ExitCodes as R, HealthVerdict as S, mayReissue as St, StartOptions as T, RepeatSignal as U, MessageTrigger as V, ServiceDescription as W, Timing as X, Span as Y, asDebounce as Z, RequestOptions as _, matchesMessage as _t, PhaseContext as a, EXIT_SIGNALS as at, CheckVerdict as b, Idempotency as bt, STAGES as c, HostStream as ct, TransportImpl as d, ProcessHost as dt, heartbeatDetection as et, cooperativeAbortAt as f, ProcessPort as ft, RequestFn as g, isMessageShape as gt, RequestEvent as h, isExitSignal as ht, LifecycleState as i, RouteRequest as it, MachineName as j, Trace as k, ShutdownOptions as l, MessageShape as lt, RequestEnd as m, isExitCode as mt, HealthServer as n, OperationOf as nt, PhaseWork as o, ExitSignal as ot, stageRank as p, ProcessTrigger as pt, FailsBy as q, Lifecycle as r, RoutePattern as rt, RunOptions as s, ExitTrigger as st, DependencyHandle as t, recoverSpan as tt, Stage as u, PROCESS_TRIGGERS as ut, RequestStream as v, nodeProcess as vt, ProbeKind as w, Health as x, Operation as xt, RequestWork as y, processPortOf as yt, FORMAT as z };
+//# sourceMappingURL=lifecycle-DtJZW09J.d.ts.map

package/build/redis.d.ts

@@ -1,6 +1,7 @@
 import { t as Backoff } from "./backoff-B-jGWVDm.js";
 import { n as Clock } from "./clock-D-38uH_z.js";
-import { B as Dependency, G as Step, H as Gate, I as Recorder, J as Operation, L as Check, W as ServiceDescription, Z as Poll, j as CheckFn, n as ServiceBuilder, rt as heartbeatDetection, s as DependencyHandle } from "./builder-DnfUDW9u.js";
+import { B as Gate, E as CheckFn, G as Step, J as Poll, L as Dependency, M as Recorder, N as Check, W as ServiceDescription, et as heartbeatDetection, t as DependencyHandle, xt as Operation } from "./lifecycle-DtJZW09J.js";
+import { n as ServiceBuilder } from "./builder-QVxu1WcL.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
 import { Machine } from "@mark1russell7/algebra";
 //#region src/redis/connection.d.ts