@mark1russell7/service 0.5.1 → 0.5.3

package/build/index.js

@@ -2,7 +2,9 @@ import { platformClock, realClock } from "./clock.js";
 import { detectionTime, heartbeat } from "./heartbeat.js";
 import { a as recoverSpan, i as heartbeatDetection, n as asWindow, r as failSpan, t as asDebounce } from "./timing-DGRi3XCI.js";
 import { n as operationProblems, t as mayReissue } from "./operation-DL5RxFds.js";
+import { a as limiterProblems, i as limitRule, n as freeAt, o as longestRetryAfter, r as idleSpan, s as retryAfterSeconds, t as decide } from "./policy-CgS4y94U.js";
 import { backoffBand, backoffDelay, backoffProblems } from "./backoff.js";
+import { n as memoryStore, t as keyedLimiter } from "./limiter-wv0uXDk9.js";
 import { n as countOf, r as millisecondsOf, t as boundedMillisecondsOf } from "./knobs-BxG-c7Zb.js";
 import { convertExact, convertible, quantity, rationals, valueIn } from "@mark1russell7/quantity";
 import { replay } from "@mark1russell7/algebra/replay";
@@ -616,6 +618,33 @@ const processPortOf = (find) => {
 };
 /** This port is the process of Node. */
 const nodeProcess = processPortOf(() => globalThis.process);
+/**
+* This function gives a process port for a lifecycle in a process that another part owns. That
+* part is a script, a test of an application, or a library entry. The port adds no handler of a signal or of
+* a trigger, it does not hold the process, and its `exit` only records the code. The caller stops
+* the lifecycle with `life.shutdown()`. A process with a service of its own gives its parts to
+* that service, and does not use this port.
+*/
+const embeddedProcess = () => {
+	let code = null;
+	let resolve = () => {};
+	return {
+		on() {
+			return () => {};
+		},
+		exit(requested) {
+			if (code !== null) return;
+			code = requested;
+			resolve(requested);
+		},
+		get exitCode() {
+			return code;
+		},
+		exited: new Promise((done) => {
+			resolve = done;
+		})
+	};
+};
 //#endregion
 //#region src/routes.ts
 const NAME = /^[A-Za-z_][A-Za-z0-9_]*/;
@@ -1400,6 +1429,7 @@ const service = (name) => {
 	const choices = /* @__PURE__ */ new Map();
 	const checks = [];
 	const runs = /* @__PURE__ */ new Map();
+	const limiters = [];
 	const couplings = [];
 	const phases = [];
 	let readiness;
@@ -1560,6 +1590,19 @@ const service = (name) => {
 			}
 			return builder;
 		},
+		limiter(entry, spec) {
+			composing(`the limiter ${entry}`);
+			once(limiters, entry, "limiter");
+			const given = spec ?? {};
+			limiters.push({
+				name: entry,
+				...given,
+				...given.policy === void 0 ? {} : { policy: { ...given.policy } },
+				...given.store === void 0 ? {} : { store: { ...given.store } },
+				...given.evict === void 0 ? {} : { evict: { ...given.evict } }
+			});
+			return builder;
+		},
 		healthServer(server) {
 			composing("the health server");
 			if (probes !== null) throw new Error(`${name} already has a health server`);
@@ -1689,6 +1732,11 @@ const service = (name) => {
 				for (const [route, operation] of Object.entries(controller.routes)) problems.push(...operationProblems(`controller ${controller.name}`, route, operation));
 				for (const declared of controller.patterns) problems.push(...routePatternProblems(`controller ${controller.name}`, declared));
 			}
+			for (const limiter of limiters) {
+				const { name: entry, ...spec } = limiter;
+				problems.push(...limiterProblems(entry, spec));
+				if (limiter.store?.kind === "shared" && typeof limiter.store.dependency === "string" && !known.has(limiter.store.dependency)) problems.push(`limiter ${entry} keeps its counts in ${limiter.store.dependency}, which is not a dependency`);
+			}
 			for (const dependency of dependencies) for (const [name, operation] of Object.entries(dependency.operations)) problems.push(...operationProblems(`dependency ${dependency.name}`, name, operation));
 			for (const phase of phases) if (!isTime$1(phase.cap)) problems.push(`phase ${phase.name}'s cap is not a time`);
 			problems.push(...shutdownProblems(floor, repeat, triggers, exitCodes, messages));
@@ -1722,6 +1770,12 @@ const service = (name) => {
 					...entry,
 					poll: { ...entry.poll }
 				})),
