fix(notifications): answer a failed channel test with its cause

The webhook, ntfy and email test routes turned every delivery failure into a bare 500, so the settings card could only say "Test failed" while the server knew the relay had answered 400. A failure at the other end, or on the way to it, is now a 502 with meta.errorCode, the upstream HTTP status or SMTP reply code, and for webhook and ntfy what the relay answered when that is short and holds no credential. The codes reuse the test card's vocabulary; upstream_rejected is new, for a relay that accepted the connection and refused the payload. The private-origin 422 is unchanged, and only a failure the server cannot name stays a 500.

The guard that pinned the bare 500 now asserts the opposite, with the reason in its name.

The admin fan-out test reports the same code and status per channel, and tests the webhook and email channels, which it used to list as an unknown channel type.

Refs #947

src/lib/notifications/__tests__/test-delivery-failure.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  codeForUpstreamStatus,
+  testFailureDetail,
+  testFailureSentence,
+} from "@/lib/notifications/test-delivery-failure";
+
+describe("codeForUpstreamStatus", () => {
+  it.each([
+    [400, "upstream_rejected"],
+    [401, "credentials_rejected"],
+    [403, "credentials_rejected"],
+    [404, "endpoint_not_found"],
+    [405, "upstream_rejected"],
+    [409, "upstream_rejected"],
+    [410, "endpoint_not_found"],
+    [413, "upstream_rejected"],
+    [415, "upstream_rejected"],
+    [422, "upstream_rejected"],
+    [429, "rate_limited"],
+    [500, "upstream_error"],
+    [502, "upstream_error"],
+    [301, "redirected"],
+    [308, "redirected"],
+  ])("%i → %s", (status, code) => {
+    expect(codeForUpstreamStatus(status)).toBe(code);
+  });
+});
+
+describe("testFailureDetail", () => {
+  it("prefers the HTTP status over any transport code", () => {
+    expect(
+      testFailureDetail({
+        ok: false,
+        statusCode: 400,
+        failureCode: "timeout",
+        upstreamBody: "bad",
+      }),
+    ).toEqual({
+      errorCode: "upstream_rejected",
+      upstreamStatus: 400,
+      upstreamBody: "bad",
+    });
+  });
+
+  it("uses the sender's code when there is no status", () => {
+    expect(
+      testFailureDetail({
+        ok: false,
+        failureCode: "upstream_rejected",
+        smtpCode: 550,
+      }),
+    ).toEqual({ errorCode: "upstream_rejected", smtpCode: 550 });
+  });
+
+  it("names nothing for an unnamed failure", () => {
+    expect(testFailureDetail({ ok: false, reason: "x" })).toEqual({});
+  });
+});
+
+describe("testFailureSentence", () => {
+  it("states the status, and falls back to a plain sentence for an unlisted code", () => {
+    expect(
+      testFailureSentence("The webhook", {
+        errorCode: "upstream_rejected",
+        upstreamStatus: 400,
+      }),
+    ).toBe("The webhook answered HTTP 400.");
+    expect(
+      testFailureSentence("The webhook", { errorCode: "something_new" }),
+    ).toBe("The webhook test failed.");
+  });
+});

src/lib/notifications/test-delivery-failure.ts

