Skip to content

Commit a088e4b

Browse files
authored
Merge pull request #866 from luvs01/feat/657-reset-eligible-exhaustion
feat(codex): classify reset-eligible quota rejection
2 parents e337390 + d142f06 commit a088e4b

4 files changed

Lines changed: 537 additions & 6 deletions

File tree

‎src/codex/quota-rejection.ts‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
import { readBoundedResponseBody } from "../lib/bounded-body";
2+
3+
const RESET_ELIGIBLE_CODE_VALUES = [
4+
"usage_limit_exceeded",
5+
"insufficient_quota",
6+
] as const;
7+
8+
export type CodexResetEligibleExhaustionCode =
9+
(typeof RESET_ELIGIBLE_CODE_VALUES)[number];
10+
11+
export type CodexPreStreamRejectionKind =
12+
| "reset-eligible-exhaustion"
13+
| "generic-rate-limit"
14+
| "unverified-billing-or-quota"
15+
| "transient-server-error"
16+
| "authentication-error"
17+
| "permission-error"
18+
| "other";
19+
20+
export interface CodexPreStreamRejection {
21+
kind: CodexPreStreamRejectionKind;
22+
status: number;
23+
alternateRetryEligible: boolean;
24+
resetCreditEligible: boolean;
25+
semanticCode?: CodexResetEligibleExhaustionCode;
26+
}
27+
28+
const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);
29+
30+
const TRANSIENT_SERVER_STATUSES = new Set([500, 502, 503, 504, 520, 521, 522]);
31+
const JSON_NUMBER_PATTERN = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
32+
33+
function rejection(
34+
status: number,
35+
kind: CodexPreStreamRejectionKind,
36+
options: {
37+
alternateRetryEligible?: boolean;
38+
semanticCode?: CodexResetEligibleExhaustionCode;
39+
} = {},
40+
): CodexPreStreamRejection {
41+
return {
42+
kind,
43+
status,
44+
alternateRetryEligible: options.alternateRetryEligible === true,
45+
resetCreditEligible: options.semanticCode !== undefined,
46+
...(options.semanticCode ? { semanticCode: options.semanticCode } : {}),
47+
};
48+
}
49+
50+
function hasOwnField(container: Record<string, unknown>, field: string): boolean {
51+
return Object.prototype.hasOwnProperty.call(container, field);
52+
}
53+
54+
type JsonScanResult = {
55+
next: number;
56+
duplicate: boolean;
57+
};
58+
59+
function skipJsonWhitespace(text: string, index: number): number {
60+
while (index < text.length && /[\t\n\r ]/.test(text[index] ?? "")) index += 1;
61+
return index;
62+
}
63+
64+
function scanJsonStringEnd(text: string, index: number): number {
65+
if (text[index] !== '"') throw new SyntaxError("expected JSON string");
66+
for (let cursor = index + 1; cursor < text.length; cursor += 1) {
67+
const char = text[cursor];
68+
if (char === '"') return cursor + 1;
69+
if (char === "\\") cursor += 1;
70+
}
71+
throw new SyntaxError("unterminated JSON string");
72+
}
73+
74+
function scanJsonValue(text: string, index: number): JsonScanResult {
75+
const start = skipJsonWhitespace(text, index);
76+
if (text[start] === "{") return scanJsonObject(text, start);
77+
if (text[start] === "[") return scanJsonArray(text, start);
78+
if (text[start] === '"') return { next: scanJsonStringEnd(text, start), duplicate: false };
79+
80+
for (const literal of ["true", "false", "null"]) {
81+
if (text.startsWith(literal, start)) {
82+
return { next: start + literal.length, duplicate: false };
83+
}
84+
}
85+
JSON_NUMBER_PATTERN.lastIndex = start;
86+
const number = JSON_NUMBER_PATTERN.exec(text);
87+
if (!number) throw new SyntaxError("expected JSON value");
88+
return { next: start + number[0].length, duplicate: false };
89+
}
90+
91+
function scanJsonObject(text: string, index: number): JsonScanResult {
92+
const keys = new Set<string>();
93+
let duplicate = false;
94+
let cursor = skipJsonWhitespace(text, index + 1);
95+
if (text[cursor] === "}") return { next: cursor + 1, duplicate: false };
96+
97+
while (cursor < text.length) {
98+
const keyEnd = scanJsonStringEnd(text, cursor);
99+
const key = JSON.parse(text.slice(cursor, keyEnd)) as unknown;
100+
if (typeof key !== "string") throw new SyntaxError("invalid JSON object key");
101+
if (keys.has(key)) duplicate = true;
102+
keys.add(key);
103+
104+
cursor = skipJsonWhitespace(text, keyEnd);
105+
if (text[cursor] !== ":") throw new SyntaxError("expected JSON object colon");
106+
const value = scanJsonValue(text, cursor + 1);
107+
duplicate ||= value.duplicate;
108+
cursor = skipJsonWhitespace(text, value.next);
109+
if (text[cursor] === "}") return { next: cursor + 1, duplicate };
110+
if (text[cursor] !== ",") throw new SyntaxError("expected JSON object separator");
111+
cursor = skipJsonWhitespace(text, cursor + 1);
112+
}
113+
throw new SyntaxError("unterminated JSON object");
114+
}
115+
116+
function scanJsonArray(text: string, index: number): JsonScanResult {
117+
let duplicate = false;
118+
let cursor = skipJsonWhitespace(text, index + 1);
119+
if (text[cursor] === "]") return { next: cursor + 1, duplicate: false };
120+
121+
while (cursor < text.length) {
122+
const value = scanJsonValue(text, cursor);
123+
duplicate ||= value.duplicate;
124+
cursor = skipJsonWhitespace(text, value.next);
125+
if (text[cursor] === "]") return { next: cursor + 1, duplicate };
126+
if (text[cursor] !== ",") throw new SyntaxError("expected JSON array separator");
127+
cursor = skipJsonWhitespace(text, cursor + 1);
128+
}
129+
throw new SyntaxError("unterminated JSON array");
130+
}
131+
132+
function isUnsafeJsonDocument(text: string): boolean {
133+
try {
134+
const result = scanJsonValue(text, 0);
135+
return result.duplicate || skipJsonWhitespace(text, result.next) !== text.length;
136+
} catch {
137+
// Scanner disagreement is untrusted input, just like JSON.parse failure.
138+
return true;
139+
}
140+
}
141+
142+
function exactResetEligibleCode(
143+
container: Record<string, unknown>,
144+
): CodexResetEligibleExhaustionCode | undefined {
145+
const hasCode = hasOwnField(container, "code");
146+
const hasType = hasOwnField(container, "type");
147+
if (!hasCode && !hasType) return undefined;
148+
149+
const code = hasCode ? container.code : undefined;
150+
const type = hasType ? container.type : undefined;
151+
if ((hasCode && typeof code !== "string") || (hasType && typeof type !== "string")) {
152+
return undefined;
153+
}
154+
if (hasCode && hasType && code !== type) return undefined;
155+
156+
const value = hasCode ? code : type;
157+
if (typeof value !== "string") return undefined;
158+
return RESET_ELIGIBLE_CODES.has(value as CodexResetEligibleExhaustionCode)
159+
? value as CodexResetEligibleExhaustionCode
160+
: undefined;
161+
}
162+
163+
function structuredResetEligibleCode(payload: unknown): CodexResetEligibleExhaustionCode | undefined {
164+
if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
165+
const root = payload as Record<string, unknown>;
166+
const hasRootDiscriminator = hasOwnField(root, "code") || hasOwnField(root, "type");
167+
168+
if (!hasOwnField(root, "error")) return exactResetEligibleCode(root);
169+
if (hasRootDiscriminator) return undefined;
170+
171+
const nested = root.error;
172+
if (!nested || typeof nested !== "object" || Array.isArray(nested)) return undefined;
173+
return exactResetEligibleCode(nested as Record<string, unknown>);
174+
}
175+
176+
async function resetEligibleCodeFromResponse(
177+
response: Response,
178+
signal?: AbortSignal,
179+
): Promise<CodexResetEligibleExhaustionCode | undefined> {
180+
try {
181+
const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
182+
if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
183+
const payload = JSON.parse(body.text) as unknown;
184+
// JSON.parse silently keeps the last duplicate key, making contradictory
185+
// payloads order-dependent. Reject any duplicate at any object depth.
186+
if (isUnsafeJsonDocument(body.text)) return undefined;
187+
return structuredResetEligibleCode(payload);
188+
} catch {
189+
// Classification must fail closed. A malformed, oversized, consumed, or
190+
// cancelled body cannot authorize an irreversible reset-credit operation.
191+
return undefined;
192+
}
193+
}
194+
195+
/**
196+
* Classify an upstream Codex rejection before any response event is exposed.
197+
*
198+
* Only an exact structured exhaustion code on HTTP 429/402 is reset-eligible.
199+
* Status alone and message text are intentionally insufficient. The broad
200+
* alternate-account retry remains eligible for 429/402 to preserve #584.
201+
*/
202+
export async function classifyCodexPreStreamRejection(
203+
response: Response,
204+
options: { signal?: AbortSignal } = {},
205+
): Promise<CodexPreStreamRejection> {
206+
const status = response.status;
207+
if (status === 401) return rejection(status, "authentication-error");
208+
if (status === 403) return rejection(status, "permission-error");
209+
if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error");
210+
if (status !== 429 && status !== 402) return rejection(status, "other");
211+
212+
const semanticCode = await resetEligibleCodeFromResponse(response, options.signal);
213+
if (semanticCode) {
214+
return rejection(status, "reset-eligible-exhaustion", {
215+
alternateRetryEligible: true,
216+
semanticCode,
217+
});
218+
}
219+
return rejection(
220+
status,
221+
status === 429 ? "generic-rate-limit" : "unverified-billing-or-quota",
222+
{ alternateRetryEligible: true },
223+
);
224+
}

