Skip to content

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

TypeScript

fix(mcp-host): validate the stall timeout default, sync timeout and timer range

Alfredo Lopez4d20e3b58e9e
diff --git a/docs/architecture/host-storage-layout.md b/docs/architecture/host-storage-layout.md
index 657285399..3507883ce 100644
--- a/docs/architecture/host-storage-layout.md
+++ b/docs/architecture/host-storage-layout.md
@@ -208,8 +208,9 @@ renames the entry.
restarts the container; a persistent cause shows as `CrashLoopBackOff`.
- A slow write is not a failure. If the worker has operations in flight and
completes none of them for `CLERUM_DB_WORKER_STALL_TIMEOUT_MS` (default
- `30000`, at least `1000` and above `CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS`), the
- queue fails the same way and the worker is terminated.
+ `30000`, at least `1000`, at most `2147483647` and above
+ `CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS`, or config load fails), the queue fails
+ the same way and the worker is terminated.
- At shutdown mcp-host waits for every queued write, bounded only by that
stall timeout and the Pod's termination grace period. A persistence failure
during shutdown exits 1 instead of 0.
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 6f22977d7..e17d1645e 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.590",
+ "version": "0.1.591",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.590",
+ "version": "0.1.591",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 1bbb5a71d..121a0584d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.590",
+ "version": "0.1.591",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/config.dbWorkerStallTimeout.test.ts b/mcp-host/src/__tests__/config.dbWorkerStallTimeout.test.ts
index ed205b15c..047914b18 100644
--- a/mcp-host/src/__tests__/config.dbWorkerStallTimeout.test.ts
+++ b/mcp-host/src/__tests__/config.dbWorkerStallTimeout.test.ts
@@ -18,6 +18,31 @@ describe('CLERUM_DB_WORKER_STALL_TIMEOUT_MS', () => {
)
})
+ it('accepts the largest value a timer can hold', () => {
+ expect(parseDbWorkerStallTimeoutMs('2147483647', 2000)).toBe(2_147_483_647)
+ })
+
+ it('rejects a value a timer cannot hold', () => {
+ // Node clamps a larger delay to 1 ms, which would turn the bound into a busy loop.
+ expect(() => parseDbWorkerStallTimeoutMs('2147483648', 2000)).toThrow(
+ "CLERUM_DB_WORKER_STALL_TIMEOUT_MS='2147483648' must not exceed 2147483647"
+ )
+ })
+
+ it('rejects the default when it does not exceed the sync timeout', () => {
+ // Liveness witness: the same default passes against the default sync timeout.
+ expect(parseDbWorkerStallTimeoutMs('', 2000)).toBe(30_000)
+ expect(() => parseDbWorkerStallTimeoutMs('', 60_000)).toThrow(
+ "CLERUM_DB_WORKER_STALL_TIMEOUT_MS='30000' (default) must exceed CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (60000)"
+ )
+ })
+
+ it.each([Number.NaN, 0, -1, 1.5])('rejects a sync timeout of %s', syncTimeoutMs => {
+ expect(() => parseDbWorkerStallTimeoutMs('5000', syncTimeoutMs)).toThrow(
+ `CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (${syncTimeoutMs}) must be a positive integer`
+ )
+ })
+
it('rejects a value that does not exceed the sync timeout', () => {
expect(() => parseDbWorkerStallTimeoutMs('2000', 2000)).toThrow(
"CLERUM_DB_WORKER_STALL_TIMEOUT_MS='2000' must exceed CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (2000)"
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 25133690f..bd3032975 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -478,22 +478,33 @@ export function parseStatelessHeartbeatIntervalMs(raw: string | undefined): numb
* Parse CLERUM_DB_WORKER_STALL_TIMEOUT_MS, the longest time the db worker may
* go without completing an operation while it has work in flight. It must
* exceed the sync write timeout, so a sync write times out on its own budget
- * before the worker is declared stalled. An explicit invalid value fails at
- * boot.
+ * before the worker is declared stalled. It must fit a Node timer (at most
+ * 2147483647 ms; a larger delay becomes 1 ms). An invalid value, the default
+ * included, fails at boot, as does a sync timeout that is not a positive
+ * integer.
*/
export function parseDbWorkerStallTimeoutMs(
raw: string | undefined,
syncTimeoutMs: number
): number {
- if (raw === undefined || raw.trim() === '') return 30_000
+ if (!Number.isSafeInteger(syncTimeoutMs) || syncTimeoutMs <= 0) {
+ throw new Error(
+ `CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (${syncTimeoutMs}) must be a positive integer`
+ )
+ }
const name = 'CLERUM_DB_WORKER_STALL_TIMEOUT_MS'
- const value = /^\d+$/.test(raw) ? Number(raw) : NaN
+ const isDefault = raw === undefined || raw.trim() === ''
+ const label = isDefault ? "'30000' (default)" : `'${raw}'`
+ const value = isDefault ? 30_000 : /^\d+$/.test(raw) ? Number(raw) : NaN
if (!Number.isSafeInteger(value) || value < 1000) {
- throw new Error(`${name}='${raw}' must be an integer of at least 1000`)
+ throw new Error(`${name}=${label} must be an integer of at least 1000`)
+ }
+ if (value > 2_147_483_647) {
+ throw new Error(`${name}=${label} must not exceed 2147483647`)
}
if (value <= syncTimeoutMs) {
throw new Error(
- `${name}='${raw}' must exceed CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (${syncTimeoutMs})`
+ `${name}=${label} must exceed CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (${syncTimeoutMs})`
)
}
return value