Utilize AbortController (Request.signal) for APIs that make outgoing …

CHANGES.md

@@ -85,6 +85,9 @@ To be released.
  -  Let the `fedify lookup` command take multiple arguments.
     [[#173], [#186] by PGD]
 
+ -  Added options related to `AbortController`.
+    [[#51] [#187] by PDJ]
+
 
 [SvelteKit]: https://kit.svelte.dev/
 [#162]: https://github.com/dahlia/fedify/issues/162

docs/manual/opentelemetry.md

@@ -130,6 +130,11 @@ spans:
 | `object_integrity_proofs.verify` | Internal    | Verifies the object integrity proof.  |
 | `webfinger.handle`               | Server      | Handles the WebFinger request.        |
 | `webfinger.lookup`               | Client      | Looks up the WebFinger resource.      |
+| Operation            | Span type | Description                       |
+|----------------------|-----------|-----------------------------------|
+| `Federation.fetch()` | Server    | Serves the incoming HTTP request. |
+| `lookupWebFinger()`  | Client    | Looks up the WebFinger resource.  |
+| `handleWebFinger()`  | Server    | Handles the WebFinger request.    |
 
 More operations will be instrumented in the future releases.
 
@@ -172,4 +177,21 @@ for ActivityPub:
 | `webfinger.resource.scheme`           | string   | The scheme of the queried resource URI.                                                  | `"acct"`                                                             |
 
 [attributes]: https://opentelemetry.io/docs/specs/otel/common/#attribute
+| Attribute                        | Type     | Description                                                                     | Example                                            |
+|----------------------------------|----------|---------------------------------------------------------------------------------|----------------------------------------------------|
+| `activitypub.activity.id`        | string   | The URI of the activity object.                                                 | `"https://example.com/activity/1"`                 |
+| `activitypub.activity.type`      | string[] | The qualified URI(s) of the activity type(s).                                   | `["https://www.w3.org/ns/activitystreams#Create"]` |
+| `activitypub.activity.to`        | string[] | The URI(s) of the recipient collections/actors of the activity.                 | `["https://example.com/1/followers/2"]`            |
+| `activitypub.activity.cc`        | string[] | The URI(s) of the carbon-copied recipient collections/actors of the activity.   | `["https://www.w3.org/ns/activitystreams#Public"]` |
+| `activitypub.activity.retries`   | int      | The ordinal number of activity resending attempt (if and only if it's retried). | `3`                                                |
+| `activitypub.actor.id`           | string   | The URI of the actor object.                                                    | `"https://example.com/actor/1"`                    |
+| `activitypub.actor.type`         | string[] | The qualified URI(s) of the actor type(s).                                      | `["https://www.w3.org/ns/activitystreams#Person"]` |
+| `activitypub.object.id`          | string   | The URI of the object or the object enclosed by the activity.                   | `"https://example.com/object/1"`                   |
+| `activitypub.object.type`        | string[] | The qualified URI(s) of the object type(s).                                     | `["https://www.w3.org/ns/activitystreams#Note"]`   |
+| `activitypub.object.in_reply_to` | string[] | The URI(s) of the original object to which the object reply.                    | `["https://example.com/object/1"]`                 |
+| `activitypub.inboxes`            | int      | The number of inboxes the activity is sent to.                                  | `12`                                               |
+| `activitypub.shared_inbox`       | boolean  | Whether the activity is sent to the shared inbox.                               | `true`                                             |
+| `webfinger.resource`             | string   | The queried resource URI.                                                       | `"acct:[email protected]"`                       |
+| `webfinger.resource.scheme`      | string   | The scheme of the queried resource URI.                                         | `"acct"`                                           |
+
 [OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/specs/semconv/

src/runtime/docloader.ts

@@ -235,6 +235,11 @@ export interface GetDocumentLoaderOptions {
    * Whether to preload the frequently used contexts.
    */
   skipPreloadedContexts?: boolean;
+
+  /**
+   * An optional abort signal to cancel the request.
+   */
+  signal?: AbortSignal | null;
 }
 
 /**
@@ -255,7 +260,7 @@ export interface GetDocumentLoaderOptions {
  * @since 1.3.0
  */
 export function getDocumentLoader(
-  { allowPrivateAddress, skipPreloadedContexts, userAgent }:
+  { allowPrivateAddress, skipPreloadedContexts, userAgent, signal }:
     GetDocumentLoaderOptions = {},
 ): DocumentLoader {
   async function load(url: string): Promise<RemoteDocument> {
@@ -284,6 +289,7 @@ export function getDocumentLoader(
       // to work around it we specify `redirect: "manual"` here too:
       // https://github.com/oven-sh/bun/issues/10754
       redirect: "manual",
+      signal,
     });
     // Follow redirects manually to get the final URL:
     if (

src/vocab/actor.ts

@@ -101,6 +101,12 @@ export interface GetActorHandleOptions extends NormalizeActorHandleOptions {
    * @since 1.3.0
    */
   tracerProvider?: TracerProvider;
+
+  /**
+   * An optional abort signal to cancel the request.
+   * @since 1.3.0
+   */
+  signal?: AbortSignal | null;
 }
 
 /**
@@ -166,10 +172,21 @@ async function getActorHandleInternal(
 ): Promise<`@${string}@${string}` | `${string}@${string}`> {
   const actorId = actor instanceof URL ? actor : actor.id;
   if (actorId != null) {
-    const result = await lookupWebFinger(actorId, {
-      userAgent: options.userAgent,
-      tracerProvider: options.tracerProvider,
-    });
+    let result;
+    try {
+      result = await lookupWebFinger(actorId, {
+        userAgent: options.userAgent,
+        tracerProvider: options.tracerProvider,
+        signal: options.signal,
+      });
+    } catch (error) {
+      if ((error as Error).name === "AbortError") {
+        throw new Error("Actor handle lookup was aborted", { cause: error });
+      }
+
+      throw error;
+    }
+
     if (result != null) {
       const aliases = [...(result.aliases ?? [])];
       if (result.subject != null) aliases.unshift(result.subject);
@@ -184,6 +201,7 @@ async function getActorHandleInternal(
               alias,
               options.userAgent,
               options.tracerProvider,
+              options.signal,
             )
           ) {
             continue;
@@ -212,8 +230,13 @@ async function verifyCrossOriginActorHandle(
   alias: string,
   userAgent: GetUserAgentOptions | string | undefined,
   tracerProvider: TracerProvider | undefined,
+  signal?: AbortSignal | null,
 ): Promise<boolean> {
-  const response = await lookupWebFinger(alias, { userAgent, tracerProvider });
+  const response = await lookupWebFinger(alias, {
+    userAgent,
+    tracerProvider,
+    signal,
+  });
   if (response == null) return false;
   for (const alias of response.aliases ?? []) {
     if (new URL(alias).href === actorId) return true;

src/vocab/lookup.ts

@@ -45,6 +45,12 @@ export interface LookupObjectOptions {
    * @since 1.3.0
    */
   tracerProvider?: TracerProvider;
+
+  /**
+   * An optional abort signal to cancel the request.
+   * @since 1.3.0
+   */
+  signal?: AbortSignal | null;
 }
 
 const handleRegexp =
@@ -147,6 +153,7 @@ async function lookupObjectInternal(
     const jrd = await lookupWebFinger(identifier, {
       userAgent: options.userAgent,
       tracerProvider: options.tracerProvider,
+      signal: options.signal,
     });
     if (jrd?.links == null) return null;
     for (const l of jrd.links) {

src/webfinger/lookup.ts

@@ -32,6 +32,11 @@ export interface LookupWebFingerOptions {
    * is used.
    */
   tracerProvider?: TracerProvider;
+
+  /**
+   * An optional abort signal to cancel the request.
+   */
+  signal?: AbortSignal | null;
 }
 
 /**
@@ -107,6 +112,7 @@ async function lookupWebFingerInternal(
     let response: Response;
     try {
       response = await fetch(url, {
+        signal: options?.signal,
         headers: {
           Accept: "application/jrd+json",
           "User-Agent": typeof options.userAgent === "string"