‎src/lib/bounded-body.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ export const BOUNDED_BODY_TIMEOUT_MS = 5_000;
77
export interface BoundedBodyOptions {
88
/** Abort the read with this signal. Its reason is rethrown by identity. */
99
signal?: AbortSignal;
10+
/**
11+
* Reject the returned promise with TypeError on malformed or truncated UTF-8
12+
* instead of replacing invalid bytes, including during timeout-path flushes.
13+
* Reader cancellation and lock release still run. Defaults to false.
14+
*/
15+
fatalUtf8?: boolean;
1016
/**
1117
* Byte ceiling for retained body data. Defaults to BOUNDED_BODY_MAX_BYTES (64 KiB),
1218
* which suits error bodies; callers materializing whole success payloads (e.g. a
@@ -75,8 +81,8 @@ function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, r
7581
}
7682
}
7783

78-
function decodeUtf8(chunks: readonly Uint8Array[]): string {
79-
const decoder = new TextDecoder();
84+
function decodeUtf8(chunks: readonly Uint8Array[], fatal: boolean): string {
85+
const decoder = new TextDecoder("utf-8", { fatal });
8086
let text = "";
8187
for (const chunk of chunks) text += decoder.decode(chunk, { stream: true });
8288
// Flush an incomplete trailing UTF-8 sequence deterministically.
@@ -158,7 +164,7 @@ export async function readBoundedResponseBody(
158164
"TimeoutError",
159165
);
160166
return {
161-
text: decodeUtf8([retained.subarray(0, retainedBytes)]),
167+
text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
162168
truncated: true,
163169
timedOut: true,
164170
totalTimedOut: outcome === TOTAL_TIMEOUT,
@@ -171,7 +177,7 @@ export async function readBoundedResponseBody(
171177
const { value, done } = outcome as ReadableStreamReadResult<Uint8Array>;
172178
if (done) {
173179
return {
174-
text: decodeUtf8([retained.subarray(0, retainedBytes)]),
180+
text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
175181
truncated: false,
176182
timedOut: false,
177183
totalTimedOut: false,

‎src/server/responses/core.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -256,8 +256,8 @@ async function shouldRetryCodexPoolAccountModel400(
256256
}
257257

258258
/** Pre-stream quota/billing rejections that warrant one alternate-account attempt (#584). */
259-
function shouldRetryCodexPoolAccountQuota(response: Response): boolean {
260-
return response.status === 429 || response.status === 402;
259+
export function shouldRetryCodexPoolAccountQuota(response: Response): boolean {
260+
return response.status === 402 || response.status === 429;
261261
}
262262

263263
interface CodexPoolAccountRetryArgs {

0 commit comments

Comments
 (0)