Skip to content

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

TypeScript

fix(control-api): per-class external GFS read budgets

Alfredo Lopez3a8ed542b49e
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index aa041be5d..07501440f 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.605",
+ "version": "0.1.606",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.605",
+ "version": "0.1.606",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index adeb0d846..0f2f7f103 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.605",
+ "version": "0.1.606",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/config.ts b/control-api/src/config.ts
index 962126f29..9fca7bbeb 100644
--- a/control-api/src/config.ts
+++ b/control-api/src/config.ts
@@ -210,10 +210,14 @@ type Config = {
// defense-in-depth ceiling across authenticated non-token GFS traffic; it
// is intentionally wider than the per-class/session/actor budgets.
externalGfsIpRlPerMin: number
- // Read waterfalls have a separate budget from mutations. A Desktop root
- // refresh legitimately performs more reads than a mutation burst, while
- // mutation/grant/share ceilings remain deliberately narrow.
- externalGfsReadRlPerMin: number
+ // Each read class has its own budget, sized from its own observed peak; the
+ // three mutation classes share one narrower budget. A Desktop root refresh
+ // legitimately performs many resource reads, while grants and shares are
+ // read only when the Manage dialog opens.
+ externalGfsResourceReadRlPerMin: number
+ externalGfsProxyReadRlPerMin: number
+ externalGfsGrantsReadRlPerMin: number
+ externalGfsSharesReadRlPerMin: number
externalGfsOperationRlPerMin: number
// Stateless-agent wake endpoint: per-host wake rate limit + server-side
// coalescence window for the wake-annotation projection.
@@ -466,9 +470,13 @@ const WORKFLOW_STEP_DEPENDS_ON_MAX_ITEMS_CEILING = 100
const WORKFLOW_STEP_ALLOWED_TOOLS_MAX_ITEMS_CEILING = 100
// The step mcpServers env can only lower this value; the CRD hard ceiling remains 20.
const WORKFLOW_STEP_MCP_SERVERS_MAX_ITEMS_CEILING = 20
-// The two actor-keyed external GFS budgets accept an environment override up
-// to twice their default; a larger value refuses to boot.
-const EXTERNAL_GFS_READ_RL_PER_MIN_CEILING = 960
+// The actor-keyed external GFS budgets accept an environment override up to a
+// compiled ceiling; a larger value refuses to boot. The two 480 budgets may
+// double; the two 120 budgets may reach 480.
+const EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN_CEILING = 960
+const EXTERNAL_GFS_PROXY_READ_RL_PER_MIN_CEILING = 960
+const EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN_CEILING = 480
+const EXTERNAL_GFS_SHARES_READ_RL_PER_MIN_CEILING = 480
const EXTERNAL_GFS_OPERATION_RL_PER_MIN_CEILING = 180
function normalizePem(value: string): string {
@@ -1009,20 +1017,50 @@ export const config: Config = {
externalGfsTokenUserRlPerMin: 10,
externalGfsTokenIpRlPerMin: 600,
externalGfsIpRlPerMin: 1_200,
- // The two actor-keyed budgets are overridable within a compiled ceiling.
- // Each value feeds the pre-resolution session and (class, IP) buckets, the
- // resolved per-actor bucket and the express backstops in
- // routes/external/gfs.ts. assertExternalGfsBudgetInvariants below refuses a
- // combination where operations exceed reads or reads exceed the per-IP
+ // The actor-keyed budgets are overridable within a compiled ceiling. Each
+ // class's value feeds that class's pre-resolution session and (class, IP)
+ // buckets, its resolved per-actor bucket and its express backstop in
+ // routes/external/gfs.ts, all through externalGfsClassRlPerMin.
+ // assertExternalGfsBudgetInvariants below refuses a combination where
+ // mutations exceed a read class or a read class exceeds the per-IP
// all-class bucket.
//
- // Read: one Desktop surface peaks at 58 resource reads/min after PR #702,
- // and the 2026-09-18 incident peaked at 133 in a sliding 60 s. 480 covers
+ // The four read classes sum to 1200 per calendar minute (480 + 480 + 120 +
+ // 120), which equals the all-class pre:ip bucket (1200): one source IP is
+ // capped at that value whatever the class mix. With one shared read budget
+ // the nominal sum was 1920. No all-read per-actor cap exists; the test
+ // suite states the sum instead of a boot invariant.
+ //
+ // Peaks below are the busiest sliding 60 s of the 30-day funnel log, prod /
+ // dev.
+ //
+ // Resource (resolve, capabilities, upload status, resources, affordances,
+ // children): 133 / 85, the prod peak being the 2026-09-18 incident. One
+ // Desktop surface peaks at 58 resource reads/min after PR #702. 480 covers
// eight surfaces of one user and is 3.6x the incident peak.
- externalGfsReadRlPerMin: boundedIntegerFromEnv(
- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN',
+ externalGfsResourceReadRlPerMin: boundedIntegerFromEnv(
+ 'CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN',
480,
- EXTERNAL_GFS_READ_RL_PER_MIN_CEILING
+ EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN_CEILING
+ ),
+ // Proxy read: 12 / 14. 480 rather than 120 because planned per-row
+ // thumbnails fan out one proxy read per listed row, as affordances do today.
+ externalGfsProxyReadRlPerMin: boundedIntegerFromEnv(
+ 'CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN',
+ 480,
+ EXTERNAL_GFS_PROXY_READ_RL_PER_MIN_CEILING
+ ),
+ // Grants and shares reads: 4 / 4 and 2 / 4. Both happen only when the
+ // Manage dialog opens; 120 is 30x the observed peak.
+ externalGfsGrantsReadRlPerMin: boundedIntegerFromEnv(
+ 'CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN',
+ 120,
+ EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN_CEILING
+ ),
+ externalGfsSharesReadRlPerMin: boundedIntegerFromEnv(
+ 'CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN',
+ 120,
+ EXTERNAL_GFS_SHARES_READ_RL_PER_MIN_CEILING
),
// Operation: one maximum-size Desktop upload is at least 27 mutations
// (ceil(200 MiB / 8 MiB) parts + create + complete, desktop-app
@@ -1200,37 +1238,54 @@ export const config: Config = {
* corrected value would leave the operator's setting and the running limit
* disagreeing.
*
- * - Operations must not be allowed more freely than reads.
- * - The per-actor read budget must not exceed the per-IP all-class bucket in
- * front of it; otherwise that bucket caps it under a different key and the
- * configured number is never reached.
+ * - A mutation class must not be allowed more freely than its read
+ * counterpart: resource, grants and shares mutations share one budget,
+ * which must not exceed any of the three read budgets. proxy-read has no
+ * mutation counterpart.
+ * - No read class may exceed the per-IP all-class bucket in front of it;
+ * otherwise that bucket caps it under a different key and the configured
+ * number is never reached.
*
- * The per-IP check cannot fire from the environment today: the read ceiling
- * (960) is below the compiled per-IP budget (1200). It guards a change to
- * either compiled value, and test/config.externalGfsBudgets.test.ts pins the
- * relation.
+ * The per-IP check cannot fire from the environment today: the largest read
+ * ceiling (960) is below the compiled per-IP budget (1200). It guards a change
+ * to either compiled value, and test/config.externalGfsBudgets.test.ts pins
+ * the relation for every read class.
*/
export function assertExternalGfsBudgetInvariants(budgets: {
- readPerMin: number
+ resourceReadPerMin: number
+ proxyReadPerMin: number
+ grantsReadPerMin: number
+ sharesReadPerMin: number
operationPerMin: number
ipPerMin: number
}): void {
- if (budgets.operationPerMin > budgets.readPerMin) {
- throw new Error(
- `CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (${budgets.operationPerMin}) must not ` +
- `exceed CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (${budgets.readPerMin})`
- )
- }
- if (budgets.readPerMin > budgets.ipPerMin) {
- throw new Error(
- `CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (${budgets.readPerMin}) must not exceed ` +
- `the per-IP external GFS budget externalGfsIpRlPerMin (${budgets.ipPerMin})`
- )
+ const reads = [
+ ['CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN', budgets.resourceReadPerMin, true],
+ ['CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN', budgets.proxyReadPerMin, false],
+ ['CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN', budgets.grantsReadPerMin, true],
+ ['CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN', budgets.sharesReadPerMin, true],
+ ] as const
+ for (const [name, readPerMin, hasMutationCounterpart] of reads) {
+ if (hasMutationCounterpart && budgets.operationPerMin > readPerMin) {
+ throw new Error(
+ `CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (${budgets.operationPerMin}) must not ` +
+ `exceed ${name} (${readPerMin})`
+ )
+ }
+ if (readPerMin > budgets.ipPerMin) {
+ throw new Error(
+ `${name} (${readPerMin}) must not exceed ` +
+ `the per-IP external GFS budget externalGfsIpRlPerMin (${budgets.ipPerMin})`
+ )
+ }
}
}
assertExternalGfsBudgetInvariants({
- readPerMin: config.externalGfsReadRlPerMin,
+ resourceReadPerMin: config.externalGfsResourceReadRlPerMin,
+ proxyReadPerMin: config.externalGfsProxyReadRlPerMin,
+ grantsReadPerMin: config.externalGfsGrantsReadRlPerMin,
+ sharesReadPerMin: config.externalGfsSharesReadRlPerMin,
operationPerMin: config.externalGfsOperationRlPerMin,
ipPerMin: config.externalGfsIpRlPerMin,
})
diff --git a/control-api/src/middleware/externalGfsRateLimit.ts b/control-api/src/middleware/externalGfsRateLimit.ts
index 0ea758bb1..fa9d5c8c2 100644
--- a/control-api/src/middleware/externalGfsRateLimit.ts
+++ b/control-api/src/middleware/externalGfsRateLimit.ts
@@ -194,13 +194,30 @@ function sourceIpDigest(req: Request): string {
return digest(externalGfsSourceIp(req))
}
-function operationLimit(operationClass: ExternalGfsOperationClass): number {
- return operationClass === 'resource' ||
- operationClass === 'proxy-read' ||
- operationClass === 'grants-read' ||
- operationClass === 'shares-read'
- ? config.externalGfsReadRlPerMin
- : config.externalGfsOperationRlPerMin
+/**
+ * The per-minute budget of one operation class. The pre-resolution session and
+ * (class, IP) buckets, the resolved actor bucket and the class's express
+ * backstop in routes/external/gfs.ts all read it here, so one class cannot be
+ * metered under two different numbers. The switch is exhaustive: a new class
+ * does not compile until it is given a budget.
+ */
+export function externalGfsClassRlPerMin(
+ operationClass: Exclude<ExternalGfsOperationClass, 'token'>
+): number {
+ switch (operationClass) {
+ case 'resource':
+ return config.externalGfsResourceReadRlPerMin
+ case 'proxy-read':
+ return config.externalGfsProxyReadRlPerMin
+ case 'grants-read':
+ return config.externalGfsGrantsReadRlPerMin
+ case 'shares-read':
+ return config.externalGfsSharesReadRlPerMin
+ case 'resource-mutation':
+ case 'grants-mutation':
+ case 'shares-mutation':
+ return config.externalGfsOperationRlPerMin
+ }
}
function applyRateLimitHeaders(
@@ -389,11 +406,11 @@ export function externalGfsPreResolutionRateLimit(
: [
{
key: `gfs-ext:pre:${operation.operationClass}:session:${sessionDigest}`,
- maxPerMinute: operationLimit(operation.operationClass),
+ maxPerMinute: externalGfsClassRlPerMin(operation.operationClass),
},
{
key: `gfs-ext:pre:${operation.operationClass}:ip:${sourceIpDigest(req)}`,
- maxPerMinute: operationLimit(operation.operationClass),
+ maxPerMinute: externalGfsClassRlPerMin(operation.operationClass),
},
{
key: `gfs-ext:pre:ip:${sourceIpDigest(req)}`,
@@ -428,7 +445,7 @@ export function externalGfsResolvedOperationRateLimit(
}
const bucket: Bucket = {
key: externalGfsResolvedActorBucketKey(operation.operationClass, authority),
- maxPerMinute: operationLimit(operation.operationClass),
+ maxPerMinute: externalGfsClassRlPerMin(operation.operationClass),
}
if (
await enforceBuckets({
diff --git a/control-api/src/routes/external/gfs.ts b/control-api/src/routes/external/gfs.ts
index 71169bca4..d6befdfb5 100644
--- a/control-api/src/routes/external/gfs.ts
+++ b/control-api/src/routes/external/gfs.ts
@@ -28,6 +28,7 @@ import {
import { asyncHandler } from '../../http/asyncHandler.js'
import {
type ExternalGfsOperationClass,
+ externalGfsClassRlPerMin,
externalGfsPreResolutionRateLimit,
externalGfsResolvedActorBucketKey,
externalGfsResolvedOperationRateLimit,
@@ -411,7 +412,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsResourceRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsReadRlPerMin,
+ limit: externalGfsClassRlPerMin('resource'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: resourceRateKey,
@@ -419,7 +420,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsProxyReadRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsReadRlPerMin,
+ limit: externalGfsClassRlPerMin('proxy-read'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: proxyReadRateKey,
@@ -427,7 +428,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsMutationRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsOperationRlPerMin,
+ limit: externalGfsClassRlPerMin('resource-mutation'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: resourceMutationRateKey,
@@ -435,7 +436,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsGrantsReadRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsReadRlPerMin,
+ limit: externalGfsClassRlPerMin('grants-read'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: grantsReadRateKey,
@@ -443,7 +444,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsGrantsMutationRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsOperationRlPerMin,
+ limit: externalGfsClassRlPerMin('grants-mutation'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: grantsMutationRateKey,
@@ -451,7 +452,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsSharesReadRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsReadRlPerMin,
+ limit: externalGfsClassRlPerMin('shares-read'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: sharesReadRateKey,
@@ -459,7 +460,7 @@ export function createExternalGfsRouter(): Router {
})
const externalGfsSharesMutationRouteRateLimit = rateLimit({
windowMs: 60_000,
- limit: config.externalGfsOperationRlPerMin,
+ limit: externalGfsClassRlPerMin('shares-mutation'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: sharesMutationRateKey,
@@ -485,11 +486,13 @@ export function createExternalGfsRouter(): Router {
// ACL listing is still a privileged manage_acl operation, but it must not
// consume the smaller mutation budget: opening the Manage dialog performs
// several list/refetch reads before one visible grant/share action. Keep
- // those reads in the existing bounded GFS read budget and in a distinct
- // actor bucket from mutations.
+ // those reads in a distinct actor bucket from mutations. GET /grants and
+ // GET /shares share this one bucket, so its limit is the sum of the two
+ // read budgets; the per-class Postgres buckets and express backstops still
+ // cap each route at its own budget.
const externalGrantsReadRateLimit = rateLimitMiddleware({
bucketType: 'gfs_grants_external_read',
- maxPerMinute: config.externalGfsReadRlPerMin,
+ maxPerMinute: config.externalGfsGrantsReadRlPerMin + config.externalGfsSharesReadRlPerMin,
getBucketKey: req => {
const authority = (req as RequestWithExternalGfsAuthority).gfsAuthority
if (authority?.kind === 'linked-admin') {
diff --git a/control-api/test/config.externalGfsBudgets.test.ts b/control-api/test/config.externalGfsBudgets.test.ts
index 2ed8f1dd9..f13d73d90 100644
--- a/control-api/test/config.externalGfsBudgets.test.ts
+++ b/control-api/test/config.externalGfsBudgets.test.ts
@@ -2,8 +2,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
import { readFileSync } from 'node:fs'
/**
- * Regression guard for the two actor-keyed external GFS budgets
- * (config.externalGfsReadRlPerMin, config.externalGfsOperationRlPerMin).
+ * Regression guard for the actor-keyed external GFS budgets: one per read
+ * class (resource, proxy-read, grants-read, shares-read) and one shared by the
+ * three mutation classes (config.externalGfsOperationRlPerMin).
*
* The operation budget is derived from the largest Desktop upload: one part
* per preferred part size up to the default product maximum, plus one create
@@ -21,11 +22,61 @@ const UPLOAD_LIFECYCLE_CALLS = 2
const MAX_UPLOAD_MUTATIONS =
Math.ceil(UPLOAD_PRODUCT_MAX_MIB / UPLOAD_PREFERRED_PART_MIB) + UPLOAD_LIFECYCLE_CALLS
+// Every read class: its environment variable, config field, default and
+// compiled ceiling.
+const READ_CLASSES = [
+ {
+ env: 'CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN',
+ field: 'externalGfsResourceReadRlPerMin',
+ defaultPerMin: 480,
+ ceiling: 960,
+ hasMutationCounterpart: true,
+ },
+ {
+ env: 'CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN',
+ field: 'externalGfsProxyReadRlPerMin',
+ defaultPerMin: 480,
+ ceiling: 960,
+ hasMutationCounterpart: false,
+ },
+ {
+ env: 'CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN',
+ field: 'externalGfsGrantsReadRlPerMin',
+ defaultPerMin: 120,
+ ceiling: 480,
+ hasMutationCounterpart: true,
+ },
+ {
+ env: 'CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN',
+ field: 'externalGfsSharesReadRlPerMin',
+ defaultPerMin: 120,
+ ceiling: 480,
+ hasMutationCounterpart: true,
+ },
+] as const
+
const ENV_KEYS = [
- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN',
+ ...READ_CLASSES.map(readClass => readClass.env),
'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN',
+ // Removed; deleted here so a host that still sets it cannot affect a case.
+ 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN',
] as const
+const DEFAULT_INVARIANT_INPUT = {
+ resourceReadPerMin: 480,
+ proxyReadPerMin: 480,
+ grantsReadPerMin: 120,
+ sharesReadPerMin: 120,
+ operationPerMin: 90,
+ ipPerMin: 1200,
+}
+const INVARIANT_FIELD = {
+ CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN: 'resourceReadPerMin',
+ CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN: 'proxyReadPerMin',
+ CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN: 'grantsReadPerMin',
+ CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN: 'sharesReadPerMin',
+} as const
+
async function loadConfigModuleWith(overrides: Partial<Record<(typeof ENV_KEYS)[number], string>>) {
const originalValues = new Map<string, string | undefined>()
for (const key of ENV_KEYS) {
@@ -85,75 +136,117 @@ describe('external GFS actor budgets', () => {
expect(config.externalGfsOperationRlPerMin).toBeGreaterThanOrEqual(MAX_UPLOAD_MUTATIONS)
})
- it('defaults to 480 reads and 90 operations per minute', async () => {
+ it('L12: defaults to 480/480/120/120 reads and 90 operations per minute', async () => {
const { config } = await loadConfigModuleWith({})
- expect(config.externalGfsReadRlPerMin).toBe(480)
+ expect(config.externalGfsResourceReadRlPerMin).toBe(480)
+ expect(config.externalGfsProxyReadRlPerMin).toBe(480)
+ expect(config.externalGfsGrantsReadRlPerMin).toBe(120)
+ expect(config.externalGfsSharesReadRlPerMin).toBe(120)
expect(config.externalGfsOperationRlPerMin).toBe(90)
})
- it('accepts an environment override within the ceiling', async () => {
+ it('L12: the four read classes sum to the per-IP all-class bucket', async () => {
+ // Documented, not enforced at boot: one source IP is capped at the per-IP
+ // bucket whatever the class mix, and with one shared read budget the
+ // nominal sum was 1920.
+ const { config } = await loadConfigModuleWith({})
+ const readSum =
+ config.externalGfsResourceReadRlPerMin +
+ config.externalGfsProxyReadRlPerMin +
+ config.externalGfsGrantsReadRlPerMin +
+ config.externalGfsSharesReadRlPerMin
+ expect(readSum).toBe(1200)
+ expect(readSum).toBe(config.externalGfsIpRlPerMin)
+ })
+
+ it('ignores the removed shared read variable', async () => {
const { config } = await loadConfigModuleWith({
CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '960',
+ })
+ expect(config.externalGfsResourceReadRlPerMin).toBe(480)
+ expect(config.externalGfsProxyReadRlPerMin).toBe(480)
+ expect(config.externalGfsGrantsReadRlPerMin).toBe(120)
+ expect(config.externalGfsSharesReadRlPerMin).toBe(120)
+ })
+
+ it('accepts every class at its ceiling', async () => {
+ const { config } = await loadConfigModuleWith({
+ ...Object.fromEntries(
+ READ_CLASSES.map(readClass => [readClass.env, String(readClass.ceiling)])
+ ),
CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '180',
})
- expect(config.externalGfsReadRlPerMin).toBe(960)
+ for (const readClass of READ_CLASSES) {
+ expect(config[readClass.field]).toBe(readClass.ceiling)
+ }
expect(config.externalGfsOperationRlPerMin).toBe(180)
})
- it('refuses to boot above either compiled ceiling', async () => {
- await expect(
- loadConfigModuleWith({ CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '961' })
- ).rejects.toThrow(
- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN must be an integer between 1 and 960'
- )
- await expect(
- loadConfigModuleWith({ CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '181' })
- ).rejects.toThrow(
- 'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN must be an integer between 1 and 180'
+ it.each([
+ ...READ_CLASSES.map(readClass => [readClass.env, readClass.ceiling] as const),
+ ['CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN', 180] as const,
+ ])('refuses to boot with %s above its ceiling %i', async (env, ceiling) => {
+ await expect(loadConfigModuleWith({ [env]: String(ceiling + 1) })).rejects.toThrow(
+ `${env} must be an integer between 1 and ${ceiling}`
)
})
- it('refuses to boot when the operation budget exceeds the read budget', async () => {
- await expect(
- loadConfigModuleWith({
- CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '100',
- CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '180',
- })
- ).rejects.toThrow(
- 'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (180) must not exceed ' +
- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (100)'
- )
- })
+ it.each(READ_CLASSES.filter(readClass => readClass.hasMutationCounterpart))(
+ 'refuses to boot when the operation budget exceeds $env',
+ async readClass => {
+ await expect(
+ loadConfigModuleWith({
+ // 110 exceeds only the class under test: every other read budget
+ // keeps its default of 120 or more.
+ [readClass.env]: '100',
+ CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '110',
+ })
+ ).rejects.toThrow(
+ 'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (110) must not exceed ' +
+ `${readClass.env} (100)`
+ )
+ }
+ )
- it('L9: the largest read budget the environment can set stays within the per-IP bucket', async () => {
- // The per-IP half of assertExternalGfsBudgetInvariants cannot fire from the
- // environment today: the read ceiling is below the compiled per-IP budget.
- // This pins that relation, so lowering the per-IP budget or raising the
- // read ceiling has to be a decision, not a boot failure found in a deploy.
+ it('boots with a proxy-read budget below the operation budget: proxy has no mutations', async () => {
const { config } = await loadConfigModuleWith({
- CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '960',
+ CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN: '10',
})
- expect(config.externalGfsReadRlPerMin).toBe(960)
- expect(config.externalGfsReadRlPerMin).toBeLessThanOrEqual(config.externalGfsIpRlPerMin)
- // 960 is the ceiling: one more is refused by the parser, before the invariant.
- await expect(
- loadConfigModuleWith({ CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '961' })
- ).rejects.toThrow(
- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN must be an integer between 1 and 960'
- )
+ expect(config.externalGfsProxyReadRlPerMin).toBe(10)
+ expect(config.externalGfsOperationRlPerMin).toBe(90)
})
- it('refuses a read budget above the per-IP budget and accepts it at the boundary', async () => {
- const { assertExternalGfsBudgetInvariants } = await loadConfigModuleWith({})
- expect(() =>
- assertExternalGfsBudgetInvariants({ readPerMin: 1300, operationPerMin: 90, ipPerMin: 1200 })
- ).toThrow(
- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (1300) must not exceed ' +
- 'the per-IP external GFS budget externalGfsIpRlPerMin (1200)'
- )
- // Liveness witness for the check being `<=`, not `<`: equal values pass.
- expect(() =>
- assertExternalGfsBudgetInvariants({ readPerMin: 1200, operationPerMin: 90, ipPerMin: 1200 })
- ).not.toThrow()
- })
+ it.each(READ_CLASSES)(
+ 'L9: $env at its ceiling stays within the per-IP bucket',
+ async readClass => {
+ // The per-IP half of assertExternalGfsBudgetInvariants cannot fire from
+ // the environment today: every read ceiling is below the compiled per-IP
+ // budget. This pins that relation, so lowering the per-IP budget or
+ // raising a read ceiling has to be a decision, not a boot failure found
+ // in a deploy.
+ const { config } = await loadConfigModuleWith({
+ [readClass.env]: String(readClass.ceiling),
+ })
+ expect(config[readClass.field]).toBe(readClass.ceiling)
+ expect(config[readClass.field]).toBeLessThanOrEqual(config.externalGfsIpRlPerMin)
+ }
+ )
+
+ it.each(READ_CLASSES)(
+ 'refuses $env above the per-IP budget and accepts it at the boundary',
+ async readClass => {
+ const { assertExternalGfsBudgetInvariants } = await loadConfigModuleWith({})
+ const field = INVARIANT_FIELD[readClass.env]
+ expect(() =>
+ assertExternalGfsBudgetInvariants({ ...DEFAULT_INVARIANT_INPUT, [field]: 1300 })
+ ).toThrow(
+ `${readClass.env} (1300) must not exceed ` +
+ 'the per-IP external GFS budget externalGfsIpRlPerMin (1200)'
+ )
+ // Liveness witness for the check being `<=`, not `<`: equal values pass.
+ expect(() =>
+ assertExternalGfsBudgetInvariants({ ...DEFAULT_INVARIANT_INPUT, [field]: 1200 })
+ ).not.toThrow()
+ }
+ )
})
diff --git a/control-api/test/middleware.externalGfsRateLimit.test.ts b/control-api/test/middleware.externalGfsRateLimit.test.ts
index eb89e9a50..5aea5dfc2 100644
--- a/control-api/test/middleware.externalGfsRateLimit.test.ts
+++ b/control-api/test/middleware.externalGfsRateLimit.test.ts
@@ -25,7 +25,12 @@ vi.mock('../src/config.js', () => ({
externalGfsTokenUserRlPerMin: 10,
externalGfsTokenIpRlPerMin: 600,
externalGfsIpRlPerMin: 1200,
- externalGfsReadRlPerMin: 120,
+ // Distinct per class, so a class metered under another class's budget
+ // shows up as a wrong number rather than passing by coincidence.
+ externalGfsResourceReadRlPerMin: 120,
+ externalGfsProxyReadRlPerMin: 60,
+ externalGfsGrantsReadRlPerMin: 45,
+ externalGfsSharesReadRlPerMin: 35,
externalGfsOperationRlPerMin: 30,
},
}))
@@ -323,7 +328,8 @@ describe('external GFS rate boundary', () => {
)
expect(keys).toContainEqual(expect.stringMatching(/^gfs-ext:pre:proxy-read:ip:[0-9a-f]{64}$/))
expect(keys).toContain(`gfs-ext:resolved:proxy-read:actor:linked-admin:${CONTROL_ADMIN_ID}`)
- expect(limits.filter(limit => limit === 120).length).toBe(6)
+ expect(limits.filter(limit => limit === 120).length).toBe(3)
+ expect(limits.filter(limit => limit === 60).length).toBe(3)
expect(limits.filter(limit => limit === 1200).length).toBe(2)
expect(limits.filter(limit => limit === 30).length).toBe(0)
})
@@ -359,10 +365,10 @@ describe('external GFS rate boundary', () => {
await request(app).post('/external/gfs/shares').set('x-user-session-token', 'session-acl-write')
const calls = checkAndIncrement.mock.calls.map(call => [String(call[0]), Number(call[1])])
- expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:grants-read:session:/), 120])
+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:grants-read:session:/), 45])
expect(calls).toContainEqual([
expect.stringMatching(/^gfs-ext:resolved:grants-read:actor:/),
- 120,
+ 45,
])
expect(calls).toContainEqual([
expect.stringMatching(/^gfs-ext:pre:grants-mutation:session:/),
@@ -372,10 +378,10 @@ describe('external GFS rate boundary', () => {
expect.stringMatching(/^gfs-ext:resolved:grants-mutation:actor:/),
30,
])
- expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:shares-read:session:/), 120])
+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:shares-read:session:/), 35])
expect(calls).toContainEqual([
expect.stringMatching(/^gfs-ext:resolved:shares-read:actor:/),
- 120,
+ 35,
])
expect(calls).toContainEqual([
expect.stringMatching(/^gfs-ext:pre:shares-mutation:session:/),
@@ -387,6 +393,42 @@ describe('external GFS rate boundary', () => {
])
})
+ it.each([
+ ['GET', '/resources', 'resource', 120],
+ ['GET', `/proxy/${RESOURCE_ID}`, 'proxy-read', 60],
+ ['GET', '/grants', 'grants-read', 45],
+ ['GET', '/shares', 'shares-read', 35],
+ ['PATCH', `/resources/${RESOURCE_ID}`, 'resource-mutation', 30],
+ ['PUT', '/grants', 'grants-mutation', 30],
+ ['POST', '/shares', 'shares-mutation', 30],
+ ] as const)(
+ 'L12: meters %s %s (%s) under its own class budget %i in all three class buckets',
+ async (method, path, operationClass, limit) => {
+ const { app, handler } = buildApp()
+
+ const response = await request(app)
+ [method.toLowerCase() as 'get' | 'patch' | 'put' | 'post'](`/external/gfs${path}`)
+ .set('x-user-session-token', `session-${operationClass}`)
+
+ // Witness: the request went through both phases to the handler.
+ expect(response.status).toBe(204)
+ expect(handler).toHaveBeenCalledTimes(1)
+ const calls = checkAndIncrement.mock.calls.map(call => [String(call[0]), Number(call[1])])
+ expect(calls).toEqual([
+ [
+ expect.stringMatching(new RegExp(`^gfs-ext:pre:${operationClass}:session:[0-9a-f]{64}$`)),
+ limit,
+ ],
+ [
+ expect.stringMatching(new RegExp(`^gfs-ext:pre:${operationClass}:ip:[0-9a-f]{64}$`)),
+ limit,
+ ],
+ [expect.stringMatching(/^gfs-ext:pre:ip:[0-9a-f]{64}$/), 1200],
+ [`gfs-ext:resolved:${operationClass}:actor:linked-admin:${CONTROL_ADMIN_ID}`, limit],
+ ])
+ }
+ )
+
it('enforces the 1200/min aggregate IP ceiling after the 120/min read buckets', async () => {
checkAndIncrement.mockImplementation((key: string, limit: number) => {
if (key.startsWith('gfs-ext:pre:ip:')) return denied(1200)
diff --git a/control-api/test/routes.externalGfs.test.ts b/control-api/test/routes.externalGfs.test.ts
index d7828df48..ae33b5d52 100644
--- a/control-api/test/routes.externalGfs.test.ts
+++ b/control-api/test/routes.externalGfs.test.ts
@@ -51,7 +51,10 @@ vi.mock('../src/config.js', () => ({
externalGfsTokenUserRlPerMin: 10,
externalGfsTokenIpRlPerMin: 600,
externalGfsIpRlPerMin: 1200,
- externalGfsReadRlPerMin: 120,
+ externalGfsResourceReadRlPerMin: 120,
+ externalGfsProxyReadRlPerMin: 60,
+ externalGfsGrantsReadRlPerMin: 45,
+ externalGfsSharesReadRlPerMin: 35,
externalGfsOperationRlPerMin: 30,
},
}))
@@ -381,13 +384,11 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
expect(mockSignGfsToken).toHaveBeenCalledTimes(10)
})
- it('uses the dedicated 120/min read route ceiling without widening mutation ceilings', async () => {
- const previousReadLimit = (config as { externalGfsReadRlPerMin: number })
- .externalGfsReadRlPerMin
- const previousOperationLimit = (config as { externalGfsOperationRlPerMin: number })
- .externalGfsOperationRlPerMin
- ;(config as { externalGfsReadRlPerMin: number }).externalGfsReadRlPerMin = 2
- ;(config as { externalGfsOperationRlPerMin: number }).externalGfsOperationRlPerMin = 2
+ it('uses the dedicated resource read route ceiling without widening mutation ceilings', async () => {
+ const previousReadLimit = config.externalGfsResourceReadRlPerMin
+ const previousOperationLimit = config.externalGfsOperationRlPerMin
+ config.externalGfsResourceReadRlPerMin = 2
+ config.externalGfsOperationRlPerMin = 2
try {
auth()
dbReturning([])
@@ -414,17 +415,16 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
.send({ name: 'rename' })
expect(mutation.status).not.toBe(429)
} finally {
- ;(config as { externalGfsReadRlPerMin: number }).externalGfsReadRlPerMin = previousReadLimit
- ;(config as { externalGfsOperationRlPerMin: number }).externalGfsOperationRlPerMin =
- previousOperationLimit
+ config.externalGfsResourceReadRlPerMin = previousReadLimit
+ config.externalGfsOperationRlPerMin = previousOperationLimit
}
})
// The three edge-backstop cases below mock every Postgres bucket as allowing
// (dbReturning → count 1), so each 429 can only come from an express backstop.
it('reports a resource edge-backstop denial on the rate metric and log', async () => {
- const previousReadLimit = config.externalGfsReadRlPerMin
- config.externalGfsReadRlPerMin = 2
+ const previousReadLimit = config.externalGfsResourceReadRlPerMin
+ config.externalGfsResourceReadRlPerMin = 2
const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
try {
auth()
@@ -479,7 +479,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
expect((await edgeBackstopDenials()) - allBefore).toBe(1)
} finally {
warn.mockRestore()
- config.externalGfsReadRlPerMin = previousReadLimit
+ config.externalGfsResourceReadRlPerMin = previousReadLimit
}
})
@@ -612,8 +612,8 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
})
it('L5: a Postgres denial and a backstop denial for one actor log the same hashedKey', async () => {
- const previousReadLimit = config.externalGfsReadRlPerMin
- config.externalGfsReadRlPerMin = 2
+ const previousReadLimit = config.externalGfsResourceReadRlPerMin
+ config.externalGfsResourceReadRlPerMin = 2
const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
try {
auth()
@@ -647,13 +647,13 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
)
} finally {
warn.mockRestore()
- config.externalGfsReadRlPerMin = previousReadLimit
+ config.externalGfsResourceReadRlPerMin = previousReadLimit
}
})
it('L10: logs the first backstop denial per key and window, and counts every denial', async () => {
- const previousReadLimit = config.externalGfsReadRlPerMin
- config.externalGfsReadRlPerMin = 2
+ const previousReadLimit = config.externalGfsResourceReadRlPerMin
+ config.externalGfsResourceReadRlPerMin = 2
const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
try {
auth()
@@ -683,13 +683,13 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
])
} finally {
warn.mockRestore()
- config.externalGfsReadRlPerMin = previousReadLimit
+ config.externalGfsResourceReadRlPerMin = previousReadLimit
}
})
it('L22: reports the exact seconds left in the backstop window', async () => {
- const previousReadLimit = config.externalGfsReadRlPerMin
- config.externalGfsReadRlPerMin = 1
+ const previousReadLimit = config.externalGfsResourceReadRlPerMin
+ config.externalGfsResourceReadRlPerMin = 1
const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
const windowOpenedAt = Date.now()
vi.useFakeTimers({ toFake: ['Date'], now: windowOpenedAt })
@@ -712,14 +712,17 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
} finally {
vi.useRealTimers()
warn.mockRestore()
- config.externalGfsReadRlPerMin = previousReadLimit
+ config.externalGfsResourceReadRlPerMin = previousReadLimit
}
})
type BudgetKey =
| 'externalGfsIngressRlPerMin'
| 'externalGfsTokenUserRlPerMin'
- | 'externalGfsReadRlPerMin'
+ | 'externalGfsResourceReadRlPerMin'
+ | 'externalGfsProxyReadRlPerMin'
+ | 'externalGfsGrantsReadRlPerMin'
+ | 'externalGfsSharesReadRlPerMin'
| 'externalGfsOperationRlPerMin'
const SOURCE_IP = '203.0.113.9'
const actorKey = (operationClass: string) =>
@@ -760,7 +763,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
},
{
guard: 'resource',
- budget: 'externalGfsReadRlPerMin',
+ budget: 'externalGfsResourceReadRlPerMin',
method: 'get',
path: '/external/gfs/resources',
operationClass: 'resource',
@@ -770,7 +773,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
},
{
guard: 'proxy-read',
- budget: 'externalGfsReadRlPerMin',
+ budget: 'externalGfsProxyReadRlPerMin',
method: 'get',
path: `/external/gfs/proxy/${R}`,
operationClass: 'proxy-read',
@@ -791,7 +794,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
},
{
guard: 'grants-read',
- budget: 'externalGfsReadRlPerMin',
+ budget: 'externalGfsGrantsReadRlPerMin',
method: 'get',
path: `/external/gfs/grants?resourceId=${R}`,
operationClass: 'grants-read',
@@ -812,7 +815,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
},
{
guard: 'shares-read',
- budget: 'externalGfsReadRlPerMin',
+ budget: 'externalGfsSharesReadRlPerMin',
method: 'get',
path: `/external/gfs/shares?resourceId=${R}`,
operationClass: 'shares-read',
@@ -900,6 +903,43 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)
}
)
+ it.each([
+ ['grants', `/external/gfs/grants?resourceId=${R}`],
+ ['shares', `/external/gfs/shares?resourceId=${R}`],
+ ])(
+ 'L12: GET /%s shares one grants/shares read bucket whose limit is the sum of both budgets',
+ async (_name, path) => {
+ // 45 + 35 in the mocked config: the per-class buckets still cap each
+ // route at its own budget, so only the shared bucket carries the sum.
+ const sharedLimit =
+ config.externalGfsGrantsReadRlPerMin + config.externalGfsSharesReadRlPerMin
+ expect(sharedLimit).toBe(80)
+ auth()
+ let sharedCount = sharedLimit
+ const sharedKeys: string[] = []
+ dbReturning([], {
+ rateLimitCountFor: key => {
+ if (!key.startsWith('gfsgrants-ext-read:')) return 1
+ sharedKeys.push(key)
+ return sharedCount
+ },
+ })
+ const app = await buildApp()
+ const send = () => request(app).get(path).set('x-user-session-token', 'sess')
+
+ const atLimit = await send()
+ expect(atLimit.status).not.toBe(429)
+ expect(atLimit.headers['x-ratelimit-limit']).toBe('80')
+
+ sharedCount = sharedLimit + 1
+ const overLimit = await send()
+ expect(overLimit.status).toBe(429)
+ expect(overLimit.headers['x-ratelimit-limit']).toBe('80')
+ // Witness: both requests reached the shared bucket under the one key.
+ expect(sharedKeys).toEqual([`gfsgrants-ext-read:user:${U1}`, `gfsgrants-ext-read:user:${U1}`])
+ }
+ )
+
it('mints a gfs token for the user with the EXISTING signGfsToken (sub=users.id)', async () => {
auth()
const app = await buildApp()
diff --git a/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts b/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts
index 785d1fce0..1ef3a9b07 100644
--- a/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts
+++ b/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts
@@ -43,6 +43,11 @@ const INGRESS_L = 1_800
const IP_L_DEFAULT = 1_200
const MINUTE_MS = 60_000
+/** Every read class at `read`: for scenarios that exercise one read class. */
+function uniformBudgets(read: number, operation: number, ip: number): Budgets {
+ return { resource: read, proxy: read, grants: read, shares: read, operation, ip }
+}
+
function databaseUrl(baseUrl: string, database: string): string {
const url = new URL(baseUrl)
url.pathname = `/${database}`
@@ -53,7 +58,14 @@ function quoteIdent(value: string): string {
return `"${value.replace(/"/g, '""')}"`
}
-type Budgets = { read: number; operation: number; ip: number }
+type Budgets = {
+ resource: number
+ proxy: number
+ grants: number
+ shares: number
+ operation: number
+ ip: number
+}
type Sent = {
path: string
status: number
@@ -149,11 +161,17 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
/** Sets a boot-valid budget, clears the ledger, returns a fresh app and the scenario minute. */
async function startScenario(budgets: Budgets) {
mod.assertExternalGfsBudgetInvariants({
- readPerMin: budgets.read,
+ resourceReadPerMin: budgets.resource,
+ proxyReadPerMin: budgets.proxy,
+ grantsReadPerMin: budgets.grants,
+ sharesReadPerMin: budgets.shares,
operationPerMin: budgets.operation,
ipPerMin: budgets.ip,
})
- mod.config.externalGfsReadRlPerMin = budgets.read
+ mod.config.externalGfsResourceReadRlPerMin = budgets.resource
+ mod.config.externalGfsProxyReadRlPerMin = budgets.proxy
+ mod.config.externalGfsGrantsReadRlPerMin = budgets.grants
+ mod.config.externalGfsSharesReadRlPerMin = budgets.shares
mod.config.externalGfsOperationRlPerMin = budgets.operation
mod.config.externalGfsIpRlPerMin = budgets.ip
await mod.pool.query('DELETE FROM rate_limit_buckets')
@@ -249,8 +267,10 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
/** Limit of every bucket key these scenarios can create; an unknown key fails loudly. */
function limitOf(key: string, budgets: Budgets): number {
if (key.startsWith('gfs-ext:pre:ip:')) return budgets.ip
- if (/^gfs-ext:(pre|resolved):(resource|grants-read):/.test(key)) return budgets.read
- if (key.startsWith('gfsgrants-ext-read:user:')) return budgets.read
+ if (/^gfs-ext:(pre|resolved):resource:/.test(key)) return budgets.resource
+ if (/^gfs-ext:(pre|resolved):grants-read:/.test(key)) return budgets.grants
+ // GET /grants and GET /shares share this bucket; its limit is the sum.
+ if (key.startsWith('gfsgrants-ext-read:user:')) return budgets.grants + budgets.shares
throw new Error(`unexpected rate limit bucket in the ledger: ${key}`)
}
@@ -305,7 +325,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
}
it('S1: 20 users with distinct sessions and IPs each get exactly the read budget', async () => {
- const budgets = { read: 6, operation: 6, ip: IP_L_DEFAULT }
+ const budgets = uniformBudgets(6, 6, IP_L_DEFAULT)
const { app } = await startScenario(budgets)
const users = await Promise.all(Array.from({ length: 20 }, () => seedUser()))
const resourceId = randomUUID()
@@ -319,7 +339,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
)
)
)
- const labels = run.result.map(response => classify(response, budgets.read))
+ const labels = run.result.map(response => classify(response, budgets.resource))
expect(run.result).toHaveLength(200)
for (let user = 0; user < 20; user += 1) {
@@ -348,7 +368,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
}, 120_000)
it('S2a: 20 users behind one IP share the (class, IP) read bucket', async () => {
- const budgets = { read: 30, operation: 30, ip: IP_L_DEFAULT }
+ const budgets = uniformBudgets(30, 30, IP_L_DEFAULT)
const { app } = await startScenario(budgets)
const users = await Promise.all(Array.from({ length: 20 }, () => seedUser()))
const resourceId = randomUUID()
@@ -363,7 +383,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
)
)
- expect(tally(run.result.map(response => classify(response, budgets.read)))).toEqual({
+ expect(tally(run.result.map(response => classify(response, budgets.resource)))).toEqual({
'allowed:200': 30,
'postgres:30': 70,
})
@@ -382,10 +402,12 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
expect(run.logged).toEqual(run.metricDelta)
}, 120_000)
- it('S2b: the per-IP all-class bucket caps two read classes behind one IP', async () => {
- // Boot-valid: read (30) <= ip (40). pre:ip can only deny when several
- // classes share the IP, because each class alone is capped at read L first.
- const budgets = { read: 30, operation: 30, ip: 40 }
+ it('S2b: each class bucket and the per-IP all-class bucket cap two read classes behind one IP', async () => {
+ // Boot-valid: operation (20) <= every read class with mutations, and every
+ // read class <= ip (40). pre:ip can only deny when several classes share
+ // the IP, because each class alone is capped at its own L first. The two
+ // classes carry different budgets, so each bucket must use its own class's.
+ const budgets = { resource: 30, proxy: 30, grants: 20, shares: 20, operation: 20, ip: 40 }
const { app } = await startScenario(budgets)
const users = await Promise.all(Array.from({ length: 10 }, () => seedUser()))
const resourceId = randomUUID()
@@ -404,14 +426,23 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
)
)
)
- const labels = run.result.map(response => classify(response, budgets.read))
+ const labels = run.result.map(response => classify(response, budgets.resource))
const tallied = tally(labels)
- expect(tallied['postgres:40']).toBe(10)
+ // The (grants-read, IP) bucket sees 25 against 20 and denies 5; pre:ip
+ // then sees 25 resource + 20 grants = 45 against 40 and denies 5.
+ expect(tallied['postgres:20']).toBe(5)
+ expect(tallied['postgres:40']).toBe(5)
expect((tallied['allowed:200'] ?? 0) + (tallied['allowed:403'] ?? 0)).toBe(40)
expect(Object.keys(tallied).sort()).toEqual(
- ['allowed:200', 'allowed:403', 'postgres:40'].filter(label => tallied[label] !== undefined)
+ ['allowed:200', 'allowed:403', 'postgres:20', 'postgres:40'].filter(
+ label => tallied[label] !== undefined
+ )
)
+ // Only the grants class is capped at 20.
+ run.result.forEach((response, index) => {
+ if (labels[index] === 'postgres:20') expect(response.path).toContain('/grants')
+ })
// "Allowed" is defined per route: affordances answer 200, the grants list
// answers 403 manage_acl_required for a caller without manage_acl.
for (const response of run.result) {
@@ -426,7 +457,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
expect(counts(ledger, 'gfs-ext:pre:grants-read:session:')).toEqual(Array(5).fill(5))
expect(counts(ledger, 'gfs-ext:pre:resource:ip:')).toEqual([25])
expect(counts(ledger, 'gfs-ext:pre:grants-read:ip:')).toEqual([25])
- expect(counts(ledger, 'gfs-ext:pre:ip:')).toEqual([50])
+ expect(counts(ledger, 'gfs-ext:pre:ip:')).toEqual([45])
expect(sum(counts(ledger, 'gfs-ext:resolved:'))).toBe(40)
expect(sum(counts(ledger, 'gfsgrants-ext-read:user:'))).toBe(tallied['allowed:403'] ?? 0)
expect(ledgerDenials(ledger, budgets)).toBe(10)
@@ -440,7 +471,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
}, 120_000)
it('S3: two sessions of one user share the resolved actor bucket', async () => {
- const budgets = { read: 10, operation: 10, ip: IP_L_DEFAULT }
+ const budgets = uniformBudgets(10, 10, IP_L_DEFAULT)
const { app } = await startScenario(budgets)
const userId = await seedUser()
const resourceId = randomUUID()
@@ -456,7 +487,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
])
)
- expect(tally(run.result.map(response => classify(response, budgets.read)))).toEqual({
+ expect(tally(run.result.map(response => classify(response, budgets.resource)))).toEqual({
'allowed:200': 10,
'postgres:10': 6,
})
@@ -478,7 +509,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
}, 120_000)
it('S4: a burst straddling a minute boundary is denied only by the route backstop', async () => {
- const budgets = { read: 8, operation: 8, ip: IP_L_DEFAULT }
+ const budgets = uniformBudgets(8, 8, IP_L_DEFAULT)
const { app, minuteMs } = await startScenario(budgets)
const userId = await seedUser()
const resourceId = randomUUID()
@@ -491,7 +522,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg
)
)
const labelsOf = (responses: Sent[]) =>
- tally(responses.map(response => classify(response, budgets.read)))
+ tally(responses.map(response => classify(response, budgets.resource)))
// A: 50 s into window 1. Opens the backstop window, fills the Postgres buckets.
vi.setSystemTime(minuteMs + 50_000)
diff --git a/docs/how-to/codeql-js-missing-rate-limiting.md b/docs/how-to/codeql-js-missing-rate-limiting.md
index 368bb8640..39864ffeb 100644
--- a/docs/how-to/codeql-js-missing-rate-limiting.md
+++ b/docs/how-to/codeql-js-missing-rate-limiting.md
@@ -26,14 +26,14 @@ may still alert until an `express-rate-limit` **edge backstop** is added (see
Tier defaults (requests/minute, per verified admin session identity unless noted):
-| Tier | Limit | Config anchor |
-| ---------------------------- | -------- | ---------------------------------------------------------- |
-| Admin public token | 20 | `adminPublicTokenRlPerMin` |
-| Admin workflow grant read | 60 | `workflowGrantReadRateLimit` |
-| Admin workflow grant write | 20 | `workflowGrantWriteRateLimit` |
-| Registry identity voucher | 30 | inline in `registry.ts` |
-| Registry connect request | 3 | inline in `registryConnect.ts` |
-| External GFS read / mutation | 120 / 30 | `externalGfsReadRlPerMin` / `externalGfsOperationRlPerMin` |
+| Tier | Limit | Config anchor |
+| -------------------------------------------------------------- | ----------------------- | ------------------------------ |
+| Admin public token | 20 | `adminPublicTokenRlPerMin` |
+| Admin workflow grant read | 60 | `workflowGrantReadRateLimit` |
+| Admin workflow grant write | 20 | `workflowGrantWriteRateLimit` |
+| Registry identity voucher | 30 | inline in `registry.ts` |
+| Registry connect request | 3 | inline in `registryConnect.ts` |
+| External GFS read (resource, proxy, grants, shares) / mutation | 480, 480, 120, 120 / 90 | `externalGfsClassRlPerMin` |
## PR #428 / F4 scope (fixed in branch)