@fedify/relay 2.4.0-pr.934.40 → 2.4.0

package/dist/mod.d.cts

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Context, KvStore, MessageQueue } from "@fedify/fedify";
 import { Actor } from "@fedify/vocab";
-//#region ../vocab-runtime/dist/docloader-xRGn1azD.d.ts
+//#region ../vocab-runtime/dist/docloader-CYwqh5Df.d.ts
 /**
 * Options for making `User-Agent` string.
 * @see {@link getUserAgent}
@@ -54,6 +54,13 @@ interface DocumentLoaderOptions {
   * @since 1.8.0
   */
   signal?: AbortSignal;
+  /**
+  * Whether to lower error-level logs for recoverable document loading
+  * failures to warning-level logs.  The loader still throws the error.
+  * @default `false`
+  * @since 2.4.0
+  */
+  suppressError?: boolean;
 }
 /**
 * A JSON-LD document loader that fetches documents from the Web.
@@ -94,6 +101,28 @@ interface DocumentLoaderFactoryOptions {
   * @since 2.2.0
   */
   maxRedirection?: number;
+  /**
+  * The timeout in milliseconds for each call of the created document
+  * loader.  The timeout is shared by all the steps of a call, including
+  * URL validation, every HTTP redirect and alternate document link it
+  * follows, retries, and reading the response body; it does not restart
+  * for each of them.  It does not interrupt synchronous work such as
+  * parsing a document that has already been received.
+  *
+  * When a call times out, the loader throws a {@link FetchError} without
+  * a {@link FetchError.response}, whose `cause` is a `DOMException` named
+  * `"TimeoutError"`.  An `AbortSignal` passed through
+  * {@link DocumentLoaderOptions.signal} still cancels a call; in that case
+  * the loader throws the signal's reason as before.
+  *
+  * Fractional values are rounded up.  Set it to `null` to turn off the
+  * timeout.
+  * @default `10000` (10 seconds)
+  * @throws {RangeError} If the value is not a positive finite number or is
+  *                      greater than 2,147,483,647 (about 24.8 days).
+  * @since 2.4.0
+  */
+  timeout?: number | null;
 }
 /**
 * A factory function that creates an authenticated {@link DocumentLoader} for
@@ -114,6 +143,7 @@ type AuthenticatedDocumentLoaderFactory = (identity: {
 * @param url The URL of the document to load.
 * @param response The response to get the document from.
 * @param fetch The function to fetch the document.
+* @param options The options for loading the document.
 * @returns The loaded remote document.
 * @throws {FetchError} If the response is not OK.
 * @internal
@@ -126,6 +156,12 @@ declare const RELAY_SERVER_ACTOR = "relay";
 */
 type RelayType = "mastodon" | "litepub";
 /**
+* A follower's subscription state.
+*
+* @internal
+*/
+type RelayFollowerState = "pending" | "accepted";
+/**
 * Handler for subscription requests (Follow/Undo activities).
 */
 type SubscriptionRequestHandler = (ctx: Context<RelayOptions>, clientActor: Actor) => Promise<boolean>;
@@ -182,7 +218,7 @@ interface RelayFollower {
   /** The validated Actor object. */
   readonly actor: Actor;
   /** The follower's state. */
-  readonly state: "pending" | "accepted";
+  readonly state: RelayFollowerState;
 }
 /**
 * Public interface for ActivityPub relay implementations.

package/dist/mod.d.ts

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Context, KvStore, MessageQueue } from "@fedify/fedify";
 import { Actor } from "@fedify/vocab";
-//#region ../vocab-runtime/dist/docloader-xRGn1azD.d.ts
+//#region ../vocab-runtime/dist/docloader-CYwqh5Df.d.ts
 /**
 * Options for making `User-Agent` string.
 * @see {@link getUserAgent}
@@ -54,6 +54,13 @@ interface DocumentLoaderOptions {
   * @since 1.8.0
   */
   signal?: AbortSignal;
+  /**
+  * Whether to lower error-level logs for recoverable document loading
+  * failures to warning-level logs.  The loader still throws the error.
+  * @default `false`
+  * @since 2.4.0
+  */
+  suppressError?: boolean;
 }
 /**
 * A JSON-LD document loader that fetches documents from the Web.
@@ -94,6 +101,28 @@ interface DocumentLoaderFactoryOptions {
   * @since 2.2.0
   */
   maxRedirection?: number;
