From 8d51598d3185b330978c7f5d0ef8f5659a7548c5 Mon Sep 17 00:00:00 2001 From: Day Dreamer <87640074+HugoXK@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:53:07 +0800 Subject: [PATCH 1/3] fix: classify a webhook reset on the error cause and retry a resolver failure (#896) --- .../896-webhook-classification.fixed.md | 1 + docs/security.md | 4 +- src/lib/webhook.ts | 51 +++++++++++++------ test/notificationOutbox.test.ts | 42 ++++++++++++++- 4 files changed, 81 insertions(+), 17 deletions(-) create mode 100644 changelog.d/896-webhook-classification.fixed.md diff --git a/changelog.d/896-webhook-classification.fixed.md b/changelog.d/896-webhook-classification.fixed.md new file mode 100644 index 00000000..a13174d0 --- /dev/null +++ b/changelog.d/896-webhook-classification.fixed.md @@ -0,0 +1 @@ +A webhook send that may have reached the destination is now classified `unknown` even when Undici puts the socket code on `error.cause`, so it is not resent automatically; a transient resolver failure is retried instead of being marked `blocked` permanently. diff --git a/docs/security.md b/docs/security.md index 942c2db6..898bb850 100644 --- a/docs/security.md +++ b/docs/security.md @@ -450,7 +450,9 @@ changed address is not mailed the old copy. A queued webhook row stores no URL: the configured `NOTIFY_WEBHOOK_URL` is read at send time under the same safety rule as a live send (https or allowlisted host, no credentials in the URL, no private or reserved address, bounded redirects), and a refused destination is -`blocked` rather than retried. The admin outbox page renders transport, state, +`blocked` rather than retried. A resolution failure (the resolver throws or +returns no address) is transient and stays `retry`; only the policy checks +(scheme, credentials, allowlist, private or reserved address) are `blocked`. The admin outbox page renders transport, state, attempt count, last error and delivery time with the address masked; it never renders the mail or webhook body. A delivered row is kept for 30 days, `dead` and `blocked` rows for 90, and `unknown` for 365 because it is the only state diff --git a/src/lib/webhook.ts b/src/lib/webhook.ts index 6be2edeb..fee8930d 100644 --- a/src/lib/webhook.ts +++ b/src/lib/webhook.ts @@ -17,6 +17,14 @@ export interface WebhookSafetyOptions { fetch?: typeof fetch } +/** A destination refusal (`blocked`) is terminal; a resolution failure is transient. */ +export class WebhookAddressError extends Error { + constructor(message: string, readonly kind: 'blocked' | 'retry') { + super(message) + this.name = 'WebhookAddressError' + } +} + const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]) const MAX_REDIRECTS = 5 @@ -29,16 +37,16 @@ function parseWebhookUrl(raw: string): URL { try { url = new URL(raw) } catch { - throw new Error('Refusing notification webhook: not an absolute URL') + throw new WebhookAddressError('Refusing notification webhook: not an absolute URL', 'blocked') } if (url.username !== '' || url.password !== '') { - throw new Error(`Refusing notification webhook: host "${normalizeHost(url.hostname)}" must not include credentials`) + throw new WebhookAddressError(`Refusing notification webhook: host "${normalizeHost(url.hostname)}" must not include credentials`, 'blocked') } if (url.protocol !== 'https:' && url.protocol !== 'http:') { - throw new Error(`Refusing notification webhook: host "${normalizeHost(url.hostname)}" must use http:// or https://`) + throw new WebhookAddressError(`Refusing notification webhook: host "${normalizeHost(url.hostname)}" must use http:// or https://`, 'blocked') } if (url.hostname === '') { - throw new Error('Refusing notification webhook: missing host') + throw new WebhookAddressError('Refusing notification webhook: missing host', 'blocked') } return url } @@ -47,7 +55,7 @@ async function resolveWebhookHost(host: string, resolve: WebhookResolver): Promi try { return await resolve(host) } catch { - throw new Error(`Refusing notification webhook: cannot resolve host "${host}"`) + throw new WebhookAddressError(`Refusing notification webhook: cannot resolve host "${host}"`, 'retry') } } @@ -58,16 +66,16 @@ export async function assertSafeWebhookUrl(raw: string, options: WebhookSafetyOp const allowlisted = allowedHosts.includes(host) if (allowedHosts.length > 0 && !allowlisted) { - throw new Error(`Refusing notification webhook: host "${host}" is not in NOTIFY_WEBHOOK_ALLOWED_HOSTS`) + throw new WebhookAddressError(`Refusing notification webhook: host "${host}" is not in NOTIFY_WEBHOOK_ALLOWED_HOSTS`, 'blocked') } if (allowlisted) return url if (url.protocol !== 'https:') { - throw new Error(`Refusing notification webhook: host "${host}" must use https://`) + throw new WebhookAddressError(`Refusing notification webhook: host "${host}" must use https://`, 'blocked') } if (isIP(host) !== 0) { if (isBlockedIpAddress(host)) { - throw new Error(`Refusing notification webhook: host "${host}" is a private or reserved address`) + throw new WebhookAddressError(`Refusing notification webhook: host "${host}" is a private or reserved address`, 'blocked') } return url } @@ -75,11 +83,11 @@ export async function assertSafeWebhookUrl(raw: string, options: WebhookSafetyOp const resolve = options.resolve ?? ((name: string) => lookup(name, { all: true })) const addresses = await resolveWebhookHost(host, resolve) if (addresses.length === 0) { - throw new Error(`Refusing notification webhook: cannot resolve host "${host}"`) + throw new WebhookAddressError(`Refusing notification webhook: cannot resolve host "${host}"`, 'retry') } for (const entry of addresses) { if (isBlockedIpAddress(entry.address)) { - throw new Error(`Refusing notification webhook: host "${host}" resolves to a private or reserved address`) + throw new WebhookAddressError(`Refusing notification webhook: host "${host}" resolves to a private or reserved address`, 'blocked') } } return url @@ -112,9 +120,10 @@ async function postWebhook( try { safeUrl = await assertSafeWebhookUrl(current.toString(), options) } catch (error) { - // A destination the safety rule refuses is not transient: retrying it - // forever would never change the answer, so the outbox records it blocked. - throw new NotificationWebhookError(String(error), 'blocked') + // A policy refusal is terminal; a resolver failure is transient. The + // address layer says which one this is, so a DNS blip is retried instead + // of losing the notification as `blocked`. + throw new NotificationWebhookError(String(error), error instanceof WebhookAddressError ? error.kind : 'blocked') } let response: Response try { @@ -164,11 +173,23 @@ export class NotificationWebhookError extends Error { // Connection refused, DNS and TLS-setup failures are not. const AMBIGUOUS_CODES = new Set(['ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT']) +function webhookErrorCode(error: unknown): string | undefined { + if (typeof error !== 'object' || error === null) return undefined + const record = error as { code?: unknown; cause?: unknown } + if (typeof record.code === 'string') return record.code + if (typeof record.cause === 'object' && record.cause !== null) { + const cause = record.cause as { code?: unknown } + if (typeof cause.code === 'string') return cause.code + } + return undefined +} + function isAmbiguousWebhookFailure(error: unknown): boolean { if (typeof error !== 'object' || error === null) return false - const record = error as { name?: unknown; code?: unknown } + const record = error as { name?: unknown } if (record.name === 'TimeoutError' || record.name === 'AbortError') return true - return typeof record.code === 'string' && AMBIGUOUS_CODES.has(record.code) + const code = webhookErrorCode(error) + return code !== undefined && AMBIGUOUS_CODES.has(code) } /** diff --git a/test/notificationOutbox.test.ts b/test/notificationOutbox.test.ts index 7ef51db2..3a1d1765 100644 --- a/test/notificationOutbox.test.ts +++ b/test/notificationOutbox.test.ts @@ -222,7 +222,7 @@ test('the webhook transport maps a status to sent, retry or dead, and a timeout assert.equal((await blocked.send(row('off'))).state, 'blocked') }) -test('a webhook that fails DNS is retried, but a private destination is blocked', async () => { +test('a fetch-level network error is retried, but a private destination is blocked', async () => { const config = testConfig({ notifyWebhookUrl: 'https://hooks.example.com/fledge' }) const resolve = async () => [{ address: '203.0.113.10', family: 4 }] const dns = webhookTransport(config, { @@ -236,6 +236,46 @@ test('a webhook that fails DNS is retried, but a private destination is blocked' assert.equal(refused.state, 'blocked', 'a refused destination is not retried forever') }) +test('a reset on the fetch cause is unknown and is not claimed on the next pass', async () => { + const config = testConfig({ notifyWebhookUrl: 'https://hooks.example.com/fledge' }) + const resolve = async () => [{ address: '203.0.113.10', family: 4 }] + const transport = webhookTransport(config, { + resolve, + fetch: async () => { throw Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNRESET' } }) }, + }) + assert.equal((await transport.send(row('cause-reset'))).state, 'unknown') + + const h = harness('cause-reset') + try { + enqueue(h.store, 'webhook:cause-reset') + const first = await deliverOutbox(h.store, { + email: { send: async () => ({ state: 'sent' }) }, + webhook: transport, + }, { now: T0, leaseMs: OUTBOX_LEASE_MS }) + assert.equal(first.unknown, 1) + + const second = await deliverOutbox(h.store, { + email: { send: async () => ({ state: 'sent' }) }, + webhook: { send: async () => { throw new Error('must not be called') } }, + }, { now: T0 + 60_000, leaseMs: OUTBOX_LEASE_MS }) + assert.equal(second.claimed, 0) + } finally { + h.store.close() + } +}) + +test('a webhook resolver failure is retryable, while a private destination stays blocked', async () => { + const config = testConfig({ notifyWebhookUrl: 'https://hooks.example.com/fledge' }) + const retry = webhookTransport(config, { + resolve: async () => { throw new Error('getaddrinfo EAI_AGAIN') }, + fetch: async () => new Response('', { status: 200 }), + }) + assert.equal((await retry.send(row('resolver-fail'))).state, 'retry') + + const blocked = webhookTransport(config, { resolve: async () => [{ address: '10.0.0.1', family: 4 }] }) + assert.equal((await blocked.send(row('resolver-private'))).state, 'blocked') +}) + // Rule the whole slice turns on: a timeout is not a failure to send, it is a // send whose outcome nobody knows. It must not be retried by the machine. test('a timeout outcome is unknown and is not claimed on the next pass', async () => { From ef59785a6dafea76ca7be247ba5ff136f0d3a545 Mon Sep 17 00:00:00 2001 From: Day Dreamer <87640074+HugoXK@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:00:34 +0800 Subject: [PATCH 2/3] fix: avoid the incomparable-type comparison in webhookErrorCode --- src/lib/webhook.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib/webhook.ts b/src/lib/webhook.ts index fee8930d..a4b6bebf 100644 --- a/src/lib/webhook.ts +++ b/src/lib/webhook.ts @@ -174,10 +174,10 @@ export class NotificationWebhookError extends Error { const AMBIGUOUS_CODES = new Set(['ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT']) function webhookErrorCode(error: unknown): string | undefined { - if (typeof error !== 'object' || error === null) return undefined + if (typeof error !== 'object' || !error) return undefined const record = error as { code?: unknown; cause?: unknown } if (typeof record.code === 'string') return record.code - if (typeof record.cause === 'object' && record.cause !== null) { + if (typeof record.cause === 'object' && record.cause) { const cause = record.cause as { code?: unknown } if (typeof cause.code === 'string') return cause.code } @@ -185,7 +185,7 @@ function webhookErrorCode(error: unknown): string | undefined { } function isAmbiguousWebhookFailure(error: unknown): boolean { - if (typeof error !== 'object' || error === null) return false + if (typeof error !== 'object' || !error) return false const record = error as { name?: unknown } if (record.name === 'TimeoutError' || record.name === 'AbortError') return true const code = webhookErrorCode(error) From 8974d005a409f2c0269832ba1b4be6488d21f9ac Mon Sep 17 00:00:00 2001 From: Day Dreamer <87640074+HugoXK@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:06:14 +0800 Subject: [PATCH 3/3] fix: use a record guard for the webhook error code --- src/lib/webhook.ts | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/src/lib/webhook.ts b/src/lib/webhook.ts index a4b6bebf..afe9578e 100644 --- a/src/lib/webhook.ts +++ b/src/lib/webhook.ts @@ -173,21 +173,20 @@ export class NotificationWebhookError extends Error { // Connection refused, DNS and TLS-setup failures are not. const AMBIGUOUS_CODES = new Set(['ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT']) +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null +} + function webhookErrorCode(error: unknown): string | undefined { - if (typeof error !== 'object' || !error) return undefined - const record = error as { code?: unknown; cause?: unknown } - if (typeof record.code === 'string') return record.code - if (typeof record.cause === 'object' && record.cause) { - const cause = record.cause as { code?: unknown } - if (typeof cause.code === 'string') return cause.code - } + if (!isRecord(error)) return undefined + if (typeof error.code === 'string') return error.code + if (isRecord(error.cause) && typeof error.cause.code === 'string') return error.cause.code return undefined } function isAmbiguousWebhookFailure(error: unknown): boolean { - if (typeof error !== 'object' || !error) return false - const record = error as { name?: unknown } - if (record.name === 'TimeoutError' || record.name === 'AbortError') return true + if (!isRecord(error)) return false + if (error.name === 'TimeoutError' || error.name === 'AbortError') return true const code = webhookErrorCode(error) return code !== undefined && AMBIGUOUS_CODES.has(code) }