@@ -0,0 +1,109 @@
+import { apiError } from "@/lib/api-response";
+import { annotate } from "@/lib/logging/context";
+import type { SendOutcome } from "@/lib/notifications/retry-policy";
+
+/**
+ * The code for an HTTP status a relay answered, in the test card's
+ * vocabulary (`settings.testConnection.errors`). The same split the
+ * Nightscout and wearable test routes use, plus two the relays need: a 3xx
+ * (safeFetch never follows a redirect) and a 4xx that is not about the
+ * credentials or the path, where the relay accepted the connection and
+ * refused the payload.
+ */
+export function codeForUpstreamStatus(status: number): string {
+  if (status === 401 || status === 403) return "credentials_rejected";
+  if (status === 404 || status === 410) return "endpoint_not_found";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "upstream_error";
+  if (status >= 300 && status < 400) return "redirected";
+  return "upstream_rejected";
+}
+
+export interface TestFailureDetail {
+  /** Absent only for a failure the sender could not name: an internal fault. */
+  errorCode?: string;
+  upstreamStatus?: number;
+  smtpCode?: number;
+  upstreamBody?: string;
+}
+
+/** What a failed send outcome says, without the private-origin refusal. */
+export function testFailureDetail(result: SendOutcome): TestFailureDetail {
+  if (result.statusCode !== undefined) {
+    return {
+      errorCode: codeForUpstreamStatus(result.statusCode),
+      upstreamStatus: result.statusCode,
+      ...(result.upstreamBody ? { upstreamBody: result.upstreamBody } : {}),
+    };
+  }
+  if (result.failureCode) {
+    return {
+      errorCode: result.failureCode,
+      ...(result.smtpCode !== undefined ? { smtpCode: result.smtpCode } : {}),
+    };
+  }
+  return {};
+}
+
+/** One English sentence for the envelope's `error`, the card translates the code. */
+export function testFailureSentence(
+  label: string,
+  detail: TestFailureDetail,
+): string {
+  if (detail.upstreamStatus !== undefined) {
+    return `${label} answered HTTP ${detail.upstreamStatus}.`;
+  }
+  const smtp =
+    detail.smtpCode !== undefined ? ` (SMTP ${detail.smtpCode})` : "";
+  switch (detail.errorCode) {
+    case "timeout":
+      return `${label} did not answer in time.`;
+    case "connection_failed":
+      return `Could not connect to ${label}.`;
+    case "credentials_rejected":
+      return `${label} rejected the credentials${smtp}.`;
+    case "upstream_rejected":
+      return `${label} refused the message${smtp}.`;
+    case "upstream_error":
+      return `${label} reported a temporary error${smtp}.`;
+    default:
+      return `${label} test failed.`;
+  }
+}
+
+/**
+ * The test routes' answer to a failed send that was not a private-origin
+ * refusal (those keep their own 422 arm).
+ *
+ * The other end, or the way to it, failed: 502 with `meta.errorCode`, the
+ * upstream status or SMTP code, and what the relay said when it is short
+ * and holds no secret. A failure the sender could not name is an internal
+ * fault and stays a 500 with `fallbackMessage`.
+ */
+export function answerTestDeliveryFailure(
+  result: SendOutcome,
+  opts: {
+    channel: "webhook" | "ntfy" | "email";
+    label: string;
+    fallbackMessage: string;
+  },
+): Response {
+  const detail = testFailureDetail(result);
+  annotate({
+    action: { name: `settings.${opts.channel}.test` },
+    meta: {
+      success: false,
+      [`${opts.channel}_test_code`]: detail.errorCode ?? "internal",
+      ...(detail.upstreamStatus !== undefined
+        ? { [`${opts.channel}_test_status`]: detail.upstreamStatus }
+        : {}),
+      ...(detail.smtpCode !== undefined
+        ? { [`${opts.channel}_test_smtp_code`]: detail.smtpCode }
+        : {}),
+    },
+  });
+  if (!detail.errorCode) {
+    return apiError(opts.fallbackMessage, 500);
+  }
+  return apiError(testFailureSentence(opts.label, detail), 502, { ...detail });
+}

src/lib/openapi/routes/settings.ts

@@ -685,7 +685,7 @@ export const settingsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
       summary: "Send a test email to the saved recipient",
       description:
         "Fires one message through the operator's SMTP transport to the address saved on this account. Takes no body. Rate-limited 5 per 5 minutes per user.\n\n" +
-        "Refuses with 400 when the instance has no SMTP transport, when the account has no email channel, or when the channel carries no recipient — three distinguishable prose messages on one status. A transport failure is a 500.",
+        "Refuses with 400 when the instance has no SMTP transport, when the account has no email channel, or when the channel carries no recipient — three distinguishable prose messages on one status. A failure at the mail server or on the way to it is a 502 that names its cause; only a failure the server cannot name is a 500.",
       responses: {
         "200": {
           description:
@@ -697,6 +697,16 @@ export const settingsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
           },
         },
         ...stdResponses,
+        "502": {
+          description:
+            "The mail server, or the way to it, failed. `meta.errorCode` names the cause: `credentials_rejected` (the server refused the SMTP login), `upstream_rejected` (a permanent 5xx rejection, e.g. an unknown mailbox or relay denied), `upstream_error` (a temporary 4xx rejection), `timeout`, or `connection_failed`. `meta.smtpCode` carries the SMTP reply code when the mail server sent one.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
+        "500": {
+          description:
+            "The send failed in a way the server could not name. An internal fault, not a statement about the mail server.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
       },
     },
   },
@@ -705,7 +715,7 @@ export const settingsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
       tags: ["Notifications"],
       summary: "Send a test message to the saved ntfy topic",
       description:
