@mark1russell7/service 0.5.3 → 0.5.5

package/build/{knobs-BxG-c7Zb.js → knobs-BZAsgb5H.js}

@@ -1,4 +1,18 @@
 import { convertible, valueIn } from "@mark1russell7/quantity";
+//#region src/drains.ts
+const holds = /* @__PURE__ */ new WeakMap();
+/** This function adds the hold of a drain under its lifecycle. It gives the function that removes the hold. */
+const holdLate = (life, hold) => {
+	const set = holds.get(life) ?? /* @__PURE__ */ new Set();
+	holds.set(life, set);
+	set.add(hold);
+	return () => {
+		set.delete(hold);
+	};
+};
+/** This function gives the hold of each drain under a lifecycle, as it is at this time. */
+const lateHolds = (life) => [...holds.get(life) ?? []].map((hold) => hold());
+//#endregion
 //#region src/knobs.ts
 /**
 * This function gives a time knob in milliseconds, or infinity for a time without a bound. The
@@ -34,6 +48,6 @@ const countOf = (knobs, name, owner) => {
 	return value;
 };
 //#endregion
-export { countOf as n, millisecondsOf as r, boundedMillisecondsOf as t };
+export { lateHolds as a, holdLate as i, countOf as n, millisecondsOf as r, boundedMillisecondsOf as t };
 
-//# sourceMappingURL=knobs-BxG-c7Zb.js.map
+//# sourceMappingURL=knobs-BZAsgb5H.js.map

package/build/knobs-BZAsgb5H.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knobs-BZAsgb5H.js","names":[],"sources":["../src/drains.ts","../src/knobs.ts"],"sourcesContent":["// The holds of the drains after their deadline (SYS-29). A transport that waits after the deadline of\n// its drain gives its hold under its lifecycle. At the cap of the drain, the lifecycle reads each hold.\n// A drain that waits only for the bytes of its answers did its work, thus the phase does not fail.\n\n/** A late hold tells what holds the drain of a transport after its deadline. */\nexport interface LateHold {\n  /** This count is the number of calls whose end did not come: their handler still runs. */\n  readonly running: number;\n  /** This count is the number of answers whose bytes did not go to the client, for example to a client that does not read. */\n  readonly unflushed: number;\n}\n\nconst holds = new WeakMap<object, Set<() => LateHold>>();\n\n/** This function adds the hold of a drain under its lifecycle. It gives the function that removes the hold. */\nexport const holdLate = (life: object, hold: () => LateHold): (() => void) => {\n  const set = holds.get(life) ?? new Set<() => LateHold>();\n  holds.set(life, set);\n  set.add(hold);\n  return () => {\n    set.delete(hold);\n  };\n};\n\n/** This function gives the hold of each drain under a lifecycle, as it is at this time. */\nexport const lateHolds = (life: object): LateHold[] => [...(holds.get(life) ?? [])].map((hold) => hold());\n","import type { Extent } from \"@mark1russell7/quantity\";\nimport { convertible, valueIn } from \"@mark1russell7/quantity\";\n\n/** A knob record is the knobs of a part, by name. A knob that is absent is undefined. */\nexport type KnobRecord = Readonly<Record<string, Extent | undefined>>;\n\n/**\n * This function gives a time knob in milliseconds, or infinity for a time without a bound. The\n * runtime has no defaults, thus a knob that is absent throws. A knob that is not a time, or that is\n * less than zero, also throws.\n */\nexport const millisecondsOf = (knobs: KnobRecord, name: string, owner: string): number => {\n  const amount = knobs[name];\n  if (amount === undefined) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);\n  if (!convertible(amount.unit, \"s\")) throw new Error(`the knob ${name} is not a time`);\n  if (amount.value === \"infinite\") return Number.POSITIVE_INFINITY;\n  const value = valueIn(amount, \"ms\");\n  if (!(value >= 0)) throw new Error(`the knob ${name} is less than zero`);\n  return value;\n};\n\n/** This function gives a time knob in milliseconds, and it throws for a time without a bound. */\nexport const boundedMillisecondsOf = (knobs: KnobRecord, name: string, owner: string): number => {\n  const value = millisecondsOf(knobs, name, owner);\n  if (!Number.isFinite(value)) throw new Error(`the knob ${name} of ${owner} has no bound: it needs a time`);\n  return value;\n};\n\n/**\n * This function gives a count knob (the unit `count`) as a whole number above zero, or infinity\n * for a count without a bound. A knob that is absent, not a count, or not a whole number above zero throws.\n */\nexport const countOf = (knobs: KnobRecord, name: string, owner: string): number => {\n  const amount = knobs[name];\n  if (amount === undefined) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);\n  if (!convertible(amount.unit, \"count\")) throw new Error(`the knob ${name} is not a count`);\n  if (amount.value === \"infinite\") return Number.POSITIVE_INFINITY;\n  const value = valueIn(amount, \"count\");\n  if (!(Number.isInteger(value) && value >= 1)) throw new Error(`the knob ${name} is ${value}, not a whole number above zero`);\n  return value;\n};\n"],"mappings":";;AAYA,MAAM,wBAAQ,IAAI,QAAqC;;AAGvD,MAAa,YAAY,MAAc,SAAuC;CAC5E,MAAM,MAAM,MAAM,IAAI,IAAI,qBAAK,IAAI,IAAoB;CACvD,MAAM,IAAI,MAAM,GAAG;CACnB,IAAI,IAAI,IAAI;CACZ,aAAa;EACX,IAAI,OAAO,IAAI;CACjB;AACF;;AAGA,MAAa,aAAa,SAA6B,CAAC,GAAI,MAAM,IAAI,IAAI,KAAK,CAAC,CAAE,CAAC,CAAC,KAAK,SAAS,KAAK,CAAC;;;;;;;;ACdxG,MAAa,kBAAkB,OAAmB,MAAc,UAA0B;CACxF,MAAM,SAAS,MAAM;CACrB,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,GAAG,MAAM,kBAAkB,KAAK,qBAAqB;CAC/F,IAAI,CAAC,YAAY,OAAO,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,YAAY,KAAK,eAAe;CACpF,IAAI,OAAO,UAAU,YAAY,OAAO,OAAO;CAC/C,MAAM,QAAQ,QAAQ,QAAQ,IAAI;CAClC,IAAI,EAAE,SAAS,IAAI,MAAM,IAAI,MAAM,YAAY,KAAK,mBAAmB;CACvE,OAAO;AACT;;AAGA,MAAa,yBAAyB,OAAmB,MAAc,UAA0B;CAC/F,MAAM,QAAQ,eAAe,OAAO,MAAM,KAAK;CAC/C,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,MAAM,YAAY,KAAK,MAAM,MAAM,+BAA+B;CACzG,OAAO;AACT;;;;;AAMA,MAAa,WAAW,OAAmB,MAAc,UAA0B;CACjF,MAAM,SAAS,MAAM;CACrB,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,GAAG,MAAM,kBAAkB,KAAK,qBAAqB;CAC/F,IAAI,CAAC,YAAY,OAAO,MAAM,OAAO,GAAG,MAAM,IAAI,MAAM,YAAY,KAAK,gBAAgB;CACzF,IAAI,OAAO,UAAU,YAAY,OAAO,OAAO;CAC/C,MAAM,QAAQ,QAAQ,QAAQ,OAAO;CACrC,IAAI,EAAE,OAAO,UAAU,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,MAAM,YAAY,KAAK,MAAM,MAAM,gCAAgC;CAC3H,OAAO;AACT"}

