@mark1russell7/service 0.5.16 → 0.5.18

package/build/index.js

@@ -609,6 +609,140 @@ const healthRuntime = (description, runs, options = {}) => {
 	};
 };
 //#endregion
+//#region src/logger.ts
+/** These are the levels of a log entry, from the least to the most severe. */
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/** This function tells if `level` is at `least` or more severe. */
+const atLeast = (level, least) => LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(least);
+/**
+* This function makes the console logger. It writes each entry at its level or more severe to the
+* method of that level, with the message first and then the fields.
+*/
+const consoleLogger = (options = {}) => {
+	const least = options.level ?? "info";
+	return { log(level, message, fields) {
+		if (!atLeast(level, least)) return;
+		const target = options.console ?? globalThis.console;
+		if (Object.keys(fields).length === 0) target[level](message);
+		else target[level](message, fields);
+	} };
+};
+const seconds = (cap) => `${valueIn(cap, "s")} s`;
+/** This function gives the exit code from the detail of an exit event, for example `exit 1`. */
+const exitCodeOf = (detail) => {
+	const found = /^exit (\d+)$/.exec(detail ?? "");
+	return found === null ? null : Number(found[1]);
+};
+/**
+* This function makes a recorder that writes each lifecycle event to a logger. Thus the logger is
+* one sink of the same stream as the recorder, not a second set of calls. The levels are these:
+* - `error`: each error of the lifecycle, and an exit at once on a repeat signal.
+* - `warn`: a phase at its cap, a failed startup, a startup over its budget, a tripped latch and a blocked event loop.
+* - `info`: each step of the startup, the start and the end of each phase, the exit, and each recovery.
+* - `debug`: each other transition, for example each poll of a check.
+* With the description, the entry of a phase also gives its cap. A failure of the logger does not stop the lifecycle.
+*/
+const logEvents = (logger, description) => {
+	const caps = new Map((description?.shutdown.phases ?? []).map((phase) => [phase.name, phase.cap]));
+	const startedAt = /* @__PURE__ */ new Map();
+	const write = (level, message, fields) => {
+		try {
+			logger.log(level, message, fields);
+		} catch {}
+	};
+	const phaseEnd = (event, base) => {
+		const phase = event.from;
+		const cap = caps.get(phase);
+		const begun = startedAt.get(phase);
+		const reached = event.on === "phase.cap";
+		const fields = {
+			...base,
+			phase,
+			outcome: reached ? "cap" : "done",
+			...cap === void 0 ? {} : { cap },
+			...begun === void 0 ? {} : { took: {
+				value: event.at - begun,
+				unit: "ms"
+			} }
+		};
+		if (reached) write("warn", `the phase ${phase} reached its cap${cap === void 0 ? "" : ` of ${seconds(cap)}`}`, fields);
+		else write("info", `the phase ${phase} ended in its cap`, fields);
+	};
+	const phaseStart = (event, base) => {
+		const phase = event.to;
+		const cap = caps.get(phase);
+		startedAt.set(phase, event.at);
+		write("info", `the phase ${phase} starts${cap === void 0 ? "" : `, with a cap of ${seconds(cap)}`}`, {
+			...base,
+			phase,
+			...cap === void 0 ? {} : { cap }
+		});
+	};
+	return (event) => {
+		const { machine, instance, from, to, on, at, detail } = event;
+		const base = {
+			machine,
+			instance,
+			from,
+			to,
+			on,
+			at,
+			...detail === void 0 ? {} : { detail }
+		};
+		switch (machine) {
+			case "gate":
+				if (on === "component.started") return write("info", `${detail ?? "a component"} started`, {
+					...base,
+					component: detail
+				});
+				if (on === "startup.begin") return write("info", `the startup of ${instance} begins`, base);
+				if (on === "mark-ready") return write("info", "the warm-up sweep begins", base);
+				if (on === "sweep.done") return write("info", `${instance} is ready: the startup gate is open`, base);
+				if (on === "startup.fail") return write("warn", `the startup of ${instance} failed`, base);
+				if (on === "startup.over-budget") return write("warn", `the startup of ${instance} is over its budget`, base);
+				break;
+			case "exit":
+				if (on === "error") return write("error", detail ?? "an error of the lifecycle", base);
+				if (to === "exited") {
+					const code = exitCodeOf(detail);
+					const fields = {
+						...base,
+						code
+					};
+					if (on === "exit.repeat") return write("error", `a signal came again, and ${instance} exits at once with the code ${code}`, fields);
+					return write("info", `${instance} exited with the code ${code}`, fields);
+				}
+				if (from === "running" && to === "stopping") return write("info", `the shutdown of ${instance} begins`, {
+					...base,
+					cause: detail
+				});
+				if (on === "exit.repeat") return write("info", "a trigger came again while the shutdown runs", base);
+				break;
+			case "drain":
+				if (on === "signal.abort") return write("info", `the signal of ${instance} aborts`, base);
+				if (on === "drain.cooperative-abort") return write("info", "the cooperative abort of the drain", base);
+				if (on === "phase.done" || on === "phase.cap") phaseEnd(event, base);
+				if (to !== "done" && from !== to) phaseStart(event, base);
+				else if (to === "done") write("info", `the shutdown of ${instance} ended its phases`, base);
+				return;
+			case "latch":
+			case "window":
+				if (to === "tripped" && from !== "tripped") return write("warn", `the check ${instance} tripped its latch`, base);
+				if (to === "released" && (from === "tripped" || from === "recovering")) return write("info", `the check ${instance} released its latch`, base);
+				break;
+			case "watchdog":
+				if (to === "blocked" && from !== "blocked") return write("warn", "the event loop is blocked", base);
+				if (to === "watching" && from === "blocked") return write("info", "the event loop is no longer blocked", base);
+		}
+		write("debug", `${machine} ${instance}: ${from} -> ${to} on ${on}`, base);
+	};
+};
+//#endregion
 //#region src/process.ts
 /** These are the signals that the runtime handles. */
 const EXIT_SIGNALS = [
@@ -1820,6 +1954,22 @@ const shutdownProblems = (floor, repeat, triggers, exitCodes, messages) => {
 	}
 	return problems;
 };