+  /**
+  * The timeout in milliseconds for each call of the created document
+  * loader.  The timeout is shared by all the steps of a call, including
+  * URL validation, every HTTP redirect and alternate document link it
+  * follows, retries, and reading the response body; it does not restart
+  * for each of them.  It does not interrupt synchronous work such as
+  * parsing a document that has already been received.
+  *
+  * When a call times out, the loader throws a {@link FetchError} without
+  * a {@link FetchError.response}, whose `cause` is a `DOMException` named
+  * `"TimeoutError"`.  An `AbortSignal` passed through
+  * {@link DocumentLoaderOptions.signal} still cancels a call; in that case
+  * the loader throws the signal's reason as before.
+  *
+  * Fractional values are rounded up.  Set it to `null` to turn off the
+  * timeout.
+  * @default `10000` (10 seconds)
+  * @throws {RangeError} If the value is not a positive finite number or is
+  *                      greater than 2,147,483,647 (about 24.8 days).
+  * @since 2.4.0
+  */
+  timeout?: number | null;
 }
 /**
 * A factory function that creates an authenticated {@link DocumentLoader} for
@@ -114,6 +143,7 @@ type AuthenticatedDocumentLoaderFactory = (identity: {
 * @param url The URL of the document to load.
 * @param response The response to get the document from.
 * @param fetch The function to fetch the document.
+* @param options The options for loading the document.
 * @returns The loaded remote document.
 * @throws {FetchError} If the response is not OK.
 * @internal
@@ -126,6 +156,12 @@ declare const RELAY_SERVER_ACTOR = "relay";
 */
 type RelayType = "mastodon" | "litepub";
 /**
+* A follower's subscription state.
+*
+* @internal
+*/
+type RelayFollowerState = "pending" | "accepted";
+/**
 * Handler for subscription requests (Follow/Undo activities).
 */
 type SubscriptionRequestHandler = (ctx: Context<RelayOptions>, clientActor: Actor) => Promise<boolean>;
@@ -182,7 +218,7 @@ interface RelayFollower {
   /** The validated Actor object. */
   readonly actor: Actor;
   /** The follower's state. */
-  readonly state: "pending" | "accepted";
+  readonly state: RelayFollowerState;
 }
 /**
 * Public interface for ActivityPub relay implementations.

package/dist/mod.js

@@ -17,6 +17,28 @@ function isRelayFollowerData(value) {
 	const obj = value;
 	return "actor" in obj && "state" in obj && typeof obj.state === "string" && (obj.state === "pending" || obj.state === "accepted");
 }
+/**
+* Parses and semantically validates follower data from storage.
+*
+* @param actorId The actor ID used as the follower's storage key.
+* @param value The stored follower data.
+* @returns The parsed follower, or `null` if the row is invalid.
+* @internal
+*/
+async function parseRelayFollowerData(actorId, value) {
+	if (!isRelayFollowerData(value)) return null;
+	try {
+		const actor = await Object$1.fromJsonLd(value.actor);
+		if (!isActor(actor) || actor.id?.href !== actorId) return null;
+		return {
+			actorId,
+			actor,
+			state: value.state
+		};
+	} catch {
+		return null;
+	}
+}
 //#endregion
 //#region src/builder.ts
 const relayBuilder = createFederationBuilder();
