@mark1russell7/service 0.5.2 → 0.5.3

package/build/policy-G4QJ1ZZq.d.ts

@@ -0,0 +1,176 @@
+import { Quantity } from "@mark1russell7/quantity";
+//#region src/limiter/policy.d.ts
+/**
+ * A token bucket gives each key a bucket of `burst` tokens. The bucket refills at `rate`, and each
+ * take uses one token. Thus a key can make `burst` takes at once after an idle time, and then
+ * `rate` takes in each unit of time.
+ */
+interface TokenBucket {
+  readonly type: "token-bucket";
+  /** This rate is how fast the bucket refills: a count for each unit of time, for example `{ value: 10, unit: "count/s" }`. */
+  readonly rate: Quantity;
+  /** This count is the size of the bucket: the most takes in a sequence after an idle time. */
+  readonly burst: Quantity;
+}
+/**
+ * A sliding window gives each key at most `limit` takes in each `window`. Each take counts for one
+ * window from its time, thus the window moves with the clock and has no fixed edges.
+ */
+interface SlidingWindow {
+  readonly type: "sliding-window";
+  /** This count is the most takes of one key in one window. */
+  readonly limit: Quantity;
+  /** This time is the length of the window. */
+  readonly window: Quantity;
+}
+/** A limit policy is the rule that a keyed limiter applies to each key, as data. It has no defaults. */
+type LimitPolicy = TokenBucket | SlidingWindow;
+/**
+ * A store failure policy tells what a take does when a shared store fails. It has no default.
+ * - `open`: the limiter lets the take in. The count is not known, thus `remaining` is 0.
+ * - `closed`: the limiter refuses the take with the cause `store`. Its `retryAfter` is the longest
+ *   `retryAfter` of the policy (`longestRetryAfter`). Thus O29 and O30 apply to it too.
+ */
+type StoreFailure = "open" | "closed";
+/**
+ * A store spec tells where the counts of the keys are:
+ * - `local`: in the memory of each replica. A limit L over N replicas is then L / N on each
+ *   replica. That sum holds only on average, when the balancer spreads the takes of each key evenly.
+ *   A local store does not fail, thus it has no `onStoreFailure`, and the limiter ignores one.
+ * - `shared`: in a store that the replicas share, the dependency of that name. The store decides
+ *   each take in one atomic step, on its own clock. Thus the limit holds across the replicas.
+ *   `onStoreFailure` tells what a take does when the store fails.
+ */
+type LimiterStoreSpec = {
+  readonly kind: "local";
+} | {
+  readonly kind: "shared";
+  readonly dependency: string;
+  readonly onStoreFailure: StoreFailure;
+};
+/**
+ * The eviction of a limiter bounds its keys. A store removes a key only when its state is equal to
+ * the state of a new key. That is a bucket that is full again, or a window with no take in it.
+ * Thus an eviction changes no decision.
+ */
+interface LimiterEviction {
+  /**
+   * This count is the most keys that the store holds. At the cap, the store refuses a take of a new
+   * key until a held key is idle for its span (`idleSpan`). A held key keeps its count.
+   */
+  readonly maxKeys: Quantity;
+}
+/** A limiter spec is the declaration of one keyed limiter. Each part is necessary, because the limiter has no defaults. */
+interface LimiterSpec {
+  /** This text tells what the key of each take is, for example `tenant` or `principal`. The caller gives each key. */
+  readonly key: string;
+  readonly policy: LimitPolicy;
+  readonly store: LimiterStoreSpec;
+  readonly evict: LimiterEviction;
+}
+/** A limiter is a keyed limiter in the description of a service: its name and its spec. */
+interface Limiter extends LimiterSpec {
+  readonly name: string;
+}
+/**
+ * A refusal cause tells why a take is refused:
+ * - `limit`: the key used its limit.
+ * - `cap`: the store holds its cap of keys, and the key is new.
+ * - `store`: the shared store failed, and its spec declares `onStoreFailure: "closed"`.
+ */
+type RefusalCause = "limit" | "cap" | "store";
+/** A permitted take used one unit of its key. `remaining` is the count of takes that the key can make at this time. */
+interface Allowed {
+  readonly allowed: true;
+  readonly remaining: number;
+  /** This text is the failure of a shared store, when `onStoreFailure: "open"` lets the take in. */
+  readonly failure?: string | undefined;
+}
+/**
+ * A refused take used nothing. `retryAfter` is the time until the limiter lets the same take in, when
+ * no other take comes first. It is always above zero.
+ */
+interface Refused {
+  readonly allowed: false;
+  readonly retryAfter: Quantity;
+  readonly cause: RefusalCause;
+  /** This text is the failure of a shared store, for the cause `store`. */
+  readonly failure?: string | undefined;
+}
+/** A decision is the answer of a limiter to one take. */
+type Decision = Allowed | Refused;
+/**
+ * A limit rule is a policy in numbers, which a store applies: each time in milliseconds, and each
+ * count as a number. A store in another process, for example a script of Redis, gets these numbers.
+ */
+type LimitRule = {
+  readonly type: "token-bucket";
+  /** This time is the refill of one token, in milliseconds. */
+  readonly interval: number;
+  readonly burst: number;
+} | {
+  readonly type: "sliding-window";
+  readonly limit: number;
+  /** This time is the length of the window, in milliseconds. */
+  readonly window: number;
+};
+/**
+ * A key state is what a store keeps for one key:
+ * - A token bucket keeps the time at which its bucket is full again (`full`, in milliseconds).
+ * - A sliding window keeps the time of each permitted take in the window, the oldest first.
+ */
+type KeyState = {
+  readonly type: "token-bucket";
+  readonly full: number;
+} | {
+  readonly type: "sliding-window";
+  readonly stamps: readonly number[];
+};
+/** A step is the decision of one take, and the state of its key after the take. A refusal keeps the count of the key. */
+interface TakeStep {
+  readonly decision: Decision;
+  readonly state: KeyState;
+}
+/**
+ * This function gives the problems of a limiter spec. `describe()` and `keyedLimiter` refuse a spec
+ * with a problem. A part that is absent is a problem, because the limiter has no defaults.
+ */
+declare const limiterProblems: (name: string, spec: Partial<LimiterSpec> | undefined) => string[];
+/**
+ * This function gives the rule of a policy in numbers. The interval of a bucket is exact as a
+ * rational, and it becomes one number only at the end. Thus 10 for each minute gives 6000 ms.
+ */
+declare const limitRule: (policy: LimitPolicy) => LimitRule;
+/**
+ * This function gives the span after which an idle key is equal to a new key. That span is
+ * `burst / rate` for a token bucket, and one window for a sliding window. A store can remove the key
+ * after it, and no decision changes. It is also the longest `retryAfter` of a new key that the store
+ * refuses at its cap.
+ */
+declare const idleSpan: (policy: LimitPolicy) => Quantity;
+/**
+ * This function gives the longest `retryAfter` of a refusal by the policy: one interval of the
+ * bucket (`1 / rate`), or one window. A refusal at the cap of keys can be longer, up to `idleSpan`.
+ */
+declare const longestRetryAfter: (policy: LimitPolicy) => Quantity;
+/**
+ * This function gives a `retryAfter` in whole seconds, rounded up, as the header `Retry-After`
+ * (RFC 9110) has it. A time over a whole second by less than one nanosecond rounds down to it,
+ * because that part is an error of floating point.
+ */
+declare const retryAfterSeconds: (retryAfter: Quantity) => number;
+/** This function gives the time at which a key state is equal to the state of a new key, in milliseconds. */
+declare const freeAt: (rule: LimitRule, state: KeyState) => number;
+/**
+ * This function decides one take of a key at the time `now`, in milliseconds, from the state of the
+ * key (`undefined` for a new key). It is the one decision of each store in this process. A store in
+ * another process does the same arithmetic in its own atomic step.
+ * - A token bucket (GCRA): the store lets the take in when, with the take, the bucket is full
+ *   again in at most `burst` intervals. A refusal waits until one token is back.
+ * - A sliding window: the store lets the take in when fewer than `limit` takes are in the window.
+ *   A refusal waits until the oldest take leaves the window.
+ */
+declare const decide: (rule: LimitRule, state: KeyState | undefined, now: number) => TakeStep;
+//#endregion
+export { retryAfterSeconds as S, freeAt as _, LimitRule as a, limiterProblems as b, LimiterSpec as c, Refused as d, SlidingWindow as f, decide as g, TokenBucket as h, LimitPolicy as i, LimiterStoreSpec as l, TakeStep as m, Decision as n, Limiter as o, StoreFailure as p, KeyState as r, LimiterEviction as s, Allowed as t, RefusalCause as u, idleSpan as v, longestRetryAfter as x, limitRule as y };
+//# sourceMappingURL=policy-G4QJ1ZZq.d.ts.map

