@mark1russell7/service 0.4.0 → 0.5.0

package/build/testing.d.ts

@@ -1,5 +1,6 @@
 import { n as Clock } from "./clock-D-38uH_z.js";
-import { C as ProcessPort, M as Outcome, S as ExitSignal, j as CheckFn, n as ServiceBuilder } from "./builder-DnfUDW9u.js";
+import { D as Outcome, E as CheckFn, at as ExitSignal, d as TransportImpl, ot as ExitTrigger, r as Lifecycle, ut as ProcessPort } from "./lifecycle-DIj4YGmO.js";
+import { n as ServiceBuilder } from "./builder-B_q-JeW8.js";
 //#region src/fakes.d.ts
 /** A fake clock moves only when a test tells it to. */
 interface FakeClock extends Clock {
@@ -15,17 +16,32 @@ interface FakeClock extends Clock {
 }
 /** This function makes a fake clock. Its time starts at `start` milliseconds. */
 export declare const fakeClock: (start?: number) => FakeClock;
-/** A fake process receives signals from a test, and keeps each exit code in place of an exit. */
+/** A fake process receives triggers from a test, and keeps each exit code in place of an exit. */
 interface FakeProcess extends ProcessPort {
   /** This method sends a signal to each handler of it. */
   signal(name: ExitSignal): void;
+  /** This method sends a trigger to each handler of it: a signal, or a process trigger, for example `stdin-close`. */
+  trigger(name: ExitTrigger): void;
   /** These are the exit codes, in sequence. A correct runtime exits one time. */
   readonly exits: readonly number[];
   /** This count is the number of handlers that are registered. */
   readonly handlers: number;
+  /** These are the triggers that have a handler, in the sequence of their first handler. */
+  readonly triggers: readonly ExitTrigger[];
+  /** These are the times of the clock of the options at each flush and each exit, when the options give a clock. */
+  readonly log: readonly string[];
+  /** This count is the number of flushes of the output. */
+  readonly flushes: number;
+}
+/** These options shape a fake process. */
+interface FakeProcessOptions {
+  /** This function is the flush of the output, for example a wait on a fake clock. Without it, a flush ends at once. */
+  readonly flush?: (() => Promise<void> | void) | undefined;
+  /** This clock stamps each line of the log. */
+  readonly clock?: Clock | undefined;
 }
 /** This function makes a fake process. */
-export declare const fakeProcess: () => FakeProcess;
+export declare const fakeProcess: (options?: FakeProcessOptions) => FakeProcess;
 /** This function gives a seeded random number generator (mulberry32), with numbers in [0, 1). */
 export declare const seeded: (seed: number) => (() => number);
 //#endregion
@@ -58,6 +74,78 @@ interface ContractOptions {
  */
 export declare const contractCases: (declare: () => ServiceBuilder, options?: ContractOptions) => ContractCase[];
 //#endregion
+//#region src/conformance.d.ts
+/** A held work is one unit of work that stays in flight until the test releases it. */
+interface HeldWork {
+  /** This method lets the work end. Its promise ends when the caller of the work has its answer, or its error. */
+  release(): Promise<void>;
+  /** This flag tells if the work got the cooperative abort of the drain. */
+  readonly aborted: boolean;
+}
+/**
+ * A transport subject is a transport and the client side of its work. The kit offers work through
+ * it, holds work in flight through it, and reads the count of the transport.
+ */
+interface TransportSubject {
+  readonly impl: TransportImpl;
+  /** This lifecycle goes to `start()`. Without it, the kit gives a detached lifecycle. */
+  readonly life?: Lifecycle | undefined;
+  /** This method offers one unit of new work. It gives true when the transport took it, and false when it refused it. */
+  offer(): Promise<boolean>;
+  /** This method starts one unit of work that stays in flight until its release. The promise ends when the transport has it. */
+  hold(): Promise<HeldWork>;
+  /** This method frees what the subject holds outside the transport: its clients and their sockets. */
+  dispose?(): Promise<void> | void;
+}
+/**
+ * This function gives a detached lifecycle: a lifecycle with no service, for the start of a
+ * transport in a test. Its state is `running`, it keeps each connection, and nothing is in flight. Each request
+ * and each use of its health throws, because no service declares a route.
+ */
+export declare const detachedLifecycle: () => Lifecycle;
+/** A subject factory makes a new subject for each case, on the clock of the case. */
+type SubjectFactory = (clock: Clock) => TransportSubject | Promise<TransportSubject>;
+/** A conformance record is one measurement of a case, for the raw records of a run in CI. */
+interface ConformanceRecord {
+  readonly case: string;
+  readonly what: string;
+  /** This time is the limit of the contract, in milliseconds. */
+  readonly expected: number;
+  /** This time is what the case measured, in milliseconds of the real clock. */
+  readonly measured: number;
+}
+/** These options tune the conformance kit. */
+interface ConformanceOptions {
+  /** This name goes before the name of each case. */
+  readonly name?: string | undefined;
+  /** This clock moves the cases: `fake` gives exact and fast cases, and `real` measures the timing. The default is `fake`. */
+  readonly clock?: "fake" | "real" | undefined;
+  /** This time is the cap of each drain of the cases, in milliseconds. The default is 1000. */
+  readonly cap?: number | undefined;
+  /** This time is the most that a close can take, in milliseconds of the real clock. The default is 1000. */
+  readonly closeBound?: number | undefined;
+  /** This time is the most that an event can take to reach the transport, in real milliseconds. The default is 100. */
+  readonly slack?: number | undefined;
+  /** False tells that the work of the transport cannot see the cooperative abort. The default is true. */
+  readonly cooperative?: boolean | undefined;
+  /** This count is the number of works that the count case holds. The default is 3. */
+  readonly holds?: number | undefined;
+  /** This function receives each measurement, for the raw records of a run. */
+  readonly record?: ((record: ConformanceRecord) => void) | undefined;
+}
+/**
+ * This function generates the conformance cases of a transport (S6 A9). `make` gives a new subject
+ * for each case. Each case throws on a failure, and its message names the part of the contract.
+ * - The start: nothing is in flight, and the transport takes work.
+ * - The count: it follows each work from its events, with no move of the clock.
+ * - `stopIntake` refuses new work, keeps the work in flight, and a second stop has no effect.
+ * - `drain` ends at once with no work, ends with the last work, and holds to its deadline and not
+ *   past it. It gives the cooperative abort to the work, and it does not throw.
+ * - `close` ends the work in flight in its bound, and a second close has no effect.
+ * - The stages in their sequence, as the lifecycle does them.
+ */
+export declare const transportConformance: (make: SubjectFactory, options?: ConformanceOptions) => ContractCase[];
+//#endregion
 //#region src/testing.d.ts
 /**
  * A behavior is what a scripted check does when the runtime starts it:
@@ -99,5 +187,5 @@ export interface QuietServer {
  */
 export declare const quietServer: () => Promise<QuietServer>;
 //#endregion
-export type { ContractCase, ContractOptions, FakeClock, FakeProcess };
+export type { ConformanceOptions, ConformanceRecord, ContractCase, ContractOptions, FakeClock, FakeProcess, FakeProcessOptions, HeldWork, SubjectFactory, TransportSubject };
 //# sourceMappingURL=testing.d.ts.map

package/build/testing.js

@@ -1,3 +1,4 @@
+import { realClock } from "./clock.js";
 import { a as recoverSpan, r as failSpan } from "./timing-DGRi3XCI.js";
 import { valueIn } from "@mark1russell7/quantity";
 import { createServer } from "node:net";
@@ -54,24 +55,38 @@ const fakeClock = (start = 0) => {
 	};
 };
 /** This function makes a fake process. */
-const fakeProcess = () => {
+const fakeProcess = (options = {}) => {
 	const handlers = /* @__PURE__ */ new Map();
 	const exits = [];
+	const log = [];
+	let flushes = 0;
+	const stamp = (what) => {
+		log.push(options.clock === void 0 ? what : `${options.clock.now()} ${what}`);
+	};
+	const send = (name) => {
+		for (const handler of [...handlers.get(name) ?? []]) handler();
+	};
 	return {
-		on(signal, handler) {
-			const set = handlers.get(signal) ?? /* @__PURE__ */ new Set();
+		on(trigger, handler) {
+			const set = handlers.get(trigger) ?? /* @__PURE__ */ new Set();
 			set.add(handler);
-			handlers.set(signal, set);
+			handlers.set(trigger, set);
 			return () => {
 				set.delete(handler);
 			};
 		},
+		async flush() {
+			stamp("flush");
+			await options.flush?.();
+			flushes += 1;
+			stamp("flushed");
+		},
 		exit(code) {
+			stamp(`exit ${code}`);
 			exits.push(code);
 		},
-		signal(name) {
-			for (const handler of [...handlers.get(name) ?? []]) handler();
-		},
+		signal: send,
+		trigger: send,
 		get exits() {
 			return [...exits];
 		},
@@ -79,6 +94,15 @@ const fakeProcess = () => {
 			let count = 0;
 			for (const set of handlers.values()) count += set.size;
 			return count;
+		},
+		get triggers() {
+			return [...handlers.keys()];
+		},
+		get log() {
+			return [...log];
+		},
+		get flushes() {
+			return flushes;
 		}
 	};
 };
@@ -273,6 +297,276 @@ const contractCases = (declare, options = {}) => {
 	return cases;
 };
 //#endregion
+//#region src/conformance.ts
+/**
+* This function gives a detached lifecycle: a lifecycle with no service, for the start of a
+* transport in a test. Its state is `running`, it keeps each connection, and nothing is in flight. Each request
+* and each use of its health throws, because no service declares a route.
+*/
+const detachedLifecycle = () => {
+	const none = () => {
+		throw new Error("a detached lifecycle has no service: give the transport the lifecycle of a service");
+	};
+	return {
+		health: {
+			verdict: none,
+			probe: none,
+			subscribe: none,
+			forceFail: none,
+			drain: none,
+			stop: none
+		},
+		state: "running",
+		exitCode: null,
+		errors: [],
+		started: Promise.resolve(),
+		done: new Promise(() => {}),
+		signal: new AbortController().signal,
+		shutdown: none,
+		request: none,
+		inFlight: () => 0,
+		keepAlive: () => true
+	};
+};
+const realNow = () => performance.now();
+const turn = () => new Promise((resolve) => setTimeout(resolve, 0));
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** This function waits on the real clock, until the test is true or the bound ends. It gives the test at the end. */
+const within = async (bound, test) => {
+	const end = realNow() + bound;
+	for (;;) {
+		if (test()) return true;
+		if (realNow() > end) return test();
+		await turn();
+	}
+};
+/** This function lets the events that are ready reach the transport, with no move of the clock of the case. */
+const quiet = async () => {
+	for (let at = 0; at < 8; at += 1) await turn();
+};
+/** This function uses a method of the transport, and gives a throw of the method as a rejection. */
+const attempt = (call) => {
+	try {
+		return Promise.resolve(call());
+	} catch (error) {
+		return Promise.reject(error);
+	}
+};
+const track = (promise) => {
+	const state = {
+		settled: false,
+		error: void 0,
+		failed: false
+	};
+	promise.then(() => {
+		state.settled = true;
+	}, (error) => {
+		state.settled = true;
+		state.failed = true;
+		state.error = error;
+	});
+	return state;
+};
+/**
+* This function generates the conformance cases of a transport (S6 A9). `make` gives a new subject
+* for each case. Each case throws on a failure, and its message names the part of the contract.
+* - The start: nothing is in flight, and the transport takes work.
+* - The count: it follows each work from its events, with no move of the clock.
+* - `stopIntake` refuses new work, keeps the work in flight, and a second stop has no effect.
+* - `drain` ends at once with no work, ends with the last work, and holds to its deadline and not
+*   past it. It gives the cooperative abort to the work, and it does not throw.
+* - `close` ends the work in flight in its bound, and a second close has no effect.
+* - The stages in their sequence, as the lifecycle does them.
+*/
+const transportConformance = (make, options = {}) => {
+	const name = options.name ?? "transport";
+	const fake = (options.clock ?? "fake") === "fake";
+	const cap = options.cap ?? 1e3;
+	const closeBound = options.closeBound ?? 1e3;
+	const slack = options.slack ?? 100;
+	const cooperative = options.cooperative ?? true;
+	const holds = options.holds ?? 3;
+	const timeOf = () => {
+		if (!fake) return {
+			clock: realClock,
+			pass: sleep
+		};
+		const clock = fakeClock();
+		return {
+			clock,
+			pass: (ms) => clock.advance(ms)
+		};
+	};
+	const check = (ok, what) => {
+		if (!ok) throw new Error(`${name}: ${what}`);
+	};
+	const each = (title, body) => ({
+		name: `${name}: ${title}`,
+		async run() {
+			const time = timeOf();
+			const subject = await make(time.clock);
+			try {
+				await subject.impl.start(new AbortController().signal, subject.life ?? detachedLifecycle());
+				await body(subject, time, title);
+			} finally {
+				try {
+					await subject.impl.close();
+				} finally {
+					await subject.dispose?.();
+				}
+			}
+		}
+	});
+	const count = (subject, expected, what) => within(slack, () => subject.impl.inFlight() === expected).then((ok) => check(ok, `${what}: inFlight() gives ${subject.impl.inFlight()}, not ${expected}`));
+	const closes = async (subject, title) => {
+		const began = realNow();
+		const closed = track(attempt(() => subject.impl.close()));
+		const inBound = await within(closeBound, () => closed.settled);
+		const took = realNow() - began;
+		options.record?.({
+			case: title,
+			what: "close",
+			expected: closeBound,
+			measured: took
+		});
+		check(inBound, `close did not end in its bound of ${closeBound} ms`);
+		check(!closed.failed, `close threw: ${String(closed.error)}`);
+	};
+	return [
+		each("nothing is in flight after the start, and it takes new work", async (subject) => {
+			check(subject.impl.inFlight() === 0, `inFlight() gives ${subject.impl.inFlight()} after the start, not 0`);
+			check(await subject.offer(), "the transport refused new work after its start");
+			await count(subject, 0, "the work ended");
+		}),
+		each("the count follows each work in flight from its events, with no move of the clock", async (subject) => {
+			const held = [];
+			for (let at = 1; at <= holds; at += 1) {
+				held.push(await subject.hold());
+				await count(subject, at, `${at} works are in flight`);
+			}
+			for (let at = holds - 1; at >= 0; at -= 1) {
+				await held[at].release();
+				await count(subject, at, `${at} works are in flight after a release`);
+			}
+		}),
+		each("stopIntake refuses new work, keeps the work in flight, and a second stop has no effect", async (subject) => {
+			const work = await subject.hold();
+			await subject.impl.stopIntake();
+			check(!await subject.offer(), "the transport took new work after stopIntake");
+			await count(subject, 1, "stopIntake cut the work in flight");
+			await subject.impl.stopIntake();
+			check(!await subject.offer(), "the transport took new work after a second stopIntake");
+			await work.release();
+			await count(subject, 0, "the work in flight ended after stopIntake");
+		}),
+		each("drain ends at once when nothing is in flight", async (subject, time) => {
+			await subject.impl.stopIntake();
+			const drained = track(attempt(() => subject.impl.drain(time.clock.now() + cap, new AbortController().signal)));
+			check(await within(slack, () => drained.settled), "drain did not end with nothing in flight");
+			check(!drained.failed, `drain threw: ${String(drained.error)}`);
+		}),
+		each("drain ends when the last work ends, before its deadline", async (subject, time) => {
+			const work = await subject.hold();
+			await subject.impl.stopIntake();
+			const deadline = time.clock.now() + cap;
+			const drained = track(attempt(() => subject.impl.drain(deadline, new AbortController().signal)));
+			await time.pass(cap / 4);
+			await quiet();
+			check(!drained.settled, "drain ended while work was in flight, before its deadline");
+			await work.release();
+			check(await within(slack, () => drained.settled), "drain did not end when the last work ended");
+			check(!drained.failed, `drain threw: ${String(drained.error)}`);
+			check(time.clock.now() < deadline, "drain waited until its deadline after the last work ended");
+		}),
+		each("drain holds to its deadline and not past it, and does not throw", async (subject, time, title) => {
+			await subject.hold();
+			await subject.impl.stopIntake();
+			const began = realNow();
+			const deadline = time.clock.now() + cap;
+			const drained = track(attempt(() => subject.impl.drain(deadline, new AbortController().signal)));
+			if (fake) {
+				await time.pass(cap - 1);
+				await quiet();
+				check(!drained.settled, "drain ended before its deadline, with work in flight");
+				await time.pass(1);
+				check(await within(slack, () => drained.settled), "drain did not end at its deadline");
+			} else {
+				const ended = await within(cap + slack, () => drained.settled);
+				const took = realNow() - began;
+				options.record?.({
+					case: title,
+					what: "drain to its deadline",
+					expected: cap,
+					measured: took
+				});
+				check(ended, `drain did not end in ${cap + slack} ms, with a deadline at ${cap} ms`);
+				check(took >= cap - slack, `drain ended after ${Math.round(took)} ms, before its deadline at ${cap} ms`);
+			}
+			check(!drained.failed, `drain threw at its deadline: ${String(drained.error)}`);
+		}),
+		...cooperative ? [each("drain gives the cooperative abort to the work in flight", async (subject, time) => {
+			const work = await subject.hold();
+			await subject.impl.stopIntake();
+			const abort = new AbortController();
+			const drained = track(attempt(() => subject.impl.drain(time.clock.now() + cap, abort.signal)));
+			await time.pass(cap / 2);
+			await quiet();
+			check(!work.aborted, "the work got an abort before the signal of the drain aborted");
+			abort.abort(/* @__PURE__ */ new Error("the cooperative abort of the conformance kit"));
+			check(await within(slack, () => work.aborted), "the work did not get the cooperative abort");
+			await time.pass(cap / 2);
+			check(await within(slack, () => drained.settled), "drain did not end at its deadline after the cooperative abort");
+			check(!drained.failed, `drain threw after the cooperative abort: ${String(drained.error)}`);
+		})] : [],
+		each("drain with an aborted signal and a deadline in the past ends at once", async (subject, time) => {
+			const work = await subject.hold();
+			await subject.impl.stopIntake();
+			const abort = new AbortController();
+			abort.abort(/* @__PURE__ */ new Error("the cooperative abort of the conformance kit"));
+			const drained = track(attempt(() => subject.impl.drain(time.clock.now() - 1, abort.signal)));
+			check(await within(slack, () => drained.settled), "drain did not end at once with its deadline in the past");
+			check(!drained.failed, `drain threw: ${String(drained.error)}`);
+			if (cooperative) check(await within(slack, () => work.aborted), "the work did not get an abort that came before the drain");
+		}),
+		each("close ends the work in flight, in its bound", async (subject, _time, title) => {
+			for (let at = 0; at < holds; at += 1) await subject.hold();
+			await count(subject, holds, "the works are in flight before the close");
+			await closes(subject, title);
+			await count(subject, 0, "close left work in flight");
+		}),
+		each("close is idempotent: a second close has no effect", async (subject, _time, title) => {
+			await subject.hold();
+			const first = track(attempt(() => subject.impl.close()));
+			const second = track(attempt(() => subject.impl.close()));
+			check(await within(closeBound, () => first.settled && second.settled), "two closes did not end in the bound");
+			check(!first.failed && !second.failed, `a close threw: ${String(first.error ?? second.error)}`);
+			await closes(subject, title);
+			await count(subject, 0, "the closes left work in flight");
+		}),
+		each("close right after the start ends in its bound", async (subject, _time, title) => {
+			await closes(subject, title);
+			check(subject.impl.inFlight() === 0, "inFlight() is not 0 after a close with no work");
+		}),
+		each("the stages in their sequence: stop intake, drain with its cooperative abort, close", async (subject, time, title) => {
+			const short = await subject.hold();
+			const long = await subject.hold();
+			await subject.impl.stopIntake();
+			check(!await subject.offer(), "the transport took new work after stopIntake");
+			const abort = new AbortController();
+			const drained = track(attempt(() => subject.impl.drain(time.clock.now() + cap, abort.signal)));
+			await short.release();
+			await count(subject, 1, "one work ended in the drain");
+			await time.pass(cap / 2);
+			abort.abort(/* @__PURE__ */ new Error("the cooperative abort of the conformance kit"));
+			if (cooperative) check(await within(slack, () => long.aborted), "the long work did not get the cooperative abort");
+			await time.pass(cap / 2);
+			check(await within(slack, () => drained.settled), "drain did not end at its deadline");
+			await closes(subject, title);
+			await count(subject, 0, "close left work in flight");
+		})
+	];
+};
+//#endregion
 //#region src/testing.ts
 /** This function makes a scripted check with a behavior at the start. */
 const scriptedCheck = (behavior = "ok") => {
@@ -344,6 +638,6 @@ const quietServer = async () => {
 	};
 };
 //#endregion
-export { contractCases, fakeClock, fakeProcess, quietServer, scriptedCheck, seeded };
+export { contractCases, detachedLifecycle, fakeClock, fakeProcess, quietServer, scriptedCheck, seeded, transportConformance };
 
 //# sourceMappingURL=testing.js.map