Fedify 2.3.0

Released on June 25, 2026.

@fedify/fedify

• Added mapActorAlias() method to ActorCallbackSetters interface to support fixed-path actor dispatchers. This is useful for exposing a single, instance-level actor at a fixed path, such as /actor for a relay or /bot for a bot, without leaking a sentinel identifier into the actor's URI. [#752, #753]

• Added optional MessageQueue.getDepth() support, using the new MessageQueueDepth return type, for reporting queue backlog depth. InProcessMessageQueue can now report queued messages, including ready and delayed counts, and ParallelMessageQueue delegates depth reporting to its wrapped queue when supported. [#735, #748]

• Added OpenTelemetry metrics for ActivityPub delivery attempts, permanent delivery failures, inbox listener processing duration, and HTTP Signature verification failures. Applications can pass the new meterProvider option to createFederation(), and Context.meterProvider exposes the provider available to request, inbox, and outbox code. [#316, #619, #755]

• Added the activitypub.delivery.failed span event to queued outbox delivery spans so retry and permanent-failure decisions include the remote host, attempt number, and HTTP status code when available. [#316, #619, #755]

• Breaking change: Changed the activitypub.activity.sent span event to record delivery metadata (activitypub.inbox.url and activitypub.activity.id) instead of the full activitypub.activity.json payload. FedifySpanExporter now stores outbound records from those attributes, and TraceActivityRecord.activityJson is present only when the span event includes full activity JSON. [#316, #619, #755]

• Added two OpenTelemetry histograms for signature verification: activitypub.signature.verification.duration measures end-to-end verification time for HTTP Signatures, Linked Data Signatures, and Object Integrity Proofs (including local key lookup and remote key fetches), and activitypub.signature.key_fetch.duration measures public key lookup duration separately so operators can isolate non-fetch verification work. Both instruments carry activitypub.signature.kind (http, linked_data, or object_integrity) and bounded result attributes; the verification histogram additionally carries spec-bounded http_signatures.algorithm, ld_signatures.type, or object_integrity_proofs.cryptosuite when known, plus http_signatures.failure_reason on rejected HTTP rows. [#316, #737, #769]

• Added OpenTelemetry HTTP server metrics for inbound requests handled by Federation.fetch(): fedify.http.server.request.count (Counter) and fedify.http.server.request.duration (Histogram). Both instruments carry http.request.method, fedify.endpoint, optional http.response.status_code, and optional fedify.route.template attributes so that operators can monitor aggregate request rate, latency, and status-code error rate even when traces are sampled. Attributes deliberately exclude raw URLs, query strings, and identifier values to keep cardinality bounded. [#316, #736, #757]

• Added OpenTelemetry metrics for ActivityPub collection requests handled by Federation.fetch() and custom collection handlers:

  • activitypub.collection.request (counter)
  • activitypub.collection.dispatch.duration (histogram)
  • activitypub.collection.page.items (histogram)
  • activitypub.collection.total_items (histogram)

  The metrics expose bounded collection dimensions: activitypub.collection.kind, activitypub.collection.page, activitypub.collection.result, fedify.collection.dispatcher, and optional http.response.status_code. Built-in collections are classified as inbox, outbox, following, followers, liked, featured, or featured_tags; application-defined collection routes are collapsed into custom. Collection IDs, cursors, custom route names, actor identifiers, and full URLs are deliberately excluded so dashboards can aggregate collection rate, latency, item counts, and totalItems values without attacker-controlled cardinality. [#316, #741, #777]

• Added OpenTelemetry queue task metrics covering Fedify's enqueue and worker boundaries for inbox, outbox, and fanout work:

  • fedify.queue.task.enqueued (counter)
  • fedify.queue.task.started (counter)
  • fedify.queue.task.completed (counter)
  • fedify.queue.task.failed (counter)
  • fedify.queue.task.duration (histogram)
  • fedify.queue.task.in_flight (up/down counter, process local)

  Instruments carry fedify.queue.role, best-effort fedify.queue.backend (the queue implementation's constructor name), and fedify.queue.native_retrial. The enqueue/started/completed/ failed/duration instruments additionally carry activitypub.activity.type whenever Fedify knows the activity type for the queued message; the in-flight up/down counter deliberately omits per-message attributes so that increment and decrement operations always pair up cleanly per attribute series. Enqueue measurements additionally carry fedify.queue.task.attempt for retries, and the completion-side instruments carry fedify.queue.task.result (completed, failed, or aborted). Together with MessageQueue.getDepth() reporting, these metrics let operators distinguish a slow-draining queue from a queue that sees less traffic. [#316, #740, #759]

• Added OpenTelemetry metrics for ActivityPub fanout and activity lifecycle events, complementing the per-recipient activitypub.delivery.* counters and the per-task fedify.queue.task.* metrics with an activity-level view of inbox and outbox pressure:

  • activitypub.fanout.recipients (histogram) records the number of recipient inboxes produced by a single fanout enqueue.
  • activitypub.inbox.activity (counter) classifies an inbound activity via the new activitypub.processing.result attribute as queued, processed, retried, rejected, or abandoned.
  • activitypub.outbox.activity (counter) classifies an outbound activity as queued, retried, or abandoned. Per-recipient sent/failed rows remain on activitypub.delivery.sent and activitypub.delivery.permanent_failure and are not duplicated.

  The lifecycle counters cover only Fedify-managed events: queue backends with nativeRetrial defer retry handling and therefore do not record retried or abandoned. Recipient URLs, actor IDs, and other high-cardinality identifiers are deliberately excluded from the fanout histogram. [#316, #742, #770]

• Added OpenTelemetry metrics for public key lookups, remote JSON-LD document fetches, and lookupObject() calls so operators can observe how often Fedify hits the cache, how long remote fetches take, and how lookupObject() resolutions split between actors, non-actor objects, and unresolved lookups:

  • activitypub.key.lookup (counter) and activitypub.key.lookup.duration (histogram) cover every public key lookup performed by fetchKey() / fetchKeyDetailed(), including signature verification paths.
  • activitypub.document.fetch (counter) and activitypub.document.fetch.duration (histogram) cover every Fedify-wrapped document or context loader invocation, including the authenticated loader.
  • activitypub.document.cache (counter) records hit or miss for each kvCache()-backed cache lookup.
  • activitypub.object.lookup (counter) records the parsed-result classification of every lookupObject() call as actor, object, or other.

  Instruments share an activitypub.lookup.kind and (where applicable) activitypub.lookup.result attribute drawn from small, spec-bounded enumerations. activitypub.remote.host records the URL host, including any non-default port; http.response.status_code is recorded when an HTTP response was observed; activitypub.cache.enabled is recorded on the key and document fetch metrics whenever Fedify can confidently report the cache layer's presence. Key IDs, actor IDs, object IDs, JSON-LD context URLs, full URLs, and fediverse handles are deliberately excluded so attacker-controlled remotes cannot inflate metric cardinality. The existing activitypub.signature.key_fetch.duration histogram (introduced in Fedify 2.3 for signature-scoped key-fetch latency, sliced by activitypub.signature.kind) remains in place; the new activitypub.key.lookup.duration is the general-purpose histogram that covers non-signature key fetches as well and adds http.response.status_code and a richer activitypub.lookup.result taxonomy. [#316, #738, #771]

• Added OpenTelemetry metrics for the WebFinger and actor handle discovery paths so operators can graph aggregate discovery rate, latency, and outcome mix without sampling spans:

  • webfinger.lookup (counter) and webfinger.lookup.duration (histogram) cover outgoing lookupWebFinger() calls.
  • webfinger.handle (counter) and webfinger.handle.duration (histogram) cover incoming WebFinger requests handled by Federation.fetch().
  • activitypub.actor.discovery (counter) and activitypub.actor.discovery.duration (histogram) cover getActorHandle() actor handle discovery.

  Each family carries a bounded result attribute (webfinger.lookup.result, webfinger.handle.result, or activitypub.actor.discovery.result) so operators can slice discovery failures by terminal outcome (found / not_found / invalid / network_error / error for outgoing lookups; resolved / invalid / not_found / tombstoned / error for incoming requests; resolved / not_found / error for actor discovery). webfinger.resource.scheme is bucketed to a small allow list (acct, http, https, mailto, or other) so an attacker-controlled query string cannot inflate metric cardinality; activitypub.remote.host records the URL host, including any non-default port. Full resource URIs, lookup URLs, and handle strings are deliberately excluded; they remain on the corresponding spans (webfinger.lookup, webfinger.handle, activitypub.get_actor_handle) for trace-level investigation.

  lookupWebFinger() and getActorHandle() follow the opt-in lookupObject() pattern: omitting the new meterProvider option emits no measurement. Applications that pass a meterProvider to createFederation() get the inbound webfinger.handle family and the federation-bound Context.lookupWebFinger() family wired up automatically. Direct getActorHandle() calls remain opt-in: pass meterProvider through GetActorHandleOptions to enable the discovery metrics, and the option is forwarded into the nested WebFinger lookups so one discovery emits both the discovery measurement and the underlying webfinger.lookup measurements (one for the actor ID host, plus a second for the alias host when cross-origin verification runs). [#316, #739, #772]

• Added an outbound delivery circuit breaker for queued outbox delivery. Fedify now tracks consecutive network and HTTP 5xx delivery failures per remote host (including any non-default port), stores the state in the configured KvStore, and requeues messages held by an open circuit instead of repeatedly sending to an unreachable server. The circuit breaker is enabled by default for queued outbox delivery and can be disabled with circuitBreaker: false; applications can customize the failure policy, recovery delay, held activity TTL, release interval, and state/drop callbacks. HTTP 429 responses do not count as circuit failures and Retry-After is respected when present. State changes are exposed through activitypub.circuit_breaker.state_change metrics and activitypub.circuit_breaker.state_change span events, and expired held activities call the outbox permanent failure handler with reason: "circuit-breaker-ttl". [#620, #778]

• Added benchmarkMode to createFederation() and FederationBuilder.build() for cooperative federation benchmarking. When enabled, Fedify exposes GET /.well-known/fedify/bench/stats for in-process OpenTelemetry metric snapshots and POST /.well-known/fedify/bench/trigger for driving sendActivity() to server-configured benchmark sink recipients. Benchmark mode also defaults allowPrivateAddress to true when built-in loaders are used, defaults signatureTimeWindow to false, reports queue depth through the new fedify.queue.depth gauge, and adds explicit low-latency buckets to the signature verification duration histogram. [#744, #782, #787]

• Replaced Fedify's internal federation routing with @fedify/uri-template for stricter RFC 6570 URI Template expansion and matching. The deprecated Router export from @fedify/fedify remains available for compatibility. [#418, #758 by ChanHaeng Lee]

• Significantly sped up TypeScript type-checking by simplifying the internal path parameter types of the setObjectDispatcher(), setCollectionDispatcher(), and setOrderedCollectionDispatcher() methods. These methods previously expanded path into thousands of RFC 6570 template-literal variants, which dominated type-checking time; a full codebase type check now completes in roughly 13 seconds instead of around 99 seconds. The public dispatcher method signatures and runtime path validation are unchanged. This is a partial fix for #613 that targets the dispatcher overload hot path; other contributors to check-all cost may remain. [#613, #800 by ChanHaeng Lee]

@fedify/cli

• Added the --skip-install option to fedify init, following the corresponding @fedify/init update, which skips automatic dependency installation after scaffolding. [#720, #776 by fru1tworld]

• Switched Node.js and Bun projects generated by fedify init from Biome plus ESLint to Oxfmt plus Oxlint. New projects now get .oxfmtrc.json, .oxlintrc.json, Oxc editor recommendations, and package scripts for format, format:check, and lint; the Oxlint config loads Fedify's rules through @fedify/lint/oxlint. [#703, #818]

• Added the fedify bench command for benchmarking Fedify federation workloads. It acts as a synthetic remote actor that drives ActivityPub-specific load (signed inbox deliveries and WebFinger lookups) against a cooperative benchmarkMode target and reports latency, throughput, success rate, and errors, reading server-side metrics from the target's stats endpoint. Benchmarks are described by a YAML or JSON scenario suite validated against a published JSON Schema, with an expect block per scenario that gates a run for CI. The command refuses public non-benchmarkMode targets without an explicit unsafe override, supports discovery-aware --dry-run planning, and ships with a local benchmark fixture used by the scenario tests. [#744, #783, #784, #791]

• Added actor, object, fanout, failure, and mixed scenario runners to fedify bench. Read scenarios can now benchmark actor and object document fetches, including authenticated GET requests; fanout scenarios drive the benchmark trigger endpoint and wait for queue task drain; failure scenarios report expected fault outcomes as successes; and mixed scenarios run weighted child scenario blends. The collection scenario type remains reserved but not executable. Fanout and remote failure scenarios can set sinkBase to generate deterministic benchmark sink inbox URLs for targets that keep triggerSinks allowlisting enabled. This change is published as benchmark scenario schema version 2. [#744, #785, #801, #802]

• Hardened fedify bench safety planning and preflight checks. The command now resolves inbox destinations before load generation, treats unreadable or malformed resolver output conservatively, applies suite defaults consistently, and keeps the local benchmark fixture inside the CLI package for regression coverage. [#744, #795]

• Added fedify bench compare for CI-friendly performance regression gates. The command checks out base and head refs into temporary worktrees, starts the benchmark target for each ref, runs the same suite, and fails when the head regresses beyond --max-regression plus the measured per-run noise band. Benchmark scenarios now run three times by default and aggregate repeated runs with median latency/throughput and pessimistic correctness results. This change is published as benchmark report schema version 3 and comparison report schema version 1. [#744, #786, #804]

@fedify/backfill

• Added @fedify/backfill for reconstructing ActivityPub conversations. It supports FEP-f228 context collections containing post-like objects or Create activities, optional reply-tree traversal, ordered hybrid strategies, shared safety budgets, deduplication, and traversal-local document caching. [#275, #779, #801, #807, #816, #820 by Jiwon Kwon]

@fedify/fixture

• Added createTestMeterProvider() and TestMetricRecorder helpers for asserting OpenTelemetry metric measurements in runtime-agnostic tests. [#316, #619, #755]

@fedify/testing

• Added a meterProvider option to createFederation() so mock contexts can expose a test OpenTelemetry meter provider. [#316, #619, #755]

@fedify/uri-template

• Added @fedify/uri-template, a dependency-free RFC 6570 URI Template implementation for expansion, variable extraction, and round-trip route matching. This package replaces Fedify's previous direct use of url-template and uri-template-router. [#418, #758 by ChanHaeng Lee]

@fedify/amqp

• Added AmqpMessageQueue.getDepth() for reporting queued, ready, and delayed message counts. Delayed counts include queues created or tracked by the same AmqpMessageQueue instance. [#735, #748]

@fedify/mysql

• Added MysqlMessageQueue.getDepth() for reporting queued, ready, and delayed message counts. [#735, #748]

@fedify/postgres

• Added PostgresMessageQueue.getDepth() for reporting queued, ready, and delayed message counts. [#735, #748]

@fedify/redis

• Added RedisMessageQueue.getDepth() for reporting queued, ready, and delayed message counts. [#735, #748]

@fedify/sqlite

• Added SqliteMessageQueue.getDepth() for reporting queued, ready, and delayed message counts. [#735, #748]

@fedify/init

• Added a --skip-install option to fedify init that skips automatic dependency installation after scaffolding. This is useful for CI environments, monorepo workspaces that install dependencies from the root, or when you want to inspect the generated files before installing. [#720, #776 by fru1tworld]

• Switched generated Node.js and Bun projects from Biome plus ESLint to Oxfmt plus Oxlint. New projects now get .oxfmtrc.json, .oxlintrc.json, Oxc editor recommendations, and package scripts for format, format:check, and lint; the Oxlint config loads Fedify's rules through @fedify/lint/oxlint. [#703, #818]

@fedify/lint

• Added official Oxlint support through a new @fedify/lint/oxlint subpath export, which exposes Fedify's lint rules in the shape Oxlint's JS plugin API expects. Previously, using @fedify/lint from Oxlint required a local wrapper module to re-export the plugin object as the default export; the new entrypoint removes that friction. The rules are reused verbatim from the ESLint plugin, and the existing Deno and ESLint root exports are unchanged. Note that Oxlint's JS plugin support is still alpha upstream. [#702, #760 by NyanRus]

@fedify/vocab-runtime

• Added PropertyPreprocessor, PropertyPreprocessorContext, and Json types for normalizing wire-level JSON-LD property values before the generated range decoder runs. [#792]

@fedify/vocab

• Explicit ActivityStreams Link objects in icon and image properties are now normalized to Image during decoding via the new exported normalizeLinkToImage() preprocessor. The public Image-oriented TypeScript API is unchanged. [#790, #792]

• The generated fromJsonLd() methods no longer resolve blank node identifiers (_:b0) against options.baseUrl; blank nodes are left as null in the resulting instance's id field. [#792]

• Added the second-stage vocabulary types for FEP-0837, economic resource coordination in federated networks. [#775, #817 by Samuel Brinkmann]

  • Added Agreement class, representing the agreement reached between parties responding to a Proposal, wrapped in an Offer and finalized as the result of an Accept.
  • Added Commitment class, representing a promised economic transaction that references an Intent via satisfies and carries the committed quantity via resourceQuantity.

@fedify/vocab-tools

• Property schemas now support a preprocessors field that lists module/function pairs. Generated decoders statically import and run these preprocessors for each expanded JSON-LD property value before falling back to the normal range decoder. [#792]

• The generated base class now stores the baseUrl from fromJsonLd() as a protected _baseUrl field. This URL is used to resolve relative URIs when cached embedded property documents are re-parsed lazily by accessors like getIcon(), so that callers do not need to pass an explicit baseUrl. The stored URL is defensively copied so that mutation of the caller's original URL object does not affect later resolution. [#792]

Documentation and examples

• Rebuilt the documentation home page on VitePress 2 with a custom Fedify landing page, package-manager-specific installation commands, richer feature sections, linked fediverse software logos, Sovereign Tech Agency credit, and a generated Open Graph image. [#809]

• Added a production monitoring guide that turns Fedify's OpenTelemetry metrics into practical Prometheus queries, dashboard panels, and alerting rules for federation health, queue backlog, delivery failures, signature verification failures, and circuit breaker state. [#813]

• Added a runnable monitoring example at examples/monitoring/ with an OpenTelemetry Collector, Prometheus, Grafana dashboard provisioning, Prometheus alert rules, synthetic Fedify-shaped metrics, validation checks, and an optional Docker Compose smoke test. [#814]

Claude Code plugin

• Added a Claude Code plugin at claude-plugin/, installable with:

  /plugin marketplace add fedify-dev/fedify
  /plugin install fedify@fedify
  

  The plugin provides six slash commands (/fedify:fedify, /fedify:docs, /fedify:actor, /fedify:inbox, /fedify:migration, /fedify:fep) and two specialized agents (fedify-reviewer and fedify-debugger). The Agent Skills bundle lives canonically in claude-plugin/skills/fedify/ and is referenced from packages/fedify/skills/fedify/ via a symlink; the prepack script resolves the symlink to real files before packing so the published npm tarball is self-contained. [#489, #756]