@fedify/fedify 2.3.0-dev.994 → 2.3.0-pr.809.36

package/dist/{context-DJGagtNd.d.cts → context-BU6jSQdo.d.ts}

@@ -1,11 +1,15 @@
-import { o as JsonValue, s as NodeInfo, t as GetNodeInfoOptions } from "./client-z-8dc-e1.cjs";
-import { o as VerifyRequestFailureReason, t as HttpMessageSignaturesSpec } from "./http-CrGuipxe.cjs";
-import { n as GetKeyOwnerOptions } from "./owner-CptqhsOy.cjs";
-import { n as KvStore, t as KvKey } from "./kv-CbLNp3zQ.cjs";
+/// <reference lib="esnext.temporal" />
+import { o as JsonValue, s as NodeInfo, t as GetNodeInfoOptions } from "./client-CSddvgWN.js";
+import { o as VerifyRequestFailureReason, t as HttpMessageSignaturesSpec } from "./http-lf8Hsd91.js";
+import { n as GetKeyOwnerOptions } from "./owner-CnngXDNJ.js";
+import { n as KvStore, t as KvKey } from "./kv-D6hNiMTK.js";
+import { r as MessageQueue } from "./mq-D-nlpY04.js";
+import { Router } from "@fedify/uri-template";
 import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
+import { MeterProvider, Span, Tracer, TracerProvider } from "@opentelemetry/api";
 import { AuthenticatedDocumentLoaderFactory, DocumentLoader, DocumentLoaderFactory, GetUserAgentOptions } from "@fedify/vocab-runtime";
 import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fedify/webfinger";
-import { Span, Tracer, TracerProvider } from "@opentelemetry/api";
+import { MeterProvider as MeterProvider$1, MetricReader } from "@opentelemetry/sdk-metrics";
 
 //#region src/compat/types.d.ts
 /**
@@ -14,6 +18,177 @@ import { Span, Tracer, TracerProvider } from "@opentelemetry/api";
 */
 type ActivityTransformer<TContextData> = (activity: Activity, context: Context<TContextData>) => Activity;
 //#endregion
