Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Bound Linear requests during reporter reconciliation (#4985)

Andrew Mikofalvy11af2ea08903
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjs
index 053468569..33a0afeba 100644
--- a/.github/scripts/write-back.mjs
+++ b/.github/scripts/write-back.mjs
@@ -47,6 +47,7 @@ export const CANDIDATE_QUERY = `
state { type }
labels { nodes { name } }
attachments { nodes { url } }
+ children(first: 1) { nodes { id } pageInfo { hasNextPage } }
}
}
}
@@ -288,6 +289,27 @@ export class NeedsHumanError extends Error {
}
}
+export class LinearRateLimitError extends Error {
+ constructor(headers) {
+ const read = (name) => headers?.get?.(name);
+ const windows = [
+ ['request reset epoch ms', read('x-ratelimit-requests-reset')],
+ [
+ `endpoint ${read('x-ratelimit-endpoint-name') ?? 'unspecified'} reset epoch ms`,
+ read('x-ratelimit-endpoint-requests-reset'),
+ ],
+ ['complexity reset epoch ms', read('x-ratelimit-complexity-reset')],
+ ['retry-after', read('retry-after')],
+ ]
+ .filter(([, value]) => value)
+ .map(([label, value]) => `${label}: ${value}`);
+ super(
+ `Linear rate limit reached${windows.length ? ` (${windows.join('; ')})` : ''}; stopping reconciliation and leaving remaining candidates for a later run.`,
+ );
+ this.name = 'LinearRateLimitError';
+ }
+}
+
export async function runWriteBack({
listCandidates,
listChildren,
@@ -349,7 +371,7 @@ export async function runWriteBack({
return;
}
- const children = await listChildren(candidate.id);
+ const children = candidate.hasChildren === false ? [] : await listChildren(candidate.id);
const considered = children.length > 0 ? children : [candidate];
@@ -522,7 +544,27 @@ export async function runWriteBack({
}
};
- for (const candidate of await listCandidates()) {
+ let candidates;
+ try {
+ candidates = await listCandidates();
+ } catch (error) {
+ if (!(error instanceof LinearRateLimitError)) throw error;
+ return {
+ posted,
+ skipped,
+ errored: [
+ {
+ identifier: 'candidate-enumeration',
+ message: error.message,
+ disposition: 'retried-next-run',
+ },
+ ],
+ deferred: null,
+ dryRun: !live,
+ };
+ }
+ let deferred = 0;
+ for (const [index, candidate] of candidates.entries()) {
try {
await processCandidate(candidate);
} catch (err) {
@@ -531,14 +573,21 @@ export async function runWriteBack({
`::warning::write-back: ${candidate.identifier} could not be processed (${disposition}): ${err.message}`,
);
errored.push({ identifier: candidate.identifier, message: err.message, disposition });
+ if (err instanceof LinearRateLimitError) {
+ deferred = candidates.length - index - 1;
+ break;
+ }
}
}
- return { posted, skipped, errored, dryRun: !live };
+ return { posted, skipped, errored, deferred, dryRun: !live };
}
-export function runFailureMessage({ errored = [] } = {}) {
+export function runFailureMessage({ errored = [], deferred } = {}) {
if (errored.length === 0) return null;
+ if (deferred === null) {
+ return `Candidate enumeration stopped: ${errored[0].message} The remaining count is unknown; no marker was written, and a later reconciliation can retry.`;
+ }
const head =
`${errored.length} of the candidates could not be processed: ` +
errored.map((e) => `${e.identifier} (${e.message})`).join('; ');
@@ -561,7 +610,7 @@ export const LINEAR_RETRY_CAP_MS = 8000;
export const REQUEST_TIMEOUT_MS = 15_000;
export function isRetryableStatus(status) {
- return status === 429 || (status >= 500 && status < 600);
+ return status >= 500 && status < 600;
}
const RETRYABLE_NETWORK_CODES = new Set([
@@ -657,14 +706,29 @@ export async function linearGraphql({
if (!res.ok) {
let body = '';
try {
- body = (await res.text()).slice(0, 400);
+ body = await res.text();
} catch (err) {
body = `<body unreadable: ${err.message}>`;
}
- throw new LinearRequestError(`Linear GraphQL returned HTTP ${res.status}: ${body}`, {
- retryable: isRetryableStatus(res.status),
- retryAfterSeconds: parseRetryAfterSeconds(res.headers?.get?.('retry-after')),
- });
+ let payload;
+ try {
+ payload = JSON.parse(body);
+ } catch {
+ payload = null;
+ }
+ if (
+ res.status === 429 ||
+ payload?.errors?.some((error) => error.extensions?.code === 'RATELIMITED')
+ ) {
+ throw new LinearRateLimitError(res.headers);
+ }
+ throw new LinearRequestError(
+ `Linear GraphQL returned HTTP ${res.status}: ${body.slice(0, 400)}`,
+ {
+ retryable: isRetryableStatus(res.status),
+ retryAfterSeconds: parseRetryAfterSeconds(res.headers?.get?.('retry-after')),
+ },
+ );
}
let payload;
@@ -676,6 +740,9 @@ export async function linearGraphql({
});
}
if (payload.errors?.length) {
+ if (payload.errors.some((error) => error.extensions?.code === 'RATELIMITED')) {
+ throw new LinearRateLimitError(res.headers);
+ }
throw new LinearRequestError(
`Linear GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`,
{
@@ -696,21 +763,30 @@ export async function linearGraphql({
}
}
-function toNode(raw) {
+export function toNode(raw) {
return {
id: raw.id,
identifier: raw.identifier,
stateType: raw.state?.type ?? 'unknown',
labels: (raw.labels?.nodes ?? []).map((l) => l.name),
attachmentUrls: (raw.attachments?.nodes ?? []).map((a) => a.url),
+ hasChildren: Array.isArray(raw.children?.nodes)
+ ? raw.children.nodes.length > 0 || raw.children.pageInfo?.hasNextPage !== false
+ : undefined,
};
}
-async function paginate({ apiKey, query, variables, log }) {
+async function paginate({ apiKey, query, variables, log, fetchImpl }) {
const collected = [];
let after = null;
do {
- const data = await linearGraphql({ apiKey, query, variables: { ...variables, after }, log });
+ const data = await linearGraphql({
+ apiKey,
+ query,
+ variables: { ...variables, after },
+ log,
+ fetchImpl,
+ });
const page = data?.issues;
if (!page)
throw new Error(
@@ -958,10 +1034,16 @@ async function main() {
);
}
+ let linearRequests = 0;
+ const fetchImpl = (...args) => {
+ linearRequests++;
+ return fetch(...args);
+ };
const result = await runWriteBack({
- listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {}, log }),
+ listCandidates: () =>
+ paginate({ apiKey, query: CANDIDATE_QUERY, variables: {}, log, fetchImpl }),
listChildren: (parentId) =>
- paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log }),
+ paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log, fetchImpl }),
versionFor: (node) => versionFor(node, channel),
stableVersionFor: (node) => versionFor(node, 'stable'),
isPublishedVersion: (version) => stableTags.includes(`v${version}`),
@@ -971,6 +1053,7 @@ async function main() {
postReply: realPostReply,
recordNotification: async ({ issueId, url, title }) => {
const data = await linearGraphql({
+ fetchImpl,
apiKey,
query:
'mutation Mark($input: AttachmentCreateInput!) { attachmentCreate(input: $input) { success } }',
@@ -988,6 +1071,8 @@ async function main() {
console.log(
JSON.stringify({
dryRun: result.dryRun,
+ linearRequests,
+ deferred: result.deferred,
posted: result.posted.length,
skipped: result.skipped,
errored: result.errored,
diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjs
index f76d71cca..1db7c47d6 100644
--- a/.github/scripts/write-back.test.mjs
+++ b/.github/scripts/write-back.test.mjs
@@ -16,6 +16,7 @@ import {
isStableVersion,
LINEAR_RETRY_ATTEMPTS,
LINEAR_RETRY_CAP_MS,
+ LinearRateLimitError,
linearGraphql,
makeReleaseWindow,
notificationMarkerUrl,
@@ -26,6 +27,7 @@ import {
runFailureMessage,
runWriteBack,
selectGhToken,
+ toNode,
} from './write-back.mjs';
import { composeReply } from './write-back-gate.mjs';
@@ -72,6 +74,23 @@ function harness(overrides = {}) {
}
describe('candidate enumeration', () => {
+ test('the candidate page proves whether a child lookup is necessary without filtering child states', () => {
+ expect(CANDIDATE_QUERY).toContain(
+ 'children(first: 1) { nodes { id } pageInfo { hasNextPage } }',
+ );
+ expect(toNode({ children: { nodes: [], pageInfo: { hasNextPage: false } } }).hasChildren).toBe(
+ false,
+ );
+ expect(
+ toNode({ children: { nodes: [{ id: 'child' }], pageInfo: { hasNextPage: false } } })
+ .hasChildren,
+ ).toBe(true);
+ expect(toNode({ children: { nodes: [], pageInfo: { hasNextPage: true } } }).hasChildren).toBe(
+ true,
+ );
+ expect(toNode({ children: { nodes: [] } }).hasChildren).toBe(true);
+ expect(toNode({}).hasChildren).toBeUndefined();
+ });
test('candidates come from a Linear ticket query, never from a walk over release commits', () => {
expect(CANDIDATE_QUERY).toContain('issues(');
expect(CANDIDATE_QUERY).toContain('state: { type: { eq: "completed" } }');
@@ -461,6 +480,92 @@ describe('idempotency marker', () => {
});
describe('write-back run', () => {
+ test('an enumeration throttle returns an unknown deferred count without processing or writing', async () => {
+ const h = harness({
+ live: true,
+ listCandidates: async () => {
+ throw new LinearRateLimitError();
+ },
+ });
+ const result = await h.run();
+ expect(result.deferred).toBeNull();
+ expect(result.errored).toHaveLength(1);
+ expect(h.writes).toEqual([]);
+ expect(runFailureMessage(result)).toContain('remaining count is unknown');
+ });
+
+ test('quota diagnostics retain endpoint and complexity windows without mislabelling them as global', () => {
+ const headers = {
+ 'x-ratelimit-endpoint-name': 'attachmentCreate',
+ 'x-ratelimit-endpoint-requests-reset': '123',
+ 'x-ratelimit-complexity-reset': '456',
+ 'retry-after': '2',
+ };
+ const error = new LinearRateLimitError({ get: (name) => headers[name] });
+ expect(error.message).toContain('endpoint attachmentCreate reset epoch ms: 123');
+ expect(error.message).toContain('complexity reset epoch ms: 456');
+ expect(error.message).toContain('retry-after: 2');
+ expect(error.message).not.toContain('(request reset');
+ });
+ test('leaf issues spend no separate child-query request', async () => {
+ let calls = 0;
+ const leaf = toNode({
+ id: 'leaf',
+ identifier: 'PRD-7539',
+ state: { type: 'completed' },
+ attachments: { nodes: [{ url: GH_ISSUE }, { url: GH_PULL }] },
+ children: { nodes: [], pageInfo: { hasNextPage: false } },
+ });
+ const h = harness({
+ listCandidates: async () => [leaf],
+ listChildren: async () => {
+ calls++;
+ return [];
+ },
+ });
+ const result = await h.run();
+ expect(result.posted).toHaveLength(1);
+ expect(calls).toBe(0);
+ });
+
+ test.each([true, undefined])(
+ 'a parent or unknown child hint still loads every child (hint=%s)',
+ async (hasChildren) => {
+ let calls = 0;
+ const h = harness({
+ listCandidates: async () => [candidate({ hasChildren })],
+ listChildren: async () => {
+ calls++;
+ return [candidate({ id: 'child', identifier: 'PRD-0002', stateType: 'started' })];
+ },
+ });
+ const result = await h.run();
+ expect(calls).toBe(1);
+ expect(result.posted).toEqual([]);
+ },
+ );
+
+ test('a Linear quota refusal stops the entire scan instead of querying every remaining candidate', async () => {
+ let calls = 0;
+ const h = harness({
+ live: true,
+ listCandidates: async () => [
+ candidate(),
+ candidate({ id: '2', identifier: 'PRD-2' }),
+ candidate({ id: '3', identifier: 'PRD-3' }),
+ ],
+ listChildren: async () => {
+ calls++;
+ throw new LinearRateLimitError({ get: () => '1790326800000' });
+ },
+ });
+ const result = await h.run();
+ expect(calls).toBe(1);
+ expect(result.deferred).toBe(2);
+ expect(result.errored).toHaveLength(1);
+ expect(result.errored[0].message).toContain('1790326800000');
+ expect(h.writes).toEqual([]);
+ });
test('with no explicit live mode it composes and logs but performs no writes at all', async () => {
const h = harness();
const result = await h.run();
@@ -922,19 +1027,39 @@ describe('a Linear call that failed for reasons unrelated to the request', () =>
expect(h.slept).toEqual([]);
});
- test('every 4xx that is not 429 fails fast, and every 5xx is retried', () => {
- for (const status of [400, 401, 403, 404, 409, 422])
+ test('4xx fails fast, while transient 5xx remains retryable', () => {
+ for (const status of [400, 401, 403, 404, 409, 422, 429])
expect(isRetryableStatus(status)).toBe(false);
- for (const status of [429, 500, 502, 503, 504]) expect(isRetryableStatus(status)).toBe(true);
+ for (const status of [500, 502, 503, 504]) expect(isRetryableStatus(status)).toBe(true);
expect(isRetryableStatus(200)).toBe(false);
});
- test('a 429 waits as long as Linear asked rather than as long as the backoff computed', async () => {
+ test('a 429 stops without spending more quota or sleeping past the job budget', async () => {
const h = callLinear([fail(429, 'slow down', { 'retry-after': '2' }), ok({ issues: {} })]);
- await h.call;
- expect(h.slept).toEqual([2000]);
+ await expect(h.call).rejects.toBeInstanceOf(LinearRateLimitError);
+ expect(h.attemptCount()).toBe(1);
+ expect(h.slept).toEqual([]);
});
+ test.each([400, 200])(
+ 'Linear GraphQL RATELIMITED on HTTP %s stops without retries',
+ async (status) => {
+ const payload = {
+ errors: [
+ { message: 'Rate limit exceeded', extensions: { code: 'RATELIMITED', statusCode: 429 } },
+ ],
+ };
+ const response =
+ status === 400
+ ? fail(400, JSON.stringify(payload))
+ : { ok: true, status: 200, json: async () => payload, headers: { get: () => null } };
+ const h = callLinear([response, ok({ issues: {} })]);
+ await expect(h.call).rejects.toBeInstanceOf(LinearRateLimitError);
+ expect(h.attemptCount()).toBe(1);
+ expect(h.slept).toEqual([]);
+ },
+ );
+
test('an outsized Retry-After is capped, so one reply cannot park the job', () => {
expect(retryDelayMs({ attempt: 1, retryAfterSeconds: 3600 })).toBe(LINEAR_RETRY_CAP_MS);
expect(parseRetryAfterSeconds('2')).toBe(2);