@fedify/fedify 2.3.0-dev.1189 → 2.3.0-dev.1212

package/dist/{context-MgCh7YGu.d.ts → context-K9cg8oGx.d.ts}

@@ -17,6 +17,177 @@ import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fed
 */
 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.
@@ -83,13 +254,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
@@ -312,11 +489,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[];
@@ -478,6 +672,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 {
@@ -651,6 +856,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.
@@ -1354,6 +1565,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.
@@ -2623,4 +2844,4 @@ interface ActorKeyPair extends CryptoKeyPair {
   readonly multikey: Multikey;
 }
 //#endregion
-export { CustomCollectionDispatcher as $, FederationKvPrefixes as A, RespondWithObjectOptions as B, IdempotencyKeyCallback as C, ObjectCallbackSetters as D, InboxListenerSetters as E, RetryContext as F, ActorHandleMapper as G, respondWithObjectIfAcceptable as H, RetryPolicy as I, CollectionCounter as J, ActorKeyPairsDispatcher as K, createExponentialBackoffPolicy as L, FederationQueueOptions as M, createFederation as N, OutboxListenerSetters as O, CreateExponentialBackoffPolicyOptions as P, CustomCollectionCursor as Q, Message as R, FederationStartQueueOptions as S, InboxChallengePolicy as T, ActorAliasMapper as U, respondWithObject as V, ActorDispatcher as W, CollectionDispatcher as X, CollectionCursor as Y, CustomCollectionCounter as Z, Federatable as _, digest as _t, GetSignedKeyOptions as a, OutboxErrorHandler as at, FederationFetchOptions as b, ParseUriResult as c, OutboxPermanentFailureHandler as ct, SendActivityOptions as d, UnverifiedActivityReason as dt, InboxErrorHandler as et, SendActivityOptionsForCollection as f, WebFingerLinksDispatcher as ft, CustomCollectionCallbackSetters as g, buildCollectionSynchronizationHeader as gt, ConstructorWithTypeId as h, PageItems as ht, GetActorOptions as i, ObjectDispatcher as it, FederationOrigin as j, Rfc6570Expression as k, RequestContext as l, SharedInboxKeyDispatcher as lt, CollectionCallbackSetters as m, SenderKeyPair as mt, Context as n, NodeInfoDispatcher as nt, InboxContext as o, OutboxListener as ot, ActorCallbackSetters as p, SendActivityError as pt, AuthorizePredicate as q, ForwardActivityOptions as r, ObjectAuthorizePredicate as rt, OutboxContext as s, OutboxListenerErrorHandler as st, ActorKeyPair as t, InboxListener as tt, RouteActivityOptions as u, UnverifiedActivityHandler as ut, Federation as v, ActivityTransformer as vt, IdempotencyStrategy as w, FederationOptions as x, FederationBuilder as y, createFederationBuilder as z };
+export { CustomCollectionDispatcher as $, FederationKvPrefixes as A, ActivityTransformer as At, RespondWithObjectOptions as B, IdempotencyKeyCallback as C, CircuitBreakerKvState as Ct, ObjectCallbackSetters as D, NormalizedCircuitBreakerOptions as Dt, InboxListenerSetters as E, CircuitBreakerStateChange as Et, RetryContext as F, ActorHandleMapper as G, respondWithObjectIfAcceptable as H, RetryPolicy as I, CollectionCounter as J, ActorKeyPairsDispatcher as K, createExponentialBackoffPolicy as L, FederationQueueOptions as M, createFederation as N, OutboxListenerSetters as O, normalizeCircuitBreakerOptions as Ot, CreateExponentialBackoffPolicyOptions as P, CustomCollectionCursor as Q, Message as R, FederationStartQueueOptions as S, CircuitBreakerFailurePolicy as St, InboxChallengePolicy as T, CircuitBreakerState as Tt, ActorAliasMapper as U, respondWithObject as V, ActorDispatcher as W, CollectionDispatcher as X, CollectionCursor as Y, CustomCollectionCounter as Z, Federatable as _, digest as _t, GetSignedKeyOptions as a, OutboxErrorHandler as at, FederationFetchOptions as b, CircuitBreakerBeforeSendDecision as bt, ParseUriResult as c, OutboxPermanentFailureHandler as ct, SendActivityOptions as d, UnverifiedActivityReason as dt, InboxErrorHandler as et, SendActivityOptionsForCollection as f, WebFingerLinksDispatcher as ft, CustomCollectionCallbackSetters as g, buildCollectionSynchronizationHeader as gt, ConstructorWithTypeId as h, PageItems as ht, GetActorOptions as i, ObjectDispatcher as it, FederationOrigin as j, Rfc6570Expression as k, parseCircuitBreakerKvState as kt, RequestContext as l, SharedInboxKeyDispatcher as lt, CollectionCallbackSetters as m, SenderKeyPair as mt, Context as n, NodeInfoDispatcher as nt, InboxContext as o, OutboxListener as ot, ActorCallbackSetters as p, SendActivityError as pt, AuthorizePredicate as q, ForwardActivityOptions as r, ObjectAuthorizePredicate as rt, OutboxContext as s, OutboxListenerErrorHandler as st, ActorKeyPair as t, InboxListener as tt, RouteActivityOptions as u, UnverifiedActivityHandler as ut, Federation as v, CircuitBreaker as vt, IdempotencyStrategy as w, CircuitBreakerOptions as wt, FederationOptions as x, CircuitBreakerCreateOptions as xt, FederationBuilder as y, CircuitBreakerActivityDrop as yt, createFederationBuilder as z };

package/dist/{deno-BomxIkHS.mjs → deno-DTaoLXHr.mjs}

@@ -3,6 +3,6 @@ import "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
 //#region deno.json
 var name = "@fedify/fedify";
-var version = "2.3.0-dev.1189+97e55e59";
+var version = "2.3.0-dev.1212+3737de7f";
 //#endregion
 export { version as n, name as t };

package/dist/{docloader-CzS6F5sZ.mjs → docloader-CdNiXmNg.mjs}

@@ -1,8 +1,8 @@
 import "@js-temporal/polyfill";
 import "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
-import { o as validateCryptoKey } from "./key-CT2NnJuR.mjs";
-import { n as doubleKnock } from "./http-DtWN_XvX.mjs";
+import { o as validateCryptoKey } from "./key-Bhsx9PrC.mjs";
+import { n as doubleKnock } from "./http-ByCfCX5K.mjs";
 import { getLogger } from "@logtape/logtape";
 import { UrlError, createActivityPubRequest, getRemoteDocument, logRequest, validatePublicUrl } from "@fedify/vocab-runtime";
 import { curry } from "es-toolkit";

package/dist/federation/builder.test.mjs

@@ -5,7 +5,7 @@ import { t as assertEquals } from "../assert_equals-C-ZRDbaf.mjs";
 import { r as assertExists } from "../std__assert-BBjXFNOb.mjs";
 import { t as assertThrows } from "../assert_throws-BOkhLGYc.mjs";
 import { t as MemoryKvStore } from "../kv-x2IvBUyq.mjs";
-import { r as createFederationBuilder } from "../builder-Dc6s3gPe.mjs";
+import { r as createFederationBuilder } from "../builder-DdbtvTFp.mjs";
 import { DisallowedOperatorError, DisallowedVarSpecModifierError, DuplicateRouteVariableError, RouteTemplateOptionsNotMatchedError, RouterError } from "@fedify/uri-template";
 import { Activity, Note, Person } from "@fedify/vocab";
 import { test } from "@fedify/fixture";

package/dist/federation/circuit-breaker.test.d.mts

@@ -0,0 +1,2 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { URLPattern } from "urlpattern-polyfill";