package/build/limiter.d.ts

@@ -1,3 +1,3 @@
 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 "./limiter-DzTyosou.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 };

package/build/redis.d.ts

@@ -2,6 +2,7 @@ import { t as Backoff } from "./backoff-B-jGWVDm.js";
 import { n as Clock } from "./clock-D-38uH_z.js";
 import { B as Gate, Ct as Operation, E as CheckFn, G as Step, J as Poll, L as Dependency, M as Recorder, N as Check, W as ServiceDescription, et as heartbeatDetection, t as DependencyHandle } from "./lifecycle-Chu9Pri2.js";
 import { n as ServiceBuilder } from "./builder-DyDB7zM9.js";
+import { n as LimiterStore } from "./store-DzTyosou.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
 import { Machine } from "@mark1russell7/algebra";
 //#region src/redis/connection.d.ts
@@ -273,6 +274,45 @@ export declare const tcpDial: DialFn;
  */
 export declare const redisClient: (name: string, spec: RedisClientSpec, options?: RedisClientOptions) => RedisClient;
 //#endregion
+//#region src/redis/limiter.d.ts
+/**
+ * This script decides one take in one atomic step of Redis. It does the arithmetic of `decide`, and
+ * it reads `TIME` of the server, the one clock of all replicas. A test can give the time in its place.
+ * - KEYS[1] is the state of the key. KEYS[2] is the index of the limiter, a sorted set of its keys
+ *   by the time at which each key is free.
+ * - ARGV is the type of the rule, its two numbers, the cap of keys, the key, and the time or "".
+ * - The state of a bucket is its full time. The state of a window is the time of each take in it.
+ * - The state expires at its free time (PX), and the index lets the cap count only busy keys.
+ * - The reply is `{1, remaining}`, or `{0, retryAfter, cause}` with the time as text. Redis gives
+ *   each Lua number as a whole number, thus the fraction of a millisecond goes as text.
+ */
+export declare const LIMITER_SCRIPT = "\nlocal kind = ARGV[1]\nlocal a = tonumber(ARGV[2])\nlocal b = tonumber(ARGV[3])\nlocal cap = tonumber(ARGV[4])\nlocal member = ARGV[5]\nlocal now\nif ARGV[6] == '' then\n  local t = redis.call('TIME')\n  now = tonumber(t[1]) * 1000 + tonumber(t[2]) / 1000\nelse\n  now = tonumber(ARGV[6])\nend\nlocal TOL = 1e-6\nlocal function num(x) return string.format('%.6f', x) end\nlocal raw = redis.call('GET', KEYS[1])\nlocal full = nil\nlocal stamps = nil\nif raw then\n  if kind == 'token-bucket' then\n    full = tonumber(raw)\n  else\n    stamps = {}\n    for x in string.gmatch(raw, '[^,]+') do stamps[#stamps + 1] = tonumber(x) end\n  end\nend\nlocal function freeAt()\n  if kind == 'token-bucket' then return full end\n  if #stamps == 0 then return -math.huge end\n  return stamps[#stamps] + b\nend\nif raw and freeAt() <= now then\n  redis.call('DEL', KEYS[1])\n  redis.call('ZREM', KEYS[2], member)\n  raw = nil\n  full = nil\n  stamps = nil\nend\nif not raw then\n  if redis.call('ZCARD', KEYS[2]) >= cap then\n    redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', num(now))\n    if redis.call('ZCARD', KEYS[2]) >= cap then\n      local first = redis.call('ZRANGE', KEYS[2], 0, 0, 'WITHSCORES')\n      return {0, num(tonumber(first[2]) - now), 'cap'}\n    end\n  end\nend\nlocal remaining\nlocal state\nif kind == 'token-bucket' then\n  local span = a * b\n  local base = now\n  if full and full > now then base = full end\n  local nxt = base + a\n  if nxt - now > span + TOL then\n    return {0, num(nxt - span - now), 'limit'}\n  end\n  remaining = math.floor((span - (nxt - now)) / a + TOL)\n  if remaining < 0 then remaining = 0 end\n  full = nxt\n  state = num(full)\nelse\n  local live = {}\n  for _, stamp in ipairs(stamps or {}) do\n    if stamp + b > now + TOL then live[#live + 1] = stamp end\n  end\n  if #live >= a then\n    return {0, num(live[1] + b - now), 'limit'}\n  end\n  live[#live + 1] = now\n  remaining = a - #live\n  stamps = live\n  local parts = {}\n  for i, stamp in ipairs(live) do parts[i] = num(stamp) end\n  state = table.concat(parts, ',')\nend\nlocal free = freeAt()\nlocal ttl = math.ceil(free - now)\nif ttl < 1 then ttl = 1 end\nredis.call('SET', KEYS[1], state, 'PX', ttl)\nredis.call('ZADD', KEYS[2], num(free), member)\nif redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end\nreturn {1, remaining}\n";
+/** These options make a store of a limiter in Redis. */
+interface RedisLimiterOptions {
+  /** This text starts the name of each key of the store in Redis, for example `limit:`. It has no braces. */
+  readonly prefix: string;
+  /**
+   * This clock replaces `TIME` of the server, for a test that compares the store with `decide`. Without
+   * it, the script reads `TIME`, thus each replica gets the one clock of the store.
+   */
+  readonly clock?: Clock | undefined;
+}
+/** A Redis client part is the part of a Redis client that the store uses: `send`. */
+type RedisSender = Pick<RedisClient, "send">;
+/**
+ * This function makes a store that the replicas share, in Redis 7. Each take is one `EVAL` of
+ * `LIMITER_SCRIPT`. The client does not send it again, because a second take counts two times.
+ * - The names of the keys have the limiter in braces, a hash tag. Thus the state and the index of a
+ *   limiter are in one slot of a Redis Cluster.
+ * - Each state expires at the time that the key is free, thus the eviction is exact, as in the memory
+ *   store. The index of the limiter bounds the count of busy keys to `maxKeys`.
+ * - A reply of an error, an outcome that is not certain, or a reply of another shape rejects the
+ *   take of the store. `keyedLimiter` then applies the `onStoreFailure` of the spec.
+ * - `TIME` is the wall clock of the Redis host, not a monotonic clock. Thus a step of that clock
+ *   moves the counts of each key. The replicas still share one clock.
+ */
+export declare const redisLimiterStore: (client: RedisSender, options: RedisLimiterOptions) => LimiterStore;
+//#endregion
 //#region src/redis/machine.d.ts
 /**
  * The Redis client as a `mark1russell7.machine/1` document. Its states are the states of ioredis.
@@ -292,5 +332,5 @@ export declare const REDIS_OPERATIONS: Readonly<Record<string, Operation>>;
 /** This function gives the name of a command as the table writes it: upper case, and CLIENT ID with its subcommand. */
 export declare const commandName: (command: string, args: readonly unknown[]) => string;
 //#endregion