+				...limiters.length === 0 ? {} : { limiters: limiters.map((entry) => ({
+					...entry,
+					policy: { ...entry.policy },
+					store: { ...entry.store },
+					evict: { maxKeys: { ...entry.evict.maxKeys } }
+				})) },
 				policies: {
 					readiness,
 					liveness,
@@ -1883,8 +1937,74 @@ const SERVICE_RULES = [
 	"O21",
 	"O22",
 	"O23",
-	"O27"
+	"O27",
+	"O29",
+	"O30"
 ];
+/**
+* These are the two rules of the law for a keyed limiter, as data. The caller of `lint()` gives
+* them, as it gives each other rule. Each one applies one time for each limiter.
+* - O29: the longest `Retry-After` of a limiter is at most the retry window of its caller. Its
+*   second inequality applies the same bound to a new key at the cap of keys.
+*   Otherwise the caller stops before the limit lets its call in, and a refusal becomes a failure.
+* - O30: the least delay of a caller before it sends a refused call again is at least the longest
+*   `Retry-After` of the policy. Otherwise a caller that does not read the header sends again too
+*   early, and the limiter refuses each early call again.
+*
+* The identifiers O29 and O30 are provisional. The corpus of the law in jarvis (R3, track B) has 28
+* rules, O01 to O28. It does not have these two rules yet, thus they take the next two identifiers.
+*/
+const LIMITER_RULES = [{
+	id: "O29",
+	rule: "the longest Retry-After of a limiter, at its cap of keys too, is at most the retry window of its caller",
+	window: "the caller stops before the limit lets its call in, thus a refusal becomes a failure",
+	expr: {
+		lhs: { terms: [{
+			knob: "retry_after",
+			coef: 1,
+			at: "limiter"
+		}] },
+		op: "<=",
+		rhs: { terms: [{
+			knob: "client_retry_window",
+			coef: 1,
+			at: "caller"
+		}] },
+		margin: 0
+	},
+	expr_more: [{
+		lhs: { terms: [{
+			knob: "retry_after_at_cap",
+			coef: 1,
+			at: "limiter"
+		}] },
+		op: "<=",
+		rhs: { terms: [{
+			knob: "client_retry_window",
+			coef: 1,
+			at: "caller"
+		}] },
+		margin: 0
+	}]
+}, {
+	id: "O30",
+	rule: "the least delay of a caller before it sends a refused call again is at least the longest Retry-After of the limiter",
+	window: "a caller that does not read Retry-After sends again too early, and the limiter refuses each early call again",
+	expr: {
+		lhs: { terms: [{
+			knob: "retry_delay",
+			coef: 1,
+			at: "caller"
+		}] },
+		op: ">=",
+		rhs: { terms: [{
+			knob: "retry_after",
+			coef: 1,
+			at: "limiter"
+		}] },
+		margin: 0
+	}
+}];
 /** This function gives a finite amount in seconds. */
 const secondsOf = (amount) => rationals.toNumber(convertExact(rationals.fromNumber(amount.value), amount.unit, "s"));
 /** This function gives an amount, or no bound, as the law binds it. */
@@ -1960,8 +2080,24 @@ const transportBindings = (transport, hop, scenario) => {
 	for (const [symbol, amount] of Object.entries(scenario.transports?.[transport.name] ?? {})) bind[symbol] = boundOf(amount);
 	return bind;
 };
+/**
+* This function gives the symbols of a limiter, and the values of the scenario for its callers.
+* - `retry_after@limiter` is the longest `Retry-After` of a refusal by the policy, in whole seconds.
+*   It is one interval of the bucket, or one window, as the HTTP edge sends it.
+* - `retry_after_at_cap@limiter` is the longest `Retry-After` of a new key at the cap of keys. It is
+*   the idle span, `burst / rate` or one window.
+*/
+const limiterBindings = (limiter, scenario) => {
+	const bind = {
+		"retry_after@limiter": retryAfterSeconds(longestRetryAfter(limiter.policy)),
+		"retry_after_at_cap@limiter": retryAfterSeconds(idleSpan(limiter.policy))
+	};
+	for (const [symbol, amount] of Object.entries(scenario.limiters?.[limiter.name] ?? {})) bind[symbol.includes("@") ? symbol : `${symbol}@caller`] = boundOf(amount);
+	return bind;
+};
 const SCOPED = /@(client|dependency|server)$/;
 const TRANSPORT_SCOPED = /@consumer$/;
+const LIMITER_SCOPED = /@(limiter|caller)$/;
 /** This identifier is the rule of the findings about a field that the declaration does not give. */
 const DECLARATION_RULE = "declaration";
 /**
@@ -1980,8 +2116,8 @@ const declarationFindings = (svc) => svc.shutdown.onRepeatSignal === void 0 ? [{
 }] : [];
 /**
 * This function applies each service rule to a declaration and a scenario. A rule applies one time
-* for the service, for each client, or for each consumer and worker. The function also gives a
-* finding for each necessary field that the description does not give (`DECLARATION_RULE`).
+* for the service, for each client, for each consumer and worker, or for each limiter. The function
+* also gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
 */
 const lint = (svc, scenario, rules) => {
 	const service = serviceBindings(svc, scenario).bind;
@@ -1989,7 +2125,10 @@ const lint = (svc, scenario, rules) => {
 	for (const rule of rules) {
 		if (!SERVICE_RULES.includes(rule.id)) continue;
 		const symbols = symbolsOf(rule);
-		const scopes = symbols.some((symbol) => TRANSPORT_SCOPED.test(symbol)) ? svc.transports.flatMap((transport) => {
+		const scopes = symbols.some((symbol) => LIMITER_SCOPED.test(symbol)) ? (svc.limiters ?? []).map((limiter) => [limiter.name, {
+			...service,
+			...limiterBindings(limiter, scenario)
+		}]) : symbols.some((symbol) => TRANSPORT_SCOPED.test(symbol)) ? svc.transports.flatMap((transport) => {
 			const hop = TRANSPORT_HOPS[transport.kind];
 			return hop === null ? [] : [[transport.name, {
 				...service,
@@ -3225,6 +3364,6 @@ const MACHINES = {
 	watchdog: WATCHDOG_MACHINE
 };
 //#endregion
-export { DECLARATION_RULE, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, MACHINES, POLLER_MACHINE, PROCESS_TRIGGERS, SERVICE_RULES, STAGES, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, cooperativeAbortAt, daemon, detectionTime, drainMachine, ephemeral, evaluate, failSpan, heartbeat, heartbeatDetection, inequalities, isExitCode, isExitSignal, isMessageShape, kubernetes, lint, localDev, matchesMessage, mayReissue, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redeliverOnce, replay, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
+export { DECLARATION_RULE, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LIMITER_RULES, MACHINES, POLLER_MACHINE, PROCESS_TRIGGERS, SERVICE_RULES, STAGES, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, cooperativeAbortAt, daemon, decide, detectionTime, drainMachine, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterProblems, lint, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
 
 //# sourceMappingURL=index.js.map