@mark1russell7/service 0.5.6 → 0.5.7

package/README.md

@@ -74,7 +74,9 @@ The format of a description is `mark1russell7.service/1`.
 
 ## The machines
 
-The machines of the runtime are `mark1russell7.machine/1` documents, which `@mark1russell7/algebra` reads. They are the gate, the latch (a debounce), the window, the poller, the exit manager and the watchdog. `drainMachine(description)` gives the drain of a declaration, with one state for each phase. Each machine gives its transitions to `run({ record })` or `start({ record })`. `replay(doc, events)` gives each transition that the document does not permit. It is the replay of `@mark1russell7/algebra`, which reads a machine of any name.
+The machines of the runtime are `mark1russell7.machine/1` documents, which `@mark1russell7/algebra` reads. They are the gate, the latch (a debounce), the window, the poller, the exit manager and the watchdog. `drainMachine(description)` gives the drain of a declaration, with one state for each phase. The keyed limiter has its own documents.
+
+Each machine gives its transitions to `run({ record })` or `start({ record })`. `replay(doc, events)` gives each transition that the document does not permit. It is the replay of `@mark1russell7/algebra`, which reads a machine of any name.
 
 The tests replay the real runtime against each document. They also compare each timer of the documents, from the algebra, with the time that the runtime keeps.
 
@@ -318,6 +320,8 @@ A keyed limiter gives each key its own limit, for example each tenant or each pr
 | `idleSpan(policy)`, `longestRetryAfter(policy)`, `retryAfterSeconds(retryAfter)` | The times of a policy, and `Retry-After` in whole seconds |
 | `limiterProblems(name, spec)` | The problems of a spec that `describe()` and `keyedLimiter` refuse |
 | `LIMITER_RULES` | The rules O29 and O30 of the law, as data. Their identifiers are provisional. |
+| `TOKEN_BUCKET_MACHINE`, `SLIDING_WINDOW_MACHINE`, `limiterMachine(policy)` | The machine of one key of each policy, as a `mark1russell7.machine/1` document |
+| `limiterStateOf(rule, state, now)` | The state of a key of a store, as its document names it: `new`, `open` or `limited` |
 
 - **No defaults.** A spec has a key, a policy, a store and a bound on its keys. `describe()` refuses a spec without its rate, its burst, its limit, its window, its store, the failure policy of a shared store or its bound. The error names the part.
 - **The key.** `key` tells what the key of each take is, for example `tenant`. The caller gives each key to `take(key)`.
@@ -343,6 +347,11 @@ A keyed limiter gives each key its own limit, for example each tenant or each pr
 - **O30.** The least delay of a caller before a retry (`retry_delay@caller`) is at least the longest `Retry-After` of the policy. Otherwise a caller that does not read the header sends again too early.
 - **A closed failure.** The `retryAfter` of the cause `store` is the longest `retryAfter` of the policy. Thus O29 and O30 apply to it too.
 - **The symbols.** `retry_after@limiter` is the longest `Retry-After` of the policy in whole seconds: one interval of the bucket, or one window. `retry_after_at_cap@limiter` is the longest at the cap, `idleSpan` in whole seconds.