-export { type CheckOptions, type ClientStep, type ConnectionFactory, type Detector, type DialFn, type Join, type Meeting, type RedisClient, type RedisClientOptions, type RedisClientSpec, type RedisConnection, type RedisConnectionOptions, type RedisKnobs, type RedisSocket, type Sent, type Situation, heartbeatDetection };
+export { type CheckOptions, type ClientStep, type ConnectionFactory, type Detector, type DialFn, type Join, type Meeting, type RedisClient, type RedisClientOptions, type RedisClientSpec, type RedisConnection, type RedisConnectionOptions, type RedisKnobs, type RedisLimiterOptions, type RedisSender, type RedisSocket, type Sent, type Situation, heartbeatDetection };
 //# sourceMappingURL=redis.d.ts.map

package/build/redis.js

@@ -688,6 +688,159 @@ const redisClient = (name, spec, options = {}) => {
 	};
 };
 //#endregion
+//#region src/redis/limiter.ts
+/**
+* This script decides one take in one atomic step of Redis. It does the arithmetic of `decide`, and
+* it reads `TIME` of the server, the one clock of all replicas. A test can give the time in its place.
+* - KEYS[1] is the state of the key. KEYS[2] is the index of the limiter, a sorted set of its keys
+*   by the time at which each key is free.
+* - ARGV is the type of the rule, its two numbers, the cap of keys, the key, and the time or "".
+* - The state of a bucket is its full time. The state of a window is the time of each take in it.
+* - The state expires at its free time (PX), and the index lets the cap count only busy keys.
+* - The reply is `{1, remaining}`, or `{0, retryAfter, cause}` with the time as text. Redis gives
+*   each Lua number as a whole number, thus the fraction of a millisecond goes as text.
+*/
+const LIMITER_SCRIPT = `
+local kind = ARGV[1]
+local a = tonumber(ARGV[2])
+local b = tonumber(ARGV[3])
+local cap = tonumber(ARGV[4])
+local member = ARGV[5]
+local now
+if ARGV[6] == '' then
+  local t = redis.call('TIME')
+  now = tonumber(t[1]) * 1000 + tonumber(t[2]) / 1000
+else
+  now = tonumber(ARGV[6])
+end
+local TOL = 1e-6
+local function num(x) return string.format('%.6f', x) end
+local raw = redis.call('GET', KEYS[1])
+local full = nil
+local stamps = nil
+if raw then
+  if kind == 'token-bucket' then
+    full = tonumber(raw)
+  else
+    stamps = {}
+    for x in string.gmatch(raw, '[^,]+') do stamps[#stamps + 1] = tonumber(x) end
+  end
+end
+local function freeAt()
+  if kind == 'token-bucket' then return full end
+  if #stamps == 0 then return -math.huge end
+  return stamps[#stamps] + b
+end
+if raw and freeAt() <= now then
+  redis.call('DEL', KEYS[1])
+  redis.call('ZREM', KEYS[2], member)
+  raw = nil
+  full = nil
+  stamps = nil
+end
+if not raw then
+  if redis.call('ZCARD', KEYS[2]) >= cap then
+    redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', num(now))
+    if redis.call('ZCARD', KEYS[2]) >= cap then
+      local first = redis.call('ZRANGE', KEYS[2], 0, 0, 'WITHSCORES')
+      return {0, num(tonumber(first[2]) - now), 'cap'}
+    end
+  end
+end
+local remaining
+local state
+if kind == 'token-bucket' then
+  local span = a * b
+  local base = now
+  if full and full > now then base = full end
+  local nxt = base + a
+  if nxt - now > span + TOL then
+    return {0, num(nxt - span - now), 'limit'}
+  end
+  remaining = math.floor((span - (nxt - now)) / a + TOL)
+  if remaining < 0 then remaining = 0 end
+  full = nxt
+  state = num(full)
+else
+  local live = {}
+  for _, stamp in ipairs(stamps or {}) do
+    if stamp + b > now + TOL then live[#live + 1] = stamp end
+  end
+  if #live >= a then
+    return {0, num(live[1] + b - now), 'limit'}
+  end
+  live[#live + 1] = now
+  remaining = a - #live
+  stamps = live
+  local parts = {}
+  for i, stamp in ipairs(live) do parts[i] = num(stamp) end
+  state = table.concat(parts, ',')
+end
+local free = freeAt()
+local ttl = math.ceil(free - now)
+if ttl < 1 then ttl = 1 end
+redis.call('SET', KEYS[1], state, 'PX', ttl)
+redis.call('ZADD', KEYS[2], num(free), member)
+if redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end
+return {1, remaining}
+`;
+/**
+* This function makes a store that the replicas share, in Redis 7. Each take is one `EVAL` of
+* `LIMITER_SCRIPT`. The client does not send it again, because a second take counts two times.
+* - The names of the keys have the limiter in braces, a hash tag. Thus the state and the index of a
+*   limiter are in one slot of a Redis Cluster.
+* - Each state expires at the time that the key is free, thus the eviction is exact, as in the memory
+*   store. The index of the limiter bounds the count of busy keys to `maxKeys`.
+* - A reply of an error, an outcome that is not certain, or a reply of another shape rejects the
+*   take of the store. `keyedLimiter` then applies the `onStoreFailure` of the spec.
+* - `TIME` is the wall clock of the Redis host, not a monotonic clock. Thus a step of that clock
+*   moves the counts of each key. The replicas still share one clock.
+*/
+const redisLimiterStore = (client, options) => {
+	if (/[{}]/.test(options.prefix)) throw new Error(`the prefix ${options.prefix} of a limiter store has a brace: the store puts the hash tag in it`);
+	return {
+		kind: "shared",
+		async take({ limiter, key, rule, maxKeys }) {
+			const base = `${options.prefix}{${limiter}}`;
+			const numbers = rule.type === "token-bucket" ? [rule.interval, rule.burst] : [rule.limit, rule.window];
+			const now = options.clock === void 0 ? "" : String(options.clock.now());
+			const sent = await client.send("EVAL", [
+				LIMITER_SCRIPT,
+				2,
+				`${base}:key:${key}`,
+				`${base}:keys`,
+				rule.type,
+				String(numbers[0]),
+				String(numbers[1]),
+				String(maxKeys),
+				key,
+				now
+			]);
+			if (sent.outcome !== "ok") throw new Error(`the limiter store ${limiter} failed (${sent.outcome}): ${sent.error}`);
+			return replyOf(limiter, sent.value);
+		}
+	};
+};
+/** This function gives the decision of a reply of `LIMITER_SCRIPT`. A reply of another shape throws. */
+const replyOf = (limiter, reply) => {
+	if (Array.isArray(reply) && Number(reply[0]) === 1 && reply.length === 2) return {
+		allowed: true,
+		remaining: Number(reply[1])
+	};
+	if (Array.isArray(reply) && Number(reply[0]) === 0 && reply.length === 3 && (reply[2] === "limit" || reply[2] === "cap")) {
+		const retryAfter = Number(reply[1]);
+		if (Number.isFinite(retryAfter) && retryAfter > 0) return {
+			allowed: false,
+			retryAfter: {
+				value: retryAfter,
+				unit: "ms"
+			},
+			cause: reply[2]
+		};
+	}
+	throw new Error(`the limiter store ${limiter} gave a reply that is not a decision: ${JSON.stringify(reply)}`);
+};
+//#endregion
 //#region src/redis/machine.ts
 const t = (id, from, on, to, extra = {}) => ({
 	id,
@@ -850,6 +1003,6 @@ const REDIS_CLIENT_MACHINE = {
 	]
 };
 //#endregion
-export { REDIS_CLIENT_MACHINE, REDIS_OPERATIONS, commandName, firstDetector, heartbeatDetection, ioredis, meetings, redisClient, retryBackoff, specProblems, tcpDial, unwatched };
+export { LIMITER_SCRIPT, REDIS_CLIENT_MACHINE, REDIS_OPERATIONS, commandName, firstDetector, heartbeatDetection, ioredis, meetings, redisClient, redisLimiterStore, retryBackoff, specProblems, tcpDial, unwatched };
 
 //# sourceMappingURL=redis.js.map