Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ci): retry transient Linear failures in reporter write-back (#3064)

Andrew Mikofalvy9242aebd743d
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjs
index d5be964a7..83305f36f 100644
--- a/.github/scripts/write-back.mjs
+++ b/.github/scripts/write-back.mjs
@@ -259,6 +259,23 @@ export function makeReleaseWindow({
};
}
+/**
+ * A failure that no later run will pick up, so a person has to.
+ *
+ * Every other per-candidate failure happens before the marker is written, which
+ * means the next release run enumerates that ticket again and tries again by
+ * itself. This one happens after, so the ticket looks notified to every future
+ * run while the reporter was never actually told. The two need opposite
+ * responses — wait versus act — and an operator reading a red job should not
+ * have to infer which from the wording of an error message.
+ */
+export class NeedsHumanError extends Error {
+ constructor(message) {
+ super(message);
+ this.name = 'NeedsHumanError';
+ }
+}
+
/**
* Walk every candidate and decide, for each, whether to reply and where.
*
@@ -416,11 +433,11 @@ export async function runWriteBack({
try {
await postReply(origin, text);
} catch (err) {
- // Past the point of no return. Re-raise saying so, because the generic
- // "could not be processed" this lands in reads as retryable and this
- // one is not: the marker stands, so no later run will pick it up and
- // the only remaining fix is a reply posted by hand.
- throw new Error(
+ // Past the point of no return. Re-raise as its own type, because the
+ // generic "could not be processed" this lands in reads as retryable and
+ // this one is not: the marker stands, so no later run will pick it up
+ // and the only remaining fix is a reply posted by hand.
+ throw new NeedsHumanError(
`marker for ${origin.url} was written but the reply did NOT send (${err.message}). ` +
'No future run will retry it; post the reply by hand.',
);
@@ -434,8 +451,11 @@ export async function runWriteBack({
try {
await processCandidate(candidate);
} catch (err) {
- log(`::warning::write-back: ${candidate.identifier} could not be processed: ${err.message}`);
- errored.push({ identifier: candidate.identifier, message: err.message });
+ const disposition = err instanceof NeedsHumanError ? 'needs-human' : 'retried-next-run';
+ log(
+ `::warning::write-back: ${candidate.identifier} could not be processed (${disposition}): ${err.message}`,
+ );
+ errored.push({ identifier: candidate.identifier, message: err.message, disposition });
}
}
@@ -448,31 +468,240 @@ export async function runWriteBack({
* returned rather than thrown where it is decided, so that "errors must still
* turn the job red" is one expression a test can hold on to instead of a branch
* inside an entry point nothing can call.
+ *
+ * Red is red either way, but the two dispositions want opposite responses and
+ * the message says which. A run that is red only because Linear wobbled needs
+ * nobody to do anything; a marker written without its reply needs a person, and
+ * saying so in the same breath as the failure is the difference between that
+ * being noticed and it being read as one more flake.
*/
export function runFailureMessage({ errored = [] } = {}) {
if (errored.length === 0) return null;
- return (
+ const head =
`${errored.length} of the candidates could not be processed: ` +
- errored.map((e) => `${e.identifier} (${e.message})`).join('; ')
+ errored.map((e) => `${e.identifier} (${e.message})`).join('; ');
+
+ const needsHuman = errored.filter((e) => e.disposition === 'needs-human');
+ if (needsHuman.length === 0) {
+ return `${head}. No marker was written for any of them, so the next release run picks them up again.`;
+ }
+ return (
+ `${head}. ACTION REQUIRED: ${needsHuman.map((e) => e.identifier).join(', ')} ` +
+ `${needsHuman.length === 1 ? 'was' : 'were'} marked as notified but the reply never sent; ` +
+ 'no future run will retry, so post it by hand.'
);
}
// --- workflow-runtime wiring (real Linear / git / gh / Discord boundary) ---
-async function linearGraphql({ apiKey, query, variables }) {
- const res = await fetch(LINEAR_GRAPHQL_URL, {
- method: 'POST',
- headers: { 'content-type': 'application/json', authorization: apiKey },
- body: JSON.stringify({ query, variables }),
- });
- if (!res.ok) {
- throw new Error(`Linear GraphQL returned HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+export const LINEAR_RETRY_ATTEMPTS = 3;
+export const LINEAR_RETRY_BASE_MS = 500;
+export const LINEAR_RETRY_CAP_MS = 8000;
+
+/**
+ * How long any one outbound request may go unanswered.
+ *
+ * A connection that is refused or dropped surfaces immediately, but one that is
+ * accepted and then goes silent is left running by undici for five minutes:
+ * half this job's entire budget, spent without a single word in the log. Two of
+ * them outlast the job, so an unbounded request does not merely delay the retry,
+ * it guarantees the retry is never spent and the run dies as a bare Actions
+ * timeout carrying none of the disposition it exists to report.
+ *
+ * The ceiling is far above any answer either endpoint has a reason to be slow
+ * about, so reaching it means silence rather than load.
+ */
+export const REQUEST_TIMEOUT_MS = 15_000;
+
+/**
+ * Which HTTP replies from Linear are worth asking again about.
+ *
+ * A 4xx is Linear having read the request and rejected it — a bad credential, a
+ * malformed query, a filter the schema does not have. Asking again produces the
+ * same answer, so retrying only delays a correct failure and buries its message
+ * under attempts. A 5xx is the opposite: the one seen in the wild was an Envoy
+ * `connection termination` raised before authentication ran at all, so the edge
+ * never reached the backend and the request as written was never judged. 429 is
+ * Linear naming a wait out loud.
+ *
+ * The distinction earns its keep at this scale rather than in principle. One
+ * enumeration makes several hundred sequential requests; meeting at least one
+ * blip across them is nearer to expected than to unlucky, and a single one used
+ * to fail the entire job.
+ */
+export function isRetryableStatus(status) {
+ return status === 429 || (status >= 500 && status < 600);
+}
+
+const RETRYABLE_NETWORK_CODES = new Set([
+ 'ECONNRESET',
+ 'ECONNREFUSED',
+ 'ENOTFOUND',
+ 'EAI_AGAIN',
+ 'EPIPE',
+ 'ETIMEDOUT',
+ 'UND_ERR_SOCKET',
+ 'UND_ERR_CONNECT_TIMEOUT',
+ 'UND_ERR_HEADERS_TIMEOUT',
+ 'UND_ERR_BODY_TIMEOUT',
+]);
+
+/**
+ * Whether a throw out of `fetch` describes a connection that failed rather than
+ * a request that was answered.
+ *
+ * Nothing was interpreted in that case — no status, no body — so the request is
+ * in exactly the state a 5xx leaves it in and gets the same treatment. undici
+ * reports these as a bare `TypeError: fetch failed` and hangs the real reason
+ * off `cause`, so the chain is walked rather than the top-level message read.
+ * An unrecognised throw is deliberately NOT retried: absent a reason to think
+ * the connection was at fault, repeating it is guesswork.
+ *
+ * A request abandoned at its own deadline is matched by name rather than by
+ * code: `AbortSignal.timeout` rejects with a DOMException whose `code` is the
+ * numeric legacy 23, which the table of string codes below cannot see. Its
+ * sibling `AbortError` is pointedly absent, because an abort no clock asked for
+ * was somebody's decision and repeating the request would be overriding it.
+ */
+export function isRetryableNetworkError(err) {
+ for (let cur = err, depth = 0; cur && typeof cur === 'object' && depth < 5; cur = cur.cause, depth += 1) {
+ if (cur.name === 'TimeoutError') return true;
+ if (RETRYABLE_NETWORK_CODES.has(cur.code)) return true;
+ if (/fetch failed|socket hang up|other side closed|terminated|network/i.test(String(cur.message ?? ''))) {
+ return true;
+ }
}
- const payload = await res.json();
- if (payload.errors?.length) {
- throw new Error(`Linear GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`);
+ return false;
+}
+
+/** `Retry-After` in its delta-seconds form; the HTTP-date form falls through to backoff. */
+export function parseRetryAfterSeconds(header) {
+ const seconds = Number(String(header ?? '').trim());
+ return Number.isFinite(seconds) && seconds > 0 ? seconds : null;
+}
+
+/**
+ * How long to wait before the next attempt.
+ *
+ * Half the exponential window plus a random slice of the other half. The random
+ * part keeps concurrent retriers from re-colliding in lockstep after a shared
+ * outage; keeping the first half fixed guarantees the wait is never so short
+ * that the retry is just a second helping of the same hammering. An explicit
+ * `Retry-After` wins over the computed window but is still capped, so a large
+ * one cannot park the job for the length of its own timeout.
+ */
+export function retryDelayMs({
+ attempt,
+ retryAfterSeconds = null,
+ base = LINEAR_RETRY_BASE_MS,
+ cap = LINEAR_RETRY_CAP_MS,
+ random = Math.random,
+}) {
+ if (retryAfterSeconds !== null) return Math.min(retryAfterSeconds * 1000, cap);
+ const window = Math.min(base * 2 ** (attempt - 1), cap);
+ return Math.round(window / 2 + random() * (window / 2));
+}
+
+class LinearRequestError extends Error {
+ constructor(message, { retryable, retryAfterSeconds = null }) {
+ super(message);
+ this.name = 'LinearRequestError';
+ this.retryable = retryable;
+ this.retryAfterSeconds = retryAfterSeconds;
+ }
+}
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * One Linear GraphQL call, retried when the failure says nothing about the
+ * request itself.
+ *
+ * Both call sites are safe to repeat. The reads are reads. The one mutation
+ * creates an attachment whose URL is deterministic in (origin, version), and
+ * Linear treats that URL as an idempotent key against the issue — the same
+ * property the cross-run at-most-once guarantee already rests on, which is
+ * strictly stronger than repeating the call inside a single run. Retrying it
+ * also closes a hole that not retrying leaves open: a marker that was written
+ * but whose reply was lost in transit reads to the next run as `already
+ * notified`, so the reporter is never told and nothing says so.
+ *
+ * Payload-level `errors` are never retried. A 200 carrying them means the query
+ * was understood and refused, which is the 4xx case wearing a different status.
+ */
+export async function linearGraphql({
+ apiKey,
+ query,
+ variables,
+ fetchImpl = fetch,
+ sleep = realSleep,
+ random = Math.random,
+ attempts = LINEAR_RETRY_ATTEMPTS,
+ timeoutMs = REQUEST_TIMEOUT_MS,
+ log = () => {},
+}) {
+ for (let attempt = 1; ; attempt += 1) {
+ try {
+ let res;
+ try {
+ // Minted per attempt, so a retry starts with a fresh deadline rather
+ // than inheriting the spent one. It stays live through the body reads
+ // below, which is what bounds a reply that begins and then stops.
+ res = await fetchImpl(LINEAR_GRAPHQL_URL, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', authorization: apiKey },
+ body: JSON.stringify({ query, variables }),
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ } catch (err) {
+ throw new LinearRequestError(`Linear GraphQL request failed before any reply: ${err.message}`, {
+ retryable: isRetryableNetworkError(err),
+ });
+ }
+
+ if (!res.ok) {
+ // The status is the part that decides retryability, so reading the body
+ // must not be able to take it away: the same dropped connection that
+ // produced a 5xx can drop again mid-body.
+ let body = '';
+ try {
+ body = (await res.text()).slice(0, 400);
+ } 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 = await res.json();
+ } catch (err) {
+ // A body that died in transit is the connection failing a beat later
+ // than the cases above and gets the same treatment. A body that arrived
+ // whole and simply is not JSON is not, and its SyntaxError says so.
+ throw new LinearRequestError(`Linear GraphQL reply could not be read: ${err.message}`, {
+ retryable: isRetryableNetworkError(err),
+ });
+ }
+ if (payload.errors?.length) {
+ throw new LinearRequestError(`Linear GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`, {
+ retryable: false,
+ });
+ }
+ return payload.data;
+ } catch (err) {
+ if (attempt >= attempts || !err.retryable) throw err;
+ const delay = retryDelayMs({ attempt, retryAfterSeconds: err.retryAfterSeconds, random });
+ log(
+ `::notice::write-back: Linear call failed transiently (${err.message}); retrying in ${delay}ms ` +
+ `(attempt ${attempt + 1} of ${attempts}).`,
+ );
+ await sleep(delay);
+ }
}
- return payload.data;
}
function toNode(raw) {
@@ -485,11 +714,11 @@ function toNode(raw) {
};
}
-async function paginate({ apiKey, query, variables }) {
+async function paginate({ apiKey, query, variables, log }) {
const collected = [];
let after = null;
do {
- const data = await linearGraphql({ apiKey, query, variables: { ...variables, after } });
+ const data = await linearGraphql({ apiKey, query, variables: { ...variables, after }, log });
const page = data?.issues;
if (!page) throw new Error('Linear returned no issues connection; refusing to treat that as an empty result.');
collected.push(...page.nodes.map(toNode));
@@ -708,10 +937,16 @@ async function realPostReply(origin, text) {
const url = process.env.DISCORD_NOTIFY_URL;
const token = process.env.DISCORD_NOTIFY_TOKEN;
if (!url || !token) throw new Error('DISCORD_NOTIFY_URL / DISCORD_NOTIFY_TOKEN are required to reply on Discord');
+ // Deadlined but deliberately not retried: this runs after the marker is
+ // written, so a second send could double-post. The deadline is what turns a
+ // bot that stopped answering into the needs-human disposition the caller
+ // raises, instead of a silent hang in the one state (marked, not delivered)
+ // that nobody can infer from a job that simply ran out of time.
const res = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
body: JSON.stringify({ threadId: origin.threadId, content: text }),
+ signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
});
if (!res.ok) {
throw new Error(`notify endpoint returned HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
@@ -764,8 +999,8 @@ async function main() {
}
const result = await runWriteBack({
- listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {} }),
- listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId } }),
+ listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {}, log }),
+ listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log }),
versionFor,
classifyRelease,
readChangesetProse: (candidate, ctx) => realReadChangesetProse(candidate, ctx),
@@ -776,6 +1011,7 @@ async function main() {
query:
'mutation Mark($input: AttachmentCreateInput!) { attachmentCreate(input: $input) { success } }',
variables: { input: { issueId, url, title } },
+ log,
});
// A dropped marker is not cosmetic: it is what stops the next run
// replying to the same reporter again.
diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjs
index 58e7ec999..2d7e1769e 100644
--- a/.github/scripts/write-back.test.mjs
+++ b/.github/scripts/write-back.test.mjs
@@ -7,10 +7,17 @@ import {
deriveVersionForFixRefs,
findChangesetPath,
isFixRepoInRemit,
+ isRetryableNetworkError,
+ isRetryableStatus,
+ LINEAR_RETRY_ATTEMPTS,
+ LINEAR_RETRY_CAP_MS,
+ linearGraphql,
makeReleaseWindow,
notificationMarkerUrl,
parseChangeset,
parseMergeShaOutput,
+ parseRetryAfterSeconds,
+ retryDelayMs,
runFailureMessage,
runWriteBack,
selectGhToken,
@@ -580,6 +587,296 @@ describe('one unreadable candidate does not silence the rest', () => {
});
});
+describe('telling a failure that waits from a failure that needs a person', () => {
+ test('a failure before the marker is filed as one the next run picks up', async () => {
+ const h = harness({
+ live: true,
+ versionFor: async () => {
+ throw new Error('Linear GraphQL returned HTTP 503');
+ },
+ });
+ const result = await h.run();
+
+ // No marker was written, so the ticket is enumerated again next release and
+ // tried again by itself. Nobody has to do anything.
+ expect(h.writes).toEqual([]);
+ expect(result.errored[0].disposition).toBe('retried-next-run');
+ });
+
+ test('a reply lost after its marker was written is filed as one that needs a person', async () => {
+ const h = harness({
+ live: true,
+ postReply: async () => {
+ throw new Error('notify endpoint returned HTTP 502');
+ },
+ });
+ const result = await h.run();
+
+ expect(result.errored[0].disposition).toBe('needs-human');
+ expect(h.logs.some((m) => m.includes('needs-human'))).toBe(true);
+ });
+
+ test('the run verdict names the tickets a person has to pick up, and stays quiet when none do', () => {
+ const transient = runFailureMessage({
+ errored: [{ identifier: 'PRD-0001', message: 'HTTP 503', disposition: 'retried-next-run' }],
+ });
+ expect(transient).toContain('next release run picks them up');
+ expect(transient).not.toContain('ACTION REQUIRED');
+
+ const needsHuman = runFailureMessage({
+ errored: [
+ { identifier: 'PRD-0001', message: 'HTTP 503', disposition: 'retried-next-run' },
+ { identifier: 'PRD-0002', message: 'marker written, reply did NOT send', disposition: 'needs-human' },
+ ],
+ });
+ // Both are red. Only one of them is a job for a person, and a verdict that
+ // did not say which would read as one more flake.
+ expect(needsHuman).toContain('ACTION REQUIRED');
+ expect(needsHuman).toContain('PRD-0002');
+ expect(needsHuman).not.toMatch(/ACTION REQUIRED[^.]*PRD-0001/);
+ });
+});
+
+describe('a Linear call that failed for reasons unrelated to the request', () => {
+ const ok = (data) => ({ ok: true, status: 200, json: async () => ({ data }), headers: { get: () => null } });
+ const fail = (status, body = 'upstream connect error', headers = {}) => ({
+ ok: false,
+ status,
+ text: async () => body,
+ headers: { get: (name) => headers[String(name).toLowerCase()] ?? null },
+ });
+
+ // Every attempt is recorded and no wall-clock time passes: `sleep` only notes
+ // what it was asked to wait, and `random` is fixed so the delay is exact.
+ function callLinear(replies, overrides = {}) {
+ const slept = [];
+ const logs = [];
+ let attempts = 0;
+ const call = linearGraphql({
+ apiKey: 'k',
+ query: 'query {}',
+ variables: {},
+ fetchImpl: async (_url, init) => {
+ const reply = replies[attempts];
+ attempts += 1;
+ if (typeof reply === 'function') return reply(init);
+ return reply;
+ },
+ sleep: async (ms) => slept.push(ms),
+ random: () => 0.5,
+ log: (m) => logs.push(m),
+ ...overrides,
+ });
+ return { call, slept, logs, attemptCount: () => attempts };
+ }
+
+ test('a 503 is asked again rather than failing the whole job', async () => {
+ // The exact shape of the failure that broke the v0.45.0 run: an Envoy reply
+ // raised before authentication, among hundreds of requests that worked.
+ const h = callLinear([
+ fail(503, 'upstream connect error or disconnect/reset before headers'),
+ ok({ issues: { nodes: [] } }),
+ ]);
+ await expect(h.call).resolves.toEqual({ issues: { nodes: [] } });
+ expect(h.attemptCount()).toBe(2);
+ expect(h.slept).toHaveLength(1);
+ expect(h.logs.join(' ')).toContain('retrying in');
+ });
+
+ test('a 401 is not asked again, because the answer would be the same', async () => {
+ // Retrying a genuine credential failure only delays a correct verdict and
+ // buries its message under attempts. The distinguishing detail must survive.
+ const h = callLinear([fail(401, '{"errors":[{"type":"AUTHENTICATION_ERROR"}]}')]);
+ await expect(h.call).rejects.toThrow(/HTTP 401/);
+ await expect(h.call).rejects.toThrow(/AUTHENTICATION_ERROR/);
+ expect(h.attemptCount()).toBe(1);
+ 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]) expect(isRetryableStatus(status)).toBe(false);
+ for (const status of [429, 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 () => {
+ const h = callLinear([fail(429, 'slow down', { 'retry-after': '2' }), ok({ issues: {} })]);
+ await h.call;
+ expect(h.slept).toEqual([2000]);
+ });
+
+ 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);
+ // The HTTP-date form is not delta-seconds; it falls through to backoff.
+ expect(parseRetryAfterSeconds('Wed, 30 Jul 2026 19:11:09 GMT')).toBeNull();
+ expect(parseRetryAfterSeconds(null)).toBeNull();
+ expect(parseRetryAfterSeconds('0')).toBeNull();
+ });
+
+ test('the wait grows between attempts and is never long enough to be unbounded', () => {
+ const first = retryDelayMs({ attempt: 1, random: () => 0.5 });
+ const second = retryDelayMs({ attempt: 2, random: () => 0.5 });
+ expect(second).toBeGreaterThan(first);
+ expect(retryDelayMs({ attempt: 20, random: () => 1 })).toBeLessThanOrEqual(LINEAR_RETRY_CAP_MS);
+ // Half the window is fixed, so a retry is never a second helping of the
+ // same hammering; the other half is where the jitter lives.
+ expect(retryDelayMs({ attempt: 1, random: () => 0 })).toBeLessThan(retryDelayMs({ attempt: 1, random: () => 1 }));
+ expect(retryDelayMs({ attempt: 1, random: () => 0 })).toBeGreaterThan(0);
+ });
+
+ test('a connection that never produced a reply is retried like a 5xx', async () => {
+ // undici reports a reset as a bare `fetch failed` and hangs the reason off
+ // `cause`, so the chain has to be walked rather than the message read.
+ const reset = Object.assign(new TypeError('fetch failed'), {
+ cause: Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET' }),
+ });
+ const h = callLinear([
+ () => {
+ throw reset;
+ },
+ ok({ issues: {} }),
+ ]);
+ await expect(h.call).resolves.toEqual({ issues: {} });
+ expect(h.attemptCount()).toBe(2);
+ });
+
+ test('a throw with no sign the connection was at fault is not retried on a guess', async () => {
+ const h = callLinear([
+ () => {
+ throw new TypeError('Invalid header value');
+ },
+ ]);
+ await expect(h.call).rejects.toThrow(/before any reply/);
+ expect(h.attemptCount()).toBe(1);
+ });
+
+ test('a reply that never arrives is given up on rather than allowed to eat the job', async () => {
+ // The case the retry is otherwise blind to. undici leaves a connection that
+ // was accepted and then went silent running for five minutes by default, so
+ // two of them exceed the job's own budget: without a deadline on the request
+ // the attempt below is never reached, and the run dies as an Actions timeout
+ // carrying none of the disposition it would otherwise have reported.
+ const h = callLinear(
+ [
+ (init) => {
+ if (!init?.signal) throw new Error('the request carried no deadline');
+ // What undici does when the signal fires: reject with its reason.
+ return new Promise((_resolve, reject) => {
+ init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true });
+ });
+ },
+ ok({ issues: {} }),
+ ],
+ { timeoutMs: 20 },
+ );
+ await expect(h.call).resolves.toEqual({ issues: {} });
+ expect(h.attemptCount()).toBe(2);
+ });
+
+ test('a request given up on at its deadline is retried, but a deliberate cancellation is not', async () => {
+ // Taken from the runtime rather than hand-rolled, because the shape is the
+ // whole point: `AbortSignal.timeout` rejects with a DOMException whose
+ // `code` is the numeric legacy 23 and not a string, so the code table cannot
+ // recognise it and its name is the only thing that can.
+ const signal = AbortSignal.timeout(1);
+ await new Promise((resolve) => signal.addEventListener('abort', resolve, { once: true }));
+ expect(signal.reason.name).toBe('TimeoutError');
+ expect(isRetryableNetworkError(signal.reason)).toBe(true);
+ // An abort nobody asked a clock for was somebody's decision, and repeating
+ // the request would be overriding it.
+ expect(isRetryableNetworkError(new DOMException('cancelled', 'AbortError'))).toBe(false);
+ });
+
+ test('the network classifier reads codes anywhere in the cause chain, and refuses the rest', () => {
+ expect(isRetryableNetworkError(Object.assign(new Error('x'), { code: 'ECONNRESET' }))).toBe(true);
+ expect(isRetryableNetworkError(Object.assign(new Error('x'), { code: 'UND_ERR_SOCKET' }))).toBe(true);
+ expect(isRetryableNetworkError(new TypeError('fetch failed'))).toBe(true);
+ expect(isRetryableNetworkError(new Error('socket hang up'))).toBe(true);
+ expect(isRetryableNetworkError(new Error('Unexpected token < in JSON'))).toBe(false);
+ expect(isRetryableNetworkError(null)).toBe(false);
+ });
+
+ test('a 200 carrying GraphQL errors is a refusal, not a wobble, so it is not retried', async () => {
+ const h = callLinear([
+ {
+ ok: true,
+ status: 200,
+ headers: { get: () => null },
+ json: async () => ({ errors: [{ message: 'Unknown field: notified' }] }),
+ },
+ ]);
+ await expect(h.call).rejects.toThrow(/Unknown field/);
+ expect(h.attemptCount()).toBe(1);
+ });
+
+ test('a service that stays down surfaces its own failure rather than a retry-shaped one', async () => {
+ const h = callLinear([fail(503), fail(503), fail(503), ok({ issues: {} })]);
+ await expect(h.call).rejects.toThrow(/HTTP 503/);
+ expect(h.attemptCount()).toBe(LINEAR_RETRY_ATTEMPTS);
+ });
+
+ test('a reply body that dies in transit is retried, since that is the connection failing a beat later', async () => {
+ const truncated = {
+ ok: true,
+ status: 200,
+ headers: { get: () => null },
+ json: async () => {
+ throw Object.assign(new TypeError('terminated'), {
+ cause: Object.assign(new Error('other side closed'), { code: 'UND_ERR_SOCKET' }),
+ });
+ },
+ };
+ const h = callLinear([truncated, ok({ issues: {} })]);
+ await expect(h.call).resolves.toEqual({ issues: {} });
+ expect(h.attemptCount()).toBe(2);
+ });
+
+ test('a reply that arrived whole and simply is not JSON is not retried', async () => {
+ const h = callLinear([
+ {
+ ok: true,
+ status: 200,
+ headers: { get: () => null },
+ json: async () => {
+ throw new SyntaxError('Unexpected token < in JSON at position 0');
+ },
+ },
+ ]);
+ await expect(h.call).rejects.toThrow(/could not be read/);
+ expect(h.attemptCount()).toBe(1);
+ });
+
+ test('an unreadable error body cannot cost the status that decides retryability', async () => {
+ // The same dropped connection that produced the 5xx can drop again while
+ // its body is being read. Losing the status there would turn a retryable
+ // failure into an unclassifiable one.
+ const h = callLinear([
+ {
+ ok: false,
+ status: 503,
+ headers: { get: () => null },
+ text: async () => {
+ throw new Error('aborted');
+ },
+ },
+ ok({ issues: {} }),
+ ]);
+ await expect(h.call).resolves.toEqual({ issues: {} });
+ expect(h.attemptCount()).toBe(2);
+ });
+
+ test('the marker mutation is retried too, since its url is what makes it idempotent', async () => {
+ // The deterministic (origin, version) url is already what stops a SECOND
+ // RUN re-replying, which is a stronger claim than repeating one call. Not
+ // retrying it leaves the worse hole open: a marker that landed while its
+ // reply was lost reads to the next run as already-notified.
+ const h = callLinear([fail(503), ok({ attachmentCreate: { success: true } })]);
+ await expect(h.call).resolves.toEqual({ attachmentCreate: { success: true } });
+ expect(h.attemptCount()).toBe(2);
+ });
+});
+
describe('workflow shape', () => {
const read = (name) => readFileSync(new URL(`../workflows/${name}`, import.meta.url), 'utf8');
const workflow = read('write-back.yml');