+/**
+* This function gives the options with one recorder for the recorder and the logger of the options.
+* Without a logger, it gives the same options.
+*/
+const withLogger = (options, description) => {
+	if (options.logger === void 0) return options;
+	const given = options.record;
+	const log = logEvents(options.logger, description);
+	return {
+		...options,
+		record: (event) => {
+			given?.(event);
+			log(event);
+		}
+	};
+};
 /** This function starts the composition of a service. */
 const service = (name) => {
 	if (name.trim().length === 0) throw new Error("a service needs a name");
@@ -1871,8 +2021,9 @@ const service = (name) => {
 		return builder;
 	};
 	/** This function makes the runtime of the declaration: its checks, and a watchdog for each spec. */
-	const makeRuntime = (options) => {
+	const makeRuntime = (given) => {
 		const description = builder.describe();
+		const options = withLogger(given, description);
 		const clock = options.clock ?? realClock;
 		const dogs = [];
 		const all = new Map(runs);
@@ -1907,7 +2058,8 @@ const service = (name) => {
 				}
 			},
 			description,
-			stopPollers
+			stopPollers,
+			options
 		};
 	};
 	const builder = {
@@ -2223,7 +2375,7 @@ const service = (name) => {
 				const ran = lifecycle(made.description, made.runtime, {
 					...components,
 					stopPollers: made.stopPollers
-				}, options, (given) => {
+				}, made.options, (given) => {
 					life = given;
 				});
 				running = ran.started.then(() => ran);
@@ -3927,6 +4079,6 @@ const MACHINES = {
 	watchdog: WATCHDOG_MACHINE
 };
 //#endregion
-export { DECLARATION_RULE, DRAIN_RULE_IDS, DURATION_FRACTIONS, EPISODES_KEPT, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LAW_STATISTIC, LIMITER_RULES, MACHINES, PLATFORM_MARKS, POLLER_MACHINE, PROCESS_TRIGGERS, PROGRESS_RULE, SERVICE_RULES, SLIDING_WINDOW_MACHINE, STAGES, STOPS, STOP_RULE, TOKEN_BUCKET_MACHINE, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, compress, compression, compressionOf, cooperativeAbortAt, daemon, decide, detectionTime, drainMachine, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, lint, lintStop, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
+export { DECLARATION_RULE, DRAIN_RULE_IDS, DURATION_FRACTIONS, EPISODES_KEPT, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LAW_STATISTIC, LIMITER_RULES, LOG_LEVELS, MACHINES, PLATFORM_MARKS, POLLER_MACHINE, PROCESS_TRIGGERS, PROGRESS_RULE, SERVICE_RULES, SLIDING_WINDOW_MACHINE, STAGES, STOPS, STOP_RULE, TOKEN_BUCKET_MACHINE, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, atLeast, backoffBand, backoffDelay, backoffProblems, capKnob, compress, compression, compressionOf, consoleLogger, cooperativeAbortAt, daemon, decide, detectionTime, drainMachine, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, lint, lintStop, localDev, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
 
 //# sourceMappingURL=index.js.map