@fedify/vocab-runtime 2.3.8 → 2.3.9

package/dist/tests/url.test.cjs

@@ -1,8 +1,31 @@
 require("./chunk-C2EiDwsr.cjs");
-const require_url = require("./url-BbEC9H_R.cjs");
+const require_url = require("./url-4PAkYhZC.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/url.test.ts
+(0, node_test.test)("UrlError reason is independent of its cause", () => {
+	const cause = /* @__PURE__ */ new Error("Underlying failure");
+	(0, node_assert.strictEqual)(new require_url.UrlError("Rejected URL").reason, "disallowed");
+	const disallowedError = new require_url.UrlError("Rejected URL", { cause });
+	(0, node_assert.strictEqual)(disallowedError.reason, "disallowed");
+	(0, node_assert.strictEqual)(disallowedError.cause, cause);
+	const dnsError = new require_url.UrlError("Lookup failed", {
+		reason: "dns",
+		cause
+	});
+	(0, node_assert.strictEqual)(dnsError.reason, "dns");
+	(0, node_assert.strictEqual)(dnsError.cause, cause);
+});
+(0, node_test.test)("validatePublicUrl() classifies disallowed URLs", async () => {
+	for (const url of [
+		"ftp://example.com",
+		"https://localhost",
+		"https://127.0.0.1"
+	]) await (0, node_assert.rejects)(() => require_url.validatePublicUrl(url), {
+		name: "UrlError",
+		reason: "disallowed"
+	});
+});
 (0, node_test.test)("validatePublicUrl()", async () => {
 	await (0, node_assert.rejects)(() => require_url.validatePublicUrl("ftp://localhost"), require_url.UrlError);
 	await (0, node_assert.rejects)(() => require_url.validatePublicUrl("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="), require_url.UrlError);
@@ -52,11 +75,21 @@ let node_assert = require("node:assert");
 	}, {
 		address: "127.0.0.1",
 		family: 4
-	}]), require_url.UrlError);
+	}]), {
+		name: "UrlError",
+		reason: "disallowed"
+	});
 	(0, node_assert.throws)(() => require_url.validateLookupAddresses([{
 		address: "app-host.example.net.",
 		family: 4
-	}]), require_url.UrlError);
+	}]), {
+		name: "UrlError",
+		reason: "dns"
+	});
+	(0, node_assert.throws)(() => require_url.validateLookupAddresses([]), {
+		name: "UrlError",
+		reason: "dns"
+	});
 });
 (0, node_test.test)("isValidPublicIPv4Address()", () => {
 	(0, node_assert.ok)(require_url.isValidPublicIPv4Address("8.8.8.8"));

package/dist/tests/url.test.mjs

@@ -1,7 +1,30 @@
-import { a as validateLookupAddresses, i as isValidPublicIPv6Address, n as expandIPv6Address, o as validatePublicUrl, r as isValidPublicIPv4Address, t as UrlError } from "./url-BBfduh6o.mjs";
+import { a as validateLookupAddresses, i as isValidPublicIPv6Address, n as expandIPv6Address, o as validatePublicUrl, r as isValidPublicIPv4Address, t as UrlError } from "./url-3fyJuqC0.mjs";
 import { test } from "node:test";
-import { deepStrictEqual, ok, rejects, throws } from "node:assert";
+import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert";
 //#region src/url.test.ts
+test("UrlError reason is independent of its cause", () => {
+	const cause = /* @__PURE__ */ new Error("Underlying failure");
+	strictEqual(new UrlError("Rejected URL").reason, "disallowed");
+	const disallowedError = new UrlError("Rejected URL", { cause });
+	strictEqual(disallowedError.reason, "disallowed");
+	strictEqual(disallowedError.cause, cause);
+	const dnsError = new UrlError("Lookup failed", {
+		reason: "dns",
+		cause
+	});
+	strictEqual(dnsError.reason, "dns");
+	strictEqual(dnsError.cause, cause);
+});
+test("validatePublicUrl() classifies disallowed URLs", async () => {
+	for (const url of [
+		"ftp://example.com",
+		"https://localhost",
+		"https://127.0.0.1"
+	]) await rejects(() => validatePublicUrl(url), {
+		name: "UrlError",
+		reason: "disallowed"
+	});
+});
 test("validatePublicUrl()", async () => {
 	await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
 	await rejects(() => validatePublicUrl("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="), UrlError);
@@ -51,11 +74,21 @@ test("validateLookupAddresses() rejects unsafe or CNAME-only Cloudflare Workers
 	}, {
 		address: "127.0.0.1",
 		family: 4
-	}]), UrlError);
+	}]), {
+		name: "UrlError",
+		reason: "disallowed"
+	});
 	throws(() => validateLookupAddresses([{
 		address: "app-host.example.net.",
 		family: 4
-	}]), UrlError);
+	}]), {
+		name: "UrlError",
+		reason: "dns"
+	});
+	throws(() => validateLookupAddresses([]), {
+		name: "UrlError",
+		reason: "dns"
+	});
 });
 test("isValidPublicIPv4Address()", () => {
 	ok(isValidPublicIPv4Address("8.8.8.8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.3.8",
+  "version": "2.3.9",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

package/src/contexts/fep-7aa9.json

@@ -0,0 +1,24 @@
+{
+  "@context": {
+    "FeaturedCollection": "https://w3id.org/fep/7aa9#FeaturedCollection",
+    "FeaturedItem": "https://w3id.org/fep/7aa9#FeaturedItem",
+    "FeatureRequest": "https://w3id.org/fep/7aa9#FeatureRequest",
+    "FeatureAuthorization": "https://w3id.org/fep/7aa9#FeatureAuthorization",
+    "topic": {
+      "@id": "https://w3id.org/fep/7aa9#topic",
+      "@type": "@id"
+    },
+    "featuredObject": {
+      "@id": "https://w3id.org/fep/7aa9#featuredObject",
+      "@type": "@id"
+    },
+    "canFeature": {
+      "@id": "https://w3id.org/fep/7aa9#canFeature",
+      "@type": "@id"
+    },
+    "featureAuthorization": {
+      "@id": "https://w3id.org/fep/7aa9#featureAuthorization",
+      "@type": "@id"
+    }
+  }
+}

package/src/contexts.ts

@@ -8,6 +8,7 @@ import activitystreams from "./contexts/activitystreams.json" with {
 import cidV1Context from "./contexts/cid-v1.json" with { type: "json" };
 import didV1 from "./contexts/did-v1.json" with { type: "json" };
 import fep5711 from "./contexts/fep-5711.json" with { type: "json" };
+import fep7aa9 from "./contexts/fep-7aa9.json" with { type: "json" };
 import fepEf61 from "./contexts/fep-ef61.json" with { type: "json" };
 import gotosocial from "./contexts/gotosocial.json" with { type: "json" };
 import identityV1 from "./contexts/identity-v1.json" with { type: "json" };
@@ -56,6 +57,13 @@ const preloadedContexts: Record<string, unknown> = {
   //      https://github.com/fedify-dev/fedify/issues/982
   "https://w3id.org/fep/ef61": fepEf61,
 
+  // The FEP-7aa9 context is hosted on Codeberg Pages, whose outages can
+  // prevent actor documents from being parsed.  Resolve it locally so that
+  // parsing does not depend on the remote context server's availability.
+  // See: https://w3id.org/fep/7aa9
+  //      https://github.com/fedify-dev/fedify/issues/1078
+  "https://w3id.org/fep/7aa9": fep7aa9,
+
   // Lemmy's context document is served as application/json without the JSON-LD
   // context Link header.  The default document loader treats that as a regular
   // JSON response instead of a JSON-LD context, so every Lemmy activity that

package/src/docloader.test.ts

@@ -1,5 +1,7 @@
+import { configure, type LogRecord, reset } from "@logtape/logtape";
 import fetchMock from "fetch-mock";
 import { deepStrictEqual, ok, rejects } from "node:assert";
+import dns from "node:dns/promises";
 import { test } from "node:test";
 import { createServer } from "node:http";
 import { gzipSync } from "node:zlib";
@@ -336,6 +338,43 @@ test("getDocumentLoader()", async (t) => {
     });
   });
 
+  // A Codeberg Pages outage must not prevent loading the FEP-7aa9 context.
+  // See: https://github.com/fedify-dev/fedify/issues/1078
+  fetchMock.get("https://w3id.org/fep/7aa9", { status: 502 });
+  await t.test("preloaded FEP-7aa9 context", async () => {
+    const url = "https://w3id.org/fep/7aa9";
+    deepStrictEqual(await fetchDocumentLoader(url), {
+      contextUrl: null,
+      documentUrl: url,
+      document: {
+        "@context": {
+          "FeaturedCollection": "https://w3id.org/fep/7aa9#FeaturedCollection",
+          "FeaturedItem": "https://w3id.org/fep/7aa9#FeaturedItem",
+          "FeatureRequest": "https://w3id.org/fep/7aa9#FeatureRequest",
+          "FeatureAuthorization":
+            "https://w3id.org/fep/7aa9#FeatureAuthorization",
+          "topic": {
+            "@id": "https://w3id.org/fep/7aa9#topic",
+            "@type": "@id",
+          },
+          "featuredObject": {
+            "@id": "https://w3id.org/fep/7aa9#featuredObject",
+            "@type": "@id",
+          },
+          "canFeature": {
+            "@id": "https://w3id.org/fep/7aa9#canFeature",
+            "@type": "@id",
+          },
+          "featureAuthorization": {
+            "@id": "https://w3id.org/fep/7aa9#featureAuthorization",
+            "@type": "@id",
+          },
+        },
+      },
+    });
+    deepStrictEqual(fetchMock.callHistory.calls(url).length, 0);
+  });
+
   await t.test("deny non-HTTP/HTTPS", async () => {
     await rejects(
       () => fetchDocumentLoader("ftp://localhost"),
@@ -641,3 +680,271 @@ test("getRemoteDocument() bounds JSON by default", async () => {
   deepStrictEqual(canceled, true);
   deepStrictEqual(pulls, 257);
 });
+
+test("getDocumentLoader() logs DNS failures as such", async (t) => {
+  // The validator skips DNS when Deno has no network permission.  Checked
+  // here rather than with top-level await, which the CommonJS build rejects.
+  if (
+    "Deno" in globalThis &&
+    (await Deno.permissions.query({ name: "net" })).state !== "granted"
+  ) {
+    t.skip("requires the net permission");
+    return;
+  }
+  const loader = getDocumentLoader();
+  for (const result of ["throws", "empty", "private"] as const) {
+    await t.test(result, async () => {
+      // Stubbing works only because url.ts uses the default node:dns/promises
+      // import; see the FIXME there.
+      const originalLookup = dns.lookup;
+      dns.lookup = (() =>
+        result === "throws"
+          ? Promise.reject(new Error("Resolver unavailable"))
+          : Promise.resolve(
+            result === "empty" ? [] : [{ address: "127.0.0.1", family: 4 }],
+          )) as typeof dns.lookup;
+      const records: LogRecord[] = [];
+      await configure({
+        sinks: {
+          buffer: (record) =>
+            records.push(record),
+        },
+        loggers: [
+          { category: "fedify", sinks: ["buffer"], lowestLevel: "debug" },
+          { category: ["logtape", "meta"], sinks: [] },
+        ],
+        reset: true,
+      });
+      try {
+        const url = "https://dns-failure.invalid/object";
+        let error: unknown;
+        await rejects(() => loader(url), (e) => {
+          error = e;
+          return true;
+        });
+        ok(error instanceof UrlError);
+        deepStrictEqual(
+          error.reason,
+          result === "private" ? "disallowed" : "dns",
+        );
+        deepStrictEqual(
+          records.map((r) => [r.level, r.rawMessage, r.properties.url]),
+          [
+            result === "private"
+              ? ["error", "Disallowed private URL: {url}", url]
+              : ["debug", "DNS lookup failed for {url}", url],
+          ],
+        );
+        ok(records[0].properties.error === error);
+      } finally {
+        await reset();
+        dns.lookup = originalLookup;
+      }
+    });
+  }
+});
+
+test("getDocumentLoader() bounds alternate document chains", async (t) => {
+  const base = "https://example.com/alternate-chain/";
+  const loader = getDocumentLoader({ allowPrivateAddress: true });
+  for (const mode of ["header", "html", "mixed"] as const) {
+    for (const hops of [20, 21]) {
+      await t.test(`${mode}: ${hops} hops`, async () => {
+        fetchMock.mockGlobal();
+        let requests = 0;
+        fetchMock.get(`begin:${base}`, ({ url }) => {
+          requests++;
+          const index = Number(new URL(url).pathname.split("/").at(-1));
+          // Keep the unpatched regression bounded too.
+          if (index === hops || requests > 30) {
+            return Response.json({ done: true });
+          }
+          const next = `${base}${index + 1}`;
+          if (mode === "mixed" && index % 2 === 1) {
+            return Response.redirect(next, 302);
+          }
+          return alternate(next, mode === "html");
+        });
+        try {
+          if (hops === 20) {
+            deepStrictEqual((await loader(`${base}0`)).document, {
+              done: true,
+            });
+          } else {
+            await rejects(loader(`${base}0`), (error: unknown) => {
+              ok(error instanceof FetchError);
+              ok(error.message.includes("Too many redirections (21)"));
+              return true;
+            });
+          }
+          deepStrictEqual(requests, 21);
+        } finally {
+          fetchMock.hardReset();
+        }
+      });
+    }
+  }
+
+  for (
+    const mode of [
+      "header",
+      "html",
+      "alternate-redirect",
+      "redirect-alternate",
+      "redirect-intermediate",
+    ]
+  ) {
+    await t.test(`${mode}: cycle`, async () => {
+      fetchMock.mockGlobal();
+      let requests = 0;
+      fetchMock.get(`begin:${base}`, ({ url }) => {
+        requests++;
+        if (requests > 30) return Response.json({ stopped: true });
+        const index = Number(new URL(url).pathname.split("/").at(-1));
+        const next = `${base}${
+          mode === "redirect-intermediate"
+            ? (index === 0 ? 1 : index === 1 ? 2 : 1)
+            : 1 - index
+        }`;
+        if (
+          (mode === "alternate-redirect" && index === 1) ||
+          ((mode === "redirect-alternate" ||
+            mode === "redirect-intermediate") && index === 0)
+        ) {
+          return Response.redirect(next, 302);
+        }
+        return alternate(next, mode === "html");
+      });
+      try {
+        await rejects(loader(`${base}0`), (error: unknown) => {
+          ok(error instanceof FetchError);
+          ok(error.message.includes("Redirect loop detected:"));
+          return true;
+        });
+        deepStrictEqual(requests, mode === "redirect-intermediate" ? 3 : 2);
+      } finally {
+        fetchMock.hardReset();
+      }
+    });
+  }
+
+  await t.test("alternate followed by 20 redirects shares the limit", async () => {
+    fetchMock.mockGlobal();
+    let requests = 0;
+    fetchMock.get(`begin:${base}`, ({ url }) => {
+      requests++;
+      const index = Number(new URL(url).pathname.split("/").at(-1));
+      if (index === 21) return Response.json({ done: true });
+      return index === 0
+        ? alternate(`${base}1`, false)
+        : Response.redirect(`${base}${index + 1}`, 302);
+    });
+    try {
+      await rejects(loader(`${base}0`), (error: unknown) => {
+        ok(error instanceof FetchError);
+        ok(error.message.includes("Too many redirections (21)"));
+        return true;
+      });
+      deepStrictEqual(requests, 21);
+    } finally {
+      fetchMock.hardReset();
+    }
+  });
+
+  await t.test("relative alternate after redirect and isolated calls", async () => {
+    fetchMock.mockGlobal();
+    fetchMock.get(`${base}start`, Response.redirect(`${base}html`, 302));
+    fetchMock.get(`${base}html`, alternate("./document", true));
+    fetchMock.get(`${base}document`, Response.json({ done: true }));
+    try {
+      for (let i = 0; i < 2; i++) {
+        const results = await Promise.all([
+          loader(`${base}start`),
+          loader(`${base}start`),
+        ]);
+        for (const result of results) {
+          deepStrictEqual(result.document, { done: true });
+          deepStrictEqual(result.documentUrl, `${base}document`);
+        }
+      }
+    } finally {
+      fetchMock.hardReset();
+    }
+  });
+
+  function alternate(next: string, html: boolean): Response {
+    return html
+      ? new Response(
+        `<link rel="alternate" type="application/activity+json" href="${next}">`,
+        {
+          headers: { "Content-Type": "text/html" },
+        },
+      )
+      : new Response("not JSON", {
+        headers: {
+          "Content-Type": "text/plain",
+          Link: `<${next}>; rel="alternate"; type="application/activity+json"`,
+        },
+      });
+  }
+});
+
+test("getDocumentLoader() preserves cancellation across alternates", async (t) => {
+  const base = "https://example.com/alternate-abort/";
+  const loader = getDocumentLoader({ allowPrivateAddress: true });
+  for (const html of [false, true]) {
+    await t.test(html ? "HTML" : "Link header", async () => {
+      fetchMock.mockGlobal();
+      const controller = new AbortController();
+      let requests = 0;
+      fetchMock.get(`begin:${base}`, ({ url }) => {
+        requests++;
+        const index = Number(new URL(url).pathname.split("/").at(-1));
+        if (index === 2) return Response.json({ done: true });
+        if (index === 1) controller.abort();
+        const next = `${base}${index + 1}`;
+        return new Response(
+          html
+            ? `<link rel="alternate" type="application/activity+json" href="${next}">`
+            : "not JSON",
+          {
+            headers: html ? { "Content-Type": "text/html" } : {
+              "Content-Type": "text/plain",
+              Link:
+                `<${next}>; rel="alternate"; type="application/activity+json"`,
+            },
+          },
+        );
+      });
+      try {
+        await rejects(loader(`${base}0`, { signal: controller.signal }), {
+          name: "AbortError",
+        });
+        deepStrictEqual(requests, 2);
+      } finally {
+        fetchMock.hardReset();
+      }
+    });
+  }
+});
+
+test("getDocumentLoader() rejects cancellation before fetching", async () => {
+  fetchMock.mockGlobal();
+  let requests = 0;
+  const url = "https://example.com/pre-aborted-alternate";
+  fetchMock.get(url, () => {
+    requests++;
+    return Response.json({ done: true });
+  });
+  try {
+    const loader = getDocumentLoader({ allowPrivateAddress: true });
+    const controller = new AbortController();
+    controller.abort();
+    await rejects(loader(url, { signal: controller.signal }), {
+      name: "AbortError",
+    });
+    deepStrictEqual(requests, 0);
+  } finally {
+    fetchMock.hardReset();
+  }
+});

package/src/docloader.ts

@@ -274,6 +274,8 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
 
 /**
  * Creates a JSON-LD document loader that utilizes the browser's `fetch` API.
+ * At most 20 HTTP redirects and alternate document links are followed in total
+ * per call.  Revisiting a URL within that chain throws a {@link FetchError}.
  *
  * The created loader preloads the below frequently used contexts by default
  * (unless `options.skipPreloadedContexts` is set to `true`):
@@ -285,6 +287,7 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
  * - <https://www.w3.org/ns/cid/v1>
  * - <https://w3id.org/security/multikey/v1>
  * - <https://w3id.org/fep/ef61>
+ * - <https://w3id.org/fep/7aa9>
  * - <https://purl.archive.org/socialweb/webfinger>
  * - <http://schema.org/>
  * @param options Options for the document loader.
@@ -320,10 +323,17 @@ export function getDocumentLoader(
         await validatePublicUrl(currentUrl);
       } catch (error) {
         if (error instanceof UrlError) {
-          logger.error("Disallowed private URL: {url}", {
-            url: currentUrl,
-            error,
-          });
+          if (error.reason === "dns") {
+            logger.debug("DNS lookup failed for {url}", {
+              url: currentUrl,
+              error,
+            });
+          } else {
+            logger.error("Disallowed private URL: {url}", {
+              url: currentUrl,
+              error,
+            });
+          }
         }
         throw error;
       }
@@ -385,7 +395,26 @@ export function getDocumentLoader(
             return await load(redirectUrl, options, redirected + 1, visited);
           }
 
-          const result = await getRemoteDocument(currentUrl, response, load);
+          const result = await getRemoteDocument(
+            currentUrl,
+            response,
+            async (alternateUrl) => {
+              options?.signal?.throwIfAborted();
+              if (redirected >= DEFAULT_MAX_REDIRECTION) {
+                throw new FetchError(
+                  currentUrl,
+                  `Too many redirections (${redirected + 1})`,
+                );
+              }
+              if (visited.has(alternateUrl)) {
+                throw new FetchError(
+                  currentUrl,
+                  `Redirect loop detected: ${alternateUrl}`,
+                );
+              }
+              return await load(alternateUrl, options, redirected + 1, visited);
+            },
+          );
           span.setAttribute("docloader.document_url", result.documentUrl);
           if (result.contextUrl != null) {
             span.setAttribute("docloader.context_url", result.contextUrl);
@@ -404,5 +433,5 @@ export function getDocumentLoader(
       },
     );
   }
-  return load;
+  return (url, options) => load(url, options);
 }

package/src/url.test.ts

@@ -1,4 +1,4 @@
-import { deepStrictEqual, ok, rejects, throws } from "node:assert";
+import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert";
 import { test } from "node:test";
 import {
   expandIPv6Address,
@@ -9,6 +9,28 @@ import {
   validatePublicUrl,
 } from "./url.ts";
 
+test("UrlError reason is independent of its cause", () => {
+  const cause = new Error("Underlying failure");
+  strictEqual(new UrlError("Rejected URL").reason, "disallowed");
+  const disallowedError = new UrlError("Rejected URL", { cause });
+  strictEqual(disallowedError.reason, "disallowed");
+  strictEqual(disallowedError.cause, cause);
+  const dnsError = new UrlError("Lookup failed", { reason: "dns", cause });
+  strictEqual(dnsError.reason, "dns");
+  strictEqual(dnsError.cause, cause);
+});
+
+test("validatePublicUrl() classifies disallowed URLs", async () => {
+  for (
+    const url of ["ftp://example.com", "https://localhost", "https://127.0.0.1"]
+  ) {
+    await rejects(() => validatePublicUrl(url), {
+      name: "UrlError",
+      reason: "disallowed",
+    });
+  }
+});
+
 test("validatePublicUrl()", async () => {
   await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
   await rejects(
@@ -81,15 +103,19 @@ test("validateLookupAddresses() rejects unsafe or CNAME-only Cloudflare Workers
         { address: "private-host.example.net.", family: 4 },
         { address: "127.0.0.1", family: 4 },
       ]),
-    UrlError,
+    { name: "UrlError", reason: "disallowed" },
   );
   throws(
     () =>
       validateLookupAddresses([
         { address: "app-host.example.net.", family: 4 },
       ]),
-    UrlError,
+    { name: "UrlError", reason: "dns" },
   );
+  throws(() => validateLookupAddresses([]), {
+    name: "UrlError",
+    reason: "dns",
+  });
 });
 
 test("isValidPublicIPv4Address()", () => {

package/src/url.ts

@@ -1,11 +1,25 @@
 import type { LookupAddress } from "node:dns";
-import { lookup } from "node:dns/promises";
+// FIXME: the default dns import exists since tests can stub `dns.lookup()`.
+// This should be replaced by injecting the lookup function such as an internal
+// option on `validatePublicUrl()`
+import dns from "node:dns/promises";
 import { isIP } from "node:net";
 
 export class UrlError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
+  /**
+   * The failure category. Defaults to `"disallowed"`.
+   * `"dns"` includes lookup errors and results with no usable IP addresses.
+   * @since 2.0.29
+   */
+  readonly reason: "dns" | "disallowed";
+
+  constructor(
+    message: string,
+    options?: { cause?: unknown; reason?: "dns" | "disallowed" },
+  ) {
     super(message, options);
     this.name = "UrlError";
+    this.reason = options?.reason ?? "disallowed";
   }
 }
 
@@ -50,9 +64,9 @@ export async function validatePublicUrl(url: string): Promise<void> {
   // and ensure that they are all public:
   let addresses: LookupAddress[];
   try {
-    addresses = await lookup(hostname, { all: true });
+    addresses = await dns.lookup(hostname, { all: true });
   } catch (error) {
-    throw new UrlError("DNS lookup failed", { cause: error });
+    throw new UrlError("DNS lookup failed", { cause: error, reason: "dns" });
   }
   validateLookupAddresses(addresses);
 }
@@ -85,7 +99,9 @@ export function validateLookupAddresses(
     validatePublicIpAddress(address, family);
   }
   if (ipAddressCount === 0) {
-    throw new UrlError("DNS lookup did not return any IP address");
+    throw new UrlError("DNS lookup did not return any IP address", {
+      reason: "dns",
+    });
   }
 }