Add diagnostics to WebFinger lookups

CHANGES.md

@@ -47,11 +47,17 @@ To be released.
     every declared size instead of only the first, so an icon offering a large
     size is no longer discarded because its smallest size is too small.
     [[#893], [#1187] by Lee Jeongmin\]
+ -  Changed the `fedify webfinger` command's error message when a lookup
+    fails.  It now explains why—resource not found, a network error, a
+    malformed response, or an unexpected server error—instead of always
+    reporting the resource as not found.  [[#897], [#1296] by Jae-Hyuk-Jang\]
 
 [#893]: https://github.com/fedify-dev/fedify/issues/893
+[#897]: https://github.com/fedify-dev/fedify/issues/897
 [#901]: https://github.com/fedify-dev/fedify/issues/901
 [#1187]: https://github.com/fedify-dev/fedify/pull/1187
 [#1265]: https://github.com/fedify-dev/fedify/pull/1265
+[#1296]: https://github.com/fedify-dev/fedify/pull/1296
 
 ### @fedify/debugger
 
@@ -182,6 +188,15 @@ To be released.
 [#1210]: https://github.com/fedify-dev/fedify/issues/1210
 [#1215]: https://github.com/fedify-dev/fedify/pull/1215
 
+### @fedify/webfinger
+
+ -  Added a `withDiagnostics` option to `lookupWebFinger()`.  When turned on,
+    the function returns an object describing why the lookup failed—a
+    network error, a malformed response, an unexpected server error, or the
+    resource genuinely not existing—instead of returning `null` for every
+    failure.  `Context.lookupWebFinger()` does not support this option.
+    [[#897], [#1296] by Jae-Hyuk-Jang\]
+
 
 Version 2.4.4
 -------------

changes.d/cli/webfinger-lookup-error-detail.md

@@ -0,0 +1,9 @@
+---
+links:
+  '#1296': https://github.com/fedify-dev/fedify/pull/1296
+  '#897': https://github.com/fedify-dev/fedify/issues/897
+---
+ -  Changed the `fedify webfinger` command's error message when a lookup
+    fails.  It now explains why—resource not found, a network error, a
+    malformed response, or an unexpected server error—instead of always
+    reporting the resource as not found.  [[#897], [#1296] by Jae-Hyuk-Jang]

changes.d/webfinger/lookup-diagnostics.md

@@ -0,0 +1,11 @@
+---
+links:
+  '#1296': https://github.com/fedify-dev/fedify/pull/1296
+  '#897': https://github.com/fedify-dev/fedify/issues/897
+---
+ -  Added a `withDiagnostics` option to `lookupWebFinger()`.  When turned on,
+    the function returns an object describing why the lookup failed—a
+    network error, a malformed response, an unexpected server error, or the
+    resource genuinely not existing—instead of returning `null` for every
+    failure.  `Context.lookupWebFinger()` does not support this option.
+    [[#897], [#1296] by Jae-Hyuk-Jang]

docs/manual/webfinger.md

@@ -393,6 +393,65 @@ The available options are:
 `signal`
 :   An `AbortSignal` for cancelling the request.
 
+`withDiagnostics`
+:   *Since Fedify 2.5.0.*  Whether to return a `WebFingerLookupOutcome`
+    describing why the lookup failed, instead of collapsing every failure
+    into `null`.  Turned off by default.  See
+    [*Diagnosing a failed lookup*](#diagnosing-a-failed-lookup) below.
+
+### Diagnosing a failed lookup
+
+*This option is available since Fedify 2.5.0.*
+
+By default, `lookupWebFinger()` returns `null` for every kind of failure:
+a response saying the resource doesn't exist looks the same as a network
+error or a malformed response.  Pass `withDiagnostics: true` to get back a
+`WebFingerLookupOutcome` instead, which explains why the lookup failed:
+
+~~~~ typescript twoslash
+import { lookupWebFinger } from "@fedify/webfinger";
+
+const outcome = await lookupWebFinger("acct:alice@example.com", {
+  withDiagnostics: true,
+});
+
+if (outcome.resource != null) {
+  console.log("Found:", outcome.resource.subject);
+} else {
+  console.log("Failed:", outcome.result);
+}
+~~~~
+
+The `result` field is one of:
+
+`"found"`
+:   The lookup returned a resource descriptor.
+
+`"not_found"`
+:   The remote responded with `404 Not Found` or `410 Gone`.
+
+`"invalid"`
+:   The remote responded with content Fedify could not parse into a
+    resource descriptor, or the queried resource was malformed.
+
+`"network_error"`
+:   No HTTP response was received, e.g., the URL was rejected as a private
+    address, or the request was aborted.
+
+`"error"`
+:   The remote responded with an unexpected non-2xx HTTP response.
+
+`withDiagnostics: true` classifies the failures listed above into a
+`WebFingerLookupOutcome`, but it does not turn every failure into one.
+An error `lookupWebFinger()` does not recognize—for example, one while
+reading the response body—still rejects the returned promise, so
+callers must keep handling a rejected promise even with this option
+turned on.
+
+> [!NOTE]
+> `~Context.lookupWebFinger()` does not support `withDiagnostics`; it always
+> returns the resource descriptor or `null`.
+
 > [!TIP]
 > Use `@fedify/webfinger` when you need a lightweight WebFinger client without
 > the full Fedify framework.  If you're already using Fedify, prefer

packages/cli/src/portable.test.ts

@@ -36,6 +36,7 @@ import {
 import { matchesActor } from "./utils.ts";
 import { linksToActor, lookupPortableWebFinger } from "./webfinger/action.ts";
 import { webFingerCommand } from "./webfinger/command.ts";
+import { WebFingerLookupError } from "./webfinger/error.ts";
 
 const keyPair = await crypto.subtle.generateKey("Ed25519", true, [
   "sign",
@@ -901,6 +902,35 @@ test("lookupPortableWebFinger() uses the first gateway of the actor", async () =
   }
 });
 
+test("lookupPortableWebFinger() preserves WebFinger diagnostics", async () => {
+  const gateway = await startGateway();
+  fetchMock.spyGlobal();
+  const resource = `ap://${did}/actor?@gateway=${
+    encodeURIComponent(gateway.url.origin)
+  }`;
+  fetchMock.get(`begin:https://${gateway.url.host}/.well-known/webfinger`, {
+    status: 500,
+  });
+  try {
+    await serveFixtures(gateway);
+    await assert.rejects(
+      lookupPortableWebFinger({
+        resource,
+        allowPrivateAddresses: true,
+      }),
+      (error: unknown) => {
+        assert.ok(error instanceof WebFingerLookupError);
+        assert.equal(error.result, "error");
+        return true;
+      },
+    );
+  } finally {
+    fetchMock.unmockGlobal();
+    fetchMock.removeRoutes();
+    await gateway.close();
+  }
+});
+
 test("linksToActor() checks the first ActivityStreams self link", () => {
   const actorId = portableId("/actor");
   const compatible =

packages/cli/src/webfinger/action.ts

@@ -22,6 +22,7 @@ import {
   NotFoundError,
   PortableActorError,
   UnlinkedPortableActorError,
+  WebFingerLookupError,
 } from "./error.ts";
 import { convertUrlIfHandle } from "./lib.ts";
 
@@ -96,11 +97,15 @@ export async function lookupSingleWebFinger(
   options: LookupSingleWebFingerOptions,
 ): Promise<ResourceDescriptor> {
   const url = convertUrlIfHandle(options.resource);
-  const webFinger = await lookupWebFinger(
-    url,
-    getLookupWebFingerOptions(options),
-  ) ?? new NotFoundError(options.resource).throw();
-  return webFinger;
+  const outcome = await lookupWebFinger(url, {
+    ...getLookupWebFingerOptions(options),
+    withDiagnostics: true,
+  });
+  return outcome.resource ?? (
+    outcome.result === "not_found"
+      ? new NotFoundError(options.resource).throw()
+      : new WebFingerLookupError(options.resource, outcome.result).throw()
+  );
 }
 
 /**
@@ -119,6 +124,9 @@ export async function lookupSingleWebFinger(
  * @throws {PortableActorError} If the actor cannot be looked up, or does
  *                              not have a WebFinger address.
  * @throws {NotFoundError} If the WebFinger address is not found.
+ * @throws {WebFingerLookupError} If the WebFinger lookup failed for another
+ *                                reason, such as a network failure or a
+ *                                malformed response.
  */
 export async function lookupPortableWebFinger(
   options: LookupSingleWebFingerOptions,
@@ -168,10 +176,15 @@ export async function lookupPortableWebFinger(
     );
   }
   const address = `acct:${username}@${gateway.host}`;
-  const descriptor = await lookupWebFinger(
-    address,
-    getLookupWebFingerOptions(options),
-  ) ?? new NotFoundError(address).throw();
+  const outcome = await lookupWebFinger(address, {
+    ...getLookupWebFingerOptions(options),
+    withDiagnostics: true,
+  });
+  const descriptor = outcome.resource ?? (
+    outcome.result === "not_found"
+      ? new NotFoundError(address).throw()
+      : new WebFingerLookupError(address, outcome.result).throw()
+  );
   return { descriptor, address, actorId: actor.id };
 }
 

packages/cli/src/webfinger/error.ts

@@ -1,4 +1,5 @@
 import { type Message, message } from "@optique/core";
+import type { WebFingerLookupResult } from "@fedify/webfinger";
 
 /**
  * Generates a user-friendly error message based on the type of error
@@ -16,6 +17,12 @@ export const getErrorMessage = (resource: string, error: unknown): Message =>
     ? message`${error.address} does not link back to the portable actor ${error.actorId}, so it is not verified to be the actor's WebFinger address:`
     : error instanceof NotFoundError
     ? message`Resource not found: ${error.resource}`
+    : error instanceof WebFingerLookupError
+    ? error.result === "network_error"
+      ? message`Failed to look up WebFinger for ${error.resource}: a network error occurred.`
+      : error.result === "invalid"
+      ? message`Failed to look up WebFinger for ${error.resource}: the server returned a response Fedify could not understand.`
+      : message`Failed to look up WebFinger for ${error.resource}: the server returned an unexpected error.`
     : error instanceof Error
     ? message`Failed to look up WebFinger for ${resource}: ${error.message}`
     : message`Failed to look up WebFinger for ${resource}: ${String(error)}`;
@@ -50,6 +57,26 @@ export class NotFoundError extends Error {
   }
 }
 
+/**
+ * Custom error class for a WebFinger lookup that failed for a reason other
+ * than the resource simply not existing, such as a network failure, a
+ * server error, or a response Fedify could not parse.
+ * @param resource The resource that could not be looked up.
+ * @param result Why the lookup failed.
+ * @extends {Error}
+ */
+export class WebFingerLookupError extends Error {
+  constructor(public resource: string, public result: WebFingerLookupResult) {
+    super(
+      `Failed to look up WebFinger for ${resource}: result was "${result}".`,
+    );
+    this.name = "WebFingerLookupError";
+  }
+  throw(): never {
+    throw this;
+  }
+}
+
 /**
  * Custom error class for [FEP-ef61] portable actors whose WebFinger address
  * cannot be determined.

packages/cli/src/webfinger/mod.test.ts

@@ -1,3 +1,4 @@
+import { formatMessage } from "@optique/core/message";
 import { parse } from "@optique/core/parser";
 import { run } from "@optique/run";
 import assert from "node:assert/strict";
@@ -6,6 +7,11 @@ import test from "node:test";
 import { type Config, configContext } from "../config.ts";
 import runWebFinger, { lookupSingleWebFinger } from "./action.ts";
 import { webFingerCommand } from "./command.ts";
+import {
+  getErrorMessage,
+  NotFoundError,
+  WebFingerLookupError,
+} from "./error.ts";
 
 const COMMAND = "webfinger";
 const USER_AGENT = "MyUserAgent/1.0";
@@ -236,3 +242,83 @@ test("Test lookupSingleWebFinger", async (): Promise<void> => {
     globalThis.fetch = originalFetch;
   }
 });
+
+// ----------------------------------------------------------------------
+// FIX FOR ISSUE #897 – DIFFERENTIATE WHY A WEBFINGER LOOKUP FAILED
+// ----------------------------------------------------------------------
+
+for (
+  const { name, response, expectedResult, expectedText } of [
+    {
+      name: "404 is still reported as not found",
+      response: () => new Response(null, { status: 404 }),
+      expectedResult: null,
+      expectedText: 'Resource not found: "acct:alice@example.com"',
+    },
+    {
+      name: "a server error is distinguished from not found",
+      response: () => new Response(null, { status: 500 }),
+      expectedResult: "error",
+      expectedText: "the server returned an unexpected error",
+    },
+    {
+      name: "a malformed response is distinguished from not found",
+      response: () => new Response("not json", { status: 200 }),
+      expectedResult: "invalid",
+      expectedText:
+        "the server returned a response Fedify could not understand",
+    },
+  ] satisfies {
+    name: string;
+    response: () => Response;
+    expectedResult: "error" | "invalid" | null;
+    expectedText: string;
+  }[]
+) {
+  test(`Test lookupSingleWebFinger - ${name}`, async () => {
+    const resource = "acct:alice@example.com";
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.resolve(response());
+    try {
+      await assert.rejects(
+        () => lookupSingleWebFinger({ resource, allowPrivateAddresses: true }),
+        (error: unknown) => {
+          if (expectedResult == null) {
+            assert.ok(error instanceof NotFoundError);
+          } else {
+            assert.ok(error instanceof WebFingerLookupError);
+            assert.strictEqual(error.result, expectedResult);
+          }
+          const text = formatMessage(getErrorMessage(resource, error));
+          assert.ok(text.includes(expectedText), text);
+          return true;
+        },
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+}
+
+test("Test lookupSingleWebFinger - a network failure is distinguished from not found", async () => {
+  const resource = "acct:alice@example.com";
+  const originalFetch = globalThis.fetch;
+  // Mocked lookups skip DNS by passing allowPrivateAddresses, same as the
+  // upstream fix for issue #1273 (0bece1f8e): a real DNS lookup for a public
+  // hostname should not be part of a unit test.
+  globalThis.fetch = () => Promise.reject(new TypeError("network down"));
+  try {
+    await assert.rejects(
+      () => lookupSingleWebFinger({ resource, allowPrivateAddresses: true }),
+      (error: unknown) => {
+        assert.ok(error instanceof WebFingerLookupError);
+        assert.strictEqual(error.result, "network_error");
+        const text = formatMessage(getErrorMessage(resource, error));
+        assert.ok(text.includes("a network error occurred"), text);
+        return true;
+      },
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

packages/fedify/src/federation/context.ts

@@ -710,7 +710,9 @@ export interface Context<TContextData> {
    * Looks up a WebFinger resource.
    *
    * It's almost the same as the {@link lookupWebFinger} function, but it uses
-   * the context's configuration by default.
+   * the context's configuration by default.  Unlike {@link lookupWebFinger},
+   * it does not support the `withDiagnostics` option; it always returns the
+   * resource descriptor or `null`.
    *
    * @param resource The resource URL to look up.
    * @param options Extra options for looking up the resource.