withIdempotency() for custom activity idempotency

Addresses issue #441 where activities with the same ID sent to different
inboxes were incorrectly deduplicated globally instead of per-inbox.

- Add IdempotencyStrategy type with "global", "per-origin", "per-inbox" options
- Add IdempotencyKeyCallback type for custom deduplication strategies
- Add InboxListenerSetters.withIdempotency() method
- Implement three built-in strategies:
  * "per-origin": deduplicate per receiving server (current default)
  * "per-inbox": deduplicate per inbox (standard ActivityPub, future default)
  * "global": deduplicate globally across all inboxes
- Add comprehensive test coverage for all strategies
- Add documentation section in docs/manual/inbox.md
- Include deprecation warning when using default strategy
- Cache processed activities for 24 hours using existing KV store
- Maintain backward compatibility with "per-origin" default

The default will change from "per-origin" to "per-inbox" in Fedify 2.0
to align with standard ActivityPub behavior.

Closes #441

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dahlia

CHANGES.md

@@ -31,6 +31,18 @@ To be released.
      -  Internal trust tracking system maintains security context throughout
         object lifecycles (construction, cloning, and property access).
 
+ -  Added `withIdempotency()` method to configure activity idempotency
+    strategies for inbox processing.  This addresses issue [#441] where
+    activities with the same ID sent to different inboxes were incorrectly
+    deduplicated globally instead of per-inbox.  [[#441]]
+
+     -  Added `IdempotencyStrategy` type.
+     -  Added `IdempotencyKeyCallback` type.
+     -  Added `InboxListenerSetters.withIdempotency()` method.
+     -  By default, `"per-origin"` strategy is used for backward compatibility.
+        This will change to `"per-inbox"` in Fedify 2.0.  We recommend
+        explicitly setting the strategy to avoid unexpected behavior changes.
+
  -  Fixed handling of ActivityPub objects containing relative URLs.  The
     Activity Vocabulary classes now automatically resolve relative URLs by
     inferring the base URL from the object's `@id` or document URL, eliminating
@@ -111,6 +123,7 @@ To be released.
 [#429]: https://github.com/fedify-dev/fedify/issues/429
 [#431]: https://github.com/fedify-dev/fedify/pull/431
 [#440]: https://github.com/fedify-dev/fedify/issues/440
+[#441]: https://github.com/fedify-dev/fedify/issues/441
 [#443]: https://github.com/fedify-dev/fedify/pull/443
 
 ### @fedify/cli
@@ -254,7 +267,7 @@ Released on September 17, 2025.
 Version 1.8.10
 --------------
 
-Released on Steptember 17, 2025.
+Released on September 17, 2025.
 
 ### @fedify/fedify
 
@@ -5221,4 +5234,7 @@ Version 0.1.0
 Initial release.  Released on March 8, 2024.
 
 <!-- cSpell: ignore Dogeon Fabien Wressell Emelia Fróði Karlsson -->
-<!-- cSpell: ignore Hana Heesun Kyunghee Jiyu Revath Kumar -->
+<!-- cSpell: ignore Hana Heesun Kyunghee Jiyu Revath Kumar Jaeyeol -->
+<!-- cSpell: ignore Jiwon Kwon Hyeonseo Chanhaeng Hasang Hyunchae KeunHyeong -->
+<!-- cSpell: ignore Jang Hanarae ByeongJun Subin -->
+<!-- cSpell: ignore Wayst Konsole Ghostty Aplc -->

cspell.json

@@ -53,6 +53,7 @@
     "keypair",
     "langstr",
     "Lemmy",
+    "lifecycles",
     "litepub",
     "logtape",
     "lume",

docs/manual/inbox.md

@@ -384,6 +384,96 @@ duplicate retry mechanisms and leverages the backend's optimized retry features.
 [`@fedify/redis`]: https://github.com/fedify-dev/fedify/tree/main/packages/redis
 
 
+Activity idempotency
+--------------------
+
+*This API is available since Fedify 1.9.0.*
+
+In ActivityPub, the same activity might be delivered multiple times to your
+inbox for various reasons, such as network failures, server restarts, or
+federation protocol retries.  To prevent processing the same activity multiple
+times, Fedify provides idempotency mechanisms that detect and skip duplicate
+activities.
+
+### Idempotency strategies
+
+Fedify supports three built-in idempotency strategies:
+
+`"per-inbox"`
+:   Activities are deduplicated per inbox.  The same activity ID can be
+    processed once per inbox, allowing the same activity to be delivered to
+    multiple inboxes independently.  This follows standard ActivityPub behavior
+    and will be the default in Fedify 2.0.
+
+`"per-origin"`
+:   Activities are deduplicated per receiving server's origin.  The same
+    activity ID will be processed only once on each receiving server,
+    but can be processed separately on different receiving servers.
+    This was the default behavior in Fedify 1.x versions.
+
+`"global"`
+:   Activities are deduplicated globally across all inboxes and origins.
+    The same activity ID will be processed only once, regardless of
+    which inbox receives it or which server sent it.
+
+You can configure the idempotency strategy using the
+`~InboxListenerSetters.withIdempotency()` method:
+
+~~~~ typescript twoslash
+import { type Federation, Follow } from "@fedify/fedify";
+const federation = null as unknown as Federation<void>;
+// ---cut-before---
+federation
+  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
+  .withIdempotency("per-inbox")  // Standard ActivityPub behavior
+  .on(Follow, async (ctx, follow) => {
+    // Handle the follow activity
+  });
+~~~~
+
+> [!WARNING]
+> If you don't explicitly configure an idempotency strategy, Fedify currently
+> uses `"per-origin"` as the default for backward compatibility.  However, this
+> default will change to `"per-inbox"` in Fedify 2.0.  We recommend explicitly
+> setting the strategy to avoid unexpected behavior changes.
+
+### Custom idempotency strategy
+
+If the built-in strategies don't meet your needs, you can implement a custom
+idempotency strategy by providing a callback function.  The callback receives
+the inbox context and the activity, and should return a unique cache key for
+the activity, or `null` to skip idempotency checking for that activity:
+
+~~~~ typescript twoslash
+import { type Federation, Follow } from "@fedify/fedify";
+const federation = null as unknown as Federation<void>;
+// ---cut-before---
+federation
+  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
+  .withIdempotency(async (ctx, activity) => {
+    // Skip idempotency for Follow activities
+    if (activity instanceof Follow) return null;
+
+    // Use per-inbox strategy for other activities
+    const inboxId
+      = ctx.recipient == null
+      ? "shared"
+      : `actor\n${ctx.recipient}`;
+    return `${ctx.origin}\n${activity.id?.href}\n${inboxId}`;
+  })
+  .on(Follow, async (ctx, follow) => {
+    // This Follow activity will not be deduplicated
+  });
+~~~~
+
+### Idempotency cache
+
+Processed activities are cached for 24 hours to detect duplicates.  The cache
+uses the same [key–value store](./kv.md) that you provided to
+the `createFederation()` function.  Cache keys are automatically namespaced to
+avoid conflicts with other data.
+
+
 Error handling
 --------------
 

packages/fedify/src/federation/builder.ts

@@ -33,6 +33,8 @@ import type {
   Federation,
   FederationBuilder,
   FederationOptions,
+  IdempotencyKeyCallback,
+  IdempotencyStrategy,
   InboxListenerSetters,
   ObjectCallbackSetters,
   ParamsKeyPath,
@@ -102,6 +104,9 @@ export class FederationBuilderImpl<TContextData>
   inboxListeners?: InboxListenerSet<TContextData>;
   inboxErrorHandler?: InboxErrorHandler<TContextData>;
   sharedInboxKeyDispatcher?: SharedInboxKeyDispatcher<TContextData>;
+  idempotencyStrategy?:
+    | IdempotencyStrategy
+    | IdempotencyKeyCallback<TContextData>;
   collectionTypeIds: Record<
     string | symbol,
     ConstructorWithTypeId<Object>
@@ -178,6 +183,7 @@ export class FederationBuilderImpl<TContextData>
     f.inboxListeners = this.inboxListeners?.clone();
     f.inboxErrorHandler = this.inboxErrorHandler;
     f.sharedInboxKeyDispatcher = this.sharedInboxKeyDispatcher;
+    f.idempotencyStrategy = this.idempotencyStrategy;
     return f;
   }
 
@@ -1202,6 +1208,12 @@ export class FederationBuilderImpl<TContextData>
         this.sharedInboxKeyDispatcher = dispatcher;
         return setters;
       },
+      withIdempotency: (
+        strategy: IdempotencyStrategy | IdempotencyKeyCallback<TContextData>,
+      ): InboxListenerSetters<TContextData> => {
+        this.idempotencyStrategy = strategy;
+        return setters;
+      },
     };
     return setters;
   }

packages/fedify/src/federation/federation.ts

@@ -30,7 +30,7 @@ import type {
   SharedInboxKeyDispatcher,
   WebFingerLinksDispatcher,
 } from "./callback.ts";
-import type { Context, RequestContext } from "./context.ts";
+import type { Context, InboxContext, RequestContext } from "./context.ts";
 import type { KvStore } from "./kv.ts";
 import type {
   FederationKvPrefixes,
@@ -952,6 +952,41 @@ export interface CollectionCallbackSetters<
   ): CollectionCallbackSetters<TContext, TContextData, TFilter>;
 }
 
+/**
+ * The strategy for handling activity idempotency in inbox processing.
+ *
+ *  -  `"global"`: Activities are deduplicated globally across all inboxes and
+ *     origins.  The same activity ID will be processed only once, regardless
+ *     of which inbox receives it or which server sent it.
+ *
+ *  -  `"per-origin"`: Activities are deduplicated per receiving server's origin.
+ *     The same activity ID will be processed only once on each receiving server,
+ *     but can be processed separately on different receiving servers. This was
+ *     the default behavior in Fedify 1.x versions.
+ *
+ *  -  `"per-inbox"`: Activities are deduplicated per inbox. The same activity
+ *     ID can be processed once per inbox, allowing the same activity to be
+ *     delivered to multiple inboxes independently.  This follows standard
+ *     ActivityPub behavior and will be the default in Fedify 2.0.
+ *
+ * @since 1.9.0
+ */
+export type IdempotencyStrategy = "global" | "per-origin" | "per-inbox";
+
+/**
+ * A callback to generate a custom idempotency key for an activity.
+ * Returns the cache key to use, or null to skip idempotency checking.
+ * @template TContextData The context data to pass to the {@link InboxContext}.
+ * @param ctx The inbox context.
+ * @param activity The activity being processed.
+ * @returns The idempotency key to use for caching, or null to skip caching.
+ * @since 1.9.0
+ */
+export type IdempotencyKeyCallback<TContextData> = (
+  ctx: InboxContext<TContextData>,
+  activity: Activity,
+) => string | null | Promise<string | null>;
+
 /**
  * Registry for inbox listeners for different activity types.
  */
@@ -992,6 +1027,39 @@ export interface InboxListenerSetters<TContextData> {
   setSharedKeyDispatcher(
     dispatcher: SharedInboxKeyDispatcher<TContextData>,
   ): InboxListenerSetters<TContextData>;
+
+  /**
+   * Configures the strategy for handling activity idempotency in inbox processing.
+   *
+   * @example
+   * Use per-inbox strategy (standard ActivityPub behavior):
+   * ```
+   * federation
+   *   .setInboxListeners("/users/{identifier}/inbox", "/inbox")
+   *   .withIdempotency("per-inbox");
+   * ```
+   *
+   * Use custom strategy:
+   * ```
+   * federation
+   *   .setInboxListeners("/users/{identifier}/inbox", "/inbox")
+   *   .withIdempotency((ctx, activity) => {
+   *     // Return null to skip idempotency
+   *     return `${ctx.origin}:${activity.id?.href}:${ctx.recipient}`;
+   *   });
+   * ```
+   *
+   * @param strategy The idempotency strategy to use. Can be:
+   *   - `"global"`: Activities are deduplicated across all inboxes and origins
+   *   - `"per-origin"`: Activities are deduplicated per inbox origin
+   *   - `"per-inbox"`: Activities are deduplicated per inbox
+   *   - A custom callback function that returns the cache key to use
+   * @returns The setters object so that settings can be chained.
+   * @since 1.9.0
+   */
+  withIdempotency(
+    strategy: IdempotencyStrategy | IdempotencyKeyCallback<TContextData>,
+  ): InboxListenerSetters<TContextData>;
 }
 
 /**

packages/fedify/src/federation/handler.ts

@@ -39,7 +39,11 @@ import type {
 } from "./callback.ts";
 import type { PageItems } from "./collection.ts";
 import type { Context, InboxContext, RequestContext } from "./context.ts";
-import type { ConstructorWithTypeId } from "./federation.ts";
+import type {
+  ConstructorWithTypeId,
+  IdempotencyKeyCallback,
+  IdempotencyStrategy,
+} from "./federation.ts";
 import { type InboxListenerSet, routeActivity } from "./inbox.ts";
 import { KvKeyCache } from "./keycache.ts";
 import type { KvKey, KvStore } from "./kv.ts";
@@ -551,6 +555,9 @@ export interface InboxHandlerParameters<TContextData> {
   onNotFound(request: Request): Response | Promise<Response>;
   signatureTimeWindow: Temporal.Duration | Temporal.DurationLike | false;
   skipSignatureVerification: boolean;
+  idempotencyStrategy?:
+    | IdempotencyStrategy
+    | IdempotencyKeyCallback<TContextData>;
   tracerProvider?: TracerProvider;
 }
 
@@ -599,7 +606,10 @@ export async function handleInbox<TContextData>(
  */
 async function handleInboxInternal<TContextData>(
   request: Request,
-  {
+  parameters: InboxHandlerParameters<TContextData>,
+  span: Span,
+): Promise<Response> {
+  const {
     recipient,
     context: ctx,
     inboxContextFactory,
@@ -613,9 +623,7 @@ async function handleInboxInternal<TContextData>(
     signatureTimeWindow,
     skipSignatureVerification,
     tracerProvider,
-  }: InboxHandlerParameters<TContextData>,
-  span: Span,
-): Promise<Response> {
+  } = parameters;
   const logger = getLogger(["fedify", "federation", "inbox"]);
   if (actorDispatcher == null) {
     logger.error("Actor dispatcher is not set.", { recipient });
@@ -822,6 +830,7 @@ async function handleInboxInternal<TContextData>(
     queue,
     span,
     tracerProvider,
+    idempotencyStrategy: parameters.idempotencyStrategy,
   });
   if (routeResult === "alreadyProcessed") {
     return new Response(