-        "Publishes one message to the account's configured ntfy server and topic. Takes no body. Rate-limited 5 per 5 minutes per user. Refuses with 400 when no ntfy channel is saved or when the saved config is missing a server URL or topic; a publish failure is a 500. A server on a private network is refused with 422 and `meta.errorCode` = `private_origin_not_approved` unless the operator listed its exact origin in `NOTIFICATION_PRIVATE_ORIGINS`; the test and the scheduled delivery take the same decision.",
+        "Publishes one message to the account's configured ntfy server and topic. Takes no body. Rate-limited 5 per 5 minutes per user. Refuses with 400 when no ntfy channel is saved or when the saved config is missing a server URL or topic. A failure at the ntfy server or on the way to it is a 502 that carries the upstream status and, when safe, what the server answered; only a failure the server cannot name is a 500. A server on a private network is refused with 422 and `meta.errorCode` = `private_origin_not_approved` unless the operator listed its exact origin in `NOTIFICATION_PRIVATE_ORIGINS`; the test and the scheduled delivery take the same decision.",
       responses: {
         "200": {
           description:
@@ -717,6 +727,16 @@ export const settingsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
           },
         },
         ...stdResponses,
+        "502": {
+          description:
+            "The ntfy server, or the way to it, failed. `meta.errorCode` names the cause: `upstream_rejected` (the other end refused the payload, e.g. 400/409/415/422), `credentials_rejected` (401/403), `endpoint_not_found` (404/410), `rate_limited` (429), `upstream_error` (5xx), `redirected` (3xx, never followed), `timeout`, or `connection_failed`. `meta.upstreamStatus` carries the HTTP status whenever one arrived, and `meta.upstreamBody` up to 200 characters of what the other end answered, with control characters removed; it is omitted when the body was empty or could carry a credential (a token-shaped string, or the saved header value, auth token, topic or URL token).",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
+        "500": {
+          description:
+            "The send failed in a way the server could not name. An internal fault, not a statement about the ntfy server.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
         "422": {
           description:
             "The saved server is on a private network the operator has not approved (`meta.errorCode` = `private_origin_not_approved`), or is a link-local, metadata or unspecified address that no grant can open (`private_origin_not_grantable`). The resolved address is never echoed.",
@@ -751,7 +771,7 @@ export const settingsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
       tags: ["Notifications"],
       summary: "Send a test payload to the saved webhook",
       description:
-        "Posts one payload to the account's configured webhook URL. Takes no body. Rate-limited 5 per 5 minutes per user. Refuses with 400 when no webhook channel is saved or the saved config has no URL; a delivery failure is a 500. The URL was checked against the SSRF floor when it was saved, so a test cannot be used to reach an internal host. A URL on a private network is refused with 422 and `meta.errorCode` = `private_origin_not_approved` unless the operator listed its exact origin in `NOTIFICATION_PRIVATE_ORIGINS`; the test and the scheduled delivery take the same decision.",
+        "Posts one payload to the account's configured webhook URL. Takes no body. Rate-limited 5 per 5 minutes per user. Refuses with 400 when no webhook channel is saved or the saved config has no URL. A failure at the relay or on the way to it is a 502 that carries the upstream status and, when safe, what the relay answered; only a failure the server cannot name is a 500. The URL was checked against the SSRF floor when it was saved, so a test cannot be used to reach an internal host. A URL on a private network is refused with 422 and `meta.errorCode` = `private_origin_not_approved` unless the operator listed its exact origin in `NOTIFICATION_PRIVATE_ORIGINS`; the test and the scheduled delivery take the same decision.",
       responses: {
         "200": {
           description:
@@ -763,6 +783,16 @@ export const settingsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
           },
         },
         ...stdResponses,
+        "502": {
+          description:
+            "The relay, or the way to it, failed. `meta.errorCode` names the cause: `upstream_rejected` (the other end refused the payload, e.g. 400/409/415/422), `credentials_rejected` (401/403), `endpoint_not_found` (404/410), `rate_limited` (429), `upstream_error` (5xx), `redirected` (3xx, never followed), `timeout`, or `connection_failed`. `meta.upstreamStatus` carries the HTTP status whenever one arrived, and `meta.upstreamBody` up to 200 characters of what the other end answered, with control characters removed; it is omitted when the body was empty or could carry a credential (a token-shaped string, or the saved header value, auth token, topic or URL token).",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
+        "500": {
+          description:
+            "The send failed in a way the server could not name. An internal fault, not a statement about the relay.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
         "422": {
           description:
             "The saved URL is on a private network the operator has not approved (`meta.errorCode` = `private_origin_not_approved`), or is a link-local, metadata or unspecified address that no grant can open (`private_origin_not_grantable`). The resolved address is never echoed.",