Skip to content

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

TypeScript

feat(llm-proxy): log request-limit reasons and check the deadline before redeem

Alfredo Lopez3e9b9ce91ddf
diff --git a/codex-llm-proxy/src/codexTransport.ts b/codex-llm-proxy/src/codexTransport.ts
index 687f4c00c..366c55313 100644
--- a/codex-llm-proxy/src/codexTransport.ts
+++ b/codex-llm-proxy/src/codexTransport.ts
@@ -124,6 +124,12 @@ export async function streamCodexCompletion(
if (request.model !== input.ticket.model) {
throw new CodexTransportError('model_not_allowed', 'request model does not match the ticket')
}
+ // The redeem consumes the single-use ticket, so a deadline that cannot be
+ // served is refused first, while there is no receipt to finalize.
+ const boundedDeadlineMs = assertBoundedDeadline(
+ input.deadlineMs ?? request.deadlineMs,
+ input.maxDeadlineMs
+ )
// A client that disconnected before dispatch must not consume the ticket:
// nothing was redeemed, so there is no attempt receipt to finalize.
if (input.signal?.aborted) {
@@ -140,10 +146,7 @@ export async function streamCodexCompletion(
await finalizeQuietly(input, redeemed, 'error')
throw new CodexTransportError('model_not_allowed', 'served model does not match the request')
}
- const deadlineMs = Math.min(
- assertBoundedDeadline(input.deadlineMs ?? request.deadlineMs, input.maxDeadlineMs),
- redeemed.transport.maxStreamDurationMs
- )
+ const deadlineMs = Math.min(boundedDeadlineMs, redeemed.transport.maxStreamDurationMs)
const idleTimeoutMs = assertBoundedIdleTimeout(input.upstreamIdleTimeoutMs)
input.onRedeemed?.()
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index d0891352c..33f7464ba 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -239,7 +239,11 @@ export function createProxyApps(config: CodexLlmProxyConfig, deps: ProxyRuntimeD
stopHeartbeat?.()
const mapped = mapError(err)
metrics.observeAttempt('error', 'completion_stream')
- metrics.observeAttemptFailure(failureLabel(mapped.code))
+ // A request limit answers provider_unavailable on the wire; its own
+ // label keeps it apart from real upstream outages in the metric.
+ metrics.observeAttemptFailure(
+ err instanceof RequestLimitError ? 'request_limit' : failureLabel(mapped.code)
+ )
if (err instanceof UpstreamTimeoutError) metrics.observeUpstreamTimeout(err.kind)
const deliveredAs = res.headersSent ? 'sse_error' : 'http_status'
logger.warn(
@@ -253,6 +257,8 @@ export function createProxyApps(config: CodexLlmProxyConfig, deps: ProxyRuntimeD
...(err instanceof CodexTransportError && err.code !== 'invalid_request'
? { reason: err.message, ...(err.details ? { details: err.details } : {}) }
: {}),
+ // RequestLimitError messages are fixed strings with no request data.
+ ...(err instanceof RequestLimitError ? { reason: err.message } : {}),
deliveredAs,
...(deliveredAs === 'http_status' ? { httpStatus: mapped.status } : {}),
toolCalls,
diff --git a/codex-llm-proxy/test/codexTransport.conformance.test.ts b/codex-llm-proxy/test/codexTransport.conformance.test.ts
index 044317e5b..48907d81a 100644
--- a/codex-llm-proxy/test/codexTransport.conformance.test.ts
+++ b/codex-llm-proxy/test/codexTransport.conformance.test.ts
@@ -1467,3 +1467,25 @@ describe('streamCodexCompletion upstream timeouts', () => {
expect(upstream.cancel).toHaveBeenCalledTimes(1)
}, 2_000)
})
+
+describe('streamCodexCompletion deadline validation', () => {
+ // The redeem consumes the single-use ticket, so a deadline that cannot be
+ // served must be refused before it, while there is no receipt to finalize.
+ it('rejects an invalid deadline before redeeming the ticket', async () => {
+ const redeem = vi.fn(async () => redeemSuccess())
+ const fetchFn = vi.fn()
+ const input = attemptInput({
+ deadlineMs: 0,
+ redeem,
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ // Witness: the rejection names the deadline check, so the path ran.
+ await expect(streamCodexCompletion(input)).rejects.toMatchObject({
+ name: 'RequestLimitError',
+ message: 'deadline is invalid',
+ })
+ expect(redeem).not.toHaveBeenCalled()
+ expect(input.finalize).not.toHaveBeenCalled()
+ expect(fetchFn).not.toHaveBeenCalled()
+ })
+})
diff --git a/codex-llm-proxy/test/server.security.test.ts b/codex-llm-proxy/test/server.security.test.ts
index 3934ba6e6..f299a0a26 100644
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@ -17,6 +17,7 @@ import {
} from '../src/controlApiClient.js'
import { logger } from '../src/logger.js'
import { CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
+import { RequestLimitError, streamGate } from '../src/requestLimits.js'
import { createProxyApps } from '../src/server.js'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
@@ -955,6 +956,35 @@ describe('codex-llm-proxy attempt telemetry', () => {
}
)
+ it('(l) logs the request-limit reason and labels its failure metric request_limit', async () => {
+ const acquire = vi
+ .spyOn(streamGate, 'acquire')
+ .mockRejectedValueOnce(new RequestLimitError('stream queue is full'))
+ try {
+ const { res, receipts, lines, metricsText } = await run('att-queue-full', 0, 0)
+ // Witness: the refusal came from the stream gate this test replaced.
+ expect(acquire).toHaveBeenCalledTimes(1)
+ expect(res.status).toBe(503)
+ expect(res.body).toEqual({ error: 'provider_unavailable' })
+ // The gate refused before the redeem, so there is no receipt to finalize.
+ expect(receipts).toEqual([])
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-queue-full',
+ outcome: 'failed',
+ code: 'provider_unavailable',
+ reason: 'stream queue is full',
+ deliveredAs: 'http_status',
+ httpStatus: 503,
+ })
+ expectNoForbiddenKeys(lines[0]!)
+ expect(failureCount(metricsText, 'request_limit')).toBe(1)
+ expect(failureCount(metricsText, 'provider_unavailable')).toBe(0)
+ } finally {
+ acquire.mockRestore()
+ }
+ })
+
it('(k) keeps a silent upstream attempt open with SSE comments and counts them', async () => {
const { res, lines } = await run('att-heartbeat', 0, 0, undefined, undefined, {
fetchFn: silentThenCompletingUpstream(100),
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index f396f1aed..2c0bb99a5 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -199,7 +199,8 @@ behavior changes:
token is empty.
- It respects SSE write backpressure.
- It drops queued stream-gate waiters on abort and checks the abort signal
- before redeeming a ticket.
+ before redeeming a ticket. It also rejects an invalid or out-of-bounds
+ deadline before the redeem, so the single-use ticket is not consumed.
- It rejects a stream-gate waiter still queued after `maxQueueWaitMs` with
`provider_unavailable` (reason `stream queue wait exceeded`). Queue wait,
the 15 s control-api redeem timeout and the first keepalive together stay
@@ -233,6 +234,11 @@ behavior changes:
control-api keeps `success | canceled | error | unknown`. Only the
`codex_proxy_attempt_finished` log line adds `failed`.
- It counts failed attempts in `codex_proxy_attempt_failures_total{code}`.
+ A request the proxy refuses on its own request limits (stream queue full,
+ queue wait exceeded, invalid deadline) reaches the Host as
+ `provider_unavailable`. The metric labels it `request_limit` to keep it
+ apart from upstream outages, and the log line carries the limit's fixed
+ `reason`.
- **Live-target attestation.** Codex authorize attests the live Host or recipe
target. The allowed providers come only from the spec's model, allowed
models and fallbacks (Hosts) or agent providers (recipes). A target that
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 0555dc920..30d8d34bd 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -165,7 +165,9 @@ Proxy robustness (both proxies):
- The SSE writer respects `res.write` backpressure: it waits for `drain` and
stops waiting if the client closes.
- Queued stream-gate waiters stop when the request aborts, and the proxy
- checks the abort signal before redeeming a ticket.
+ checks the abort signal before redeeming a ticket. It also rejects an
+ invalid or out-of-bounds deadline before the redeem, so the single-use
+ ticket is not consumed.
- A stream-gate waiter still queued after `maxQueueWaitMs` (60 s) is rejected
with `provider_unavailable` (reason `stream queue wait exceeded`). Queue
wait, the 15 s control-api redeem timeout and the first keepalive together
@@ -316,6 +318,10 @@ above.
Anything outside the table is recorded as `other`, because a control-api error
body is not bounded by the proxy. The raw code stays in the
`grok_proxy_attempt_finished` log line.
+A request the proxy refuses on its own request limits (stream queue full,
+queue wait exceeded, invalid deadline) reaches the Host as
+`provider_unavailable`. The metric labels it `request_limit` to keep it apart
+from upstream outages, and the log line carries the limit's fixed `reason`.
## Feature flags
diff --git a/grok-llm-proxy/src/grokTransport.ts b/grok-llm-proxy/src/grokTransport.ts
index 3a504c65a..8c30d6336 100644
--- a/grok-llm-proxy/src/grokTransport.ts
+++ b/grok-llm-proxy/src/grokTransport.ts
@@ -151,6 +151,12 @@ export async function streamGrokCompletion(
if (request.model !== input.ticket.model) {
throw new GrokTransportError('model_not_allowed', 'request model does not match the ticket')
}
+ // The redeem consumes the single-use ticket, so a deadline that cannot be
+ // served is refused first, while there is no receipt to finalize.
+ const boundedDeadlineMs = assertBoundedDeadline(
+ input.deadlineMs ?? request.deadlineMs,
+ input.maxDeadlineMs
+ )
// A client that disconnected before dispatch must not consume the ticket:
// nothing was redeemed, so there is no attempt receipt to finalize.
if (input.signal?.aborted) {
@@ -167,10 +173,7 @@ export async function streamGrokCompletion(
await finalizeQuietly(input, redeemed, 'error')
throw new GrokTransportError('model_not_allowed', 'served model does not match the request')
}
- const deadlineMs = Math.min(
- assertBoundedDeadline(input.deadlineMs ?? request.deadlineMs, input.maxDeadlineMs),
- redeemed.transport.maxStreamDurationMs
- )
+ const deadlineMs = Math.min(boundedDeadlineMs, redeemed.transport.maxStreamDurationMs)
const idleTimeoutMs = assertBoundedIdleTimeout(input.upstreamIdleTimeoutMs)
input.onRedeemed?.()
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index bccdc8442..b03549e3c 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -242,7 +242,11 @@ export function createProxyApps(
stopHeartbeat?.()
const mapped = mapError(err)
metrics.observeAttempt('error', 'completion_stream')
- metrics.observeAttemptFailure(failureLabel(mapped.code))
+ // A request limit answers provider_unavailable on the wire; its own
+ // label keeps it apart from real upstream outages in the metric.
+ metrics.observeAttemptFailure(
+ err instanceof RequestLimitError ? 'request_limit' : failureLabel(mapped.code)
+ )
if (err instanceof UpstreamTimeoutError) metrics.observeUpstreamTimeout(err.kind)
const deliveredAs = res.headersSent ? 'sse_error' : 'http_status'
logger.warn(
@@ -256,6 +260,8 @@ export function createProxyApps(
...(err instanceof GrokTransportError && err.code !== 'invalid_request'
? { reason: err.message, ...(err.details ? { details: err.details } : {}) }
: {}),
+ // RequestLimitError messages are fixed strings with no request data.
+ ...(err instanceof RequestLimitError ? { reason: err.message } : {}),
deliveredAs,
...(deliveredAs === 'http_status' ? { httpStatus: mapped.status } : {}),
toolCalls,
diff --git a/grok-llm-proxy/test/grokTransport.conformance.test.ts b/grok-llm-proxy/test/grokTransport.conformance.test.ts
index b66fd5da6..d3480f515 100644
--- a/grok-llm-proxy/test/grokTransport.conformance.test.ts
+++ b/grok-llm-proxy/test/grokTransport.conformance.test.ts
@@ -1599,3 +1599,25 @@ describe('streamGrokCompletion upstream timeouts', () => {
expect(upstream.cancel).toHaveBeenCalledTimes(1)
}, 2_000)
})
+
+describe('streamGrokCompletion deadline validation', () => {
+ // The redeem consumes the single-use ticket, so a deadline that cannot be
+ // served must be refused before it, while there is no receipt to finalize.
+ it('rejects an invalid deadline before redeeming the ticket', async () => {
+ const redeem = vi.fn(async () => redeemSuccess())
+ const fetchFn = vi.fn()
+ const input = attemptInput({
+ deadlineMs: 0,
+ redeem,
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ // Witness: the rejection names the deadline check, so the path ran.
+ await expect(streamGrokCompletion(input)).rejects.toMatchObject({
+ name: 'RequestLimitError',
+ message: 'deadline is invalid',
+ })
+ expect(redeem).not.toHaveBeenCalled()
+ expect(input.finalize).not.toHaveBeenCalled()
+ expect(fetchFn).not.toHaveBeenCalled()
+ })
+})
diff --git a/grok-llm-proxy/test/server.security.test.ts b/grok-llm-proxy/test/server.security.test.ts
index 835186187..9d305c47b 100644
--- a/grok-llm-proxy/test/server.security.test.ts
+++ b/grok-llm-proxy/test/server.security.test.ts
@@ -18,6 +18,7 @@ import {
import { MAX_TOOL_CALL_ARGUMENT_CHARS } from '../src/grokTransport.js'
import { REDACT_PATHS, logger } from '../src/logger.js'
import { GROK_CATALOG_ORIGIN, GROK_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
+import { RequestLimitError, streamGate } from '../src/requestLimits.js'
import { createProxyApps } from '../src/server.js'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
@@ -1099,6 +1100,35 @@ describe('grok-llm-proxy attempt telemetry', () => {
}
)
+ it('(rl1) logs the request-limit reason and labels its failure metric request_limit', async () => {
+ const acquire = vi
+ .spyOn(streamGate, 'acquire')
+ .mockRejectedValueOnce(new RequestLimitError('stream queue is full'))
+ try {
+ const { res, receipts, lines, metricsText } = await run({ providerAttemptId: 'att-queue-full' })
+ // Witness: the refusal came from the stream gate this test replaced.
+ expect(acquire).toHaveBeenCalledTimes(1)
+ expect(res.status).toBe(503)
+ expect(res.body).toEqual({ error: 'provider_unavailable' })
+ // The gate refused before the redeem, so there is no receipt to finalize.
+ expect(receipts).toEqual([])
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-queue-full',
+ outcome: 'failed',
+ code: 'provider_unavailable',
+ reason: 'stream queue is full',
+ deliveredAs: 'http_status',
+ httpStatus: 503,
+ })
+ expectNoForbiddenKeys(lines[0]!)
+ expect(failureCount(metricsText, 'request_limit')).toBe(1)
+ expect(failureCount(metricsText, 'provider_unavailable')).toBe(0)
+ } finally {
+ acquire.mockRestore()
+ }
+ })
+
it('(hb1) keeps a silent upstream attempt open with SSE comments and counts them', async () => {
const { res, lines } = await run({
providerAttemptId: 'att-heartbeat',