Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(gfs-controller): monotonic limiter clock and a key cap on the denial log throttle

Alfredo Lopez5ec88f76b8a6
diff --git a/gfs-controller/src/logThrottle.test.ts b/gfs-controller/src/logThrottle.test.ts
index 9543b6c10..971c21359 100644
--- a/gfs-controller/src/logThrottle.test.ts
+++ b/gfs-controller/src/logThrottle.test.ts
@@ -52,7 +52,41 @@ describe("LogThrottle", () => {
expect(throttle.trackedKeyCount).toBe(1);
});
- it("rejects a non-positive interval", () => {
+ it("sends every key past maxKeys to one shared overflow entry, so an interval writes at most maxKeys + 1 lines", () => {
+ let t = 1_000;
+ const throttle = new LogThrottle(60_000, () => t, 3);
+
+ const tracked = ["a", "b", "c"].map((key) => throttle.admit(key));
+ const overflow = Array.from({ length: 50 }, (_, i) => throttle.admit(`new-${i}`));
+
+ // Witness: the three tracked keys each got their line.
+ expect(tracked).toEqual([0, 0, 0]);
+ // Fifty distinct new keys share one line between them.
+ expect(overflow.filter((r) => r !== undefined)).toEqual([0]);
+ expect(throttle.trackedKeyCount).toBe(4);
+ // A tracked key is still throttled on its own entry.
+ expect(throttle.admit("a")).toBeUndefined();
+
+ t += 60_000;
+ // The overflow line carries the combined count of the 49 it suppressed.
+ expect(throttle.admit("new-999")).toBe(49);
+ });
+
+ it("tracks at most 1 000 keys by default", () => {
+ const t = 1_000;
+ const throttle = new LogThrottle(60_000, () => t);
+ const admitted = Array.from({ length: 5_000 }, (_, i) => throttle.admit(`k${i}`)).filter(
+ (r) => r !== undefined,
+ );
+ expect(admitted).toHaveLength(1_001);
+ expect(throttle.trackedKeyCount).toBe(1_001);
+ });
+
+ it("rejects a non-positive interval and a non-positive key cap", () => {
expect(() => new LogThrottle(0)).toThrow(/intervalMs must be > 0/);
+ expect(() => new LogThrottle(1_000, () => 0, 0)).toThrow(/maxKeys must be a positive integer/);
+ expect(() => new LogThrottle(1_000, () => 0, 1.5)).toThrow(
+ /maxKeys must be a positive integer/,
+ );
});
});
diff --git a/gfs-controller/src/logThrottle.ts b/gfs-controller/src/logThrottle.ts
index e282705e5..3cddacfb5 100644
--- a/gfs-controller/src/logThrottle.ts
+++ b/gfs-controller/src/logThrottle.ts
@@ -1,3 +1,6 @@
+/** Distinct keys one throttle tracks before new keys share a single entry. */
+export const LOG_THROTTLE_MAX_KEYS = 1_000;
+
/**
* Bounds how many lines one event writes: at most one per key per interval.
* A suppressed event is only counted, and the next admitted line for that key
@@ -10,6 +13,12 @@
* A count still pending when its key is swept is lost from the log, not from
* the metrics.
*
+ * Keys often come from clients, and a client can send a new one on every
+ * request. Once `maxKeys` keys are tracked, every key not already tracked shares
+ * one overflow entry: together they get at most one line per interval, and that
+ * line carries their combined suppressed count. So one interval writes at most
+ * `maxKeys + 1` lines, and the map holds at most `maxKeys + 1` entries.
+ *
* Same semantics as control-api's `src/observability/logThrottle.ts`.
*/
export class LogThrottle {
@@ -18,9 +27,13 @@ export class LogThrottle {
constructor(
private readonly intervalMs: number,
- private readonly now: () => number = () => Date.now()
+ private readonly now: () => number = () => Date.now(),
+ private readonly maxKeys: number = LOG_THROTTLE_MAX_KEYS,
) {
if (!(intervalMs > 0)) throw new Error("LogThrottle: intervalMs must be > 0");
+ if (!Number.isSafeInteger(maxKeys) || maxKeys < 1) {
+ throw new Error("LogThrottle: maxKeys must be a positive integer");
+ }
this.lastSweep = now();
}
@@ -37,12 +50,14 @@ export class LogThrottle {
admit(key: string): number | undefined {
const now = this.now();
this.sweep(now);
- const entry = this.entries.get(key);
+ const trackedKey =
+ this.entries.has(key) || this.entries.size < this.maxKeys ? key : OVERFLOW_KEY;
+ const entry = this.entries.get(trackedKey);
if (entry && now - entry.emittedAt < this.intervalMs) {
entry.suppressed += 1;
return undefined;
}
- this.entries.set(key, { emittedAt: now, suppressed: 0 });
+ this.entries.set(trackedKey, { emittedAt: now, suppressed: 0 });
return entry?.suppressed ?? 0;
}
@@ -54,3 +69,7 @@ export class LogThrottle {
this.lastSweep = now;
}
}
+
+// A NUL byte cannot appear in a key built from a denial kind and a hex hash,
+// so the overflow entry cannot collide with a real key.
+const OVERFLOW_KEY = "\u0000overflow";
diff --git a/gfs-controller/src/quota/quota.test.ts b/gfs-controller/src/quota/quota.test.ts
index aee659f05..348fbefd8 100644
--- a/gfs-controller/src/quota/quota.test.ts
+++ b/gfs-controller/src/quota/quota.test.ts
@@ -1,7 +1,7 @@
-import { describe, expect, it } from "vitest";
-import { assertByteQuota, QuotaError } from "./bytes.js";
+import { describe, expect, it, vi } from "vitest";
+import { QuotaError, assertByteQuota } from "./bytes.js";
import { assertObjectQuota } from "./objects.js";
-import { RateLimiter, RateLimitExceededError, buildAgentRateLimits } from "./rateLimit.js";
+import { RateLimitExceededError, RateLimiter, buildAgentRateLimits } from "./rateLimit.js";
/**
* P4-S03 — byte + object quotas and per-subject rate limit. Exceeding any →
@@ -116,6 +116,25 @@ describe("RateLimiter", () => {
expect(() => rl.check("s")).toThrow(RateLimitExceededError);
});
+ it("C6: the default clock is monotonic, so a wall clock stepped back does not keep a hit in the window", async () => {
+ // The wall clock is replaced before the limiter is built, so a limiter that
+ // defaulted to Date.now would read this one.
+ const realNow = Date.now;
+ let stepMs = 0;
+ const wall = vi.spyOn(Date, "now").mockImplementation(() => realNow() + stepMs);
+ try {
+ const rl = new RateLimiter({ limit: 1, windowMs: 20 });
+ rl.check("s");
+ // Witness: the window is full on the default clock.
+ expect(() => rl.check("s")).toThrow(RateLimitExceededError);
+ stepMs = -300_000;
+ await new Promise((resolve) => setTimeout(resolve, 40));
+ expect(() => rl.check("s")).not.toThrow();
+ } finally {
+ wall.mockRestore();
+ }
+ });
+
it("M15: compaction bounds the slots a subject holds to about twice its live window", () => {
// 100 live hits per window, for 100 windows: 10 000 hits in total. Without
// compaction the array keeps every one of them.
@@ -134,7 +153,7 @@ describe("buildAgentRateLimits", () => {
let t = 1_000_000;
const limits = buildAgentRateLimits(
{ agentReadRlPerMinPerReplica: 5, agentWriteRlPerMinPerReplica: 2 },
- () => t
+ () => t,
);
expect(limits.reads.limitPerWindow).toBe(5);
expect(limits.writes.limitPerWindow).toBe(2);
diff --git a/gfs-controller/src/quota/rateLimit.ts b/gfs-controller/src/quota/rateLimit.ts
index 657135068..c489f48b0 100644
--- a/gfs-controller/src/quota/rateLimit.ts
+++ b/gfs-controller/src/quota/rateLimit.ts
@@ -18,7 +18,10 @@ export class RateLimitExceededError extends QuotaError {
* P4-S03). Caps an agent's reads or writes so a compromised agent cannot flood
* gfsc; exceeding → rate_limited. In-memory per process, so a budget is per
* replica; the durable counter is a follow-up. Clock is injectable for
- * deterministic tests.
+ * deterministic tests. The default is the monotonic `performance.now()`: the
+ * limiter only compares its own timestamps, and a wall clock stepped back (NTP)
+ * would keep every recorded hit in the window and stall the sweep for as long
+ * as the step.
*/
export class RateLimiter {
private readonly hits = new Map<string, SubjectWindow>();
@@ -33,7 +36,7 @@ export class RateLimiter {
}
this.limit = opts.limit;
this.windowMs = opts.windowMs;
- this.now = opts.now ?? Date.now;
+ this.now = opts.now ?? (() => performance.now());
this.lastSweep = this.now();
}