Skip to content

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

TypeScript

docs(plugin-sdk): remediate deep-review comment-truth + add rate-limit wiring guard

Alfredo Lopez25d0af691018
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 0a592e285..6adbc39fe 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.456",
+ "version": "0.1.457",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.456",
+ "version": "0.1.457",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index 970d5d636..6b11fdc69 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.456",
+ "version": "0.1.457",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/services/pluginWorkloadSdkDb.ts b/control-api/src/services/pluginWorkloadSdkDb.ts
index 920f57387..d584c15d9 100644
--- a/control-api/src/services/pluginWorkloadSdkDb.ts
+++ b/control-api/src/services/pluginWorkloadSdkDb.ts
@@ -12,7 +12,8 @@ import {
// Owns the three SDK tables:
// - plugin_workload_sdk_grants per-recipe capability grants
// - plugin_workload_sdk_invocations invocation audit trail
-// - plugin_workload_sdk_quota_counters per-recipe+period quota tracking
+// - plugin_workload_sdk_quota_counters historical-only counters (issue #348);
+// admin read path only, no writers
export const PLUGIN_WORKLOAD_SDK_FAMILIES = ['promptBridge', 'clientNotifications'] as const
export type PluginWorkloadSdkFamily = (typeof PLUGIN_WORKLOAD_SDK_FAMILIES)[number]
diff --git a/control-api/src/services/pluginWorkloadSdkSchema.ts b/control-api/src/services/pluginWorkloadSdkSchema.ts
index e08f7ddb3..600ad48ca 100644
--- a/control-api/src/services/pluginWorkloadSdkSchema.ts
+++ b/control-api/src/services/pluginWorkloadSdkSchema.ts
@@ -123,6 +123,10 @@ export async function applyPluginWorkloadSdkSchema(db: DbClient): Promise<void>
CREATE INDEX IF NOT EXISTS plugin_workload_sdk_invocations_recipe_created
ON plugin_workload_sdk_invocations (recipe_namespace, recipe_name, created_at DESC);
+ -- Historical-only since issue #348: per-run/period enforcement was removed
+ -- and nothing writes this table anymore (admin read path only). Retained so
+ -- existing rows stay queryable; hard removal is a separate follow-up. See the
+ -- note above getQuotaCounters in pluginWorkloadSdkDb.ts.
CREATE TABLE IF NOT EXISTS plugin_workload_sdk_quota_counters (
recipe_namespace TEXT NOT NULL,
recipe_name TEXT NOT NULL,
diff --git a/control-api/test/config.pluginSdkRateLimits.test.ts b/control-api/test/config.pluginSdkRateLimits.test.ts
index 467be895b..201f5b9b1 100644
--- a/control-api/test/config.pluginSdkRateLimits.test.ts
+++ b/control-api/test/config.pluginSdkRateLimits.test.ts
@@ -4,11 +4,11 @@ import { readFileSync } from 'node:fs'
/**
* Plugin Workload SDK platform rate-limit config (issue #348, plan D2).
*
- * RED-FIRST (plan §6.6): this suite asserts the POST-change target behavior.
- * Against pre-change code the four `pluginSdk*RlPerMin` config fields and the
- * four `CONTROL_API_PLUGIN_SDK_*_PER_MIN` ConfigMap keys do not exist yet, so
- * every test here FAILS until Phase 1 (step 1.1) and Phase 3 (D1) land. Do
- * not weaken these assertions to pass early.
+ * RED-FIRST (plan §6.6): the RED was captured pre-change — against the old
+ * code the four `pluginSdk*RlPerMin` config fields and the four
+ * `CONTROL_API_PLUGIN_SDK_*_PER_MIN` ConfigMap keys did not exist. Phase 1
+ * (step 1.1) and Phase 3 (D1) have LANDED, so the behavior asserted below is
+ * now live and this suite is GREEN. Do not weaken these assertions.
*
* Covered:
* 1. Code defaults 150/120/600/600 (decision Q3: recalibrated from the old
@@ -66,9 +66,9 @@ async function loadConfigWith(overrides: Partial<Record<RateLimitKey, string>>)
vi.resetModules()
try {
const mod = await import('../src/config.js')
- // The four fields are added by Phase 1 step 1.1; index access keeps the
- // TARGET assertion expressible before the Config type gains the fields
- // (the values are still asserted strictly below — no soft pass).
+ // The four fields exist on Config now; the widening cast is only to allow
+ // dynamic `config[field]` access in the it.each below (the values are
+ // asserted strictly there — no soft pass).
return mod.config as typeof mod.config & Record<string, unknown>
} finally {
for (const key of RATE_LIMIT_KEYS) {
@@ -179,4 +179,29 @@ describe('plugin SDK platform rate-limit config (issue #348)', () => {
expect(notificationsDescription).toContain('default 150')
expect(notificationsDescription).toContain('CONTROL_API_PLUGIN_SDK_NOTIFICATIONS_PER_MIN')
})
+
+ // Wiring guard: the request-bucket and pre-auth limits are only exercised for
+ // their config VALUE above; their two CONSUMERS must actually read the config
+ // field, not a hardcoded 600. A regression to `maxPerMinute: 600` / `limit:
+ // 600` would otherwise pass every value/default test. extractOne fails loud if
+ // the config reference is replaced by a literal.
+ it('wires the request-bucket limit from config in the SDK request middleware', () => {
+ const source = read('../src/middleware/pluginWorkloadSdkRateLimits.ts')
+ const field = extractOne(
+ source,
+ /maxPerMinute:\s*config\.(pluginSdkRequestBucketRlPerMin)\b/,
+ 'maxPerMinute wired from config in src/middleware/pluginWorkloadSdkRateLimits.ts'
+ )
+ expect(field).toBe('pluginSdkRequestBucketRlPerMin')
+ })
+
+ it('wires the pre-auth flood-guard limit from config in the SDK routes', () => {
+ const source = read('../src/routes/mcp-host/plugin-workload-sdk.routes.ts')
+ const field = extractOne(
+ source,
+ /limit:\s*config\.(pluginSdkPreauthRlPerMin)\b/,
+ 'limit wired from config in src/routes/mcp-host/plugin-workload-sdk.routes.ts'
+ )
+ expect(field).toBe('pluginSdkPreauthRlPerMin')
+ })
})
diff --git a/control-api/test/routes.adminPluginWorkloadSdk.test.ts b/control-api/test/routes.adminPluginWorkloadSdk.test.ts
index 178d43fce..632dcffd8 100644
--- a/control-api/test/routes.adminPluginWorkloadSdk.test.ts
+++ b/control-api/test/routes.adminPluginWorkloadSdk.test.ts
@@ -470,9 +470,9 @@ describe('routes/admin/pluginWorkloadSdk — grants', () => {
capabilityFamily: 'promptBridge',
provider: 'zai',
allowedCallers: ['api'],
- // Issue #348 (plan 2.6, RED until the strip lands): the deprecated
- // per-run key is tolerated on write but STRIPPED before persistence —
- // the persisted quotaLimits must be empty, not { maxRequestsPerRun: 10 }.
+ // Issue #348 (plan 2.6, strip has LANDED): the deprecated per-run key
+ // is tolerated on write but STRIPPED before persistence — the persisted
+ // quotaLimits must be empty, not { maxRequestsPerRun: 10 }.
quotaLimits: {},
}),
'11111111-1111-4111-8111-111111111111'
diff --git a/scripts/e2e/e2e-plugin-workload-sdk.sh b/scripts/e2e/e2e-plugin-workload-sdk.sh
index 47317ba75..241d989ab 100755
--- a/scripts/e2e/e2e-plugin-workload-sdk.sh
+++ b/scripts/e2e/e2e-plugin-workload-sdk.sh
@@ -1381,7 +1381,7 @@ fi
if printf "%s" "$logs" | grep -q E2E_SDK_QUOTA_EXCEEDED_OK; then
ok "per-minute rate limit rejected the 5th call after 4/4 invocations in the window"
else
- fail "per-minute rate limit did not reject the 5th call (fixture marker missing; caller logs redacted)"
+ fail "per-minute rate limit did not reject the 5th call (fixture marker missing; caller logs redacted). If the caller logged E2E_SDK_QUOTA_EXCEEDED_FAIL=*:possible_window_ageout or *:window_overcount, this is the known per-minute 60s-window timing race (issue #348 fixture caveat), not a real enforcement regression — retry on a less loaded cluster or apply the coordinated gate+fixture reset fix."
exit 1
fi
diff --git a/tests/e2e/fixtures/package-lock.json b/tests/e2e/fixtures/package-lock.json
index 94f1ebf6c..0a277b6b7 100644
--- a/tests/e2e/fixtures/package-lock.json
+++ b/tests/e2e/fixtures/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.58",
+ "version": "1.0.59",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.58",
+ "version": "1.0.59",
"dependencies": {
"@kubernetes/client-node": "^1.0.0"
},
diff --git a/tests/e2e/fixtures/package.json b/tests/e2e/fixtures/package.json
index b86ee8892..0b583c9a0 100644
--- a/tests/e2e/fixtures/package.json
+++ b/tests/e2e/fixtures/package.json
@@ -1,6 +1,6 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.58",
+ "version": "1.0.59",
"description": "E2E test fixtures and utilities for Clerum testing",
"type": "module",
"main": "index.ts",
diff --git a/tests/e2e/fixtures/workflow-plugin-sdk-e2e/src/index.js b/tests/e2e/fixtures/workflow-plugin-sdk-e2e/src/index.js
index 05d475af5..9f9993c56 100644
--- a/tests/e2e/fixtures/workflow-plugin-sdk-e2e/src/index.js
+++ b/tests/e2e/fixtures/workflow-plugin-sdk-e2e/src/index.js
@@ -277,6 +277,21 @@ async function exerciseIdempotency() {
// The default and explicit-target prompt calls consumed 2 slots; the
// idempotency replay does NOT consume a slot. Fill the remaining slots, then
// attempt one beyond.
+//
+// PER-MINUTE WINDOW CAVEAT (issue #348): enforcement moved from a per-run
+// counter (no clock) to a trailing 60s window. Reusing the Phase-1 happy call
+// and the Phase-2 explicit call as 2 of the QUOTA_LIMIT slots means those two
+// rows must still be inside the 60s window when the exceed call fires. Rows are
+// timestamped record-first (call start), but the SPACING between them absorbs
+// real provider latency (up to ~15s/promptBridge fetch + notification
+// transport). If the happy row ages past 60s before the exceed call, the window
+// count drops below the limit and the exceed call is wrongly ACCEPTED — a
+// spurious RED (never a false pass). A deterministic fix requires the gate to
+// reset invocation rows immediately before a tight, self-contained quota burst
+// so earlier phases can't age out of the window; that coordinated gate+fixture
+// change must be validated on a live minikube cert run (deferred). Until then
+// the FAIL reasons below name the window hypothesis so a spurious RED is
+// diagnosable at a glance.
async function exerciseQuotaEnforcement() {
try {
const remaining = QUOTA_LIMIT - 2
@@ -288,7 +303,10 @@ async function exerciseQuotaEnforcement() {
})
if (status !== 200) {
const code = (body && (body.error || body.code)) || `http_${status}`
- log(`E2E_SDK_QUOTA_EXCEEDED_FAIL=fill_call_failed:${code}`)
+ // A quota/429 here means an EARLIER phase's rows plus these fills already
+ // crossed the per-minute limit within the 60s window (window over-count).
+ const hint = code.includes('quota') || status === 429 ? ':window_overcount' : ''
+ log(`E2E_SDK_QUOTA_EXCEEDED_FAIL=fill_call_failed:${code}${hint}`)
return
}
}
@@ -307,7 +325,10 @@ async function exerciseQuotaEnforcement() {
log(`E2E_SDK_QUOTA_EXCEEDED_FAIL=wrong_error:${code}`)
}
} else {
- log('E2E_SDK_QUOTA_EXCEEDED_FAIL=call_accepted_after_quota_exhausted')
+ // Accepted when it should have been denied. Under per-minute semantics the
+ // likeliest cause is an earlier filler row aging past the 60s window
+ // before this call, so the in-window count fell below the limit.
+ log('E2E_SDK_QUOTA_EXCEEDED_FAIL=call_accepted_after_quota_exhausted:possible_window_ageout')
}
} catch (err) {
log(`E2E_SDK_QUOTA_EXCEEDED_FAIL=exception:${err && err.message ? err.message : err}`)