@@ -77,12 +99,12 @@ relayBuilder.setActorDispatcher("/users/{identifier}", async (ctx, identifier) =
 });
 async function getFollowerActors(ctx) {
 	const actors = [];
-	for await (const { value } of ctx.data.kv.list(["follower"])) {
-		if (!isRelayFollowerData(value)) continue;
-		if (value.state !== "accepted") continue;
-		const actor = await Object$1.fromJsonLd(value.actor);
-		if (!isActor(actor)) continue;
-		actors.push(actor);
+	for await (const { key, value } of ctx.data.kv.list(["follower"])) {
+		const actorId = key[1];
+		if (typeof actorId !== "string") continue;
+		const follower = await parseRelayFollowerData(actorId, value);
+		if (follower?.state !== "accepted") continue;
+		actors.push(follower.actor);
 	}
 	return actors;
 }
@@ -93,6 +115,64 @@ async function dispatchRelayActors(ctx, identifier) {
 relayBuilder.setFollowersDispatcher("/users/{identifier}/followers", dispatchRelayActors);
 relayBuilder.setFollowingDispatcher("/users/{identifier}/following", dispatchRelayActors);
 //#endregion
+//#region src/follow.ts
+/**
+* Validate Follow activity and return follower actor if valid.
+* This validation is common to both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param follow The Follow activity to validate
+* @returns The follower Actor if valid, null otherwise
+*/
+async function validateFollowActivity(ctx, follow) {
+	if (follow.id == null || follow.objectId == null) return null;
+	const parsed = ctx.parseUri(follow.objectId);
+	if (!(follow.objectId.href === "https://www.w3.org/ns/activitystreams#Public") && parsed?.type !== "actor") return null;
+	const follower = await follow.getActor(ctx);
+	if (follower == null || follower.id == null || follower.preferredUsername == null || follower.inboxId == null) return null;
+	return follower;
+}
+/**
+* Send Accept or Reject response for a Follow activity.
+* This is common to both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param follow The Follow activity being responded to
+* @param follower The actor who sent the Follow
+* @param approved Whether the follow was approved
+*/
+async function sendFollowResponse(ctx, follow, follower, approved) {
+	const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
+	const Activity = approved ? Accept : Reject;
+	const action = approved ? "accepts" : "rejects";
+	await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Activity({
+		id: new URL(`#${action}`, relayActorUri),
+		actor: relayActorUri,
+		object: follow
+	}));
+}
+/**
+* Handle Undo activity for Follow.
+* This logic is identical for both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param undo The Undo activity to handle
+* @param logger The logger instance to use for warnings
+*/
+async function handleUndoFollow(ctx, undo, logger) {
+	const activity = await undo.getObject({
+		crossOrigin: "trust",
+		...ctx
+	});
+	if (activity instanceof Follow) {
+		if (activity.id == null || activity.actorId == null) return;
+		await ctx.data.kv.delete(["follower", activity.actorId.href]);
+	} else logger.warn("Unsupported object type ({type}) for Undo activity: {object}", {
+		type: activity?.constructor.name,
+		object: activity
+	});
+}
+//#endregion
 //#region src/base.ts
 /**
 * Abstract base class for relay implementations.
@@ -112,25 +192,6 @@ var BaseRelay = class {
 		return await (await this.#getFederation()).fetch(request, { contextData: this.options });
 	}
 	/**
-	* Helper method to parse and validate follower data from storage.
-	* Deserializes JSON-LD actor data and validates it.
-	*
-	* @param actorId The actor ID of the follower
-	* @param data Raw data from KV store
-	* @returns RelayFollower object if valid, null otherwise
-	* @internal
-	*/
-	async parseFollowerData(actorId, data) {
-		if (!isRelayFollowerData(data)) return null;
-		const actor = await Object$1.fromJsonLd(data.actor);
-		if (!isActor(actor)) return null;
-		return {
-			actorId,
-			actor,
-			state: data.state
-		};
-	}
-	/**
 	* Lists all followers of the relay.
 	*
 	* @returns An async iterator of follower entries
@@ -159,7 +220,7 @@ var BaseRelay = class {
 		for await (const entry of this.options.kv.list(["follower"])) {
 			const actorId = entry.key[1];
 			if (typeof actorId !== "string") continue;
-			const follower = await this.parseFollowerData(actorId, entry.value);
+			const follower = await parseRelayFollowerData(actorId, entry.value);
 			if (follower) yield follower;
 		}
 	}
@@ -192,8 +253,35 @@ var BaseRelay = class {
 	* @since 2.0.0
 	*/
 	async getFollower(actorId) {
-		const followerData = await this.options.kv.get(["follower", actorId]);
-		return await this.parseFollowerData(actorId, followerData);
+		return await parseRelayFollowerData(actorId, await this.options.kv.get(["follower", actorId]));
+	}
+	shouldSkipFollow(_ctx, _follower) {
+		return Promise.resolve(false);
+	}
+	afterFollowApproved(_ctx, _follower) {
+		return Promise.resolve();
+	}
+	async #handleFollow(ctx, follow) {
+		const follower = await validateFollowActivity(ctx, follow);
+		if (follower?.id == null || await this.shouldSkipFollow(ctx, follower)) return;
+		const approved = await this.options.subscriptionHandler(ctx, follower);
+		if (approved) await ctx.data.kv.set(["follower", follower.id.href], {
+			actor: await follower.toJsonLd(),
+			state: this.initialFollowerState
+		});
+		await sendFollowResponse(ctx, follow, follower, approved);
+		if (approved) await this.afterFollowApproved(ctx, follower);
+	}
+	async #relayActivity(ctx, activity) {
+		const senderId = activity.actorId;
+		const excludeBaseUris = senderId == null ? [] : [senderId];
+		await this.deliverActivity(ctx, activity, excludeBaseUris);
+	}
+	setupInboxListeners() {
+		if (this.federation == null) throw new Error("Federation must be initialized before inbox listeners");
+		const listeners = this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox");
+		listeners.on(Follow, async (ctx, follow) => await this.#handleFollow(ctx, follow)).on(Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, this.logger)).on(Create, async (ctx, create) => await this.#relayActivity(ctx, create)).on(Delete, async (ctx, deleteActivity) => await this.#relayActivity(ctx, deleteActivity)).on(Move, async (ctx, move) => await this.#relayActivity(ctx, move)).on(Update, async (ctx, update) => await this.#relayActivity(ctx, update)).on(Announce, async (ctx, announce) => await this.#relayActivity(ctx, announce));
+		return listeners;
 	}
 	async #getFederation() {
 		if (this.federation == null) {
@@ -213,64 +301,6 @@ var BaseRelay = class {
 	}
 };
 //#endregion
-//#region src/follow.ts
-/**
-* Validate Follow activity and return follower actor if valid.
-* This validation is common to both Mastodon and LitePub relay protocols.
-*
-* @param ctx The federation context
-* @param follow The Follow activity to validate
-* @returns The follower Actor if valid, null otherwise
-*/
-async function validateFollowActivity(ctx, follow) {
-	if (follow.id == null || follow.objectId == null) return null;
-	const parsed = ctx.parseUri(follow.objectId);
-	if (!(follow.objectId.href === "https://www.w3.org/ns/activitystreams#Public") && parsed?.type !== "actor") return null;
-	const follower = await follow.getActor(ctx);
-	if (follower == null || follower.id == null || follower.preferredUsername == null || follower.inboxId == null) return null;
-	return follower;
-}
-/**
-* Send Accept or Reject response for a Follow activity.
-* This is common to both Mastodon and LitePub relay protocols.
-*
-* @param ctx The federation context
-* @param follow The Follow activity being responded to
-* @param follower The actor who sent the Follow
-* @param approved Whether the follow was approved
-*/
-async function sendFollowResponse(ctx, follow, follower, approved) {
-	const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
-	const Activity = approved ? Accept : Reject;
-	const action = approved ? "accepts" : "rejects";
-	await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Activity({
-		id: new URL(`#${action}`, relayActorUri),
-		actor: relayActorUri,
-		object: follow
-	}));
-}
-/**
-* Handle Undo activity for Follow.
-* This logic is identical for both Mastodon and LitePub relay protocols.
-*
-* @param ctx The federation context
-* @param undo The Undo activity to handle
-* @param logger The logger instance to use for warnings
-*/
-async function handleUndoFollow(ctx, undo, logger) {
-	const activity = await undo.getObject({
-		crossOrigin: "trust",
-		...ctx
-	});
-	if (activity instanceof Follow) {
-		if (activity.id == null || activity.actorId == null) return;
-		await ctx.data.kv.delete(["follower", activity.actorId.href]);
-	} else logger.warn("Unsupported object type ({type}) for Undo activity: {object}", {
-		type: activity?.constructor.name,
-		object: activity
-	});
-}
-//#endregion
 //#region src/litepub.ts
 const logger$1 = getLogger([
 	"fedify",
@@ -285,9 +315,23 @@ const logger$1 = getLogger([
 * @since 2.0.0
 */
 var LitePubRelay = class extends BaseRelay {
-	async #announceToFollowers(ctx, activity) {
-		const sender = await activity.getActor(ctx);
-		const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
+	initialFollowerState = "pending";
+	logger = logger$1;
+	async shouldSkipFollow(ctx, follower) {
+		if (follower.id == null) return true;
+		const existingFollow = await ctx.data.kv.get(["follower", follower.id.href]);
+		return await parseRelayFollowerData(follower.id.href, existingFollow) != null;
+	}
+	async afterFollowApproved(ctx, follower) {
+		if (follower.id == null) return;
+		const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
+		await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Follow({
+			actor: relayActorUri,
+			object: follower.id,
+			to: follower.id
+		}));
+	}
+	async deliverActivity(ctx, activity, excludeBaseUris) {
 		const announce = new Announce({
 			id: new URL(`/announce#${crypto.randomUUID()}`, ctx.origin),
 			actor: ctx.getActorUri(RELAY_SERVER_ACTOR),
@@ -301,25 +345,7 @@ var LitePubRelay = class extends BaseRelay {
 		});
 	}
 	setupInboxListeners() {
-		if (this.federation != null) this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(Follow, async (ctx, follow) => {
-			const follower = await validateFollowActivity(ctx, follow);
-			if (!follower || !follower.id) return;
-			if ((await ctx.data.kv.get(["follower", follower.id.href]))?.state === "pending") return;
-			const approved = await this.options.subscriptionHandler(ctx, follower);
-			if (approved) {
-				await ctx.data.kv.set(["follower", follower.id.href], {
-					actor: await follower.toJsonLd(),
-					state: "pending"
-				});
-				await sendFollowResponse(ctx, follow, follower, approved);
-				const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
-				await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Follow({
-					actor: relayActorUri,
-					object: follower.id,
-					to: follower.id
-				}));
-			} else await sendFollowResponse(ctx, follow, follower, approved);
-		}).on(Accept, async (ctx, accept) => {
+		return super.setupInboxListeners().on(Accept, async (ctx, accept) => {
 			const follow = await accept.getObject({
 				crossOrigin: "trust",
 				...ctx
@@ -327,18 +353,19 @@ var LitePubRelay = class extends BaseRelay {
 			if (!(follow instanceof Follow)) return;
 			const relayActorId = follow.actorId;
 			if (relayActorId == null) return;
-			const followerActor = await accept.getActor();
+			const followerActor = await accept.getActor(ctx);
 			if (!isActor(followerActor) || !followerActor.id) return;
 			const parsed = ctx.parseUri(relayActorId);
 			if (parsed == null || parsed.type !== "actor") return;
 			const followerData = await ctx.data.kv.get(["follower", followerActor.id.href]);
-			if (followerData == null) return;
+			if (!isRelayFollowerData(followerData)) return;
+			if (await parseRelayFollowerData(followerActor.id.href, followerData) == null) return;
 			const updatedFollowerData = {
 				...followerData,
 				state: "accepted"
 			};
 			await ctx.data.kv.set(["follower", followerActor.id.href], updatedFollowerData);
-		}).on(Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, logger$1)).on(Create, async (ctx, create) => await this.#announceToFollowers(ctx, create)).on(Update, async (ctx, update) => await this.#announceToFollowers(ctx, update)).on(Move, async (ctx, move) => await this.#announceToFollowers(ctx, move)).on(Delete, async (ctx, deleteActivity) => await this.#announceToFollowers(ctx, deleteActivity)).on(Announce, async (ctx, announce) => await this.#announceToFollowers(ctx, announce));
+		});
 	}
 };
 //#endregion
@@ -356,27 +383,15 @@ const logger = getLogger([
 * @since 2.0.0
 */
 var MastodonRelay = class extends BaseRelay {
-	async #forwardToFollowers(ctx, activity) {
-		const sender = await activity.getActor(ctx);
-		const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
+	initialFollowerState = "accepted";
+	logger = logger;
+	async deliverActivity(ctx, _activity, excludeBaseUris) {
 		await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
 			skipIfUnsigned: true,
 			excludeBaseUris,
 			preferSharedInbox: true
 		});
 	}
-	setupInboxListeners() {
-		if (this.federation != null) this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(Follow, async (ctx, follow) => {
-			const follower = await validateFollowActivity(ctx, follow);
-			if (!follower || !follower.id) return;
-			const approved = await this.options.subscriptionHandler(ctx, follower);
-			if (approved) await ctx.data.kv.set(["follower", follower.id.href], {
-				actor: await follower.toJsonLd(),
-				state: "accepted"
-			});
-			await sendFollowResponse(ctx, follow, follower, approved);
-		}).on(Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, logger)).on(Create, async (ctx, create) => await this.#forwardToFollowers(ctx, create)).on(Delete, async (ctx, deleteActivity) => await this.#forwardToFollowers(ctx, deleteActivity)).on(Move, async (ctx, move) => await this.#forwardToFollowers(ctx, move)).on(Update, async (ctx, update) => await this.#forwardToFollowers(ctx, update)).on(Announce, async (ctx, announce) => await this.#forwardToFollowers(ctx, announce));
-	}
 };
 //#endregion
 //#region src/factory.ts