+- **The machine of a key.** Each policy has a document of one key, which `@mark1russell7/algebra` reads. A key is `new` (the store holds no count, or a count equal to a new key), `open` (its next take is permitted) or `limited` (its next take is refused).
+- **The timers of a token bucket.** `token` fires at most `1 / rate` after the take that used the last token. That time is the longest `Retry-After`. `full` fires from one to `burst` intervals after a permitted take: the bucket is full, and the key is new again.
+- **The timers of a sliding window.** `oldest` fires at most one window after the take that filled the window. `last` fires one window after the last permitted take, and the key is new again.
+- **The other transitions.** A refused take leaves a limited key limited. A new key at the cap stays new, with the cause `cap`. A failure of a shared store leaves each state as it is.
+- **The replay.** The tests drive the runtime on a fake clock and replay each take and each change of state against the document. The scenarios reach each transition. The times of the runtime are inside the bounds of the timers that the algebra gives.
 
 ```ts
 import { keyedLimiter, memoryStore, realClock } from "@mark1russell7/service";

package/build/index.d.ts

@@ -5,7 +5,7 @@ import { S as retryAfterSeconds, _ as freeAt, a as LimitRule, b as limiterProble
 import { $ as failSpan, A as LifecycleEvent, B as Gate, C as ProbeAnswer, Ct as Operation, D as Outcome, E as CheckFn, F as CooperativeFloor, G as Step, H as Phase, I as Coupling, J as Poll, K as Transport, L as Dependency, M as Recorder, N as Check, O as Result, P as Controller, Q as asWindow, R as ExitCodes, S as HealthVerdict, St as Idempotency, T as StartOptions, U as RepeatSignal, V as MessageTrigger, W as ServiceDescription, X as Timing, Y as Span, Z as asDebounce, _ as RequestOptions, _t as isExitSignal, a as PhaseContext, at as EXIT_SIGNALS, b as CheckVerdict, bt as nodeProcess, c as STAGES, ct as ExitTrigger, d as TransportImpl, dt as PROCESS_TRIGGERS, et as heartbeatDetection, f as cooperativeAbortAt, ft as ProcessHost, g as RequestFn, gt as isExitCode, h as RequestEvent, ht as embeddedProcess, i as LifecycleState, it as RouteRequest, j as MachineName, l as ShutdownOptions, lt as HostStream, m as RequestEnd, mt as ProcessTrigger, n as HealthServer, nt as OperationOf, o as PhaseWork, ot as EmbeddedProcess, p as stageRank, pt as ProcessPort, q as FailsBy, r as Lifecycle, rt as RoutePattern, s as RunOptions, st as ExitSignal, t as DependencyHandle, tt as recoverSpan, u as Stage, ut as MessageShape, v as RequestStream, vt as isMessageShape, w as ProbeKind, wt as mayReissue, x as Health, xt as processPortOf, y as RequestWork, yt as matchesMessage, z as FORMAT } from "./lifecycle-Chu9Pri2.js";
 import { a as WatchdogSpec, c as Profile, d as kubernetes, f as localDev, i as Watchdog, l as daemon, n as ServiceBuilder, o as watchdog, r as service, s as PodTiming, t as ControllerBuilder, u as ephemeral } from "./builder-DyDB7zM9.js";
 import { a as keyedLimiter, i as TakeRequest, n as LimiterStore, o as memoryStore, r as MemoryStore, t as KeyedLimiter } from "./store-DzTyosou.js";
-import "./limiter.js";
+import { a as limiterStateOf, i as limiterMachine, n as SLIDING_WINDOW_MACHINE, r as TOKEN_BUCKET_MACHINE, t as LimiterState } from "./limiter-DCDdzVwe.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
 import { replay } from "@mark1russell7/algebra/replay";
 import { Machine } from "@mark1russell7/algebra";
@@ -431,5 +431,5 @@ export declare const drainMachine: (description: ServiceDescription) => Machine;
 /** These are the static machines of the runtime, by the name that their events carry. */
 export declare const MACHINES: Readonly<Record<Exclude<MachineName, "drain" | "client">, Machine>>;
 //#endregion
-export { type Allowed, type Backoff, type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, type Decision, type DelayBand, type Dependency, type DependencyHandle, EXIT_SIGNALS, type EmbeddedProcess, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type KeyState, type KeyedLimiter, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterStore, type LimiterStoreSpec, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RefusalCause, type Refused, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type RoutePattern, type RouteRequest, type Rule, type RunOptions, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type SlidingWindow, type Span, type Stage, type StartOptions, type Step, type StoreFailure, type TakeRequest, type TakeStep, type Term, type Timing, type TokenBucket, type Transport, type TransportImpl, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterProblems, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, realClock, recoverSpan, replay, retryAfterSeconds, service, stageRank, watchdog };
+export { type Allowed, type Backoff, type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, type Decision, type DelayBand, type Dependency, type DependencyHandle, EXIT_SIGNALS, type EmbeddedProcess, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type KeyState, type KeyedLimiter, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RefusalCause, type Refused, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type RoutePattern, type RouteRequest, type Rule, type RunOptions, SLIDING_WINDOW_MACHINE, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type SlidingWindow, type Span, type Stage, type StartOptions, type Step, type StoreFailure, TOKEN_BUCKET_MACHINE, type TakeRequest, type TakeStep, type Term, type Timing, type TokenBucket, type Transport, type TransportImpl, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, realClock, recoverSpan, replay, retryAfterSeconds, service, stageRank, watchdog };
 //# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -5,7 +5,7 @@ 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 { a as lateHolds, l as takeOutside, n as countOf, r as millisecondsOf, s as ownStream, t as boundedMillisecondsOf } from "./knobs-D2ClI68I.js";
 import { backoffBand, backoffDelay, backoffProblems } from "./backoff.js";
-import { n as memoryStore, t as keyedLimiter } from "./limiter-wv0uXDk9.js";
+import { a as keyedLimiter, i as limiterStateOf, n as TOKEN_BUCKET_MACHINE, o as memoryStore, r as limiterMachine, t as SLIDING_WINDOW_MACHINE } from "./limiter-pkBZUp-t.js";
 import { convertExact, convertible, quantity, rationals, valueIn } from "@mark1russell7/quantity";
 import { replay } from "@mark1russell7/algebra/replay";
 //#region src/description.ts
@@ -3389,6 +3389,6 @@ const MACHINES = {
 	watchdog: WATCHDOG_MACHINE
 };
 //#endregion
-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 };
+export { DECLARATION_RULE, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LIMITER_RULES, MACHINES, POLLER_MACHINE, PROCESS_TRIGGERS, SERVICE_RULES, SLIDING_WINDOW_MACHINE, STAGES, TOKEN_BUCKET_MACHINE, 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, limiterMachine, limiterProblems, limiterStateOf, 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

package/build/limiter-DCDdzVwe.d.ts

@@ -0,0 +1,45 @@
+import { a as LimitRule, i as LimitPolicy, r as KeyState } from "./policy-G4QJ1ZZq.js";
+import "./store-DzTyosou.js";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/limiter/machine.d.ts
+/**
+ * A limiter state is the state of one key of a keyed limiter, as its machine document names it:
+ * - `new`: the store holds no state for the key, or a state that is equal to the state of a new key.
+ * - `open`: the key holds a count, and its next take is permitted.
+ * - `limited`: the next take of the key is refused with the cause `limit`, until a unit is back.
+ */
+type LimiterState = "new" | "open" | "limited";
+/**
+ * A token bucket of one key (GCRA), as a `mark1russell7.machine/1` document. The bucket holds
+ * `burst` tokens, and it gets one token back in each interval, `1 / rate`. The store keeps one time
+ * for the key: when its bucket is full again.
+ * - A take is permitted when, with the take, the bucket is full again in at most `burst` intervals.
+ * - A refused take waits until one token is back: at most one interval. That interval is the
+ *   longest `Retry-After` of the policy (`retry_after@limiter` of the law).
+ * - After `burst / rate` with no take, the bucket is full, and the key is equal to a new key. That
+ *   span is the idle span, and the longest wait of a new key at the cap of keys
+ *   (`retry_after_at_cap@limiter`).
+ */
+declare const TOKEN_BUCKET_MACHINE: Machine;
+/**
+ * A sliding window of one key, as a `mark1russell7.machine/1` document. The store keeps the time of
+ * each permitted take of the key in the window, and each take counts for one window from its time.
+ * - A take is permitted when fewer than `limit` takes are in the window.
+ * - A refused take waits until the oldest take leaves the window: at most one window. That window is
+ *   the longest `Retry-After` of the policy (`retry_after@limiter` of the law).
+ * - One window after the last take, no take is in the window, and the key is equal to a new key.
+ *   That window is the idle span, and the longest wait of a new key at the cap of keys
+ *   (`retry_after_at_cap@limiter`).
+ */
+declare const SLIDING_WINDOW_MACHINE: Machine;
+/** This function gives the machine document of the policy of a limiter. */
+declare const limiterMachine: (policy: LimitPolicy) => Machine;
+/**
+ * This function gives the state of a key of a store as its machine document names it, at the time
+ * `now` in milliseconds. `state` is what the store keeps for the key, or `undefined` when it keeps
+ * nothing. A key equal to a new key is `new`, and a key whose next take `decide` refuses is `limited`.
+ */
+declare const limiterStateOf: (rule: LimitRule, state: KeyState | undefined, now: number) => LimiterState;
+//#endregion
+export { limiterStateOf as a, limiterMachine as i, SLIDING_WINDOW_MACHINE as n, TOKEN_BUCKET_MACHINE as r, LimiterState as t };
+//# sourceMappingURL=limiter-DCDdzVwe.d.ts.map

package/build/limiter-pkBZUp-t.js

@@ -0,0 +1,402 @@
+import { a as limiterProblems, i as limitRule, n as freeAt, o as longestRetryAfter, t as decide } from "./policy-CgS4y94U.js";
+import { convertExact, rationals } from "@mark1russell7/quantity";
+//#region src/limiter/store.ts
+const ms = (value) => ({
+	value,
+	unit: "ms"
+});
+/**
+* This function makes the store of one replica. It reads time only through the clock. Thus a step
+* of the wall clock does not move a count, and a fake clock gives exact decisions in a test.
+* - The eviction is exact. A key whose bucket is full again, or whose window has no take, is equal
+*   to a new key. The store removes it at its next take, or at a sweep.
+* - The count of keys has a bound. At the cap, a take of a new key sweeps the table, but only when
+*   a held key can be free. Each sweep reads each key one time. When no key is free, the store
+*   refuses the new key with the cause `cap`. Its `retryAfter` is at most the time until the
+*   earliest held key is free, and that time is at most `idleSpan` of the policy.
+*/
+const memoryStore = (clock) => {
+	const tables = /* @__PURE__ */ new Map();
+	const sweep = (table, rule, now) => {
+		let next = Number.POSITIVE_INFINITY;
+		for (const [key, state] of table.states) {
+			const free = freeAt(rule, state);
+			if (free <= now) table.states.delete(key);
+			else next = Math.min(next, free);
+		}
+		table.next = next;
+	};
+	return {
+		kind: "local",
+		take({ limiter, key, rule, maxKeys }) {
+			const now = clock.now();
+			let table = tables.get(limiter);
+			if (table === void 0) {
+				table = {
+					states: /* @__PURE__ */ new Map(),
+					next: Number.POSITIVE_INFINITY
+				};
+				tables.set(limiter, table);
+			}
+			let state = table.states.get(key);
+			if (state !== void 0 && freeAt(rule, state) <= now) {
+				table.states.delete(key);
+				state = void 0;
+			}
+			if (state === void 0 && table.states.size >= maxKeys) {
+				if (table.next <= now) sweep(table, rule, now);
+				if (table.states.size >= maxKeys) return {
+					allowed: false,
+					retryAfter: ms(table.next - now),
+					cause: "cap"
+				};
+			}
+			const step = decide(rule, state, now);
+			if (state === void 0) {
+				table.states.set(key, step.state);
+				table.next = Math.min(table.next, freeAt(rule, step.state));
+			} else table.states.set(key, step.state);
+			return step.decision;
+		},
+		size(limiter) {
+			return tables.get(limiter)?.states.size ?? 0;
+		}
+	};
+};
+/** This function gives the text of a failure. */
+const failureOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+* This function makes the runtime of a limiter from its spec and its store. It refuses a spec with a
+* problem, because the limiter has no defaults. It also refuses a store of the wrong kind: a spec
+* with a shared store needs a store that the replicas share.
+* - A failure of a shared store gives the decision of `onStoreFailure`. With `open`, the take is
+*   permitted with `remaining` 0. With `closed`, it is refused with the cause `store`.
+* - The `retryAfter` of the cause `store` is the longest `retryAfter` of the policy.
+* - A failure of a local store rejects the take, because a local store has no `onStoreFailure`.
+*/
+const keyedLimiter = (name, spec, store) => {
+	const problems = limiterProblems(name, spec);
+	if (problems.length > 0) throw new Error(problems.join("; "));
+	if (store.kind !== spec.store.kind) throw new Error(`limiter ${name} declares a ${spec.store.kind} store, but the store that it got is ${store.kind}`);
+	const rule = limitRule(spec.policy);
+	const maxKeys = rationals.toNumber(convertExact(rationals.fromNumber(spec.evict.maxKeys.value), spec.evict.maxKeys.unit, "count"));
+	const onStoreFailure = spec.store.kind === "shared" ? spec.store.onStoreFailure : void 0;
+	const closedAfter = longestRetryAfter(spec.policy);
+	const take = async (key) => {
+		const request = {
+			limiter: name,
+			key,
+			rule,
+			maxKeys
+		};
+		if (onStoreFailure === void 0) return store.take(request);
+		try {
+			return await store.take(request);
+		} catch (error) {
+			const failure = failureOf(error);
+			if (onStoreFailure === "open") return {
+				allowed: true,
+				remaining: 0,
+				failure
+			};
+			return {
+				allowed: false,
+				retryAfter: { ...closedAfter },
+				cause: "store",
+				failure
+			};
+		}
+	};
+	return {
+		name,
+		spec: {
+			key: spec.key,
+			policy: { ...spec.policy },
+			store: { ...spec.store },
+			evict: { maxKeys: { ...spec.evict.maxKeys } }
+		},
+		rule,
+		maxKeys,
+		take
+	};
+};
+//#endregion
+//#region src/limiter/machine.ts
+const t = (id, from, on, to, extra = {}) => ({
+	id,
+	from,
+	on,
+	to,
+	...extra
+});
+const count = (key) => ({
+	key,
+	scope: "limiter",
+	unit: "count",
+	default: null
+});
+/** These are the states of a key that a store can hold. A store fails in each of them. */
+const HELD = [
+	"new",
+	"open",
+	"limited"
+];
+/** These are the parts of each document of a limiter that do not change with its policy. */
+const COMMON = {
+	format: "mark1russell7.machine/1",
+	layer: "self",
+	version: "0.1.0",
+	sources: [
+		{
+			ref: "packages/service/src/limiter (the runtime implements this document: decide, memoryStore, keyedLimiter)",
+			rung: "implemented"
+		},
+		{
+			ref: "RFC 6585 §4: 429 Too Many Requests, which can carry Retry-After",
+			rung: "normative"
+		},
+		{
+			ref: "RFC 9110 §10.2.3: Retry-After, as delay-seconds or an HTTP-date",
+			rung: "normative"
+		}
+	],
+	conditions: {
+		"store.local": "the counts are in the memory of one replica: a limit L over N replicas is L / N on each replica, and that sum holds only on average",
+		"store.shared": "the counts are in a store that the replicas share: one atomic step on the clock of the store decides each take"
+	},
+	states: {
+		new: {
+			initial: true,
+			note: "the store holds no state for the key, or a state equal to a new key. The store can remove the key"
+		},
+		open: { note: "the key holds a count, and its next take is permitted" },
+		limited: { note: "the next take is refused with the cause limit, until a unit is back" }
+	}
+};
+/** These are the events of each document of a limiter. */
+const EVENTS = {
+	take: {
+		kind: "app",
+		note: "one call of take(key): one request of the key. A permitted take uses one unit"
+	},
+	"unit.back": {
+		kind: "timer",
+		note: "the next take of a limited key is permitted again"
+	},
+	idle: {
+		kind: "timer",
+		note: "the key is equal to a new key. The store can remove it, and no decision changes"
+	},
+	"store.fail": {
+		kind: "local",
+		note: "a shared store fails the take. The state of the key does not change"
+	}
+};
+/** These are the knobs of each document of a limiter that do not change with its policy. */
+const KNOBS = {
+	max_keys: count("limiters.<name>.evict.maxKeys"),
+	on_store_failure: {
+		key: "limiters.<name>.store.onStoreFailure",
+		scope: "limiter",
+		unit: null,
+		default: null
+	}
+};
+/**
+* These are the transitions of each document of a limiter that do not change with its policy. They
+* are the refusal of a limited key, a new key at the cap of keys, and a failure of a shared store.
+*/
+const COMMON_TRANSITIONS = [
+	t("refuse", "limited", "take", "limited", {
+		emits: ["429 limit"],
+		note: "Retry-After is the time until the next take is permitted, in whole seconds, rounded up. The count of the key does not change"
+	}),
+	t("cap", "new", "take", "new", {
+		guard: "the store holds max_keys keys for the limiter, and no held key is equal to a new key",
+		emits: ["429 cap"],
+		note: "Retry-After is the time until the earliest held key is free: at most the idle span. A held key keeps its count"
+	}),
+	...HELD.map((state) => t(`store-failed-${state}`, state, "store.fail", state, {
+		guard: "the store is shared",
+		emits: ["allow, or 429 store"],
+		note: "on_store_failure open lets the take in, with remaining 0. closed refuses it with the cause store, and its Retry-After is the longest of the policy"
+	}))
+];
+/**
+* A token bucket of one key (GCRA), as a `mark1russell7.machine/1` document. The bucket holds
+* `burst` tokens, and it gets one token back in each interval, `1 / rate`. The store keeps one time
+* for the key: when its bucket is full again.
+* - A take is permitted when, with the take, the bucket is full again in at most `burst` intervals.
+* - A refused take waits until one token is back: at most one interval. That interval is the
+*   longest `Retry-After` of the policy (`retry_after@limiter` of the law).
+* - After `burst / rate` with no take, the bucket is full, and the key is equal to a new key. That
+*   span is the idle span, and the longest wait of a new key at the cap of keys
+*   (`retry_after_at_cap@limiter`).
+*/
+const TOKEN_BUCKET_MACHINE = {
+	...COMMON,
+	id: "service.machine.limiter.token-bucket",
+	title: "A token bucket of one key of the keyed limiter",
+	events: EVENTS,
+	knobs: {
+		rate: {
+			key: "limiters.<name>.policy.rate",
+			scope: "limiter",
+			unit: "count/s",
+			default: null
+		},
+		burst: count("limiters.<name>.policy.burst"),
+		...KNOBS
+	},
+	timers: {
+		token: {
+			duration: {
+				expr: "1 / rate",
+				unit: "s"
+			},
+			early: {
+				expr: "1 / rate",
+				unit: "s"
+			},
+			arms: ["enter:limited"],
+			cancels: ["idle"],
+			fires: "unit.back",
+			note: "one token comes back at most one interval after the take that used the last token. The Retry-After of each refusal is the time to this firing"
+		},
+		full: {
+			duration: {
+				expr: "burst / rate",
+				unit: "s"
+			},
+			early: {
+				expr: "(burst - 1) / rate",
+				unit: "s"
+			},
+			arms: ["take"],
+			fires: "idle",
+			note: "the bucket is full again from one to burst intervals after a permitted take. A refused take does not move it"
+		}
+	},
+	transitions: [
+		t("first", "new", "take", "open", {
+			guard: "burst > 1",
+			emits: ["allow"]
+		}),
+		t("first-last", "new", "take", "limited", {
+			guard: "burst = 1",
+			emits: ["allow"]
+		}),
+		t("take", "open", "take", "open", {
+			guard: "a token remains after the take",
+			emits: ["allow"]
+		}),
+		t("take-last", "open", "take", "limited", {
+			guard: "the take uses the last token",
+			emits: ["allow"]
+		}),
+		...COMMON_TRANSITIONS,
+		t("token-back", "limited", "unit.back", "open", {
+			timer: "token",
+			guard: "burst > 1"
+		}),
+		t("full", "open", "idle", "new", { timer: "full" }),
+		t("full-at-once", "limited", "idle", "new", {
+			timer: "full",
+			guard: "burst = 1: the one token is back when the bucket is full"
+		})
+	]
+};
+/**
+* A sliding window of one key, as a `mark1russell7.machine/1` document. The store keeps the time of
+* each permitted take of the key in the window, and each take counts for one window from its time.
+* - A take is permitted when fewer than `limit` takes are in the window.
+* - A refused take waits until the oldest take leaves the window: at most one window. That window is
+*   the longest `Retry-After` of the policy (`retry_after@limiter` of the law).
+* - One window after the last take, no take is in the window, and the key is equal to a new key.
+*   That window is the idle span, and the longest wait of a new key at the cap of keys
+*   (`retry_after_at_cap@limiter`).
+*/
+const SLIDING_WINDOW_MACHINE = {
+	...COMMON,
+	id: "service.machine.limiter.sliding-window",
+	title: "A sliding window of one key of the keyed limiter",
+	events: EVENTS,
+	knobs: {
+		limit: count("limiters.<name>.policy.limit"),
+		window: {
+			key: "limiters.<name>.policy.window",
+			scope: "limiter",
+			unit: "s",
+			default: null
+		},
+		...KNOBS
+	},
+	timers: {
+		oldest: {
+			duration: {
+				knob: "window",
+				unit: "s"
+			},
+			early: {
+				knob: "window",
+				unit: "s"
+			},
+			arms: ["enter:limited"],
+			cancels: ["idle"],
+			fires: "unit.back",
+			note: "the oldest take leaves the window at most one window after the take that filled it. The Retry-After of each refusal is the time to this firing"
+		},
+		last: {
+			duration: {
+				knob: "window",
+				unit: "s"
+			},
+			arms: ["take"],
+			fires: "idle",
+			note: "the last permitted take leaves the window one window after its time. A refused take does not move it"
+		}
+	},
+	transitions: [
+		t("first", "new", "take", "open", {
+			guard: "limit > 1",
+			emits: ["allow"]
+		}),
+		t("first-last", "new", "take", "limited", {
+			guard: "limit = 1",
+			emits: ["allow"]
+		}),
+		t("take", "open", "take", "open", {
+			guard: "fewer than limit - 1 takes are in the window before the take",
+			emits: ["allow"]
+		}),
+		t("take-last", "open", "take", "limited", {
+			guard: "the take is the limit-th take in the window",
+			emits: ["allow"]
+		}),
+		...COMMON_TRANSITIONS,
+		t("oldest-leaves", "limited", "unit.back", "open", {
+			timer: "oldest",
+			guard: "a later take stays in the window"
+		}),
+		t("last-leaves", "open", "idle", "new", { timer: "last" }),
+		t("all-leave", "limited", "idle", "new", {
+			timer: "last",
+			guard: "each take of the window has one time: limit = 1, or each take came at once"
+		})
+	]
+};
+/** This function gives the machine document of the policy of a limiter. */
+const limiterMachine = (policy) => policy.type === "token-bucket" ? TOKEN_BUCKET_MACHINE : SLIDING_WINDOW_MACHINE;
+/**
+* This function gives the state of a key of a store as its machine document names it, at the time
+* `now` in milliseconds. `state` is what the store keeps for the key, or `undefined` when it keeps
+* nothing. A key equal to a new key is `new`, and a key whose next take `decide` refuses is `limited`.
+*/
+const limiterStateOf = (rule, state, now) => {
+	if (state === void 0 || freeAt(rule, state) <= now) return "new";
+	return decide(rule, state, now).decision.allowed ? "open" : "limited";
+};
+//#endregion
+export { keyedLimiter as a, limiterStateOf as i, TOKEN_BUCKET_MACHINE as n, memoryStore as o, limiterMachine as r, SLIDING_WINDOW_MACHINE as t };
+
+//# sourceMappingURL=limiter-pkBZUp-t.js.map

package/build/limiter-pkBZUp-t.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter-pkBZUp-t.js","names":["r"],"sources":["../src/limiter/store.ts","../src/limiter/machine.ts"],"sourcesContent":["import type { Quantity } from \"@mark1russell7/quantity\";\nimport { convertExact, rationals as r } from \"@mark1russell7/quantity\";\nimport type { Clock } from \"../clock.ts\";\nimport type { Decision, KeyState, LimiterSpec, LimitRule } from \"./policy.ts\";\nimport { decide, freeAt, limitRule, limiterProblems, longestRetryAfter } from \"./policy.ts\";\n\n/** A take request is one take of one key, with the rule and the cap of its limiter in numbers. */\nexport interface TakeRequest {\n  /** This name is the limiter. A store keeps the keys of each limiter apart. */\n  readonly limiter: string;\n  readonly key: string;\n  readonly rule: LimitRule;\n  /** This count is the most keys that the store holds for the limiter. */\n  readonly maxKeys: number;\n}\n\n/**\n * A limiter store keeps the state of each key, and it decides each take in one atomic step, on its\n * own clock. Thus two takes of one key do not read the same state at any time. A store in this\n * process uses `decide`. A store that the replicas share does the same arithmetic in one step of its\n * own, for example one script of Redis that reads `TIME`.\n */\nexport interface LimiterStore {\n  /** This kind tells where the counts are: in the memory of this replica, or in a store that the replicas share. */\n  readonly kind: \"local\" | \"shared\";\n  /**\n   * This method decides one take. It removes a key only when its state is equal to the state of a\n   * new key. It holds at most `maxKeys` keys for each limiter. A failure of a shared store rejects\n   * the take, and the limiter then applies the `onStoreFailure` of its spec.\n   */\n  take(request: TakeRequest): Decision | Promise<Decision>;\n}\n\n/** A memory store is the store of one replica, on the injected monotonic clock. */\nexport interface MemoryStore extends LimiterStore {\n  readonly kind: \"local\";\n  /** This method gives the count of keys that the store holds for a limiter. */\n  size(limiter: string): number;\n}\n\n/** A table is the keys of one limiter in a memory store. */\ninterface Table {\n  readonly states: Map<string, KeyState>;\n  /**\n   * This time is at or before the earliest time at which a held key is equal to a new key. An\n   * insert lowers it, and a sweep sets it again. A take of a held key only moves the time of that\n   * key later, thus the bound stays true.\n   */\n  next: number;\n}\n\nconst ms = (value: number): Quantity => ({ value, unit: \"ms\" });\n\n/**\n * This function makes the store of one replica. It reads time only through the clock. Thus a step\n * of the wall clock does not move a count, and a fake clock gives exact decisions in a test.\n * - The eviction is exact. A key whose bucket is full again, or whose window has no take, is equal\n *   to a new key. The store removes it at its next take, or at a sweep.\n * - The count of keys has a bound. At the cap, a take of a new key sweeps the table, but only when\n *   a held key can be free. Each sweep reads each key one time. When no key is free, the store\n *   refuses the new key with the cause `cap`. Its `retryAfter` is at most the time until the\n *   earliest held key is free, and that time is at most `idleSpan` of the policy.\n */\nexport const memoryStore = (clock: Clock): MemoryStore => {\n  const tables = new Map<string, Table>();\n  const sweep = (table: Table, rule: LimitRule, now: number): void => {\n    let next = Number.POSITIVE_INFINITY;\n    for (const [key, state] of table.states) {\n      const free = freeAt(rule, state);\n      if (free <= now) table.states.delete(key);\n      else next = Math.min(next, free);\n    }\n    table.next = next;\n  };\n  return {\n    kind: \"local\",\n    take({ limiter, key, rule, maxKeys }) {\n      const now = clock.now();\n      let table = tables.get(limiter);\n      if (table === undefined) {\n        table = { states: new Map(), next: Number.POSITIVE_INFINITY };\n        tables.set(limiter, table);\n      }\n      let state = table.states.get(key);\n      // a key that is equal to a new key goes: the decision is the same, and it frees its slot\n      if (state !== undefined && freeAt(rule, state) <= now) {\n        table.states.delete(key);\n        state = undefined;\n      }\n      if (state === undefined && table.states.size >= maxKeys) {\n        if (table.next <= now) sweep(table, rule, now);\n        if (table.states.size >= maxKeys) return { allowed: false, retryAfter: ms(table.next - now), cause: \"cap\" };\n      }\n      const step = decide(rule, state, now);\n      if (state === undefined) {\n        // a new key is never refused by its policy: a full bucket, or an empty window\n        table.states.set(key, step.state);\n        table.next = Math.min(table.next, freeAt(rule, step.state));\n      } else table.states.set(key, step.state);\n      return step.decision;\n    },\n    size(limiter) {\n      return tables.get(limiter)?.states.size ?? 0;\n    },\n  };\n};\n\n/** A keyed limiter is the runtime of one declared limiter: its spec, its rule in numbers, and its store. */\nexport interface KeyedLimiter {\n  readonly name: string;\n  /** This spec is the declaration, the same data that `svc.limiter(name, spec)` takes and `describe()` shows. */\n  readonly spec: LimiterSpec;\n  readonly rule: LimitRule;\n  /** This count is the most keys that the store holds for the limiter. */\n  readonly maxKeys: number;\n  /**\n   * This method takes one unit for a key, and gives the decision of the store. When a shared store\n   * fails, it gives the decision of `onStoreFailure`, with the failure as text.\n   */\n  take(key: string): Promise<Decision>;\n}\n\n/** This function gives the text of a failure. */\nconst failureOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));\n\n/**\n * This function makes the runtime of a limiter from its spec and its store. It refuses a spec with a\n * problem, because the limiter has no defaults. It also refuses a store of the wrong kind: a spec\n * with a shared store needs a store that the replicas share.\n * - A failure of a shared store gives the decision of `onStoreFailure`. With `open`, the take is\n *   permitted with `remaining` 0. With `closed`, it is refused with the cause `store`.\n * - The `retryAfter` of the cause `store` is the longest `retryAfter` of the policy.\n * - A failure of a local store rejects the take, because a local store has no `onStoreFailure`.\n */\nexport const keyedLimiter = (name: string, spec: LimiterSpec, store: LimiterStore): KeyedLimiter => {\n  const problems = limiterProblems(name, spec);\n  if (problems.length > 0) throw new Error(problems.join(\"; \"));\n  if (store.kind !== spec.store.kind)\n    throw new Error(`limiter ${name} declares a ${spec.store.kind} store, but the store that it got is ${store.kind}`);\n  const rule = limitRule(spec.policy);\n  const maxKeys = r.toNumber(convertExact(r.fromNumber(spec.evict.maxKeys.value), spec.evict.maxKeys.unit, \"count\"));\n  const onStoreFailure = spec.store.kind === \"shared\" ? spec.store.onStoreFailure : undefined;\n  const closedAfter = longestRetryAfter(spec.policy);\n  const take = async (key: string): Promise<Decision> => {\n    const request: TakeRequest = { limiter: name, key, rule, maxKeys };\n    if (onStoreFailure === undefined) return store.take(request);\n    try {\n      return await store.take(request);\n    } catch (error) {\n      const failure = failureOf(error);\n      if (onStoreFailure === \"open\") return { allowed: true, remaining: 0, failure };\n      return { allowed: false, retryAfter: { ...closedAfter }, cause: \"store\", failure };\n    }\n  };\n  return {\n    name,\n    spec: {\n      key: spec.key,\n      policy: { ...spec.policy },\n      store: { ...spec.store },\n      evict: { maxKeys: { ...spec.evict.maxKeys } },\n    },\n    rule,\n    maxKeys,\n    take,\n  };\n};\n","import type { Machine, TransitionDef } from \"@mark1russell7/algebra\";\nimport type { KeyState, LimitPolicy, LimitRule } from \"./policy.ts\";\nimport { decide, freeAt } from \"./policy.ts\";\n\nconst t = (id: string, from: string | readonly string[], on: string | readonly string[], to: string, extra: Partial<TransitionDef> = {}): TransitionDef => ({\n  id,\n  from,\n  on,\n  to,\n  ...extra,\n});\nconst count = (key: string) => ({ key, scope: \"limiter\", unit: \"count\", default: null }) as const;\n\n/**\n * A limiter state is the state of one key of a keyed limiter, as its machine document names it:\n * - `new`: the store holds no state for the key, or a state that is equal to the state of a new key.\n * - `open`: the key holds a count, and its next take is permitted.\n * - `limited`: the next take of the key is refused with the cause `limit`, until a unit is back.\n */\nexport type LimiterState = \"new\" | \"open\" | \"limited\";\n\n/** These are the states of a key that a store can hold. A store fails in each of them. */\nconst HELD = [\"new\", \"open\", \"limited\"] as const;\n\n/** These are the parts of each document of a limiter that do not change with its policy. */\nconst COMMON = {\n  format: \"mark1russell7.machine/1\",\n  layer: \"self\",\n  version: \"0.1.0\",\n  sources: [\n    { ref: \"packages/service/src/limiter (the runtime implements this document: decide, memoryStore, keyedLimiter)\", rung: \"implemented\" },\n    { ref: \"RFC 6585 §4: 429 Too Many Requests, which can carry Retry-After\", rung: \"normative\" },\n    { ref: \"RFC 9110 §10.2.3: Retry-After, as delay-seconds or an HTTP-date\", rung: \"normative\" },\n  ],\n  conditions: {\n    \"store.local\": \"the counts are in the memory of one replica: a limit L over N replicas is L / N on each replica, and that sum holds only on average\",\n    \"store.shared\": \"the counts are in a store that the replicas share: one atomic step on the clock of the store decides each take\",\n  },\n  states: {\n    new: { initial: true, note: \"the store holds no state for the key, or a state equal to a new key. The store can remove the key\" },\n    open: { note: \"the key holds a count, and its next take is permitted\" },\n    limited: { note: \"the next take is refused with the cause limit, until a unit is back\" },\n  },\n} as const;\n\n/** These are the events of each document of a limiter. */\nconst EVENTS = {\n  take: { kind: \"app\", note: \"one call of take(key): one request of the key. A permitted take uses one unit\" },\n  \"unit.back\": { kind: \"timer\", note: \"the next take of a limited key is permitted again\" },\n  idle: { kind: \"timer\", note: \"the key is equal to a new key. The store can remove it, and no decision changes\" },\n  \"store.fail\": { kind: \"local\", note: \"a shared store fails the take. The state of the key does not change\" },\n} as const;\n\n/** These are the knobs of each document of a limiter that do not change with its policy. */\nconst KNOBS = {\n  max_keys: count(\"limiters.<name>.evict.maxKeys\"),\n  on_store_failure: { key: \"limiters.<name>.store.onStoreFailure\", scope: \"limiter\", unit: null, default: null },\n} as const;\n\n/**\n * These are the transitions of each document of a limiter that do not change with its policy. They\n * are the refusal of a limited key, a new key at the cap of keys, and a failure of a shared store.\n */\nconst COMMON_TRANSITIONS: readonly TransitionDef[] = [\n  t(\"refuse\", \"limited\", \"take\", \"limited\", {\n    emits: [\"429 limit\"],\n    note: \"Retry-After is the time until the next take is permitted, in whole seconds, rounded up. The count of the key does not change\",\n  }),\n  t(\"cap\", \"new\", \"take\", \"new\", {\n    guard: \"the store holds max_keys keys for the limiter, and no held key is equal to a new key\",\n    emits: [\"429 cap\"],\n    note: \"Retry-After is the time until the earliest held key is free: at most the idle span. A held key keeps its count\",\n  }),\n  ...HELD.map((state) =>\n    t(`store-failed-${state}`, state, \"store.fail\", state, {\n      guard: \"the store is shared\",\n      emits: [\"allow, or 429 store\"],\n      note: \"on_store_failure open lets the take in, with remaining 0. closed refuses it with the cause store, and its Retry-After is the longest of the policy\",\n    }),\n  ),\n];\n\n/**\n * A token bucket of one key (GCRA), as a `mark1russell7.machine/1` document. The bucket holds\n * `burst` tokens, and it gets one token back in each interval, `1 / rate`. The store keeps one time\n * for the key: when its bucket is full again.\n * - A take is permitted when, with the take, the bucket is full again in at most `burst` intervals.\n * - A refused take waits until one token is back: at most one interval. That interval is the\n *   longest `Retry-After` of the policy (`retry_after@limiter` of the law).\n * - After `burst / rate` with no take, the bucket is full, and the key is equal to a new key. That\n *   span is the idle span, and the longest wait of a new key at the cap of keys\n *   (`retry_after_at_cap@limiter`).\n */\nexport const TOKEN_BUCKET_MACHINE: Machine = {\n  ...COMMON,\n  id: \"service.machine.limiter.token-bucket\",\n  title: \"A token bucket of one key of the keyed limiter\",\n  events: EVENTS,\n  knobs: {\n    rate: { key: \"limiters.<name>.policy.rate\", scope: \"limiter\", unit: \"count/s\", default: null },\n    burst: count(\"limiters.<name>.policy.burst\"),\n    ...KNOBS,\n  },\n  timers: {\n    token: {\n      duration: { expr: \"1 / rate\", unit: \"s\" },\n      early: { expr: \"1 / rate\", unit: \"s\" },\n      arms: [\"enter:limited\"],\n      cancels: [\"idle\"],\n      fires: \"unit.back\",\n      note: \"one token comes back at most one interval after the take that used the last token. The Retry-After of each refusal is the time to this firing\",\n    },\n    full: {\n      duration: { expr: \"burst / rate\", unit: \"s\" },\n      early: { expr: \"(burst - 1) / rate\", unit: \"s\" },\n      arms: [\"take\"],\n      fires: \"idle\",\n      note: \"the bucket is full again from one to burst intervals after a permitted take. A refused take does not move it\",\n    },\n  },\n  transitions: [\n    t(\"first\", \"new\", \"take\", \"open\", { guard: \"burst > 1\", emits: [\"allow\"] }),\n    t(\"first-last\", \"new\", \"take\", \"limited\", { guard: \"burst = 1\", emits: [\"allow\"] }),\n    t(\"take\", \"open\", \"take\", \"open\", { guard: \"a token remains after the take\", emits: [\"allow\"] }),\n    t(\"take-last\", \"open\", \"take\", \"limited\", { guard: \"the take uses the last token\", emits: [\"allow\"] }),\n    ...COMMON_TRANSITIONS,\n    t(\"token-back\", \"limited\", \"unit.back\", \"open\", { timer: \"token\", guard: \"burst > 1\" }),\n    t(\"full\", \"open\", \"idle\", \"new\", { timer: \"full\" }),\n    t(\"full-at-once\", \"limited\", \"idle\", \"new\", {\n      timer: \"full\",\n      guard: \"burst = 1: the one token is back when the bucket is full\",\n    }),\n  ],\n};\n\n/**\n * A sliding window of one key, as a `mark1russell7.machine/1` document. The store keeps the time of\n * each permitted take of the key in the window, and each take counts for one window from its time.\n * - A take is permitted when fewer than `limit` takes are in the window.\n * - A refused take waits until the oldest take leaves the window: at most one window. That window is\n *   the longest `Retry-After` of the policy (`retry_after@limiter` of the law).\n * - One window after the last take, no take is in the window, and the key is equal to a new key.\n *   That window is the idle span, and the longest wait of a new key at the cap of keys\n *   (`retry_after_at_cap@limiter`).\n */\nexport const SLIDING_WINDOW_MACHINE: Machine = {\n  ...COMMON,\n  id: \"service.machine.limiter.sliding-window\",\n  title: \"A sliding window of one key of the keyed limiter\",\n  events: EVENTS,\n  knobs: {\n    limit: count(\"limiters.<name>.policy.limit\"),\n    window: { key: \"limiters.<name>.policy.window\", scope: \"limiter\", unit: \"s\", default: null },\n    ...KNOBS,\n  },\n  timers: {\n    oldest: {\n      duration: { knob: \"window\", unit: \"s\" },\n      early: { knob: \"window\", unit: \"s\" },\n      arms: [\"enter:limited\"],\n      cancels: [\"idle\"],\n      fires: \"unit.back\",\n      note: \"the oldest take leaves the window at most one window after the take that filled it. The Retry-After of each refusal is the time to this firing\",\n    },\n    last: {\n      duration: { knob: \"window\", unit: \"s\" },\n      arms: [\"take\"],\n      fires: \"idle\",\n      note: \"the last permitted take leaves the window one window after its time. A refused take does not move it\",\n    },\n  },\n  transitions: [\n    t(\"first\", \"new\", \"take\", \"open\", { guard: \"limit > 1\", emits: [\"allow\"] }),\n    t(\"first-last\", \"new\", \"take\", \"limited\", { guard: \"limit = 1\", emits: [\"allow\"] }),\n    t(\"take\", \"open\", \"take\", \"open\", { guard: \"fewer than limit - 1 takes are in the window before the take\", emits: [\"allow\"] }),\n    t(\"take-last\", \"open\", \"take\", \"limited\", { guard: \"the take is the limit-th take in the window\", emits: [\"allow\"] }),\n    ...COMMON_TRANSITIONS,\n    t(\"oldest-leaves\", \"limited\", \"unit.back\", \"open\", { timer: \"oldest\", guard: \"a later take stays in the window\" }),\n    t(\"last-leaves\", \"open\", \"idle\", \"new\", { timer: \"last\" }),\n    t(\"all-leave\", \"limited\", \"idle\", \"new\", {\n      timer: \"last\",\n      guard: \"each take of the window has one time: limit = 1, or each take came at once\",\n    }),\n  ],\n};\n\n/** This function gives the machine document of the policy of a limiter. */\nexport const limiterMachine = (policy: LimitPolicy): Machine =>\n  policy.type === \"token-bucket\" ? TOKEN_BUCKET_MACHINE : SLIDING_WINDOW_MACHINE;\n\n/**\n * This function gives the state of a key of a store as its machine document names it, at the time\n * `now` in milliseconds. `state` is what the store keeps for the key, or `undefined` when it keeps\n * nothing. A key equal to a new key is `new`, and a key whose next take `decide` refuses is `limited`.\n */\nexport const limiterStateOf = (rule: LimitRule, state: KeyState | undefined, now: number): LimiterState => {\n  if (state === undefined || freeAt(rule, state) <= now) return \"new\";\n  return decide(rule, state, now).decision.allowed ? \"open\" : \"limited\";\n};\n"],"mappings":"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"}

package/build/limiter.d.ts

@@ -1,3 +1,4 @@
 import { S as retryAfterSeconds, _ as freeAt, a as LimitRule, b as limiterProblems, c as LimiterSpec, d as Refused, f as SlidingWindow, g as decide, h as TokenBucket, i as LimitPolicy, l as LimiterStoreSpec, m as TakeStep, n as Decision, o as Limiter, p as StoreFailure, r as KeyState, s as LimiterEviction, t as Allowed, u as RefusalCause, v as idleSpan, x as longestRetryAfter, y as limitRule } from "./policy-G4QJ1ZZq.js";
 import { a as keyedLimiter, i as TakeRequest, n as LimiterStore, o as memoryStore, r as MemoryStore, t as KeyedLimiter } from "./store-DzTyosou.js";
-export { type Allowed, type Decision, type KeyState, type KeyedLimiter, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterStore, type LimiterStoreSpec, type MemoryStore, type RefusalCause, type Refused, type SlidingWindow, type StoreFailure, type TakeRequest, type TakeStep, type TokenBucket, decide, freeAt, idleSpan, keyedLimiter, limitRule, limiterProblems, longestRetryAfter, memoryStore, retryAfterSeconds };
+import { a as limiterStateOf, i as limiterMachine, n as SLIDING_WINDOW_MACHINE, r as TOKEN_BUCKET_MACHINE, t as LimiterState } from "./limiter-DCDdzVwe.js";
+export { type Allowed, type Decision, type KeyState, type KeyedLimiter, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type MemoryStore, type RefusalCause, type Refused, SLIDING_WINDOW_MACHINE, type SlidingWindow, type StoreFailure, TOKEN_BUCKET_MACHINE, type TakeRequest, type TakeStep, type TokenBucket, decide, freeAt, idleSpan, keyedLimiter, limitRule, limiterMachine, limiterProblems, limiterStateOf, longestRetryAfter, memoryStore, retryAfterSeconds };

package/build/limiter.js

@@ -1,3 +1,3 @@
 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 { n as memoryStore, t as keyedLimiter } from "./limiter-wv0uXDk9.js";
-export { decide, freeAt, idleSpan, keyedLimiter, limitRule, limiterProblems, longestRetryAfter, memoryStore, retryAfterSeconds };
+import { a as keyedLimiter, i as limiterStateOf, n as TOKEN_BUCKET_MACHINE, o as memoryStore, r as limiterMachine, t as SLIDING_WINDOW_MACHINE } from "./limiter-pkBZUp-t.js";
+export { SLIDING_WINDOW_MACHINE, TOKEN_BUCKET_MACHINE, decide, freeAt, idleSpan, keyedLimiter, limitRule, limiterMachine, limiterProblems, limiterStateOf, longestRetryAfter, memoryStore, retryAfterSeconds };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/service",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "A service declared as data before it starts, and its runtime: checks on jittered loops, a latch for each policy, probes from the cache, the startup in its sequence, and a staged, capped drain. The timer-ordering law checks the declaration. Its clock, heartbeat and backoff also work alone, in a browser too.",
   "keywords": [
     "service",
@@ -90,7 +90,7 @@
   },
   "devDependencies": {
     "@mark1russell7/cue": "github:mark1russell7/cue",
-    "@mark1russell7/harness": "^0.11.19",
+    "@mark1russell7/harness": "^0.11.21",
     "@types/node": "^26.6.4",
     "ioredis": "6.0.0",
     "testcontainers": "12.2.0",

package/build/limiter-wv0uXDk9.js

@@ -1,126 +0,0 @@
-import { a as limiterProblems, i as limitRule, n as freeAt, o as longestRetryAfter, t as decide } from "./policy-CgS4y94U.js";
-import { convertExact, rationals } from "@mark1russell7/quantity";
-//#region src/limiter/store.ts
-const ms = (value) => ({
-	value,
-	unit: "ms"
-});
-/**
-* This function makes the store of one replica. It reads time only through the clock. Thus a step
-* of the wall clock does not move a count, and a fake clock gives exact decisions in a test.
-* - The eviction is exact. A key whose bucket is full again, or whose window has no take, is equal
-*   to a new key. The store removes it at its next take, or at a sweep.
-* - The count of keys has a bound. At the cap, a take of a new key sweeps the table, but only when
-*   a held key can be free. Each sweep reads each key one time. When no key is free, the store
-*   refuses the new key with the cause `cap`. Its `retryAfter` is at most the time until the
-*   earliest held key is free, and that time is at most `idleSpan` of the policy.
-*/
-const memoryStore = (clock) => {
-	const tables = /* @__PURE__ */ new Map();
-	const sweep = (table, rule, now) => {
-		let next = Number.POSITIVE_INFINITY;
-		for (const [key, state] of table.states) {
-			const free = freeAt(rule, state);
-			if (free <= now) table.states.delete(key);
-			else next = Math.min(next, free);
-		}
-		table.next = next;
-	};
-	return {
-		kind: "local",
-		take({ limiter, key, rule, maxKeys }) {
-			const now = clock.now();
-			let table = tables.get(limiter);
-			if (table === void 0) {
-				table = {
-					states: /* @__PURE__ */ new Map(),
-					next: Number.POSITIVE_INFINITY
-				};
-				tables.set(limiter, table);
-			}
-			let state = table.states.get(key);
-			if (state !== void 0 && freeAt(rule, state) <= now) {
-				table.states.delete(key);
-				state = void 0;
-			}
-			if (state === void 0 && table.states.size >= maxKeys) {
-				if (table.next <= now) sweep(table, rule, now);
-				if (table.states.size >= maxKeys) return {
-					allowed: false,
-					retryAfter: ms(table.next - now),
-					cause: "cap"
-				};
-			}
-			const step = decide(rule, state, now);
-			if (state === void 0) {
-				table.states.set(key, step.state);
-				table.next = Math.min(table.next, freeAt(rule, step.state));
-			} else table.states.set(key, step.state);
-			return step.decision;
-		},
-		size(limiter) {
-			return tables.get(limiter)?.states.size ?? 0;
-		}
-	};
-};
-/** This function gives the text of a failure. */
-const failureOf = (error) => error instanceof Error ? error.message : String(error);
-/**
-* This function makes the runtime of a limiter from its spec and its store. It refuses a spec with a
-* problem, because the limiter has no defaults. It also refuses a store of the wrong kind: a spec
-* with a shared store needs a store that the replicas share.
-* - A failure of a shared store gives the decision of `onStoreFailure`. With `open`, the take is
-*   permitted with `remaining` 0. With `closed`, it is refused with the cause `store`.
-* - The `retryAfter` of the cause `store` is the longest `retryAfter` of the policy.
-* - A failure of a local store rejects the take, because a local store has no `onStoreFailure`.
-*/
-const keyedLimiter = (name, spec, store) => {
-	const problems = limiterProblems(name, spec);
-	if (problems.length > 0) throw new Error(problems.join("; "));
-	if (store.kind !== spec.store.kind) throw new Error(`limiter ${name} declares a ${spec.store.kind} store, but the store that it got is ${store.kind}`);
-	const rule = limitRule(spec.policy);
-	const maxKeys = rationals.toNumber(convertExact(rationals.fromNumber(spec.evict.maxKeys.value), spec.evict.maxKeys.unit, "count"));
-	const onStoreFailure = spec.store.kind === "shared" ? spec.store.onStoreFailure : void 0;
-	const closedAfter = longestRetryAfter(spec.policy);
-	const take = async (key) => {
-		const request = {
-			limiter: name,
-			key,
-			rule,
-			maxKeys
-		};
-		if (onStoreFailure === void 0) return store.take(request);
-		try {
-			return await store.take(request);
-		} catch (error) {
-			const failure = failureOf(error);
-			if (onStoreFailure === "open") return {
-				allowed: true,
-				remaining: 0,
-				failure
-			};
-			return {
-				allowed: false,
-				retryAfter: { ...closedAfter },
-				cause: "store",
-				failure
-			};
-		}
-	};
-	return {
-		name,
-		spec: {
-			key: spec.key,
-			policy: { ...spec.policy },
-			store: { ...spec.store },
-			evict: { maxKeys: { ...spec.evict.maxKeys } }
-		},
-		rule,
-		maxKeys,
-		take
-	};
-};
-//#endregion
-export { memoryStore as n, keyedLimiter as t };
-
-//# sourceMappingURL=limiter-wv0uXDk9.js.map

package/build/limiter-wv0uXDk9.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"limiter-wv0uXDk9.js","names":["r"],"sources":["../src/limiter/store.ts"],"sourcesContent":["import type { Quantity } from \"@mark1russell7/quantity\";\nimport { convertExact, rationals as r } from \"@mark1russell7/quantity\";\nimport type { Clock } from \"../clock.ts\";\nimport type { Decision, KeyState, LimiterSpec, LimitRule } from \"./policy.ts\";\nimport { decide, freeAt, limitRule, limiterProblems, longestRetryAfter } from \"./policy.ts\";\n\n/** A take request is one take of one key, with the rule and the cap of its limiter in numbers. */\nexport interface TakeRequest {\n  /** This name is the limiter. A store keeps the keys of each limiter apart. */\n  readonly limiter: string;\n  readonly key: string;\n  readonly rule: LimitRule;\n  /** This count is the most keys that the store holds for the limiter. */\n  readonly maxKeys: number;\n}\n\n/**\n * A limiter store keeps the state of each key, and it decides each take in one atomic step, on its\n * own clock. Thus two takes of one key do not read the same state at any time. A store in this\n * process uses `decide`. A store that the replicas share does the same arithmetic in one step of its\n * own, for example one script of Redis that reads `TIME`.\n */\nexport interface LimiterStore {\n  /** This kind tells where the counts are: in the memory of this replica, or in a store that the replicas share. */\n  readonly kind: \"local\" | \"shared\";\n  /**\n   * This method decides one take. It removes a key only when its state is equal to the state of a\n   * new key. It holds at most `maxKeys` keys for each limiter. A failure of a shared store rejects\n   * the take, and the limiter then applies the `onStoreFailure` of its spec.\n   */\n  take(request: TakeRequest): Decision | Promise<Decision>;\n}\n\n/** A memory store is the store of one replica, on the injected monotonic clock. */\nexport interface MemoryStore extends LimiterStore {\n  readonly kind: \"local\";\n  /** This method gives the count of keys that the store holds for a limiter. */\n  size(limiter: string): number;\n}\n\n/** A table is the keys of one limiter in a memory store. */\ninterface Table {\n  readonly states: Map<string, KeyState>;\n  /**\n   * This time is at or before the earliest time at which a held key is equal to a new key. An\n   * insert lowers it, and a sweep sets it again. A take of a held key only moves the time of that\n   * key later, thus the bound stays true.\n   */\n  next: number;\n}\n\nconst ms = (value: number): Quantity => ({ value, unit: \"ms\" });\n\n/**\n * This function makes the store of one replica. It reads time only through the clock. Thus a step\n * of the wall clock does not move a count, and a fake clock gives exact decisions in a test.\n * - The eviction is exact. A key whose bucket is full again, or whose window has no take, is equal\n *   to a new key. The store removes it at its next take, or at a sweep.\n * - The count of keys has a bound. At the cap, a take of a new key sweeps the table, but only when\n *   a held key can be free. Each sweep reads each key one time. When no key is free, the store\n *   refuses the new key with the cause `cap`. Its `retryAfter` is at most the time until the\n *   earliest held key is free, and that time is at most `idleSpan` of the policy.\n */\nexport const memoryStore = (clock: Clock): MemoryStore => {\n  const tables = new Map<string, Table>();\n  const sweep = (table: Table, rule: LimitRule, now: number): void => {\n    let next = Number.POSITIVE_INFINITY;\n    for (const [key, state] of table.states) {\n      const free = freeAt(rule, state);\n      if (free <= now) table.states.delete(key);\n      else next = Math.min(next, free);\n    }\n    table.next = next;\n  };\n  return {\n    kind: \"local\",\n    take({ limiter, key, rule, maxKeys }) {\n      const now = clock.now();\n      let table = tables.get(limiter);\n      if (table === undefined) {\n        table = { states: new Map(), next: Number.POSITIVE_INFINITY };\n        tables.set(limiter, table);\n      }\n      let state = table.states.get(key);\n      // a key that is equal to a new key goes: the decision is the same, and it frees its slot\n      if (state !== undefined && freeAt(rule, state) <= now) {\n        table.states.delete(key);\n        state = undefined;\n      }\n      if (state === undefined && table.states.size >= maxKeys) {\n        if (table.next <= now) sweep(table, rule, now);\n        if (table.states.size >= maxKeys) return { allowed: false, retryAfter: ms(table.next - now), cause: \"cap\" };\n      }\n      const step = decide(rule, state, now);\n      if (state === undefined) {\n        // a new key is never refused by its policy: a full bucket, or an empty window\n        table.states.set(key, step.state);\n        table.next = Math.min(table.next, freeAt(rule, step.state));\n      } else table.states.set(key, step.state);\n      return step.decision;\n    },\n    size(limiter) {\n      return tables.get(limiter)?.states.size ?? 0;\n    },\n  };\n};\n\n/** A keyed limiter is the runtime of one declared limiter: its spec, its rule in numbers, and its store. */\nexport interface KeyedLimiter {\n  readonly name: string;\n  /** This spec is the declaration, the same data that `svc.limiter(name, spec)` takes and `describe()` shows. */\n  readonly spec: LimiterSpec;\n  readonly rule: LimitRule;\n  /** This count is the most keys that the store holds for the limiter. */\n  readonly maxKeys: number;\n  /**\n   * This method takes one unit for a key, and gives the decision of the store. When a shared store\n   * fails, it gives the decision of `onStoreFailure`, with the failure as text.\n   */\n  take(key: string): Promise<Decision>;\n}\n\n/** This function gives the text of a failure. */\nconst failureOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));\n\n/**\n * This function makes the runtime of a limiter from its spec and its store. It refuses a spec with a\n * problem, because the limiter has no defaults. It also refuses a store of the wrong kind: a spec\n * with a shared store needs a store that the replicas share.\n * - A failure of a shared store gives the decision of `onStoreFailure`. With `open`, the take is\n *   permitted with `remaining` 0. With `closed`, it is refused with the cause `store`.\n * - The `retryAfter` of the cause `store` is the longest `retryAfter` of the policy.\n * - A failure of a local store rejects the take, because a local store has no `onStoreFailure`.\n */\nexport const keyedLimiter = (name: string, spec: LimiterSpec, store: LimiterStore): KeyedLimiter => {\n  const problems = limiterProblems(name, spec);\n  if (problems.length > 0) throw new Error(problems.join(\"; \"));\n  if (store.kind !== spec.store.kind)\n    throw new Error(`limiter ${name} declares a ${spec.store.kind} store, but the store that it got is ${store.kind}`);\n  const rule = limitRule(spec.policy);\n  const maxKeys = r.toNumber(convertExact(r.fromNumber(spec.evict.maxKeys.value), spec.evict.maxKeys.unit, \"count\"));\n  const onStoreFailure = spec.store.kind === \"shared\" ? spec.store.onStoreFailure : undefined;\n  const closedAfter = longestRetryAfter(spec.policy);\n  const take = async (key: string): Promise<Decision> => {\n    const request: TakeRequest = { limiter: name, key, rule, maxKeys };\n    if (onStoreFailure === undefined) return store.take(request);\n    try {\n      return await store.take(request);\n    } catch (error) {\n      const failure = failureOf(error);\n      if (onStoreFailure === \"open\") return { allowed: true, remaining: 0, failure };\n      return { allowed: false, retryAfter: { ...closedAfter }, cause: \"store\", failure };\n    }\n  };\n  return {\n    name,\n    spec: {\n      key: spec.key,\n      policy: { ...spec.policy },\n      store: { ...spec.store },\n      evict: { maxKeys: { ...spec.evict.maxKeys } },\n    },\n    rule,\n    maxKeys,\n    take,\n  };\n};\n"],"mappings":"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"}