package/build/redis.d.ts

@@ -1,7 +1,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-DjEpgpRk.js";
-import { n as ServiceBuilder } from "./builder-BzjhWk2E.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 { Extent, Quantity } from "@mark1russell7/quantity";
 import { Machine } from "@mark1russell7/algebra";
 //#region src/redis/connection.d.ts

package/build/testing.d.ts

@@ -1,6 +1,6 @@
 import { n as Clock } from "./clock-D-38uH_z.js";
-import { D as Outcome, E as CheckFn, ct as ExitTrigger, d as TransportImpl, pt as ProcessPort, r as Lifecycle, st as ExitSignal } from "./lifecycle-DjEpgpRk.js";
-import { n as ServiceBuilder } from "./builder-BzjhWk2E.js";
+import { D as Outcome, E as CheckFn, ct as ExitTrigger, d as TransportImpl, pt as ProcessPort, r as Lifecycle, st as ExitSignal } from "./lifecycle-Chu9Pri2.js";
+import { n as ServiceBuilder } from "./builder-DyDB7zM9.js";
 //#region src/fakes.d.ts
 /** A fake clock moves only when a test tells it to. */
 interface FakeClock extends Clock {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/service",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "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",
@@ -11,7 +11,8 @@
     "graceful-shutdown",
     "idempotency",
     "timeouts",
-    "kubernetes"
+    "kubernetes",
+    "rate-limit"
   ],
   "homepage": "https://mark1russell7.github.io/systems/",
   "repository": {
@@ -57,6 +58,10 @@
       "types": "./build/http.d.ts",
       "default": "./build/http.js"
     },
+    "./limiter": {
+      "types": "./build/limiter.d.ts",
+      "default": "./build/limiter.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -68,7 +73,7 @@
     "node": ">=22.19"
   },
   "dependencies": {
-    "@mark1russell7/algebra": "^0.7.1",
+    "@mark1russell7/algebra": "^0.7.2",
     "@mark1russell7/quantity": "^0.2.0"
   },
   "peerDependencies": {
@@ -85,7 +90,7 @@
   },
   "devDependencies": {
     "@mark1russell7/cue": "github:mark1russell7/cue",
-    "@mark1russell7/harness": "^0.11.4",
+    "@mark1russell7/harness": "^0.11.18",
     "@types/node": "^26.6.4",
     "ioredis": "6.0.0",
     "testcontainers": "12.2.0",