+//#region src/federation/circuit-breaker.d.ts
+/**
+* The state of a remote host circuit breaker.
+* @since 2.3.0
+*/
+type CircuitBreakerState = "closed" | "open" | "half-open";
+/**
+* The JSON-serializable state stored in the configured {@link KvStore}.
+* @since 2.3.0
+*/
+interface CircuitBreakerKvState {
+  readonly state: CircuitBreakerState;
+  readonly failures: readonly string[];
+  readonly opened?: string;
+  readonly halfOpened?: string;
+}
+/**
+* Details passed to {@link CircuitBreakerOptions.onActivityDrop} when a held
+* activity expires before the remote host recovers.
+* @since 2.3.0
+*/
+interface CircuitBreakerActivityDrop {
+  /** The inbox URL that would have received the activity. */
+  readonly inbox: URL;
+  /** The activity that was dropped. */
+  readonly activity: Activity;
+  /** The activity ID, when known. */
+  readonly activityId?: string;
+  /** The activity type. */
+  readonly activityType: string;
+  /** The actor IDs represented by this inbox. */
+  readonly actorIds: readonly URL[];
+  /** The time when Fedify first held this activity. */
+  readonly heldSince: Temporal.Instant;
+}
+/**
+* Configures how a remote host circuit opens after repeated delivery
+* failures.
+* @since 2.3.0
+*/
+type CircuitBreakerFailurePolicy = {
+  failure(timestamps: readonly Temporal.Instant[]): boolean;
+  readonly failureThreshold?: never;
+  readonly failureWindow?: never;
+} | {
+  readonly failure?: never;
+  readonly failureThreshold?: number;
+  readonly failureWindow?: Temporal.Duration | Temporal.DurationLike;
+};
+/**
+* Options for Fedify's outbound activity circuit breaker.
+* @since 2.3.0
+*/
+type CircuitBreakerOptions = CircuitBreakerFailurePolicy & {
+  /**
+  * How long an open circuit waits before allowing a half-open recovery probe.
+  * @default `{ minutes: 30 }`
+  */
+  readonly recoveryDelay?: Temporal.Duration | Temporal.DurationLike;
+  /**
+  * How long Fedify keeps requeueing activities held by an open circuit before
+  * dropping them.
+  * @default `{ days: 7 }`
+  */
+  readonly heldActivityTtl?: Temporal.Duration | Temporal.DurationLike;
+  /**
+  * How often other held activities retry while a half-open probe is in
+  * flight.  The probe is treated as stale after the recovery delay.
+  * @default `{ seconds: 1 }`
+  */
+  readonly releaseInterval?: Temporal.Duration | Temporal.DurationLike;
+  /**
+  * Called whenever the circuit state changes.
+  */
+  readonly onStateChange?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
+  /**
+  * Called when an activity held by the circuit breaker expires.
+  */
+  readonly onActivityDrop?: (remoteHost: string, details: CircuitBreakerActivityDrop) => void | Promise<void>;
+};
+/**
+* Normalized circuit breaker options used internally by Fedify.
+* @internal
+*/
+interface NormalizedCircuitBreakerOptions {
+  readonly failure: (timestamps: readonly Temporal.Instant[]) => boolean;
+  readonly pruneFailures: (timestamps: readonly Temporal.Instant[], now: Temporal.Instant) => readonly Temporal.Instant[];
+  readonly recoveryDelay: Temporal.Duration;
+  readonly heldActivityTtl: Temporal.Duration;
+  readonly releaseInterval: Temporal.Duration;
+  readonly onStateChange?: CircuitBreakerOptions["onStateChange"];
+  readonly onActivityDrop?: CircuitBreakerOptions["onActivityDrop"];
+}
+/**
+* Constructor options for {@link CircuitBreaker}.
+* @internal
+*/
+interface CircuitBreakerCreateOptions {
+  readonly kv: KvStore;
+  readonly prefix: KvKey;
+  readonly options?: CircuitBreakerOptions;
+  readonly now?: () => Temporal.Instant;
+  /**
+  * Observes state changes after user callbacks have run.
+  * @internal
+  */
+  readonly stateChangeObserver?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
+}
+/**
+* The delivery decision returned by {@link CircuitBreaker.beforeSend}.
+* @internal
+*/
+type CircuitBreakerBeforeSendDecision = {
+  readonly type: "send";
+  readonly probe: boolean;
+  readonly stateChange?: CircuitBreakerStateChange;
+} | {
+  readonly type: "hold";
+  readonly state: "open" | "half-open";
+  readonly delay: Temporal.Duration;
+  readonly heldSince: Temporal.Instant;
+} | {
+  readonly type: "drop";
+  readonly heldSince: Temporal.Instant;
+};
+/**
+* A circuit breaker state transition.
+* @since 2.3.0
+*/
+interface CircuitBreakerStateChange {
+  readonly previousState: CircuitBreakerState;
+  readonly newState: CircuitBreakerState;
+}
+/**
+* Tracks reachability state for remote outbox delivery hosts.
+* @since 2.3.0
+*/
+declare class CircuitBreaker {
+  #private;
+  constructor(options: CircuitBreakerCreateOptions);
+  get options(): NormalizedCircuitBreakerOptions;
+  capHeldDelay(heldSince: Temporal.Instant, delay: Temporal.Duration): Temporal.Duration;
+  beforeSend(remoteHost: string, message: {
+    readonly circuitHeldSince?: string;
+  }): Promise<CircuitBreakerBeforeSendDecision>;
+  recordSuccess(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
+  recordReachableFailure(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
+  recordFailure(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
+  dropActivity(remoteHost: string, details: CircuitBreakerActivityDrop): Promise<void>;
+  getState(remoteHost: string): Promise<CircuitBreakerKvState | undefined>;
+}
+/**
+* Normalizes user-provided circuit breaker options into the internal policy
+* shape used while processing queued outbox deliveries.
+*
+* @param options The public circuit breaker options supplied to Fedify.
+* @returns The normalized failure predicate, failure pruning function,
+* duration values, and optional callbacks with defaults applied.
+* @throws {RangeError} If any configured duration is not positive.
+* @throws {TypeError} If `failureThreshold` is not a positive integer.
+*/
+declare function normalizeCircuitBreakerOptions(options: CircuitBreakerOptions): NormalizedCircuitBreakerOptions;
+/**
+* Parses a value loaded from the circuit breaker KV store.
+*
+* @param value The raw KV value to validate.
+* @returns A circuit breaker state when `value` has a recognized state and
+* valid instant strings, or `undefined` when the stored value is malformed.
+*/
+declare function parseCircuitBreakerKvState(value: unknown): CircuitBreakerKvState | undefined;
+//#endregion
 //#region src/federation/collection.d.ts
 /**
 * A page of items.
@@ -80,13 +255,19 @@ declare class SendActivityError extends Error {
   */
   readonly responseBody: string;
   /**
+  * The response headers from the inbox.
+  * @since 2.3.0
+  */
+  readonly responseHeaders: Headers;
+  /**
   * Creates a new {@link SendActivityError}.
   * @param inbox The inbox URL.
   * @param statusCode The HTTP status code.
   * @param message The error message.
   * @param responseBody The response body.
+  * @param responseHeaders The response headers.
   */
-  constructor(inbox: URL, statusCode: number, message: string, responseBody: string);
+  constructor(inbox: URL, statusCode: number, message: string, responseBody: string, responseHeaders?: HeadersInit);
 }
 //#endregion
 //#region src/federation/callback.d.ts
@@ -309,11 +490,28 @@ type OutboxErrorHandler = (error: Error, activity: Activity | null) => void | Pr
 * @since 2.0.0
 */
 type OutboxPermanentFailureHandler<TContextData> = (context: Context<TContextData>, values: {
-  /** The inbox URL that failed. */readonly inbox: URL; /** The activity that failed to deliver. */
+  /**
+  * Why Fedify is giving up on delivery.
+  *
+  * `"http"` means the inbox returned a configured permanent-failure HTTP
+  * status.  `"circuit-breaker-ttl"` means the outbound circuit breaker held
+  * the activity until its retention period expired.
+  *
+  * @since 2.3.0
+  */
+  readonly reason: "http" | "circuit-breaker-ttl"; /** The inbox URL that failed. */
+  readonly inbox: URL; /** The activity that failed to deliver. */
   readonly activity: Activity; /** The error that occurred. */
   readonly error: SendActivityError; /** The HTTP status code returned by the inbox. */
   readonly statusCode: number;
   /**
+  * The time when the circuit breaker first held the activity, if
+  * {@link reason} is `"circuit-breaker-ttl"`.
+  *
+  * @since 2.3.0
+  */
+  readonly circuitHeldSince?: Temporal.Instant;
+  /**
   * The actor IDs that were supposed to receive the activity at this inbox.
   */
   readonly actorIds: readonly URL[];
@@ -380,172 +578,6 @@ type CustomCollectionCounter<TParam extends string, TContextData> = (context: Re
 */
 type CustomCollectionCursor<TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>) => string | null | Promise<string | null>;
 //#endregion
-//#region src/federation/mq.d.ts
-/**
-* Additional options for enqueuing a message in a queue.
-*
-* @since 0.5.0
-*/
-interface MessageQueueEnqueueOptions {
-  /**
-  * The delay before the message is enqueued.  No delay by default.
-  *
-  * It must not be negative.
-  */
-  readonly delay?: Temporal.Duration;
-  /**
-  * An optional key that ensures messages with the same ordering key are
-  * processed sequentially (one at a time).  Messages with different ordering
-  * keys (or no ordering key) may be processed in parallel.
-  *
-  * This is useful for ensuring that related messages are processed in order,
-  * such as ensuring that a `Delete` activity is processed after a `Create`
-  * activity for the same object.
-  *
-  * @since 2.0.0
-  */
-  readonly orderingKey?: string;
-}
-/**
-* Additional options for listening to a message queue.
-*
-* @since 1.0.0
-*/
-interface MessageQueueListenOptions {
-  /**
-  * The signal to abort listening to the message queue.
-  */
-  signal?: AbortSignal;
-}
-/**
-* An abstract interface for a message queue.
-*
-* @since 0.5.0
-*/
-interface MessageQueue {
-  /**
-  * Whether the message queue backend provides native retry mechanisms.
-  * When `true`, Fedify will skip its own retry logic and rely on the backend
-  * to handle retries. When `false` or omitted, Fedify will handle retries
-  * using its own retry policies.
-  *
-  * @default `false`
-  * @since 1.7.0
-  */
-  readonly nativeRetrial?: boolean;
-  /**
-  * Enqueues a message in the queue.
-  * @param message The message to enqueue.
-  * @param options Additional options for enqueuing the message.
-  */
-  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
-  /**
-  * Enqueues multiple messages in the queue.  This operation is optional,
-  * and may not be supported by all implementations.  If not supported,
-  * Fedify will invoke {@link enqueue} for each message.
-  *
-  * @param messages The messages to enqueue.
-  * @param options Additional options for enqueuing the messages.
-  */
-  enqueueMany?: (messages: readonly any[], options?: MessageQueueEnqueueOptions) => Promise<void>;
-  /**
-  * Listens for messages in the queue.
-  * @param handler The handler for messages in the queue.
-  * @param options Additional options for listening to the message queue.
-  * @returns A promise that resolves when the listening is done.  It never
-  *          rejects, and is resolved when the signal is aborted.  If no
-  *          signal is provided, it never resolves.
-  */
-  listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
-}
-/**
-* Additional options for {@link InProcessMessageQueue}.
-* @since 1.0.0
-*/
-interface InProcessMessageQueueOptions {
-  /**
-  * The interval to poll for messages in the queue.  5 seconds by default.
-  * @default `{ seconds: 5 }`
-  */
-  pollInterval?: Temporal.Duration | Temporal.DurationLike;
-}
-/**
-* A message queue that processes messages in the same process.
-* Do not use this in production as it does neither persist messages nor
-* distribute them across multiple processes.
-*
-* @since 0.5.0
-*/
-declare class InProcessMessageQueue implements MessageQueue {
-  #private;
-  /**
-  * In-process message queue does not provide native retry mechanisms.
-  * @since 1.7.0
-  */
-  readonly nativeRetrial = false;
-  /**
-  * Constructs a new {@link InProcessMessageQueue} with the given options.
-  * @param options Additional options for the in-process message queue.
-  */
-  constructor(options?: InProcessMessageQueueOptions);
-  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
-  enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;
-  listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
-}
-/**
-* A message queue that processes messages in parallel.  It takes another
-* {@link MessageQueue}, and processes messages in parallel up to a certain
-* number of workers.
-*
-* Actually, it's rather a decorator than a queue itself.
-*
-* Note that the workers do not run in truly parallel, in the sense that they
-* are not running in separate threads or processes.  They are running in the
-* same process, but are scheduled to run in parallel.  Hence, this is useful
-* for I/O-bound tasks, but not for CPU-bound tasks, which is okay for Fedify's
-* workloads.
-*
-* When using `ParallelMessageQueue`, the ordering guarantee is preserved
-* *only if* the underlying queue implementation delivers messages in a wrapper
-* format that includes the `__fedify_ordering_key__` property.  Currently,
-* only `DenoKvMessageQueue` and `WorkersMessageQueue` use this format.
-* For other queue implementations (e.g., `InProcessMessageQueue`,
-* `RedisMessageQueue`, `PostgresMessageQueue`, `SqliteMessageQueue`,
-* `AmqpMessageQueue`), the ordering key cannot be detected by
-* `ParallelMessageQueue`, so ordering guarantees are handled by those
-* implementations directly rather than at the `ParallelMessageQueue` level.
-*
-* Messages with the same ordering key will never be processed concurrently
-* by different workers, ensuring sequential processing within each key.
-* Messages with different ordering keys (or no ordering key) can still be
-* processed in parallel.
-*
-* @since 1.0.0
-*/
-declare class ParallelMessageQueue implements MessageQueue {
-  #private;
-  readonly queue: MessageQueue;
-  readonly workers: number;
-  /**
-  * Inherits the native retry capability from the wrapped queue.
-  * @since 1.7.0
-  */
-  readonly nativeRetrial?: boolean;
-  /**
-  * Constructs a new {@link ParallelMessageQueue} with the given queue and
-  * number of workers.
-  * @param queue The message queue to use under the hood.  Note that
-  *              {@link ParallelMessageQueue} cannot be nested.
-  * @param workers The number of workers to process messages in parallel.
-  * @throws {TypeError} If the given queue is an instance of
-  *                     {@link ParallelMessageQueue}.
-  */
-  constructor(queue: MessageQueue, workers: number);
-  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
-  enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;
-  listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
-}
-//#endregion
 //#region src/federation/handler.d.ts
 /**
 * Options for the {@link respondWithObject} and
@@ -578,91 +610,6 @@ declare function respondWithObject(object: Object$1, options?: RespondWithObject
 */
 declare function respondWithObjectIfAcceptable(object: Object$1, request: Request, options?: RespondWithObjectOptions): Promise<Response | null>;
 //#endregion
-//#region src/federation/router.d.ts
-/**
-* Options for the {@link Router}.
-* @since 0.12.0
-*/
-interface RouterOptions {
-  /**
-  * Whether to ignore trailing slashes when matching paths.
-  */
-  trailingSlashInsensitive?: boolean;
-}
-/**
-* The result of {@link Router.route} method.
-* @since 1.3.0
-*/
-interface RouterRouteResult {
-  /**
-  * The matched route name.
-  */
-  name: string;
-  /**
-  * The URL template of the matched route.
-  */
-  template: string;
-  /**
-  * The values extracted from the URL.
-  */
-  values: Record<string, string>;
-}
-/**
-* URL router and constructor based on URI Template
-* ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
-*/
-declare class Router {
-  #private;
-  /**
-  * Whether to ignore trailing slashes when matching paths.
-  * @since 1.6.0
-  */
-  trailingSlashInsensitive: boolean;
-  /**
-  * Create a new {@link Router}.
-  * @param options Options for the router.
-  */
-  constructor(options?: RouterOptions);
-  clone(): Router;
-  /**
-  * Checks if a path name exists in the router.
-  * @param name The name of the path.
-  * @returns `true` if the path name exists, otherwise `false`.
-  */
-  has(name: string): boolean;
-  /**
-  * Adds a new path rule to the router.
-  * @param template The path pattern.
-  * @param name The name of the path.
-  * @returns The names of the variables in the path pattern.
-  */
-  add(template: string, name: string): Set<string>;
-  /**
-  * Resolves a path name and values from a URL, if any match.
-  * @param url The URL to resolve.
-  * @returns The name of the path and its values, if any match.  Otherwise,
-  *          `null`.
-  */
-  route(url: string): RouterRouteResult | null;
-  /**
-  * Constructs a URL/path from a path name and values.
-  * @param name The name of the path.
-  * @param values The values to expand the path with.
-  * @returns The URL/path, if the name exists.  Otherwise, `null`.
-  */
-  build(name: string, values: Record<string, string>): string | null;
-}
-/**
-* An error thrown by the {@link Router}.
-*/
-declare class RouterError extends Error {
-  /**
-  * Create a new {@link RouterError}.
-  * @param message The error message.
-  */
-  constructor(message: string);
-}
-//#endregion
 //#region src/federation/builder.d.ts
 /**
 * Creates a new {@link FederationBuilder} instance.
@@ -726,6 +673,17 @@ interface OutboxMessage {
   readonly attempt: number;
   readonly headers: Readonly<Record<string, string>>;
   readonly orderingKey?: string;
+  /**
+  * Whether this message is currently held by the outbound circuit breaker.
+  * @internal
+  */
+  readonly circuitHeld?: true;
+  /**
+  * When Fedify first held this message because the remote host circuit was
+  * open.
+  * @internal
+  */
+  readonly circuitHeldSince?: string;
   readonly traceContext: Readonly<Record<string, string>>;
 }
 interface InboxMessage {
@@ -733,6 +691,42 @@ interface InboxMessage {
   readonly id: ReturnType<typeof crypto.randomUUID>;
   readonly baseUrl: string;
   readonly activity: unknown;
+  /**
+  * The normalized JSON-LD representation of a signed inbox activity that
+  * Fedify already compacted successfully while accepting the request.  Queue
+  * workers can reuse this producer-side parse cache under stricter loader or
+  * network constraints without changing the raw payload preserved for
+  * forwarding.
+  *
+  * This may exist even when {@link ldSignatureVerified} is `false`, because
+  * fallback-authenticated traffic and already-queued backlog items can still
+  * depend on the cached normalized form to avoid re-fetching remote custom
+  * contexts during worker processing.
+  *
+  * This is optional for backward compatibility with messages that were
+  * queued by older Fedify versions or that were already in a queue before
+  * upgrading.
+  *
+  * Fedify keeps this on the queued message itself instead of an external
+  * sidecar because generic queue backends do not provide reliable lifecycle
+  * guarantees for auxiliary storage across retries and redeliveries.
+  *
+  * @internal
+  */
+  readonly normalizedActivity?: unknown;
+  /**
+  * Whether the producer actually verified the Linked Data Signature before
+  * queueing this message.  This lets workers distinguish verified LDS replay
+  * from other authenticated inbox traffic that merely happened to include a
+  * signature block.  This provenance marker is separate from the optional
+  * normalizedActivity parse cache.
+  *
+  * `undefined` preserves backward compatibility with older queued messages
+  * that predate this marker.
+  *
+  * @internal
+  */
+  readonly ldSignatureVerified?: boolean;
   readonly started: string;
   readonly attempt: number;
   readonly identifier: string | null;
@@ -863,6 +857,12 @@ interface FederationKvPrefixes {
   * @since 2.1.0
   */
   readonly acceptSignatureNonce: KvKey;
+  /**
+  * The key prefix used for storing outbound delivery circuit breaker state.
+  * @default `["_fedify", "circuit"]`
+  * @since 2.3.0
+  */
+  readonly circuitBreaker: KvKey;
 }
 /**
 * Options for {@link FederationOptions.origin} when it is not a string.
@@ -884,8 +884,10 @@ interface FederationOrigin {
 }
 /**
 * Create a new {@link Federation} instance.
-* @param parameters Parameters for initializing the instance.
+* @param options Parameters for initializing the instance.
 * @returns A new {@link Federation} instance.
+* @throws {TypeError} If benchmark mode and `meterProvider` are both
+* specified.
 * @since 0.10.0
 */
 declare function createFederation<TContextData>(options: FederationOptions<TContextData>): Federation<TContextData>;
@@ -1370,7 +1372,10 @@ interface Federation<TContextData> extends Federatable<TContextData> {
 interface FederationBuilder<TContextData> extends Federatable<TContextData> {
   /**
   * Builds the federation object.
+  * @param options Parameters for initializing the federation object.
   * @returns The federation object.
+  * @throws {TypeError} If benchmark mode and `meterProvider` are both
+  * specified.
   */
   build(options: FederationOptions<TContextData>): Promise<Federation<TContextData>>;
 }
@@ -1408,6 +1413,25 @@ interface InboxChallengePolicy {
   nonceTtlSeconds?: number;
 }
 /**
+* Options for cooperative benchmark mode.
+* @since 2.3.0
+*/
+interface FederationBenchmarkOptions {
+  /**
+  * Server-controlled inbox URLs that the benchmark trigger endpoint may
+  * deliver to.
+  */
+  triggerSinks?: readonly (string | URL)[];
+  /**
+  * Whether the benchmark trigger endpoint may deliver to recipients outside
+  * {@link FederationBenchmarkOptions.triggerSinks}.
+  *
+  * Do not enable this option unless the benchmark endpoint is only reachable
+  * by a trusted benchmark controller.
+  */
+  allowUnsafeTriggerRecipients?: boolean;
+}
+/**
 * Options for creating a {@link Federation} object.
 * @template TContextData The context data to pass to the {@link Context}.
 * @since 1.6.0
@@ -1487,6 +1511,21 @@ interface FederationOptions<TContextData> {
   */
   allowPrivateAddress?: boolean;
   /**
+  * Whether to enable cooperative benchmark mode.  This mode exposes
+  * benchmark-only endpoints and relaxes selected defaults for benchmark
+  * targets.  Pass an object to configure benchmark trigger delivery.
+  * Do not enable this option in production.
+  *
+  * When enabled, {@link FederationOptions.allowPrivateAddress} defaults to
+  * `true` unless {@link FederationOptions.documentLoaderFactory} or
+  * {@link FederationOptions.contextLoaderFactory} is configured, and
+  * {@link FederationOptions.signatureTimeWindow} defaults to `false`.
+  *
+  * Turned off by default.
+  * @since 2.3.0
+  */
+  benchmarkMode?: boolean | FederationBenchmarkOptions;
+  /**
   * Options for making `User-Agent` strings for HTTP requests.
   * If a string is provided, it is used as the `User-Agent` header.
   * If an object is provided, it is passed to the {@link getUserAgent}
@@ -1566,6 +1605,16 @@ interface FederationOptions<TContextData> {
   */
   outboxRetryPolicy?: RetryPolicy;
   /**
+  * The circuit breaker for queued outbound activity delivery.  When enabled,
+  * Fedify tracks repeated failures per remote host and temporarily holds
+  * queued activities instead of repeatedly hammering an unreachable server.
+  *
+  * Passing `false` disables the circuit breaker.
+  *
+  * @since 2.3.0
+  */
+  circuitBreaker?: false | CircuitBreakerOptions;
+  /**
   * The retry policy for processing incoming activities.  By default, this
   * uses an exponential backoff strategy with a maximum of 10 attempts and a
   * maximum delay of 12 hours.
@@ -1594,6 +1643,12 @@ interface FederationOptions<TContextData> {
   * @since 1.3.0
   */
   tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider for recording metrics.  If not provided,
+  * the default global meter provider is used.
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
 }
 /**
 * Additional settings for the actor dispatcher.
@@ -1641,6 +1696,18 @@ interface ActorCallbackSetters<TContextData> {
   */
   mapAlias(mapper: ActorAliasMapper<TContextData>): ActorCallbackSetters<TContextData>;
   /**
+  * Maps a fixed path to a sentinel identifier.  It is useful for exposing
+  * a single, instance-level actor at a fixed path, such as `/actor` for
+  * a relay or `/bot` for a bot.
+  * @param path The fixed path to map to the identifier.
+  * @param identifier The sentinel identifier to map the path to.
+  * @returns The setters object so that settings can be chained.
+  * @throws {RouterError} If the provided path or identifier is invalid or fails
+  *                       runtime validation.
+  * @since 2.3.0
+  */
+  mapActorAlias(path: `/${string}`, identifier: string): ActorCallbackSetters<TContextData>;
+  /**
   * Specifies the conditions under which requests are authorized.
   * @param predicate A callback that returns whether a request is authorized.
   * @returns The setters object so that settings can be chained.
@@ -1999,6 +2066,11 @@ interface Context<TContextData> {
   */
   readonly tracerProvider: TracerProvider;
   /**
+  * The OpenTelemetry meter provider.
+  * @since 2.3.0
+  */
+  readonly meterProvider?: MeterProvider;
+  /**
   * The document loader for loading remote JSON-LD documents.
   */
   readonly documentLoader: DocumentLoader;
@@ -2496,9 +2568,12 @@ interface InboxContext<TContextData> extends Context<TContextData> {
   * Forwards a received activity to the recipients' inboxes.  The forwarded
   * activity will be signed in HTTP Signatures by the forwarder, but its
   * payload will not be modified, i.e., Linked Data Signatures and Object
-  * Integrity Proofs will not be added.  Therefore, if the activity is not
-  * signed (i.e., it has neither Linked Data Signatures nor Object Integrity
-  * Proofs), the recipient probably will not trust the activity.
+  * Integrity Proofs will not be added.  Even when Fedify internally
+  * normalizes a Linked Data Signature activity for parsing, this method still
+  * forwards the original received payload so the sender's signatures/proofs
+  * are preserved as-is.  Therefore, if the activity is not signed (i.e., it
+  * has neither Linked Data Signatures nor Object Integrity Proofs), the
+  * recipient probably will not trust the activity.
   * @param forwarder The forwarder's identifier or the forwarder's username
   *                  or the forwarder's key pair(s).
   * @param recipients The recipients of the activity.
@@ -2514,9 +2589,12 @@ interface InboxContext<TContextData> extends Context<TContextData> {
   * Forwards a received activity to the recipients' inboxes.  The forwarded
   * activity will be signed in HTTP Signatures by the forwarder, but its
   * payload will not be modified, i.e., Linked Data Signatures and Object
-  * Integrity Proofs will not be added.  Therefore, if the activity is not
-  * signed (i.e., it has neither Linked Data Signatures nor Object Integrity
-  * Proofs), the recipient probably will not trust the activity.
+  * Integrity Proofs will not be added.  Even when Fedify internally
+  * normalizes a Linked Data Signature activity for parsing, this method still
+  * forwards the original received payload so the sender's signatures/proofs
+  * are preserved as-is.  Therefore, if the activity is not signed (i.e., it
+  * has neither Linked Data Signatures nor Object Integrity Proofs), the
+  * recipient probably will not trust the activity.
   * @param forwarder The forwarder's identifier or the forwarder's username.
   * @param recipients In this case, it must be `"followers"`.
   * @param options Options for forwarding the activity.
@@ -2806,4 +2884,4 @@ interface ActorKeyPair extends CryptoKeyPair {
   readonly multikey: Multikey;
 }
 //#endregion
-export { ActorAliasMapper as $, FederationKvPrefixes as A, Router as B, IdempotencyKeyCallback as C, SendActivityError as Ct, ObjectCallbackSetters as D, digest as Dt, InboxListenerSetters as E, buildCollectionSynchronizationHeader as Et, RetryContext as F, respondWithObject as G, RouterOptions as H, RetryPolicy as I, InProcessMessageQueueOptions as J, respondWithObjectIfAcceptable as K, createExponentialBackoffPolicy as L, FederationQueueOptions as M, createFederation as N, OutboxListenerSetters as O, ActivityTransformer as Ot, CreateExponentialBackoffPolicyOptions as P, ParallelMessageQueue as Q, Message as R, FederationStartQueueOptions as S, WebFingerLinksDispatcher as St, InboxChallengePolicy as T, PageItems as Tt, RouterRouteResult as U, RouterError as V, RespondWithObjectOptions as W, MessageQueueEnqueueOptions as X, MessageQueue as Y, MessageQueueListenOptions as Z, Federatable as _, OutboxListenerErrorHandler as _t, GetSignedKeyOptions as a, CollectionCursor as at, FederationFetchOptions as b, UnverifiedActivityHandler as bt, ParseUriResult as c, CustomCollectionCursor as ct, SendActivityOptions as d, InboxListener as dt, ActorDispatcher as et, SendActivityOptionsForCollection as f, NodeInfoDispatcher as ft, CustomCollectionCallbackSetters as g, OutboxListener as gt, ConstructorWithTypeId as h, OutboxErrorHandler as ht, GetActorOptions as i, CollectionCounter as it, FederationOrigin as j, Rfc6570Expression as k, RequestContext as l, CustomCollectionDispatcher as lt, CollectionCallbackSetters as m, ObjectDispatcher as mt, Context as n, ActorKeyPairsDispatcher as nt, InboxContext as o, CollectionDispatcher as ot, ActorCallbackSetters as p, ObjectAuthorizePredicate as pt, InProcessMessageQueue as q, ForwardActivityOptions as r, AuthorizePredicate as rt, OutboxContext as s, CustomCollectionCounter as st, ActorKeyPair as t, ActorHandleMapper as tt, RouteActivityOptions as u, InboxErrorHandler as ut, Federation as v, OutboxPermanentFailureHandler as vt, IdempotencyStrategy as w, SenderKeyPair as wt, FederationOptions as x, UnverifiedActivityReason as xt, FederationBuilder as y, SharedInboxKeyDispatcher as yt, createFederationBuilder as z };
+export { CustomCollectionCursor as $, Rfc6570Expression as A, parseCircuitBreakerKvState as At, createFederationBuilder as B, FederationStartQueueOptions as C, CircuitBreakerFailurePolicy as Ct, InboxListenerSetters as D, CircuitBreakerStateChange as Dt, InboxChallengePolicy as E, CircuitBreakerState as Et, CreateExponentialBackoffPolicyOptions as F, ActorDispatcher as G, respondWithObject as H, RetryContext as I, AuthorizePredicate as J, ActorHandleMapper as K, RetryPolicy as L, FederationOrigin as M, FederationQueueOptions as N, ObjectCallbackSetters as O, NormalizedCircuitBreakerOptions as Ot, createFederation as P, CustomCollectionCounter as Q, createExponentialBackoffPolicy as R, FederationOptions as S, CircuitBreakerCreateOptions as St, IdempotencyStrategy as T, CircuitBreakerOptions as Tt, respondWithObjectIfAcceptable as U, RespondWithObjectOptions as V, ActorAliasMapper as W, CollectionCursor as X, CollectionCounter as Y, CollectionDispatcher as Z, Federatable as _, buildCollectionSynchronizationHeader as _t, GetSignedKeyOptions as a, ObjectDispatcher as at, FederationBuilder as b, CircuitBreakerActivityDrop as bt, ParseUriResult as c, OutboxListenerErrorHandler as ct, SendActivityOptions as d, UnverifiedActivityHandler as dt, CustomCollectionDispatcher as et, SendActivityOptionsForCollection as f, UnverifiedActivityReason as ft, CustomCollectionCallbackSetters as g, PageItems as gt, ConstructorWithTypeId as h, SenderKeyPair as ht, GetActorOptions as i, ObjectAuthorizePredicate as it, FederationKvPrefixes as j, ActivityTransformer as jt, OutboxListenerSetters as k, normalizeCircuitBreakerOptions as kt, RequestContext as l, OutboxPermanentFailureHandler as lt, CollectionCallbackSetters as m, SendActivityError as mt, Context as n, InboxListener as nt, InboxContext as o, OutboxErrorHandler as ot, ActorCallbackSetters as p, WebFingerLinksDispatcher as pt, ActorKeyPairsDispatcher as q, ForwardActivityOptions as r, NodeInfoDispatcher as rt, OutboxContext as s, OutboxListener as st, ActorKeyPair as t, InboxErrorHandler as tt, RouteActivityOptions as u, SharedInboxKeyDispatcher as ut, Federation as v, digest as vt, IdempotencyKeyCallback as w, CircuitBreakerKvState as wt, FederationFetchOptions as x, CircuitBreakerBeforeSendDecision as xt, FederationBenchmarkOptions as y, CircuitBreaker as yt, Message as z };