Skip to content

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

TypeScript

fix(proxy): log the refusal type, bound the visual body limit, tighten the visual-gate tests

Alfredo Lopez42c7596d83e7
diff --git a/codex-llm-proxy/src/auth/platformJwtVerifier.ts b/codex-llm-proxy/src/auth/platformJwtVerifier.ts
index 211ba02be..5246d9ab5 100644
--- a/codex-llm-proxy/src/auth/platformJwtVerifier.ts
+++ b/codex-llm-proxy/src/auth/platformJwtVerifier.ts
@@ -25,7 +25,7 @@ export function verifyPlatformJwt(
if (!Array.isArray(claims.hostRefs) || !Array.isArray(claims.workflowControlScopes)) {
return null
}
- // A11.7 V3: `sub` becomes part of the per-principal visual admission key,
+ // `sub` becomes part of the per-principal visual admission key,
// so a missing, empty or non-string sub must fail verification instead of
// collapsing every such caller onto the literal principal "undefined".
const sub = claims.sub
diff --git a/codex-llm-proxy/src/config.ts b/codex-llm-proxy/src/config.ts
index 43bc42e72..63d106ce5 100644
--- a/codex-llm-proxy/src/config.ts
+++ b/codex-llm-proxy/src/config.ts
@@ -89,7 +89,15 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): CodexLlmProxyC
if (maxVisualBodyBytes < LIMITS.maxVisualRequestBodyBytes) {
throw new Error('Visual Codex requests require the full shared envelope byte budget')
}
- // Y2 — an equal or lower budget would collapse visual admission into the
+ // The 1Gi memory limit was measured with two visual streams at the contract
+ // ceiling only (see IN_FLIGHT_BODY_BUDGET_BODIES). A larger value would admit
+ // bodies that measurement never covered.
+ if (maxVisualBodyBytes > LIMITS.maxVisualRequestBodyBytes) {
+ throw new Error(
+ `CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at most ${LIMITS.maxVisualRequestBodyBytes}, the contract maxVisualRequestBodyBytes`
+ )
+ }
+ // An equal or lower budget would collapse visual admission into the
// ordinary parser's cap, so the visual gate's separate accounting would
// never engage.
if (maxVisualBodyBytes <= maxBodyBytes) {
diff --git a/codex-llm-proxy/src/requestLimits.ts b/codex-llm-proxy/src/requestLimits.ts
index 1ef4f7db0..8a3944325 100644
--- a/codex-llm-proxy/src/requestLimits.ts
+++ b/codex-llm-proxy/src/requestLimits.ts
@@ -21,15 +21,17 @@ export const DEFAULT_MAX_BODY_BYTES = CONTRACT_LIMITS.maxRequestBodyBytes + ENVE
* (the raw buffer, the decoded string, the parsed object, the contract copy and
* more than one serialization of it). Without this bound the stream gate would
* let 24 bodies in.
- * Bodies over the ordinary cap never take this budget: they are V2 visual
- * envelopes, bounded by `visualStreamGate` instead, so the declared bodies a pod
- * can hold at once are 3 x 8 MiB here plus 2 x 24 MiB there. Measured with the
+ * A body whose Content-Length exceeds the ordinary cap is read under
+ * `visualStreamGate`. If it parses to a size within the ordinary cap
+ * (demotion), it takes a reservation for that size before releasing the
+ * visual slot, so the declared bodies a pod can hold at once are still 3 x 8
+ * MiB here plus 2 x 24 MiB there. Measured with the
* full load the gates admit (eight 8 MiB streams, two 24 MiB visual streams
* and three queued 8 MiB bodies, #739 D5), the process peaked at 790 MiB of
* RSS with `--max-old-space-size=384` and at 886-1009 MiB with an uncapped
* heap, which is why the deployment sets that cap and a 1Gi memory limit.
*
- * A8 — bytes alone do not bound the parse: JSON.parse allocates one heap
+ * Bytes alone do not bound the parse: JSON.parse allocates one heap
* object per container, so the contracts cap containers at
* `maxRequestContainers` (262 144) and every parser scans the raw body for it
* before JSON.parse. Measured in this proxy (tsc build,
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index 50b5fe372..f36da2580 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -104,13 +104,20 @@ function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
}
-function reject(res: Response, status: number, code: string): void {
+/**
+ * `type` is the fixed error type of a refused body (body-parser's or the
+ * structure scan's), never a message or any part of the body.
+ */
+function reject(res: Response, status: number, code: string, type?: string): void {
if (res.headersSent) return
- logger.warn({ event: 'codex_proxy_denied', code }, 'request denied')
+ logger.warn(
+ type === undefined ? { event: 'codex_proxy_denied', code } : { event: 'codex_proxy_denied', code, type },
+ 'request denied'
+ )
res.status(status).json({ error: code })
}
-// A8: every JSON parser scans the raw body before JSON.parse. JSON.parse
+// Every JSON parser scans the raw body before JSON.parse. JSON.parse
// allocates one heap object per container, so a body within the byte limit
// can still exhaust the heap; the scan refuses a body denser, more nested or
// with more containers than any request the contract accepts. Its depth bound
@@ -120,18 +127,21 @@ const verifyBodyStructure = createBodyStructureVerify(BODY_STRUCTURE_LIMITS)
function boundedErrorHandler(err: unknown, _req: Request, res: Response, _next: () => void): void {
const typed = err as { type?: string; status?: number; body?: unknown }
+ // The refusals below share one response code per status, so the logged type
+ // is what tells a structural 413 from a byte-limit 413.
+ const type = typeof typed?.type === 'string' ? typed.type : undefined
if (typed?.type === 'entity.too.large' || typed?.status === 413) {
- reject(res, 413, 'payload_too_large')
+ reject(res, 413, 'payload_too_large', type)
return
}
// R9-1: the parsers run with `inflate: false`, so body-parser refuses an
// encoded body before reading it.
if (typed?.type === 'encoding.unsupported' || typed?.type === 'charset.unsupported') {
- reject(res, 415, 'unsupported_media_type')
+ reject(res, 415, 'unsupported_media_type', type)
return
}
if (err instanceof SyntaxError || typed?.type === 'body.structure.too.deep') {
- reject(res, 400, 'invalid_request')
+ reject(res, 400, 'invalid_request', type)
return
}
// body-parser attaches the raw body to an error thrown by `verify` or by
@@ -359,7 +369,7 @@ export function createProxyApps(
ordinaryJson(req, res, next)
return
}
- // B4 / A11.7 V3: one principal gets a fair share of the visual gate, so a
+ // One principal gets a fair share of the visual gate, so a
// single host cannot fill the entries every other host also needs. The
// share is taken before the gate wait, so queued entries count too.
const platform = req.codexPlatform
@@ -392,7 +402,19 @@ export function createProxyApps(
const releasePrincipalShare = (): void => {
if (!principalShareHeld) return
principalShareHeld = false
- const remaining = (visualPrincipalAdmissions.get(visualPrincipal) ?? 1) - 1
+ const held = visualPrincipalAdmissions.get(visualPrincipal)
+ if (held === undefined) {
+ // A held share always has an entry, so a missing one is a counting
+ // defect. This runs from `close` handlers, where a throw has no
+ // caller to reach, so it is logged and the release completes.
+ logger.error(
+ { event: 'codex_proxy_error', reason: 'principal_share_missing', sub: platform.sub },
+ 'visual principal share missing at release'
+ )
+ visualPrincipalAdmissions.delete(visualPrincipal)
+ return
+ }
+ const remaining = held - 1
if (remaining > 0) visualPrincipalAdmissions.set(visualPrincipal, remaining)
else visualPrincipalAdmissions.delete(visualPrincipal)
}
@@ -443,7 +465,7 @@ export function createProxyApps(
}, bodyReadDeadlineMs)
res.once('close', () => {
clearTimeout(readDeadline)
- // Backstop only while the admission is still held here. A kept
+ // The close handler releases only while the slot is still held here. A kept
// visual body transfers `req.codexStreamRelease` into the handler,
// which clears the field and releases in its outer `finally`. A
// demoted body releases through `releaseAdmission` before it joins
@@ -634,7 +656,7 @@ export function createProxyApps(
release = gated.codexStreamRelease
gated.codexStreamRelease = undefined
} else if (gated.codexStreamRelease) {
- // A8 D3: a demoted body was read through the visual gate, so it holds
+ // A demoted body was read through the visual gate, so it holds
// no body-budget reservation. It takes one for its compact size
// before it gives up the visual slot, so the 8-wide stream gate
// never holds more resident bodies than the budget admits. Every
diff --git a/codex-llm-proxy/test/bodyStructure.test.ts b/codex-llm-proxy/test/bodyStructure.test.ts
index 778b88bb8..ba9894c5b 100644
--- a/codex-llm-proxy/test/bodyStructure.test.ts
+++ b/codex-llm-proxy/test/bodyStructure.test.ts
@@ -19,7 +19,7 @@ import {
} from '../src/requestLimits.js'
import { type ProxyRuntimeDeps, createProxyApps } from '../src/server.js'
-// A8: JSON.parse allocates one heap object per container, so a body that fits
+// JSON.parse allocates one heap object per container, so a body that fits
// every byte limit can still exhaust the proxy heap. Every parser scans the raw
// body against BODY_STRUCTURE_LIMITS before JSON.parse runs. These tests pin
// where each refusal happens (before the parse) and that a body at both the
@@ -287,7 +287,7 @@ function controlledStream() {
return { calls, impl }
}
-describe('codex proxy raw-body structure bounds (A8)', () => {
+describe('codex proxy raw-body structure bounds', () => {
const streams: Array<ReturnType<typeof controlledStream>> = []
const serversToClose: Array<{ close: () => Promise<void> }> = []
const listeners: Array<ReturnType<typeof createServer>> = []
@@ -619,12 +619,52 @@ describe('codex proxy raw-body structure bounds (A8)', () => {
const refused = await post(port, over)
expect(refused.status).toBe(413)
expect(warn).toHaveBeenCalledWith(
- { event: 'codex_proxy_denied', code: 'payload_too_large' },
+ {
+ event: 'codex_proxy_denied',
+ code: 'payload_too_large',
+ type: 'body.structure.too.many.containers',
+ },
'request denied'
)
expect(loggedText(warn, error, info)).not.toContain(MARKER)
})
+ it('logs the fixed refusal type of a structural 413, a byte-limit 413 and a too-deep 400', async () => {
+ const warn = vi.spyOn(logger, 'warn')
+ const denied = (): unknown[] =>
+ warn.mock.calls
+ .map(([entry]) => entry)
+ .filter(entry => (entry as { event?: unknown } | undefined)?.event === 'codex_proxy_denied')
+ const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
+
+ const base = measure(bodyWithFiller('codex-completion-request.v2', wideNumbers(1))).structuralBytes
+ const count = Math.ceil((BODY_STRUCTURE_LIMITS.maxStructuralBytes + 1 - base) / 9) + 1
+ const dense = await post(port, bodyWithFiller('codex-completion-request.v2', wideNumbers(count)))
+ expect(dense.status).toBe(413)
+
+ const deep = await post(port, bodyWithDepth(BODY_STRUCTURE_LIMITS.maxDepth + 1))
+ expect(deep.status).toBe(400)
+
+ // The admin parser answers a declared length over its limit from the
+ // header, as body-parser's `entity.too.large`.
+ const adminPort = listen(createProxyApps(config({ maxBodyBytes: 4096 })), 'adminApp')
+ const tooLarge = await fetch(`http://127.0.0.1:${adminPort}/internal/admin/v1/codex/models`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${adminPermit()}`, 'content-type': 'application/json' },
+ body: JSON.stringify({ filler: 'x'.repeat(4096) }),
+ })
+ expect(tooLarge.status).toBe(413)
+ expect(await tooLarge.json()).toEqual({ error: 'payload_too_large' })
+
+ // The two 413s carry the same response code; only the logged type tells
+ // them apart. The exact list is also the witness that each refusal ran.
+ expect(denied()).toEqual([
+ { event: 'codex_proxy_denied', code: 'payload_too_large', type: 'body.structure.too.dense' },
+ { event: 'codex_proxy_denied', code: 'invalid_request', type: 'body.structure.too.deep' },
+ { event: 'codex_proxy_denied', code: 'payload_too_large', type: 'entity.too.large' },
+ ])
+ })
+
it('logs only the type and status of an unmapped verify error', async () => {
const warn = vi.spyOn(logger, 'warn')
const error = vi.spyOn(logger, 'error')
@@ -644,7 +684,8 @@ describe('codex proxy raw-body structure bounds (A8)', () => {
const error = vi.spyOn(logger, 'error')
const fault = new Error('visual gate fault')
const acquire = vi.spyOn(visualStreamGate, 'acquire').mockRejectedValueOnce(fault)
- const largeParses = spyLargeParses()
+ const parse = vi.spyOn(JSON, 'parse')
+ const parsedTexts = (): unknown[] => parse.mock.calls.map(([text]) => text)
const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
const body = bodyWithContainers('codex-completion-request.v2', 8)
@@ -656,7 +697,14 @@ describe('codex proxy raw-body structure bounds (A8)', () => {
expect(await res.json()).toEqual({ error: 'internal_error' })
expect(acquire).toHaveBeenCalledTimes(1)
expect(error).toHaveBeenCalledWith({ event: 'codex_proxy_error', err: fault }, 'unhandled request error')
- expect(largeParses()).not.toContain(padded.length)
+ expect(parsedTexts()).not.toContain(padded)
+
+ // Witness: the same body through a working gate reaches JSON.parse as this
+ // exact text, so the assertion above would see a parse had one happened.
+ const admitted = await post(port, padded)
+ expect(admitted.status).toBe(403)
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(parsedTexts()).toContain(padded)
})
describe('a demoted visual body (declared above the ordinary cap, compact below it)', () => {
diff --git a/codex-llm-proxy/test/requestLimits.test.ts b/codex-llm-proxy/test/requestLimits.test.ts
index d96428a31..9edbfb5f6 100644
--- a/codex-llm-proxy/test/requestLimits.test.ts
+++ b/codex-llm-proxy/test/requestLimits.test.ts
@@ -8,6 +8,7 @@ import {
VISUAL_PER_HOST_MAX_ADMITTED,
VISUAL_STREAM_LIMITS,
assertBoundedDeadline,
+ visualStreamGate,
} from '../src/requestLimits.js'
import { DEFAULT_HEARTBEAT_INTERVAL_MS, MAX_HEARTBEAT_INTERVAL_MS } from '../src/sseHeartbeat.js'
@@ -409,4 +410,22 @@ describe('StreamGate', () => {
for (const release of held) release()
for (const waiter of queued) (await waiter)()
})
+
+ it('builds the shared visual gate from VISUAL_STREAM_LIMITS', async () => {
+ const { maxConcurrentStreams, maxQueuedRequests } = VISUAL_STREAM_LIMITS
+ const held: Array<() => void> = []
+ for (let i = 0; i < maxConcurrentStreams; i += 1) held.push(await visualStreamGate.acquire())
+ expect(visualStreamGate.snapshot()).toEqual({ running: maxConcurrentStreams, queued: 0 })
+ // Width: every caller past maxConcurrentStreams queues instead of running.
+ const queued = Array.from({ length: maxQueuedRequests }, () => visualStreamGate.acquire())
+ expect(visualStreamGate.snapshot()).toEqual({
+ running: maxConcurrentStreams,
+ queued: maxQueuedRequests,
+ })
+ // Queue capacity: the caller after maxQueuedRequests is refused.
+ await expect(visualStreamGate.acquire()).rejects.toMatchObject({ kind: 'queue_full' })
+ for (const release of held) release()
+ for (const waiter of queued) (await waiter)()
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ })
})
diff --git a/codex-llm-proxy/test/server.security.test.ts b/codex-llm-proxy/test/server.security.test.ts
index dee51a214..92bd05235 100644
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@ -7,11 +7,14 @@ import { describe, expect, it, vi } from 'vitest'
import {
ENVELOPE_ALLOWANCE_BYTES as CONTRACT_ENVELOPE_ALLOWANCE_BYTES,
LIMITS,
+ hashCodexCompletionRequest,
hashCodexCompletionRequestV1,
+ parseCodexCompletionRequest,
parseCodexCompletionRequestV1,
} from '@clerum/llm-provider-attempt-contract'
import { verifyAdminPermit } from '../src/auth/adminPermitVerifier.js'
import { verifyExecutionTicket } from '../src/auth/executionTicketVerifier.js'
+import { CodexTransportError } from '../src/codexTransport.js'
import { loadConfig, type CodexLlmProxyConfig } from '../src/config.js'
import {
ControlApiClient,
@@ -27,6 +30,7 @@ import {
ENVELOPE_ALLOWANCE_BYTES,
RequestLimitError,
STREAM_LIMITS,
+ VISUAL_STREAM_LIMITS,
streamGate,
visualStreamGate,
} from '../src/requestLimits.js'
@@ -270,6 +274,48 @@ describe('codex-llm-proxy security surface', () => {
acquire.mockRestore()
}, 30_000)
+ it('answers a transport payload_too_large with HTTP 413 before any SSE byte', async () => {
+ const raw = {
+ schemaVersion: 'codex-completion-request.v1',
+ requestId: 'req-payload-too-large',
+ idempotencyKey: 'idem-payload-too-large',
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'hello' }],
+ }
+ const parsed = parseCodexCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashCodexCompletionRequestV1(parsed.value)
+ const executionTicket = sign(
+ {
+ jti: '12121212-1212-4121-8121-121212121212',
+ typ: 'codex-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: 'att-payload-too-large',
+ },
+ 'codex-llm-proxy'
+ )
+ let streamCalls = 0
+ const { runtimeApp, probeApp } = createProxyApps(config({ maxBodyBytes: 65_536 }), {
+ streamCompletion: async () => {
+ streamCalls += 1
+ throw new CodexTransportError('payload_too_large', 'request exceeds maxVisualRequestBodyBytes')
+ },
+ })
+ const res = await request(runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({ executionTicket, requestHash, request: raw })
+ // Witness: the request reached the transport.
+ expect(streamCalls).toBe(1)
+ expect(res.status).toBe(413)
+ expect(res.body).toEqual({ error: 'payload_too_large' })
+ const metricsText = (await request(probeApp).get('/metrics')).text
+ expect(metricsText).toMatch(/^codex_proxy_attempt_failures_total\{code="payload_too_large"\} 1$/m)
+ })
+
it('does not let a V2 declaration raise the non-image budget to 24 MiB', async () => {
const { runtimeApp } = createProxyApps(config({ maxBodyBytes: DEFAULT_MAX_BODY_BYTES }))
// One byte of text past the non-image ceiling plus its envelope allowance,
@@ -589,8 +635,39 @@ describe('codex-llm-proxy security surface', () => {
expect(loadConfig(required).maxVisualBodyBytes).toBe(24 * 1024 * 1024)
})
- // Y2 — with an equal budget every visual envelope would also fit the
- // ordinary parser's cap, so the visual gate's separate admission and memory
+ // The 1Gi memory limit was measured with two visual streams at the contract
+ // ceiling. A larger visual limit would admit bodies that measurement never
+ // covered, so the proxy refuses to start with one.
+ it('refuses a visual body limit above the contract visual ceiling', () => {
+ const required = {
+ CODEX_LLM_PROXY_JWT_PUBLIC_KEY: publicKey,
+ CODEX_LLM_PROXY_CONTROL_API_URL:
+ 'http://control-api-rpc-gateway.control-plane.svc.cluster.local:8090/api/v1',
+ CODEX_LLM_PROXY_CONTROL_API_TOKEN: 'dev-codex-llm-proxy-token',
+ }
+ expect(LIMITS.maxVisualRequestBodyBytes).toBe(25_165_824)
+ expect(() =>
+ loadConfig({
+ ...required,
+ CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes + 1),
+ })
+ ).toThrow(
+ `CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at most ${LIMITS.maxVisualRequestBodyBytes}, the contract maxVisualRequestBodyBytes`
+ )
+ expect(() =>
+ loadConfig({ ...required, CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(64 * 1024 * 1024) })
+ ).toThrow(/^CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at most 25165824,/)
+ // Witness: the ceiling itself loads.
+ expect(
+ loadConfig({
+ ...required,
+ CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes),
+ }).maxVisualBodyBytes
+ ).toBe(LIMITS.maxVisualRequestBodyBytes)
+ })
+
+ // With an equal budget every visual envelope would also fit the ordinary
+ // parser's cap, so the visual gate's separate admission and memory
// accounting would never engage.
it('refuses a visual body limit less than or equal to the ordinary body limit', () => {
const required = {
@@ -618,14 +695,16 @@ describe('codex-llm-proxy security surface', () => {
).toThrow(
'CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be greater than CODEX_LLM_PROXY_MAX_BODY_BYTES'
)
- // Liveness witness: one byte above the ordinary limit loads.
+ // Liveness witness: a visual limit one byte above the ordinary limit loads.
+ // The visual limit is pinned to the contract ceiling, so the ordinary limit
+ // moves instead.
expect(
loadConfig({
...required,
- CODEX_LLM_PROXY_MAX_BODY_BYTES: String(equal),
- CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(equal + 1),
+ CODEX_LLM_PROXY_MAX_BODY_BYTES: String(equal - 1),
+ CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(equal),
}).maxVisualBodyBytes
- ).toBe(equal + 1)
+ ).toBe(equal)
})
})
@@ -1939,6 +2018,89 @@ describe('codex-llm-proxy ticket-aware stream-gate wait (#739 D1-bis)', () => {
await releaseAndDrain(slots)
}
}, 30_000)
+
+ /** A V2 envelope past `maxBodyBytes`, so it takes the visual gate. */
+ function visualEnvelope(providerAttemptId: string, ticketLifeMs: number): Record<string, unknown> {
+ const raw: Record<string, unknown> = {
+ schemaVersion: 'codex-completion-request.v2',
+ requestId: `req-${providerAttemptId}`,
+ idempotencyKey: `idem-${providerAttemptId}`,
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'x'.repeat(80_000) }],
+ }
+ const parsed = parseCodexCompletionRequest(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashCodexCompletionRequest(parsed.value)
+ const executionTicket = jwt.sign(
+ {
+ jti: '78787878-7878-4787-8787-787878787878',
+ typ: 'codex-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId,
+ exp: (Date.now() + ticketLifeMs) / 1000,
+ },
+ privateKey,
+ { algorithm: 'RS256', issuer: 'control-api', audience: 'codex-llm-proxy' }
+ )
+ return { executionTicket, requestHash, request: raw }
+ }
+
+ // R17-2 on the visual path: the visual gate is taken before the body is
+ // parsed, so the ticket is read only once a slot frees. A ticket that died
+ // during that wait reaches the ticket gate expired, and the answer is the
+ // retryable ticket_expired, not the stream gate's ticket-life refusal.
+ it('T-R17-2-visual answers ticket_expired when the ticket died while the body waited at the visual gate', async () => {
+ fakeClock()
+ const warn = vi.spyOn(logger, 'warn')
+ const held: Array<() => void> = []
+ try {
+ for (let i = 0; i < VISUAL_STREAM_LIMITS.maxConcurrentStreams; i += 1) {
+ held.push(await visualStreamGate.acquire())
+ }
+ const control = countingClient('granted')
+ const apps = createProxyApps(config({ maxBodyBytes: 65_536 }), {
+ controlApiClient: control.client,
+ fetchFn: upstream,
+ lookup,
+ })
+ const ticketLifeMs = 20_000
+ const body = visualEnvelope('att-visual-expired', ticketLifeMs)
+ expect(Buffer.byteLength(JSON.stringify(body))).toBeGreaterThan(65_536)
+ const reply = request(apps.runtimeApp)
+ .post(COMPLETIONS)
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(body)
+ .then(res => res)
+ await until(() => visualStreamGate.snapshot().queued === 1, 'the body queueing at the visual gate')
+
+ await vi.advanceTimersByTimeAsync(ticketLifeMs)
+ // Witness: the body was still waiting for a slot at the ticket's expiry.
+ expect(await withinReal(reply, 100)).toBeUndefined()
+ held.pop()?.()
+ // One stream-gate poll interval.
+ await vi.advanceTimersByTimeAsync(10)
+ const res = await withinReal(reply, 2_000)
+ expect(res?.status).toBe(403)
+ expect(res?.body).toEqual({ error: 'ticket_expired' })
+ expect(control.redeems()).toBe(0)
+
+ const events = warn.mock.calls.map(call => call[0] as unknown as Record<string, unknown>)
+ expect(events.filter(entry => entry?.event === 'codex_proxy_denied')).toEqual([
+ { event: 'codex_proxy_denied', code: 'ticket_expired' },
+ ])
+ expect(events.filter(entry => entry?.event === 'codex_proxy_admission_refused')).toEqual([])
+ // The ticket refusal released the visual slot the body was parsed under.
+ expect(visualStreamGate.snapshot()).toEqual({ running: held.length, queued: 0 })
+ expect(streamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ } finally {
+ for (const release of held.splice(0)) release()
+ vi.useRealTimers()
+ warn.mockRestore()
+ }
+ }, 30_000)
})
/**
@@ -1946,7 +2108,7 @@ describe('codex-llm-proxy ticket-aware stream-gate wait (#739 D1-bis)', () => {
* copies of it are alive: reading, parsing, hashing and forwarding. That phase
* ends when the upstream fetch resolves, because the whole request body has
* been written by then. The reservation is released there instead of when the
- * SSE stream closes; the response's `close` event stays the backstop for every
+ * SSE stream closes; the response's `close` event still releases it on every
* path that never reaches the upstream.
*/
describe('codex-llm-proxy body budget release on upstream acceptance (#739 D2)', () => {
diff --git a/codex-llm-proxy/test/streamGate.handoff.test.ts b/codex-llm-proxy/test/streamGate.handoff.test.ts
index 13a402958..1d19ee583 100644
--- a/codex-llm-proxy/test/streamGate.handoff.test.ts
+++ b/codex-llm-proxy/test/streamGate.handoff.test.ts
@@ -478,23 +478,74 @@ describe('visual stream-gate handoff', () => {
}
it('refuses a platform token whose sub is not a non-empty string with 401', async () => {
- const port = listen(createProxyApps(config()))
+ const maxBodyBytes =
+ Buffer.byteLength(completionPayload('codex-completion-request.v1').body) + 512
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const port = listen(createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 })))
const claims = {
hostRefs: ['research-host'],
workflowControlScopes: ['llm:codex:execute'],
scope: 'workflow:approval:request',
}
+ // Each body is large enough to take the visual gate once its token passes.
for (const bearerToken of [
sign(claims, 'workflow-approvals'),
sign({ ...claims, sub: '' }, 'workflow-approvals'),
sign({ ...claims, sub: 403 }, 'workflow-approvals'),
]) {
- const res = await postBody(port, bearerToken, JSON.stringify({ probe: 1 }))
+ const res = await postBody(port, bearerToken, invalidTicketBody(maxBodyBytes))
expect(res.status).toBe(401)
expect(await res.json()).toEqual({ error: 'Unauthorized' })
}
- // Liveness witness: none of those requests reached body admission.
- expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ expect(acquire).not.toHaveBeenCalled()
+
+ // Positive control: the same body with a valid sub reaches the visual
+ // gate and then the ticket check.
+ const admitted = await postBody(
+ port,
+ sign({ ...claims, sub: 'default/research-host' }, 'workflow-approvals'),
+ invalidTicketBody(maxBodyBytes)
+ )
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(1)
+ })
+
+ it('logs an error and completes the release when the principal share is missing', async () => {
+ const maxBodyBytes =
+ Buffer.byteLength(completionPayload('codex-completion-request.v1').body) + 512
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const error = vi.spyOn(logger, 'error')
+ const port = listen(createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 })))
+
+ // Liveness witness: a normal visual request takes and releases its share
+ // without the error.
+ await expectNextVisualAdmitted(port, maxBodyBytes)
+ expect(acquire).toHaveBeenCalledTimes(1)
+ expect(error).not.toHaveBeenCalled()
+
+ // Force the defect: the share is counted at admission but never stored,
+ // so the release finds no entry for the principal.
+ const principal = JSON.stringify(['default/research-host', 'research-host'])
+ const originalSet = Map.prototype.set
+ const set = vi
+ .spyOn(Map.prototype, 'set')
+ .mockImplementation(function (this: Map<unknown, unknown>, key: unknown, value: unknown) {
+ if (key === principal) return this
+ return originalSet.call(this, key, value)
+ })
+ await expectNextVisualAdmitted(port, maxBodyBytes)
+ expect(set).toHaveBeenCalledWith(principal, 1)
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(error).toHaveBeenCalledTimes(1)
+ expect(error).toHaveBeenCalledWith(
+ { event: 'codex_proxy_error', reason: 'principal_share_missing', sub: 'default/research-host' },
+ 'visual principal share missing at release'
+ )
+ await waitFor(
+ () => visualStreamGate.snapshot().running === 0 && visualStreamGate.snapshot().queued === 0,
+ 'the visual slot was not released after the missing share'
+ )
})
it('admits at most four visual entries per principal while another principal proceeds', async () => {
@@ -520,7 +571,7 @@ describe('visual stream-gate handoff', () => {
'host A did not take both running visual slots'
)
const third = postBody(port, platformToken(), invalidTicketBody(maxBodyBytes))
- postBody(port, platformToken(), invalidTicketBody(maxBodyBytes))
+ const fourth = postBody(port, platformToken(), invalidTicketBody(maxBodyBytes))
await waitFor(
() => visualStreamGate.snapshot().queued === 2,
'host A did not take two queued visual entries'
@@ -561,6 +612,9 @@ describe('visual stream-gate handoff', () => {
const thirdRes = await third
expect(thirdRes.status).toBe(403)
expect(await thirdRes.json()).toEqual({ error: 'ticket_invalid' })
+ const fourthRes = await fourth
+ expect(fourthRes.status).toBe(403)
+ expect(await fourthRes.json()).toEqual({ error: 'ticket_invalid' })
const otherRes = await otherHost
expect(otherRes.status).toBe(403)
expect(await otherRes.json()).toEqual({ error: 'ticket_invalid' })
@@ -898,10 +952,10 @@ describe('visual stream-gate handoff', () => {
await holder
})
- // M1 regression: after the handler takes a visual slot for the stream
- // (hand-off), a client disconnect must not free the slot or the principal
- // share early. The `res.close` backstop only runs while the slot is still
- // held in selectTransportBudget; once the handler owns it the slot is freed
+ // After the handler takes a visual slot for the stream (hand-off), a
+ // client disconnect must not free the slot or the principal share early.
+ // The close handler releases only while the slot is still held in
+ // selectTransportBudget; once the handler owns it the slot is freed
// by the handler's own `finally` when it finishes unwinding. Freeing it on
// close after hand-off would admit another large body over the gate width
// while the disconnected request's parsed body is still resident.
@@ -949,7 +1003,8 @@ describe('visual stream-gate handoff', () => {
// hang holds it). Its slot and the queue place must both persist.
abort.abort()
expect(await holderA).toBeInstanceOf(Error)
- // Give the close backstop time to (wrongly) fire before the assertion.
+ // Wait long enough for the close handler to run before the assertion; it
+ // must find the slot handed off and release nothing.
await new Promise(resolve => setTimeout(resolve, 300))
expect(visualStreamGate.snapshot()).toEqual({ running: 2, queued: 1 })
expect(acquire).toHaveBeenCalledTimes(3)
diff --git a/grok-llm-proxy/src/auth/platformJwtVerifier.ts b/grok-llm-proxy/src/auth/platformJwtVerifier.ts
index 6b1044714..106a28d12 100644
--- a/grok-llm-proxy/src/auth/platformJwtVerifier.ts
+++ b/grok-llm-proxy/src/auth/platformJwtVerifier.ts
@@ -30,7 +30,7 @@ export function verifyPlatformJwt(
if (!Array.isArray(claims.hostRefs) || !Array.isArray(claims.workflowControlScopes)) {
return null
}
- // A11.7 V3: `sub` becomes part of the per-principal visual admission key,
+ // `sub` becomes part of the per-principal visual admission key,
// so a missing, empty or non-string sub must fail verification instead of
// collapsing every such caller onto the literal principal "undefined".
const sub = claims.sub
diff --git a/grok-llm-proxy/src/config.ts b/grok-llm-proxy/src/config.ts
index b11d80e9b..e21885c06 100644
--- a/grok-llm-proxy/src/config.ts
+++ b/grok-llm-proxy/src/config.ts
@@ -93,7 +93,15 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): GrokLlmProxyCo
`GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at least ${LIMITS.maxVisualRequestBodyBytes}, the contract maxVisualRequestBodyBytes`
)
}
- // Y2 — an equal or lower budget would collapse visual admission into the
+ // The 1Gi memory limit was measured with one visual stream at the contract
+ // ceiling only (see VISUAL_STREAM_LIMITS). A larger value would admit bodies
+ // that measurement never covered.
+ if (maxVisualBodyBytes > LIMITS.maxVisualRequestBodyBytes) {
+ throw new Error(
+ `GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at most ${LIMITS.maxVisualRequestBodyBytes}, the contract maxVisualRequestBodyBytes`
+ )
+ }
+ // An equal or lower budget would collapse visual admission into the
// ordinary parser's cap, so the visual gate's separate accounting would
// never engage.
if (maxVisualBodyBytes <= maxBodyBytes) {
diff --git a/grok-llm-proxy/src/requestLimits.ts b/grok-llm-proxy/src/requestLimits.ts
index 6ec2ef0f5..fe6792103 100644
--- a/grok-llm-proxy/src/requestLimits.ts
+++ b/grok-llm-proxy/src/requestLimits.ts
@@ -21,13 +21,15 @@ export const DEFAULT_MAX_BODY_BYTES = CONTRACT_LIMITS.maxRequestBodyBytes + ENVE
* buffer, the decoded string, the parsed object, the contract copy and the
* canonical serialization). Without this bound the stream gate would let 24
* bodies in.
- * Bodies over the ordinary cap never take this budget: they are V2 visual
- * envelopes, bounded by `visualStreamGate` instead. With eight 8 MiB streams
- * and three queued 8 MiB bodies (#739 D5) the process peaked at 511 MiB of
- * RSS with `--max-old-space-size=384` (#739 measured 509.8) and at 480-511
- * MiB with an uncapped heap. That is past the former 256Mi limit, which is why the deployment sets
- * that cap. The full load the gates admit adds one visual stream; see
- * `VISUAL_STREAM_LIMITS` for that peak and the memory limit it sets.
+ * A body whose Content-Length exceeds the ordinary cap is read under
+ * `visualStreamGate`. If it parses to a size within the ordinary cap
+ * (demotion), it takes a reservation for that size before releasing the
+ * visual slot. With eight 8 MiB streams and three queued 8 MiB bodies (#739
+ * D5) the process peaked at 511 MiB of RSS with `--max-old-space-size=384`
+ * (#739 measured 509.8) and at 480-511 MiB with an uncapped heap, which is
+ * why the deployment sets that heap cap. The full load the gates admit adds
+ * one visual stream; `VISUAL_STREAM_LIMITS` records that peak and the 1Gi
+ * memory limit it sets.
*/
export const IN_FLIGHT_BODY_BUDGET_BODIES = 3
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index 973fb7a54..7d4c3168d 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -108,13 +108,20 @@ function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
}
-function reject(res: Response, status: number, code: string): void {
+/**
+ * `type` is the fixed error type of a refused body (body-parser's or the
+ * structure scan's), never a message or any part of the body.
+ */
+function reject(res: Response, status: number, code: string, type?: string): void {
if (res.headersSent) return
- logger.warn({ event: 'grok_proxy_denied', code }, 'request denied')
+ logger.warn(
+ type === undefined ? { event: 'grok_proxy_denied', code } : { event: 'grok_proxy_denied', code, type },
+ 'request denied'
+ )
res.status(status).json({ error: code })
}
-// A8: every JSON parser scans the raw body before JSON.parse. JSON.parse
+// Every JSON parser scans the raw body before JSON.parse. JSON.parse
// allocates one heap object per container, so a body within the byte limit
// can still exhaust the heap; the scan refuses a body denser, more nested or
// with more containers than any request the contract accepts. Its depth bound
@@ -124,18 +131,21 @@ const verifyBodyStructure = createBodyStructureVerify(BODY_STRUCTURE_LIMITS)
function boundedErrorHandler(err: unknown, _req: Request, res: Response, _next: () => void): void {
const typed = err as { type?: string; status?: number; body?: unknown }
+ // The refusals below share one response code per status, so the logged type
+ // is what tells a structural 413 from a byte-limit 413.
+ const type = typeof typed?.type === 'string' ? typed.type : undefined
if (typed?.type === 'entity.too.large' || typed?.status === 413) {
- reject(res, 413, 'payload_too_large')
+ reject(res, 413, 'payload_too_large', type)
return
}
// R9-1: the parsers run with `inflate: false`, so body-parser refuses an
// encoded body before reading it.
if (typed?.type === 'encoding.unsupported' || typed?.type === 'charset.unsupported') {
- reject(res, 415, 'unsupported_media_type')
+ reject(res, 415, 'unsupported_media_type', type)
return
}
if (err instanceof SyntaxError || typed?.type === 'body.structure.too.deep') {
- reject(res, 400, 'invalid_request')
+ reject(res, 400, 'invalid_request', type)
return
}
// body-parser attaches the raw body to an error thrown by `verify` or by
@@ -370,7 +380,7 @@ export function createProxyApps(
ordinaryJson(req, res, next)
return
}
- // B4 / A11.7 V3: one principal gets a fair share of the visual gate, so a
+ // One principal gets a fair share of the visual gate, so a
// single host cannot fill the entries every other host also needs. The
// share is taken before the gate wait, so queued entries count too.
const platform = req.grokPlatform
@@ -403,7 +413,19 @@ export function createProxyApps(
const releasePrincipalShare = (): void => {
if (!principalShareHeld) return
principalShareHeld = false
- const remaining = (visualPrincipalAdmissions.get(visualPrincipal) ?? 1) - 1
+ const held = visualPrincipalAdmissions.get(visualPrincipal)
+ if (held === undefined) {
+ // A held share always has an entry, so a missing one is a counting
+ // defect. This runs from `close` handlers, where a throw has no
+ // caller to reach, so it is logged and the release completes.
+ logger.error(
+ { event: 'grok_proxy_error', reason: 'principal_share_missing', sub: platform.sub },
+ 'visual principal share missing at release'
+ )
+ visualPrincipalAdmissions.delete(visualPrincipal)
+ return
+ }
+ const remaining = held - 1
if (remaining > 0) visualPrincipalAdmissions.set(visualPrincipal, remaining)
else visualPrincipalAdmissions.delete(visualPrincipal)
}
@@ -454,7 +476,7 @@ export function createProxyApps(
}, bodyReadDeadlineMs)
res.once('close', () => {
clearTimeout(readDeadline)
- // Backstop only while the admission is still held here. A kept
+ // The close handler releases only while the slot is still held here. A kept
// visual body transfers `req.grokStreamRelease` into the handler,
// which clears the field and releases in its outer `finally`. A
// demoted body releases through `releaseAdmission` before it joins
@@ -646,7 +668,7 @@ export function createProxyApps(
release = gated.grokStreamRelease
gated.grokStreamRelease = undefined
} else if (gated.grokStreamRelease) {
- // A8 D3: a demoted body was read through the visual gate, so it holds
+ // A demoted body was read through the visual gate, so it holds
// no body-budget reservation. It takes one for its compact size
// before it gives up the visual slot, so the 8-wide stream gate
// never holds more resident bodies than the budget admits. Every
diff --git a/grok-llm-proxy/test/bodyStructure.test.ts b/grok-llm-proxy/test/bodyStructure.test.ts
index ed59c1330..0966eb3f5 100644
--- a/grok-llm-proxy/test/bodyStructure.test.ts
+++ b/grok-llm-proxy/test/bodyStructure.test.ts
@@ -19,7 +19,7 @@ import {
} from '../src/requestLimits.js'
import { type ProxyRuntimeDeps, createProxyApps } from '../src/server.js'
-// A8: JSON.parse allocates one heap object per container, so a body that fits
+// JSON.parse allocates one heap object per container, so a body that fits
// every byte limit can still exhaust the proxy heap. Every parser scans the raw
// body against BODY_STRUCTURE_LIMITS before JSON.parse runs. These tests pin
// where each refusal happens (before the parse) and that a body at both the
@@ -287,7 +287,7 @@ function controlledStream() {
return { calls, impl }
}
-describe('grok proxy raw-body structure bounds (A8)', () => {
+describe('grok proxy raw-body structure bounds', () => {
const streams: Array<ReturnType<typeof controlledStream>> = []
const serversToClose: Array<{ close: () => Promise<void> }> = []
const listeners: Array<ReturnType<typeof createServer>> = []
@@ -616,12 +616,52 @@ describe('grok proxy raw-body structure bounds (A8)', () => {
const refused = await post(port, over)
expect(refused.status).toBe(413)
expect(warn).toHaveBeenCalledWith(
- { event: 'grok_proxy_denied', code: 'payload_too_large' },
+ {
+ event: 'grok_proxy_denied',
+ code: 'payload_too_large',
+ type: 'body.structure.too.many.containers',
+ },
'request denied'
)
expect(loggedText(warn, error, info)).not.toContain(MARKER)
})
+ it('logs the fixed refusal type of a structural 413, a byte-limit 413 and a too-deep 400', async () => {
+ const warn = vi.spyOn(logger, 'warn')
+ const denied = (): unknown[] =>
+ warn.mock.calls
+ .map(([entry]) => entry)
+ .filter(entry => (entry as { event?: unknown } | undefined)?.event === 'grok_proxy_denied')
+ const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
+
+ const base = measure(bodyWithFiller('grok-completion-request.v2', wideNumbers(1))).structuralBytes
+ const count = Math.ceil((BODY_STRUCTURE_LIMITS.maxStructuralBytes + 1 - base) / 9) + 1
+ const dense = await post(port, bodyWithFiller('grok-completion-request.v2', wideNumbers(count)))
+ expect(dense.status).toBe(413)
+
+ const deep = await post(port, bodyWithDepth(BODY_STRUCTURE_LIMITS.maxDepth + 1))
+ expect(deep.status).toBe(400)
+
+ // The admin parser answers a declared length over its limit from the
+ // header, as body-parser's `entity.too.large`.
+ const adminPort = listen(createProxyApps(config({ maxBodyBytes: 4096 })), 'adminApp')
+ const tooLarge = await fetch(`http://127.0.0.1:${adminPort}/internal/admin/v1/grok/models`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${adminPermit()}`, 'content-type': 'application/json' },
+ body: JSON.stringify({ filler: 'x'.repeat(4096) }),
+ })
+ expect(tooLarge.status).toBe(413)
+ expect(await tooLarge.json()).toEqual({ error: 'payload_too_large' })
+
+ // The two 413s carry the same response code; only the logged type tells
+ // them apart. The exact list is also the witness that each refusal ran.
+ expect(denied()).toEqual([
+ { event: 'grok_proxy_denied', code: 'payload_too_large', type: 'body.structure.too.dense' },
+ { event: 'grok_proxy_denied', code: 'invalid_request', type: 'body.structure.too.deep' },
+ { event: 'grok_proxy_denied', code: 'payload_too_large', type: 'entity.too.large' },
+ ])
+ })
+
it('logs only the type and status of an unmapped verify error', async () => {
const warn = vi.spyOn(logger, 'warn')
const error = vi.spyOn(logger, 'error')
@@ -641,7 +681,8 @@ describe('grok proxy raw-body structure bounds (A8)', () => {
const error = vi.spyOn(logger, 'error')
const fault = new Error('visual gate fault')
const acquire = vi.spyOn(visualStreamGate, 'acquire').mockRejectedValueOnce(fault)
- const largeParses = spyLargeParses()
+ const parse = vi.spyOn(JSON, 'parse')
+ const parsedTexts = (): unknown[] => parse.mock.calls.map(([text]) => text)
const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
const body = bodyWithContainers('grok-completion-request.v2', 8)
@@ -653,7 +694,14 @@ describe('grok proxy raw-body structure bounds (A8)', () => {
expect(acquire).toHaveBeenCalledTimes(1)
expect(error).toHaveBeenCalledWith({ event: 'grok_proxy_error', err: fault }, 'unhandled request error')
expect(visualStreamGate.snapshot().running).toBe(0)
- expect(largeParses()).not.toContain(padded.length)
+ expect(parsedTexts()).not.toContain(padded)
+
+ // Witness: the same body through a working gate reaches JSON.parse as this
+ // exact text, so the assertion above would see a parse had one happened.
+ const admitted = await post(port, padded)
+ expect(admitted.status).toBe(403)
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(parsedTexts()).toContain(padded)
})
describe('a demoted visual body (declared above the ordinary cap, compact below it)', () => {
diff --git a/grok-llm-proxy/test/contractFreeze.test.ts b/grok-llm-proxy/test/contractFreeze.test.ts
index f541ab539..3e2d1d647 100644
--- a/grok-llm-proxy/test/contractFreeze.test.ts
+++ b/grok-llm-proxy/test/contractFreeze.test.ts
@@ -63,7 +63,8 @@ const SHARED_LIMIT_KEYS = [
// SHARED_LIMIT_KEYS. Keeping it runtime-only takes one: add it here.
// maxVisualRequestBodyBytes stays here while the subscription endpoint is
// unmeasured for images: the fixture describes the measured upstream.
-// maxRequestContainers bounds the proxies' parse memory (A8), not the upstream.
+// maxRequestContainers bounds the proxies' parse memory (JSON.parse allocates
+// one heap object per container), not the upstream.
const RUNTIME_ONLY_LIMIT_KEYS = [
'maxIdLength',
'maxNestingDepth',
@@ -141,7 +142,9 @@ function emittedTransportCodes(): { codes: Set<string>; sites: number; construct
}
// Every direct HTTP refusal in src, `reject(res, <status>, <code>)`, with its code.
-const REJECT_SITE = /reject\(res,\s*[^,()]+,\s*([^,()]+?)\s*\)/g
+// The body-parser error handler also passes `type`, the parser's fixed error
+// type, which is logged and never sent, so it is the one fourth argument allowed.
+const REJECT_SITE = /reject\(res,\s*[^,()]+,\s*([^,()]+?)\s*(?:,\s*type\s*)?\)/g
// Refusal codes are wire strings; `Unauthorized` is the one spelled in capitals.
const REJECT_CODE_LITERAL = /^'([A-Za-z][A-Za-z0-9_]+)'$/
// The only computed code a refusal may carry, as its exact source text:
diff --git a/grok-llm-proxy/test/deployManifest.test.ts b/grok-llm-proxy/test/deployManifest.test.ts
index ac5ed9364..5a2c464a2 100644
--- a/grok-llm-proxy/test/deployManifest.test.ts
+++ b/grok-llm-proxy/test/deployManifest.test.ts
@@ -34,8 +34,9 @@ const SHUTDOWN_MARGIN_SECONDS = 20
const CAPPED_PEAK_RSS_MIB = 775.4
const MEMORY_HEADROOM = 1.25
/**
- * Owner decision on review M4 (#739): the request sits near the D5 peak, so a
- * busy node does not schedule the pod on memory it cannot give it under load.
+ * Owner decision on review M4 (#739): the request sits just below
+ * CAPPED_PEAK_RSS_MIB (D5 plus one visual stream), so a busy node does not
+ * schedule the pod on memory it cannot give it under load.
*/
const MEMORY_REQUEST_MIB = 768
@@ -88,7 +89,7 @@ describe('grok-llm-proxy base manifest', () => {
expect(grace).toBe(Math.ceil(worstCaseMs / 1000) + SHUTDOWN_MARGIN_SECONDS)
})
- it('T-DEP-2 caps the heap below the memory limit, keeps the limit above the D5 peak and requests 768Mi', () => {
+ it('T-DEP-2 caps the heap below the memory limit, keeps the limit 25% above the D5-plus-visual peak and requests 768Mi', () => {
const nodeOptions = activeLines(MANIFEST).findIndex((line) => /name:\s*NODE_OPTIONS\s*$/.test(line))
expect(nodeOptions, 'the container must set NODE_OPTIONS').toBeGreaterThanOrEqual(0)
const heap = /--max-old-space-size=(\d+)/.exec(activeLines(MANIFEST)[nodeOptions + 1] ?? '')
diff --git a/grok-llm-proxy/test/requestLimits.test.ts b/grok-llm-proxy/test/requestLimits.test.ts
index 1e5152137..f1ddc8aba 100644
--- a/grok-llm-proxy/test/requestLimits.test.ts
+++ b/grok-llm-proxy/test/requestLimits.test.ts
@@ -424,12 +424,20 @@ describe('StreamGate', () => {
})
it('builds the shared visual gate from VISUAL_STREAM_LIMITS', async () => {
- const held = await visualStreamGate.acquire()
- try {
- expect(visualStreamGate.snapshot()).toEqual({ running: 1, queued: 0 })
- } finally {
- held()
- }
+ const { maxConcurrentStreams, maxQueuedRequests } = VISUAL_STREAM_LIMITS
+ const held: Array<() => void> = []
+ for (let i = 0; i < maxConcurrentStreams; i += 1) held.push(await visualStreamGate.acquire())
+ expect(visualStreamGate.snapshot()).toEqual({ running: maxConcurrentStreams, queued: 0 })
+ // Width: every caller past maxConcurrentStreams queues instead of running.
+ const queued = Array.from({ length: maxQueuedRequests }, () => visualStreamGate.acquire())
+ expect(visualStreamGate.snapshot()).toEqual({
+ running: maxConcurrentStreams,
+ queued: maxQueuedRequests,
+ })
+ // Queue capacity: the caller after maxQueuedRequests is refused.
+ await expect(visualStreamGate.acquire()).rejects.toMatchObject({ kind: 'queue_full' })
+ for (const release of held) release()
+ for (const waiter of queued) (await waiter)()
expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
})
})
diff --git a/grok-llm-proxy/test/server.security.test.ts b/grok-llm-proxy/test/server.security.test.ts
index a1ea2ed94..f1bb49153 100644
--- a/grok-llm-proxy/test/server.security.test.ts
+++ b/grok-llm-proxy/test/server.security.test.ts
@@ -823,23 +823,41 @@ describe('grok-llm-proxy startup config', () => {
expect(() => loadConfig({ ...base, GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: '1024' })).toThrow(
/^GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at least 36700160,/
)
- // Witness: the ceiling itself and any larger value load.
+ // Witness: the ceiling itself loads.
expect(
loadConfig({
...base,
GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes),
}).maxVisualBodyBytes
).toBe(LIMITS.maxVisualRequestBodyBytes)
- expect(
+ })
+
+ // The 1Gi memory limit was measured with one visual stream at the contract
+ // ceiling. A larger visual limit would admit bodies that measurement never
+ // covered, so the proxy refuses to start with one.
+ it('refuses a visual body limit above the contract visual ceiling', () => {
+ expect(() =>
loadConfig({
...base,
GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes + 1),
+ })
+ ).toThrow(
+ `GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at most ${LIMITS.maxVisualRequestBodyBytes}, the contract maxVisualRequestBodyBytes`
+ )
+ expect(() =>
+ loadConfig({ ...base, GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(64 * 1024 * 1024) })
+ ).toThrow(/^GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be at most 36700160,/)
+ // Witness: the ceiling itself loads.
+ expect(
+ loadConfig({
+ ...base,
+ GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes),
}).maxVisualBodyBytes
- ).toBe(LIMITS.maxVisualRequestBodyBytes + 1)
+ ).toBe(LIMITS.maxVisualRequestBodyBytes)
})
- // Y2 — with an equal budget every visual envelope would also fit the
- // ordinary parser's cap, so the visual gate's separate admission and memory
+ // With an equal budget every visual envelope would also fit the ordinary
+ // parser's cap, so the visual gate's separate admission and memory
// accounting would never engage.
it('refuses a visual body limit less than or equal to the ordinary body limit', () => {
const equal = LIMITS.maxVisualRequestBodyBytes
@@ -861,14 +879,16 @@ describe('grok-llm-proxy startup config', () => {
).toThrow(
'GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES must be greater than GROK_LLM_PROXY_MAX_BODY_BYTES'
)
- // Liveness witness: one byte above the ordinary limit loads.
+ // Liveness witness: a visual limit one byte above the ordinary limit loads.
+ // The visual limit is pinned to the contract ceiling, so the ordinary limit
+ // moves instead.
expect(
loadConfig({
...base,
- GROK_LLM_PROXY_MAX_BODY_BYTES: String(equal),
- GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(equal + 1),
+ GROK_LLM_PROXY_MAX_BODY_BYTES: String(equal - 1),
+ GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(equal),
}).maxVisualBodyBytes
- ).toBe(equal + 1)
+ ).toBe(equal)
})
it('T-R2-6c-grok does not refuse a request at the contract cap with a real ticket as payload_too_large', async () => {
@@ -2229,7 +2249,7 @@ describe('grok-llm-proxy ticket-aware stream-gate wait (#739 D1-bis)', () => {
* copies of it are alive: reading, parsing, hashing and forwarding. That phase
* ends when the upstream fetch resolves, because the whole request body has
* been written by then. The reservation is released there instead of when the
- * SSE stream closes; the response's `close` event stays the backstop for every
+ * SSE stream closes; the response's `close` event still releases it on every
* path that never reaches the upstream.
*/
describe('grok-llm-proxy body budget release on upstream acceptance (#739 D2)', () => {
diff --git a/grok-llm-proxy/test/streamGate.handoff.test.ts b/grok-llm-proxy/test/streamGate.handoff.test.ts
index a771f3ea1..e8568310f 100644
--- a/grok-llm-proxy/test/streamGate.handoff.test.ts
+++ b/grok-llm-proxy/test/streamGate.handoff.test.ts
@@ -468,23 +468,74 @@ describe('grok visual stream-gate handoff', () => {
}
it('refuses a platform token whose sub is not a non-empty string with 401', async () => {
- const port = listen(createProxyApps(config()))
+ const maxBodyBytes =
+ Buffer.byteLength(completionPayload('grok-completion-request.v1').body) + 512
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const port = listen(createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 })))
const claims = {
hostRefs: ['research-host'],
workflowControlScopes: ['llm:grok:execute'],
scope: 'workflow:approval:request',
}
+ // Each body is large enough to take the visual gate once its token passes.
for (const bearerToken of [
sign(claims, 'workflow-approvals'),
sign({ ...claims, sub: '' }, 'workflow-approvals'),
sign({ ...claims, sub: 403 }, 'workflow-approvals'),
]) {
- const res = await postBody(port, bearerToken, JSON.stringify({ probe: 1 }))
+ const res = await postBody(port, bearerToken, invalidTicketBody(maxBodyBytes))
expect(res.status).toBe(401)
expect(await res.json()).toEqual({ error: 'Unauthorized' })
}
- // Liveness witness: none of those requests reached body admission.
- expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ expect(acquire).not.toHaveBeenCalled()
+
+ // Positive control: the same body with a valid sub reaches the visual
+ // gate and then the ticket check.
+ const admitted = await postBody(
+ port,
+ sign({ ...claims, sub: 'default/research-host' }, 'workflow-approvals'),
+ invalidTicketBody(maxBodyBytes)
+ )
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(1)
+ })
+
+ it('logs an error and completes the release when the principal share is missing', async () => {
+ const maxBodyBytes =
+ Buffer.byteLength(completionPayload('grok-completion-request.v1').body) + 512
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const error = vi.spyOn(logger, 'error')
+ const port = listen(createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 })))
+
+ // Liveness witness: a normal visual request takes and releases its share
+ // without the error.
+ await expectNextVisualAdmitted(port, maxBodyBytes)
+ expect(acquire).toHaveBeenCalledTimes(1)
+ expect(error).not.toHaveBeenCalled()
+
+ // Force the defect: the share is counted at admission but never stored,
+ // so the release finds no entry for the principal.
+ const principal = JSON.stringify(['default/research-host', 'research-host'])
+ const originalSet = Map.prototype.set
+ const set = vi
+ .spyOn(Map.prototype, 'set')
+ .mockImplementation(function (this: Map<unknown, unknown>, key: unknown, value: unknown) {
+ if (key === principal) return this
+ return originalSet.call(this, key, value)
+ })
+ await expectNextVisualAdmitted(port, maxBodyBytes)
+ expect(set).toHaveBeenCalledWith(principal, 1)
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(error).toHaveBeenCalledTimes(1)
+ expect(error).toHaveBeenCalledWith(
+ { event: 'grok_proxy_error', reason: 'principal_share_missing', sub: 'default/research-host' },
+ 'visual principal share missing at release'
+ )
+ await waitFor(
+ () => visualStreamGate.snapshot().running === 0 && visualStreamGate.snapshot().queued === 0,
+ 'the visual slot was not released after the missing share'
+ )
})
it('admits at most two visual entries per principal while another principal proceeds', async () => {
@@ -871,10 +922,10 @@ describe('grok visual stream-gate handoff', () => {
await holder
})
- // M1 regression: after the handler takes the visual slot for the stream
- // (hand-off), a client disconnect must not free the slot or the principal
- // share early. The `res.close` backstop only runs while the slot is still
- // held in selectTransportBudget; once the handler owns it the slot is freed
+ // After the handler takes the visual slot for the stream (hand-off), a
+ // client disconnect must not free the slot or the principal share early.
+ // The close handler releases only while the slot is still held in
+ // selectTransportBudget; once the handler owns it the slot is freed
// by the handler's own `finally` when it finishes unwinding. Freeing it on
// close after hand-off would admit another large body over the gate width
// while the disconnected request's parsed body is still resident.
@@ -920,7 +971,8 @@ describe('grok visual stream-gate handoff', () => {
// (the hang holds it). The slot and the queue place must both persist.
abort.abort()
expect(await holder).toBeInstanceOf(Error)
- // Give the close backstop time to (wrongly) fire before the assertion.
+ // Wait long enough for the close handler to run before the assertion; it
+ // must find the slot handed off and release nothing.
await new Promise(resolve => setTimeout(resolve, 300))
expect(visualStreamGate.snapshot()).toEqual({ running: 1, queued: 1 })
expect(acquire).toHaveBeenCalledTimes(2)