---
url: /cli.md
description: >-
  The fedify command is a CLI toolchain for Fedify and debugging
  ActivityPub-enabled federated server apps.  This section explains the key
  features of the fedify command.
---

# `fedify`: CLI toolchain

The `fedify` command is a CLI toolchain for Fedify and debugging
ActivityPub-enabled federated server apps.  Although it is primarily designed
for developers who use Fedify, it can be used with any ActivityPub-enabled
server.

## Installation

### Using npm

If you have [Node.js] or [Bun] installed, you can install `fedify` by running
the following command:

::: code-group

```sh [npm]
npm install -g @fedify/cli
```

```sh [Bun]
bun install -g @fedify/cli
```

:::

[Node.js]: https://nodejs.org/

[Bun]: https://bun.sh/

### Using Homebrew on macOS and Linux

If you are using macOS or Linux and have [Homebrew] installed, you can install
`fedify` by running the following command:

```sh
brew install fedify
```

[Homebrew]: https://brew.sh/

### Using Scoop on Windows

If you are using Windows and have [Scoop] installed, you can install `fedify`
by running the following command:

```powershell
scoop install fedify
```

[Scoop]: https://scoop.sh/

### Using Deno

If you have [Deno] installed, you can install `fedify` by running the following
command:

::: code-group

```sh [Linux]
deno install \
  -gA \
  --unstable-fs --unstable-kv \
  -n fedify \
  jsr:@fedify/cli
```

```sh [macOS]
deno install \
  -gA \
  --unstable-fs --unstable-kv \
  -n fedify \
  jsr:@fedify/cli
```

```powershell [Windows]
deno install `
  -gA `
  --unstable-fs --unstable-kv `
  -n fedify `
  jsr:@fedify/cli
```

:::

On Deno versions earlier than 2.7.0, add `--unstable-temporal` to the install
command above.

[Deno]: https://deno.com/

### Downloading the executable

You can download the pre-built executables from the [releases] page.  Download
the appropriate executable for your platform and put it in your `PATH`.

[releases]: https://github.com/fedify-dev/fedify/releases

## Configuration file

*This feature is available since Fedify 2.0.0.*

The `fedify` command supports configuration files to set default values for
command options.  Configuration files are written in [TOML] format.

[TOML]: https://toml.io/

### Configuration file locations

Configuration files are loaded from the following locations in order, with
later files taking precedence over earlier ones:

1. System-wide configuration directories (see below)
2. *~/.config/fedify/config.toml* (user-level, or
   `$XDG_CONFIG_HOME/fedify/config.toml`)
3. *.fedify.toml* in the current working directory (project-level)
4. Custom path specified via `--config` option (highest precedence)

The system-wide and user-level config paths vary by operating system:

* **Linux/macOS (system)**: Directories listed in `$XDG_CONFIG_DIRS`
  (default: */etc/xdg/fedify/config.toml*)
* **Linux/macOS (user)**: `$XDG_CONFIG_HOME/fedify/config.toml`
  (default: *~/.config/fedify/config.toml*)
* **Windows (system)**: *%ProgramData%\fedify\config.toml*
* **Windows (user)**: *%APPDATA%\fedify\config.toml*

### `--config`: Load an additional configuration file

You can specify an additional configuration file to load using the `--config`
option:

```sh
fedify --config ./my-config.toml lookup @user@example.com
```

This file is loaded after all standard configuration files and takes the
highest precedence.

### `--ignore-config`: Ignore all configuration files

The `--ignore-config` option skips loading all configuration files.  This is
useful for CI environments or when you want reproducible behavior:

```sh
fedify --ignore-config lookup @user@example.com
```

### Configuration file structure

Below is an example configuration file showing all available options:

```toml
# Global settings (apply to all commands)
debug = false
userAgent = "MyApp/1.0"
tunnelService = "localhost.run"  # "localhost.run", "serveo.net", or "pinggy.io"

[webfinger]
allowPrivateAddress = false
maxRedirection = 5

[lookup]
authorizedFetch = false
firstKnock = "draft-cavage-http-signatures-12"  # or "rfc9421"
allowPrivateAddress = false
traverse = false
suppressErrors = false
reverse = false
defaultFormat = "default"  # "default", "raw", "compact", or "expand"
separator = "----"
timeout = 30  # seconds

[inbox]
actorName = "Fedify Ephemeral Actor"
actorSummary = "An ephemeral actor for testing purposes."
authorizedFetch = false
noTunnel = false
follow = ["@user@example.com"]
acceptFollow = ["*"]

[relay]
protocol = "mastodon"  # or "litepub"
port = 8000
name = "Fedify Relay"
persistent = "/path/to/relay.db"  # optional, uses in-memory if not specified
noTunnel = false
acceptFollow = ["*"]
rejectFollow = []

[nodeinfo]
raw = false
bestEffort = false
showFavicon = true
showMetadata = false
```

All configuration options are optional.  Command-line arguments always take
precedence over configuration file values.

## `fedify init`: Initializing a Fedify project

*This command is available since Fedify 0.12.0.*

[![The “fedify init” command demo](https://asciinema.org/a/671658.svg)](https://asciinema.org/a/671658)

The `fedify init` command is used to initialize a new Fedify project.
It creates a new directory with the necessary files and directories for a
Fedify project.  To create a new Fedify project, run the below command:

```sh
fedify init my-fedify-project
```

The above command will start the interactive prompt to initialize a new Fedify
project.  It will ask you a few questions to set up the project:

* Web framework: Bare-bones, [Hono], [Elysia], [Express], [Nitro], [Next.js],
  or [Astro]
* Package manager: [Deno], [Bun], [npm], [pnpm], or [Yarn]
* Message queue: In-Process, [Redis], [PostgreSQL], [AMQP] (e.g., [RabbitMQ]),
  or [Deno KV] (if Deno)
* Key–value store: In-Memory, [Redis], [PostgreSQL], or [Deno KV] (if Deno)

> \[!TIP]
> Projects created with `fedify init` automatically include [`@fedify/lint`]
> for consistent code linting.  Deno projects get a lint plugin configured in
> *deno.json*, while Node.js and Bun projects get an *eslint.config.ts* with
> `@fedify/lint`.

> \[!NOTE]
> If you find the full `@fedify/cli` toolchain too heavy for your needs, you
> can use [`@fedify/create`] instead to scaffold a new Fedify project without
> installing the CLI globally.  See the
> [*Alternative: Using `@fedify/create`*](./install.md#alternative-using-fedify-create)
> section for details.

Alternatively, you can specify the options in the command line to skip some of
interactive prompts:

[Hono]: https://hono.dev/

[Elysia]: https://elysiajs.com/

[Express]: https://expressjs.com/

[Nitro]: https://nitro.unjs.io/

[Next.js]: https://nextjs.org/

[Astro]: https://astro.build/

[npm]: https://www.npmjs.com/

[pnpm]: https://pnpm.io/

[Yarn]: https://yarnpkg.com/

[Redis]: https://redis.io/

[PostgreSQL]: https://www.postgresql.org/

[AMQP]: https://www.amqp.org/

[RabbitMQ]: https://www.rabbitmq.com/

[Deno KV]: https://deno.com/kv

[`@fedify/lint`]: /manual/lint

[`@fedify/create`]: https://www.npmjs.com/package/@fedify/create

### `-p`/`--package-manager`: Package manager

You can specify the package manager by using the `-p`/`--package-manager`
option.  The available options are:

* `deno`: [Deno]
* `pnpm`: [pnpm]
* `bun`: [Bun]
* `yarn`: [Yarn]
* `npm`: [npm]

### `-w`/`--web-framework`: Web framework

You can specify the web framework to integrate with Fedify by using
the `-w`/`--web-framework` option.  The available options are:

* `bare-bones`: A minimal setup without any web framework integration, but in
  Node.js, [Hono] is used for a simple adapter for a lightweight experience.
* `hono`: [Hono]
* `nitro`: [Nitro]
* `next`: [Next.js]
* `elysia`: [Elysia]
* `astro`: [Astro]
* `express`: [Express]

### `-k`/`--kv-store`: key–value store

You can specify the key–value store to use by using the `-k`/`--kv-store`
option.  The available options are:

* `in-memory`: An in-memory key–value store that does not persist data across
  restarts.  This is useful for testing and development purposes.
* `redis`: [Redis]
* `postgres`: [PostgreSQL]
* `denokv`: [Deno KV] (if Deno)

### `-m`/`--message-queue`: Message queue

You can specify the message queue to use by using the `-m`/`--message-queue`
option.  The available options are:

* `in-process`: An in-process message queue that does not persist messages
  across restarts.  This is useful for testing and development purposes.
* `redis`: [Redis]
* `postgres`: [PostgreSQL]
* `amqp`: [AMQP] (e.g., [RabbitMQ])
* `denokv`: [Deno KV] (if Deno)

### `--dry-run`: Preview without creating files

*This option is available since Fedify 1.8.0.*

The `--dry-run` option allows you to preview what files and configurations would
be created without actually creating them.  This is useful for reviewing the
project structure before committing to the initialization.

```sh
fedify init my-fedify-project --dry-run
```

When using `--dry-run`, the command will:

* Display all files that would be created with their contents
* Show which dependencies would be installed
* Preview any commands that would be executed
* Not create any directories or files on your filesystem

This option works with all other initialization options, allowing you to preview
different configurations before making a decision.

## `fedify lookup`: Looking up an ActivityPub object

The `fedify lookup` command is used to look up an ActivityPub object by its URL
or an actor by its handle.

For example, the below command looks up a `Note` object with the given URL:

```sh
fedify lookup https://todon.eu/@hongminhee/112341925069749583
```

The output will be like the below:

```
Note {
  id: URL "https://todon.eu/users/hongminhee/statuses/112341925069749583",
  attachments: [
    Document {
      name: "The demo video on my terminal",
      url: URL "https://todon.eu/system/media_attachments/files/112/341/916/300/016/369/original/f83659866f94054f.mp"... 1 more character,
      mediaType: "video/mp4"
    }
  ],
  attribution: URL "https://todon.eu/users/hongminhee",
  contents: [
    '<p>I&#39;m working on adding a CLI toolchain to <a href="https://todon.eu/tags/Fedify" class="mentio'... 379 more characters,
    <en> '<p>I&#39;m working on adding a CLI toolchain to <a href="https://todon.eu/tags/Fedify" class="mentio'... 379 more characters
  ],
  published: 2024-04-27T07:08:57Z,
  replies: Collection {
    id: URL "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies",
    first: CollectionPage {
      items: [
        URL "https://todon.eu/users/hongminhee/statuses/112343493232608516"
      ],
      partOf: URL "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies",
      next: URL "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies?min_id=112343493232608516&page"... 5 more characters
    }
  },
  url: URL "https://todon.eu/@hongminhee/112341925069749583",
  to: URL "https://www.w3.org/ns/activitystreams#Public",
  cc: URL "https://todon.eu/users/hongminhee/followers",
  sensitive: false
}
```

### Looking up an actor by handle

You can also look up an actor by its handle or URL.  For example, the below
command looks up an actor with the given handle:

```sh
fedify lookup @fedify-example@fedify-blog.deno.dev
```

The output will be like the below:

```
Person {
  id: URL "https://fedify-blog.deno.dev/users/fedify-example",
  name: "Fedify Example Blog",
  published: 2024-03-03T13:18:11.857384756Z,
  summary: "This blog is powered by Fedify, a fediverse server framework.",
  url: URL "https://fedify-blog.deno.dev/",
  preferredUsername: "fedify-example",
  publicKey: CryptographicKey {
    id: URL "https://fedify-blog.deno.dev/users/fedify-example#main-key",
    owner: URL "https://fedify-blog.deno.dev/users/fedify-example",
    publicKey: CryptoKey {
      type: "public",
      extractable: true,
      algorithm: {
        name: "RSASSA-PKCS1-v1_5",
        modulusLength: 4096,
        publicExponent: Uint8Array(3) [ 1, 0, 1 ],
        hash: { name: "SHA-256" }
      },
      usages: [ "verify" ]
    }
  },
  inbox: URL "https://fedify-blog.deno.dev/users/fedify-example/inbox",
  outbox: URL "https://fedify-blog.deno.dev/users/fedify-example/outbox",
  following: URL "https://fedify-blog.deno.dev/users/fedify-example/following",
  followers: URL "https://fedify-blog.deno.dev/users/fedify-example/followers",
  endpoints: Endpoints { sharedInbox: URL "https://fedify-blog.deno.dev/inbox" },
  discoverable: true,
  suspended: false,
  memorial: false,
  indexable: true
}
```

You can omit the `@` prefix when looking up an actor by handle:

```sh
fedify lookup fedify-example@fedify-blog.deno.dev
```

Or you can look up an actor by `acct:` URL:

```sh
fedify lookup acct:fedify-example@fedify-blog.deno.dev
```

### Looking up multiple objects at once

You can also look up multiple objects at once by specifying multiple URLs or
handles.  For example, the below command looks up multiple objects:

```sh
fedify lookup @hongminhee@fosstodon.org @fedify@hollo.social
```

The output will be like the below:

```
Person {
  ...
}
----
Person {
  ...
}
```

As you can see, the outputs are separated by `----` by default.  You can change
the separator by using the [`-s`/`--separator`](#s-separator-output-separator)
option.

### `-t`/`--traverse`: Traverse the collection

*This option is available since Fedify 0.14.0.*

The `-t`/`--traverse` option is used to traverse the collection when looking up
a collection object.  For example, the below command looks up a collection
object:

```sh
fedify lookup --traverse https://fosstodon.org/users/hongminhee/outbox
```

The difference between with and without the `-t`/`--traverse` option is that
the former will output the objects in the collection, while the latter will
output the collection object itself.

When this option is enabled, each argument has to resolve to a collection.

### `--recurse`: Recurse through object relationships

*This option is available since Fedify 2.1.0.*

The `--recurse` option is used to recursively follow an object relationship.
This is useful when you want to walk a reply chain through `replyTarget`, or
follow quote relationships through `quoteUrl`.

```sh
fedify lookup --recurse=replyTarget https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf
```

You can also provide the fully qualified property IRI:

```sh
fedify lookup --recurse=https://www.w3.org/ns/activitystreams#inReplyTo https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf
```

For quote relationships, both the short form and the full IRI are accepted:

```sh
fedify lookup --recurse=quoteUrl https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf
fedify lookup --recurse=https://www.w3.org/ns/activitystreams#quoteUrl https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf
```

For short names, only Fedify property naming is accepted.  For example,
`replyTarget` and `quoteUrl` are accepted, while `inReplyTo`, `_misskey_quote`,
and `quoteUri` are not accepted as short forms.

> \[!NOTE]
> `--recurse` and [`-t`/`--traverse`](#t-traverse-traverse-the-collection)
> are mutually exclusive.
>
> Recursive fetches always disallow private/localhost addresses for safety.
> `-p`/`--allow-private-address` only applies to explicit lookup/traverse
> targets, not to recursive steps.

### `--recurse-depth`: Set recursion depth limit

*This option is available since Fedify 2.1.0.*

The `--recurse-depth` option sets the maximum recursion depth when using
[`--recurse`](#recurse-recurse-through-object-relationships).  By default, it
is set to `20`.

```sh
fedify lookup --recurse=replyTarget --recurse-depth=10 https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf
```

This option depends on the `--recurse` option.

### `-S`/`--suppress-errors`: Suppress partial errors during traversal or recursion

*This option is available since Fedify 0.14.0.*

The `-S`/`--suppress-errors` option is used to suppress partial errors during
traversal or recursion.

For traversal mode:

```sh
fedify lookup --traverse --suppress-errors https://fosstodon.org/users/hongminhee/outbox
```

For recursion mode:

```sh
fedify lookup --recurse=replyTarget --suppress-errors https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf
```

The difference between with and without the `-S`/`--suppress-errors` option is
that the former will suppress the partial errors during traversal or recursion,
while the latter will stop on the first such error.

### `-c`/`--compact`: Compact JSON-LD

> \[!NOTE]
> This option is mutually exclusive with `-e`/`--expanded` and `-r`/`--raw`.

You can also output the object in the [compacted JSON-LD] format by using the
`-c`/`--compact` option:

```sh
fedify lookup --compact https://todon.eu/@hongminhee/112341925069749583
```

The output will be like the below:

```json
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://todon.eu/users/hongminhee/statuses/112341925069749583",
  "type": "Note",
  "attachment": {
    "type": "Document",
    "mediaType": "video/mp4",
    "name": "The demo video on my terminal",
    "url": "https://todon.eu/system/media_attachments/files/112/341/916/300/016/369/original/f83659866f94054f.mp4"
  },
  "attributedTo": "https://todon.eu/users/hongminhee",
  "cc": "https://todon.eu/users/hongminhee/followers",
  "content": "<p>I&#39;m working on adding a CLI toolchain to <a href=\"https://todon.eu/tags/Fedify\" class=\"mention hashtag\" rel=\"tag\">#<span>Fedify</span></a> to help with debugging.  The first feature I implemented is the ActivityPub object lookup.</p><p>Here&#39;s a demo.</p><p><a href=\"https://todon.eu/tags/fedidev\" class=\"mention hashtag\" rel=\"tag\">#<span>fedidev</span></a> <a href=\"https://todon.eu/tags/ActivityPub\" class=\"mention hashtag\" rel=\"tag\">#<span>ActivityPub</span></a></p>",
  "contentMap": {
    "en": "<p>I&#39;m working on adding a CLI toolchain to <a href=\"https://todon.eu/tags/Fedify\" class=\"mention hashtag\" rel=\"tag\">#<span>Fedify</span></a> to help with debugging.  The first feature I implemented is the ActivityPub object lookup.</p><p>Here&#39;s a demo.</p><p><a href=\"https://todon.eu/tags/fedidev\" class=\"mention hashtag\" rel=\"tag\">#<span>fedidev</span></a> <a href=\"https://todon.eu/tags/ActivityPub\" class=\"mention hashtag\" rel=\"tag\">#<span>ActivityPub</span></a></p>"
  },
  "published": "2024-04-27T07:08:57Z",
  "replies": {
    "id": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies",
    "type": "Collection",
    "first": {
      "type": "CollectionPage",
      "items": "https://todon.eu/users/hongminhee/statuses/112343493232608516",
      "next": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies?min_id=112343493232608516&page=true",
      "partOf": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies"
    }
  },
  "as:sensitive": false,
  "to": "as:Public",
  "url": "https://todon.eu/@hongminhee/112341925069749583"
}
```

[compacted JSON-LD]: https://www.w3.org/TR/json-ld/#compacted-document-form

### `-e`/`--expanded`: Expanded JSON-LD

> \[!NOTE]
> This option is mutually exclusive with `-c`/`--compact` and `-r`/`--raw`.

You can also output the object in the [expanded JSON-LD] format by using the
`-e`/`--expanded` option:

```sh
fedify lookup --expand https://todon.eu/@hongminhee/112341925069749583
```

The output will be like the below:

```json
[
  {
    "@id": "https://todon.eu/users/hongminhee/statuses/112341925069749583",
    "@type": [
      "https://www.w3.org/ns/activitystreams#Note"
    ],
    "https://www.w3.org/ns/activitystreams#attachment": [
      {
        "@type": [
          "https://www.w3.org/ns/activitystreams#Document"
        ],
        "https://www.w3.org/ns/activitystreams#mediaType": [
          {
            "@value": "video/mp4"
          }
        ],
        "https://www.w3.org/ns/activitystreams#name": [
          {
            "@value": "The demo video on my terminal"
          }
        ],
        "https://www.w3.org/ns/activitystreams#url": [
          {
            "@id": "https://todon.eu/system/media_attachments/files/112/341/916/300/016/369/original/f83659866f94054f.mp4"
          }
        ]
      }
    ],
    "https://www.w3.org/ns/activitystreams#attributedTo": [
      {
        "@id": "https://todon.eu/users/hongminhee"
      }
    ],
    "https://www.w3.org/ns/activitystreams#cc": [
      {
        "@id": "https://todon.eu/users/hongminhee/followers"
      }
    ],
    "https://www.w3.org/ns/activitystreams#content": [
      {
        "@value": "<p>I&#39;m working on adding a CLI toolchain to <a href=\"https://todon.eu/tags/Fedify\" class=\"mention hashtag\" rel=\"tag\">#<span>Fedify</span></a> to help with debugging.  The first feature I implemented is the ActivityPub object lookup.</p><p>Here&#39;s a demo.</p><p><a href=\"https://todon.eu/tags/fedidev\" class=\"mention hashtag\" rel=\"tag\">#<span>fedidev</span></a> <a href=\"https://todon.eu/tags/ActivityPub\" class=\"mention hashtag\" rel=\"tag\">#<span>ActivityPub</span></a></p>"
      },
      {
        "@language": "en",
        "@value": "<p>I&#39;m working on adding a CLI toolchain to <a href=\"https://todon.eu/tags/Fedify\" class=\"mention hashtag\" rel=\"tag\">#<span>Fedify</span></a> to help with debugging.  The first feature I implemented is the ActivityPub object lookup.</p><p>Here&#39;s a demo.</p><p><a href=\"https://todon.eu/tags/fedidev\" class=\"mention hashtag\" rel=\"tag\">#<span>fedidev</span></a> <a href=\"https://todon.eu/tags/ActivityPub\" class=\"mention hashtag\" rel=\"tag\">#<span>ActivityPub</span></a></p>"
      }
    ],
    "https://www.w3.org/ns/activitystreams#published": [
      {
        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
        "@value": "2024-04-27T07:08:57Z"
      }
    ],
    "https://www.w3.org/ns/activitystreams#replies": [
      {
        "@id": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies",
        "@type": [
          "https://www.w3.org/ns/activitystreams#Collection"
        ],
        "https://www.w3.org/ns/activitystreams#first": [
          {
            "@type": [
              "https://www.w3.org/ns/activitystreams#CollectionPage"
            ],
            "https://www.w3.org/ns/activitystreams#items": [
              {
                "@id": "https://todon.eu/users/hongminhee/statuses/112343493232608516"
              }
            ],
            "https://www.w3.org/ns/activitystreams#next": [
              {
                "@id": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies?min_id=112343493232608516&page=true"
              }
            ],
            "https://www.w3.org/ns/activitystreams#partOf": [
              {
                "@id": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies"
              }
            ]
          }
        ]
      }
    ],
    "https://www.w3.org/ns/activitystreams#sensitive": [
      {
        "@value": false
      }
    ],
    "https://www.w3.org/ns/activitystreams#to": [
      {
        "@id": "https://www.w3.org/ns/activitystreams#Public"
      }
    ],
    "https://www.w3.org/ns/activitystreams#url": [
      {
        "@id": "https://todon.eu/@hongminhee/112341925069749583"
      }
    ]
  }
]
```

[expanded JSON-LD]: https://www.w3.org/TR/json-ld/#expanded-document-form

### `-r`/`--raw`: Raw JSON

*This option is available since Fedify 0.15.0.*

> \[!NOTE]
> This option is mutually exclusive with `-c`/`--compact` and `-e`/`--expanded`.

You can also output the fetched object in the raw JSON format by using
the `-r`/`--raw` option:

```sh
fedify lookup --raw https://todon.eu/@hongminhee/112341925069749583
```

The output will be like the below:

```json
{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "ostatus": "http://ostatus.org#",
      "atomUri": "ostatus:atomUri",
      "inReplyToAtomUri": "ostatus:inReplyToAtomUri",
      "conversation": "ostatus:conversation",
      "sensitive": "as:sensitive",
      "toot": "http://joinmastodon.org/ns#",
      "votersCount": "toot:votersCount",
      "blurhash": "toot:blurhash",
      "focalPoint": {
        "@container": "@list",
        "@id": "toot:focalPoint"
      },
      "Hashtag": "as:Hashtag"
    }
  ],
  "id": "https://todon.eu/users/hongminhee/statuses/112341925069749583",
  "type": "Note",
  "summary": null,
  "inReplyTo": null,
  "published": "2024-04-27T07:08:57Z",
  "url": "https://todon.eu/@hongminhee/112341925069749583",
  "attributedTo": "https://todon.eu/users/hongminhee",
  "to": [
    "https://www.w3.org/ns/activitystreams#Public"
  ],
  "cc": [
    "https://todon.eu/users/hongminhee/followers"
  ],
  "sensitive": false,
  "atomUri": "https://todon.eu/users/hongminhee/statuses/112341925069749583",
  "inReplyToAtomUri": null,
  "conversation": "tag:todon.eu,2024-04-27:objectId=90184788:objectType=Conversation",
  "content": "<p>I&#39;m working on adding a CLI toolchain to <a href=\"https://todon.eu/tags/Fedify\" class=\"mention hashtag\" rel=\"tag\">#<span>Fedify</span></a> to help with debugging.  The first feature I implemented is the ActivityPub object lookup.</p><p>Here&#39;s a demo.</p><p><a href=\"https://todon.eu/tags/fedidev\" class=\"mention hashtag\" rel=\"tag\">#<span>fedidev</span></a> <a href=\"https://todon.eu/tags/ActivityPub\" class=\"mention hashtag\" rel=\"tag\">#<span>ActivityPub</span></a></p>",
  "contentMap": {
    "en": "<p>I&#39;m working on adding a CLI toolchain to <a href=\"https://todon.eu/tags/Fedify\" class=\"mention hashtag\" rel=\"tag\">#<span>Fedify</span></a> to help with debugging.  The first feature I implemented is the ActivityPub object lookup.</p><p>Here&#39;s a demo.</p><p><a href=\"https://todon.eu/tags/fedidev\" class=\"mention hashtag\" rel=\"tag\">#<span>fedidev</span></a> <a href=\"https://todon.eu/tags/ActivityPub\" class=\"mention hashtag\" rel=\"tag\">#<span>ActivityPub</span></a></p>"
  },
  "attachment": [
    {
      "type": "Document",
      "mediaType": "video/mp4",
      "url": "https://todon.eu/system/media_attachments/files/112/341/916/300/016/369/original/f83659866f94054f.mp4",
      "name": "The demo video on my terminal",
      "blurhash": "U87_4lWB_3WBt7bHazWV~qbHaybFozj[ayfj",
      "width": 1092,
      "height": 954
    }
  ],
  "tag": [
    {
      "type": "Hashtag",
      "href": "https://todon.eu/tags/fedify",
      "name": "#fedify"
    },
    {
      "type": "Hashtag",
      "href": "https://todon.eu/tags/fedidev",
      "name": "#fedidev"
    },
    {
      "type": "Hashtag",
      "href": "https://todon.eu/tags/activitypub",
      "name": "#activitypub"
    }
  ],
  "replies": {
    "id": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies",
    "type": "Collection",
    "first": {
      "type": "CollectionPage",
      "next": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies?min_id=112343493232608516&page=true",
      "partOf": "https://todon.eu/users/hongminhee/statuses/112341925069749583/replies",
      "items": [
        "https://todon.eu/users/hongminhee/statuses/112343493232608516"
      ]
    }
  }
}
```

### `-a`/`--authorized-fetch`: Authorized fetch

You can also use the `-a`/`--authorized-fetch` option to fetch the object with
authentication.  Under the hood, this option generates a one-time key pair,
spins up a temporary ActivityPub server to serve the public key, and signs
the request with the private key.

Here's an example where the `fedify lookup` fails due to the object being
protected:

```sh
fedify lookup @tchambers@indieweb.social
```

The above command will output the below error:

```
Failed to fetch the object.
It may be a private object.  Try with -a/--authorized-fetch.
```

However, you can fetch the object with the `-a`/`--authorized-fetch` option:

```sh
fedify lookup --authorized-fetch @tchambers@indieweb.social
```

This time, the above command will output the object successfully:

```
Person {
  id: URL "https://indieweb.social/users/tchambers",
  attachments: [
    PropertyValue {
      name: "Indieweb Site",
      value: '<a href="http://www.timothychambers.net" target="_blank" rel="nofollow noopener noreferrer me" trans'... 128 more characters
    },
    PropertyValue {
      name: "Gravatar",
      value: '<a href="https://en.gravatar.com/tchambers" target="_blank" rel="nofollow noopener noreferrer me" tr'... 134 more characters
    },
    PropertyValue {
      name: "Threads",
      value: '<a href="https://www.threads.net/@timothyjchambers" target="_blank" rel="nofollow noopener noreferre'... 150 more characters
    },
    PropertyValue {
      name: "GitHub",
      value: '<a href="https://github.com/Timothyjchambers" target="_blank" rel="nofollow noopener noreferrer me" '... 138 more characters
    }
  ],
  name: "Tim Chambers",
  icon: Image {
    url: URL "https://cdn.masto.host/indiewebsocial/accounts/avatars/000/000/002/original/5de753df6fe336d5.png",
    mediaType: "image/png"
  },
  image: Image {
    url: URL "https://cdn.masto.host/indiewebsocial/accounts/headers/000/000/002/original/38c44f4142b84cf4.png",
    mediaType: "image/png"
  },
  published: 2019-08-30T00:00:00Z,
  summary: "<p>Technologist, writer, admin of indieweb.social. Fascinated by how new politics impacts technology"... 346 more characters,
  url: URL "https://indieweb.social/@tchambers",
  preferredUsername: "tchambers",
  publicKey: CryptographicKey {
    id: URL "https://indieweb.social/users/tchambers#main-key",
    owner: URL "https://indieweb.social/users/tchambers",
    publicKey: CryptoKey {
      type: "public",
      extractable: true,
      algorithm: {
        name: "RSASSA-PKCS1-v1_5",
        modulusLength: 2048,
        publicExponent: Uint8Array(3) [ 1, 0, 1 ],
        hash: { name: "SHA-256" }
      },
      usages: [ "verify" ]
    }
  },
  manuallyApprovesFollowers: false,
  inbox: URL "https://indieweb.social/users/tchambers/inbox",
  outbox: URL "https://indieweb.social/users/tchambers/outbox",
  following: URL "https://indieweb.social/users/tchambers/following",
  followers: URL "https://indieweb.social/users/tchambers/followers",
  endpoints: Endpoints { sharedInbox: URL "https://indieweb.social/inbox" },
  discoverable: true,
  memorial: false,
  indexable: true
}
```

### `--first-knock`: First-knock spec for `-a`/`--authorized-fetch`

*This option is available since Fedify 1.6.0.*

The `--first-knock` option is used to specify which HTTP Signatures spec to
try first when using the `-a`/`--authorized-fetch` option.  The ActivityPub
ecosystem currently uses different versions of HTTP Signatures specifications,
and the [double-knocking] technique (trying one version, then falling back to
another if rejected) allows for better compatibility across servers.

Available options are:

`draft-cavage-http-signatures-12`
:   [HTTP Signatures], which is obsolete but still widely adopted in
the fediverse as of May 2025.

`rfc9421` (default)
:   [RFC 9421]: HTTP Message Signatures, which is the final revision of
the specification and is recommended, but not yet widely adopted
in the fediverse as of June 2025.

If the first signature attempt fails, Fedify will automatically try the other
specification format, implementing the [double-knocking] technique described in
the [ActivityPub HTTP Signatures] specification.

[double-knocking]: https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions

[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421

[ActivityPub HTTP Signatures]: https://swicg.github.io/activitypub-http-signature/

### `--tunnel-service`: Tunneling service for `-a`/`--authorized-fetch`

The `--tunnel-service` option is used to specify which tunneling service to use
when using the `-a`/`--authorized-fetch` option.  The authorized fetch feature
requires a temporary server to be exposed to the public internet, and this
option allows you to choose the tunneling service.  Available services can be
found in the output of the `fedify lookup --help` command.  For example, to use
serveo.net as the tunneling service:

```sh
fedify lookup --authorized-fetch --tunnel-service serveo.net @user@example.com
```

### `-u`/`--user-agent`: Custom `User-Agent` header

*This option is available since Fedify 1.3.0.*

By default, the `fedify lookup` command sends the `User-Agent` header with the
value `Fedify/1.3.0 (Deno/2.0.4)` (version numbers may vary).  You can specify
a custom `User-Agent` header by using the `-u`/`--user-agent` option.  For
example, to send the `User-Agent` header with the value `MyApp/1.0`, run the
below command:

```sh
fedify lookup --user-agent MyApp/1.0 @fedify@hollo.social
```

### `-p`/`--allow-private-address`: Allow private IP addresses

By default, `fedify lookup` does not fetch private or localhost addresses.
The `-p`/`--allow-private-address` option allows explicit lookup/traverse
requests to private addresses when needed for local development.

```sh
fedify lookup --allow-private-address http://localhost:8000/users/alice
```

> \[!NOTE]
> Recursive fetches enabled by
> [`--recurse`](#recurse-recurse-through-object-relationships) continue to
> disallow private addresses.

### `-s`/`--separator`: Output separator

*This option is available since Fedify 1.3.0.*

You can specify the separator between the outputs when looking up multiple
objects at once by using the `-s`/`--separator` option.  For example, to use
the separator `====` between the outputs, run the below command:

```sh
fedify lookup -s ==== @fedify@hollo.social @hongminhee@fosstodon.org
```

It does not affect the output when looking up a single object.

> \[!TIP]
> The separator is also used when looking up a collection object with the
> [`-t`/`--traverse`](#t-traverse-traverse-the-collection) option.

### `--reverse`: Reverse output order

*This option is available since Fedify 2.1.0.*

The `--reverse` option reverses the output order of fetched results.
It affects output order only, and does not change lookup semantics.

```sh
fedify lookup @fedify@hollo.social @hongminhee@fosstodon.org --reverse
fedify lookup --traverse https://fosstodon.org/users/hongminhee/outbox --reverse
fedify lookup --recurse=replyTarget https://hollo.social/@fedify/019c8522-b247-79d3-b0e7-c6a2293bb1cf --reverse
```

When using `--reverse`, `fedify lookup` buffers results before printing.
This may increase memory usage for large traversals or long recursion chains.

### `-o`/`--output`: Output file path

*This option is available since Fedify 1.8.0.*

You can specify the output file path to save lookup results, instead of
printing results to stdout. For example, to save the retrieved information
about the specified objects to a given path, run the command below:

```sh
fedify lookup -o actors.json @fedify@hollo.social @hongminhee@fosstodon.org
```

### `-T`/`--timeout`: Request timeout

*This option is available since Fedify 1.9.0.*

You can specify the request timeout duration by using the `-T`/`--timeout`
option. The duration should be an integer in seconds.  By default, there is no
timeout.  For example, to set the request timeout to 10 seconds, run the below
command:

```sh
fedify lookup --timeout 10 @fedify@hollo.social
```

## `fedify inbox`: Ephemeral inbox server

The `fedify inbox` command is used to spin up an ephemeral server that serves
the ActivityPub inbox with a one-time actor, through a short-lived public DNS
with HTTPS. This is useful when you want to test and debug the outgoing
activities of your server.  To start an ephemeral inbox server,
run the below command:

```sh
fedify inbox
```

If it goes well, you will see the output like the below (without termination;
press ^C to stop the server):

```
✔ The ephemeral ActivityPub server is up and running: https://f9285cf4974c86.lhr.life/
✔ Sent follow request to @faguscus_dashirniul@activitypub.academy.
╭───────────────┬─────────────────────────────────────────╮
│ Actor handle: │ i@f9285cf4974c86.lhr.life               │
├───────────────┼─────────────────────────────────────────┤
│    Actor URI: │ https://f9285cf4974c86.lhr.life/i       │
├───────────────┼─────────────────────────────────────────┤
│  Actor inbox: │ https://f9285cf4974c86.lhr.life/i/inbox │
├───────────────┼─────────────────────────────────────────┤
│ Shared inbox: │ https://f9285cf4974c86.lhr.life/inbox   │
╰───────────────┴─────────────────────────────────────────╯
```

Although the given URIs and handle are short-lived, they are anyway publicly
dereferenceable until the server is terminated.  You can use these URIs and
handle to test and debug the outgoing activities of your server.

If any incoming activities are received, the server will log them to the
console:

```
╭────────────────┬─────────────────────────────────────╮
│     Request #: │ 2                                   │
├────────────────┼─────────────────────────────────────┤
│ Activity type: │ Follow                              │
├────────────────┼─────────────────────────────────────┤
│  HTTP request: │ POST /i/inbox                       │
├────────────────┼─────────────────────────────────────┤
│ HTTP response: │ 202                                 │
├────────────────┼─────────────────────────────────────┤
│        Details │ https://f9285cf4974c86.lhr.life/r/2 │
╰────────────────┴─────────────────────────────────────╯
```

You can also see the details of the incoming activities by visiting the
`/r/:id` endpoint of the server in your browser:

![The details of the incoming activities](/assets/fedify-inbox-web.CjSCOSFT.png)

### `-f`/`--follow`: Follow an actor

The `-f`/`--follow` option is used to follow an actor.  You can specify the
actor handle or URI to follow.  For example, to follow the actor with the
handle *@john@doe.com* and *@jane@doe.com*, run the below command:

```sh
fedify inbox -f @john@doe.com -f @jane@doe.com
```

> \[!NOTE]
> Although `-f`/`--follow` option sends `Follow` activities to the specified
> actors, it does not guarantee that they will accept the follow requests.
> If the actors accept the follow requests, you will receive the `Accept`
> activities in the inbox server, and the server will log them to the console:
>
> ```
> ╭────────────────┬─────────────────────────────────────╮
> │     Request #: │ 0                                   │
> ├────────────────┼─────────────────────────────────────┤
> │ Activity type: │ Accept                              │
> ├────────────────┼─────────────────────────────────────┤
> │  HTTP request: │ POST /i/inbox                       │
> ├────────────────┼─────────────────────────────────────┤
> │ HTTP response: │ 202                                 │
> ├────────────────┼─────────────────────────────────────┤
> │        Details │ https://f9285cf4974c86.lhr.life/r/0 │
> ╰────────────────┴─────────────────────────────────────╯
> ```

### `-a`/`--accept-follow`: Accept follow requests

The `-a`/`--accept-follow` option is used to accept follow requests from
actors.  You can specify the actor handle or URI to accept follow requests.
Or you can accept all follow requests by specifying the wildcard `*`.
For example, to accept follow requests from the actor with the handle
*@john@doe.com* and *@jane@doe.com*, run the below command:

```sh
fedify inbox -a @john@doe.com -a @jane@doe.com
```

When the follow requests are received from the specified actors, the server
will immediately send the `Accept` activities to them.  Otherwise, the server
will just log the `Follow` activities to the console without sending the
`Accept` activities.

### `-T`/`--no-tunnel`: Local server without tunneling

The `-T`/`--no-tunnel` option is used to disable the tunneling feature of the
inbox server.  By default, the inbox server tunnels the local server to the
public internet, so that the server is accessible from the outside.  If you
want to disable the tunneling feature, run the below command:

```sh
fedify inbox --no-tunnel
```

It would be useful when you want to test the server locally but are worried
about the security implications of exposing the server to the public internet.

> \[!NOTE]
> If you disable the tunneling feature, the ephemeral ActivityPub instance will
> be served via HTTP instead of HTTPS.

### `--tunnel-service`: Tunneling service

The `--tunnel-service` option is used to specify which tunneling service to use
for exposing the ephemeral inbox server to the public internet.  Available
services can be found in the output of the `fedify inbox --help` command.
For example, to use serveo.net as the tunneling service:

```sh
fedify inbox --tunnel-service serveo.net
```

> \[!NOTE]
> This option cannot be used together with `-T`/`--no-tunnel`.

### `-A`/`--authorized-fetch`: Authorized fetch mode

The `-A`/`--authorized-fetch` option enables authorized fetch mode on the
ephemeral inbox server.  When enabled, incoming requests without valid HTTP
Signatures are rejected with `401 Unauthorized`.

```sh
fedify inbox --authorized-fetch
```

This is useful for testing whether your ActivityPub server correctly signs
its outgoing requests, as many instances in the fediverse (such as Mastodon
with secure mode) require valid signatures.

## `fedify nodeinfo`: Visualizing an instance's NodeInfo

*This command is available since Fedify 1.8.0.*

*The `fedify node` alias is deprecated and will be removed in version 2.0.0.*

![The result of fedify lookup fosstodon.org. The NodeInfo document is
visualized along with the favicon.](/assets/fedify-nodeinfo.D41FcnNo.png)

The `fedify nodeinfo` command fetches the given instance's [NodeInfo] document
and visualizes it in [`neofetch`]-style.  The argument can be either a bare
hostname or a full URL.

> \[!TIP]
> Not all instances provide the NodeInfo document.  If the given instance does
> not provide the NodeInfo document, the command will output an error message.

[NodeInfo]: https://nodeinfo.diaspora.software/

[`neofetch`]: https://github.com/dylanaraps/neofetch

### `-r`/`--raw`: Raw JSON

> \[!NOTE]
> This option is mutually exclusive with `-b`/`--best-effort`, `--no-favicon`
> and `-m`/`--metadata`.

You can also output the fetched NodeInfo document in the raw JSON format by
using the `-r`/`--raw` option:

```sh
fedify nodeinfo --raw fosstodon.org
```

The output will be like the below:

```json
{
  "version": "2.0",
  "software": {
    "name": "mastodon",
    "version": "4.4.2"
  },
  "protocols": [
    "activitypub"
  ],
  "services": {
    "outbound": [],
    "inbound": []
  },
  "usage": {
    "users": {
      "total": 62444,
      "activeMonth": 8788,
      "activeHalfyear": 14000
    },
    "localPosts": 4335412
  },
  "openRegistrations": false,
  "metadata": {
    "nodeName": "Fosstodon",
    "nodeDescription": "Fosstodon is an invite only Mastodon instance that is open to those who are interested in technology; particularly free & open source software.\r\n\r\nIf you wish to join, contact us for an invite."
  }
}
```

### `-b`/`--best-effort`: Parsing with best effort

> \[!NOTE]
> This option is mutually exclusive with `-r`/`--raw`.

The `-b`/`--best-effort` option is used to parse the NodeInfo document with
best effort.  If the NodeInfo document is not well-formed, the option will
try to parse it as much as possible.

### `--no-favicon`: Disabling favicon fetching

> \[!NOTE]
> This option is mutually exclusive with `-r`/`--raw`.

The `--no-favicon` option is used to disable fetching the favicon of the
instance.

### `-m`/`--metadata`: Showing metadata

> \[!NOTE]
> This option is mutually exclusive with `-r`/`--raw`.

The `-m`/`--metadata` option is used to show the extra metadata of the NodeInfo,
i.e., the `metadata` field of the document.

### `-u`/`--user-agent`: Custom `User-Agent` header

*This option is available since Fedify 1.3.0.*

By default, the `fedify nodeinfo` command sends the `User-Agent` header with the
value `Fedify/1.3.0 (Deno/2.0.4)` (version numbers may vary).  You can specify
a custom `User-Agent` header by using the `-u`/`--user-agent` option.  For
example, to send the `User-Agent` header with the value `MyApp/1.0`, run the
below command:

```sh
fedify nodeinfo --user-agent MyApp/1.0 mastodon.social
```

## `fedify relay`: Running an ephemeral ActivityPub relay server

*This command is available since Fedify 2.0.0.*

The `fedify relay` command is used to spin up an ephemeral ActivityPub relay
server that forwards activities between federated instances.  The server can use
either [Mastodon] or [LitePub] compatible relay protocol.

To start a relay server, you must specify the relay protocol using the
`-p`/`--protocol` option:

```sh
fedify relay -p mastodon
```

If it goes well, you will see the output like the below (without termination;
press ^C to stop the server):

```
✔ Relay server is running: https://f9285cf4974c86.lhr.life/
╭───────────────┬──────────────────────────────────────────╮
│    Actor URI: │ https://f9285cf4974c86.lhr.life/actor    │
├───────────────┼──────────────────────────────────────────┤
│ Shared Inbox: │ https://f9285cf4974c86.lhr.life/inbox    │
├───────────────┼──────────────────────────────────────────┤
│     Protocol: │ mastodon                                 │
├───────────────┼──────────────────────────────────────────┤
│         Name: │ Fedify Relay                             │
├───────────────┼──────────────────────────────────────────┤
│      Storage: │ in-memory                                │
╰───────────────┴──────────────────────────────────────────╯

Press ^C to stop the relay server.
```

By default, the relay server is tunneled to the public internet so that
external instances can connect to it.

[Mastodon]: https://joinmastodon.org/

[LitePub]: https://litepub.social/

### `-p`/`--protocol`: Relay protocol

The `-p`/`--protocol` option specifies which relay protocol to use.
This option is required.  The available options are:

* `mastodon`: [Mastodon]-compatible relay protocol
* `litepub`: [LitePub]-compatible relay protocol

### `--persistent`: Persistent storage

The `--persistent` option specifies a path to a SQLite database file for
persistent storage.  If not specified, the relay uses in-memory storage which
is lost when the server stops.

```sh
fedify relay -p mastodon --persistent relay.db
```

### `-P`/`--port`: Local port

The `-P`/`--port` option specifies the local port to listen on.  By default,
it listens on port 8000.

```sh
fedify relay -p mastodon -P 3000
```

### `-n`/`--name`: Relay display name

The `-n`/`--name` option specifies the relay display name.  By default, it is
`Fedify Relay`.

```sh
fedify relay -p mastodon -n "My Relay"
```

### `-a`/`--accept-follow`: Accept follow requests

The `-a`/`--accept-follow` option specifies which actors' follow requests to
accept.  The argument can be either an actor URI, a handle, or a wildcard (`*`).
This option can be specified multiple times.  If a wildcard is specified, all
follow requests will be accepted.

```sh
fedify relay -p mastodon -a @john@doe.com -a @jane@doe.com
```

### `-r`/`--reject-follow`: Reject follow requests

The `-r`/`--reject-follow` option specifies which actors' follow requests to
reject.  The argument can be either an actor URI, a handle, or a wildcard (`*`).
This option can be specified multiple times.  If a wildcard is specified, all
follow requests will be rejected.

```sh
fedify relay -p mastodon -r @spammer@example.com
```

> \[!NOTE]
> When both `-a`/`--accept-follow` and `-r`/`--reject-follow` are specified,
> a follow request is accepted only if the actor matches the accept list and
> does *not* match the reject list.

### `-T`/`--no-tunnel`: Local server without tunneling

The `-T`/`--no-tunnel` option disables the tunneling feature of the relay
server.  By default, the relay server tunnels the local server to the public
internet for external access.

```sh
fedify relay -p mastodon --no-tunnel
```

> \[!NOTE]
> If you disable the tunneling feature, the relay server will be served via
> HTTP instead of HTTPS.

### `--tunnel-service`: Tunneling service

The `--tunnel-service` option specifies which tunneling service to use for
exposing the relay server to the public internet.  Available services can be
found in the output of the `fedify relay --help` command.  For example, to use
serveo.net as the tunneling service:

```sh
fedify relay -p mastodon --tunnel-service serveo.net
```

> \[!NOTE]
> This option cannot be used together with `-T`/`--no-tunnel`.

## `fedify tunnel`: Exposing a local HTTP server to the public internet

*This command is available since Fedify 0.13.0.*

The `fedify tunnel` command is used to expose a local HTTP server to the public
internet using a secure tunnel.  It is useful when you want to test your
local ActivityPub server with the real-world ActivityPub instances.

To create a tunnel for a local server, for example, running on port 3000,
run the below command:

```sh
fedify tunnel 3000
```

> \[!TIP]
>
> The HTTP requests through the tunnel have the following headers:
>
> `X-Forwarded-For`
> :   The IP address of the client.
>
> `X-Forwarded-Proto`
> :   The protocol of the client, either `http` or `https`.
>
> `X-Forwarded-Host`
> :   The host of the public tunnel server.
>
> If you want to make your local server aware of these headers, you can use
> the [x-forwarded-fetch] middleware in front of your HTTP server.
>
> For more information, see [*How the `Federation` object recognizes the domain
> name*
> section](./manual/federation.md#how-the-federation-object-recognizes-the-domain-name)
> in the *Federation* document.

[x-forwarded-fetch]: https://github.com/dahlia/x-forwarded-fetch

### `-s`/`--service`/`--tunnel-service`: The tunneling service

The `-s`/`--service` option is used to specify the tunneling service to use.
The `--tunnel-service` is an alias for consistency with other commands that
support tunneling.  Available services can be found in the output of the
`fedify tunnel --help` command.  For example, to use serveo.net, run the below
command:

```sh
fedify tunnel --service serveo.net 3000
```

## `fedify webfinger`: Looking up a WebFinger resource

*This command is available since Fedify 1.8.0.*

The `fedify webfinger` command is used to look up a WebFinger resource by
resource URI or handle.  [WebFinger] is a protocol that allows discovery of
information about people and other entities on the Internet using simple web
requests.  This command is useful for debugging and testing WebFinger
implementations.

To look up a WebFinger resource, for example, for a user handle, run the
below command:

```sh
fedify webfinger @username@domain.com
```

The output will be like the below:

```json
{
  "subject": "acct:username@domain.com",
  "aliases": [
    "https://domain.com/@username",
    "https://domain.com/users/username"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://domain.com/@username"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://domain.com/users/username"
    }
  ]
}
```

You can also look up a WebFinger resource by its URL.  For example, the below
command looks up a WebFinger resource by http or acct URL:

```sh
fedify webfinger https://domain.com/@username
fedify webfinger acct:username@domain.com
```

Or, you can also look up multiple WebFinger resources at once.  For example,
the below command looks up multiple WebFinger resources:

```sh
fedify webfinger @user1@domain.com https://domain.com/@username acct:username@domain.com
```

The outputs will be displayed sequentially, each preceded by a success message
indicating which resource was found.

[WebFinger]: https://tools.ietf.org/html/rfc7033

### `-a`/`--user-agent`: Custom `User-Agent` header

By default, the `fedify webfinger` command sends the `User-Agent` header with
the value `Fedify/1.8.0 (Deno/2.4.0)` (version numbers may vary).  You can
specify a custom `User-Agent` header by using the `-a`/`--user-agent` option.
For example, to send the `User-Agent` header with the value `MyApp/1.0`, run
the below command:

```sh
fedify webfinger --user-agent MyApp/1.0 @username@domain.com
```

### `-p`/`--allow-private-address`: Allow private IP addresses

The `-p`/`--allow-private-address` option is used to allow private IP addresses.
If you want to allow private IP addresses, run the below command:

```sh
fedify webfinger --allow-private-address @username@localhost
```

Mostly useful for testing purposes.  *Do not use this in production.*

### `--max-redirection`: Maximum number of redirections

The `--max-redirection` option is used to control the maximum number of
redirections allowed during WebFinger lookups.  By default, it is set to 5.
If you want to set a custom limit, run the below command:

```sh
# Use default redirection limit (5)
fedify webfinger @user@example.com

# Set custom redirection limit
fedify webfinger @user@example.com --max-redirection 3

# Disable redirections entirely
fedify webfinger @user@example.com --max-redirection 0
```

## Shell completions

The `fedify` command supports shell completions for [Bash](#bash),
[Fish](#fish), and [Zsh](#zsh).

### Bash

To enable Bash completions add the following line to your profile file
(*~/.bashrc*, *~/.bash\_profile*, or *~/.profile*):

```bash
source <(fedify completions bash)
```

### Fish

To enable Fish completions add the following line to your profile file
(*~/.config/fish/config.fish*):

```fish
source (fedify completions fish | psub)
```

### Zsh

To enable Zsh completions add the following line to your profile file
(*~/.zshrc*):

```zsh
source <(fedify completions zsh)
```

---

---
url: /manual/access-control.md
description: >-
  Fedify provides a flexible access control system that allows you to control
  who can access your resources.  This section explains how to use the access
  control system.
---

# Access control

*This API is available since Fedify 0.7.0.*

Fedify provides a flexible access control system that allows you to control who
can access your resources through the method named [authorized fetch], which is
popularized by Mastodon.  The method requires HTTP Signatures to be attached to
even `GET` requests, and Fedify automatically verifies the signatures and
derives the actor from the signature.

> \[!NOTE]
> Although the method is popularized by Mastodon, it is not a part of the
> ActivityPub specification, and clients are not required to use the method.
> Turning this feature on may limit the compatibility with some clients.

[authorized fetch]: https://swicg.github.io/activitypub-http-signature/#authorized-fetch

## Enabling authorized fetch

To enable authorized fetch, you need to register an `AuthorizePredicate`
callback with `ActorCallbackSetters.authorize()` or
`CollectionCallbackSetters.authorize()`, or `ObjectAuthorizePredicate` callback
with `ObjectCallbackSetters.authorize()`.  The below example shows how to enable
authorized fetch for the actor dispatcher:

```typescript{9-11} twoslash
// @noErrors: 2307 2345
import type { Federation } from "@fedify/fedify";
import type { Actor } from "@fedify/vocab";
/**
 * A hypothetical `Federation` instance.
 */
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that checks if the user blocks the actor.
 * @param userId The ID of the user to check if the actor is blocked.
 * @param signedKeyOwner The actor who signed the request.
 * @returns `true` if the actor is blocked; otherwise, `false`.
 */
async function isBlocked(userId: string, signedKeyOwner: Actor): Promise<boolean> {
  return false;
}
// ---cut-before---
import { federation } from "./your-federation.ts";
import { isBlocked } from "./your-blocklist.ts";

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    // Omitted for brevity; see the related section for details.
  })
  .authorize(async (ctx, identifier) => {
    const signedKeyOwner = await ctx.getSignedKeyOwner();
    if (signedKeyOwner == null) return false;
    return !await isBlocked(identifier, signedKeyOwner);
  });
```

The equivalent method is available for collections as well:

```typescript{9-11} twoslash
// @noErrors: 2307 2345
import type { Federation } from "@fedify/fedify";
import type { Actor } from "@fedify/vocab";
/**
 * A hypothetical `Federation` instance.
 */
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that checks if the user blocks the actor.
 * @param userId The ID of the user to check if the actor is blocked.
 * @param signedKeyOwner The actor who signed the request.
 * @returns `true` if the actor is blocked; otherwise, `false`.
 */
async function isBlocked(userId: string, signedKeyOwner: Actor): Promise<boolean> {
  return false;
}
// ---cut-before---
import { federation } from "./your-federation.ts";
import { isBlocked } from "./your-blocklist.ts";

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier) => {
    // Omitted for brevity; see the related section for details.
  })
  .authorize(async (ctx, identifier) => {
    const signedKeyOwner  = await ctx.getSignedKeyOwner();
    if (signedKeyOwner == null) return false;
    return !await isBlocked(identifier, signedKeyOwner);
  });
```

If the predicate returns `false`, the request is rejected with a
`401 Unauthorized` response.

## Fine-grained access control

You may not want to block everything from an unauthorized user, but only filter
some resources.  For example, you may want to show some private posts to
a specific group of users.  In such cases, you can use the
`RequestContext.getSignedKeyOwner()` method inside the dispatcher
to get the actor who signed the request and make a decision based on the actor.

The method returns the `Actor` object who signed the request (more precisely,
the owner of the key that signed the request, if the key is associated with an
actor).  The below pseudo code shows how to filter out private posts:

```typescript{7} twoslash
// @noErrors: 2307
import type { Federation } from "@fedify/fedify";
import type { Actor, Create } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
interface Post {
  /**
   * A hypothetical method that checks if the post is visible to the actor.
   * @param actor The actor who wants to access the post.
   * @returns `true` if the post is visible; otherwise, `false`.
   */
  isVisibleTo(actor: Actor): boolean;
}
/**
 * A hypothetical function that gets posts from the database.
 * @param userId The ID of the user to get posts.
 * @returns The posts of the user.
 */
async function getPosts(userId: string): Promise<Post[]> {
  return [];
}
/**
 * A hypothetical function that converts a model object to an ActivityStreams object.
 * @param post The model object to convert.
 * @returns The ActivityStreams object.
 */
function toCreate(post: Post): Create {
  return {} as unknown as Create;
}
// ---cut-before---
import { federation } from "./your-federation.ts";
import { getPosts, toCreate } from "./your-model.ts";

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier) => {
    const posts = await getPosts(identifier);  // Get posts from the database
    const keyOwner = await ctx.getSignedKeyOwner();  // Get the actor who signed the request
    if (keyOwner == null) return { items: [] };  // Return an empty array if the actor is not found
    const items = posts
      .filter(post => post.isVisibleTo(keyOwner))  // [!code highlight]
      .map(toCreate);  // Convert model objects to ActivityStreams objects
    return { items };
  });
```

## Instance actor

When you enable authorized fetch, you need to fetch actors from other servers
to retrieve their public keys.  However, this can cause problems when the other
server also has authorized fetch enabled:

* *Unauthenticated appearance*: If the remote server requires a signed
  request to fetch its actor, and your server fetches it without a signature,
  the remote server returns an HTTP 401 error.  In this case,
  `~RequestContext.getSignedKeyOwner()` returns `null`, so the requester
  appears unauthenticated to your `AuthorizePredicate`—which will typically
  deny the request.

* *Infinite loop*: If both servers require authorized fetch, fetching the
  remote actor requires your server to be authenticated, which in turn
  requires fetching *your* actor, which requires authentication, and so on.

> \[!NOTE]
> Even without the infinite loop, if the remote server requires authorized
> fetch, `~RequestContext.getSignedKeyOwner()` returns `null` for requests
> from that server (since fetching the key owner fails with HTTP 401).
> This means such requests appear unauthenticated to your
> `AuthorizePredicate`.  To properly authenticate those requests, implement
> the instance actor pattern below.

The most common way to prevent both problems is a pattern called
[instance actor], which is an actor that represents the whole instance and
exceptionally does not require authorized fetch.  You can use the instance
actor to fetch resources from other servers with a valid signature, without
causing an infinite loop.

Usually, many ActivityPub implementations name their instance actor as their
domain name, such as `example.com@example.com`.  Here is an example of how to
implement an instance actor:

```typescript{3-11,20-27} twoslash
import { type Federation } from "@fedify/fedify";
import { type Actor, Application, Person } from "@fedify/vocab";
/**
 * A hypothetical `Federation` instance.
 */
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that checks if the user blocks the actor.
 * @param userId The ID of the user to check if the actor is blocked.
 * @param signedKeyOwner The actor who signed the request.
 * @returns `true` if the actor is blocked; otherwise, `false`.
 */
async function isBlocked(userId: string, signedKeyOwner: Actor): Promise<boolean> {
  return false;
}
// ---cut-before---
federation
  .setActorDispatcher("/actors/{identifier}", async (ctx, identifier) => {
    if (identifier === ctx.hostname) {
      // A special case for the instance actor:
      return new Application({
        id: ctx.getActorUri(identifier),
        // Omitted for brevity; other properties of the instance actor...
        // Note that you have to set the `publicKey` property of the instance
        // actor.
      });
    }

    // A normal case for a user actor:
    return new Person({
      id: ctx.getActorUri(identifier),
      // Omitted for brevity; other properties of the user actor...
    });
  })
  .authorize(async (ctx, identifier) => {
    // Allow the instance actor to access any resources:
    if (identifier === ctx.hostname) return true;
    // Create an authenticated document loader behalf of the instance actor:
    const documentLoader = await ctx.getDocumentLoader({
      identifier: ctx.hostname,
    });
    // Get the actor who signed the request:
    const signedKeyOwner = await ctx.getSignedKeyOwner({ documentLoader });
    if (signedKeyOwner == null) return false;
    return !await isBlocked(identifier, signedKeyOwner);
  });
```

[instance actor]: https://swicg.github.io/activitypub-http-signature/#instance-actor

---

---
url: /manual/actor.md
description: >-
  You can register an actor dispatcher so that Fedify can dispatch an
  appropriate actor by its identifier.  This section explains how to register an
  actor dispatcher and the key properties of an actor.
---

# Actor dispatcher

In ActivityPub, [actors] are entities that can perform [activities].  You can
register an actor dispatcher so that Fedify can dispatch an appropriate actor
by its identifier.  Since the actor dispatcher is the most significant part of
Fedify, it is the first thing you need to do to make Fedify work.

An actor dispatcher is a callback function that takes a `Context` object and
an identifier, and returns an actor object.  The actor object can be one of
the following:

* `Application`
* `Group`
* `Organization`
* `Person`
* `Service`

The below example shows how to register an actor dispatcher:

```typescript{7-15} twoslash
// @noErrors: 2451 2345
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
interface User { }
const user = null as User | null;
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
});

federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  // Work with the database to find the actor by the identifier.
  if (user == null) return null;  // Return null if the actor is not found.
  return new Person({
    id: ctx.getActorUri(identifier),
    preferredUsername: identifier,
    // Many more properties; see the next section for details.
  });
});
```

In the above example, the `~Federatable.setActorDispatcher()` method registers
an actor dispatcher for the `/users/{identifier}` path.  This pattern syntax
follows the [URI Template] specification.

> \[!TIP]
> By registering the actor dispatcher, `Federation.fetch()` automatically
> deals with [WebFinger] requests for the actor.

> \[!TIP]
> By default, Fedify assumes that the actor's identifier is the WebFinger
> username.  If you want to decouple the WebFinger username from the actor's
> identifier, you can register an actor handle mapper through the
> `~ActorCallbackSetters.mapHandle()` method.
>
> See the [next section](#decoupling-actor-uris-from-webfinger-usernames)
> for details.

> \[!NOTE]
> The URI Template syntax supports different expansion types like `{identifier}`
> (simple expansion) and `{+identifier}` (reserved expansion).  Choosing the
> right expansion type is important to avoid encoding issues.  See the
> [*URI Template* guide](./uri-template.md) for details on when to use
> each type.

[actors]: https://www.w3.org/TR/activitystreams-core/#actors

[activities]: https://www.w3.org/TR/activitystreams-core/#activities

[URI Template]: https://datatracker.ietf.org/doc/html/rfc6570

[WebFinger]: https://datatracker.ietf.org/doc/html/rfc7033

## Actor identifier and WebFinger username

An actor *identifier* is a unique string that identifies the actor.  It can be
a username, a UUID, or any other unique string.  The actor identifier is used
as a URL parameter in the actor dispatcher and other dispatchers.  It's usually
used to find the actor in your database, i.e., primary key.

A WebFinger *username* is a string that comes before the domain part of the
fediverse handle, e.g., `hongminhee` in `@hongminhee@fosstodon.org`.
The WebFinger username is also used as the `preferredUsername` property of
the actor.  It's usually displayed in the user interface, and used to find
the actor by the WebFinger protocol, i.e., looking up the fediverse handle
in the search box.  It's also called the *bare handle*.

By default, Fedify assumes that the actor's identifier is the WebFinger
username, but you can decouple the WebFinger username from the actor's
identifier if you want.   You can think of the difference between these two
approaches as analogous to [natural key] vs. [surrogate key] in the database
design.

There are pros and cons to using the WebFinger username as the actor's
identifier (which is Fedify's default):

Pros
:    -  The actor URI is more predictable and human-readable,
which makes debugging easier.
\-  The internal ID of the actor can be hidden from the public.

Cons
:    -  Changing the WebFinger username may break the existing network.
Hence, the fediverse handle is immutable in practice.
\-  It's usually treated as an anti-pattern in the fediverse.

You need to choose the best approach for your use case before implementing the
actor dispatcher.  If you decide to use the WebFinger username as the actor's
identifier, there's nothing to do—Fedify assumes it by default.

If you decide to decouple the WebFinger username from the actor's identifier,
see the [next section](#decoupling-actor-uris-from-webfinger-usernames) for
details.

[natural key]: https://en.wikipedia.org/wiki/Natural_key

[surrogate key]: https://en.wikipedia.org/wiki/Surrogate_key

## Key properties of an `Actor`

Although ActivityPub declares every property of an actor as optional,
in practice, you need to set some of them to make the actor work properly
with the existing ActivityPub implementations.  The following shows
the key properties of an `Actor` object:

### `id`

The `~Object.id` property is the URI of the actor.  It is a required property
in ActivityPub.  You can use the `Context.getActorUri()` method to generate
the dereferenceable URI of the actor by its identifier.

### `preferredUsername`

The `preferredUsername` property is the WebFinger username of the actor.
Unless [you decouple the WebFinger username from the actor's
identifier](#decoupling-actor-uris-from-webfinger-usernames), it is okay to
set the `preferredUsername` property to the actor's identifier.

### `name`

The `~Object.name` property is the full name of the actor.

### `summary`

The `~Object.summary` property is usually a short biography of the actor.

### `url`

The `~Object.url` property usually refers to the actor's profile page.

### `published`

The `~Object.published` property is the date and time when the actor was
created.  Note that Fedify represents the date and time in
the [`Temporal.Instant`] value.

[`Temporal.Instant`]: https://tc39.es/proposal-temporal/docs/instant.html

### `inbox`

The `inbox` property is the URI of the actor's inbox.  You can use
the `Context.getInboxUri()` method to generate the URI of the actor's
inbox.

See the [*Inbox listeners*](./inbox.md) section for details.

### `outbox`

The `outbox` property is the URI of the actor's outbox.  You can use
the `Context.getOutboxUri()` method to generate the URI of the actor's
outbox.

### `followers`

The `followers` property is the URI of the actor's followers collection.
You can use the `Context.getFollowersUri()` method to generate the URI of
the actor's followers collection.

### `following`

The `following` property is the URI of the actor's following collection.
You can use the `Context.getFollowingUri()` method to generate the URI of
the actor's following collection.

### `endpoints`

The `endpoints` property is an `Endpoints` instance, an object that contains
the URIs of the actor's endpoints.  The most important endpoint is the
`sharedInbox`.  You can use the `Context.getInboxUri()` method with no
arguments to generate the URI of the actor's shared inbox:

```typescript twoslash
import { Context } from "@fedify/fedify";
import { Endpoints } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
// ---cut-before---
new Endpoints({ sharedInbox: ctx.getInboxUri() })
```

### `publicKey`

The `publicKey` property contains the public key of the actor.  It is
a `CryptographicKey` instance.  This property is usually used for verifying
[HTTP Signatures](./send.md#http-signatures).

See the [next section](#public-keys-of-an-actor) for details.

> \[!TIP]
> In theory, an actor has multiple `publicKeys`, but in practice, most
> implementations have trouble with multiple keys.  Therefore, it is recommended
> to set only one key in the `publicKey` property.  Usually, it contains
> the first RSA-PKCS#1-v1.5 public key of the actor.
>
> If you need to set multiple keys, you can use the `assertionMethods` property
> instead.

### `assertionMethods`

*This API is available since Fedify 0.10.0.*

The `assertionMethods` property contains the public keys of the actor.  It is
an array of `Multikey` instances.  This property is usually used for verifying
[Object Integrity Proofs](./send.md#object-integrity-proofs).

> \[!TIP]
> Usually, the `assertionMethods` property contains the Ed25519 public keys of
> the actor.  Although it is okay to include RSA-PKCS#1-v1.5 public keys too,
> those RSA-PKCS#1-v1.5 keys are not used for verifying Object Integrity Proofs.

## Public keys of an `Actor`

In order to sign and verify the activities, you need to set the `publicKey` and
`assertionMethods` property of the actor.  The `publicKey` property contains
a `CryptographicKey` instance, and the `assertionMethods` property contains
an array of `Multikey` instances.  Usually you don't have to create them
manually.  Instead, you can register a key pairs dispatcher through
the `~ActorCallbackSetters.setKeyPairsDispatcher()` method so that Fedify can
dispatch appropriate key pairs by the actor's identifier:

```typescript{4-6,10-14,17-26} twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
interface User {}
const user = null as User | null;
const publicKey1 = null as unknown as CryptoKey;
const privateKey1 = null as unknown as CryptoKey;
const publicKey2 = null as unknown as CryptoKey;
const privateKey2 = null as unknown as CryptoKey;
// ---cut-before---
federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  // Work with the database to find the actor by the identifier.
  if (user == null) return null;  // Return null if the actor is not found.
  // Context.getActorKeyPairs() method dispatches the key pairs of an actor
  // by the identifier, and returns an array of key pairs in various formats:
  const keys = await ctx.getActorKeyPairs(identifier);
  return new Person({
    id: ctx.getActorUri(identifier),
    preferredUsername: identifier,
    // For the publicKey property, we only use first CryptographicKey:
    publicKey: keys[0].cryptographicKey,
    // For the assertionMethods property, we use all Multikey instances:
    assertionMethods: keys.map((key) => key.multikey),
    // Many more properties; see the previous section for details.
  });
})
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // Work with the database to find the key pair by the identifier.
    if (user == null) return [];  // Return null if the key pair is not found.
    // Return the loaded key pair.  See the below example for details.
    return [
      { publicKey: publicKey1, privateKey: privateKey1 },
      { publicKey: publicKey2, privateKey: privateKey2 },
      // ...
    ];
  });
```

In the above example, the `~ActorCallbackSetters.setKeyPairsDispatcher()` method
registers a key pairs dispatcher.  The key pairs dispatcher is a callback
function that takes context data and an identifier, and returns an array of
[`CryptoKeyPair`] object which is defined in the Web Cryptography API.

Usually, you need to generate key pairs for each actor when the actor is
created (i.e., when a new user is signed up), and securely store actor's key
pairs in the database.  The key pairs dispatcher should load the key pairs from
the database and return them.

How to generate key pairs and store them in the database is out of the scope of
this document, but here's a simple example of how to generate key pairs and
store them in a [Deno KV] database in form of JWK:

```typescript twoslash
const identifier: string = "";
// ---cut-before---
import { generateCryptoKeyPair, exportJwk } from "@fedify/fedify";

const kv = await Deno.openKv();
const rsaPair = await generateCryptoKeyPair("RSASSA-PKCS1-v1_5");
const ed25519Pair = await generateCryptoKeyPair("Ed25519");
await kv.set(["keypair", "rsa", identifier], {
  privateKey: await exportJwk(rsaPair.privateKey),
  publicKey: await exportJwk(rsaPair.publicKey),
});
await kv.set(["keypair", "ed25519", identifier], {
  privateKey: await exportJwk(ed25519Pair.privateKey),
  publicKey: await exportJwk(ed25519Pair.publicKey),
});
```

> \[!TIP]
> Fedify currently supports two key types:
>
> * RSA-PKCS#1-v1.5 (`"RSASSA-PKCS1-v1_5"`) is used for [HTTP
>   Signatures](./send.md#http-signatures), [HTTP Message
>   Signatures](./send.md#http-message-signatures), and [Linked Data
>   Signatures](./send.md#linked-data-signatures).
> * Ed25519 (`"Ed25519"`) is used for [Object Integrity
>   Proofs](./send.md#object-integrity-proofs).
>
> HTTP Signatures and Linked Data Signatures are de facto standards for signing
> ActivityPub activities, and Object Integrity Proofs is a new standard for
> verifying the integrity of the objects in the fediverse.  While HTTP
> Signatures and Linked Data Signatures are widely supported in the fediverse,
> it's limited to the RSA-PKCS#1-v1.5 algorithm.
>
> If your federated app needs to support HTTP Signatures, Linked Data
> Signatures, and Object Integrity Proofs at the same time,
> you need to generate both RSA-PKCS#1-v1.5 and Ed25519 key
> pairs for each actor, and store them in the database—and we recommend
> you to support both key types.

Here's an example of how to load key pairs from the database too:

```typescript{12-34} twoslash
// @noErrors: 2345
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { importJwk } from "@fedify/fedify";

interface KeyPairEntry {
  privateKey: JsonWebKey;
  publicKey: JsonWebKey;
}

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    // Omitted for brevity; see the previous example for details.
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    const kv = await Deno.openKv();
    const result: CryptoKeyPair[] = [];
    const rsaPair = await kv.get<KeyPairEntry>(
      ["keypair", "rsa", identifier],
    );
    if (rsaPair?.value != null) {
      result.push({
        privateKey: await importJwk(rsaPair.value.privateKey, "private"),
        publicKey: await importJwk(rsaPair.value.publicKey, "public"),
      });
    }
    const ed25519Pair = await kv.get<KeyPairEntry>(
      ["keypair", "ed25519", identifier],
    );
    if (ed25519Pair?.value != null) {
      result.push({
        privateKey: await importJwk(ed25519Pair.value.privateKey, "private"),
        publicKey: await importJwk(ed25519Pair.value.publicKey, "public"),
      });
    }
    return result;
  });
```

[`CryptoKeyPair`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair

[Deno KV]: https://deno.com/kv

## Constructing actor URIs

To construct an actor URI, you can use the `Context.getActorUri()` method.
This method takes an identifier and returns a dereferenceable URI of the actor.

The below example shows how to construct an actor URI:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getActorUri("john_doe")
```

In the above example, the `Context.getActorUri()` method generates the
dereferenceable URI of the actor with the identifier `"john_doe"`.

If you [decouple the WebFinger username from the actor's
identifier](#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in the actor dispatcher to
the `Context.getActorUri()` method, not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getActorUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getActorUri()` method does not guarantee that the actor
> URI is always dereferenceable for every argument.  Make sure that
> the argument is a valid identifier before calling the method.

## Decoupling actor URIs from WebFinger usernames

*This API is available since Fedify 0.15.0.*

> \[!TIP]
> The WebFinger username means the username part of the `acct:` URI or
> the fediverse handle.  For example, the WebFinger username of the
> `acct:fedify@hollo.social` URI or the `@fedify@hollo.social` handle
> is `fedify`.

By default, Fedify uses the identifier as the WebFinger username.  However,
you can decouple the WebFinger username from the identifier by registering
an actor handle mapper through the `~ActorCallbackSetters.mapHandle()` method:

```typescript twoslash
// @noErrors: 2391 2345
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
interface User { uuid: string; }
/**
 * It's a hypothetical function that finds a user by the UUID.
 * @param uuid The UUID of the user.
 * @returns The user object.
 */
function findUserByUuid(uuid: string): User;
/**
 * It's a hypothetical function that finds a user by the username.
 * @param username The username of the user.
 * @returns The user object.
 */
function findUserByUsername(username: string): User;
// ---cut-before---
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    // Since we map a WebFinger username to the corresponding user's UUID below,
    // the `identifier` parameter is the user's UUID, not the WebFinger
    // username:
    const user = await findUserByUuid(identifier);
    // Omitted for brevity; see the previous example for details.
  })
  .mapHandle(async (ctx, username) => {
    // Work with the database to find the user's UUID by the WebFinger username.
    const user = await findUserByUsername(username);
    if (user == null) return null;  // Return null if the actor is not found.
    return user.uuid;
  });
```

Decoupling the WebFinger username from the identifier is useful when you want
to let users change their WebFinger username without breaking the existing
network, because changing the WebFinger username does not affect the actor URI.

> \[!NOTE]
> We highly recommend that you set the actor's `preferredUsername` property to
> the corresponding WebFinger username so that peers can find the actor's
> fediverse handle by fetching the actor object.

## WebFinger links

Some properties of an `Actor` returned by the actor dispatcher affect
responses to WebFinger requests.

> \[!TIP]
> *Since Fedify 1.9.0*, you can also customize WebFinger responses using
> `~Federatable.setWebFingerLinksDispatcher()` to add custom links with
> the `template` field. See the
> [WebFinger documentation](./webfinger.md#customizing-webfinger-endpoint) for
> details.

### `preferredUsername`

*This API is available since Fedify 0.15.0.*

The `preferredUsername` property is the bare handle of the actor.  It is
used as the WebFinger username, used in the `acct:` URI of the `aliases`
property of the WebFinger response.

### `url`

The `url` property usually refers to the actor's profile page.  It is
used as the `links` property of the WebFinger response, with the `rel`
property set to <http://webfinger.net/rel/profile-page>.

> \[!TIP]
> You probably want to implement [actor aliases](#actor-aliases) if you want
> to give different URLs to the actor URI and its web profile URL.

If you want to provide links with other `rel` than
<http://webfinger.net/rel/profile-page>, you can put `Link` objects in the
`url` property:

```typescript{8-16} twoslash
import { type Federation } from "@fedify/fedify";
import { Link, Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      urls: [
        new URL(`/@${identifier}`, ctx.origin),
        new Link({
          rel: "alternate",
          href: new URL(`/@${identifier}/atom.xml`, ctx.origin),
          mediaType: "application/atom+xml",
        }),
        new Link({
          rel: "http://openid.net/specs/connect/1.0/issuer",
          href: new URL("/openid", ctx.origin),
        }),
      ],
      // Omitted for brevity; see the previous example for details.
    });
  });
```

With the above example, the WebFinger response will contain the following
`links` property:

```json
{
  "subject": "acct:johndoe@example.com",
  "aliases": [
    "https://example.com/users/john_doe"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "href": "https://example.com/@john_doe"
    },
    {
      "rel": "alternate",
      "href": "https://example.com/@john_doe/atom.xml",
      "type": "application/atom+xml"
    },
    {
      "rel": "http://openid.net/specs/connect/1.0/issuer",
      "href": "https://example.com/openid"
    }
  ]
}
```

### `icon`

*This API is available since Fedify 1.0.0.*

The `icon` property is an `Image` object that represents the actor's
icon (i.e., avatar).  It is used as the `links` property of the WebFinger
response, with the `rel` property set to <http://webfinger.net/rel/avatar>.

## Actor aliases

*This API is available since Fedify 1.4.0.*

Sometimes, you may want to give different URLs to the actor URI and its web
profile URL.  It can be easily configured by setting the `url` property of
the `Actor` object returned by the actor dispatcher.  However, if someone
queries the WebFinger for a profile URL, the WebFinger response will not
contain the corresponding actor URI.

To solve this problem, you can set the aliases of the actor by
the `~ActorCallbackSetters.mapAlias()` method.  It takes a callback function
that takes a `Context` object and a queried URL through WebFinger, and returns
the corresponding actor's internal identifier or username, or `null` if there
is no corresponding actor:

```typescript{15-25} twoslash
// @noErrors: 2345 2391
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
interface User { uuid: string; }
/**
 * It's a hypothetical function that finds a user by the UUID.
 * @param uuid The UUID of the user.
 * @returns The user object.
 */
function findUserByUuid(uuid: string): User;
/**
 * It's a hypothetical function that finds a user by the username.
 * @param username The username of the user.
 * @returns The user object.
 */
function findUserByUsername(username: string): User;
// ---cut-before---
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    // Since we map a WebFinger username to the corresponding user's UUID below,
    // the `identifier` parameter is the user's UUID, not the WebFinger
    // username:
    const user = await findUserByUuid(identifier);
    // Omitted for brevity; see the previous example for details.
  })
  .mapHandle(async (ctx, username) => {
    // Work with the database to find the user's UUID by the WebFinger username.
    const user = await findUserByUsername(username);
    if (user == null) return null;  // Return null if the actor is not found.
    return user.uuid;
  })
  .mapAlias((ctx, resource: URL) => {
    // Parse the URL and return the corresponding actor's username if
    // the URL is the profile URL of the actor:
    if (resource.protocol !== "https:") return null;
    if (resource.hostname !== "example.com") return null;
    const m = /^\/@(\w+)$/.exec(resource.pathname);
    if (m == null) return null;
    // Note that it is okay even if the returned username is non-existent.
    // It's dealt with by the `mapHandle()` above:
    return { username: m[1] };
  });
```

By registering the alias mapper, Fedify can respond to WebFinger requests
for the actor's profile URL with the corresponding actor URI.

> \[!TIP]
> You also can return the actor's internal identifier instead of the username
> in the `~ActorCallbackSetters.mapAlias()` method:
>
> ```typescript twoslash
> // @noErrors: 2345 7006
> import { type Federation } from "@fedify/fedify";
> const federation = null as unknown as Federation<void>;
> federation.setActorDispatcher(
>   "/users/{identifier}", async (ctx, identifier) => {}
> )
> // ---cut-before---
> .mapAlias((ctx, resource: URL) => {
>   // Parse the URL and return the corresponding actor's username if
>   // the URL is the profile URL of the actor:
>   if (resource.protocol !== "https:") return null;
>   if (resource.hostname !== "example.com") return null;
>   const userId = resource.searchParams.get("userId");
>   if (userId == null) return null;
>   return { identifier: userId };  // [!code highlight]
> });
> ```

> \[!TIP]
> The callback function of the `~ActorCallbackSetters.mapAlias()` method
> can be an async function.

---

---
url: /manual/collections.md
description: >-
  Fedify provides a generic way to construct and handle collections. This
  section explains how to work with collections in Fedify.
---

# Collections

In ActivityPub, a [collection] is a group of objects.  For example, the
followers collection consists of the followers of an actor, and the outbox
collection consists of the activities that an actor has sent.

Fedify provides a generic way to construct and handle collections.  This
section explains how to work with collections in Fedify.

[collection]: https://www.w3.org/TR/activitypub/#collections

## Outbox

> \[!TIP]
> Since the way to construct an outbox collection is the same as the way to
> construct any other collection, the following examples are also applicable to
> constructing other collections.

First, let's see how to construct an [outbox] collection.  An outbox collection
consists of the activities that an actor has sent.  As each collection has its
own URI, the outbox collection has its own URI, too.  The URI of the outbox
collection is determined by the first parameter of
the `~Federatable.setOutboxDispatcher()` method:

```typescript twoslash
// @noErrors: 2345
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier) => {
    // Work with the database to find the activities that the actor has sent.
    // Omitted for brevity.  See the next example for details.
  });
```

Each actor has its own outbox collection, so the URI pattern of the outbox
dispatcher should include the actor's `{identifier}`.  The URI pattern syntax
follows the [URI Template] specification.

> \[!NOTE]
> The URI Template syntax supports different expansion types like `{identifier}`
> (simple expansion) and `{+identifier}` (reserved expansion).  If your
> identifiers contain URIs or special characters, you may need to use
> `{+identifier}` to avoid double-encoding issues.  See the
> [*URI Template* guide](./uri-template.md) for details.

Since the outbox is a collection of activities, the outbox dispatcher should
return an array of activities.  The following example shows how to construct
an outbox collection:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents a post.
 */
interface Post {
  /**
   * The ID of the post.
   */
  id: string;
  /**
   * The title of the post.
   */
  title: string;
  /**
   * The content of the post.
   */
  content: string;
}
/**
 * A hypothetical function that returns the posts that an actor has sent.
 * @param identifier The actor's identifier.
 * @returns The posts that the actor has sent.
 */
function getPostsByUserId(userId: string): Post[] { return []; }
// ---cut-before---
import { Article, Create } from "@fedify/vocab";

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier) => {
    // Work with the database to find the activities that the actor has sent
    // (the following `getPostsByUserId` is a hypothetical function):
    const posts = await getPostsByUserId(identifier);
    // Turn the posts into `Create` activities:
    const items = posts.map(post =>
      new Create({
        id: new URL(`/posts/${post.id}#activity`, ctx.url),
        actor: ctx.getActorUri(identifier),
        object: new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        }),
      })
    );
    return { items };
  });
```

If you try to access the outbox collection of an actor, the server will respond
with a JSON object that contains the activities that the actor has sent:

```http
GET /users/alice/outbox HTTP/1.1
Accept: application/activity+json
Host: localhost
```

```http
HTTP/1.1 200 OK
Content-Type: application/activity+json
Vary: Accept

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "items": [
    {
      "id": "http://localhost/posts/123#activity",
      "type": "Create",
      "actor": "http://localhost/users/alice",
      "object": {
        "id": "http://localhost/posts/123",
        "type": "Article",
        "summary": "Hello, world!",
        "content": "This is the first post."
      }
    },
    // More items...
  ]
}
```

As you can expect, the server responds with the whole activities that the actor
has sent without any pagination.  In the real world, you should implement
pagination for the outbox collection.  In the next section, we'll see how to
implement pagination for a collection.

[outbox]: https://www.w3.org/TR/activitypub/#outbox

[URI Template]: https://datatracker.ietf.org/doc/html/rfc6570

### Page

A collection page is a subset of a collection.  For example, the first page of
the outbox collection is a collection page that contains the first few items of
the outbox collection.  Each page has its own URI which is determined by
a unique cursor, and links to the next and previous pages if they exist.
No random access is allowed for a collection page; you can only access the next
and previous pages.

Fedify abstracts the concept of a collection page as cursor-based pagination.
The cursor is a string that represents the position in the collection.  It can
be either an opaque token or an offset numeric value; the way to interpret it
is up to the server implementation.

If your database system supports cursor-based pagination ([Deno KV], for
example), you can just use the cursor that the database system provides as is.
If your database system supports only offset-based pagination (most
relational databases), you can use the offset as the cursor.

Although it's omitted in the previous example, there is the third parameter to
a callback that `~Federatable.setOutboxDispatcher()` method takes: the cursor.
When the request is for a collection page, the cursor is passed to the callback
as the third parameter.  When the request is for a whole collection, the cursor
is `null` (that the previous example assumes).

Here's an example of how to implement collection pages for the outbox collection
with assuming that the database system supports cursor-based pagination:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Article, Create } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents a post.
 */
interface Post {
  /**
   * The ID of the post.
   */
  id: string;
  /**
   * The title of the post.
   */
  title: string;
  /**
   * The content of the post.
   */
  content: string;
}
/**
 * A hypothetical type that represents the result set of the posts.
 */
interface PostResultSet {
  /**
   * The posts that the actor has sent.
   */
  posts: Post[];
  /**
   * The next cursor that represents the position of the next page.
   */
  nextCursor: string | null;
  /**
   * Whether the current page is the last page.
   */
  last: boolean;
}
/**
 * A hypothetical type that represents the options for
 * the `getPostsByUserId` function.
 */
interface GetPostsByUserIdOptions {
  /**
   * The cursor that represents the position of the current page.
   */
  cursor?: string | null;
  /**
   * The number of items per page.
   */
  limit: number;
}
/**
 * A hypothetical function that returns the posts that an actor has sent.
 * @param userId The actor's identifier.
 * @returns The result set that contains the posts, the next cursor, and whether
 *          the current page is the last page.
 */
function getPostsByUserId(
  userId: string,
  options: GetPostsByUserIdOptions,
): PostResultSet {
  return { posts: [], nextCursor: null, last: true };
}
// ---cut-before---
federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier, cursor) => {
    // If a whole collection is requested, returns nothing as we prefer
    // collection pages over the whole collection:
    if (cursor == null) return null;
    // Work with the database to find the activities that the actor has sent
    // (the following `getPostsByUserId` is a hypothetical function):
    const { posts, nextCursor, last } = await getPostsByUserId(identifier, {
      cursor,
      limit: 10,
    });
    // Turn the posts into `Create` activities:
    const items = posts.map(post =>
      new Create({
        id: new URL(`/posts/${post.id}#activity`, ctx.url),
        actor: ctx.getActorUri(identifier),
        object: new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        }),
      })
    );
    return {
      items,
      // If `last` is `true`, it means that the current page is the last page:
      nextCursor: last ? null : nextCursor,
    }
  });
```

In the above example, the hypothetical `getPostsByUserId()` function returns
the `nextCursor` along with the `items`.  The `nextCursor` represents the
position of the next page, which is provided by the database system.  If the
`last` is `true`, it means that the current page is the last page, so the
`nextCursor` is `null`.

[Deno KV]: https://deno.com/kv

### First cursor

The first cursor is a special cursor that represents the beginning of the
collection.  It's used to initialize a traversal of the collection.  The first
cursor is `null` if the collection is empty.

The value for the first cursor is determined by
`~CollectionCallbackSetters.setFirstCursor()` method:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Article, Create } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents a post.
 */
interface Post {
  /**
   * The ID of the post.
   */
  id: string;
  /**
   * The title of the post.
   */
  title: string;
  /**
   * The content of the post.
   */
  content: string;
}
/**
 * A hypothetical type that represents the result set of the posts.
 */
interface PostResultSet {
  /**
   * The posts that the actor has sent.
   */
  posts: Post[];
  /**
   * The next cursor that represents the position of the next page.
   */
  nextCursor: string | null;
  /**
   * Whether the current page is the last page.
   */
  last: boolean;
}
/**
 * A hypothetical type that represents the options for
 * the `getPostsByUserId` function.
 */
interface GetPostsByUserIdOptions {
  /**
   * The cursor that represents the position of the current page.
   */
  cursor?: string | null;
  /**
   * The number of items per page.
   */
  limit: number;
}
/**
 * A hypothetical function that returns the posts that an actor has sent.
 * @param userId The actor's identifier.
 * @returns The result set that contains the posts, the next cursor, and whether
 *          the current page is the last page.
 */
function getPostsByUserId(
  userId: string,
  options: GetPostsByUserIdOptions,
): PostResultSet {
  return { posts: [], nextCursor: null, last: true };
}
// ---cut-before---
// The number of items per page:
const window = 10;

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier, cursor) => {
    if (cursor == null) return null;
    // The following `getPostsByUserId` is a hypothetical function:
    const { posts, nextCursor, last } = await getPostsByUserId(
      identifier,
      cursor === "" ? { limit: window } : { cursor, limit: window }
    );
    // Turn the posts into `Create` activities:
    const items = posts.map(post =>
      new Create({
        id: new URL(`/posts/${post.id}#activity`, ctx.url),
        actor: ctx.getActorUri(identifier),
        object: new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        }),
      })
    );
    return { items, nextCursor: last ? null : nextCursor }
  })
  .setFirstCursor(async (ctx, identifier) => {
    // Let's assume that an empty string represents the beginning of the
    // collection:
    return "";  // Note that it's not `null`.
  });
```

In the above example, the first cursor is an empty string.  When the first
cursor is requested, the server queries the database *without any cursor* to
get the first few items of the collection.

Of course, since the first cursor is also an opaque token, you can use any
string as the first cursor.

> \[!NOTE]
> The first cursor is an enabler of the pagination.  If you don't set the first
> cursor, the collection is not considered as paginated, and the server will
> respond with the whole collection without any pagination.

### Counter

As the name suggests, the counter is a callback that counts the *total* number
of items in the collection, which is useful for the client to show, for example,
the total number of articles a user has posted.

The following example shows how to implement the counter for the outbox
collection:

```typescript twoslash
// @noErrors: 2345
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that counts the number of posts that an actor has
 * sent.
 * @param userId The actor's identifier.
 * @returns The number of posts that the actor has sent.
 */
async function countPostsByUserId(userId: string): Promise<number> {
  return 0;
}
// ---cut-before---
federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier, cursor) => {
    // Omitted for brevity.
  })
  .setCounter(async (ctx, identifier) => {
    // The following `countPostsByUserId` is a hypothetical function:
    return await countPostsByUserId(identifier);
  });
```

> \[!TIP]
> The counter can return either a `number` or a `bigint`.

### Last cursor

The last cursor is a special cursor that represents the end of the collection.
With the last cursor and `prevCursor`, the client can traverse the collection
backwards.

Since not all database systems support backward pagination, the last cursor is
optional.  If you don't set the last cursor, the client can only traverse the
collection forwards, which is fine in most cases.

So, the below example assumes that the database system supports offset-based
pagination, which is easy to implement backward pagination:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Article, Create } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents a post.
 */
interface Post {
  /**
   * The ID of the post.
   */
  id: string;
  /**
   * The title of the post.
   */
  title: string;
  /**
   * The content of the post.
   */
  content: string;
}
/**
 * A hypothetical type that represents the options for
 * the `getPostsByUserId` function.
 */
interface GetPostsByUserIdOptions {
  /**
   * The offset of the current page.
   */
  offset: number;
  /**
   * The number of items per page.
   */
  limit: number;
}
/**
 * A hypothetical function that returns the posts that an actor has sent.
 * @param userId The actor's identifier.
 * @returns The result set that contains the posts, the next cursor, and whether
 *          the current page is the last page.
 */
function getPostsByUserId(
  userId: string,
  options: GetPostsByUserIdOptions,
): Post[] {
  return [];
}
/**
 * A hypothetical function that counts the number of posts that an actor has
 * sent.
 * @param userId The actor's identifier.
 * @returns The number of posts that the actor has sent.
 */
async function countPostsByUserId(userId: string): Promise<number> {
  return 0;
}
// ---cut-before---
// The number of items per page:
const window = 10;

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier, cursor) => {
    if (cursor == null) return null;
    // Here we use the offset numeric value as the cursor:
    const offset = parseInt(cursor);
    // The following `getPostsByUserId` is a hypothetical function:
    const posts = await getPostsByUserId(
      identifier,
      { offset, limit: window }
    );
    // Turn the posts into `Create` activities:
    const items = posts.map(post =>
      new Create({
        id: new URL(`/posts/${post.id}#activity`, ctx.url),
        actor: ctx.getActorUri(identifier),
        object: new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        }),
      })
    );
    return { items, nextCursor: (offset + window).toString() }
  })
  .setFirstCursor(async (ctx, identifier) => "0")
  .setLastCursor(async (ctx, identifier) => {
    // The following `countPostsByUserId` is a hypothetical function:
    const total = await countPostsByUserId(identifier);
    // The last cursor is the offset of the last page:
    return (total - (total % window)).toString();
  });
```

### Constructing outbox collection URIs

To construct an outbox collection URI, you can use the `Context.getOutboxUri()`
method.  This method takes the actor's identifier and returns
the dereferenceable URI of the outbox collection of the actor.

The following shows how to construct an outbox collection URI of an actor named
`"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getOutboxUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getOutboxUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getOutboxUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getOutboxUri()` method does not guarantee that the outbox
> collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check if
> the identifier is valid before calling the method.

## Inbox

*This API is available since Fedify 0.11.0.*

The inbox collection is similar to the outbox collection, but it's a collection
of activities that an actor has received.

Cursors and counters for the inbox collection are implemented in the same way as
the outbox collection, so we don't repeat the explanation here.

The below example shows how to construct an inbox collection:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that returns the activities that an actor has
 * received.
 * @param userId The actor's identifier.
 * @returns The activities that the actor has received.
 */
async function getInboxByUserId(userId: string): Promise<Activity[]> {
  return [];
}
/**
 * A hypothetical function that counts the number of activities that an actor
 * has received.
 * @param userId The actor's identifier.
 * @returns The number of activities that the actor has received.
 */
async function countInboxByUserId(userId: string): Promise<number> {
  return 0;
}
// ---cut-before---
import { Activity } from "@fedify/vocab";

federation
  .setInboxDispatcher("/users/{identifier}/inbox", async (ctx, identifier) => {
    // Work with the database to find the activities that the actor has received
    // (the following `getInboxByUserId` is a hypothetical function):
    const items: Activity[] = await getInboxByUserId(identifier);
    return { items };
  })
  .setCounter(async (ctx, identifier) => {
    // The following `countInboxByUserId` is a hypothetical function:
    return await countInboxByUserId(identifier);
  });
```

> \[!NOTE]
> The path for the inbox collection dispatcher must match the path for the inbox
> listeners.

### Constructing inbox collection URIs

To construct an inbox collection URI, you can use the `Context.getInboxUri()`
method.  This method takes the actor's identifier and returns
the dereferenceable URI of the inbox collection of the actor.

The following shows how to construct an inbox collection URI of an actor named
`"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getInboxUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getInboxUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getInboxUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getInboxUri()` method does not guarantee that the inbox
> collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check if
> the identifier is valid before calling the method.

## Following

The following collection consists of the actors that an actor is following.
The following collection is similar to the outbox collection, but it's a
collection of actors instead of activities.  More specifically, the following
collection can consist of `Actor` objects or `URL` objects that represent the
actors.

Cursors and counters for the following collection are implemented in the same
way as the outbox collection, so we don't repeat the explanation here.

The below example shows how to construct a following collection:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents an actor in the database.
 */
interface User {
  /**
   * The URI of the actor.
   */
  uri: string;
}
/**
 * A hypothetical type that represents the result set of the actors that
 * an actor is following.
 */
interface ResultSet {
  /**
   * The actors that the actor is following.
   */
  users: User[];
  /**
   * The next cursor that represents the position of the next page.
   */
  nextCursor: string | null;
  /**
   * Whether the current page is the last page.
   */
  last: boolean;
}
/**
 * A hypothetical function that returns the actors that an actor is following.
 * @param userId The actor's identifier.
 * @param options The options for the query.
 * @returns The actors that the actor is following, the next cursor, and whether
 *          the current page is the last page.
 */
async function getFollowingByUserId(
  identifier: string,
  options: { cursor?: string | null; limit: number },
): Promise<ResultSet> {
  return { users: [], nextCursor: null, last: true };
}
// ---cut-before---
federation
  .setFollowingDispatcher("/users/{identifier}/following", async (ctx, identifier, cursor) => {
    // If a whole collection is requested, returns nothing as we prefer
    // collection pages over the whole collection:
    if (cursor == null) return null;
    // Work with the database to find the actors that the actor is following
    // (the below `getFollowingByUserId` is a hypothetical function):
    const { users, nextCursor, last } = await getFollowingByUserId(
      identifier,
      cursor === "" ? { limit: 10 } : { cursor, limit: 10 }
    );
    // Turn the users into `URL` objects:
    const items = users.map(actor => new URL(actor.uri));
    return { items, nextCursor: last ? null : nextCursor }
  })
  // The first cursor is an empty string:
  .setFirstCursor(async (ctx, identifier) => "");
```

### Constructing following collection URIs

To construct a following collection URI, you can use
the `Context.getFollowingUri()` method.  This method takes the actor's
identifier and returns the dereferenceable URI of the following collection
of the actor.

The following shows how to construct a following collection URI of an actor
named `"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFollowingUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getFollowingUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFollowingUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
> The `Context.getFollowingUri()` method does not guarantee that the following
> collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check if
> the identifier is valid before calling the method.

## Followers

The followers collection is very similar to the following collection, but it's
a collection of actors that are following the actor.  The followers collection
has to consist of `Recipient` objects that represent the actors.

The below example shows how to construct a followers collection:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents an actor in the database.
 */
interface User {
  /**
   * The URI of the actor.
   */
  uri: string;
  /**
   * The inbox URI of the actor.
   */
  inboxUri: string;
}
/**
 * A hypothetical type that represents the result set of the actors that
 * are following an actor.
 */
interface ResultSet {
  /**
   * The actors that are following the actor.
   */
  users: User[];
  /**
   * The next cursor that represents the position of the next page.
   */
  nextCursor: string | null;
  /**
   * Whether the current page is the last page.
   */
  last: boolean;
}
/**
 * A hypothetical type that represents the options for
 * the `getFollowersByUserId` function.
 */
interface GetFollowersByUserIdOptions {
  /**
   * The cursor that represents the position of the current page.
   */
  cursor?: string | null;
  /**
   * The number of items per page. If `null`, the entire collection is returned.
   */
  limit?: number | null;
}
/**
 * A hypothetical function that returns the actors that are following an actor.
 * @param userId The actor's identifier.
 * @param options The options for the query.
 * @returns The actors that are following the actor, the next cursor, and
 *          whether the current page is the last page.
 */
async function getFollowersByUserId(
  userId: string,
  options: GetFollowersByUserIdOptions = {},
): Promise<ResultSet> {
    return { users: [], nextCursor: null, last: true };
}
// ---cut-before---
federation
  .setFollowersDispatcher(
    "/users/{identifier}/followers",
    async (ctx, identifier, cursor) => {
      // If a whole collection is requested, returns nothing as we prefer
      // collection pages over the whole collection:
      if (cursor == null) return null;
      // Work with the database to find the actors that are following the actor
      // (the below `getFollowersByUserId` is a hypothetical function):
      const { users, nextCursor, last } = await getFollowersByUserId(
        identifier,
        cursor === "" ? { limit: 10 } : { cursor, limit: 10 }
      );
      // Turn the users into `Recipient` objects:
      const items: Recipient[] = users.map(actor => ({
        id: new URL(actor.uri),
        inboxId: new URL(actor.inboxUri),
      }));
      return { items, nextCursor: last ? null : nextCursor };
    }
  )
  // The first cursor is an empty string:
  .setFirstCursor(async (ctx, identifier) => "");
```

> \[!TIP]
>
> Every `Actor` object is also a `Recipient` object, so you can use the `Actor`
> object as the `Recipient` object.

### One-shot followers collection for gathering recipients

When you invoke `Context.sendActivity()` method with setting the `recipients`
parameter to `"followers"`, Fedify automatically gathers the recipients from
the followers collection.  In this case, the followers collection dispatcher
is not called by remote servers, but it's called in the same process.
Therefore, you don't have much merit to paginate the followers collection,
but instead you would want to gather all the followers at once.

Under the hood, the `Context.sendActivity()` method tries to gather the
recipients by calling the followers collection dispatcher with the `cursor`
parameter set to `null`.  However, if the followers collection dispatcher
returns `null`, the method treats it as a signal that the followers collection
is always paginated, and it gathers the recipients by paginating the followers
collection with multiple invocation of the followers collection dispatcher.
If the followers collection dispatcher returns an object that contains
the entire followers collection, the method gathers the recipients at once.

Therefore, if you use `"followers"` as the `recipients` parameter of
the `Context.sendActivity()` method, you should return the entire followers
collection when the `cursor` parameter is `null`:

```typescript{5-17} twoslash
import type { Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents an actor in the database.
 */
interface User {
  /**
   * The URI of the actor.
   */
  uri: string;
  /**
   * The inbox URI of the actor.
   */
  inboxUri: string;
}
/**
 * A hypothetical type that represents the result set of the actors that
 * are following an actor.
 */
interface ResultSet {
  /**
   * The actors that are following the actor.
   */
  users: User[];
  /**
   * The next cursor that represents the position of the next page.
   */
  nextCursor: string | null;
  /**
   * Whether the current page is the last page.
   */
  last: boolean;
}
/**
 * A hypothetical type that represents the options for
 * the `getFollowersByUserId` function.
 */
interface GetFollowersByUserIdOptions {
  /**
   * The cursor that represents the position of the current page.
   */
  cursor?: string | null;
  /**
   * The number of items per page. If `null`, the entire collection is returned.
   */
  limit?: number | null;
}
/**
 * A hypothetical function that returns the actors that are following an actor.
 * @param userId The actor's identifier.
 * @param options The options for the query.
 * @returns The actors that are following the actor, the next cursor, and
 *          whether the current page is the last page.
 */
async function getFollowersByUserId(
  userId: string,
  options: GetFollowersByUserIdOptions = {},
): Promise<ResultSet> {
    return { users: [], nextCursor: null, last: true };
}
// ---cut-before---
federation
  .setFollowersDispatcher(
    "/users/{identifier}/followers",
    async (ctx, identifier, cursor) => {
      // If a whole collection is requested, returns the entire collection
      // instead of paginating it, as we prefer one-shot gathering:
      if (cursor == null) {
        // Work with the database to find the actors that are following the actor
        // (the below `getFollowersByUserId` is a hypothetical function):
        const { users } = await getFollowersByUserId(identifier);
        return {
          items: users.map(actor => ({
            id: new URL(actor.uri),
            inboxId: new URL(actor.inboxUri),
          })),
        };
      }
      const { users, nextCursor, last } = await getFollowersByUserId(
        identifier,
        cursor === "" ? { limit: 10 } : { cursor, limit: 10 }
      );
      // Turn the users into `Recipient` objects:
      const items: Recipient[] = users.map(actor => ({
        id: new URL(actor.uri),
        inboxId: new URL(actor.inboxUri),
      }));
      return { items, nextCursor: last ? null : nextCursor };
    }
  )
  // The first cursor is an empty string:
  .setFirstCursor(async (ctx, identifier) => "");
```

> \[!CAUTION]
> The common pitfall is that the followers collection dispatcher returns
> the first page of the followers collection when the `cursor` parameter is
> `null`.  If the followers collection dispatcher returns only the first page
> when the `cursor` parameter is `null`, the `Context.sendActivity()` method
> will treat it as the entire followers collection, and it will not gather
> the rest of the followers collection.  Therefore, it will send the activity
> only to the followers in the first page.  Watch out for this pitfall.

### Filtering by server

*This API is available since Fedify 0.8.0.*

The followers collection can be filtered by the base URI of the actor URIs.
It can be useful to filter by a remote server to synchronize the followers
collection with it.

> \[!TIP]
> However, the filtering is optional, and you can skip it if you don't need
> [followers collection synchronization](./send.md#followers-collection-synchronization).

In order to filter the followers collection by the server, you need to let
your followers collection dispatcher be aware of the fourth argument:
the base URI of the actor URIs to filter in.  The base URI consists of
the protocol, the authority (the host and the port), and the root path of
the actor URIs.  When the base URI is not `null`, the dispatcher should
return only the actors whose URIs start with the base URI.  If the base URI
is `null`, the dispatcher should return all the actors.

The following example shows how to filter the followers collection by the
server:

```typescript{8-11} twoslash
import type { Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents an actor in the database.
 */
interface User {
  /**
   * The URI of the actor.
   */
  uri: URL;

  /**
   * The inbox URI of the actor.
   */
  inboxUri: URL;
}
/**
 * A hypothetical function that returns the actors that are following an actor.
 * @param userId The actor's identifier.
 * @returns The actors that are following the actor.
 */
async function getFollowersByUserId(userId: string): Promise<User[]> {
  return [];
}
// ---cut-before---
federation
  .setFollowersDispatcher(
    "/users/{identifier}/followers",
    async (ctx, identifier, cursor, baseUri) => {
      // Work with the database to find the actors that are following the actor
      // (the below `getFollowersByUserId` is a hypothetical function):
      let users = await getFollowersByUserId(identifier);
      // Filter the actors by the base URI:
      if (baseUri != null) {
        users = users.filter(actor => actor.uri.href.startsWith(baseUri.href));
      }
      // Turn the users into `Recipient` objects:
      const items: Recipient[] = users.map(actor => ({
        id: actor.uri,
        inboxId: actor.inboxUri,
      }));
      return { items };
    }
  );
```

> \[!NOTE]
> In the above example, we filter the actors in memory, but in the real
> world, you should filter the actors in the database query to improve the
> performance.

### Constructing followers collection URIs

To construct a followers collection URI, you can use
the `Context.getFollowersUri()` method.  This method takes the actor's
identifier and returns the dereferenceable URI of the followers collection
of the actor.

The following shows how to construct a followers collection URI of an actor
named `"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFollowersUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getFollowersUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFollowersUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getFollowersUri()` method does not guarantee that the followers
> collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check if
> the identifier is valid before calling the method.

## Liked

*This API is available since Fedify 0.15.0.*

The liked collection is a collection of objects that an actor has liked.
The liked collection is similar to the outbox collection, but it's a collection
of `Object`s instead of `Activity` objects.

Cursors and counters for the liked collection are implemented in the same way as
the outbox collection, so we don't repeat the explanation here.

The below example shows how to construct a liked collection:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that returns the objects that an actor has liked.
 * @param userId The actor's identifier.
 * @returns The objects that the actor has liked.
 */
async function getLikedByUserId(userId: string): Promise<Object[]> {
  return [];
}
// ---cut-before---
import type { Object } from "@fedify/vocab";

federation
  .setLikedDispatcher("/users/{identifier}/liked", async (ctx, identifier, cursor) => {
    // Work with the database to find the objects that the actor has liked
    // (the below `getLikedPostsByUserId` is a hypothetical function):
    const items: Object[] = await getLikedByUserId(identifier);
    return { items };
  });
```

Or you can yield the object URIs instead of the objects:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that returns the objects that an actor has liked.
 * @param userId The actor's identifier.
 * @returns The objects that the actor has liked.
 */
async function getLikedByUserId(userId: string): Promise<Object[]> {
  return [];
}
// ---cut-before---
import type { Object } from "@fedify/vocab";

federation
  .setLikedDispatcher("/users/{identifier}/liked", async (ctx, identifier, cursor) => {
    // Work with the database to find the objects that the actor has liked
    // (the below `getLikedPostsByUserId` is a hypothetical function):
    const objects: Object[] = await getLikedByUserId(identifier);
    // Turn the objects into `URL` objects:
    const items: URL[] = objects.map(obj => obj.id).filter(id => id != null);
    return { items };
  });
```

### Constructing liked collection URIs

To construct a liked collection URI, you can use the `Context.getLikedUri()`
method.  This method takes the actor's identifier and returns
the dereferenceable URI of the liked collection of the actor.

The following shows how to construct a liked collection URI of an actor named
`"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getLikedUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getLikedUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getLikedUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getLikedUri()` method does not guarantee that the liked
> collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check if
> the identifier is valid before calling the method.

## Featured

*This API is available since Fedify 0.11.0.*

The featured collection is a collection of objects that an actor has featured
on top of their profile, i.e., pinned statuses.  The featured collection is
similar to the outbox collection, but it's a collection of any ActivityStreams
objects instead of activities.

Cursors and counters for the featured collection are implemented in the same way
as the outbox collection, so we don't repeat the explanation here.

The below example shows how to construct a featured collection:

```typescript twoslash
import type { Federation } from "@fedify/fedify";
import type { Object } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that returns the objects that an actor has featured.
 * @param userId The actor's identifier.
 * @returns The objects that the actor has featured.
 */
async function getFeaturedByUserId(userId: string): Promise<Object[]> {
  return [];
}
// ---cut-before---
federation
  .setFeaturedDispatcher("/users/{identifier}/featured", async (ctx, identifier, cursor) => {
    // Work with the database to find the objects that the actor has featured
    // (the below `getFeaturedPostsByUserId` is a hypothetical function):
    const items = await getFeaturedByUserId(identifier);
    return { items };
  });
```

### Constructing featured collection URIs

To construct a featured collection URI, you can use
the `Context.getFeaturedUri()` method.  This method takes the actor's identifier
and returns the dereferenceable URI of the featured collection of the actor.

The following shows how to construct a featured collection URI of an actor named
`"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFeaturedUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getFeaturedUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFeaturedUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getFeaturedUri()` method does not guarantee that the featured
> collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check if
> the identifier is valid before calling the method.

## Featured tags

*This API is available since Fedify 0.11.0.*

The featured tags collection is a collection of tags that an actor has featured
on top of their profile.  The featured tags collection is similar to the
featured collection, but it's a collection of `Hashtag` objects instead of
any ActivityStreams objects.

Cursors and counters for the featured tags collection are implemented in the
same way as the outbox collection, so we don't repeat the explanation here.

The below example shows how to construct a featured tags collection:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Hashtag } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that returns the tags that an actor has featured.
 * @param userId The actor's identifier.
 * @returns The tags that the actor has featured.
 */
async function getFeaturedTagsByUserId(userId: string): Promise<string[]> {
  return [];
}
// ---cut-before---
federation
  .setFeaturedTagsDispatcher("/users/{identifier}/tags", async (ctx, identifier, cursor) => {
    // Work with the database to find the tags that the actor has featured
    // (the below `getFeaturedTagsByUserId` is a hypothetical function):
    const hashtags = await getFeaturedTagsByUserId(identifier);
    const items = hashtags.map(hashtag =>
      new Hashtag({
        href: new URL(`/tags/${encodeURIComponent(hashtag)}`, ctx.url),
        name: `#${hashtag}`,
      })
    );
    return { items };
  });
```

### Constructing featured tags collection URIs

To construct a featured tags collection URI, you can use
the `Context.getFeaturedTagsUri()` method.  This method takes the actor's
identifier and returns the dereferenceable URI of the featured tags collection
of the actor.

The following shows how to construct a featured tags collection URI of an actor
named `"alice"`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFeaturedTagsUri("alice")
```

If you [decouple the WebFinger username from the actor's
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
you should pass the identifier that is used in
the [actor dispatcher](./actor.md) to the `Context.getFeaturedTagsUri()` method,
not the WebFinger username:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getFeaturedTagsUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
```

> \[!NOTE]
>
> The `Context.getFeaturedTagsUri()` method does not guarantee that the featured
> tags collection actually exists.  It only constructs a URI based on the given
> identifier, which may respond with `404 Not Found`.  Make sure to check
> if the identifier is valid before calling the method.

## Custom collections

*This API is available since Fedify 1.8.0.*

In addition to the built-in collections like outbox, inbox, following, and
followers, Fedify allows you to create custom collections for your specific
needs.  Custom collections can be used to expose any type of ActivityPub
objects in a paginated manner.

There are two types of custom collections you can create:

* **Collection**: An unordered collection of objects
* **Ordered Collection**: An ordered collection of objects where the order
  matters

### Setting up a custom collection

To create a custom collection, you use either `setCollectionDispatcher()` for
unordered collections or `setOrderedCollectionDispatcher()` for ordered
collections. Both methods work similarly to the built-in collection dispatchers.

Here's an example of creating a custom collection of bookmarked posts:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Article } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents a bookmarked post.
 */
interface BookmarkedPost {
  /**
   * The ID of the post.
   */
  id: string;
  /**
   * The title of the post.
   */
  title: string;
  /**
   * The content of the post.
   */
  content: string;
}
/**
 * A hypothetical function that returns the bookmarked posts for a user.
 */
async function getBookmarkedPostsByUserId(
  userId: string,
  cursor?: string | null,
  limit = 10,
): Promise<{ posts: BookmarkedPost[]; nextCursor: string | null }> {
  return { posts: [], nextCursor: null };
}
/**
 * A hypothetical function that counts bookmarked posts for a user.
 */
async function getBookmarkCountByUserId(userId: string): Promise<number> {
  return 0;
}
// ---cut-before---
federation
  .setCollectionDispatcher(
    "bookmarks",  // Unique name for this collection
    Article,      // Type of objects in the collection
    "/users/{identifier}/bookmarks", // URI pattern
    async (ctx, values, cursor) => {
      // If a whole collection is requested, return null to use pagination
      if (cursor == null) return null;

      // Work with the database to find bookmarked posts
      const { posts, nextCursor } = await getBookmarkedPostsByUserId(
        values.identifier,
        cursor === "" ? null : cursor,
        10
      );

      // Convert posts to Article objects
      const items = posts.map(post =>
        new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        })
      );

      return { items, nextCursor };
    }
  )
  .setFirstCursor(async (ctx, values) => "")
  .setCounter(async (ctx, values) => {
    // Return the total count of bookmarked posts
    const count = await getBookmarkCountByUserId(values.identifier);
    return count;
  });
```

For ordered collections, simply use `setOrderedCollectionDispatcher()` instead:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Article } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents a bookmarked post.
 */
interface BookmarkedPost {
  /**
   * The ID of the post.
   */
  id: string;
  /**
   * The title of the post.
   */
  title: string;
  /**
   * The content of the post.
   */
  content: string;
}
/**
 * A hypothetical function that returns the bookmarked posts for a user.
 */
async function getBookmarkedPostsByUserId(
  userId: string,
  cursor?: string | null,
  limit = 10,
): Promise<{ posts: BookmarkedPost[]; nextCursor: string | null }> {
  return { posts: [], nextCursor: null };
}
/**
 * A hypothetical function that counts bookmarked posts for a user.
 */
async function getBookmarkCountByUserId(userId: string): Promise<number> {
  return 0;
}
// ---cut-before---
federation
  .setOrderedCollectionDispatcher(
    "bookmarks",  // Unique name for this collection
    Article,      // Type of objects in the collection
    "/users/{identifier}/bookmarks", // URI pattern
    async (ctx, values, cursor) => {
      // Implementation is the same as regular collections
      if (cursor == null) return null;

      const { posts, nextCursor } = await getBookmarkedPostsByUserId(
        values.identifier,
        cursor === "" ? null : cursor,
        10
      );

      const items = posts.map(post =>
        new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        })
      );

      return { items, nextCursor };
    }
  )
  .setFirstCursor(async (ctx, values) => "")
  .setCounter(async (ctx, values) => {
    return await getBookmarkCountByUserId(values.identifier);
  });
```

### Custom collection callbacks

Custom collections support the same callback methods as built-in collections:

* **`.setCounter()`**: Sets a callback that returns the total number of items
  in the collection
* **`.setFirstCursor()`**: Sets the cursor for the first page of the collection
* **`.setLastCursor()`**: Sets the cursor for the last page of the collection
* **`.authorize()`**: Sets an authorization predicate to control access to
  the collection

### Multiple parameters

Custom collections can have multiple parameters in their URI patterns:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that returns posts by category.
 */
async function getPostsByCategory(
  userId: string,
  category: string,
  cursor?: string | null,
): Promise<{ posts: any[]; nextCursor: string | null }> {
  return { posts: [], nextCursor: null };
}
// ---cut-before---
federation
  .setCollectionDispatcher(
    "category-posts",
    Note,
    "/users/{identifier}/categories/{category}/posts",
    async (ctx, values, cursor) => {
      // values.identifier and values.category are both available
      const { posts, nextCursor } = await getPostsByCategory(
        values.identifier,
        values.category,
        cursor === "" ? null : cursor
      );

      const items = posts.map(post => new Note({
        id: new URL(`/posts/${post.id}`, ctx.url),
        content: post.content,
      }));

      return { items, nextCursor };
    }
  )
  .setFirstCursor(async (ctx, values) => "");
```

### Constructing custom collection URIs

To construct a custom collection URI, you can use the
`Context.getCollectionUri()` method. This method takes the collection name and
the parameter values:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
// For a collection with one parameter:
ctx.getCollectionUri("bookmarks", { identifier: "alice" })

// For a collection with multiple parameters:
ctx.getCollectionUri("category-posts", {
  identifier: "alice",
  category: "technology"
})
```

> \[!NOTE]
>
> The `Context.getCollectionUri()` method does not guarantee that the custom
> collection actually exists.  It only constructs a URI based on the given
> name and parameters, which may respond with `404 Not Found`.  Make sure to
> check if the parameters are valid before calling the method.

### Authorization

You can restrict access to custom collections using the `.authorize()` method:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Article } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical function that checks if a user can access another user's bookmarks.
 */
async function canAccessBookmarks(
  viewerId: string | null,
  ownerId: string,
): Promise<boolean> {
  return false;
}
/**
 * A hypothetical function that returns the bookmarked posts for a user.
 */
async function getBookmarkedPostsByUserId(
  userId: string,
  cursor?: string | null,
  limit = 10,
): Promise<{ posts: any[]; nextCursor: string | null }> {
  return { posts: [], nextCursor: null };
}
async function getActorIdentifier(actorId: URL|null): Promise<string | null> {
  // Hypothetical function to get the identifier of an actor
  return "";
}
// ---cut-before---
federation
  .setCollectionDispatcher(
    "private-bookmarks",
    Article,
    "/users/{identifier}/private-bookmarks",
    async (ctx, values, cursor) => {
      if (cursor == null) return null;

      const { posts, nextCursor } = await getBookmarkedPostsByUserId(
        values.identifier,
        cursor === "" ? null : cursor
      );

      const items = posts.map(post =>
        new Article({
          id: new URL(`/posts/${post.id}`, ctx.url),
          summary: post.title,
          content: post.content,
        })
      );

      return { items, nextCursor };
    }
  )
  .setFirstCursor(async (ctx, values) => "")
  .authorize(async (ctx, values) => {
    // Only allow access if the viewer is the owner of the bookmarks
    const signedKeyOwner = await ctx.getSignedKeyOwner();
    if (signedKeyOwner == null) return false;

    const viewerId = await getActorIdentifier(signedKeyOwner.id);
    return await canAccessBookmarks(viewerId, values.identifier);
  });
```

---

---
url: /manual/context.md
description: >-
  The Context object is a container that holds the information of the current
  request.  This section explains the key features of the Context object.
---

# Context

The `Context` object is a container that holds the information of the current
request.  It is passed to various callback functions that are registered to
the `Federation` object, and also can be gathered from the outside of the
callbacks.

The key features of the `Context` object are as follows:

* Carrying [`TContextData`](./federation.md#tcontextdata)
* [Building the object URIs](#building-the-object-uris)
  (e.g., actor URIs, shared inbox URI)
* [Dispatching Activity Vocabulary objects](#dispatching-objects)
* Getting the current HTTP request
* [Enqueuing an outgoing activity](#enqueuing-an-outgoing-activity)
* [Getting a `DocumentLoader`](#getting-a-documentloader)
* [Looking up remote objects](#looking-up-remote-objects)
* [NodeInfo client](./nodeinfo.md#nodeinfo-client)

## Where to get a `Context` object

You can get a `Context` object from the first parameter of most of the callbacks
that are registered to the `Federation` object.  The following shows a few
callbacks that take a `Context` object as the first parameter:

* [Actor dispatcher](./actor.md)
* [Inbox listeners](./inbox.md)
* [Outbox collection dispatcher](./collections.md#outbox)
* [Inbox collection dispatcher](./collections.md#inbox)
* [Following collection dispatcher](./collections.md#following)
* [Followers collection dispatcher](./collections.md#followers)
* [Liked collection dispatcher](./collections.md#liked)
* [Featured collection dispatcher](./collections.md#featured)
* [Featured tags collection dispatcher](./collections.md#featured-tags)
* [NodeInfo dispatcher](./nodeinfo.md)

Those are not all; there are more callbacks that take a `Context` object.

You can also get a `Context` object from the `Federation` object by calling the
`~Federation.createContext()` method.  The following shows an example:

```typescript twoslash
// @noErrors
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { federation } from "../federation.ts"; // Import the `Federation` object

export async function handler(request: Request) {
  const ctx = federation.createContext(request, undefined);  // [!code highlight]
  // Work with the `ctx` object...
};
```

## Getting the base URL

*This API is available since Fedify 0.12.0.*

The `Context` object has properties to get the base URL of the current request:

| Property                  | Description                                              | Value example              |
| ------------------------- | -------------------------------------------------------- | -------------------------- |
| `Context.hostname`        | A hostname                                               | `"example.com"`            |
| `Context.host`            | A hostname followed by an optional port                  | `"example.com:88"`         |
| `Context.origin`          | A scheme followed by a host                              | `"https://example.com:88"` |
| `Context.canonicalOrigin` | An explicitly configured `~FederationOptions.origin`\[^1] | `"https://example.com"`    |

For `RequestContext`, there is an additional property named
`~RequestContext.url` that contains the full URL of the current request.

\[^1]: If no canonical origin is explicitly configured, it is the same as the
`Context.origin`. See also the [*Explicitly setting the canonical origin*
section](./federation.md#explicitly-setting-the-canonical-origin) in the
*Federation* document.

## Building the object URIs

The `Context` object has a few methods to build the object URIs.  The following
shows the methods:

* `~Context.getNodeInfoUri()`
* `~Context.getActorUri()`
* `~Context.getObjectUri()`
* `~Context.getInboxUri()`
* `~Context.getOutboxUri()`
* `~Context.getFollowingUri()`
* `~Context.getFollowersUri()`
* `~Context.getLikedUri()`
* `~Context.getFeaturedUri()`
* `~Context.getFeaturedTagsUri()`

You could hard-code the URIs, but it is better to use those methods to build
the URIs because the URIs are subject to change in the future.

Here's an example of using the `~Context.getActorUri()` method in the actor
dispatcher:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
interface User { }
const user: User | null = true ? { } : null;
// ---cut-before---
federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  // Work with the database to find the actor by the identifier.
  if (user == null) return null;
  return new Person({
    id: ctx.getActorUri(identifier),  // [!code highlight]
    preferredUsername: identifier,
    // Many more properties...
  });
});
```

On the other way around, you can use the `~Context.parseUri()` method to
determine the type of the URI and extract the identifier or other values from
the URI.

## Enqueuing an outgoing activity

The `Context` object can enqueue an outgoing activity to the actor's outbox
by calling the `~Context.sendActivity()` method.  The following shows an
example in an [inbox listener](./inbox.md):

```typescript{12-16} twoslash
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { Accept, Follow } from "@fedify/vocab";

federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    // In order to send an activity, we need the identifier of the sender actor:
    if (follow.objectId == null) return;
    const parsed = ctx.parseUri(follow.objectId);
    if (parsed?.type !== "actor") return;
    const recipient = await follow.getActor(ctx);
    if (recipient == null) return;
    await ctx.sendActivity(
      { identifier: parsed.identifier }, // sender
      recipient,
      new Accept({ actor: follow.objectId, object: follow }),
    );
  });
```

For more information about this topic, see the [*Sending activities*
section](./send.md).

> \[!NOTE]
> The `~Context.sendActivity()` method works only if the [key pairs dispatcher]
> is registered to the `Federation` object.  If the key pairs dispatcher is not
> registered, the `~Context.sendActivity()` method throws an error.

> \[!TIP]
> Why do you need to enqueue an outgoing activity, instead of directly sending
> the activity to the recipient's inbox?  The reason is that in distributed
> systems, we need to consider the delivery failure.  If the delivery fails,
> the system needs to retry the delivery.  Delivery failure can happen for
> various reasons, such as network failure, recipient server failure, and so on.
>
> Anyway, you don't have to worry about the delivery failure because the
> Fedify handles the delivery failure by enqueuing the outgoing
> activity to the actor's outbox and retrying the delivery on failure.

[key pairs dispatcher]: ./actor.md#public-keys-of-an-actor

## Dispatching objects

*This API is available since Fedify 0.7.0.*

The `RequestContext` object has a method to dispatch an Activity Vocabulary
object from the URL arguments.  The following shows an example of using
the `RequestContext.getActor()` method:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Update } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
const request = new Request("");
const identifier: string = "";
// ---cut-before---
const ctx = federation.createContext(request, undefined);
const actor = await ctx.getActor(identifier);  // [!code highlight]
if (actor != null) {
  await ctx.sendActivity(
    { identifier },
    "followers",
    new Update({ actor: actor.id, object: actor }),
  );
}
```

> \[!NOTE]
> The `RequestContext.getActor()` method is only available when the actor
> dispatcher is registered to the `Federation` object.  If the actor dispatcher
> is not registered, the `RequestContext.getActor()` method throws an error.

In the same way, you can use the `RequestContext.getObject()` method to dispatch
an object from the URL arguments.  The following shows an example:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
const request = new Request("");
const identifier: string = "";
const id: string = "";
// ---cut-before---
const ctx = federation.createContext(request, undefined);
const note = await ctx.getObject(Note, { identifier, id });  // [!code highlight]
```

## Getting a `DocumentLoader`

The `Context.documentLoader` property carries a `DocumentLoader` object that
is specified in the `Federation` constructor.  It is used to load remote
documents and contexts in the JSON-LD format.  There are a few methods to take
a `DocumentLoader` as an option in vocabulary API:

* [`fromJsonLd()` static method](./vocab.md#json-ld)
* [`toJsonLd()` method](./vocab.md#json-ld)
* [`get*()` dereferencing accessors](./vocab.md#object-ids-and-remote-objects)
* [`lookupObject()` function](./vocab.md#looking-up-remote-objects)

All of those methods take options in the form of
`{ documentLoader?: DocumentLoader, contextLoader?: DocumentLoader }` which is
compatible with `Context`.  So you can just pass a `Context` object to those
methods:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Object } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const jsonLd: unknown = {};
// ---cut-before---
const object = await Object.fromJsonLd(jsonLd, ctx);
const json = await object.toJsonLd(ctx);
```

## Getting an authenticated `DocumentLoader`

*This API is available since Fedify 0.4.0.*

Sometimes you need to load a remote document which requires authentication,
such as an actor's following collection that is configured as private.
In such cases, you can use the `Context.getDocumentLoader()` method to get
an authenticated `DocumentLoader` object.  The following shows an example:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { type Actor, Person } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const actor = new Person({}) as Actor;
// ---cut-before---
const documentLoader = await ctx.getDocumentLoader({
  identifier: "2bd304f9-36b3-44f0-bf0b-29124aafcbb4",
});
const following = await actor.getFollowing({ documentLoader });
```

In the above example, the `getFollowing()` method takes the `documentLoader`
which is authenticated as the actor with an identifier of
`2bd304f9-36b3-44f0-bf0b-29124aafcbb4`.  If the `actor` allows
actor `2bd304f9-36b3-44f0-bf0b-29124aafcbb4` to see the following collection,
the `getFollowing()` method returns the following collection.

> \[!TIP]
> Inside a personal inbox listener, the `Context.documentLoader` property is
> automatically set to an authenticated `DocumentLoader` object that is
> identified by the inbox owner's key.  So you don't need to call the
> `Context.getDocumentLoader()` method in the personal inbox listener,
> but just passing the `Context` object to dereferencing accessors is enough.
>
> See the [*`Context.documentLoader` on an inbox listener*
> section](./inbox.md#context-documentloader-on-an-inbox-listener) for details.

## Document loader vs. context loader

Both a document loader and a context loader are represented by `DocumentLoader`
type, but they are used for different purposes:

* A document loader is used to load remote documents,
  such as an actor's profile document, an object document, and so on.

* A context loader is used to load remote contexts,
  such as the ActivityStreams context, the W3C security context, and so on.

Sometimes a document loader needs to be authenticated to load a remote document
which requires authorization, but a context loader mostly needs to be highly
cached and doesn't require authorization.

## Looking up remote objects

*This API is available since Fedify 0.15.0.*

> \[!TIP]
> In most cases, you don't need to look up remote objects explicitly.
> Instead, you can use the dereferencing accessors to fetch the remote objects
> implicitly.
>
> For example, you can get the `object` from an `Activity` object directly:
>
> ```typescript twoslash
> import { Activity } from "@fedify/vocab";
> const activity = new Activity({});
> // ---cut-before---
> const object = await activity.getObject();
> ```
>
> … instead of:
>
> ```typescript twoslash
> import { type Context } from "@fedify/fedify";
> import { Activity } from "@fedify/vocab";
> const ctx = null as unknown as Context<void>;
> const activity = new Activity({});
> // ---cut-before---
> const object = activity.objectId == null
>   ? null
>   : await ctx.lookupObject(activity.objectId);
> ```

Suppose your app has a search box that allows the user to look up a fediverse
user by the handle or a post by the URI.  In such cases, you need to look up
the object from a remote server that your app haven't interacted with yet.
The `Context.lookupObject()` method plays a role in such cases.  The following
shows an example of looking up an actor object from the handle:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const actor = await ctx.lookupObject("@hongminhee@todon.eu");
```

In the above example, the `~Context.lookupObject()` method queries the remote
server's WebFinger endpoint to get the actor's URI from the handle,
and then fetches the actor object from the URI.

> \[!TIP]
> The `~Context.lookupObject()` method accepts a fediverse handle without
> prefix `@` as well:
>
> ```typescript twoslash
> import { type Context } from "@fedify/fedify";
> const ctx = null as unknown as Context<void>;
> // ---cut-before---
> const actor = await ctx.lookupObject("hongminhee@todon.eu");
> ```
>
> Also an `acct:` URI:
>
> ```typescript twoslash
> import { type Context } from "@fedify/fedify";
> const ctx = null as unknown as Context<void>;
> // ---cut-before---
> const actor = await ctx.lookupObject("acct:hongminhee@todon.eu");
> ```

The `~Context.lookupObject()` method is not limited to the actor object.
It can look up any object in the Activity Vocabulary.  For example
the following shows an example of looking up a `Note` object from the URI:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const note = await ctx.lookupObject(
  "https://todon.eu/@hongminhee/112060633798771581"
);
```

> \[!NOTE]
> Some objects require authentication to look up, such as a `Note` object with
> a visibility of followers-only.  In such cases, you need to use
> the `Context.getDocumentLoader()` method to get an authenticated
> `DocumentLoader` object.  The `~Context.lookupObject()` method takes the
> `documentLoader` option to specify the method to fetch the remote object:
>
> ```typescript twoslash
> import { type Context } from "@fedify/fedify";
> const ctx = null as unknown as Context<void>;
> // ---cut-before---
> const documentLoader = await ctx.getDocumentLoader({ identifier: "john" });
> const note = await ctx.lookupObject("...", { documentLoader });
> ```
>
> See the [*Getting an authenticated
> `DocumentLoader`*](#getting-an-authenticated-documentloader)
> section for details.

> \[!CAUTION]
> For security reasons, the `~Context.lookupObject()` method implements
> origin-based validation following [FEP-fe34].  If the fetched JSON-LD
> document contains an `@id` that has a different origin than the requested
> URL, the method will return `null` by default to prevent content spoofing
> attacks.
>
> For example, if you request `https://example.com/notes/123` but the fetched
> document has `@id: "https://malicious.com/notes/456"`, the method will
> refuse to return the object and log a warning instead.
>
> You can control this behavior using the `crossOrigin` option:
>
> ```typescript twoslash
> import { type Context } from "@fedify/fedify";
> const ctx = null as unknown as Context<void>;
> // ---cut-before---
> // Default behavior: return null for cross-origin objects (recommended)
> const objectDefault = await ctx.lookupObject("https://example.com/notes/123");
>
> // Throw an error when encountering cross-origin objects
> const objectStrict = await ctx.lookupObject(
>   "https://example.com/notes/123",
>   { crossOrigin: "throw" }
> );
>
> // Bypass origin checks (not recommended, potential security risk)
> const objectBypass = await ctx.lookupObject(
>   "https://example.com/notes/123",
>   { crossOrigin: "trust" }
> );
> ```
>
> Only use `crossOrigin: "trust"` if you fully understand the security
> implications and have implemented additional validation measures.

[FEP-fe34]: https://w3id.org/fep/fe34

## WebFinger lookups

*This API is available since Fedify 1.6.0.*

The `Context` provides a dedicated method for WebFinger lookups when you need
to find information about accounts and resources across federated networks.
The `~Context.lookupWebFinger()` method allows you to query a remote server's
WebFinger endpoint directly:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const webfingerData = await ctx.lookupWebFinger("acct:fedify@hollo.social");
```

If the lookup fails or the account doesn't exist, the method returns `null`.
The returned WebFinger document contains links to various resources associated
with the account, such as profile pages, ActivityPub actor URIs, and more:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const webfingerData = await ctx.lookupWebFinger("acct:fedify@hollo.social");

// Find the ActivityPub actor URI
const activityPubActorLink = webfingerData?.links?.find(link =>
  link.rel === "self" && link.type === "application/activity+json"
);

if (activityPubActorLink?.href) {
  const actor = await ctx.lookupObject(activityPubActorLink.href);
  // Work with the actor...
}
```

> \[!NOTE]
> In most cases, you can use the higher-level `~Context.lookupObject()` method
> which automatically performs WebFinger lookups when given a handle.
> Use `~Context.lookupWebFinger()` when you need the raw WebFinger data or
> want more direct control over the lookup process.

## Traversing remote collections

*This API is available since Fedify 1.1.0.*

Sometimes you need to traverse a remote collection from the beginning
to the end, such as an actor's outbox, an actor's followers collection,
and so on.  The `Context.traverseCollection()` method plays a role in such
cases.  The following shows an example of traversing an actor's outbox:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { isActor } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const actor = await ctx.lookupObject("@hongminhee@fosstodon.org");
if (isActor(actor)) {
  const outbox = await actor.getOutbox();
  if (outbox != null) {
    for await (const activity of ctx.traverseCollection(outbox)) {
      console.log(activity);
    }
  }
}
```

## Replacing the context data

*This API is available since Fedify 1.6.0.*

You can replace the context data by calling the `Context.clone()` method.
This is useful when you want to create a new context based on the existing one
but with different data.  The following shows an example of replacing the
context data:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<{ foo: string; bar: number }>;
// ---cut-before---
const newCtx = ctx.clone({ ...ctx.data, foo: "new value" });
```

---

---
url: /tutorial/microblog.md
description: >-
  In this tutorial, we will build a small microblog that implements the
  ActivityPub protocol, similar to Mastodon or Misskey, using Fedify, an
  ActivityPub server framework.
---

# Creating your own federated microblog

> \[!TIP]
>
> This tutorial is also available in the following languages: [한국어] (Korean)
> and [日本語] (Japanese).

In this tutorial, we will build a small [microblog] that implements
the ActivityPub protocol, similar to [Mastodon] or [Misskey], using [Fedify],
an ActivityPub server framework. This tutorial will focus more on how to
use Fedify rather than understanding its underlying operating principles.

If you have any questions, suggestions, or feedback, please feel free to join
our [Matrix chat space] or [Discord server] or [GitHub Discussions].

[한국어]: https://hackers.pub/@hongminhee/2025/fedify-tutorial-ko

[日本語]: https://zenn.dev/hongminhee/books/4a38b6358a027b

[microblog]: https://en.wikipedia.org/wiki/Microblogging

[Mastodon]: https://joinmastodon.org/

[Misskey]: https://misskey-hub.net/

[Fedify]: https://fedify.dev/

[Matrix chat space]: https://matrix.to/#/#fedify:matrix.org

[Discord server]: https://discord.gg/bhtwpzURwd

[GitHub Discussions]: https://github.com/fedify-dev/fedify/discussions

## Target audience

This tutorial is aimed at those who want to learn Fedify and create ActivityPub
server software.

We assume that you have experience in creating web applications using HTML
and HTTP, and that you understand command-line interfaces, SQL, JSON,
and basic JavaScript. However, you don't need to know TypeScript, JSX,
ActivityPub, or Fedify—we'll teach you what you need to know about these as
we go along.

You don't need experience in creating ActivityPub software, but we do assume
that you've used at least one ActivityPub software like Mastodon or Misskey.
This is so you have an idea of what we're trying to build.

\*\[JSX]: JavaScript XML

## Goals

In this tutorial, we'll use Fedify to create a single-user microblog that can
communicate with other federated software and services via ActivityPub.
This software will include the following features:

* Only one account can be created.
* Other accounts in the fediverse can follow the user.
* Followers can unfollow the user.
* The user can view their list of followers.
* The user can create posts.
* The user's posts are visible to followers in the fediverse.
* The user can follow other accounts in the fediverse.
* The user can view a list of accounts they are following.
* The user can view a chronological list of posts from accounts they follow.

To simplify the tutorial, we'll impose the following feature constraints:

* Account profiles (bio, photos, etc.) cannot be set.
* Once created, an account cannot be deleted.
* Once posted, a post cannot be edited or deleted.
* Once followed, another account cannot be unfollowed.
* There are no likes, shares, or comments.
* There is no search functionality.
* There are no security features such as authentication or permission checks.

Of course, after completing the tutorial, you're welcome to add these
features—it would be good practice!

The complete source code is available in the [GitHub repository],
with commits separated according to each implementation step for your reference.

[GitHub repository]: https://github.com/fedify-dev/microblog

## Setting up the development environment

### Installing Node.js

Fedify supports three JavaScript runtimes: [Deno], [Bun], and [Node.js].
Among these, Node.js is the most widely used, so we'll use Node.js as the basis
for this tutorial.

> \[!TIP]
> A JavaScript runtime is a platform that executes JavaScript code. Web browsers
> are one type of JavaScript runtime, and for command-line or server use,
> Node.js is widely used. Recently, cloud edge functions like
> [Cloudflare Workers] have also gained popularity as JavaScript runtimes.

To use Fedify, you need Node.js version 22.0.0 or higher. There are
[various installation methods]—choose the one that suits you best.

Once Node.js is installed, you'll have access to the `node` and `npm` commands:

```sh
node --version
npm --version
```

[Deno]: https://deno.com/

[Bun]: https://bun.sh/

[Node.js]: https://nodejs.org/

[Cloudflare Workers]: https://workers.cloudflare.com/

[various installation methods]: https://nodejs.org/en/download/package-manager

### Installing the `fedify` command

To set up a Fedify project, you need to install the [`fedify`](../cli.md)
command on your system. There are
[several installation methods](../cli.md#installation),
but using the `npm` command is the simplest:

```sh
npm install -g @fedify/cli
```

After installation, check if you can use the `fedify` command. You can check
the version of the `fedify` command with this command:

```sh
fedify --version
```

Make sure the version number is 1.0.0 or higher. If it's an older version,
you won't be able to properly follow this tutorial.

### `fedify init` to initialize the project

To start a new Fedify project, let's decide on a directory path to work in.
In this tutorial, we'll name it *microblog*. Run the
[`fedify init`](../cli.md#fedify-init-initializing-a-fedify-project) command
followed by the directory path (it's okay if the directory doesn't exist yet):

```sh
fedify init microblog
```

When you run the `fedify init` command, you'll see a series of prompts.
Select *Node.js*, *npm*, *Hono*, *In-memory*, and *In-process* in order:

```console
             ___      _____        _ _  __
            /'_')    |  ___|__  __| (_)/ _|_   _
     .-^^^-/  /      | |_ / _ \/ _` | | |_| | | |
   __/       /       |  _|  __/ (_| | |  _| |_| |
  <__.|_|-|_|        |_|  \___|\__,_|_|_|  \__, |
                                           |___/

? Choose the JavaScript runtime to use
  Deno
  Bun
❯ Node.js

? Choose the package manager to use
❯ npm
  Yarn
  pnpm

? Choose the web framework to integrate Fedify with
  Bare-bones
  Fresh
❯ Hono
  Express
  Nitro

? Choose the key–value store to use for caching
❯ In-memory
  Redis
  PostgreSQL
  Deno KV

? Choose the message queue to use for background jobs
❯ In-process
  Redis
  PostgreSQL
  AMQP (e.g., RabbitMQ)
  Deno KV
```

> \[!NOTE]
> Fedify is not a full-stack framework, but rather a framework specialized for
> implementing ActivityPub servers. Therefore, it's designed to be used
> alongside other web frameworks. In this tutorial, we'll adopt [Hono] as
> our web framework to use with Fedify.

After a moment, you'll see files created in your working directory with
the following structure:

* *.vscode/* — Visual Studio Code related settings
  * *extensions.json* — Recommended extensions for Visual Studio Code
  * *settings.json* — Visual Studio Code settings
* *node\_modules/* — Directory where dependent packages are installed
  (contents omitted)
* *src/* — Source code
  * *app.tsx* — Server unrelated to ActivityPub
  * *federation.ts* — ActivityPub server
  * *index.ts* — Entry point
  * *logging.ts* — Logging configuration
* *biome.json* — Formatter and linter settings
* *package.json* — Package metadata
* *tsconfig.json* — TypeScript settings

As you might guess, we're using TypeScript instead of JavaScript,
which is why we have *.ts* and *.tsx* files instead of *.js* files.

The generated source code is a working demo. Let's first check if it runs
properly:

```sh
npm run dev
```

This command will keep the server running until you press
Ctrl+C:

```console
Server started at http://0.0.0.0:8000
```

With the server running, open a new terminal tab and run the following command:

```sh
fedify lookup http://localhost:8000/users/john
```

This command queries an actor (actor) on the ActivityPub server we've set up
locally. In ActivityPub, an actor can be thought of as an account that's
accessible across various ActivityPub servers.

If you see output like this, it's working correctly:

```console
✔ Looking up the object...
Person {
  id: URL "http://localhost:8000/users/john",
  name: "john",
  preferredUsername: "john"
}
```

This result tells us that there's an actor object located at the */users/john*
path, it's of type `Person`, its ID is *http://localhost:8000/users/john*,
its name is *john*, and its username is also *john*.

> \[!TIP]
> [`fedify lookup`](../cli.md#fedify-lookup-looking-up-an-activitypub-object)
> is a command to query ActivityPub objects. This is equivalent
> to searching with the corresponding URI on Mastodon. (Of course, since your
> server is only accessible locally at the moment, searching on Mastodon won't
> yield any results yet.)
>
> If you prefer `curl` over the `fedify lookup` command, you can also query
> the actor with this command (note that we're sending the Accept
> header with the `-H` option):
>
> ```sh
> curl -H"Accept: application/activity+json" http://localhost:8000/users/john
> ```
>
> However, if you query like this, the result will be in JSON format,
> which is difficult to read with the naked eye. If you also have the `jq`
> command installed on your system, you can use `curl` and `jq` together:
>
> ```sh
> curl -H"Accept: application/activity+json" http://localhost:8000/users/john | jq .
> ```

[Hono]: https://hono.dev/

### Visual Studio Code

[Visual Studio Code] might not be your favorite editor. However, we recommend
using Visual Studio Code while following this tutorial. This is because we need
to use TypeScript, and Visual Studio Code is currently the most convenient and
excellent TypeScript IDE. Also, the generated project setup already includes
Visual Studio Code settings, so you don't have to wrestle with formatters or
linters.

> \[!WARNING]
> Don't confuse this with Visual Studio. Visual Studio Code and Visual Studio
> only share a brand name; they are completely different software.

After [installing Visual Studio Code], open the working directory by selecting
*File* → *Open Folder…* from the menu.

If you see a popup in the bottom right asking Do you want to install
the recommended ‘Biome’ extension from biomejs for this repository?,
click the *Install* button to install the extension. Installing this extension
will automatically format your TypeScript code, so you don't have to wrestle
with code styles like indentation or spacing when writing TypeScript code.

> \[!TIP]
> If you're a loyal Emacs or Vim user, we won't discourage you from using your
> favorite editor. However, we recommend setting up TypeScript LSP.
> The difference in productivity depending on whether TypeScript LSP is set up
> or not is significant.

\*\[LSP]: Language Server Protocol

[Visual Studio Code]: https://code.visualstudio.com/

[installing Visual Studio Code]: https://code.visualstudio.com/docs/setup/setup-overview

## Prerequisites

### TypeScript

Before we start modifying code, let's briefly go over TypeScript.
If you're already familiar with TypeScript, you can skip this section.

TypeScript adds static type checking to JavaScript. The TypeScript syntax is
almost the same as JavaScript, but the main difference is that you can specify
types for variables and functions. Types are specified by adding a colon (`:`)
after the variable or parameter.

For example, the following code indicates that the `foo` variable is a `string`:

```typescript twoslash
let foo: string;
```

If you try to assign a value of a different type to a variable declared like
this, Visual Studio Code will show a red underline *before you even run it* and
display a type error:

```typescript twoslash
// @errors: 2322
let foo: string;
// ---cut-before---
foo = 123;
```

When coding, don't ignore red underlines. If you ignore them and run
the program, it's likely that an error will actually occur at that part.

The most common type of error you'll encounter when coding in TypeScript is
the `null` possibility error. For example, in the following code, the `bar`
variable can be either a `string` or `null` (`string | null`):

```typescript twoslash
function someFunction(): string | null { return ""; }
// ---cut-before---
const bar: string | null = someFunction();
```

What happens if you try to get the first character of this variable's content
like this?

```typescript twoslash
// @errors: 18047
function someFunction(): string | null { return ""; }
const bar: string | null = someFunction();
// ---cut-before---
const firstChar = bar.charAt(0);
```

You'll get a type error like above. It's saying that `bar` might sometimes be
`null`, and in that case, calling `null.charAt(0)` would cause an error,
so you need to fix the code. In such cases, you need to add handling for
the `null` case like this:

```typescript twoslash
function someFunction(): string | null { return ""; }
const bar: string | null = someFunction();
// ---cut-before---
const firstChar = bar === null ? "" : bar.charAt(0);
```

In this way, TypeScript helps prevent bugs by making you think of cases you
might not have considered when coding.

Another incidental advantage of TypeScript is that it enables auto-completion.
For example, if you type `foo.`, a list of methods available for string objects
will appear, allowing you to choose from them. This allows for faster coding
without having to check documentation each time.

We hope you'll feel the charm of TypeScript as you follow this tutorial.
Above all, Fedify provides the best experience when used with TypeScript.

> \[!TIP]
> If you want to learn TypeScript properly and thoroughly, we recommend reading
> *[The TypeScript Handbook]*. It takes about 30 minutes to read it all.

[The TypeScript Handbook]: https://www.typescriptlang.org/docs/handbook/intro.html

### JSX

JSX is a syntax extension of JavaScript that allows you to insert XML or HTML
into JavaScript code. It can also be used in TypeScript, in which case it's
sometimes called TSX. In this tutorial, we'll write all HTML within JavaScript
code using JSX syntax. Those who are already familiar with JSX can skip this
section.

For example, the following code assigns an HTML tree with a `<div>` element
at the top to the `html` variable:

```tsx twoslash
const html = <div>
  <p id="greet">Hello, <strong>JSX</strong>!</p>
</div>;
```

You can also insert JavaScript expressions using curly braces (the following
code assumes, of course, that there's a `getName()` function):

```tsx twoslash
/**
 * A hypothetical function that returns a name.
 */
function getName(): string { return ""; }
// ---cut-before---
const html = <div title={"Hello, " + getName() + "!"}>
  <p id="greet">Hello, <strong>{getName()}</strong>!</p>
</div>;
```

One of the features of JSX is that you can define your own tags called
components. Components can be defined as ordinary JavaScript functions.
For example, the following code defines and uses a `<Container>` component
(component names typically follow PascalCase style):

```tsx twoslash
import type { Child, FC } from "hono/jsx";

function getName() {
  return "JSX";
}

interface ContainerProps {
  name: string;
  children: Child;
}

const Container: FC<ContainerProps> = (props) => {
  return <div title={"Hello, " + props.name + "!"}>{props.children}</div>;
};

const html = <Container name={getName()}>
  <p id="greet">Hello, <strong>{getName()}</strong>!</p>
</Container>;
```

In the above code, `FC` is provided by [Hono], the web framework we'll use,
and it helps define the type of the component. `FC` is a generic type,
and the types that go inside the angle brackets after `FC` are type arguments.
Here, we specify the props type as the type argument. Props refer to
the parameters passed to the component. In the above code, we declared and
used the `ContainerProps` interface as the props type for the `<Container>`
component.

> \[!TIP]
> Type arguments for generic types can be multiple, separated by commas.
> For example, `Foo<A, B>` applies type arguments `A` and `B` to the generic
> type `Foo`.
>
> There are also generic functions, which are written as
> `someFunction<A, B>(foo, bar)`.
>
> When there's only one type argument, the angle brackets enclosing the type
> argument may look like XML/HTML tags, but they have nothing to do with JSX
> functionality.
>
> `FC<ContainerProps>`
> :   Applies the type argument `ContainerProps` to the generic type `FC`.
>
> `<Container>`
> :   Opens a component tag named `<Container>`. Must be closed with
> `</Container>`.

Among the things passed as props, `children` is worth noting specifically. This
is because the child elements of the component are passed as the `children`
prop. As a result, in the above code, the `html` variable is assigned the HTML
tree
`<div title="Hello, JSX!"><p id="greet">Hello, <strong>JSX</strong>!</p></div>`.

> \[!TIP]
> JSX was invented in the React project and started to be widely used.
> If you want to know more about JSX, read the *[Writing Markup with JSX]* and
> *[JavaScript in JSX with Curly Braces]* sections of the React documentation.

[Writing Markup with JSX]: https://react.dev/learn/writing-markup-with-jsx

[JavaScript in JSX with Curly Braces]: https://react.dev/learn/javascript-in-jsx-with-curly-braces

## Account creation page

The first thing we'll create is the account creation page. We need to create
an account before we can post or follow other accounts. Let's start by building
the visible part.

First, let's create a file named *src/views.tsx*. Inside this file, we'll define
a `<Layout>` component using JSX:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";

export const Layout: FC = (props) => (
  <html lang="en">
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="color-scheme" content="light dark" />
      <title>Microblog</title>
      <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css"
      />
    </head>
    <body>
      <main class="container">{props.children}</main>
    </body>
  </html>
);
```

To avoid spending too much time on design, we'll use a CSS framework called
[Pico CSS].

> \[!TIP]
> When the type of a variable or parameter can be inferred by TypeScript's type
> checker, like `props` above, it's fine to omit the type annotation. Even when
> the type annotation is omitted in such cases, you can check the type of
> a variable by hovering your mouse cursor over the variable name in
> Visual Studio Code.

Next, in the same file, let's define a `<SetupForm>` component that will go
inside the layout:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
// ---cut-before---
export const SetupForm: FC = () => (
  <>
    <h1>Set up your microblog</h1>
    <form method="post" action="/setup">
      <fieldset>
        <label>
          Username{" "}
          <input
            type="text"
            name="username"
            required
            maxlength={50}
            pattern="^[a-z0-9_\-]+$"
          />
        </label>
      </fieldset>
      <input type="submit" value="Setup" />
    </form>
  </>
);
```

In JSX, you can only have one top-level element, but the `<SetupForm>` component
has two top-level elements: `<h1>` and `<form>`. That's why we've wrapped them
with `<>` and `</>`. This is called a fragment.

Now it's time to use the components we've defined. Open the *src/app.tsx* file
and `import` the two components we just defined:

```tsx twoslash [src/app.tsx]
// @noErrors: 2395 2307
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const SetupForm: FC = () => <></>;
// ---cut-before---
import { Layout, SetupForm } from "./views.tsx";
```

Then, display the account creation form we just made on the */setup* page:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const SetupForm: FC = () => <></>;
// ---cut-before---
app.get("/setup", (c) =>
  c.html(
    <Layout>
      <SetupForm />
    </Layout>,
  ),
);
```

Now, let's open the <http://localhost:8000/setup> page in a web browser.
If you see a screen like this, it's working correctly:

![Account creation page](/assets/account-creation-page.Zbk-Rx66.png)

> \[!NOTE]
> To use JSX, the source file extension must be *.jsx* or *.tsx*.
> Note that both files we edited in this section have the *.tsx* extension.

[Pico CSS]: https://picocss.com/

### Database setup

Now that we've implemented the visible part, it's time to implement
the functionality. We need a place to store account information, so let's use
[SQLite]. SQLite is a relational database suitable for small-scale applications.

First, let's declare a table to hold account information. From now on, we'll
write all table declarations in the *src/schema.sql* file. We'll store account
information in the `users` table:

```sql [src/schema.sql]
CREATE TABLE IF NOT EXISTS users (
  id       INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
  username TEXT    NOT NULL UNIQUE      CHECK (trim(lower(username)) = username
                                               AND username <> ''
                                               AND length(username) <= 50)
);
```

Since the microblog we're creating can only have one account, we've put
a constraint on the `id` column, which is the primary key, to not allow values
other than `1`. This ensures that the `users` table can't contain more than one
record. We've also put constraints on the `username` column to not allow empty
strings or strings that are too long.

Now we need to run the *src/schema.sql* file to create the users table.
For this, we need the `sqlite3` command, which you can
[get from the SQLite website] or install from your platform's package manager.
For macOS, you don't need to get it separately as it is built into the system.
If you get it directly, you can get the *sqlite-tools-\*.zip* file for your
OS and unzip it. If you use a package manager, you can also install it with
the following command:

::: code-group

```sh [Debian & Ubuntu]
sudo apt install sqlite3
```

```sh [Fedora & RHEL]
sudo dnf install sqlite
```

```powershell [Chocolatey]
choco install sqlite
```

```powershell [Scoop]
scoop install sqlite
```

```powershell [Windows Package Manager]
winget install SQLite.SQLite
```

:::

Okay, now that we have the `sqlite3` command, let's use it to create
a database file:

```sh
sqlite3 microblog.sqlite3 < src/schema.sql
```

The above command will create a *microblog.sqlite3* file, which will store your
SQLite data.

[SQLite]: https://www.sqlite.org/

[get from the SQLite website]: https://www.sqlite.org/download.html

### Connecting to the database in the app

Now we need to use the SQLite database in our app. To use SQLite database in
Node.js, we need a SQLite driver library, and we'll use the *[better-sqlite3]*
package. You can easily install the package with the `npm` command:

```sh
npm add better-sqlite3
npm add --save-dev @types/better-sqlite3
```

> \[!TIP]
> The *[@types/better-sqlite3]* package contains type information about
> the *better-sqlite3* package's API for TypeScript. You need to install this
> package to enable auto-completion and type checking when editing in Visual
> Studio Code.
>
> Packages like this in the *@types/* scope are called [Definitely Typed]
> packages. When a library is not written in TypeScript, the community adds
> type information and makes it into a package.

Now that we've installed the package, let's write code to connect to
the database using this package. Create a new file named *src/db.ts* and code
it as follows:

```typescript twoslash [src/db.ts]
import Database from "better-sqlite3";

const db = new Database("microblog.sqlite3");
db.pragma("journal_mode = WAL");
db.pragma("foreign_keys = ON");

export default db;
```

> \[!TIP]
> The settings made through the `db.pragma()` function have the following
> effects:
>
> [`journal_mode = WAL`]
> :   Adopts [Write-Ahead Logging] mode as a way to implement atomic commits and
> rollbacks in SQLite. This mode is generally more performant than
> the default [rollback journal] mode.
>
> [`foreign_keys = ON`]
> :   By default, SQLite does not check foreign key constraints. Turning on this
> setting makes it check foreign key constraints, which helps maintain data
> integrity.

Now let's declare a type in JavaScript to represent the record stored in
the `users` table. Create a *src/schema.ts* file and define the `User` type
as follows:

```typescript twoslash [src/schema.ts]
export interface User {
  id: number;
  username: string;
}
```

[better-sqlite3]: https://github.com/WiseLibs/better-sqlite3

[@types/better-sqlite3]: https://www.npmjs.com/package/@types/better-sqlite3

[Definitely Typed]: https://github.com/DefinitelyTyped/DefinitelyTyped

[`journal_mode = WAL`]: https://www.sqlite.org/wal.html

[Write-Ahead Logging]: https://en.wikipedia.org/wiki/Write-ahead_logging

[rollback journal]: https://www.sqlite.org/lockingv3.html#rollback

[`foreign_keys = ON`]: https://www.sqlite.org/foreignkeys.html#fk_enable

### Record insertion

Now that we've connected to the database, it's time to write code to insert
records.

Open the *src/app.tsx* file and `import` the `db` object and `User` type that
will be used for record insertion:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import Database from "better-sqlite3";
const db = new Database("");
interface User {}
// ---cut-before---
import db from "./db.ts";
import type { User } from "./schema.ts";
```

Implement the `POST /setup` handler:

```typescript twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User {}
// ---cut-before---
app.post("/setup", async (c) => {
  // Check if an account already exists
  const user = db.prepare<unknown[], User>("SELECT * FROM users LIMIT 1").get();
  if (user != null) return c.redirect("/");

  const form = await c.req.formData();
  const username = form.get("username");
  if (typeof username !== "string" || !username.match(/^[a-z0-9_-]{1,50}$/)) {
    return c.redirect("/setup");
  }
  db.prepare("INSERT INTO users (username) VALUES (?)").run(username);
  return c.redirect("/");
});
```

Add code to check if an account already exists to the `GET /setup` handler
we created earlier:

```tsx{2-4} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const SetupForm: FC = () => <></>;
import Database from "better-sqlite3";
const db = new Database("");
interface User {}
// ---cut-before---
app.get("/setup", (c) => {
  // Check if an account already exists
  const user = db.prepare<unknown[], User>("SELECT * FROM users LIMIT 1").get();
  if (user != null) return c.redirect("/");

  return c.html(
    <Layout>
      <SetupForm />
    </Layout>,
  );
});
```

### Testing

Now that we've roughly implemented the account creation feature, let's try it
out. Open the <http://localhost:8000/setup> page in a web browser and create
an account. In this tutorial, we'll assume that we used *johndoe* as
the username. If it's created, let's also check if the record was properly
inserted into the SQLite database:

```sh
echo "SELECT * FROM users;" | sqlite3 -table microblog.sqlite3
```

If the record was properly inserted, you should see output like this (of course,
`johndoe` will be whatever username you entered):

| `id` | `username` |
| ---- | ---------- |
| `1`  | `johndoe`  |

## Profile page

Now that we've created an account, let's implement a profile page to display
the account information. Although we don't have much information to show yet.

Let's start with the visible part again. Open the *src/views.tsx* file and
define a `<Profile>` component:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
// ---cut-before---
export interface ProfileProps {
  name: string;
  handle: string;
}

export const Profile: FC<ProfileProps> = ({ name, handle }) => (
  <>
    <hgroup>
      <h1>{name}</h1>
      <p style="user-select: all;">{handle}</p>
    </hgroup>
  </>
);
```

Then, open the *src/app.tsx* file and `import` the component we just defined:

```tsx twoslash [src/app.tsx]
// @noErrors: 2395 2307
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const Profile: FC = () => <></>;
export const SetupForm: FC = () => <></>;
// ---cut-before---
import { Layout, Profile, SetupForm } from "./views.tsx";
```

And add a `GET /users/{username}` request handler that displays the `<Profile>`
component:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const Profile: FC = () => <></>;
import Database from "better-sqlite3";
const db = new Database("");
interface User {
  username: string;
}
// ---cut-before---
app.get("/users/:username", async (c) => {
  const user = db
    .prepare<unknown[], User>("SELECT * FROM users WHERE username = ?")
    .get(c.req.param("username"));
  if (user == null) return c.notFound();

  const url = new URL(c.req.url);
  const handle = `@${user.username}@${url.host}`;
  return c.html(
    <Layout>
      <Profile name={user.username} handle={handle} />
    </Layout>,
  );
});
```

Now let's test if it displays correctly.
Open the <http://localhost:8000/users/johndoe> page in your web browser
(if you created an account with a username other than `johndoe`,
change the URL accordingly). You should see a screen like this:

![Profile page](/assets/profile-page.BQHXdBsx.png)

> \[!TIP]
> A fediverse handle, or simply handle, is a unique address that identifies
> an account in the fediverse. For example, it looks like
> `@hongminhee@fosstodon.org`. It's similar to an email address,
> and its structure is also similar to an email address. It starts with `@`,
> followed by a name, then another `@`, and finally the domain name of
> the server the account belongs to. Sometimes the initial `@` is omitted.
>
> Technically, handles are implemented using two standards: [WebFinger] and
> the [`acct:` URI scheme]. Thanks to Fedify implementing these, you don't need
> to know the implementation details while following this tutorial.

[WebFinger]: https://datatracker.ietf.org/doc/html/rfc7033

[`acct:` URI scheme]: https://datatracker.ietf.org/doc/html/rfc7565

## Implementing the actor

As the name suggests, ActivityPub is a protocol for exchanging activities.
Writing a post, editing a post, deleting a post, liking a post, commenting,
editing a profile… All actions that happen in social media are expressed as
activities.

And all activities are transmitted from actor to actor. For example, when John
Doe writes a post, a writing (`Create(Note)`) activity is sent from Joh
Doe to John Doe's followers. If Jane Doe likes that post, a liking
(`Like`) activity is sent from Jane Doe to John Doe.

Therefore, the first step in implementing ActivityPub is to implement the actor.

The demo app generated by the `fedify init` command already has a very simple
actor implemented, but to communicate with actual software like Mastodon or
Misskey, we need to implement the actor more properly.

First, let's take a look at the current implementation.
Open the *src/federation.ts* file:

```typescript{12-18} twoslash [src/federation.ts]
import { createFederation, InProcessMessageQueue, MemoryKvStore } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
import { getLogger } from "@logtape/logtape";

const logger = getLogger("microblog");

const federation = createFederation({
  kv: new MemoryKvStore(),
  queue: new InProcessMessageQueue(),
});

federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    preferredUsername: identifier,
    name: identifier,
  });
});

export default federation;
```

The part we should focus on is the `~Federatable.setActorDispatcher()` method.
This method defines the URL and behavior that other ActivityPub software will
use when querying an actor on our server. For example, if we query
*/users/johndoe* as we did earlier, the `identifier` parameter of the callback
function will receive the string value `"johndoe"`. And the callback function
returns an instance of the `Person` class to convey the information of
the queried actor.

The `ctx` parameter receives a `Context` object, which contains various
functions related to the ActivityPub protocol. For example,
the `~Context.getActorUri()` method used in the above code returns the unique
URI of the actor with the `identifier` passed as a parameter. This URI is
being used as the unique identifier of the `Person` object.

As you can see from the implementation code, currently it's *making up* actor
information and returning it for any identifier that comes after the */users/*
path.  But what we want is to only allow queries for accounts that are actually
registered. Let's modify this part to only return for accounts in the database.

### Table creation

We need to create an `actors` table. Unlike the `users` table which only
contains accounts on the current instance server, this table will also include
remote actors belonging to federated servers. The table looks like this.
Add the following SQL to the *src/schema.sql* file:

```sql [src/schema.sql]
CREATE TABLE IF NOT EXISTS actors (
  id               INTEGER NOT NULL PRIMARY KEY,
  user_id          INTEGER          REFERENCES users (id),
  uri              TEXT    NOT NULL UNIQUE CHECK (uri <> ''),
  handle           TEXT    NOT NULL UNIQUE CHECK (handle <> ''),
  name             TEXT,
  inbox_url        TEXT    NOT NULL UNIQUE CHECK (inbox_url LIKE 'https://%'
                                                  OR inbox_url LIKE 'http://%'),
  shared_inbox_url TEXT                    CHECK (shared_inbox_url
                                                  LIKE 'https://%'
                                                  OR shared_inbox_url
                                                  LIKE 'http://%'),
  url              TEXT                    CHECK (url LIKE 'https://%'
                                                  OR url LIKE 'http://%'),
  created          TEXT    NOT NULL DEFAULT (CURRENT_TIMESTAMP)
                                           CHECK (created <> '')
);
```

* The `user_id` column is a foreign key to connect with the `users` column.
  If the record represents a remote actor, it will be `NULL`, but if it's
  an account on the current instance server, it will contain the `users.id`
  value of that account.

* The `uri` column contains the unique URI of the actor, also called the actor
  ID. All ActivityPub objects, including actors, have a unique ID in URI form.
  Therefore, it cannot be empty and cannot be duplicated.

* The `handle` column contains the fediverse handle in the form of
  `@johndoe@example.com`. Likewise, it cannot be empty and cannot be
  duplicated.

* The `name` column contains the name displayed in the UI. It usually contains
  a full name or nickname. However, according to the ActivityPub
  specification, this column can be empty.

* The `inbox_url` column contains the URL of the actor's inbox.
  We'll explain in detail what an inbox is below, but for now, just know that
  it must exist for the actor. This column also cannot be empty or duplicated.

* The `shared_inbox_url` column contains the URL of the actor's shared inbox,
  which we'll also explain below. It's not mandatory, so it can be empty,
  and as the column name suggests, it can share the same shared inbox URL with
  other actors.

* The `url` column contains the profile URL of the actor. A profile URL means
  the URL of the profile page that can be opened in a web browser.
  Sometimes the actor's ID and profile URL are the same, but they can be
  different depending on the service, so in that case, the profile URL is
  stored in this column. It can be empty.

* The `created` column records when the record was created.
  It cannot be empty, and by default, the insertion time is recorded.

Now, let's apply the *src/schema.sql* file to the *microblog.sqlite3* database
file:

```sh
sqlite3 microblog.sqlite3 < src/schema.sql
```

And let's define a type in *src/schema.ts* to represent records stored in
the `actors` table in JavaScript:

```typescript twoslash [src/schema.ts]
export interface Actor {
  id: number;
  user_id: number | null;
  uri: string;
  handle: string;
  name: string | null;
  inbox_url: string;
  shared_inbox_url: string | null;
  url: string | null;
  created: string;
}
```

### Actor record

Although we currently have one record in the `users` table, there's no
corresponding record in the `actors` table. This is because we didn't add
a record to the `actors` table when creating the account. We need to modify
the account creation code to add records to both `users` and `actors`.

First, let's modify the `SetupForm` in *src/views.tsx* to also input a name
that will go into the `actors.name` column along with the username:

```tsx{16-18} twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
// ---cut-before---
export const SetupForm: FC = () => (
  <>
    <h1>Set up your microblog</h1>
    <form method="post" action="/setup">
      <fieldset>
        <label>
          Username{" "}
          <input
            type="text"
            name="username"
            required
            maxlength={50}
            pattern="^[a-z0-9_\-]+$"
          />
        </label>
        <label>
          Name <input type="text" name="name" required />
        </label>
      </fieldset>
      <input type="submit" value="Setup" />
    </form>
  </>
);
```

Now `import` the Actor type we defined earlier in *src/app.tsx*:

```typescript [src/app.tsx]
import type { Actor, User } from "./schema.ts";
```

Now let's add code to the `POST /setup` handler to create a record in
the `actors` table with the input name and other necessary information:

```typescript{7,19-24,26,30-44} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User {}
import type { Federation } from "@fedify/fedify";
const fedi = null as unknown as Federation<void>;
// ---cut-before---
app.post("/setup", async (c) => {
  // Check if an account already exists
  const user = db
    .prepare<unknown[], User>(
      `
      SELECT * FROM users
      JOIN actors ON (users.id = actors.user_id)
      LIMIT 1
      `,
    )
    .get();
  if (user != null) return c.redirect("/");

  const form = await c.req.formData();
  const username = form.get("username");
  if (typeof username !== "string" || !username.match(/^[a-z0-9_-]{1,50}$/)) {
    return c.redirect("/setup");
  }
  const name = form.get("name");
  if (typeof name !== "string" || name.trim() === "") {
    return c.redirect("/setup");
  }
  const url = new URL(c.req.url);
  const handle = `@${username}@${url.host}`;
  const ctx = fedi.createContext(c.req.raw, undefined);
  db.transaction(() => {
    db.prepare("INSERT OR REPLACE INTO users (id, username) VALUES (1, ?)").run(
      username,
    );
    db.prepare(
      `
      INSERT OR REPLACE INTO actors
        (user_id, uri, handle, name, inbox_url, shared_inbox_url, url)
      VALUES (1, ?, ?, ?, ?, ?, ?)
    `,
    ).run(
      ctx.getActorUri(username).href,
      handle,
      name,
      ctx.getInboxUri(username).href,
      ctx.getInboxUri().href,
      ctx.getActorUri(username).href,
    );
  })();
  return c.redirect("/");
});
```

When checking if an account already exists, we modified it to determine that
there's no account yet not only when there's no record in the `users` table,
but also when there's no matching record in the `actors` table. Apply the same
condition to the `GET /setup` handler and the `GET /users/{username}` handler:

```tsx{7} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User {}
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const SetupForm: FC = () => <></>;
// ---cut-before---
app.get("/setup", (c) => {
  // Check if the user already exists
  const user = db
    .prepare<unknown[], User>(
      `
      SELECT * FROM users
      JOIN actors ON (users.id = actors.user_id)
      LIMIT 1
      `,
    )
    .get();
  if (user != null) return c.redirect("/");

  return c.html(
    <Layout>
      <SetupForm />
    </Layout>,
  );
});
```

```tsx{6} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { name: string; }
interface User { username: string; }
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const Profile: FC = () => <></>;
// ---cut-before---
app.get("/users/:username", async (c) => {
  const user = db
    .prepare<unknown[], User & Actor>(
      `
      SELECT * FROM users
      JOIN actors ON (users.id = actors.user_id)
      WHERE username = ?
      `,
    )
    .get(c.req.param("username"));
  if (user == null) return c.notFound();

  const url = new URL(c.req.url);
  const handle = `@${user.username}@${url.host}`;
  return c.html(
    <Layout>
      <Profile name={user.name ?? user.username} handle={handle} />
    </Layout>,
  );
});
```

> \[!TIP]
> In TypeScript, `A & B` means an object that is both type `A` and type `B`.
> For example, given the type `{ a: number } & { b: string }`, `{ a: 123 }` or
> `{ b: "foo" }` do not satisfy this type, but `{ a: 123, b: "foo" }` does
> satisfy this type.

Finally, open the *src/federation.ts* file and add the following code below
the actor dispatcher:

```typescript twoslash [src/federation.ts]
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setInboxListeners("/users/{identifier}/inbox", "/inbox");
```

Don't worry about the `~Federatable.setInboxListeners()` method for now.
We'll cover this when we explain about the inbox. Just note that
the `~Context.getInboxUri()` method used in the account creation code needs
the above code to work properly.

If you've modified all the code, open the <http://localhost:8000/setup> page
in your browser and create an account again:

![Account creation page](/assets/account-creation-page-2.BAKG9NMu.png)

### Actor dispatcher

Now that we've created the `actors` table and filled in a record, let's modify
*src/federation.ts* again. First, `import` the `db` object, and `Endpoints` and
Actor types:

```typescript twoslash [src/federation.ts]
// @noErrors: 2307
import { createFederation } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";
import db from "./db.ts";
import type { Actor, User } from "./schema.ts";
```

Now that we've `import`ed what we need, let's modify
the `~Federatable.setActorDispatcher()` method:

```typescript{2-11,16-21} twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";
import Database from "better-sqlite3";
const db = new Database("");
interface User {}
interface Actor { name: string; }
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  const user = db
    .prepare<unknown[], User & Actor>(
      `
      SELECT * FROM users
      JOIN actors ON (users.id = actors.user_id)
      WHERE users.username = ?
      `,
    )
    .get(identifier);
  if (user == null) return null;

  return new Person({
    id: ctx.getActorUri(identifier),
    preferredUsername: identifier,
    name: user.name,
    inbox: ctx.getInboxUri(identifier),
    endpoints: new Endpoints({
      sharedInbox: ctx.getInboxUri(),
    }),
    url: ctx.getActorUri(identifier),
  });
});
```

In the changed code, we now query the `users` table in the database and return
`null` if it's not an account on the current server. In other words, it will
respond with a proper `Person` object with `200 OK` for a `GET /users/johndoe`
request (assuming the account was created with the username `johndoe`),
and respond with `404 Not Found` for other requests.

Let's look at how the part creating the `Person` object has changed.
First, a `name` property has been added. This property uses the value from
the `actors.name` column. We'll cover the `inbox` and `endpoints` properties
when we explain about the inbox. The `url` property contains the profile URL
of this account, and in this tutorial, we'll make the actor ID and the actor's
profile URL match.

> \[!TIP]
> Sharp-eyed readers may have noticed that we're defining overlapping handlers
> for `GET /users/{identifier}` on both Hono and Fedify sides. So what happens
> when an actual request is sent to this path? The answer is that it depends on
> the Accept header of the request. If a request is sent with
> the `Accept: text/html` header, the request handler on the Hono side responds.
> If a request is sent with the `Accept: application/activity+json` header,
> the request handler on the Fedify side responds.
>
> This way of giving different responses according to the Accept
> header of the request is called HTTP [content negotiation], and Fedify itself
> implements content negotiation. More specifically, all requests go through
> Fedify once, and if it's not an ActivityPub-related request, it's passed on to
> the integrated framework, which in this tutorial is Hono.

> \[!TIP]
> In Fedify, all URIs and URLs are represented as [`URL`] instances.

[content negotiation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation

[`URL`]: https://developer.mozilla.org/

### Testing

Now, let's test if the actor dispatcher is working well.

With the server running, open a new terminal tab and enter the following
command:

```sh
fedify lookup http://localhost:8000/users/alice
```

Since there's no account named `alice`, you'll get an error like this,
unlike before:

```console
✔ Looking up the object...
Failed to fetch the object.
It may be a private object.  Try with -a/--authorized-fetch.
```

Now let's look up the `johndoe` account:

```sh
fedify lookup http://localhost:8000/users/johndoe
```

Now you get a good result:

```console
✔ Looking up the object...
Person {
  id: URL "http://localhost:8000/users/johndoe",
  name: "John Doe",
  url: URL "http://localhost:8000/users/johndoe",
  preferredUsername: "johndoe",
  inbox: URL "http://localhost:8000/users/johndoe/inbox",
  endpoints: Endpoints { sharedInbox: URL "http://localhost:8000/inbox" }
}
```

## Cryptographic key pairs

The next thing we'll implement is the actor's cryptographic keys for signing.
In ActivityPub, when an actor creates and sends an activity, it uses
a [digital signature] to prove that the activity was really created by that
actor. For this, each actor creates and holds their own matching private key
(secret key) and public key pair, and makes the public key visible to other
actors. When actors receive an activity, they compare the sender's public key
with the activity's signature to verify that the activity was indeed created
by the sender. Fedify handles the signing and signature verification
automatically, but you need to implement the generation and preservation of
the key pairs yourself.

> \[!WARNING]
> As the name suggests, the private key (secret key) should not be accessible
> to anyone other than the signing subject. On the other hand, the public key's
> purpose is to be public, so it's fine for anyone to access it.

[digital signature]: https://en.wikipedia.org/wiki/Digital_signature

### Table creation

Let's define a `keys` table in *src/schema.sql* to store the private and public
key pairs:

```sql [src/schema.sql]
CREATE TABLE IF NOT EXISTS keys (
  user_id     INTEGER NOT NULL REFERENCES users (id),
  type        TEXT    NOT NULL CHECK (type IN ('RSASSA-PKCS1-v1_5', 'Ed25519')),
  private_key TEXT    NOT NULL CHECK (private_key <> ''),
  public_key  TEXT    NOT NULL CHECK (public_key <> ''),
  created     TEXT    NOT NULL DEFAULT (CURRENT_TIMESTAMP) CHECK (created <> ''),
  PRIMARY KEY (user_id, type)
);
```

If you look closely at the table, you can see that the `type` column only allows
two types of values. One is the [RSA-PKCS#1-v1.5] type and the other is
the [Ed25519] type. (What each of these means is not important for this
tutorial.) Since the primary key is on `(user_id, type)`, there can be a maximum
of two key pairs for one user.

> \[!TIP]
> We can't go into detail in this tutorial, but as of November 2024,
> the ActivityPub network is in the process of transitioning from
> the RSA-PKCS#1-v1.5 type to the Ed25519 type. Some software only
> accepts the RSA-PKCS#1-v1.5 type, while some software accepts
> the Ed25519 type. Therefore, to communicate with both sides,
> both pairs of keys are needed.

The `private_key` and `public_key` columns can receive strings,
and we'll put JSON data in them. We'll cover how to encode private
and public keys as JSON later.

Now let's create the `keys` table:

```sh
sqlite3 microblog.sqlite3 < src/schema.sql
```

Let's also define a `Key` type in the *src/schema.ts* file to represent records
stored in the `keys` table in JavaScript:

```typescript twoslash [src/schema.ts]
export interface Key {
  user_id: number;
  type: "RSASSA-PKCS1-v1_5" | "Ed25519";
  private_key: string;
  public_key: string;
  created: string;
}
```

[RSA-PKCS#1-v1.5]: https://www.rfc-editor.org/rfc/rfc2313

[Ed25519]: https://ed25519.cr.yp.to/

### Key pairs dispatcher

Now we need to write code to generate and load key pairs.

Open the *src/federation.ts* file and `import` the `exportJwk()`,
`generateCryptoKeyPair()`, `importJwk()` functions provided by Fedify and
the `Key` type we defined earlier:

```typescript{5-7,9} twoslash [src/federation.ts]
// @noErrors: 2307
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";
import type { Actor, Key, User } from "./schema.ts";
```

Now let's modify the actor dispatcher part as follows:

```typescript twoslash [src/federation.ts]
import {
  type Federation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import { type Logger } from "@logtape/logtape";
const logger = null as unknown as Logger;
import Database from "better-sqlite3";
const db = new Database("");
interface User { id: number; }
interface Actor { name: string; }
interface Key {
  type: "RSASSA-PKCS1-v1_5" | "Ed25519";
  private_key: string;
  public_key: string;
}
// ---cut-before---
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    const user = db
      .prepare<unknown[], User & Actor>(
        `
        SELECT * FROM users
        JOIN actors ON (users.id = actors.user_id)
        WHERE users.username = ?
        `,
      )
      .get(identifier);
    if (user == null) return null;

    const keys = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      name: user.name,
      inbox: ctx.getInboxUri(identifier),
      endpoints: new Endpoints({
        sharedInbox: ctx.getInboxUri(),
      }),
      url: ctx.getActorUri(identifier),
      publicKey: keys[0].cryptographicKey,
      assertionMethods: keys.map((k) => k.multikey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    const user = db
      .prepare<unknown[], User>("SELECT * FROM users WHERE username = ?")
      .get(identifier);
    if (user == null) return [];
    const rows = db
      .prepare<unknown[], Key>("SELECT * FROM keys WHERE keys.user_id = ?")
      .all(user.id);
    const keys = Object.fromEntries(
      rows.map((row) => [row.type, row]),
    ) as Record<Key["type"], Key>;
    const pairs: CryptoKeyPair[] = [];
    // For each of the two key formats (RSASSA-PKCS1-v1_5 and Ed25519) that
    // the actor supports, check if they have a key pair, and if not,
    // generate one and store it in the database:
    for (const keyType of ["RSASSA-PKCS1-v1_5", "Ed25519"] as const) {
      if (keys[keyType] == null) {
        logger.debug(
          "The user {identifier} does not have an {keyType} key; creating one...",
          { identifier, keyType },
        );
        const { privateKey, publicKey } = await generateCryptoKeyPair(keyType);
        db.prepare(
          `
          INSERT INTO keys (user_id, type, private_key, public_key)
          VALUES (?, ?, ?, ?)
          `,
        ).run(
          user.id,
          keyType,
          JSON.stringify(await exportJwk(privateKey)),
          JSON.stringify(await exportJwk(publicKey)),
        );
        pairs.push({ privateKey, publicKey });
      } else {
        pairs.push({
          privateKey: await importJwk(
            JSON.parse(keys[keyType].private_key),
            "private",
          ),
          publicKey: await importJwk(
            JSON.parse(keys[keyType].public_key),
            "public",
          ),
        });
      }
    }
    return pairs;
  });
```

First of all, we should pay attention to
the `~ActorCallbackSetters.setKeyPairsDispatcher()` method called in succession
after the `~Federatable.setActorDispatcher()` method. This method connects
the key pairs returned by the callback function to the account. By connecting
the key pairs in this way, Fedify automatically adds digital signatures with
the registered private keys when sending activities.

The `generateCryptoKeyPair()` function generates a new private key and public
key pair and returns it as a [`CryptoKeyPair`] object. For your reference,
the [`CryptoKeyPair`] type has the type
`{ privateKey: CryptoKey; publicKey: CryptoKey; }`.

The `exportJwk()` function returns an object representing the [`CryptoKey`]
object in JWK format. You don't need to know what the JWK format is.
Just understand that it's a standard format for representing cryptographic keys
in JSON. [`CryptoKey`] is a web standard type for representing cryptographic
keys as JavaScript objects.

The `importJwk()` function converts a key represented in JWK format to
a [`CryptoKey`] object. You can understand it as the opposite of
the `exportJwk()` function.

Now, let's turn our attention back to the `~Federatable.setActorDispatcher()`
method. We're using a method called `~Context.getActorKeyPairs()`, which,
as the name suggests, returns the key pairs of the actor. The actor's key pairs
are those very key pairs we just loaded with
the `~ActorCallbackSetters.setKeyPairsDispatcher()` method. We loaded two pairs
of keys in RSA-PKCS#1-v1.5 and Ed25519 formats,
so the `~Context.getActorKeyPairs()` method returns an array of two key pairs.
Each element of the array is an object representing the key pair in various
formats, which looks like this:

```typescript twoslash
import type { CryptographicKey, Multikey } from "@fedify/vocab";
// ---cut-before---
interface ActorKeyPair {
  privateKey: CryptoKey;              // Private key
  publicKey: CryptoKey;               // Public key
  keyId: URL;                         // Unique identification URI of the key
  cryptographicKey: CryptographicKey; // Another format of the public key
  multikey: Multikey;                 // Yet another format of the public key
}
```

It's complex to explain here how [`CryptoKey`], `CryptographicKey`,
and `Multikey` differ, and why there need to be so many formats. For now,
let's just note that when initializing the `Person` object, the `publicKey`
property accepts the `CryptographicKey` type and the `assertionMethods`
property accepts the `MultiKey[]` (TypeScript notation for an array of
`Multikey`) type.

By the way, why are there two properties in the `Person` object that hold public
keys, `publicKey` and `assertionMethods`? Originally in ActivityPub, there was
only the `publicKey` property, but later the `assertionMethods` property was
added to allow registration of multiple keys. Similar to how we generated both
RSA-PKCS#1-v1.5 and Ed25519 keys earlier, we're setting both properties
for compatibility with various software. If you look closely, you can see that
we're only registering the RSA-PKCS#1-v1.5 key to the legacy `publicKey`
property (the first item in the array is the RSA-PKCS#1-v1.5 key pair,
and the second item is the Ed25519 key pair).

> \[!TIP]
> Actually, the `publicKey` property can contain multiple keys too. However,
> many software are already implemented under the assumption that
> the `publicKey` property will only contain one key, so they often malfunction.
> The `assertionMethods` property was proposed to avoid this.
>
> For those interested in this, refer to the [FEP-521a] document.

[`CryptoKeyPair`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair

[`CryptoKey`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey

[FEP-521a]: https://w3id.org/fep/521a

### Testing

Now that we've registered the cryptographic keys to the actor object,
let's check if it's working well. Query the actor with the following command:

```sh
fedify lookup http://localhost:8000/users/johndoe
```

If it's working correctly, you should see output like this:

```console{7,14,22-23,30,38,44}
✔ Looking up the object...
Person {
  id: URL "http://localhost:8000/users/johndoe",
  name: "John Doe",
  url: URL "http://localhost:8000/users/johndoe",
  preferredUsername: "johndoe",
  publicKey: CryptographicKey {
    id: URL "http://localhost:8000/users/johndoe#main-key",
    owner: URL "http://localhost:8000/users/johndoe",
    publicKey: CryptoKey {
      type: "public",
      extractable: true,
      algorithm: {
        name: "RSASSA-PKCS1-v1_5",
        modulusLength: 4096,
        publicExponent: Uint8Array(3) [ 1, 0, 1 ],
        hash: { name: "SHA-256" }
      },
      usages: [ "verify" ]
    }
  },
  assertionMethods: [
    Multikey {
      id: URL "http://localhost:8000/users/johndoe#main-key",
      controller: URL "http://localhost:8000/users/johndoe",
      publicKey: CryptoKey {
        type: "public",
        extractable: true,
        algorithm: {
          name: "RSASSA-PKCS1-v1_5",
          modulusLength: 4096,
          publicExponent: Uint8Array(3) [ 1, 0, 1 ],
          hash: { name: "SHA-256" }
        },
        usages: [ "verify" ]
      }
    },
    Multikey {
      id: URL "http://localhost:8000/users/johndoe#key-2",
      controller: URL "http://localhost:8000/users/johndoe",
      publicKey: CryptoKey {
        type: "public",
        extractable: true,
        algorithm: { name: "Ed25519" },
        usages: [ "verify" ]
      }
    }
  ],
  inbox: URL "http://localhost:8000/users/johndoe/inbox",
  endpoints: Endpoints { sharedInbox: URL "http://localhost:8000/inbox" }
}
```

You can see that the `Person` object's `publicKey` property contains one
`CryptographicKey` object in RSA-PKCS#1-v1.5 type,
and the `assertionMethods` property contains two `Multikey` objects
in RSA-PKCS#1-v1.5 and Ed25519 formats.

## Interoperating with Mastodon

Now let's check if we can actually view the actor we've created in Mastodon.

### Exposing to the public internet

Unfortunately, the current server is only accessible locally. However, it would
be inconvenient to deploy somewhere every time we modify the code for testing.
Wouldn't it be great if we could expose our local server to the internet without
deployment for immediate testing?

Here's where the
[`fedify tunnel`](../cli.md#fedify-tunnel-exposing-a-local-http-server-to-the-public-internet)
command comes in handy. In a terminal, open a new tab and enter this command
followed by the port number of your local server:

```sh
fedify tunnel 8000
```

This creates a disposable domain name and relays to your local server.
It will output a URL that's accessible from the outside:

```console
✔ Your local server at 8000 is now publicly accessible:

https://temp-address.serveo.net/

Press ^C to close the tunnel.
```

Of course, you'll see your own unique URL different from the one above.
You can check if it's connecting well by opening
<https://temp-address.serveo.net/users/johndoe> in your web browser
(replace with your unique temporary domain):

![Profile page exposed to the public internet](/assets/profile-page-2.ixKV_Uc_.png)

Copy your fediverse handle shown on the above web page, then go into Mastodon
and paste it into the search box in the upper left corner:

![Search results for the fediverse handle in Mastodon](/assets/search-results.BvVtwbw0.png)

If the actor we created appears in the search results as shown above,
it's working correctly. You can also click on the actor's name in the search
results to go to their profile page:

![Actor's profile viewed in Mastodon](/assets/remote-profile.C4GEH3OF.png)

But this is as far as we can go. Don't try to follow yet! For our actor to be
followable from other servers, we need to implement an inbox.

> \[!NOTE]
> The `fedify tunnel` command automatically disconnects after a while if not
> used. When this happens, you need to press Ctrl+C to
> stop it, then run the `fedify tunnel 8000` command again to establish a new
> connection.

## Inbox

In ActivityPub, an inbox is an endpoint where an actor receives incoming
activities from other actors. All actors have their own inbox, which is
a URL that can receive activities via HTTP `POST` requests. When another actor
sends a follow request, writes a post, comments, or performs any other
interaction, the corresponding activity is delivered to the recipient's inbox.
The server processes the activities that come into the inbox and responds
appropriately, allowing it to communicate and function as part of the federated
network.

For now, we'll start by implementing the reception of follow requests.

### Table creation

We need to create a `follows` table to hold the actors who follow you
(followers) and the actors you follow (following). Add the following SQL to
the *src/schema.sql* file:

```sql [src/schema.sql]
CREATE TABLE IF NOT EXISTS follows (
  following_id INTEGER          REFERENCES actors (id),
  follower_id  INTEGER          REFERENCES actors (id),
  created      TEXT    NOT NULL DEFAULT (CURRENT_TIMESTAMP)
                                CHECK (created <> ''),
  PRIMARY KEY (following_id, follower_id)
);
```

Let's create the `follows` table by executing *src/schema.sql* once again:

```sh
sqlite3 microblog.sqlite3 < src/schema.sql
```

Open the *src/schema.ts* file and define a type to represent records stored
in the `follows` table in JavaScript:

```typescript twoslash [src/schema.ts]
export interface Follow {
  following_id: number;
  follower_id: number;
  created: string;
}
```

### Receiving `Follow` activity

Now it's time to implement the inbox. Actually, we've already written
the following code in the *src/federation.ts* file earlier:

```typescript twoslash [src/federation.ts]
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setInboxListeners("/users/{identifier}/inbox", "/inbox");
```

Before modifying this code, let's `import` the `Accept` and `Follow` classes
and the `getActorHandle()` function provided by Fedify:

```typescript{2,4,9} twoslash [src/federation.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Person,
  getActorHandle,
} from "@fedify/vocab";
```

Now let's modify the code calling the `~Federatable.setInboxListeners()` method
as follows:

```typescript twoslash [src/federation.ts]
import {
  type Federation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Person,
  getActorHandle,
} from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import type { Logger } from "@logtape/logtape";
const logger = null as unknown as Logger;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { id: number; }
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    if (follow.objectId == null) {
      logger.debug("The Follow object does not have an object: {follow}", {
        follow,
      });
      return;
    }
    const object = ctx.parseUri(follow.objectId);
    if (object == null || object.type !== "actor") {
      logger.debug("The Follow object's object is not an actor: {follow}", {
        follow,
      });
      return;
    }
    const follower = await follow.getActor();
    if (follower?.id == null || follower.inboxId == null) {
      logger.debug("The Follow object does not have an actor: {follow}", {
        follow,
      });
      return;
    }
    const followingId = db
      .prepare<unknown[], Actor>(
        `
        SELECT * FROM actors
        JOIN users ON users.id = actors.user_id
        WHERE users.username = ?
        `,
      )
      .get(object.identifier)?.id;
    if (followingId == null) {
      logger.debug(
        "Failed to find the actor to follow in the database: {object}",
        { object },
      );
    }
    const followerId = db
      .prepare<unknown[], Actor>(
        `
        -- Add a new follower actor record or update if it already exists
        INSERT INTO actors (uri, handle, name, inbox_url, shared_inbox_url, url)
        VALUES (?, ?, ?, ?, ?, ?)
        ON CONFLICT (uri) DO UPDATE SET
          handle = excluded.handle,
          name = excluded.name,
          inbox_url = excluded.inbox_url,
          shared_inbox_url = excluded.shared_inbox_url,
          url = excluded.url
        WHERE
          actors.uri = excluded.uri
        RETURNING *
        `,
      )
      .get(
        follower.id.href,
        await getActorHandle(follower),
        follower.name?.toString(),
        follower.inboxId.href,
        follower.endpoints?.sharedInbox?.href,
        follower.url?.href,
      )?.id;
    db.prepare(
      "INSERT INTO follows (following_id, follower_id) VALUES (?, ?)",
    ).run(followingId, followerId);
    const accept = new Accept({
      actor: follow.objectId,
      to: follow.actorId,
      object: follow,
    });
    await ctx.sendActivity(object, follower, accept);
  });
```

Let's examine the code carefully. The `~InboxListenerSetters.on()` method
defines the action to take when a specific type of activity is received.
Here, we've written code to record the follower information in the database
when a `Follow` activity is received, and then send an `Accept(Follow)`
activity back to the actor who sent the follow request.

The `follow.objectId` should contain the URI of the actor being followed.
We use the `~Context.parseUri()` method to check if the URI inside it points
to the actor we created.

The `getActorHandle()` function returns the fediverse handle as a string
from the given actor object.

If there's no information about the actor who sent the follow request in
the `actors` table yet, we first add a record. If a record already exists,
we update it with the latest data. Then, we add the follower to the `follows`
table.

Once the record is completed in the database, we use
the `~Context.sendActivity()` method to send an `Accept(Follow)` activity
as a reply to the actor who sent the activity. It takes the sender as the first
parameter, the recipient as the second parameter, and the activity object to
send as the third parameter.

### ActivityPub.Academy

Now it's time to check if follow requests are being received properly.

While it would be fine to test from a regular Mastodon server, let's use
the [ActivityPub.Academy] server, which allows us to see exactly how activities
are exchanged. ActivityPub.Academy is a special Mastodon server for education
and debugging purposes, where you can easily create temporary accounts with
just one click.

![ActivityPub.Academy homepage](/assets/academy.BEfymNOt.jpg)

After agreeing to the privacy policy, click the *Sign Up* button to create a new
account. The created account will have a randomly generated name and handle,
and will disappear on its own after a day. Instead, you can create new accounts
as many times as you want.

Once you're logged in, paste the handle of the actor we created into the search
box in the top left corner of the screen:

![Search results for our actor's handle on ActivityPub.Academy](/assets/academy-search-results.BRfKsJiB.png)

If our actor appears in the search results, click the follow button on the right
to send a follow request. Then click on *Activity Log* in the right menu:

![ActivityPub.Academy's Activity Log](/assets/activity-log.Dm59VnxS.png)

You'll see an indication that a `Follow` activity was sent from
the ActivityPub.Academy server to the inbox of the actor we created by clicking
the follow button just now. You can see the contents of the activity by clicking
*show source* in the bottom right:

![Activity Log screen after clicking show source](/assets/activity-log-2.Bsel8qEA.png)

[ActivityPub.Academy]: https://activitypub.academy/

### Testing

Now that we've confirmed that the activity was sent well, it's time to check if
our inbox code is working properly. First, let's see if a record was created
properly in the `follows` table:

```sh
echo "SELECT * FROM follows;" | sqlite3 -table microblog.sqlite3
```

If the follow request was processed successfully, you should see a result like
this (of course, the time will be different):

| `following_id` | `follower_id` | `created`             |
| -------------- | ------------- | --------------------- |
| `1`            | `2`           | `2024-09-01 10:19:41` |

Let's also check if a new record was created in the `actors` table:

```sh
echo "SELECT * FROM actors WHERE id > 1;" | sqlite3 -table microblog.sqlite3
```

| `id` | `user_id` | `uri`                                                  | `handle`                                  | `name`               | `inbox_url`                                                  | `shared_inbox_url`                  | `url`                                             | `created`             |
| ---- | --------- | ------------------------------------------------------ | ----------------------------------------- | -------------------- | ------------------------------------------------------------ | ----------------------------------- | ------------------------------------------------- | --------------------- |
| `2`  |           | `https://activitypub.academy/users/dobussia_dovornath` | `@dobussia_dovornath@activitypub.academy` | `Dobussia Dovornath` | `https://activitypub.academy/users/dobussia_dovornath/inbox` | `https://activitypub.academy/inbox` | `https://activitypub.academy/@dobussia_dovornath` | `2024-09-01 10:19:41` |

Now, let's look at ActivityPub.Academy's *Activity Log* again.
If the `Accept(Follow)` activity sent by our actor arrived well,
it should be displayed as follows:

![Accept(Follow) activity displayed in Activity Log](/assets/activity-log-3.CK83vz3Y.png)

This way, you've implemented your first interaction via ActivityPub!

## Unfollow

What happens if an actor from another server unfollows our actor after following
it? Let's test this in [ActivityPub.Academy]. As before, enter our actor's
fediverse handle in the ActivityPub.Academy search box:

![Search results in ActivityPub.Academy](/assets/academy-search-results-2.UVqR0fdO.png)

If you look closely, you'll see an unfollow button in place of the follow button
to the right of the actor name. Click this button to unfollow, then go to
the *Activity Log* to see what activity is sent:

![Activity Log showing the sent Undo(Follow) activity](/assets/activity-log-4.C2MQmf8S.png)

As you can see, an `Undo(Follow)` activity has been sent. If you click *show
source* in the bottom right, you can see the detailed contents of the activity:

```json
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://activitypub.academy/users/dobussia_dovornath#follows/3283/undo",
  "type": "Undo",
  "actor": "https://activitypub.academy/users/dobussia_dovornath",
  "object": {
    "id": "https://activitypub.academy/98b131b8-89ea-49ba-b2bd-3ee0f5a87694",
    "type": "Follow",
    "actor": "https://activitypub.academy/users/dobussia_dovornath",
    "object": "https://temp-address.serveo.net/users/johndoe"
  }
}
```

Looking at this JSON object, you can see that the `Undo(Follow)` activity
includes the `Follow` activity that was received by our inbox earlier. However,
since we haven't defined any behavior for when the inbox receives
an `Undo(Follow)` activity, nothing has happened.

### Receiving `Undo(Follow)` activity

To implement unfollow, open the *src/federation.ts* file and `import` the `Undo`
class provided by Fedify:

```typescript twoslash [src/federation.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Person,
  Undo,  // [!code highlight]
  getActorHandle,
} from "@fedify/vocab";
```

Then add `on(Undo, ...)` in succession after `on(Follow, ...)`:

```typescript{6-23} twoslash [src/federation.ts]
// @errors: 1160
import { type Federation } from "@fedify/fedify";
import { Follow, Undo } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import Database from "better-sqlite3";
const db = new Database("");
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    // ... omitted ...
  })
  .on(Undo, async (ctx, undo) => {
    const object = await undo.getObject();
    if (!(object instanceof Follow)) return;
    if (undo.actorId == null || object.objectId == null) return;
    const parsed = ctx.parseUri(object.objectId);
    if (parsed == null || parsed.type !== "actor") return;
    db.prepare(
      `
      DELETE FROM follows
      WHERE following_id = (
        SELECT actors.id
        FROM actors
        JOIN users ON actors.user_id = users.id
        WHERE users.username = ?
      ) AND follower_id = (SELECT id FROM actors WHERE uri = ?)
      `,
    ).run(parsed.identifier, undo.actorId.href);
  });
```

This time, the code is shorter than when processing follow requests.
It checks if the thing inside the `Undo(Follow)` activity is a `Follow`
activity, uses the `parseUri()` method to check if the follow target of
the `Follow` activity to be canceled is our actor, and then deletes
the corresponding record from the `follows` table.

### Testing

We can't unfollow once more since we already clicked the unfollow button in
[ActivityPub.Academy] earlier. We'll have to follow again and then unfollow to
test. But before that, we need to empty the `follows` table. Otherwise,
there will be an error when the follow request comes in because the record
already exists.

Let's empty the `follows` table using the `sqlite3` command:

```sh
echo "DELETE FROM follows;" | sqlite3 microblog.sqlite3
```

Now press the follow button again, then check the database:

```sh
echo "SELECT * FROM follows;" | sqlite3 -table microblog.sqlite3
```

If the follow request was processed successfully, you should see a result like
this:

| `following_id` | `follower_id` | `created`             |
| -------------- | ------------- | --------------------- |
| `1`            | `2`           | `2024-09-02 01:05:17` |

Now press the unfollow button again, then check the database one more time:

```sh
echo "SELECT count(*) FROM follows;" | sqlite3 -table microblog.sqlite3
```

If the unfollow request was processed successfully, the record should have
disappeared, so you should see a result like this:

| `count(*)` |
| ---------- |
| `0`        |

## Followers list

It's cumbersome to view the followers list using the `sqlite3` command every
time, so let's make it possible to view the followers list on the web.

Let's start by adding a new component to the *src/views.tsx* file.
First, `import` the Actor type:

```typescript twoslash [src/views.tsx]
// @noErrors: 2307
import type { Actor } from "./schema.ts";
```

Then define the `<FollowerList>` component and the `<ActorLink>` component:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface Actor {
  id: number;
  uri: string;
  name: string | null;
  handle: string;
  url: string | null;
}
// ---cut-before---
export interface FollowerListProps {
  followers: Actor[];
}

export const FollowerList: FC<FollowerListProps> = ({ followers }) => (
  <>
    <h2>Followers</h2>
    <ul>
      {followers.map((follower) => (
        <li key={follower.id}>
          <ActorLink actor={follower} />
        </li>
      ))}
    </ul>
  </>
);

export interface ActorLinkProps {
  actor: Actor;
}

export const ActorLink: FC<ActorLinkProps> = ({ actor }) => {
  const href = actor.url ?? actor.uri;
  return actor.name == null ? (
    <a href={href} class="secondary">
      {actor.handle}
    </a>
  ) : (
    <>
      <a href={href}>{actor.name}</a>{" "}
      <small>
        (
        <a href={href} class="secondary">
          {actor.handle}
        </a>
        )
      </small>
    </>
  );
};
```

The `<ActorLink>` component is used to represent a single actor,
and the `<FollowerList>` component uses the `<ActorLink>` component
to represent the list of followers. As you can see, since JSX doesn't
have conditional statements or loops, we're using the ternary operator
and the [`Array.map()`] method.

Now let's create an endpoint to display the followers list.
Open the *src/app.tsx* file and `import` the `<FollowerList>` component:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import { FollowerList, Layout, Profile, SetupForm } from "./views.tsx";
```

Then add a request handler for `GET /users/{username}/followers`:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const FollowerList: FC = () => <></>;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor {}
// ---cut-before---
app.get("/users/:username/followers", async (c) => {
  const followers = db
    .prepare<unknown[], Actor>(
      `
      SELECT followers.*
      FROM follows
      JOIN actors AS followers ON follows.follower_id = followers.id
      JOIN actors AS following ON follows.following_id = following.id
      JOIN users ON users.id = following.user_id
      WHERE users.username = ?
      ORDER BY follows.created DESC
      `,
    )
    .all(c.req.param("username"));
  return c.html(
    <Layout>
      <FollowerList followers={followers} />
    </Layout>,
  );
});
```

Now, shall we check if it's displaying correctly? There should be followers,
so with `fedify tunnel` running, follow our actor from another Mastodon server
or [ActivityPub.Academy]. After the follow request is accepted, open
the <http://localhost:8000/users/johndoe/followers> page in your web browser,
and you should see something like this:

![Followers list page](/assets/followers-list.CFBaVYQj.png)

Now that we've created the followers list, it would be nice to display
the number of followers on the profile page as well. Open the *src/views.tsx*
file again and modify the `<Profile>` component as follows:

```tsx{20-23} twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
// ---cut-before---
export interface ProfileProps {
  name: string;
  username: string;   // [!code highlight]
  handle: string;
  followers: number;  // [!code highlight]
}

export const Profile: FC<ProfileProps> = ({
  name,
  username,   // [!code highlight]
  handle,
  followers,  // [!code highlight]
}) => (
  <>
    <hgroup>
      <h1>
        <a href={`/users/${username}`}>{name}</a>
      </h1>
      <p>
        <span style="user-select: all;">{handle}</span> &middot;{" "}
        <a href={`/users/${username}/followers`}>
          {followers === 1 ? "1 follower" : `${followers} followers`}
        </a>
      </p>
    </hgroup>
  </>
);
```

Two props have been added to `ProfileProps`. `followers` is a prop that holds
the number of followers, as the name suggests. `username` receives
the username that will go into the URL to link to the followers list.

Now go back to the *src/app.tsx* file and modify the `GET /users/{username}`
request handler as follows:

```tsx{5-15,21,23} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  followers: number;
}
export const Profile: FC<ProfileProps> = () => <></>;
import Database from "better-sqlite3";
const db = new Database("");
interface User {
  id: number;
  username: string;
}
interface Actor { name: string; }
const user = {} as unknown as User & Actor;
const handle = "" as string;
// ---cut-before---
app.get("/users/:username", async (c) => {
  // ... omitted ...
  if (user == null) return c.notFound();

  // biome-ignore lint/style/noNonNullAssertion: Always returns a single record
  const { followers } = db
    .prepare<unknown[], { followers: number }>(
      `
      SELECT count(*) AS followers
      FROM follows
      JOIN actors ON follows.following_id = actors.id
      WHERE actors.user_id = ?
      `,
    )
    .get(user.id)!;
  // ... omitted ...
  return c.html(
    <Layout>
      <Profile
        name={user.name ?? user.username}
        username={user.username}
        handle={handle}
        followers={followers}
      />
    </Layout>,
  );
});
```

SQL that counts the number of records in the `follows` table in the database
has been added. Now, let's check the changed profile page. When you open
the <http://localhost:8000/users/johndoe> page in your web browser,
you should see something like this:

![Changed profile page](/assets/profile-page-3.Bz3NK0AA.png)

[`Array.map()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map

## Followers collection

However, there's one problem. Let's look up our actor from a Mastodon server
that is *not* ActivityPub.Academy. (You know how to look it up, right?
With the server exposed to the public internet, enter the actor's handle in
the Mastodon search box.) When you view our actor's profile in Mastodon,
you might notice something strange:

![Our actor's profile viewed in Mastodon](/assets/remote-profile-2.havFcOBx.png)

The number of followers is shown as 0. This is because our actor is not
exposing the followers list via ActivityPub. To expose the followers list in
ActivityPub, we need to define a followers collection.

Open the *src/federation.ts* file and `import` the `Recipient` type provided
by Fedify:

```typescript twoslash [src/federation.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Person,
  Undo,
  getActorHandle,
  type Recipient,  // [!code highlight]
} from "@fedify/vocab";
```

Then add a followers collection dispatcher at the bottom:

```typescript twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor {
  uri: string;
  inbox_url: string;
  shared_inbox_url: string | null;
}
// ---cut-before---
federation
  .setFollowersDispatcher(
    "/users/{identifier}/followers",
    (ctx, identifier, cursor) => {
      const followers = db
        .prepare<unknown[], Actor>(
          `
          SELECT followers.*
          FROM follows
          JOIN actors AS followers ON follows.follower_id = followers.id
          JOIN actors AS following ON follows.following_id = following.id
          JOIN users ON users.id = following.user_id
          WHERE users.username = ?
          ORDER BY follows.created DESC
          `,
        )
        .all(identifier);
      const items: Recipient[] = followers.map((f) => ({
        id: new URL(f.uri),
        inboxId: new URL(f.inbox_url),
        endpoints:
          f.shared_inbox_url == null
            ? null
            : { sharedInbox: new URL(f.shared_inbox_url) },
      }));
      return { items };
    },
  )
  .setCounter((ctx, identifier) => {
    const result = db
      .prepare<unknown[], { cnt: number }>(
        `
        SELECT count(*) AS cnt
        FROM follows
        JOIN actors ON actors.id = follows.following_id
        JOIN users ON users.id = actors.user_id
        WHERE users.username = ?
        `,
      )
      .get(identifier);
    return result == null ? 0 : result.cnt;
  });
```

The `~Federatable.setFollowersDispatcher()` method creates a followers
collection object to respond to when a `GET /users/{identifier}/followers`
request comes in. Although the SQL is a bit long, it essentially gets the list
of actors following the actor with the `identifier` parameter. The `items`
contains `Recipient` objects, and the `Recipient` type looks like this:

```typescript twoslash
export interface Recipient {
  readonly id: URL | null;
  readonly inboxId: URL | null;
  readonly endpoints?: {
    sharedInbox: URL | null;
  } | null;
}
```

The `id` property contains the actor's unique IRI, and `inboxId` contains
the URL of the actor's personal inbox. `endpoints.sharedInbox` contains
the URL of the actor's shared inbox. Since we have all that information in
our `actors` table, we can fill the `items` array with that information.

The `~CollectionCallbackSetters.setCounter()` method gets the total number of
the followers collection. Here too, the SQL is a bit complex, but in summary,
it's counting the number of actors following the actor with the `identifier`
parameter.

Now, let's check if the followers collection is working properly by using
the `fedify lookup` command:

```sh
fedify lookup http://localhost:8000/users/johndoe/followers
```

If implemented correctly, you should see a result like this:

```console
✔ Looking up the object...
OrderedCollection {
  totalItems: 1,
  items: [ URL "https://activitypub.academy/users/dobussia_dovornath" ]
}
```

However, just creating a followers collection like this doesn't let other
servers know where the followers collection is. So we need to link to
the followers collection in the actor dispatcher:

```typescript twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    // ... omitted ...
    return new Person({
      // ... omitted ...
      followers: ctx.getFollowersUri(identifier),  // [!code highlight]
    });
  })
```

Let's look up the actor with `fedify lookup` again:

```sh
fedify lookup http://localhost:8000/users/johndoe
```

If you see a `"followers"` property included in the result as shown below,
it's correct:

```console
✔ Looking up the object...
Person {
  ... omitted ...
  inbox: URL "http://localhost:8000/users/johndoe/inbox",
  followers: URL "http://localhost:8000/users/johndoe/followers",
  endpoints: Endpoints { sharedInbox: URL "http://localhost:8000/inbox" }
}
```

Now, let's look up our actor in Mastodon again. But the result might be a bit
disappointing:

![Our actor's profile viewed again in Mastodon](/assets/remote-profile-2.havFcOBx.png)

The number of followers is still shown as 0. This is because Mastodon caches
information about actors from other servers. There are ways to update this,
but they're not as easy as pressing the F5 key:

* One way is to wait for a week. Mastodon clears the cache that holds
  information about actors from other servers 7 days after the last update.

* Another way is to send an `Update` activity, but this requires tedious
  coding.

* Or you could try looking it up from another Mastodon server where
  the cache hasn't been created yet.

* The last method is to turn off and on `fedify tunnel` to get a new
  temporary domain assigned.

If you want to see the correct number of followers displayed on another
Mastodon server, try one of the methods I've listed.

## Posts

Now, it's finally time to implement posts. Unlike a typical blog,
the microblog we're creating should be able to store posts created on other
servers as well. Let's design with this in mind.

### Table creation

Let's start by creating a `posts` table. Open the *src/schema.sql* file and
add the following SQL:

```sql [src/schema.sql]
CREATE TABLE IF NOT EXISTS posts (
  id       INTEGER NOT NULL PRIMARY KEY,
  uri      TEXT    NOT NULL UNIQUE CHECK (uri <> ''),
  actor_id INTEGER NOT NULL REFERENCES actors (id),
  content  TEXT    NOT NULL,
  url      TEXT             CHECK (url LIKE 'https://%' OR url LIKE 'http://%'),
  created  TEXT    NOT NULL DEFAULT (CURRENT_TIMESTAMP) CHECK (created <> '')
);
```

* The `id` column is the primary key of the table.

* The `uri` column holds the unique URI of the post. As mentioned earlier,
  all ActivityPub objects must have a unique URI.

* The `actor_id` column points to the actor who wrote the post.

* The `content` column contains the content of the post.

* The `url` column contains the URL where the post is displayed in
  a web browser. There are cases where the URI of an ActivityPub object and
  the URL of the page displayed in a web browser match, but there are also
  cases where they don't, so a separate column is necessary. However,
  it can be empty.

* The `created` column contains the time the post was created.

Let's execute the SQL to create the `posts` table:

```sh
sqlite3 microblog.sqlite3 < src/schema.sql
```

Also define a `Post` type in the *src/schema.ts* file to represent records
that will be stored in the `posts` table in JavaScript:

```typescript twoslash [src/schema.ts]
export interface Post {
  id: number;
  uri: string;
  actor_id: number;
  content: string;
  url: string | null;
  created: string;
}
```

### Home page

To write a post, there needs to be a form somewhere, right? Come to think of it,
we haven't properly created the home page yet. Let's add a post creation form to
the home page.

First, open the *src/views.tsx* file and `import` the `User` type:

```typescript twoslash [src/views.tsx]
// @noErrors: 2307
import type { Actor, User } from "./schema.ts";
```

Then define the `<Home>` component:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface User {
  username: string;
}
interface Actor {
  name: string;
}
// ---cut-before---
export interface HomeProps {
  user: User & Actor;
}

export const Home: FC<HomeProps> = ({ user }) => (
  <>
    <hgroup>
      <h1>{user.name}'s microblog</h1>
      <p>
        <a href={`/users/${user.username}`}>{user.name}'s profile</a>
      </p>
    </hgroup>
    <form method="post" action={`/users/${user.username}/posts`}>
      <fieldset>
        <label>
          <textarea name="content" required={true} placeholder="What's up?" />
        </label>
      </fieldset>
      <input type="submit" value="Post" />
    </form>
  </>
);
```

Then open the *src/app.tsx* file and `import` the `<Home>` component we just
defined:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import { FollowerList, Home, Layout, Profile, SetupForm } from "./views.tsx";
```

And modify the existing `GET /` request handler:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface Actor {}
interface User {}
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export const Home: FC = () => <></>;
// ---cut-before---
app.get("/", (c) => {
  const user = db
    .prepare<unknown[], User & Actor>(
      `
      SELECT users.*, actors.*
      FROM users
      JOIN actors ON users.id = actors.user_id
      LIMIT 1
      `,
    )
    .get();
  if (user == null) return c.redirect("/setup");

  return c.html(
    <Layout>
      <Home user={user} />
    </Layout>,
  );
});
```

If you've done this much, let's check if the home page comes out well.
When you open the <http://localhost:8000/> page in your web browser,
you should see something like this:

![Home page](/assets/home.BoOMqfRd.png)

### Record insertion

Now that we've created the post creation form, we need code to actually save
the post content to the `posts` table.

First, open the *src/federation.ts* file and `import` the `Note` class provided
by Fedify:

```typescript twoslash [src/federation.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Note,  // [!code highlight]
  Person,
  Undo,
  getActorHandle,
  type Recipient,
} from "@fedify/vocab";
```

Add the following code:

```typescript twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setObjectDispatcher(
  Note,
  "/users/{identifier}/posts/{id}",
  (ctx, values) => {
    return null;
  },
);
```

This code doesn't do much yet, but it's needed to determine the permalink
format of the posts. We'll implement it properly later.

In ActivityPub, the content of posts is exchanged in HTML format. Therefore,
we need to convert the content received in plain text format to HTML format.
At this time, we need the *[stringify-entities]* package to convert characters
like `<` and `>` to HTML entities like `&lt;` and `&gt;`:

```sh
npm add stringify-entities
```

Then open the *src/app.tsx* file and `import` the installed package:

```typescript twoslash [src/app.tsx]
import { stringifyEntities } from "stringify-entities";
```

Also `import` the `Post` type and the `Note` class provided by Fedify:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import type { Actor, Post, User } from "./schema.ts";
import { Note } from "@fedify/vocab";
```

And implement the `POST /users/{username}/posts` request handler:

```typescript twoslash [src/app.tsx]
import { stringifyEntities } from "stringify-entities";
import { type Federation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const fedi = null as unknown as Federation<void>;
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { id: number; }
interface Post { id: number; }
// ---cut-before---
app.post("/users/:username/posts", async (c) => {
  const username = c.req.param("username");
  const actor = db
    .prepare<unknown[], Actor>(
      `
      SELECT actors.*
      FROM actors
      JOIN users ON users.id = actors.user_id
      WHERE users.username = ?
      `,
    )
    .get(username);
  if (actor == null) return c.redirect("/setup");
  const form = await c.req.formData();
  const content = form.get("content")?.toString();
  if (content == null || content.trim() === "") {
    return c.text("Content is required", 400);
  }
  const ctx = fedi.createContext(c.req.raw, undefined);
  const url: string | null = db.transaction(() => {
    const post = db
      .prepare<unknown[], Post>(
        `
        INSERT INTO posts (uri, actor_id, content)
        VALUES ('https://localhost/', ?, ?)
        RETURNING *
        `,
      )
      .get(actor.id, stringifyEntities(content, { escapeOnly: true }));
    if (post == null) return null;
    const url = ctx.getObjectUri(Note, {
      identifier: username,
      id: post.id.toString(),
    }).href;
    db.prepare("UPDATE posts SET uri = ?, url = ? WHERE id = ?").run(
      url,
      url,
      post.id,
    );
    return url;
  })();
  if (url == null) return c.text("Failed to create post", 500);
  return c.redirect(url);
});
```

Although it's a normal code that adds a record to the `posts` table, there's
one peculiar part. To get the URI of the ActivityPub object representing
the post, `posts.id` needs to be determined first, so we first insert
a temporary URI `https://localhost/` into the `posts.uri` column to add
the record, then use the determined `posts.id` to get the actual URI using
the `getObjectUri()` method and update the record.

Now, let's open the <http://localhost:8000/> page in your web browser and
create a post:

![Creating a post](/assets/home-2.BRuu-QR7.png)

When you press the *Post* button to create a post, unfortunately you'll get
a `404 Not Found` error:

![404 Not Found](/assets/404.DUD_N_SX.png)

This is because we implemented it to redirect to the post's permalink,
but we haven't implemented the post page yet. However, a record should have
been created in the `posts` table. Let's check:

```sh
echo "SELECT * FROM posts;" | sqlite3 -table microblog.sqlite3
```

You should see a result like this:

| `id` | `uri`                                         | `actor_id` | `content`             | `url`                                         | `created`             |
| ---- | --------------------------------------------- | ---------- | --------------------- | --------------------------------------------- | --------------------- |
| `1`  | `http://localhost:8000/users/johndoe/posts/1` | `1`        | `It's my first post!` | `http://localhost:8000/users/johndoe/posts/1` | `2024-09-02 08:10:55` |

[stringify-entities]: https://github.com/wooorm/stringify-entities

### Post page

To prevent the `404 Not Found` error after creating a post, let's implement
the post page.

Open the *src/views.tsx* file and `import` the `Post` type:

```typescript twoslash [src/views.tsx]
// @noErrors: 2307
import type { Actor, Post, User } from "./schema.ts";
```

Then define the `<PostPage>` component and the `<PostView>` component:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
export interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  followers: number;
}
interface Actor { } interface Post {
  uri: string;
  url: string | null;
  content: string;
  created: string;
}
const Profile: FC<ProfileProps> = () => <></>;
export interface ActorLinkProps { actor: Actor; }
const ActorLink: FC<ActorLinkProps> = () => <></>;
// ---cut-before---
export interface PostPageProps extends ProfileProps, PostViewProps {}

export const PostPage: FC<PostPageProps> = (props) => (
  <>
    <Profile
      name={props.name}
      username={props.username}
      handle={props.handle}
      followers={props.followers}
    />
    <PostView post={props.post} />
  </>
);

export interface PostViewProps {
  post: Post & Actor;
}

export const PostView: FC<PostViewProps> = ({ post }) => (
  <article>
    <header>
      <ActorLink actor={post} />
    </header>
    {/* biome-ignore lint/security/noDangerouslySetInnerHtml: */}
    <div dangerouslySetInnerHTML={{ __html: post.content }} />
    <footer>
      <a href={post.url ?? post.uri}>
        <time datetime={new Date(post.created).toISOString()}>
          {post.created}
        </time>
      </a>
    </footer>
  </article>
);
```

Now let's load the post data from the database and render it with
the `<PostPage>` component. Open the *src/app.tsx* file and `import`
the `<PostPage>` component we just defined:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import {
  FollowerList,
  Home,
  Layout,
  PostPage,  // [!code highlight]
  Profile,
  SetupForm,
} from "./views.tsx";
```

And implement the `GET /users/{username}/posts/{id}` request handler:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { name: string | null; handle: string; }
interface Post { id: number; actor_id: number; }
interface User { username: string; }
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  followers: number;
}
export interface PostViewProps { post: Post & Actor; }
export interface PostPageProps extends ProfileProps, PostViewProps {}
export const PostPage: FC<PostPageProps> = () => <></>;
// ---cut-before---
app.get("/users/:username/posts/:id", (c) => {
  const post = db
    .prepare<unknown[], Post & Actor & User>(
      `
      SELECT users.*, actors.*, posts.*
      FROM posts
      JOIN actors ON actors.id = posts.actor_id
      JOIN users ON users.id = actors.user_id
      WHERE users.username = ? AND posts.id = ?
      `,
    )
    .get(c.req.param("username"), c.req.param("id"));
  if (post == null) return c.notFound();

  // biome-ignore lint/style/noNonNullAssertion: Always returns a single record
  const { followers } = db
    .prepare<unknown[], { followers: number }>(
      `
      SELECT count(*) AS followers
      FROM follows
      WHERE follows.following_id = ?
      `,
    )
    .get(post.actor_id)!;
  return c.html(
    <Layout>
      <PostPage
        name={post.name ?? post.username}
        username={post.username}
        handle={post.handle}
        followers={followers}
        post={post}
      />
    </Layout>,
  );
});
```

Now let's open the <http://localhost:8000/users/johndoe/posts/1> page that
gave a `404 Not Found` error earlier in your web browser:

![Post page](/assets/post-page.B2yFZAN1.png)

### `Note` object dispatcher

Now, can we check if the post can be viewed from other Mastodon servers?
First, use `fedify tunnel` to expose the local server to the public internet.

In that state, try entering the post's permalink
<https://temp-address.serveo.net/users/johndoe/posts/1> (replace with your
temporary domain name) in the Mastodon search box:

![Empty search results](/assets/search-results-2.TfIygmaz.png)

Unfortunately, the search results are empty. This is because we haven't exposed
the post as an ActivityPub object. Let's expose the post as an ActivityPub
object.

Before implementation, we need to install a necessary library. Because
the [Temporal API] used by Fedify to represent time is not yet built into
Node.js, we need the *[@js-temporal/polyfill]* package to polyfill it:

```sh
npm add @js-temporal/polyfill
```

Open the *src/federation.ts* file and `import` the installed package:

```typescript twoslash [src/federation.ts]
import { Temporal } from "@js-temporal/polyfill";
```

Also `import` the `Post` type and the `PUBLIC_COLLECTION` constant provided by
Fedify:

```typescript twoslash [src/federation.ts]
// @noErrors: 2307
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Note,
  PUBLIC_COLLECTION,  // [!code highlight]
  Person,
  Undo,
  getActorHandle,
  type Recipient,
} from "@fedify/vocab";
import type {
  Actor,
  Key,
  Post,  // [!code highlight]
  User,
} from "./schema.ts";
```

Short posts like microblog posts are usually represented as `Note` in
ActivityPub. We've already created an empty implementation of the object
dispatcher for the `Note` class:

```typescript twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setObjectDispatcher(
  Note,
  "/users/{identifier}/posts/{id}",
  (ctx, values) => {
    return null;
  },
);
```

Let's modify this as follows:

```typescript twoslash [src/federation.ts]
import { Temporal } from "@js-temporal/polyfill";
import { type Federation } from "@fedify/fedify";
import { Note, PUBLIC_COLLECTION } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import Database from "better-sqlite3";
const db = new Database("");
interface Post { id: number; content: string; created: string; }
// ---cut-before---
federation.setObjectDispatcher(
  Note,
  "/users/{identifier}/posts/{id}",
  (ctx, values) => {
    const post = db
      .prepare<unknown[], Post>(
        `
        SELECT posts.*
        FROM posts
        JOIN actors ON actors.id = posts.actor_id
        JOIN users ON users.id = actors.user_id
        WHERE users.username = ? AND posts.id = ?
        `,
      )
      .get(values.identifier, values.id);
    if (post == null) return null;
    return new Note({
      id: ctx.getObjectUri(Note, values),
      attribution: ctx.getActorUri(values.identifier),
      to: PUBLIC_COLLECTION,
      cc: ctx.getFollowersUri(values.identifier),
      content: post.content,
      mediaType: "text/html",
      published: Temporal.Instant.from(`${post.created.replace(" ", "T")}Z`),
      url: ctx.getObjectUri(Note, values),
    });
  },
);
```

The property values filled when creating the `Note` object have the following
roles:

* Putting `ctx.getActorUri(values.identifier)` in the `attribution` property
  indicates that the author of this post is the actor we created.

* Putting `PUBLIC_COLLECTION` in the `to` property indicates that this
  post is a public post.

* Putting `ctx.getFollowersUri(values.identifier)` in the `cc` property
  indicates that this post is delivered to followers, but this itself doesn't
  have much meaning.

Now, let's try entering the post's permalink
<https://temp-address.serveo.net/users/johndoe/posts/1> (replace with your
temporary domain name) in the Mastodon search box again:

![Mastodon search results showing our created post](/assets/search-results-3.7hzVgwrP.png)

This time, our created post appears properly in the search results!

[Temporal API]: https://tc39.es/proposal-temporal/docs/

[@js-temporal/polyfill]: https://github.com/js-temporal/temporal-polyfill

### Sending `Create(Note)` activity

However, even if you follow our created actor from Mastodon, newly created posts
won't appear in the Mastodon timeline. This is because Mastodon doesn't
automatically fetch new posts; instead, the side that created the new post needs
to send a `Create(Note)` activity to notify that a new post has been created.

Let's modify the code to send a `Create(Note)` activity when creating a post.
Open the *src/app.tsx* file and `import` the `Create` class provided by Fedify:

```typescript twoslash [src/app.tsx]
import { Create, Note } from "@fedify/vocab";
```

Then modify the `POST /users/{username}/posts` request handler as follows:

```typescript{4,24,26-40} twoslash [src/app.tsx]
import { stringifyEntities } from "stringify-entities";
import { type Federation } from "@fedify/fedify";
import { Create, Note } from "@fedify/vocab";
const fedi = null as unknown as Federation<void>;
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface Post { id: number; }
interface Actor { id: number; }
const actor = {} as unknown as Actor;
const content = "" as string;
const username = "" as string;
// ---cut-before---
app.post("/users/:username/posts", async (c) => {
  // ... omitted ...
  const ctx = fedi.createContext(c.req.raw, undefined);
  const post: Post | null = db.transaction(() => {
    const post = db
      .prepare<unknown[], Post>(
        `
        INSERT INTO posts (uri, actor_id, content)
        VALUES ('https://localhost/', ?, ?)
        RETURNING *
        `,
      )
      .get(actor.id, stringifyEntities(content, { escapeOnly: true }));
    if (post == null) return null;
    const url = ctx.getObjectUri(Note, {
      identifier: username,
      id: post.id.toString(),
    }).href;
    db.prepare("UPDATE posts SET uri = ?, url = ? WHERE id = ?").run(
      url,
      url,
      post.id,
    );
    return post;
  })();
  if (post == null) return c.text("Failed to create post", 500);
  const noteArgs = { identifier: username, id: post.id.toString() };
  const note = await ctx.getObject(Note, noteArgs);
  await ctx.sendActivity(
    { identifier: username },
    "followers",
    new Create({
      id: new URL("#activity", note?.id ?? undefined),
      object: note,
      actors: note?.attributionIds,
      tos: note?.toIds,
      ccs: note?.ccIds,
    }),
  );
  return c.redirect(ctx.getObjectUri(Note, noteArgs).href);
});
```

The `getObject()` method returns the ActivityPub object created by the object
dispatcher. Here, it will return a `Note` object. We put that `Note` object in
the `object` property when creating the `Create` object. We set the `tos`
(plural of `to`) and `ccs` (plural of `cc`) properties of the activity the same
as the `Note` object. We set an arbitrary unique URI for the `id` of
the activity.

> \[!TIP]
> The `id` property of the activity object doesn't necessarily need to be
> an accessible URI. It just needs to be unique.

The second parameter of the `sendActivity()` method is where the recipients go,
and here we've specified the special option `"followers"`. When this option is
specified, it uses the followers collection dispatcher we implemented earlier
to send the activity to all followers.

Now that we've finished the implementation, let's check if the `Create(Note)`
activity is sent properly.

With the `fedify tunnel` command exposing the local server to the public
internet, go to [ActivityPub.Academy] and follow
*@johndoe@temp-address.serveo.net* (replace the domain name with the temporary
domain name assigned to you). After making sure that the follow request has been
accepted in the followers list, go to <https://temp-address.serveo.net/> (again,
replace the domain name) in your web browser and create a new post.

> \[!WARNING]
> When testing activity transmission, you must access via a domain name
> accessible from the public internet, not *localhost*. This is because when
> determining the ID of ActivityPub objects, the URI is constructed based on
> the domain name of the incoming request.

To check if the `Create(Note)` activity was sent well, let's look at
ActivityPub.Academy's *Activity Log*:

![Activity Log showing received Create(Note) activity](/assets/activity-log-5.BGmaQ3LG.png)

It came in well. Now let's look at the timeline in ActivityPub.Academy:

![The created post is visible in ActivityPub.Academy's timeline](/assets/academy-timeline.DcazK0VL.png)

We did it!

## Post list on profile page

Currently, the profile page only shows the name, fediverse handle, and number of
followers, but not the actual posts. Let's display the created posts on
the profile page.

First, open the *src/views.tsx* file and add a `<PostList>` component:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface Post { id: number; }
interface Actor {}
interface PostViewProps { post: Post & Actor; }
const PostView: FC<PostViewProps> = () => <></>;
// ---cut-before---
export interface PostListProps {
  posts: (Post & Actor)[];
}

export const PostList: FC<PostListProps> = ({ posts }) => (
  <>
    {posts.map((post) => (
      <div key={post.id}>
        <PostView post={post} />
      </div>
    ))}
  </>
);
```

Then, open the *src/app.tsx* file and `import` the `<PostList>` component
we just defined:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import {
  FollowerList,
  Home,
  Layout,
  PostList,  // [!code highlight]
  PostPage,
  Profile,
  SetupForm,
} from "./views.tsx";
```

Modify the existing `GET /users/{username}` request handler as follows:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User { }
interface Actor { user_id: number | null; }
interface Post {}
const user = {} as unknown as User & Actor;
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export interface PostListProps { posts: (Post & Actor)[]; }
export const PostList: FC<PostListProps> = () => <></>;
// ---cut-before---
app.get("/users/:username", async (c) => {
  // ... omitted ...
  const posts = db
    .prepare<unknown[], Post & Actor>(
      `
      SELECT actors.*, posts.*
      FROM posts
      JOIN actors ON posts.actor_id = actors.id
      WHERE actors.user_id = ?
      ORDER BY posts.created DESC
      `,
    )
    .all(user.user_id);
  // ... omitted ...
  return c.html(
    <Layout>
      // ... omitted ...
      <PostList posts={posts} />
    </Layout>,
  );
});
```

Now, let's open the <http://localhost:8000/users/johndoe> page in your web
browser:

![Modified profile page](/assets/profile-page-4.DDjJeIrV.png)

You can see that the created posts are displayed well.

## Follow

Currently, our actor can receive follow requests from actors on other servers,
but it can't send follow requests to actors on other servers. Since we can't
follow, we also can't see posts created by other actors. So, let's add
the functionality to send follow requests to actors on other servers.

Let's start with the UI. Open the *src/views.tsx* file and modify the existing
`<Home>` component as follows:

```tsx{6-17} twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface User { username: string; }
interface HomeProps { user: User; }
// ---cut-before---
export const Home: FC<HomeProps> = ({ user }) => (
  <>
    <hgroup>
      {/* ... omitted ... */}
    </hgroup>
    <form method="post" action={`/users/${user.username}/following`}>
      {/* biome-ignore lint/a11y/noRedundantRoles: PicoCSS requires role=group */}
      <fieldset role="group">
        <input
          type="text"
          name="actor"
          required={true}
          placeholder="Enter an actor handle (e.g., @johndoe@mastodon.com) or URI (e.g., https://mastodon.com/@johndoe)"
        />
        <input type="submit" value="Follow" />
      </fieldset>
    </form>
    <form method="post" action={`/users/${user.username}/posts`}>
      {/* ... omitted ... */}
    </form>
  </>
);
```

To check if the home page has been modified correctly, open
the <http://localhost:8000/> page in your web browser:

![Home page with follow request UI added](/assets/home-3.Bg8eDKPT.png)

### Sending `Follow` activity

Now that we have the follow request UI, let's write the code to actually send
the `Follow` activity.

Open the *src/app.tsx* file and `import` the `Follow` class and the `isActor()`
function provided by Fedify:

```typescript twoslash [src/app.tsx]
import {
  Create,
  Follow,        // [!code highlight]
  isActor,       // [!code highlight]
  Note,
} from "@fedify/vocab";
```

Then add a `POST /users/{username}/following` request handler:

```typescript twoslash [src/app.tsx]
import { type Federation } from "@fedify/fedify";
import { Follow, isActor } from "@fedify/vocab";
const fedi = null as unknown as Federation<void>;
import { Hono } from "hono";
const app = new Hono();
// ---cut-before---
app.post("/users/:username/following", async (c) => {
  const username = c.req.param("username");
  const form = await c.req.formData();
  const handle = form.get("actor");
  if (typeof handle !== "string") {
    return c.text("Invalid actor handle or URL", 400);
  }
  const ctx = fedi.createContext(c.req.raw, undefined);
  const actor = await ctx.lookupObject(handle.trim());
  if (!isActor(actor)) {
    return c.text("Invalid actor handle or URL", 400);
  }
  await ctx.sendActivity(
    { identifier: username },
    actor,
    new Follow({
      actor: ctx.getActorUri(username),
      object: actor.id,
      to: actor.id,
    }),
  );
  return c.text("Successfully sent a follow request");
});
```

`Context.lookupObject()` method looks up ActivityPub objects, including actors.
It takes the unique URI of an ActivityPub object or a fediverse handle as input
and returns the looked-up ActivityPub object.

The `isActor()` function checks if the given ActivityPub object is an actor.

In this code, we're using the `sendActivity()` method to send a `Follow`
activity to the looked-up actor. However, we're not adding any records to
the `follows` table yet. This is because we should add the record after
receiving an `Accept(Follow)` activity from the other party.

### Testing

We need to check if the implemented follow request functionality is working
properly. This time too, we need to send an activity, so use the `fedify tunnel`
command to expose the local server to the public internet, then enter
the <https://temp-address.serveo.net/> page (replace the domain name) in
your web browser:

![Home page with follow request UI](./microblog/home-4.png)

You need to enter the fediverse handle of the actor you want to follow in
the follow request input field. Here, for easy debugging, let's enter an actor
from [ActivityPub.Academy]. By the way, you can see the handle of the temporary
account logged in to ActivityPub.Academy by clicking on the temporary account
name to go to the profile page and looking just below the name:

![Fediverse handle visible on the account profile page in ActivityPub.Academy](/assets/academy-profile.BWyi1vIy.png)

Enter the ActivityPub.Academy actor's handle as follows, then press the *Follow*
button to send a follow request:

![Sending a follow request to the ActivityPub.Academy actor](/assets/home-5.nO4VlUKm.png)

And check ActivityPub.Academy's *Activity Log*:

![ActivityPub.Academy's Activity Log](/assets/activity-log-6.BMlsSF-r.png)

The *Activity Log* shows the `Follow` activity we sent and the `Accept(Follow)`
activity sent in response from ActivityPub.Academy.

If you go to the notifications page in ActivityPub.Academy, you can see that
the follow request has actually arrived:

![Arrived follow request shown on ActivityPub.Academy's notifications page](/assets/academy-notifications.BU98-1EO.png)

### Receiving `Accept(Follow)` activity

However, we're not taking any action on the received `Accept(Follow)` activity
yet, so we need to implement this part.

Open the *src/federation.ts* file and `import` the `isActor()` function and
`Actor` type provided by Fedify:

```typescript twoslash [src/federation.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Endpoints,
  Follow,
  Note,
  PUBLIC_COLLECTION,
  Person,
  Undo,
  getActorHandle,
  isActor,                // [!code highlight]
  type Actor as APActor,  // [!code highlight]
  type Recipient,
} from "@fedify/vocab";
```

We've given the alias `APActor` to the `Actor` type because
the Actor type name is already used in this source file.

Before implementation, let's refactor the code that adds actor information to
the `actors` table when first encountered to make it reusable. Add the following
function:

```typescript twoslash [src/federation.ts]
import { getActorHandle, isActor, type Actor as APActor } from "@fedify/vocab";
import type { Logger } from "@logtape/logtape";
const logger = {} as unknown as Logger;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor {}
// ---cut-before---
async function persistActor(actor: APActor): Promise<Actor | null> {
  if (actor.id == null || actor.inboxId == null) {
    logger.debug("Actor is missing required fields: {actor}", { actor });
    return null;
  }
  return (
    db
      .prepare<unknown[], Actor>(
        `
        -- Add a new actor record or update if it already exists
        INSERT INTO actors (uri, handle, name, inbox_url, shared_inbox_url, url)
        VALUES (?, ?, ?, ?, ?, ?)
        ON CONFLICT (uri) DO UPDATE SET
          handle = excluded.handle,
          name = excluded.name,
          inbox_url = excluded.inbox_url,
          shared_inbox_url = excluded.shared_inbox_url,
          url = excluded.url
        WHERE
          actors.uri = excluded.uri
        RETURNING *
        `,
      )
      .get(
        actor.id.href,
        await getActorHandle(actor),
        actor.name?.toString(),
        actor.inboxId.href,
        actor.endpoints?.sharedInbox?.href,
        actor.url?.href,
      ) ?? null
  );
}
```

The defined `persistActor()` function adds a record corresponding to the actor
object passed as an argument to the `actors` table. If there's already
a corresponding record in the table, it updates the record.

Change the code doing the same role in the `on(Follow, ...)` part of the inbox
to use the `persistActor()` function:

```typescript twoslash [src/federation.ts]
import { type Federation, type ParseUriResult } from "@fedify/fedify";
import { type Actor as APActor, Follow } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import type { Logger } from "@logtape/logtape";
const logger = {} as unknown as Logger;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { id: number; }
async function persistActor(actor: APActor): Promise<Actor | null> {
  return null;
}
const object = {} as unknown as ParseUriResult;
const followingId = 0 as number;
const follower = {} as unknown as APActor;
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    // ... omitted ...
    if (followingId == null) {
      logger.debug(
        "Failed to find the actor to follow in the database: {object}",
        { object },
      );
    }
    const followerId = (await persistActor(follower))?.id;  // [!code highlight]
    db.prepare(
      "INSERT INTO follows (following_id, follower_id) VALUES (?, ?)",
    ).run(followingId, followerId);
    // ... omitted ...
  })
```

Now that we've finished refactoring, let's implement the behavior when receiving
an `Accept(Follow)` activity in the inbox:

```typescript twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import {
  Accept,
  type Actor as APActor,
  Follow,
  isActor,
} from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { id: number; }
async function persistActor(actor: APActor): Promise<Actor | null> {
  return null;
}
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
// ---cut-before---
  .on(Accept, async (ctx, accept) => {
    const follow = await accept.getObject();
    if (!(follow instanceof Follow)) return;
    const following = await accept.getActor();
    if (!isActor(following)) return;
    const follower = follow.actorId;
    if (follower == null) return;
    const parsed = ctx.parseUri(follower);
    if (parsed == null || parsed.type !== "actor") return;
    const followingId = (await persistActor(following))?.id;
    if (followingId == null) return;
    db.prepare(
      `
      INSERT INTO follows (following_id, follower_id)
      VALUES (
        ?,
        (
          SELECT actors.id
          FROM actors
          JOIN users ON actors.user_id = users.id
          WHERE users.username = ?
        )
      )
      `,
    ).run(followingId, parsed.identifier);
  });
```

Although there's a lot of validity checking code, in summary, it gets the actor
who sent the follow request (`follower`) and the actor who received the follow
request (`following`) from the contents of the `Accept(Follow)` activity and
adds a record to the `follows` table.

### Testing

Now we need to check if it's working well, but there's a problem. When we sent
a follow request earlier, [ActivityPub.Academy] already accepted the follow
request and sent an `Accept(Follow)` activity, so even if we send another follow
request, it will be ignored. Therefore, we need to log out of
ActivityPub.Academy and create a new temporary account to test.

If you've created a new temporary account in ActivityPub.Academy, with the local
server exposed to the public internet using the `fedify tunnel` command, go to
the <https://temp-address.serveo.net/> page (replace the domain name) in your
web browser and send a follow request to the new temporary account on
ActivityPub.Academy.

If the follow request was sent successfully, you should see the `Follow`
activity arriving and the `Accept(Follow)` activity being sent in response in
the *Activity Log*, just like before:

![Activity Log showing received Follow activity and sent Accept(Follow) activity](/assets/activity-log-7.C0CTOcUr.png)

We haven't implemented the following list yet, so let's directly check if
a record has been properly added to the `follows` table:

```sh
echo "SELECT * FROM follows WHERE follower_id = 1;" | sqlite3 -table microblog.sqlite3
```

If successful, you should see a result like this (the value in
the `following_id` column might be slightly different):

| `following_id` | `follower_id` | `created`             |
| -------------- | ------------- | --------------------- |
| `3`            | `1`           | `2024-09-02 14:11:17` |

## Following list

Let's create a page that displays the list of actors our actor is following.

First, open the *src/views.tsx* file and add a `<FollowingList>` component:

```tsx twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface Actor { id: number; }
export interface ActorLinkProps { actor: Actor; }
const ActorLink: FC<ActorLinkProps> = () => <></>;
// ---cut-before---
export interface FollowingListProps {
  following: Actor[];
}

export const FollowingList: FC<FollowingListProps> = ({ following }) => (
  <>
    <h2>Following</h2>
    <ul>
      {following.map((actor) => (
        <li key={actor.id}>
          <ActorLink actor={actor} />
        </li>
      ))}
    </ul>
  </>
);
```

Then, open the *src/app.tsx* file and `import` the `<FollowingList>` component
we just defined:

```typescript twoslash [src/app.tsx]
// @noErrors: 2307
import {
  FollowerList,
  FollowingList,  // [!code highlight]
  Home,
  Layout,
  PostList,
  PostPage,
  Profile,
  SetupForm,
} from "./views.tsx";
```

And add a handler for the `GET /users/{username}/following` request:

```tsx twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface Actor {}
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export interface FollowingListProps { following: Actor[]; }
export const FollowingList: FC<FollowingListProps> = () => <></>;
// ---cut-before---
app.get("/users/:username/following", async (c) => {
  const following = db
    .prepare<unknown[], Actor>(
      `
      SELECT following.*
      FROM follows
      JOIN actors AS followers ON follows.follower_id = followers.id
      JOIN actors AS following ON follows.following_id = following.id
      JOIN users ON users.id = followers.user_id
      WHERE users.username = ?
      ORDER BY follows.created DESC
      `,
    )
    .all(c.req.param("username"));
  return c.html(
    <Layout>
      <FollowingList following={following} />
    </Layout>,
  );
});
```

To check if it's been implemented correctly,
open the <http://localhost:8000/users/johndoe/following> page in your
web browser:

![Following list](/assets/following-list.Du0M00k7.png)

## Following count

Just as we're showing the number of followers, we should also display the number
of accounts the user is following.

Open the *src/views.tsx* file and modify the `<Profile>` component as follows:

```tsx{23-24} twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
// ---cut-before---
export interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  following: number;  // [!code highlight]
  followers: number;
}

export const Profile: FC<ProfileProps> = ({
  name,
  username,
  handle,
  following,  // [!code highlight]
  followers,
}) => (
  <>
    <hgroup>
      <h1>
        <a href={`/users/${username}`}>{name}</a>
      </h1>
      <p>
        <span style="user-select: all;">{handle}</span> &middot;{" "}
        <a href={`/users/${username}/following`}>{following} following</a>{" "}
        &middot;{" "}
        <a href={`/users/${username}/followers`}>
          {followers === 1 ? "1 follower" : `${followers} followers`}
        </a>
      </p>
    </hgroup>
  </>
);
```

Also modify the `<PostPage>` component as follows:

```tsx{9} twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  following: number;
  followers: number;
}
interface Post {}
interface Actor {}
interface PostViewProps { post: Post & Actor; }
const PostView: FC<PostViewProps> = () => <></>;
const Profile: FC<ProfileProps> = () => <></>;
// ---cut-before---
export interface PostPageProps extends ProfileProps, PostViewProps {}

export const PostPage: FC<PostPageProps> = (props) => (
  <>
    <Profile
      name={props.name}
      username={props.username}
      handle={props.handle}
      following={props.following}
      followers={props.followers}
    />
    <PostView post={props.post} />
  </>
);
```

Now we need to write code to actually query the database and get the number
of following accounts.

Open the *src/app.tsx* file and modify the `GET /users/{username}` request
handler as follows:

```tsx{5-15,23} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User { id: number; username: string; }
interface Actor { name: string | null; }
interface Post {}
const user = {} as unknown as User & Actor;
const handle = "" as string;
const followers = 0 as number;
const posts = [] as (Post & Actor)[];
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  following: number;
  followers: number;
}
export const Profile: FC<ProfileProps> = () => <></>;
export interface PostListProps { posts: (Post & Actor)[]; }
export const PostList: FC<PostListProps> = () => <></>;
// ---cut-before---
app.get("/users/:username", async (c) => {
  // ... omitted ...
  if (user == null) return c.notFound();

  // biome-ignore lint/style/noNonNullAssertion: Always returns a single record
  const { following } = db
    .prepare<unknown[], { following: number }>(
      `
      SELECT count(*) AS following
      FROM follows
      JOIN actors ON follows.follower_id = actors.id
      WHERE actors.user_id = ?
      `,
    )
    .get(user.id)!;
  // ... omitted ...
  return c.html(
    <Layout>
      <Profile
        name={user.name ?? user.username}
        username={user.username}
        handle={handle}
        following={following}
        followers={followers}
      />
      <PostList posts={posts} />
    </Layout>,
  );
});
```

Also modify the `GET /users/{username}/posts/{id}` request handler:

```tsx{5-14,21} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User { id: number; username: string; }
interface Actor { name: string | null; handle: string; }
interface Post { actor_id: number; }
const post = {} as unknown as Post & User & Actor;
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
interface ProfileProps {
  name: string;
  username: string;
  handle: string;
  following: number;
  followers: number;
}
interface PostViewProps { post: Post & Actor; }
interface PostPageProps extends ProfileProps, PostViewProps {}
const PostPage: FC<PostPageProps> = () => <></>;
// ---cut-before---
app.get("/users/:username/posts/:id", (c) => {
  // ... omitted ...
  if (post == null) return c.notFound();

  // biome-ignore lint/style/noNonNullAssertion: Always returns a single record
  const { following, followers } = db
    .prepare<unknown[], { following: number; followers: number }>(
      `
      SELECT sum(follows.follower_id = ?) AS following,
             sum(follows.following_id = ?) AS followers
      FROM follows
      `,
    )
    .get(post.actor_id, post.actor_id)!;
  return c.html(
    <Layout>
      <PostPage
        name={post.name ?? post.username}
        username={post.username}
        handle={post.handle}
        following={following}
        followers={followers}
        post={post}
      />
    </Layout>,
  );
});
```

If you've made all these modifications,
open the <http://localhost:8000/users/johndoe> page in your web browser:

![Profile page](/assets/profile-page-5.Bs7wI18J.png)

## Timeline

We've implemented many things, but posts written on other Mastodon servers are
still not visible. As you might have guessed from the process so far, just as we
sent a `Create(Note)` activity when we wrote a post, we need to receive
a `Create(Note)` activity from other servers to see posts written on other
Mastodon servers.

To see exactly what happens when a post is written on another Mastodon server,
let's create a new post on [ActivityPub.Academy]:

![Creating a new post on ActivityPub.Academy](/assets/academy-compose.DJU3L4C1.png)

After pressing the *Publish!* button to save the post, go to the *Activity Log*
page and check if the `Create(Note)` activity was indeed sent:

![Activity Log showing sent Create(Note) activity](/assets/activity-log-8.8tG98GVz.png)

Now we need to write code to receive this sent `Create(Note)` activity.

### Receiving `Create(Note)` activity

Open the *src/federation.ts* file and `import` the `Create` class provided by
Fedify:

```typescript twoslash [src/federation.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,
  Create,  // [!code highlight]
  Endpoints,
  Follow,
  Note,
  PUBLIC_COLLECTION,
  Person,
  Undo,
  getActorHandle,
  isActor,
  type Actor as APActor,
  type Recipient,
} from "@fedify/vocab";
```

And add `on(Create, ...)` to the inbox code:

```typescript twoslash [src/federation.ts]
import { type Federation } from "@fedify/fedify";
import {
  type Actor as APActor,
  Create,
  Note,
  isActor,
} from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
import Database from "better-sqlite3";
const db = new Database("");
interface Actor { id: number; }
async function persistActor(actor: APActor): Promise<Actor | null> {
  return null;
}
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
// ---cut-before---
  .on(Create, async (ctx, create) => {
    const object = await create.getObject();
    if (!(object instanceof Note)) return;
    const actor = create.actorId;
    if (actor == null) return;
    const author = await object.getAttribution();
    if (!isActor(author) || author.id?.href !== actor.href) return;
    const actorId = (await persistActor(author))?.id;
    if (actorId == null) return;
    if (object.id == null) return;
    const content = object.content?.toString();
    db.prepare(
      "INSERT INTO posts (uri, actor_id, content, url) VALUES (?, ?, ?, ?)",
    ).run(object.id.href, actorId, content, object.url?.href);
  });
```

We use the `~Object.getAttribution()` method to get the author, then add
the actor to the `actors` table if it's not already there using
the `persistActor()` function. Then we add a new record to the `posts` table.

To check if the code is working well, let's go back to [ActivityPub.Academy] and
create a post. Open the *Activity Log* to check if the `Create(Note)` activity
was sent, then use the following command to check if a record was indeed added
to the `posts` table:

```sh
echo "SELECT * FROM posts WHERE actor_id != 1" | sqlite3 -table microblog.sqlite3
```

If a record was indeed added, you should see a result like this:

| `id` | `uri`                                                                            | `actor_id` | `content`                                       | `url`                                                              | `created`             |
| ---- | -------------------------------------------------------------------------------- | ---------- | ----------------------------------------------- | ------------------------------------------------------------------ | --------------------- |
| `3`  | `https://activitypub.academy/users/algusia_draneoll/statuses/113068684551948316` | `3`        | `<p>Would it send a Create(Note) activity?</p>` | `https://activitypub.academy/@algusia_draneoll/113068684551948316` | `2024-09-02 15:33:32` |

### Displaying remote posts

Now that we've added remote posts as records in the `posts` table, all that's
left is to display these records well. This is often called a timeline
feature.

First, open the *src/views.tsx* file and modify the `<Home>` component:

```tsx{1,8} twoslash [src/views.tsx]
import type { FC } from "hono/jsx";
interface User {}
interface Actor {}
interface Post {}
interface PostListProps { posts: Post[]; }
const PostList: FC<PostListProps> = () => <></>;
// ---cut-before---
export interface HomeProps extends PostListProps {
  user: User & Actor;
}

export const Home: FC<HomeProps> = ({ user, posts }) => (
  <>
    {/* ... omitted ... */}
    <PostList posts={posts} />
  </>
);
```

Then, open the *src/app.tsx* file and modify the `GET /` request handler:

```tsx{5-19,22} twoslash [src/app.tsx]
import { Hono } from "hono";
const app = new Hono();
import Database from "better-sqlite3";
const db = new Database("");
interface User { id: number; }
interface Actor {}
interface Post {}
const user = {} as unknown as User & Actor;
import type { FC } from "hono/jsx";
export const Layout: FC = (props) => <html/>;
export interface PostListProps { posts: Post[]; }
export interface HomeProps extends PostListProps { user: User & Actor; }
export const Home: FC<HomeProps> = () => <></>;
// ---cut-before---
app.get("/", (c) => {
  // ... omitted ...
  if (user == null) return c.redirect("/setup");

  const posts = db
    .prepare<unknown[], Post & Actor>(
      `
      SELECT actors.*, posts.*
      FROM posts
      JOIN actors ON posts.actor_id = actors.id
      WHERE posts.actor_id = ? OR posts.actor_id IN (
        SELECT following_id
        FROM follows
        WHERE follower_id = ?
      )
      ORDER BY posts.created DESC
      `,
    )
    .all(user.id, user.id);
  return c.html(
    <Layout>
      <Home user={user} posts={posts} />
    </Layout>,
  );
});
```

Now that we've implemented everything, let's open the <http://localhost:8000/>
page in your web browser to admire the timeline:

![Timeline visible on the home page](/assets/home-6.Chj_T8HC.png)

As you can see above, posts created remotely and posts created locally are
displayed in chronological order. How do you like it?

This is all we're going to implement in this tutorial. Based on this, you should
be able to complete your own microblog.

## Areas for improvement

Unfortunately, the microblog you've completed through this tutorial is not yet
suitable for real use. In particular, there are many vulnerabilities in terms of
security, so it could be dangerous to actually use it.

For those who want to further develop the microblog you've created, you might
want to try solving the following challenges:

* Currently, there's no authentication, so anyone can post if they know
  the URL. How about adding a login process to prevent this?

* The current implementation directly outputs the HTML contained in the `Note`
  object received via ActivityPub. Therefore, a malicious ActivityPub server
  could send a `Create(Note)` activity containing HTML like
  `<script>while (true) alert('Gotcha!');</script>`. This is called an [XSS]
  vulnerability. How can we prevent such vulnerabilities?

* Let's try changing the name of the actor we created by executing
  the following SQL in the SQLite database:

  ```sql
  UPDATE actors SET name = 'Renamed' WHERE id = 1;
  ```

  When we change the actor's name like this, will the changed name be applied
  on other Mastodon servers? If not, what kind of activity should we send to
  apply the change?

* Let's try adding a profile picture to the actor. If you're wondering how to
  add a profile picture, try using the `fedify lookup` command to look up
  an actor that already has a profile picture.

* Try creating a post with an image attached on another Mastodon server.
  In the timeline we created, the image attached to the post isn't visible.
  How can we display the attached image?

* Let's make it possible to mention other actors within a post. What should
  we do to send a notification to the mentioned party? Use the *Activity Log*
  of [ActivityPub.Academy] to find a way.

[XSS]: https://en.wikipedia.org/wiki/Cross-site_scripting

---

---
url: /manual/debug.md
description: >-
  The @fedify/debugger package provides an embedded real-time debug dashboard
  for inspecting ActivityPub traces and activities in your federated server app.
---

# Debugging

*This API is available since Fedify 2.0.0.*

When developing a federated server app, it can be difficult to understand what
activities are being sent and received, and whether signatures are being
verified correctly.  The `@fedify/debugger` package provides an embedded
real-time debug dashboard that you can add to your app to inspect ActivityPub
traces and activities without leaving your browser.

## Installation

::: code-group

```bash [Deno]
deno add jsr:@fedify/debugger
```

```bash [npm]
npm install @fedify/debugger
```

```bash [pnpm]
pnpm add @fedify/debugger
```

```bash [Yarn]
yarn add @fedify/debugger
```

```bash [Bun]
bun add @fedify/debugger
```

:::

## Setup

The debugger works as a proxy that wraps your existing `Federation` object.
It intercepts HTTP requests matching a configurable path prefix and serves
the debug dashboard, while delegating everything else to the inner federation.

The simplest way to set it up is to call `createFederationDebugger()` with
your federation object:

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
  // ... other federation options
});

const federation = createFederationDebugger(innerFederation);
```

When called without an `exporter` option, `createFederationDebugger()`
automatically:

* Creates a `MemoryKvStore` and `FedifySpanExporter` for trace data storage
* Creates a `BasicTracerProvider` with a `SimpleSpanProcessor`
* Registers it as the global [OpenTelemetry] tracer provider
* Registers an `AsyncLocalStorageContextManager` as the global OpenTelemetry
  context manager (required for parent–child span propagation)
* Registers a `W3CTraceContextPropagator` as the global OpenTelemetry
  propagator (required for trace context to propagate across message queue
  boundaries)
* Configures [LogTape] to collect logs per trace (using `getConfig()` to
  merge with any existing configuration)

This means `createFederation()` will automatically use the tracer provider
without needing an explicit `tracerProvider` option, and logs emitted by
Fedify will be captured and displayed alongside traces in the dashboard.

The `federation` object returned by `createFederationDebugger()` is a drop-in
replacement for the original.  You can use it everywhere you would normally use
the inner federation object (e.g., passing it to framework integrations).

> \[!WARNING]
> The debug dashboard is intended for development use only.  It is strongly
> recommended to enable [authentication](#auth) if the dashboard is accessible
> over a network, as it exposes internal trace data.

[OpenTelemetry]: ./opentelemetry.md

[LogTape]: https://logtape.org/

## Configuration

The `createFederationDebugger()` function accepts the following options:

### `path`

The path prefix for the debug dashboard.  Defaults to `"/__debug__"`.
All dashboard routes are served under this prefix.

For example, if you set `path` to `"/_debug"`, the dashboard will be available
at `/_debug/` and traces at `/_debug/traces/:traceId`.

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
// ---cut-before---
const federation = createFederationDebugger(innerFederation, {
  path: "/_debug",
});
```

### `auth`

*Optional.*  Authentication configuration for the debug dashboard.  When
omitted, the dashboard is accessible without authentication.

The `auth` option accepts a discriminated union with three modes:

#### Password-only authentication

Shows a login form with a single password field.  You can provide a static
password string or an `authenticate()` callback:

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
// ---cut-before---
// Static password:
const federation = createFederationDebugger(innerFederation, {
  auth: {
    type: "password",
    password: Deno.env.get("DEBUG_PASSWORD")!,
  },
});
```

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
// ---cut-before---
// Callback:
const federation = createFederationDebugger(innerFederation, {
  auth: {
    type: "password",
    authenticate: (password) => password === "my-secret",
  },
});
```

#### Username + password authentication

Shows a login form with both username and password fields:

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
// ---cut-before---
// Static credentials:
const federation = createFederationDebugger(innerFederation, {
  auth: {
    type: "usernamePassword",
    username: "admin",
    password: Deno.env.get("DEBUG_PASSWORD")!,
  },
});
```

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
// ---cut-before---
// Callback:
const federation = createFederationDebugger(innerFederation, {
  auth: {
    type: "usernamePassword",
    authenticate: (username, password) =>
      username === "admin" && password === "secret",
  },
});
```

#### Request-based authentication

Authenticates based on the incoming `Request` object, without showing a login
form.  Useful for IP-based access control.  Rejected requests receive a 403
Forbidden response.

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
// ---cut-before---
const federation = createFederationDebugger(innerFederation, {
  auth: {
    type: "request",
    authenticate: (request) => {
      // Only allow requests from localhost
      const url = new URL(request.url);
      return url.hostname === "127.0.0.1" || url.hostname === "::1";
    },
  },
});
```

> \[!NOTE]
> Authentication only applies to the debug dashboard routes.  All other
> requests (e.g., ActivityPub endpoints) are passed through to the inner
> federation without any authentication check.

### `exporter`

*Optional.*  A `FedifySpanExporter` instance that the dashboard queries for
trace data.

When omitted (the recommended approach), the debugger automatically creates
an exporter and sets up OpenTelemetry tracing for you.

When provided, you are responsible for setting up the `BasicTracerProvider`
and passing it to `createFederation()`.  See the
[Advanced setup](#advanced-setup) section below.

### `kv`

*Required when `exporter` is provided.*  A `KvStore` instance used to persist
log records collected by the debug dashboard's LogTape sink.

When using the simplified overload (without `exporter`), the debugger
automatically creates a `MemoryKvStore` for log storage.

When using the advanced overload (with `exporter`), you must pass the same
`KvStore` instance so that log records written by worker processes are visible
in the web dashboard.

## Dashboard pages

Once set up, the debug dashboard is accessible at the configured path prefix
(default: `/__debug__/`).

### Traces list

The root page (`/__debug__/`) shows a list of all captured traces.  For each
trace, it displays:

* **Trace ID** (first 8 characters, linked to the detail page)
* **Activity types** present in the trace (e.g., Create, Follow, Like)
* **Activity count**
* **Timestamp**

![Traces list page of the debug dashboard](/assets/traces-list.pXTVBGmU.png)

The page automatically polls the JSON API every 3 seconds and refreshes when
new traces are detected.

### Trace detail

The trace detail page (`/__debug__/traces/:traceId`) shows all activities
belonging to a specific trace.  For each activity, it displays:

* **Direction** (inbound or outbound)
* **Activity type** (e.g., Create, Accept, Follow)
* **Span ID** and optional parent span ID
* **Activity ID** (if present)
* **Actor ID**
* **Timestamp**
* **Inbox URL** (for outbound activities)
* **Signature verification** details (for inbound activities):
  * Whether HTTP Signatures were verified
  * The key ID used for verification
  * Whether Linked Data Signatures were verified
* **Activity JSON** (expandable, pretty-printed)

Below the activities section, a **Logs** section shows all [LogTape] log
records captured during the trace.  Each log entry displays:

* **Timestamp** (time portion only)
* **Log level** (color-coded: debug, info, warning, error, fatal)
* **Logger category** (e.g., `fedify.federation.http`)
* **Message** with expandable properties

![Trace detail page of the debug dashboard](/assets/trace-detail.DvdfVFv_.png)

### JSON API

A JSON API endpoint is available at `/__debug__/api/traces` which returns
the list of recent traces in JSON format.  This is used by the auto-polling
mechanism on the traces list page, but you can also query it directly for
programmatic access.

A separate endpoint at `/__debug__/api/logs/:traceId` returns the log records
for a specific trace in JSON format.

## Using with framework integrations

The debugger works with any framework integration that accepts a `Federation`
object.  Simply wrap the federation before passing it to your integration:

### Hono

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";
import { federation as honoFederation } from "@fedify/hono";
import { Hono } from "hono";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
const federation = createFederationDebugger(innerFederation);

const app = new Hono();
app.use(honoFederation(federation, (_) => undefined));
```

### Express

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { createFederationDebugger } from "@fedify/debugger";
import { integrateFederation } from "@fedify/express";
import express from "express";

const innerFederation = createFederation<void>({
  kv: new MemoryKvStore(),
});
const federation = createFederationDebugger(innerFederation);

const app = express();
app.use(integrateFederation(federation, (req) => undefined));
```

## Advanced setup

If you need full control over the OpenTelemetry setup (for example, to use
a custom `KvStore` or to add additional span processors), you can pass an
explicit `exporter` option:

```typescript twoslash
// @noErrors: 2345
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { FedifySpanExporter } from "@fedify/fedify/otel";
import { createFederationDebugger } from "@fedify/debugger";
import { context, propagation } from "@opentelemetry/api";
import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
import { W3CTraceContextPropagator } from "@opentelemetry/core";
import {
  BasicTracerProvider,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";

// Register context manager and propagator (required for trace
// propagation across async boundaries and message queues):
context.setGlobalContextManager(new AsyncLocalStorageContextManager());
propagation.setGlobalPropagator(new W3CTraceContextPropagator());

// Create a KV store and a span exporter that captures trace data:
const kv = new MemoryKvStore();
const exporter = new FedifySpanExporter(kv);
const tracerProvider = new BasicTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(exporter)],
});

const innerFederation = createFederation({
  kv,
  tracerProvider,
  // ... other federation options
});

// Wrap the federation with the debugger:
const federation = createFederationDebugger(innerFederation, {
  exporter,
  kv,
});
```

In this mode, the returned `federation` object has a `sink` property that is
a [LogTape] `Sink` function.  You should include it in your LogTape
configuration to enable per-trace log collection:

```typescript twoslash
// @noErrors: 2345
import { configure } from "@logtape/logtape";
declare const federation: { sink: (record: any) => void };
// ---cut-before---
await configure({
  sinks: {
    debugger: federation.sink,
    // ... other sinks
  },
  loggers: [
    { category: "fedify", sinks: ["debugger"] },
    // ... other loggers
  ],
});
```

In this mode, you are responsible for:

* Registering an `AsyncLocalStorageContextManager` as the global context
  manager
* Registering a `W3CTraceContextPropagator` as the global propagator
* Creating and configuring the `BasicTracerProvider`
* Passing `tracerProvider` to `createFederation()`
* Passing the same `exporter` and `kv` to `createFederationDebugger()`
* Configuring LogTape with `federation.sink` to collect logs per trace

---

---
url: /manual/deploy.md
description: >-
  This document explains how to deploy Fedify applications to various platforms
  and runtime environments, with specific guidance for serverless platforms that
  have unique architectural constraints.
---

# Deployment

Fedify applications can be deployed to various platforms and runtime
environments.  While the core development patterns remain consistent across
platforms, some deployment targets—particularly serverless environments—require
specific architectural considerations and configuration patterns.

This document covers deployment-specific concerns that go beyond basic
application development, focusing on platform-specific requirements,
configuration patterns, and operational considerations.

## General deployment considerations

### Environment configuration

Fedify applications typically require several environment-specific
configurations that should be managed through environment variables or secure
configuration systems:

Domain configuration
:   Set your canonical domain through
the [`origin`](./federation.md#explicitly-setting-the-canonical-origin)
option or ensure proper `Host` header handling.

Database connections
:   Configure your chosen [key–value store](./kv.md) and
[message queue](./mq.md) implementations.

Cryptographic keys
:   Securely manage actor key pairs outside your application code.

### Observability

Fedify provides comprehensive observability features that should be configured
for production deployments:

Logging
:   [Configure loggers](./log.md) with appropriate log levels and sinks (output
destinations) for your environment.

Tracing
:   Enable [OpenTelemetry](./opentelemetry.md) integration to trace ActivityPub
operations across your infrastructure.

Monitoring
:   Set up monitoring for queue depths, delivery success rates, and response
times to ensure your application is performing optimally.

### Scaling considerations

ActivityPub applications have unique scaling characteristics due to their
federated nature.  Consider the following when deploying:

Message processing
:   [Consider separating web traffic from background message
processing](./mq.md#separating-message-processing-from-the-main-process)
for better resource utilization.

Database performance
:   Optimize your [key–value store](./kv.md) and [message queue](./mq.md) for
the expected load patterns, including read/write ratios and concurrency.

## Traditional server environments

While Fedify works seamlessly with traditional server deployments on Node.js,
Bun, and Deno, each runtime has specific considerations for production use.

### Node.js

Node.js does not provide a built-in HTTP server that accepts `fetch()`-style
handlers, so you will need an adapter.  The [@hono/node-server] package provides
this functionality:

```typescript twoslash
import { MemoryKvStore } from "@fedify/fedify";
// ---cut-before---
import { serve } from "@hono/node-server";
import { createFederation } from "@fedify/fedify";

const federation = createFederation<void>({
// ---cut-start---
  kv: new MemoryKvStore(),
// ---cut-end---
  // Configuration...
});

serve({
  async fetch(request) {
    return await federation.fetch(request, { contextData: undefined });
  },
});
```

For production deployments, consider using process managers like [PM2] or
[systemd] to ensure reliability and automatic restarts.

[@hono/node-server]: https://github.com/honojs/node-server

[PM2]: https://pm2.keymetrics.io/

[systemd]: https://systemd.io/

### Bun and Deno

Both Bun and Deno provide built-in HTTP servers with `fetch()`-style handlers,
making integration straightforward:

```typescript twoslash [index.ts]
import { MemoryKvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";

const federation = createFederation<void>({
// ---cut-start---
  kv: new MemoryKvStore(),
// ---cut-end---
  // Configuration...
});

export default {
  async fetch(request: Request): Promise<Response> {
    return await federation.fetch(request, { contextData: undefined });
  },
};
```

Then, you can run your application using the built-in server commands:

::: code-group

```bash [Deno]
deno serve index.ts
```

```bash [Bun]
bun run index.ts
```

:::

> \[!TIP]
>
> See also the documentation for [`deno serve`] and
> [Bun's `export default` syntax].

[`deno serve`]: https://docs.deno.com/runtime/reference/cli/serve/

[Bun's `export default` syntax]: https://bun.sh/docs/api/http#export-default-syntax

### Key–value store and message queue

For traditional server environments, choose persistent storage solutions based
on your infrastructure:

Development
:   Use [`MemoryKvStore`](./kv.md#memorykvstore) and
[`InProcessMessageQueue`](./mq.md#inprocessmessagequeu) for quick setup.

Production
:   Consider [`PostgresKvStore`](./kv.md#postgreskvstore) and
[`PostgresMessageQueue`](./mq.md#postgresmessagequeue) if you already use
PostgreSQL, [`MysqlKvStore`](./kv.md#mysqlkvstore) and
[`MysqlMessageQueue`](./mq.md#mysqlmessagequeue) if you already use
MySQL or MariaDB, or [`RedisKvStore`](./kv.md#rediskvstore) and
[`RedisMessageQueue`](./mq.md#redismessagequeue) for dedicated caching
infrastructure. There is also [`AmqpMessageQueue`](./mq.md#amqpmessagequeue)
for RabbitMQ users.

### Key management

In traditional server environments, actor key pairs should be generated once
during user registration and securely stored in your database.  Avoid generating
keys on every server restart—this will break federation with other servers that
have cached your public keys.

### Web frameworks

For web framework integration patterns,
see the [*Integration* section](./integration.md), which covers Express, Hono,
Fresh, SvelteKit, and other popular frameworks.

## Cloudflare Workers

*Cloudflare Workers support is available in Fedify 1.6.0 and later.*

[Cloudflare Workers] presents a unique deployment environment with specific
constraints and architectural requirements.  Unlike traditional server
environments, Workers operate within strict execution time limits and provide
access to platform services through binding mechanisms rather than global
imports.

[Cloudflare Workers]: https://workers.cloudflare.com/

### Node.js compatibility

Fedify requires [Node.js compatibility flag] to function properly on Cloudflare
Workers.  Add the following to your *wrangler.jsonc* configuration file:

```jsonc
"compatibility_date": "2025-05-31",
"compatibility_flags": ["nodejs_compat"],
```

This enables essential Node.js APIs that Fedify depends on, including
cryptographic functions and DNS resolution.

[Node.js compatibility flag]: https://developers.cloudflare.com/workers/runtime-apis/nodejs/

### Builder pattern

Unlike other environments where you can initialize a `Federation` object
globally, Workers only provide access to bindings (KV, Queues, etc.) through
`env` parameter in request handlers.  This makes the [builder
pattern](./federation.md#builder-pattern-for-structuring) mandatory:

```typescript twoslash
// @noErrors: 2345
type Env = {
  KV_NAMESPACE: KVNamespace<string>;
  QUEUE: Queue;
};
import { Person } from "@fedify/vocab";
// ---cut-before---
import { createFederationBuilder } from "@fedify/fedify";
import { WorkersKvStore, WorkersMessageQueue } from "@fedify/cfworkers";

const builder = createFederationBuilder<Env>();

// Configure your federation using the builder
builder.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  // Your actor logic here
// ---cut-start---
  return new Person({});
// ---cut-end---
});

// Export the default handler
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const federation = await builder.build({
      kv: new WorkersKvStore(env.KV_NAMESPACE),
      queue: new WorkersMessageQueue(env.QUEUE),
      // Other options...
    });

    return federation.fetch(request, { contextData: env });
  },
};
```

### Manual queue processing

Cloudflare Queues don't provide polling-based APIs, so the `WorkersMessageQueue`
cannot implement a traditional `~MessageQueue.listen()` method.  Instead, you
must manually connect queue handlers:

```typescript twoslash
// @noErrors: 2345
import { createFederationBuilder, type Message } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
import { WorkersKvStore, WorkersMessageQueue } from "@fedify/cfworkers";

type Env = {
  KV_NAMESPACE: KVNamespace<string>;
  QUEUE: Queue;
};

const builder = createFederationBuilder<Env>();
// ---cut-before---
// Handle queue messages
export default {
  // ... fetch handler above

  async queue(batch: MessageBatch<unknown>, env: Env): Promise<void> {
    const federation = await builder.build({
      kv: new WorkersKvStore(env.KV_NAMESPACE),
      queue: new WorkersMessageQueue(env.QUEUE),
    });

    for (const message of batch.messages) {
      try {
        await federation.processQueuedTask(
          message.body as unknown as Message,
          env,
        );
        message.ack();
      } catch (error) {
        message.retry();
      }
    }
  },
};
```

### Example deployment

For a complete working example, see the [Cloudflare Workers example]
in the Fedify repository, which demonstrates a simple functional ActivityPub
server deployed to Cloudflare Workers.

[Cloudflare Workers example]: https://github.com/fedify-dev/fedify/tree/main/examples/cloudflare-workers

## Deno Deploy

[Deno Deploy] is a serverless platform optimized for Deno applications, offering
global distribution and built-in persistence through Deno KV.  Fedify provides
first-class support for Deno Deploy through [dedicated key–value
store](./kv.md#denokvstore-deno-only) and [message
queue](./mq.md#denokvmessagequeue-deno-only) implementations.

Deno Deploy applications can use Deno KV and leverage it for message queueing
as well:

```typescript
import { createFederation } from "@fedify/fedify";
import { DenoKvStore, DenoKvMessageQueue } from "@fedify/denokv";

// Open Deno KV (automatically available on Deno Deploy)
const kv = await Deno.openKv();

const federation = createFederation<void>({
  kv: new DenoKvStore(kv),
  queue: new DenoKvMessageQueue(kv),
  // Other configuration...
});

// Standard Deno Deploy handler
Deno.serve((request) => federation.fetch(request, { contextData: undefined }));
```

[Deno Deploy]: https://deno.com/deploy

## Other platforms

Support for additional serverless platforms is planned for future releases.
Each platform may have similar architectural requirements to Cloudflare Workers,
particularly around resource binding and execution constraints.

If you are interested in support for a specific platform, please [open an issue]
to discuss requirements and implementation approaches.

[open an issue]: https://github.com/fedify-dev/fedify/issues

---

---
url: /manual/federation.md
description: >-
  The Federation object is the main entry point of the Fedify library. This
  section explains the key features of the Federation object.
---

# Federation

The `Federation` object is the main entry point of the Fedify library.
It provides a set of methods to configure and run the federated server.
The key features of the `Federation` object are as follows:

* Registering an [actor dispatcher](./actor.md)
* Registering [inbox listeners](./inbox.md)
* Registering [collections](./collections.md)
* Registering [object dispatchers](./object.md)
* Creating a `Context` object
* Maintaining a queue of [outgoing activities](./send.md)
* Registering a [NodeInfo dispatcher](./nodeinfo.md)

You can create a `Federation` object by calling `createFederation()` function
with a configuration object:

```typescript twoslash
import { createFederation, MemoryKvStore } from "@fedify/fedify";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
  // Omitted for brevity; see the following sections for details.
});
```

## Constructor parameters

The `createFederation()` function takes an object with the following
properties.  Some of them are required:

### `kv`

*Required.*  The `~FederationOptions.kv` property is a `KvStore` instance
that the `Federation` object uses to store several kinds of cache data and
to maintain the queue of outgoing activities.

`KvStore` is an abstract interface that represents a key–value store.
For now, Fedify provides two built-in implementations of `KvStore`, which are
`MemoryKvStore` and `DenoKvStore` classes.  The `MemoryKvStore` class is for
testing and development purposes, and the `DenoKvStore` class is Deno KV-backed
implementation for production use (as you can guess from the name, it is only
available in Deno runtime).

As separate packages, [`@fedify/redis`] provides [`RedisKvStore`] class, which
is a Redis-backed implementation for production use, [`@fedify/postgres`]
provides [`PostgresKvStore`] class, which is a PostgreSQL-backed implementation
for production use, and [`@fedify/mysql`] provides [`MysqlKvStore`] class, which
is a MySQL/MariaDB-backed implementation for production use.

Further details are explained in the [*Key–value store* section](./kv.md).

[`@fedify/redis`]: https://github.com/fedify-dev/fedify/tree/main/packages/redis

[`RedisKvStore`]: https://jsr.io/@fedify/redis/doc/kv/~/RedisKvStore

[`@fedify/postgres`]: https://github.com/fedify-dev/fedify/tree/main/packages/postgres

[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore

[`@fedify/mysql`]: https://github.com/fedify-dev/fedify/tree/main/packages/mysql

[`MysqlKvStore`]: https://jsr.io/@fedify/mysql/doc/kv/~/MysqlKvStore

### `kvPrefixes`

The `~FederationOptions.kvPrefixes` property is an object that contains
the key prefixes for the cache data.  The following are the key prefixes
that the `Federation` object uses:

`~FederationKvPrefixes.activityIdempotence`
:   The key prefix used for storing whether activities have already been
processed or not.  `["_fedify", "activityIdempotence"]` by default.

`~FederationKvPrefixes.remoteDocument`
:   The key prefix used for storing remote JSON-LD documents.
`["_fedify", "remoteDocument"]` by default.

`~FederationKvPrefixes.publicKey`
:   *This API is available since Fedify 0.12.0.*

```
The key prefix used for caching public keys.  `["_fedify", "publicKey"]`
by default.
```

`~FederationKvPrefixes.httpMessageSignaturesSpec`
:   *This API is available since Fedify 1.6.0.*

```
The key prefix used for caching HTTP Message Signatures spec.  The cached
spec is used to reduce the number of attempts to make signed requests
([double-knocking] technique).
`["_fedify", "httpMessageSignaturesSpec"]` by default.
```

[double-knocking]: https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions

### `queue`

*This API is available since Fedify 0.5.0.*

The `~FederationOptions.queue` property is a `MessageQueue` instance that
the `Federation` object uses to maintain the queue of incoming and outgoing
activities.  If you don't provide this option, activities will not be queued
and will be processed immediately.

`MessageQueue` is an abstract interface that represents a message queue.
For now, Fedify provides two built-in implementations of `MessageQueue`, which
are `InProcessMessageQueue` and `DenoKvMessageQueue` classes.
The `InProcessMessageQueue` class is for testing and development purposes,
and the `DenoKvMessageQueue` class is a Deno KV-backed implementation for
production use (as you can guess from the name, it is only available in Deno
runtime).

As separate packages, [`@fedify/redis`] provides [`RedisMessageQueue`] class,
which is a Redis-backed implementation for production use,
[`@fedify/postgres`] provides [`PostgresMessageQueue`] class, which is a
PostgreSQL-backed implementation for production use,
[`@fedify/mysql`] provides [`MysqlMessageQueue`] class, which is a
MySQL/MariaDB-backed implementation for production use, and [`@fedify/amqp`]
provides [`AmqpMessageQueue`] class, which is an AMQP broker-backed
implementation for production use.

Further details are explained in the [*Message queue* section](./mq.md).

> \[!IMPORTANT]
> While the `queue` option is optional, it is highly recommended to provide
> a message queue implementation in production environments.  If you don't
> provide a message queue implementation, activities will not be queued and
> will be sent immediately.  This can make delivery of activities unreliable
> and can cause performance issues.

> \[!TIP]
> Since Fedify 1.3.0, you can separately configure the message queue for
> incoming and outgoing activities by providing an object with `inbox` and
> `outbox` properties:
>
> ```typescript twoslash
> import {
>   createFederation,
>   type KvStore,
>   MemoryKvStore,
>   type MessageQueue,
> } from "@fedify/fedify";
> import { PostgresMessageQueue } from "@fedify/postgres";
> import { RedisMessageQueue } from "@fedify/redis";
> import postgres from "postgres";
> import Redis from "ioredis";
>
> createFederation<void>({
> kv: null as unknown as KvStore,
> // ---cut-before---
> queue: {
>   inbox: new PostgresMessageQueue(
>     postgres("postgresql://user:pass@localhost/db")
>   ),
>   outbox: new RedisMessageQueue(() => new Redis()),
> }
> // ---cut-after---
> });
> ```
>
> Or, you can provide a message queue for only the `inbox` or `outbox` by
> omitting the other:
>
> ```typescript twoslash
> import {
>   createFederation,
>   type KvStore,
>   MemoryKvStore,
>   type MessageQueue,
> } from "@fedify/fedify";
> import { PostgresMessageQueue } from "@fedify/postgres";
> import postgres from "postgres";
>
> createFederation<void>({
> kv: null as unknown as KvStore,
> // ---cut-before---
> queue: {
>   inbox: new PostgresMessageQueue(
>     postgres("postgresql://user:pass@localhost/db")
>   ),
>   // outbox is not provided; outgoing activities will not be queued.
> }
> // ---cut-after---
> });
> ```

[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/mq/~/PostgresMessageQueue

[`MysqlMessageQueue`]: https://jsr.io/@fedify/mysql/doc/mq/~/MysqlMessageQueue

[`@fedify/amqp`]: https://github.com/fedify-dev/fedify/tree/main/packages/amqp

[`AmqpMessageQueue`]: https://jsr.io/@fedify/amqp/doc/mq/~/AmqpMessageQueue

### `manuallyStartQueue`

*This API is available since Fedify 0.12.0.*

Whether to start the task queue manually or automatically.

If `true`, the task queue will not start automatically and you need to
manually start it by calling the `Federation.startQueue()` method.

If `false`, the task queue will start automatically as soon as the first
task is enqueued.

By default, the queue starts automatically.

> \[!TIP]
> This option is useful when you want to separately deploy the web server
> and the task queue worker.  In this case, you can start the task queue
> in the worker process, and the web server process doesn't start the task
> queue, but only enqueues tasks.  Of course, in this case, you need to
> provide a `MessageQueue` backend that can be shared between the web server
> and the worker process (e.g., a Redis-backed message queue) as
> the [`queue`](#queue) option.

### `documentLoaderFactory`

*This API is available since Fedify 1.4.0.*

A factory function that creates a JSON-LD `DocumentLoader` that the `Federation`
object uses to load remote JSON-LD documents.  The factory function takes
a `DocumentLoaderFactoryOptions` object and returns a `DocumentLoader`
function.

Usually, you don't need to set this property because the default document
loader is sufficient for most cases.  The default document loader
caches the loaded documents in the key–value store.

See the
[*Getting a `DocumentLoader`* section](./context.md#getting-a-documentloader)
for details.

### `authenticatedDocumentLoaderFactory`

*This API is available since Fedify 0.4.0.*

A factory function that creates an authenticated document loader function.
The factory function takes the key pair of an actor and returns a document
loader function that loads remote JSON-LD documents as the actor.

Usually, you don't need to set this property because the default document
loader factory is sufficient for most cases.  The default document loader
factory intentionally doesn't cache the loaded documents in the key–value
store.

See the [*Getting an authenticated `DocumentLoader`*
section](./context.md#getting-an-authenticated-documentloader) for details.

### `contextLoaderFactory`

*This API is available since Fedify 1.4.0.*

A factory function to get a JSON-LD context loader that the `Federation`
object uses to load remote JSON-LD contexts.  The type of the factory is
the same as the `documentLoaderFactory`, but their purposes are different
(see also [*Document loader vs. context loader*
section](./context.md#document-loader-vs-context-loader)).

### `allowPrivateAddress`

*This API is available since Fedify 0.15.0.*

> \[!WARNING]
> Do not turn on this option in production environments.  Disallowing fetching
> private network addresses is a security feature to prevent [SSRF] attacks.

Whether to allow fetching private network addresses in the document loader.

Mostly useful for testing purposes.

Turned off by default.

[SSRF]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery

### `userAgent`

*This API is available since Fedify 1.3.0.*

The options for making `User-Agent` header in the HTTP requests that Fedify
makes.  By default, it contains the name and version of the Fedify library,
and the name and version of the JavaScript runtime, e.g.:

```
Fedify/1.3.0 (Deno/2.0.4)
Fedify/1.3.0 (Node.js/v22.10.0)
Fedify/1.3.0 (Bun/1.1.33)
```

You can customize the `User-Agent` header by providing options like `software`
and `url`.  For example, if you provide the following options:

```ts
{
  software: "MyApp/1.0.0",
  url: "https://myinstance.com/"
}
```

The `User-Agent` header will be like:

```
MyApp/1.0.0 (Fedify/1.3.0; Deno/2.0.4; +https://myinstance.com/)
```

Or, you can rather provide a custom `User-Agent` string directly instead of
an object for options.

> \[!CAUTION]
>
> This settings do not affect the `User-Agent` header of the HTTP requests
> that `lookupWebFinger()`, `lookupObject()`, and `getNodeInfo()` functions
> make, since they do not depend on the `Federation` object.
>
> However, `Context.lookupObject()` method is affected by this settings.

### `firstKnock`

*This API is available since Fedify 1.7.0.*

The HTTP Signatures specification to use for the first signature attempt
when communicating with unknown servers. This option affects the
[double-knocking] mechanism.

When making HTTP requests to servers that haven't been encountered before,
Fedify will first attempt to sign the request using the specified
signature specification. If the request fails, it will retry with the
alternative specification.

Available options are:

`"draft-cavage-http-signatures-12"`
:   [HTTP Signatures], which is obsolete but still widely adopted in
the fediverse as of May 2025.

`"rfc9421"` (default)
:   [RFC 9421]: HTTP Message Signatures, which is the final revision of
the specification and is recommended, but not yet widely adopted
in the fediverse as of May 2025.

Defaults to `"rfc9421"`.

[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421

### `permanentFailureStatusCodes`

*This API is available since Fedify 2.0.0.*

HTTP status codes that should be treated as permanent delivery failures.
When an inbox returns one of these codes, the delivery will not be retried
and the permanent failure handler (if registered via
`~Federatable.setOutboxPermanentFailureHandler()`) will be called.

By default, `[404, 410]`.

```typescript twoslash
// @noErrors: 2345
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
  queue: new InProcessMessageQueue(),
  permanentFailureStatusCodes: [404, 410, 451],
});
```

See also the
[*Permanent delivery failure handling*](./send.md#permanent-delivery-failure-handling)
section in the *Sending activities* page for how to register a handler for
permanent delivery failures.

### `outboxRetryPolicy`

*This API is available since Fedify 0.12.0.*

The retry policy for sending activities to recipients' inboxes.

By default, this uses an exponential backoff strategy with a maximum of 10
attempts and a maximum delay of 12 hours.

You can fully customize the retry policy by providing a custom function that
satisfies the `RetryPolicy` type.  Or you can adjust the parameters of
the `createExponentialBackoffRetryPolicy()` function, which is a default
implementation of the retry policy.

> \[!NOTE]
> This policy is ignored when using message queue backends that provide native
> retry mechanisms (`MessageQueue.nativeRetrial` is `true`).  In such cases,
> the backend's native retry logic takes precedence.

### `inboxRetryPolicy`

*This API is available since Fedify 0.12.0.*

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.

In the same way as the `outboxRetryPolicy` option, you can fully customize
the retry policy by providing a custom function that satisfies the `RetryPolicy`
type.  Or you can adjust the parameters of the built-in
`createExponentialBackoffRetryPolicy()` function.

> \[!NOTE]
> This policy is ignored when using message queue backends that provide native
> retry mechanisms (`MessageQueue.nativeRetrial` is `true`).  In such cases,
> the backend's native retry logic takes precedence.

### `activityTransformers`

*This API is available since Fedify 1.4.0.*

Activity transformers are a way to adjust activities before sending them to
the recipients.  It is useful for modifying the activity to fit the recipient's
ActivityPub implementation (which may have some quirks) or for adding some
additional information to the activity.

See the [*Activity transformers* section](./send.md#activity-transformers)
for details.

### `trailingSlashInsensitive`

*This API is available since Fedify 0.12.0.*

Whether the router should be insensitive to trailing slashes in the URL paths.
For example, if this option is `true`, `/foo` and `/foo/` are treated as the
same path.

Turned off by default.

### `tracerProvider`

*This API is available since Fedify 1.3.0.*

The OpenTelemetry tracer provider that the `Federation` object uses to
instrument various parts of Fedify for tracing.  If omitted, it is configured
to use the default tracer provider (i.e., [`trace.getTracerProvider()`]).

For more information, see the [*OpenTelemetry* section](./opentelemetry.md).

[`trace.getTracerProvider()`]: https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api._opentelemetry_api.TraceAPI.html#gettracerprovider

## Builder pattern for structuring

*This API is available since Fedify 1.6.0.*

If your federated application is large enough, you may want to defer the
instantiation of the `Federation` object until all your dispatchers and
listeners are set up.  This is useful for structuring your code and
avoiding circular dependencies.  Here's a brief instruction on how to
do that:

1. Instead of instantiating a `Federation` object using `createFederation()`
   function, create a `FederationBuilder` object using
   `createFederationBuilder()` function.
2. Register your dispatchers and listeners to the `FederationBuilder`
   object as you would do with a regular `Federation` object.
3. Call the `FederationBuilder.build()` method to create a `Federation`
   object.  This method takes the same options as `createFederation()`
   function, and it returns a `Federation` object.

It looks like this:

```typescript [federation.ts]
import { createFederationBuilder } from "@fedify/fedify";

export const builder = createFederationBuilder<void>();

// Register your dispatchers and listeners here...
builder.setActorDispatcher(
  "/users/{identifier}",
  async (ctx, identifier) => {
    // Omitted for brevity
  }
);
// ...
```

```typescript [main.ts]
import { builder } from "./federation.ts";

// Build the `Federation` object
export const federation = await builder.build({
  kv: new MemoryKvStore(),
  // Omitted for brevity; see the following sections for details.
});
```

If you want to access the `Federation` object inside dispatchers or listeners
before the `FederationBuilder` instantiates it, you can use
the `Context.federation` property.  The `Context.federation` property refers
to the `Federation` object that is to be instantiated by the `FederationBuilder`
and is available in the `Context` object passed to the dispatchers and
listeners.  For example, you can access the `Federation` object like this:

```typescript twoslash
import { type FederationBuilder } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const builder = null as unknown as FederationBuilder<void>;
// ---cut-before---
builder.setActorDispatcher(
  "/users/{identifier}",
  async (ctx, identifier) => {
    const federation = ctx.federation; // Access the `Federation` object
    // Omitted for brevity
// ---cut-start---
    return new Person({});
// ---cut-end---
  }
);
```

## The `~Federation.fetch()` API

*This API is available since Fedify 0.6.0.*

The `Federation` object provides the `~Federation.fetch()` method to handle
incoming HTTP requests.  The `~Federation.fetch()` method takes an incoming
[`Request`] and returns a [`Response`].

Actually, this interface is de facto standard in the server-side JavaScript
world, and it is inspired by the [`window.fetch()`] method in the browser
environment.

Therefore, you can pass it to the [`Deno.serve()`] function in [Deno], and
the [`Bun.serve()`] function in [Bun]:

::: code-group

```typescript twoslash [Deno]
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
const request = new Request("");
// ---cut-before---
Deno.serve(
  (request) => federation.fetch(request, { contextData: undefined })
);
```

```typescript twoslash [Bun]
import "@types/bun";
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
const request = new Request("");
// ---cut-before---
Bun.serve({
  fetch: (request) => federation.fetch(request, { contextData: undefined }),
})
```

:::

However, in case of [Node.js], it has no built-in server API that takes
`fetch()` callback function like Deno or Bun.  Instead, you need to use
[@hono/node-server] package to adapt the `~Federation.fetch()` method to
the Node.js' HTTP server API:

::: code-group

```sh [Node.js]
npm add @hono/node-server
```

:::

And then, you can use the [`serve()`] function from the package:

::: code-group

```typescript twoslash [Node.js]
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
const request = new Request("");
// ---cut-before---
import { serve } from "@hono/node-server";

serve({
  fetch: (request) => federation.fetch(request, { contextData: undefined }),
})
```

:::

> \[!NOTE]
>
> Although a `Federation` object can be directly passed to the HTTP server
> APIs, you would usually integrate it with a web framework.  For details,
> see the [*Integration* section](./integration.md).

[`Request`]: https://developer.mozilla.org/en-US/docs/Web/API/Request

[`Response`]: https://developer.mozilla.org/en-US/docs/Web/API/Response

[`window.fetch()`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch

[`Deno.serve()`]: https://docs.deno.com/api/deno/~/Deno.serve

[Deno]: http://deno.com/

[`Bun.serve()`]: https://bun.sh/docs/api/http#bun-serve

[Bun]: https://bun.sh/

[Node.js]: https://nodejs.org/

[@hono/node-server]: https://github.com/honojs/node-server

[`serve()`]: https://github.com/honojs/node-server?tab=readme-ov-file#usage

## How the `Federation` object recognizes the domain name

By default, the `Federation` object recognizes the domain name of the server by
the [`Host`] header of the incoming HTTP requests.  The `Host` header is
a standard HTTP header that contains the domain name of the server.

However, the `Host` header is not always reliable because it can be
bypassed by a reverse proxy or a load balancer.  If you use a reverse
proxy or a load balancer, you should configure it to pass the original
`Host` header to the server.

Or you can make the `Federation` object recognize the domain name by looking
at the [`X-Forwarded-Host`] header instead of the `Host` header using
the [x-forwarded-fetch] middleware.  To use the `x-forwarded-fetch` middleware,
install the package:

::: code-group

```sh [Deno]
deno add jsr:@hongminhee/x-forwarded-fetch
```

```sh [Node.js]
npm install x-forwarded-fetch
```

```sh [Bun]
bun add x-forwarded-fetch
```

:::

Then, import the package and place the `behindProxy()` middleware in front of
the `Federation.fetch()` method:

::: code-group

```typescript{1,4} twoslash [Deno]
// @noErrors: 2300 2307
import { behindProxy } from "x-forwarded-fetch";
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { behindProxy } from "@hongminhee/x-forwarded-fetch";

Deno.serve(
  behindProxy(request => federation.fetch(request, { contextData: undefined }))
);
```

```typescript{2,5} twoslash [Node.js]
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { serve } from "@hono/node-server";
import { behindProxy } from "x-forwarded-fetch";

serve({
  fetch: behindProxy((request) => federation.fetch(request, { contextData: undefined })),
});
```

```typescript{1,4} twoslash [Bun]
import "@types/bun";
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { behindProxy } from "x-forwarded-fetch";

Bun.serve({
  fetch: behindProxy((request) => federation.fetch(request, { contextData: undefined })),
});
```

:::

> \[!TIP]
> When your `Federation` object is integrated with a web framework, you should
> place the `behindProxy()` middleware in front of the framework's `fetch()`
> method, not the `Federation.fetch()` method.

[`Host`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host

[`X-Forwarded-Host`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host

[x-forwarded-fetch]: https://github.com/dahlia/x-forwarded-fetch

## Explicitly setting the canonical origin

*This API is available since Fedify 1.5.0.*

Or you can explicitly set the canonical origin of the server by passing
the `~FederationOptions.origin` option to the `createFederation()`
function.  The `~FederationOptions.origin` option is either a string or
a `FederationOrigin` object, which consists of two fields:
`~FederationOrigin.handleHost` and `~FederationOrigin.webOrigin`.

For example, if you want to set the canonical origin to `https://example.com`,
you can pass the string:

```typescript twoslash
import { createFederation, type KvStore } from "@fedify/fedify";
// ---cut-before---
const federation = createFederation({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  origin: "https://example.com",
});
```

> \[!NOTE]
> The `~FederationOptions.origin` option has to include the leading
> `https://` or `http://` scheme.

Such a configuration leads the [constructed URLs using
`Context`](./context.md#building-the-object-uris) to use the canonical origin
instead of the origin from the incoming HTTP requests, which avoids constructing
unexpected URLs when a request bypasses a reverse proxy or a load balancer.

> \[!CAUTION]
> For example, suppose that your federated server (upstream) is accessible at
> the `http://1.2.3.4:8000` and your load balancer (downstream) is accessible at
> the `https://example.com` and forwards the requests to the upstream server.
> In this case, you should set the canonical origin to `https://example.com` to
> construct the correct URLs.  Otherwise, when some malicious actor directly
> sends a request to the upstream server, the constructed URLs will start with
> `http://1.2.3.4:8000` instead of `https://example.com`, which can lead to
> security issues.

> \[!TIP]
> If your federated server needs to support [multiple domains on the same
> server](#virtual-hosting), you would not want to set the canonical origin
> explicitly.  Instead, you should rely on the [`Host`] header or
> [`X-Forwarded-Host`] header to determine the domain name.

## Separating WebFinger host from the server origin

*This API is available since Fedify 1.5.0.*

Sometimes you may want to use different domain names for WebFinger handles
(i.e., fediverse handles) and the server origin.  For example, you may want
to use `https://ap.example.com/actors/alice` as an actor URI but want to use
`@alice@example.com` as its fediverse handle.

In such cases, you can set the `~FederationOrigin.handleHost` different from
the `~FederationOrigin.webOrigin` in the `~FederationOptions.origin`
option.  The `~FederationOrigin.handleHost` is used to construct the WebFinger
handles, and the `~FederationOrigin.webOrigin` is used to [construct the URLs
in the `Context` object](./context.md#building-the-object-uris):

```typescript twoslash
import { createFederation, type KvStore } from "@fedify/fedify";
// ---cut-before---
const federation = createFederation({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  origin: {
    handleHost: "example.com",
    webOrigin: "https://ap.example.com",
  },
});
```

That is not all.  You also need to make the */.well-known/webfinger* endpoint
of the `~FederationOrigin.handleHost` to redirect to the
*/.well-known/webfinger* endpoint of the `~FederationOrigin.webOrigin` unless
you want to connect the `~FederationOrigin.handleHost` to the same server as
the `~FederationOrigin.webOrigin`.  For example, if your
`~FederationOrigin.handleHost` is served by [Caddy], you can use the following
configuration to redirect the WebFinger requests:

```caddy
example.com {
  redir /.well-known/webfinger https://ap.example.com/.well-known/webfinger
}
```

Or if you use [nginx], you can use the following configuration:

```nginx
server {
  server_name example.com;
  location /.well-known/webfinger {
    return 301 https://ap.example.com$request_uri;
  }
}
```

> \[!NOTE]
> Even if you set the `~FederationOrigin.handleHost` different from the
> `~FederationOrigin.webOrigin`, the other fediverse handle with the same
> domain name as the `~FederationOrigin.webOrigin` will still be recognized.
>
> In the above example, two fediverse handles are recognized as the same:
>
> * `@alice@example.com`
> * `@alice@ap.example.com`

[Caddy]: https://caddyserver.com/

[nginx]: https://nginx.org/

## Integrating with web frameworks

`Federation` is designed to be used together with web frameworks.  For details,
see the [*Integration* section](./integration.md).

## `TContextData`

The `Federation` class is a generic class that takes a type parameter named
`TContextData`.  The `TContextData` type is the type of the context data,
which is shared among the actor dispatcher, inbox listener, and other
callback functions.  The `TContextData` type can be `void` if you don't
need to share any context data, but it can be any type if you need to share
context data.

For example, if you want to share a database connection among the actor
dispatcher, inbox listener, and other callback functions, you can set the
`TContextData` type to the type of the database connection:

```typescript
import { FreshContext } from "$fresh/server.ts";
import { federation } from "../federation.ts"; // Import the `Federation` object
import { DatabasePool, getPool } from "./database.ts";

export async function handler(request: Request, context: FreshContext) {
  return federation.fetch(request, {
    contextData: getPool(),  // [!code highlight]
    onNotFound: context.next.bind(context),
    onNotAcceptable: async (request: Request) => {
      // Omitted for brevity
    }
  });
};
```

The `Context.data` is passed to registered callback functions as their first
parameter within the `Context` object:

```typescript twoslash
// @noErrors: 2345
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  // There is a database connection in `ctx.data`.
});
```

Another example is to determine the virtual host of the server based on the
incoming HTTP request.  See the [next section](#virtual-hosting) for details.

## Virtual hosting

*This API is available since Fedify 0.12.0.*

> \[!CAUTION]
> You should not [explicitly configure a canonical
> origin](#explicitly-setting-the-canonical-origin) when you want to support
> multiple domains on the same server.

You may want to support multiple domains on the same server, so-called
*virtual hosts*.  To determine the virtual host of the server based on the
incoming HTTP request, you can use `Context.host` that contains
the virtual host information:

```typescript{2} twoslash
// @noErrors: 2345
import { type Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher("/@{identifier}", (ctx, identifier) => {
  const fullHandle = `${identifier}@${ctx.host}`;
  // Omitted for brevity
});
```

You can access the virtual host information in the actor dispatcher,
inbox listener, and other callback functions.

See also the [*Getting the base URL* section](./context.md#getting-the-base-url)
in the *Context* document.

---

---
url: /manual/inbox.md
description: >-
  Fedify provides a way to register inbox listeners so that you can handle
  incoming activities from other actors.  This section explains how to register
  an inbox listener and how to handle errors.
---

# Inbox listeners

In ActivityPub, an [inbox] is where an actor receives incoming activities from
other actors.  Fedify provides a way to register inbox listeners so that you can
handle incoming activities from other actors.

[inbox]: https://www.w3.org/TR/activitypub/#inbox

## Signature verification

The inbox listeners automatically verify the signature of the incoming
activities with various specifications, such as:

* Draft cavage [HTTP Signatures]
* HTTP Message Signatures ([RFC 9421])
* [Linked Data Signatures]
* Object Integrity Proofs ([FEP-8b32])

You don't need to worry about the signature verification at all.  By default,
activities whose signatures/proofs cannot be verified are rejected with
`401 Unauthorized` and are not passed to inbox listeners.  If you want to see
why some activities are rejected, you can turn on [logging](./log.md) for
`["fedify", "sig"]` category.

[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421

[Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/

[FEP-8b32]: https://w3id.org/fep/8b32

### `Accept-Signature` challenges

*This API is available since Fedify 2.1.0.*

You can optionally enable [`Accept-Signature`] challenge emission on inbox
`401` responses by setting the `inboxChallengePolicy` option when creating
a `Federation`:

```typescript
import { createFederation } from "@fedify/fedify";

const federation = createFederation<void>({
  // ... other options ...
  inboxChallengePolicy: {
    enabled: true,
    // Optional: customize covered components (defaults shown below)
    // components: ["@method", "@target-uri", "@authority", "content-digest"],
    // Optional: require a one-time nonce for replay protection
    // requestNonce: false,
    // Optional: nonce TTL in seconds (default: 300)
    // nonceTtlSeconds: 300,
  },
});
```

When enabled, if HTTP Signature verification fails, the `401` response will
include an `Accept-Signature` header telling the sender which components and
parameters to include in a new signature.  Senders that support [RFC 9421 §5]
(including Fedify 2.1.0+) will automatically retry with the requested
parameters.

Note that actor/key mismatch `401` responses are *not* challenged, since
re-signing with different parameters does not resolve an impersonation issue.

When `requestNonce` is enabled, a cryptographically random nonce is included
in each challenge and must be echoed back in the retry signature.  The nonce
is stored in the key-value store and consumed on use, providing replay
protection.  Nonces expire after `nonceTtlSeconds` (default: 5 minutes).

[`Accept-Signature`]: https://www.rfc-editor.org/rfc/rfc9421#section-5.1

[RFC 9421 §5]: https://www.rfc-editor.org/rfc/rfc9421#section-5

## Handling unverified activities

*This API is available since Fedify 2.1.0.*

Most applications can keep the default behavior and ignore unverified inbound
activities.  However, some applications need finer control.  Typical examples
include:

* remote actor deletions where the `Delete` activity can still be parsed,
  but the signing key now returns `410 Gone`
* noisy redelivery loops from remote servers that keep retrying activities
  you have decided not to process
* custom logging, metrics, moderation, or quarantine flows for suspicious
  inbound traffic

For these cases, you can register
`~InboxListenerSetters.onUnverifiedActivity()`.  The callback receives the
`RequestContext`, the parsed activity, and a reason object whose `type` is one
of `"noSignature"`, `"invalidSignature"`, or `"keyFetchError"`.

If the callback returns a `Response`, Fedify uses it as-is.  If it returns
nothing (`void`), Fedify falls back to the default `401 Unauthorized`
response.

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Delete } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .onUnverifiedActivity((ctx, activity, reason) => {
    if (
      activity instanceof Delete &&
      reason.type === "keyFetchError" &&
      "status" in reason.result &&
      reason.result.status === 410
    ) {
      // For example, stop redelivery of a Delete from a permanently gone actor.
      return new Response(null, { status: 202 });
    }
  });
```

Returning a custom response does not pass the activity to the inbox listeners
registered through `~InboxListenerSetters.on()`.  Verified activities continue
to flow to those listeners as usual; unverified activities remain opt-in.

The request context includes the original `Request` object, so you can inspect
details such as the `Host` header through `RequestContext.request` when making
policy decisions.

## Registering an inbox listener

An inbox is basically an HTTP endpoint that receives webhook requests from other
servers.  There are two types of inboxes in ActivityPub: the [shared inbox] and
the personal inbox.  The shared inbox is a single inbox that receives activities
for all actors in the server, while the personal inbox is an inbox for a
specific actor.

With Fedify, you can register an inbox listener for both types of inboxes at
a time.  The following shows how to register an inbox listener:

```typescript{7-20} twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Accept, Follow } from "@fedify/vocab";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
});

federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    if (follow.objectId == null) return;
    const parsed = ctx.parseUri(follow.objectId);
    if (parsed?.type !== "actor") return;
    const recipient = await follow.getActor(ctx);
    if (recipient == null) return;
    await ctx.sendActivity(
      { identifier: parsed.identifier },
      recipient,
      new Accept({ actor: follow.objectId, object: follow }),
    );
  });
```

In the above example, the `~Federatable.setInboxListeners()` method registers
path patterns for the personal inbox and the shared inbox, and the following
`~InboxListenerSetters.on()` method registers an inbox listener for the `Follow`
activity.  The `~InboxListenerSetters.on()` method takes a class of the activity
and a callback function that takes a `Context` object and the activity object.

Note that the `~InboxListenerSetters.on()` method can be chained to register
multiple inbox listeners for different activity types.

> \[!NOTE]
> The URI Template syntax supports different expansion types like `{identifier}`
> (simple expansion) and `{+identifier}` (reserved expansion).  If your
> identifiers contain URIs or special characters, you may need to use
> `{+identifier}` to avoid double-encoding issues.  See the
> [*URI Template* guide](./uri-template.md) for details.

> \[!WARNING]
> Activities of any type that are not registered with
> the `~InboxListenerSetters.on()` method are silently ignored.
> If you want to catch all types of activities anyway, add a listener
> for the `Activity` class.

> \[!TIP]
> You can get a personal or shared inbox URI by calling
> the `~Context.getInboxUri()` method.  It takes an optional parameter
> `identifier` to get the personal inbox URI for the actor with the given
> identifier.  If the `identifier` parameter is not provided, the method
> returns the shared inbox URI.

[shared inbox]: https://www.w3.org/TR/activitypub/#shared-inbox-delivery

## Determining the recipient of an activity

### Looking at the `to`, `cc`, `bto`, and `bcc` fields

When you receive an activity, you may want to determine the recipient of the
activity.  The recipient is usually the actor who is mentioned in
the `to`, `cc`, `bto`, or `bcc` field of the activity.  The following shows
how to determine the recipient of a `Create` activity:

```typescript twoslash
import { type InboxListenerSetters } from "@fedify/fedify";
import { Create } from "@fedify/vocab";
(0 as unknown as InboxListenerSetters<void>)
// ---cut-before---
.on(Create, async (ctx, create) => {
  if (create.toId == null) return;
  const to = ctx.parseUri(create.toId);
  if (to?.type !== "actor") return;
  const recipient = to.identifier;
  // Do something with the recipient
});
```

The `to`, `cc`, `bto`, and `bcc` fields can contain multiple recipients,
so you may need to iterate over them to determine the recipient of the activity:

```typescript twoslash
import { type InboxListenerSetters } from "@fedify/fedify";
import { Create } from "@fedify/vocab";
(0 as unknown as InboxListenerSetters<void>)
// ---cut-before---
.on(Create, async (ctx, create) => {
  for (const toId of create.toIds) {
    const to = ctx.parseUri(toId);
    if (to?.type !== "actor") continue;
    const recipient = to.identifier;
    // Do something with the recipient
  }
});
```

Also, the `to`, `cc`, `bto`, and `bcc` fields can contain both actor and
collection objects.  In such cases, you may need to recursively resolve the
collection objects to determine the recipients of the activity:

```typescript twoslash
import { type InboxListenerSetters } from "@fedify/fedify";
import { Collection, Create, isActor } from "@fedify/vocab";
(0 as unknown as InboxListenerSetters<void>)
// ---cut-before---
.on(Create, async (ctx, create) => {
  for await (const to of create.getTos()) {
    if (isActor(to)) {
      // `to` is a recipient of the activity
      // Do something with the recipient
    } else if (to instanceof Collection) {
      // `to` is a collection object
      for await (const actor of to.getItems()) {
        if (!isActor(actor)) continue;
        // `actor` is a recipient of the activity
        // Do something with the recipient
      }
    }
  }
});
```

> \[!TIP]
> It might look strange, non-scalar accessor methods for `to`, `cc`, `bto`,
> and `bcc` fields are named as `~Object.getTos()`, `~Object.getCcs()`,
> `~Object.getBtos()`, and `~Object.getBccs()`, respectively.

### Looking at the `InboxContext.recipient` property

*This API is available since Fedify 1.2.0.*

However, the `to`, `cc`, `bto`, and `bcc` fields are not always present in
an activity.  In such cases, you can determine the recipient by looking at
the `InboxContext.recipient` property.  The below example shows how to determine
the recipient of a `Follow` activity:

```typescript twoslash
import { type InboxListenerSetters } from "@fedify/fedify";
import { Follow } from "@fedify/vocab";
(0 as unknown as InboxListenerSetters<void>)
// ---cut-before---
.on(Follow, async (ctx, follow) => {
  const recipient = ctx.recipient;
  // Do something with the recipient
});
```

The `~InboxContext.recipient` property is set to the identifier of the actor
who is the recipient of the activity.  If the invocation is not for a personal
inbox, but for a shared inbox, the `~InboxContext.recipient` property is set to
`null`.

## `Context.documentLoader` on an inbox listener

The `Context.documentLoader` property carries a `DocumentLoader` object that
you can use to fetch a remote document.  If a request is made to a shared inbox,
the `Context.documentLoader` property is set to the default `documentLoader`
that is specified in the `createFederation()` function.  However, if a request
is made to a personal inbox, the `Context.documentLoader` property is set to
an authenticated `DocumentLoader` object that is identified by the inbox owner's
key.

This means that you can pass the `Context` object to dereferencing accessors\[^1]
inside a personal inbox listener so that they can fetch remote documents with
the correct authentication.

\[^1]: See the [*Object IDs and remote objects*
section](./vocab.md#object-ids-and-remote-objects) if you are not familiar
with dereferencing accessors.

### Shared inbox key dispatcher

*This API is available since Fedify 0.11.0.*

> \[!TIP]
> We highly recommend configuring the shared inbox key dispatcher to avoid
> potential incompatibility issues with ActivityPub servers that require
> [authorized fetch] (i.e., secure mode).

If you want to use an authenticated `DocumentLoader` object as
the `Context.documentLoader` for a shared inbox, you can set the identity
for the authentication using `~InboxListenerSetters.setSharedKeyDispatcher()`
method.  For example, the following shows how to implement the [instance actor]
pattern:

```typescript{5-9,13-18} twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { Application, Person } from "@fedify/vocab";

federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  // The following line assumes that there is an instance actor named `~actor`
  // for the server.  The leading tilde (`~`) is just for avoiding conflicts
  // with regular actor handles, but you don't have to necessarily follow this
  // convention:
  .setSharedKeyDispatcher((_ctx) => ({ identifier: "~actor" }));

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier === "~actor") {
      // Returns an Application object for the instance actor:
      return new Application({
        // ...
      });
    }

    // Fetches the regular actor from the database and returns a Person object:
    return new Person({
      // ...
    });
  });
```

Or you can manually configure the key pair instead of referring to an actor
by its identifier:

```typescript{11-18} twoslash
// @noErrors: 2391
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
/**
 * A hypothetical type that represents an instance actor.
 */
interface InstanceActor {
  /**
   * The private key of the instance actor in JWK format.
   */
  privateKey: JsonWebKey;
  /**
   * The URI of the public key of the instance actor.
   */
  publicKeyUri: string;
}
/**
 * A hypothetical function that fetches information about the instance actor
 * from a database or some other storage.
 * @returns Information about the instance actor.
 */
function getInstanceActor(): InstanceActor;
// ---cut-before---
import { importJwk } from "@fedify/fedify";

interface InstanceActor {
  privateKey: JsonWebKey;
  publicKeyUri: string;
}

federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .setSharedKeyDispatcher(async (_ctx) => {
    // The following getInstanceActor() is just a hypothetical function that
    // fetches information about the instance actor from a database or some
    // other storage:
    const instanceActor: InstanceActor = await getInstanceActor();
    return {
      privateKey: await importJwk(instanceActor.privateKey, "private"),
      keyId: new URL(instanceActor.publicKeyUri),
    };
  });
```

> \[!NOTE]
> If a shared inbox key dispatcher returns `null`, the default `documentLoader`,
> which is not authenticated, is used for the shared inbox.

[authorized fetch]: https://swicg.github.io/activitypub-http-signature/#authorized-fetch

[instance actor]: https://seb.jambor.dev/posts/understanding-activitypub-part-4-threads/#the-instance-actor

## Making inbox listeners non-blocking

*This API is available since Fedify 0.12.0.*

Usually, processes inside an inbox listener should be non-blocking because
they may involve long-running tasks.  Fortunately, you can easily turn inbox
listeners into non-blocking by providing a [`queue`](./federation.md#queue)
option to `createFederation()` function:

```typescript twoslash
// @noErrors: 2345
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
  queue: new InProcessMessageQueue(),  // [!code highlight]
});
```

> \[!NOTE]
> The `InProcessMessageQueue` is a simple in-memory message queue that is
> suitable for development and testing.  For production use, you should
> consider using a more robust message queue, such as [`DenoKvMessageQueue`]
> from [`@fedify/denokv`] package, [`RedisMessageQueue`] from
> [`@fedify/redis`] package, or [`MysqlMessageQueue`] from
> [`@fedify/mysql`] package.
>
> For more information, see the [*Message queue* section](./mq.md).

If it is not present, incoming activities are processed immediately and block
the response to the sender until the processing is done.

While the `queue` option is not mandatory, it is highly recommended to use it
in production environments to prevent the server from being overwhelmed by
incoming activities.

With the `queue` enabled, the failed activities are automatically retried
after a certain period of time.  By default, Fedify handles retries using
exponential backoff with a maximum of 10 retries, but you can customize it
by providing an [`inboxRetryPolicy`](./federation.md#inboxretrypolicy) option
to the `createFederation()` function.

However, if your message queue backend provides native retry mechanisms
(indicated by `MessageQueue.nativeRetrial` being `true`), Fedify will skip
its own retry logic and rely on the backend to handle retries.  This avoids
duplicate retry mechanisms and leverages the backend's optimized retry features.

> \[!NOTE]
> Activities with invalid signatures/proofs are not queued and are not passed
> to inbox listeners.  If
> `~InboxListenerSetters.onUnverifiedActivity()` is configured, the hook runs
> before the default `401 Unauthorized` response is returned.

> \[!TIP]
> If your inbox listeners are mostly I/O-bound, consider parallelizing
> message processing by using the `ParallelMessageQueue` class.  For more
> information, see the [*Parallel message processing*
> section](./mq.md#parallel-message-processing).
>
> If your inbox listeners are CPU-bound, consider running multiple nodes of
> your application so that each node can process messages in parallel with
> the shared message queue.

[`DenoKvMessageQueue`]: https://jsr.io/@fedify/denokv/doc/mq/~/DenoKvMessageQueue

[`@fedify/denokv`]: https://github.com/fedify-dev/fedify/tree/main/packages/denokv

[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

[`@fedify/redis`]: https://github.com/fedify-dev/fedify/tree/main/packages/redis

[`MysqlMessageQueue`]: https://jsr.io/@fedify/mysql/doc/mq/~/MysqlMessageQueue

[`@fedify/mysql`]: https://github.com/fedify-dev/fedify/tree/main/packages/mysql

## 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"` (default)
:   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 is the default strategy since Fedify 2.0.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 had been 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 } from "@fedify/fedify";
import { Follow } from "@fedify/vocab";
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
  });
```

### 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 } from "@fedify/fedify";
import { Follow } from "@fedify/vocab";
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

Since an incoming activity can be malformed or invalid, you may want to handle
such cases.  Also, your listener itself may throw an error.
The `~InboxListenerSetters.onError()` method registers a callback
function that takes a `Context` object and an error object.  The following shows
an example of handling errors:

```typescript{6-8} twoslash
import { type Federation } from "@fedify/fedify";
import { Follow } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    // Omitted for brevity
  })
  .onError(async (ctx, error) => {
    console.error(error);
  });
```

> \[!NOTE]
> Activities with invalid signatures/proofs are not passed to the error
> handler.  If you need to inspect them, use
> `~InboxListenerSetters.onUnverifiedActivity()` instead.

## Forwarding activities to another server

*This API is available since Fedify 1.0.0.*

Sometimes, you may want to forward incoming activities to another server.
For example, you may want to forward `Flag` activities to a moderation server.
Or you may want to forward `Create` activities which reply to your server to
your followers so that they can see the replies.

The problem is that the recipients of the forwarded activities will not trust
the forwarded activities unless they are signed by the original sender, not by
you.  You might think that you can just `~Context.sendActivity()` the received
activity to the recipient in your inbox listener, but it doesn't work because
the signature made by the original sender is stripped when the received activity
is passed to the inbox listener, and `~Context.sendActivity()` will sign the
activity with your key.

To solve this problem, you can use the `~InboxContext.forwardActivity()` method
in your inbox listener.  It forwards the received activity without any
modification, so the signature made by the original sender is preserved
(if the activity is signed using by the original sender).

The following shows an example of forwarding `Create` activities to followers:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Create } from "@fedify/vocab";
const federation: Federation<void> = null as unknown as Federation<void>;
federation.setInboxListeners("/{identifier}/inbox", "/inbox")
// ---cut-before---
.on(Create, async (ctx, create) => {
  if (create.toId == null) return;
  const to = ctx.parseUri(create.toId);
  if (to?.type !== "actor") return;
  const forwarder = to.identifier;
  await ctx.forwardActivity({ identifier: forwarder }, "followers");
})
```

> \[!NOTE]
> The `~InboxContext.forwardActivity()` method does not guarantee that the
> forwarded activity is successfully delivered to the recipient, since
> the original sender might  neither sign the activity using [Linked Data
> Signatures](./send.md#linked-data-signatures) nor [Object Integrity
> Proofs](./send.md#object-integrity-proofs).  In such cases, the recipient
> probably won't trust the forwarded activity.\[^2]
>
> If you don't want to forward unsigned activities, you can turn on
> the `skipIfUnsigned` option in the `~InboxContext.forwardActivity()` method:
>
> ```typescript twoslash
> import { type InboxContext } from "@fedify/fedify";
> const ctx = null as unknown as InboxContext<void>;
> // ---cut-before---
> await ctx.forwardActivity(
>   { identifier: "alice" },
>   "followers",
>   { skipIfUnsigned: true },
> );
> ```

> \[!NOTE]
> The `~InboxContext.forwardActivity()` method does not use a [two-stage
> delivery process](./send.md#optimizing-activity-delivery-for-large-audiences),
> because `~InboxContext.forwardActivity()` method is invoked inside inbox
> listeners, which are usually running in the background task worker.

\[^2]: Some implementations may try to verify the unsigned activity by fetching
the original object from the original sender's server even if they don't
trust the forwarded activity. However, it is not guaranteed that all
implementations do so.

## Constructing inbox URIs

To construct an inbox URI, you can use the `~Context.getInboxUri()` method.
This method optionally takes an identifier of an actor and returns
a dereferenceable URI of the inbox of the actor.  If no argument is provided,
the method returns the shared inbox URI.

The following shows how to construct an inbox URI of an actor identified by
`5fefc9bb-397d-4949-86bb-33487bf233fb`:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getInboxUri("5fefc9bb-397d-4949-86bb-33487bf233fb")
```

> \[!NOTE]
> The `~Context.getInboxUri()` method does not guarantee that the inbox
> actually exists.  It only constructs a URI based on the given identifier,
> which may respond with `404 Not Found`.  Make sure to check if the identifier
> is valid before calling the method.

The following shows how to construct a shared inbox URI:

```typescript twoslash
import type { Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getInboxUri()
```

## Manual routing

*This API is available since Fedify 1.3.0.*

If you want to manually route an activity to the appropriate inbox listener
with no actual HTTP request, you can use the `Context.routeActivity()` method.
The method takes an identifier of the recipient (or `null` for the shared inbox)
and an `Activity` object to route.  The point of this method is that it verifies
if the `Activity` object is made by the its actor, and unless it is, the method
silently ignores the activity.

The following code shows how to route an `Activity` object enclosed in
top-level `Announce` object to the corresponding inbox listener:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Activity, Announce } from "@fedify/vocab";

const federation = null as unknown as Federation<void>;

federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
// ---cut-before---
  .on(Announce, async (ctx, announce) => {
    // Get an object enclosed in the `Announce` object:
    const object = await announce.getObject();
    if (object instanceof Activity) {
      // Route the activity to the appropriate inbox listener (shared inbox):
      await ctx.routeActivity(ctx.recipient, object);
    }
  })
```

As another example, the following code shows how to invoke the corresponding
inbox listeners for a remote actor's activities:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity, isActor } from "@fedify/vocab";

async function main(context: Context<void>) {
// ---cut-before---
const actor = await context.lookupObject("@hongminhee@fosstodon.org");
if (!isActor(actor)) return;
const collection = await actor.getOutbox();
if (collection == null) return;
for await (const item of context.traverseCollection(collection)) {
  if (item instanceof Activity) {
    await context.routeActivity(null, item);
  }
}
// ---cut-after---
}
```

> \[!TIP]
> The `Context.routeActivity()` method trusts the `Activity` object only if
> one of the following conditions is met:
>
> * The `Activity` has its Object Integrity Proofs and the proofs are signed
>   by its actor.

> * The `Activity` is dereferenceable by its `~Object.id` and
>   the dereferenced object has an actor that belongs to the same origin
>   as the `Activity` object.

---

---
url: /install.md
description: How to install Fedify.
---

# Installation

## Quick start

The easiest way to start a new Fedify project is to use the `fedify init`
command.  It creates a new directory with a minimal Fedify project template.

### CLI toolchain

First of all, you need to have the `fedify` command, the Fedify CLI toolchain,
installed on your system.  If you haven't installed it yet, please follow the
following instructions:

::: code-group

```sh [npm]
npm install -g @fedify/cli
```

```sh [Homebrew (Linux/macOS)]
brew install fedify
```

```powershell [Scoop (Windows)]
scoop install fedify
```

```sh [Bun]
bun install -g @fedify/cli
```

```sh [Deno]
deno install -gA --unstable-fs --unstable-kv -n fedify jsr:@fedify/cli
```

:::

If you use Deno earlier than 2.7.0, add `--unstable-temporal` to the Deno
installation command above.

There are other ways to install the `fedify` command.  Please refer to the
[*Installation* section](./cli.md#installation) in the *CLI toolchain* docs.

### Project setup

After installing the `fedify` command, you can create a new Fedify project by
running the following command:

```sh
fedify init your-project-dir
```

The above command will start a wizard to guide you through the project setup.
You can choose the JavaScript runtime, the package manager, and the web
framework you want to integrate Fedify with, and so on.  After the wizard
finishes, you will have a new Fedify project in the *your-project-dir*
directory.

For more information about the `fedify init` command, please refer to the
[*`fedify init`* section](./cli.md#fedify-init-initializing-a-fedify-project)
in the *CLI toolchain* docs.

[![The “fedify init” command demo](https://asciinema.org/a/671658.svg)](https://asciinema.org/a/671658)

### Alternative: Using `@fedify/create`

If you don't want to install the `fedify` CLI globally, you can use
`@fedify/create` directly:

::: code-group

```sh [npm]
npm init @fedify your-project-dir
```

```sh [pnpm]
pnpm create @fedify your-project-dir
```

```sh [Yarn]
yarn create @fedify your-project-dir
```

```sh [Bun]
bunx @fedify/create your-project-dir
```

:::

This works the same way as `fedify init` and will guide you through the same
project setup wizard.

## Manual installation

Fedify is available on [JSR] for [Deno] and on [npm] for [Bun] and [Node.js].

[JSR]: https://jsr.io/@fedify/fedify

[Deno]: https://deno.com/

[npm]: https://www.npmjs.com/package/@fedify/fedify

[Bun]: https://bun.sh/

[Node.js]: https://nodejs.org/

### Deno

[Deno] is the primary runtime for Fedify.  As a prerequisite, you need to have
Deno 2.0.0 or later installed on your system.  Then you can install Fedify
via the following command:

```sh
deno add jsr:@fedify/fedify
```

Fedify requires the [`Temporal`] API.  On Deno 2.7.0 or later, it is stable and
no extra setting is needed.  On Deno versions earlier than 2.7.0, add
`"temporal"` to the `"unstable"` field in *deno.json*:

```json{5}
{
  "imports": {
    "@fedify/fedify": "jsr:@fedify/fedify"
  },
  "unstable": ["temporal"]
}
```

[`Temporal`]: https://tc39.es/proposal-temporal/docs/

### Bun

Fedify can also be used in Bun.  You can install it via the following
command:

```sh
bun add @fedify/fedify
```

### Node.js

Fedify can also be used in Node.js.  As a prerequisite, you need to have Node.js
22.0.0 or later installed on your system.  Then you can install Fedify via
the following command:

::: code-group

```sh [npm]
npm add @fedify/fedify
```

```sh [pnpm]
pnpm add @fedify/fedify
```

```sh [Yarn]
yarn add @fedify/fedify
```

:::

We recommend using [ESM] with Fedify by adding `"type": "module"` to the
*package.json* file. While Fedify also supports [CommonJS] for legacy
compatibility, ESM is the preferred approach:

```json{2}
{
  "type": "module",
  "dependencies": {
    "@fedify/fedify": "^1.8.1"
  }
}
```

[ESM]: https://nodejs.org/api/esm.html

[CommonJS]: https://nodejs.org/docs/latest/api/modules.html

---

---
url: /manual/integration.md
description: >-
  Fedify is designed to be used together with web frameworks.  This document
  explains how to integrate Fedify with web frameworks.
---

# Integration

Fedify is designed to be used together with web frameworks.  This document
explains how to integrate Fedify with web frameworks.

## How it works

Usually, Fedify behaves as a middleware that wraps around the web framework's
request handler.  The middleware intercepts the incoming HTTP requests and
dispatches them to the appropriate handler based on the request path and
the [`Accept`] header (i.e., [content negotiation]).  Basically, this
architecture allows Fedify and your web framework to coexist in the same domain
and port.

For example, if you make a request to */.well-known/webfinger* Fedify will
handle the request by itself, but if you make a request to */users/alice*
(assuming your web framework has a handler for `/users/:identifier`) with
`Accept: text/html` header, Fedify will dispatch the request to the web
framework's appropriate handler for `/users/:identifier`.  Or if you define an
actor dispatcher for `/users/{identifier}` in Fedify, and the request is made
with `Accept: application/activity+json` header, Fedify will dispatch the
request to the appropriate actor dispatcher.

Here is a diagram that illustrates the architecture:

```mermaid
sequenceDiagram
  participant Client
  participant Fedify
  participant AD as Actor dispatcher<br/>(Fedify)
  participant WF as Web framework

  Client ->> Fedify: GET /users/alice<br/>(Accept: application/activity+json)
  Fedify -->> Client: 200 OK
  Fedify ->> AD: GET /users/alice
  AD -->> Fedify: 200 OK
  Fedify -->> Client: 200 OK

  Client ->> Fedify: GET /users/alice<br/>(Accept: text/html)
  Fedify ->> AD: GET /users/alice<br/>(Accept: text/html)
  AD -->> Fedify: 406 Not Acceptable
  Fedify ->> WF: GET /users/alice
  WF -->> Fedify: 200 OK
  Fedify -->> Client: 200 OK
```

> \[!NOTE]
>
> Why not use a reverse proxy in front of the web framework and Fedify?
> Because you would want to call Fedify's API from the web framework's
> request handler, e.g., to send an ActivityPub activity.  If you put a
> reverse proxy in front of them, the web framework cannot call Fedify's API
> directly.
>
> Of course, you can divide your application into two separate services,
> one for ActivityPub and the other for the web application, and put a
> reverse proxy in front of them.  But in this case, you need to implement
> the communication between the two services (using a message queue or RPC,
> for example), which is non-trivial.

[`Accept`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept

[content negotiation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation

## Express

[Express] is a fast, unopinionated, minimalist web framework for Node.js.
The *@fedify/express* package provides a middleware to integrate Fedify with
Express:

::: code-group

```sh [Deno]
deno add jsr:@fedify/express
```

```sh [npm]
npm add @fedify/express
```

```sh [pnpm]
pnpm add @fedify/express
```

```sh [Yarn]
yarn add @fedify/express
```

```sh [Bun]
bun add @fedify/express
```

:::

```typescript twoslash
// @noErrors: 2345
import express from "express";
import { integrateFederation } from "@fedify/express";
import { createFederation } from "@fedify/fedify";

export const federation = createFederation<string>({
  // Omitted for brevity; see the related section for details.
});

export const app = express();

app.set("trust proxy", true);

app.use(integrateFederation(federation, (req) => "context data goes here"));  // [!code highlight]
```

[Express]: https://expressjs.com/

## Fastify

*This API is available since Fedify 1.9.0.*

[Fastify] is a fast and low overhead web framework for Node.js, with
a powerful plugin architecture and sensible defaults.  The *@fedify/fastify*
package provides a plugin to integrate Fedify with Fastify:

::: code-group

```sh [npm]
npm add @fedify/fastify
```

```sh [pnpm]
pnpm add @fedify/fastify
```

```sh [Yarn]
yarn add @fedify/fastify
```

```sh [Bun]
bun add @fedify/fastify
```

:::

```typescript twoslash
// @noErrors: 2345
import Fastify from "fastify";
import { fedifyPlugin } from "@fedify/fastify";
import { createFederation } from "@fedify/fedify";

export const federation = createFederation<void>({
  // Omitted for brevity; see the related section for details.
});

const fastify = Fastify({ logger: true });

// Register the Fedify plugin:
await fastify.register(fedifyPlugin, {  // [!code highlight]
  federation,  // [!code highlight]
  contextDataFactory: () => undefined,  // [!code highlight]
});  // [!code highlight]

fastify.listen({ port: 3000 });
```

[Fastify]: https://fastify.dev/

## Koa

*This API is available since Fedify 1.9.0.*

[Koa] is a lightweight, expressive, and modern web framework for Node.js,
designed by the team behind Express.  It uses async functions and provides
a more elegant middleware architecture.  The *@fedify/koa* package provides
a middleware to integrate Fedify with Koa:

::: code-group

```sh [Deno]
deno add jsr:@fedify/koa
```

```sh [npm]
npm add @fedify/koa
```

```sh [pnpm]
pnpm add @fedify/koa
```

```sh [Yarn]
yarn add @fedify/koa
```

```sh [Bun]
bun add @fedify/koa
```

:::

```typescript twoslash
// @noErrors: 2345
import Koa from "koa";
import { createMiddleware } from "@fedify/koa";
import { createFederation } from "@fedify/fedify";

export const federation = createFederation<string>({
  // Omitted for brevity; see the related section for details.
});

export const app = new Koa();

app.proxy = true;  // trust proxy headers

app.use(createMiddleware(federation, (ctx) => "context data goes here"));  // [!code highlight]
```

> \[!NOTE]
> The `@fedify/koa` package supports both Koa v2.x and v3.x.

[Koa]: https://koajs.com/

## Hono

*This API is available since Fedify 1.9.0.*

[Hono] is a fast, lightweight, and Web standard-compliant server framework for
TypeScript.  The *@fedify/hono* package provides a middleware to integrate
Fedify with Hono:

::: code-group

```sh [Deno]
deno add jsr:@fedify/hono
```

```sh [npm]
npm add @fedify/hono
```

```sh [pnpm]
pnpm add @fedify/hono
```

```sh [Yarn]
yarn add @fedify/hono
```

```sh [Bun]
bun add @fedify/hono
```

:::

```typescript
import { createFederation } from "@fedify/fedify";
import { federation } from "@fedify/hono";
import { Hono } from "hono";

const fedi = createFederation<string>({
  // Omitted for brevity; see the related section for details.
});

const app = new Hono();
app.use(federation(fedi, (ctx) => "context data"));  // [!code highlight]
```

[Hono]: https://hono.dev/

## h3

[h3] is an HTTP server framework behind [Nitro], [Analog], [Vinxi],
[SolidStart], [TanStack Start], and other many web frameworks.
The *@fedify/h3* package provides a middleware to integrate Fedify with h3:

::: code-group

```sh [Deno]
deno add jsr:@fedify/h3
```

```sh [npm]
npm add @fedify/h3
```

```sh [pnpm]
pnpm add @fedify/h3
```

```sh [Yarn]
yarn add @fedify/h3
```

```sh [Bun]
bun add @fedify/h3
```

:::

```typescript {9-15} twoslash
// @noErrors: 2345
import { createApp, createRouter } from "h3";
import { createFederation } from "@fedify/fedify";
import { integrateFederation, onError } from "@fedify/h3";

export const federation = createFederation<string>({
  // Omitted for brevity; see the related section for details.
});

export const app = createApp({ onError });
app.use(
  integrateFederation(
    federation,
    (event, request) => "context data goes here"
  )
);

const router = createRouter();
app.use(router);
```

> \[!NOTE]
> Your app has to configure `onError` to let Fedify negotiate content types.
> If you don't do this, Fedify will not be able to respond with a proper error
> status code when a content negotiation fails.

[h3]: https://h3.unjs.io/

[Nitro]: https://nitro.unjs.io/

[Analog]: https://analogjs.org/

[Vinxi]: https://vinxi.vercel.app/

[SolidStart]: https://start.solidjs.com/

[TanStack Start]: https://tanstack.com/start

## SvelteKit

*This API is available since Fedify 1.3.0.*

[SvelteKit] is a framework for building web applications with [Svelte].  The
*@fedify/sveltekit* package provides a middleware to integrate Fedify with
SvelteKit:

::: code-group

```sh [Deno]
deno add jsr:@fedify/sveltekit
```

```sh [npm]
npm add @fedify/sveltekit
```

```sh [pnpm]
pnpm add @fedify/sveltekit
```

```sh [Yarn]
yarn add @fedify/sveltekit
```

```sh [Bun]
bun add @fedify/sveltekit
```

:::

```typescript
import { createFederation } from "@fedify/fedify";
import { fedifyHook } from "@fedify/sveltekit";

const federation = createFederation<string>({
  // Omitted for brevity; see the related section for details.
});

// This is the entry point to the Fedify hook from the SvelteKit framework:
export const handle = fedifyHook(federation, (req) => "context data");
```

[SvelteKit]: https://kit.svelte.dev/

[Svelte]: https://svelte.dev/

## NestJS

*This API is available since Fedify 1.8.0.*

[NestJS] is a modular, versatile, and scalable framework for building efficient,
reliable, and scalable server-side applications with Node.js and TypeScript.
The *@fedify/nestjs* package provides a middleware to integrate Fedify with
NestJS:

::: code-group

```sh [npm]
npm add @fedify/nestjs
```

```sh [pnpm]
pnpm add @fedify/nestjs
```

```sh [Yarn]
yarn add @fedify/nestjs
```

```sh [Bun]
bun add @fedify/nestjs
```

:::

```typescript [modules/federation/federation.service.ts] twoslash
import { Injectable, Inject, OnModuleInit } from '@nestjs/common';
import {
  FEDIFY_FEDERATION,
} from '@fedify/nestjs';
import { Federation } from '@fedify/fedify';

@Injectable()
export class FederationService implements OnModuleInit {
  private initialized = false;

  constructor(
    @Inject(FEDIFY_FEDERATION) private federation: Federation<unknown>,
  ) { }

  async onModuleInit() {
    if (!this.initialized) {
      await this.initialize();
      this.initialized = true;
    }
  }

  async initialize() {
    this.federation.setNodeInfoDispatcher("/nodeinfo/2.1", async (context) => {
      return {
        software: {
          name: "Fedify NestJS sample",
          version: "0.0.1"
        },
        protocols: ["activitypub"],
        usage: {
          users: {
            total: 0,
            activeHalfyear: 0,
            activeMonth: 0,
            activeDay: 0,
          },
          localPosts: 0,
          localComments: 0,
        },
      }
    });
  }
}
```

```typescript [modules/federation/federation.module.ts] twoslash
// @noErrors: 2395 2307
import { Injectable, Inject, OnModuleInit } from '@nestjs/common';
import {
  FEDIFY_FEDERATION,
} from '@fedify/nestjs';
import { Federation } from '@fedify/fedify';

@Injectable()
export class FederationService implements OnModuleInit {
  private initialized = false;

  constructor(
    @Inject(FEDIFY_FEDERATION) private federation: Federation<unknown>,
  ) { }

  async onModuleInit() {
    if (!this.initialized) {
      await this.initialize();
      this.initialized = true;
    }
  }

  async initialize() {
  }
}
// ---cut-before---
import { Module } from '@nestjs/common';
import { FederationService } from './federation.service';

@Module({
  providers: [FederationService],
  exports: [FederationService],
})
export class FederationModule {}
```

```typescript [app.module.ts] twoslash
// @noErrors: 2307
// ---cut-before---
import {
  Inject,
  MiddlewareConsumer,
  Module,
  NestModule,
  RequestMethod,
} from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import * as express from 'express';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { DatabaseModule } from './database/database.module';
import { FederationModule } from './modules/federation/federation.module';
import { InProcessMessageQueue, MemoryKvStore, Federation } from '@fedify/fedify';
import process from 'node:process';

import {
  FEDIFY_FEDERATION,
  FedifyModule,
  integrateFederation,
} from '@fedify/nestjs';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    DatabaseModule,
    FedifyModule.forRoot({
      kv: new MemoryKvStore(),
      queue: new InProcessMessageQueue(),
      origin: process.env.FEDERATION_ORIGIN || 'http://localhost:3000',
    }),
    FederationModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  constructor(
    @Inject(FEDIFY_FEDERATION) private federation: Federation<unknown>,
  ) { }

  configure(consumer: MiddlewareConsumer) {
    const fedifyMiddleware = integrateFederation(
      this.federation,
      async (req, res) => {
        return {
          request: req,
          response: res,
          url: new URL(req.url, process.env.FEDERATION_ORIGIN),
        };
      },
    );

    // Fedify middleware requires the raw request body for HTTP signature verification
    // so we apply `express.raw()` before `fedifyMiddleware` to preserve the body.
    consumer.apply(
      express.raw({ type: '*/*' }),
      fedifyMiddleware
    ).forRoutes({ path: '*', method: RequestMethod.ALL });
  }
}
```

[NestJS]: https://nestjs.com/

## Elysia

*This API is available since Fedify 1.8.0.*

[Elysia] is an ergonomic framework designed for humans, featuring built-in
TypeScript support with end-to-end type safety, type integrity, and
an exceptional developer experience.  Powered by Bun, it delivers high
performance and modern tooling.  The *@fedify/elysia* package provides
a seamless plugin for integrating Fedify with Elysia:

```sh [Bun]
bun add @fedify/elysia
```

```sh [Deno]
deno add npm:@fedify/elysia
```

```sh [npm]
npm add @fedify/elysia
```

```sh [pnpm]
pnpm add @fedify/elysia
```

```sh [Yarn]
yarn add @fedify/elysia
```

```typescript
import { fedify } from "@fedify/elysia";
import { federation } from "./federation.ts";  // Your `Federation` instance
import { Elysia } from "elysia";

const app = new Elysia();

app
  .use(fedify(federation, () => "context data goes here"))
  .listen(3000);

console.log("Elysia App Start!");
```

[Elysia]: https://elysiajs.com/

## Next.js

*This API is available since Fedify 1.9.0.*

> \[!TIP]
> You can see the example in the `examples/next-integration` directory in
> the [Fedify repository].  You can create a Fedify–Next.js app copying the
> example with the following command:
>
> ::: code-group
>
> ```sh [npm]
> npx create-next-app -e https://github.com/fedify-dev/fedify \
>   --example-path examples/next-integration
> ```
>
> ```sh [pnpm]
> pnpm create next-app -e https://github.com/fedify-dev/fedify \
>   --example-path examples/next-integration
> ```
>
> ```sh [Yarn]
> yarn create next-app -e https://github.com/fedify-dev/fedify \
>   --example-path examples/next-integration
> ```
>
> ```sh [Bun]
> bun create next-app -e https://github.com/fedify-dev/fedify \
>   --example-path examples/next-integration
> ```
>
> :::

[Next.js] is a React framework that enables you to build server-rendered
and statically generated web applications.  The *@fedify/next* package provides
a middleware to integrate Fedify with Next.js:

::: code-group

```sh [Deno]
deno add jsr:@fedify/next
```

```sh [npm]
npm add @fedify/next
```

```sh [pnpm]
pnpm add @fedify/next
```

```sh [Yarn]
yarn add @fedify/next
```

```sh [Bun]
bun add @fedify/next
```

:::

Or create an app with the following command using the Fedify CLI:

```sh
fedify init my-next-app
```

```
? Choose the JavaScript runtime to use › Node.js
? Choose the package manager to use › npm
? Choose the web framework to integrate Fedify with › Next.js
? Choose the key–value store to use for caching › In-memory
? Choose the message queue to use for background jobs › In-process
✔ Would you like your code inside a `src/` directory? … No
✔ Would you like to customize the import alias (`@/*` by default)? … No
```

Then you can see the Next.js boilerplate code in the `my-next-app` directory.
If you have created a Next.js app with `create-next-app` before, you'll see
some differences in the code. There is a `middleware.ts` file in the
`my-next-app` directory, which is the entry point to the Fedify middleware
from the Next.js framework. Or, if you just install *@fedify/next* manually,
put the following code in your `middleware.ts` file:

```typescript
import { fedifyWith } from "@fedify/next";
import federation from "./federation"; // Your `Federation` instance

export default fedifyWith(federation)(
/*
  function (request: Request) {
    // If you need to handle other requests besides federation
    // requests in middleware, you can do it here.
    // If you handle only federation requests in middleware,
    // you don't need this function.
    return NextResponse.next();
  },
*/
)

// This config needs because middleware process only requests with the
// "Accept" header matching the federation accept regex.
// More details: https://nextjs.org/docs/app/api-reference/file-conventions/middleware#config-object-optional
export const config = {
  runtime: "nodejs",
  matcher: [
    {
      source: "/:path*",
      has: [
        {
          type: "header",
          key: "Accept",
          value: ".*application\\/((jrd|activity|ld)\\+json|xrd\\+xml).*",
        },
      ],
    },
    {
      source: "/:path*",
      has: [
        {
          type: "header",
          key: "content-type",
          value: ".*application\\/((jrd|activity|ld)\\+json|xrd\\+xml).*",
        },
      ],
    },
    { source: "/.well-known/nodeinfo" },
    { source: "/.well-known/x-nodeinfo2" },
  ],
};
```

As you can see in the comment, you can handle other requests besides
federation requests in the middleware.  If you handle only federation requests
in the middleware, you can omit the function argument of `fedifyWith()`.
The `config` object is necessary to let Next.js know that the middleware
should process requests with the [`Accept`] header matching the federation
accept regex.  This is because Next.js middleware processes only requests
with the [`Accept`] header matching the regex by default.  More details can be
found in the Next.js official documentation [`config` in `middleware.js`].

[Fedify repository]: https://github.com/fedify-dev/fedify

[Next.js]: https://nextjs.org/

[`config` in `middleware.js`]: https://nextjs.org/docs/app/api-reference/file-conventions/middleware#config-object-optional

## Astro

*This API is available since Fedify 2.1.0.*

[Astro] is a web framework for content-driven websites. The *@fedify/astro*
package provides an integration and middleware to integrate Fedify with Astro:

::: code-group

```sh [Deno]
deno add jsr:@fedify/astro
```

```sh [npm]
npm add @fedify/astro
```

```sh [pnpm]
pnpm add @fedify/astro
```

```sh [Yarn]
yarn add @fedify/astro
```

```sh [Bun]
bun add @fedify/astro
```

:::

First, add the Fedify integration to your *astro.config.ts*:

```typescript
import { defineConfig } from "astro/config";
import { fedifyIntegration } from "@fedify/astro";

export default defineConfig({
  integrations: [fedifyIntegration()], // [!code highlight]
  output: "server",
});
```

Then, create your middleware in *src/middleware.ts*:

```typescript
import { createFederation } from "@fedify/fedify";
import { fedifyMiddleware } from "@fedify/astro";

const federation = createFederation<void>({
  // Omitted for brevity; see the related section for details.
});

export const onRequest = fedifyMiddleware( // [!code highlight]
  federation, // [!code highlight]
  (context) => void 0, // [!code highlight]
); // [!code highlight]
```

[Astro]: https://astro.build/

### For Deno users

If you are using Deno, you should import `@deno/vite-adapter` in
*astro.config.ts* and use it as the adapter:

```typescript
import { defineConfig } from "astro/config";
import { fedifyIntegration } from "@fedify/astro";
import deno from "@deno/astro-adapter";

export default defineConfig({
  integrations: [fedifyIntegration()],
  output: "server",
  adapter: deno(),
});
```

And the tasks in *deno.json* should be updated to use `deno run npm:astro`
instead of `astro`:

```json
{
  "tasks": {
    "dev": "deno run -A npm:astro dev",
    "build": "deno run -A npm:astro build",
    "preview": "deno run -A npm:astro preview"
  }
}
```

## Fresh

*This API is available since Fedify 2.0.0.*

[Fresh] is a full stack modern web framework for Deno.  Fedify has the
`@fedify/fresh` module that provides a middleware to integrate Fedify
with Fresh.

::: code-group

```sh [Deno]
deno add jsr:@fedify/fresh
```

:::

> \[!NOTE]
> The `@fedify/fresh` package only supports Fresh 2.x.

> \[!NOTE]
> Fresh 2 development mode has been verified with Deno 2.7.7.  Deno 2.7.6 had
> an upstream Vite/esbuild regression that caused
> `Callback called multiple times` before Fedify code could run.

> \[!WARNING]
> Due to `@fedify/fedify` use `Temporal` inside, you should add `deno.unstable`
> to `compilerOptions.libs` field of `deno.json`.
>
> ```json
>  "compilerOptions": {
>    "lib": [
>      "dom",
>      "dom.asynciterable",
>      "dom.iterable",
>      "deno.ns",
>      "deno.unstable"
>    ],
> ...
> ```

Put the following code in your *routes/\_middleware.ts* file:

```typescript [_middelware.ts]
import { createFederation } from "@fedify/fedify";
import { integrateHandler } from "@fedify/fresh";
import { define } from "../utils.ts";

const federation = createFederation<void>({
  // Omitted for brevity; see the related section for details.
});

// This is the entry point to the Fedify middleware from the Fresh framework:
export default define.middleware(
  integrateHandler(federation, () => undefined),
);
```

Or you can use `app.use()` in your `main.ts` to register the middleware
globally:

```typescript [main.ts]
import { App } from "fresh";
import { createFederation } from "@fedify/fedify";
import { integrateHandler } from "@fedify/fresh";
import { define } from "./utils.ts";
const app = new App();
const federation = createFederation<void>({
  // Omitted for brevity; see the related section for details.
});
// This is the entry point to the Fedify middleware from the Fresh framework:
const fedifyMiddleware = define.middleware(
  integrateHandler(federation, () => undefined),
);
app.use(fedifyMiddleware);
```

[Fresh]: https://fresh.deno.dev/

## Custom middleware

Even if you are using a web framework that is not officially supported by
Fedify, you can still integrate Fedify with the framework by creating a custom
middleware (unless the framework does not support middleware).

Web frameworks usually provide a way to intercept incoming requests and outgoing
responses in the middle, which is so-called middleware.  If your
web framework has a middleware feature, you can use it to intercept
federation-related requests and handle them with the `Federation` object.

The key is to create a middleware that calls the `Federation.fetch()` method
with the incoming request and context data, and then sends the response from
Fedify to the client.  At this point, you can use `onNotFound` and
`onNotAcceptable` callbacks to forward the request to the next middleware.

The following is an example of a custom middleware for a hypothetical web
framework:

```typescript
import { Federation } from "@fedify/fedify";

export type Middleware = (
  request: Request,
  next: (request: Request) => Promise<Response>
) => Promise<Response>;

export function createFedifyMiddleware<TContextData>(
  federation: Federation<TContextData>,
  contextDataFactory: (request: Request) => TContextData,
): Middleware {
  return async (request, next) => {
    return await federation.fetch(request, {
      contextData: contextDataFactory(request),

      // If the `federation` object finds a `request` not responsible for it
      // (i.e., not a federation-related request), it will call the `next`
      // provided by the web framework to continue the request handling by
      // the web framework:
      onNotFound: async (request) => await next(request),

      // Similar to `onNotFound`, but slightly more tickly one.
      // When the `federation` object finds a `request` not acceptable type-wise
      // (i.e., a user-agent doesn't want JSON-LD), it will call the `next`
      // provided by the web framework so that it renders HTML if there's some
      // page.  Otherwise, it will simply respond with `406 Not Acceptable`.
      // This trick enables the Fedify and the web framework to share the same
      // routes and they do content negotiation depending on `Accept` header:
      onNotAcceptable: async (request) => {
        const response = await next(request);
        if (response.status !== 404) return response;
        return new Response("Not Acceptable", {
          status: 406,
          headers: {
            "Content-Type": "text/plain",
            Vary: "Accept"
          },
        })
      }
    });
  };
}
```

In some cases, your web framework may not represent requests and responses
as [`Request`] and [`Response`] objects.  In that case, you need to convert
the request and response objects to the appropriate types that the `Federation`
object can handle.

[`Request`]: https://developer.mozilla.org/en-US/docs/Web/API/Request

[`Response`]: https://developer.mozilla.org/en-US/docs/Web/API/Response

---

---
url: /manual/kv.md
---
# Key–value store

*This API is available since Fedify 0.5.0.*

The `KvStore` interface is a crucial component in Fedify, providing a flexible
key–value storage solution for caching and maintaining internal data.
This guide will help you choose the right `KvStore` implementation for
your project and even create your own custom implementation if needed.

## Choosing a `KvStore` implementation

Fedify offers several `KvStore` implementations to suit different needs.

Choose the implementation that best fits your project's requirements,
considering factors like scalability, runtime environment, and distributed
nature of your system.

### `MemoryKvStore`

`MemoryKvStore` is a simple in-memory key–value store that doesn't persist data.
It's best suited for development and testing environments where data don't have
to be shared across multiple nodes.  No setup is required, making it easy to
get started.

Best for
:   Development and testing.

Pros
:   Simple, no setup required.

Cons
:   Data is not persistent, not suitable for production.

```typescript twoslash
import { createFederation, MemoryKvStore } from "@fedify/fedify";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
  // ... other options
});
```

### `SqliteKvStore`

To use the [`SqliteKvStore`], you need to install the *@fedify/sqlite* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/sqlite
```

```bash [npm]
npm add @fedify/sqlite
```

```bash [pnpm]
pnpm add @fedify/sqlite
```

```bash [Yarn]
yarn add @fedify/sqlite
```

```bash [Bun]
bun add @fedify/sqlite
```

:::

[`SqliteKvStore`] is a simple key–value store implementation that uses SQLite as
the backend storage. It provides persistent storage with minimal configuration.
It's suitable for development and testing. It uses native sqlite modules,
[`node:sqlite`] for Node.js and Deno, [`bun:sqlite`] for Bun.

Best for
:   Development and testing.

Pros
:   Simple, persistent with minimal configuration.

Cons
:   Limited scalability, not suitable for high-traffic production.

::: code-group

```typescript twoslash [Deno]
import { DatabaseSync } from "node:sqlite";
import { createFederation } from "@fedify/fedify";
import { SqliteKvStore } from "@fedify/sqlite";

const db = new DatabaseSync(":memory:");
const federation = createFederation<void>({
  // ...
  kv: new SqliteKvStore(db),
});
```

```typescript twoslash [Node.js]
import { DatabaseSync } from "node:sqlite";
import { createFederation } from "@fedify/fedify";
import { SqliteKvStore } from "@fedify/sqlite";

const db = new DatabaseSync(":memory:");
const federation = createFederation<void>({
  // ...
  kv: new SqliteKvStore(db),
});
```

```typescript [Bun]
import { Database } from "bun:sqlite";
import { createFederation } from "@fedify/fedify";
import { SqliteKvStore } from "@fedify/sqlite";

const db = new Database(":memory:");
const federation = createFederation<void>({
  // ...
  kv: new SqliteKvStore(db),
});
```

:::

> \[!TIP]
> If you are using Bun, you may encounter a type error in your IDE because
> TypeScript's language server runs on Node.js and resolves the
> `@fedify/sqlite` module using Node.js [conditional exports] instead of
> Bun's.  To fix this, add the following to your *tsconfig.json*:
>
> ```json
> {
>   "compilerOptions": {
>     "moduleResolution": "bundler",
>     "customConditions": ["bun"]
>   }
> }
> ```
>
> This tells TypeScript to use Bun's module resolution when resolving
> [conditional exports].

[`SqliteKvStore`]: https://jsr.io/@fedify/sqlite/doc/kv/~/SqliteKvStore

[`node:sqlite`]: https://nodejs.org/api/sqlite.html

[`bun:sqlite`]: https://bun.com/docs/api/sqlite

[conditional exports]: https://nodejs.org/api/packages.html#conditional-exports

### `DenoKvStore` (Deno only)

To use the [`DenoKvStore`], you need to install the *@fedify/denokv* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/denokv
```

:::

[`DenoKvStore`] is a key–value store implementation for [Deno] runtime that uses
Deno's built-in [`Deno.openKv()`] API. It provides persistent storage and good
performance for Deno environments.  It's suitable for production use in Deno
applications.

Best for
:   Production use in Deno environments.

Pros
:   Persistent storage, good performance, easy to set up.

Cons
:   Only available in Deno runtime.

```typescript
import { createFederation } from "@fedify/fedify";
import { DenoKvStore } from "@fedify/denokv";

const kv = await Deno.openKv();
const federation = createFederation<void>({
  kv: new DenoKvStore(kv),
  // ... other options
});
```

[`DenoKvStore`]: https://jsr.io/@fedify/denokv/doc/mq/~/DenoKvStore

[Deno]: https://deno.com/

[`Deno.openKv()`]: https://docs.deno.com/api/deno/~/Deno.openKv

### [`RedisKvStore`]

To use the [`RedisKvStore`], you need to install the *@fedify/redis* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/redis
```

```bash [npm]
npm add @fedify/redis
```

```bash [pnpm]
pnpm add @fedify/redis
```

```bash [Yarn]
yarn add @fedify/redis
```

```bash [Bun]
bun add @fedify/redis
```

:::

[`RedisKvStore`] is a key–value store implementation that uses Redis as
the backend storage. It provides scalability and high performance, making it
suitable for production use in distributed systems. It requires a Redis
server setup and maintenance.

Best for
:   Production use, distributed systems.

Pros
:   Scalable, supports clustering.

Cons
:   Requires Redis setup and maintenance.

```typescript twoslash
import { createFederation } from "@fedify/fedify";
import { RedisKvStore } from "@fedify/redis";
import Redis from "ioredis";

const redis = new Redis(); // Configure as needed
const federation = createFederation<void>({
  kv: new RedisKvStore(redis),
  // ... other options
});
```

[`RedisKvStore`]: https://jsr.io/@fedify/redis/doc/kv/~/RedisKvStore

### [`PostgresKvStore`]

To use the [`PostgresKvStore`], you need to install the *@fedify/postgres*
package first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/postgres
```

```bash [npm]
npm add @fedify/postgres
```

```bash [pnpm]
pnpm add @fedify/postgres
```

```bash [Yarn]
yarn add @fedify/postgres
```

```bash [Bun]
bun add @fedify/postgres
```

:::

[`PostgresKvStore`] is a key–value store implementation that uses PostgreSQL as
the backend storage. It provides scalability and high performance, making it
suitable for production use in distributed systems.  It requires a PostgreSQL
server setup and maintenance.

Best for
:   Production use, a system that already uses PostgreSQL.

Pros
:   Scalable, no additional setup required if already using PostgreSQL.

Cons
:   Requires PostgreSQL setup and maintenance.

```typescript{6-8} twoslash
import { createFederation } from "@fedify/fedify";
import { PostgresKvStore } from "@fedify/postgres";
import postgres from "postgres";

const federation = createFederation<void>({
  kv: new PostgresKvStore(
    postgres("postgresql://user:pass@localhost/db"),
  ),
  // ... other options
});
```

[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore

### [`MysqlKvStore`]

*This API is available since Fedify 2.1.0.*

To use the [`MysqlKvStore`], you need to install the *@fedify/mysql* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/mysql
```

```bash [npm]
npm add @fedify/mysql mysql2
```

```bash [pnpm]
pnpm add @fedify/mysql mysql2
```

```bash [Yarn]
yarn add @fedify/mysql mysql2
```

```bash [Bun]
bun add @fedify/mysql mysql2
```

:::

[`MysqlKvStore`] is a key-value store implementation that uses MySQL (or
MariaDB) as the backend storage.  It provides scalability and high performance,
making it suitable for production use in distributed systems.  It requires
a MySQL or MariaDB server setup and maintenance.

Best for
:   Production use, a system that already uses MySQL or MariaDB.

Pros
:   Scalable, no additional setup required if already using MySQL/MariaDB.

Cons
:   Requires MySQL/MariaDB setup and maintenance.

```typescript twoslash
import { createFederation } from "@fedify/fedify";
import { MysqlKvStore } from "@fedify/mysql";
import mysql from "mysql2/promise";

const pool = mysql.createPool("mysql://user:pass@localhost/db");
const federation = createFederation<void>({
  kv: new MysqlKvStore(pool),
  // ... other options
});
```

[`MysqlKvStore`]: https://jsr.io/@fedify/mysql/doc/kv/~/MysqlKvStore

### `WorkersKvStore` (Cloudflare Workers only)

*This API is available since Fedify 1.6.0.*

To use the [`WorkersKvStore`], you need to install the *@fedify/cfworkers*
package first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/cfworkers
```

```bash [npm]
npm add @fedify/cfworkers
```

```bash [pnpm]
pnpm add @fedify/cfworkers
```

```bash [Yarn]
yarn add @fedify/cfworkers
```

```bash [Bun]
bun add @fedify/cfworkers
```

:::

[`WorkersKvStore`] is a key–value store implementation for [Cloudflare Workers]
that uses Cloudflare's built-in [Cloudflare Workers KV] API.  It provides
persistent storage and good performance for Cloudflare Workers environments.
It's suitable for production use in Cloudflare Workers applications.

Best for
:   Production use in Cloudflare Workers environments.

Pros
:   Persistent storage, good performance, easy to set up.

Cons
:   Only available in Cloudflare Workers runtime.

```typescript twoslash
// @noErrors: 2345
import type { FederationBuilder } from "@fedify/fedify";
const builder = undefined as unknown as FederationBuilder<void>;
// ---cut-before---
import type { Federation } from "@fedify/fedify";
import { WorkersKvStore } from "@fedify/cfworkers";

export default {
  async fetch(request, env, ctx) {
    const federation: Federation<void> = await builder.build({
      kv: new WorkersKvStore(env.KV_BINDING),
    });
    return await federation.fetch(request, { contextData: undefined });
  }
} satisfies ExportedHandler<{ KV_BINDING: KVNamespace<string> }>;
```

> \[!NOTE]
> Since your `KVNamespace` is not bound to a global variable, but rather
> passed as an argument to the `fetch()` method, you need to instantiate
> your `Federation` object inside the `fetch()` method, rather than the top
> level.
>
> For better organization, you probably want to use a builder pattern to
> register your dispatchers and listeners before instantiating the `Federation`
> object.  See the [*Builder pattern for structuring*
> section](./federation.md#builder-pattern-for-structuring) for details.

[`WorkersKvStore`]: https://jsr.io/@fedify/cfworkers/doc/kv/~/WorkersKvStore

[Cloudflare Workers]: https://workers.cloudflare.com/

[Cloudflare Workers KV]: https://developers.cloudflare.com/kv/

## Implementing a custom `KvStore`

> \[!TIP]
> We are always looking to improve Fedify and add more `KvStore`
> implementations.  If you've created a custom implementation that you think
> would be useful to others, consider contributing it to the community by
> packaging it as a standalone module and sharing it on JSR and npm.

If the provided implementations don't meet your needs, you can create a custom
`KvStore`.  Here's a step-by-step guide:

### Implement the `KvStore` interface

Create a class that implements the `KvStore` interface.  The interface defines
four methods: `~KvStore.get()`, `~KvStore.set()`, `~KvStore.delete()`, and
`~KvStore.list()`, and optionally `~KvStore.cas()`.

```typescript twoslash
import type {
  KvStore,
  KvKey,
  KvStoreSetOptions,
  KvStoreListEntry,
} from "@fedify/fedify";

class MyCustomKvStore implements KvStore {
  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
    // Implement get logic
    // ---cut-start---
    return undefined;
    // ---cut-end---
  }

  async set(
    key: KvKey,
    value: unknown,
    options?: KvStoreSetOptions
  ): Promise<void> {
    // Implement set logic
  }

  async delete(key: KvKey): Promise<void> {
    // Implement delete logic
  }

  async cas(
    key: KvKey,
    expectedValue: unknown,
    newValue: unknown
  ): Promise<boolean> {
    // Implement compare-and-swap logic if needed
    // ---cut-start---
    return false;
    // ---cut-end---
  }

  async *list(prefix?: KvKey): AsyncIterable<KvStoreListEntry> {
    // Implement list logic
  }
}
```

### Handle `KvKey`

The `KvKey` is an array of strings. You'll need to convert it into a format
suitable for your storage backend. For example:

```typescript twoslash
import type { KvKey } from "@fedify/fedify";
class MyCustomKvStore {
// ---cut-before---
private serializeKey(key: KvKey): string {
  return key.join(':');
}
// ---cut-after---
}
```

> \[!NOTE]
> The above example uses a simple colon-separated string as the serialized key,
> but in practice, it probably needs to be more sophisticated to handle complex
> keys and avoid conflicts.

### Implement `~KvStore.get()` method

Retrieve the value associated with the key. Remember to handle cases where
the key doesn't exist:

```typescript twoslash
import type { KvStore, KvKey, KvStoreSetOptions } from "@fedify/fedify";
/**
 * A hypothetical storage interface.
 */
interface HypotheticalStorage {
  /**
   * A hypothetical method to retrieve a value by key.
   * @param key The key to retrieve.
   * @returns The value associated with the key.
   */
  retrieve(key: string): Promise<unknown>;
}
class MyCustomKvStore implements KvStore {
  /**
   * A hypothetical storage backend.
   */
  storage: HypotheticalStorage = {
   async retrieve(key: string): Promise<unknown> {
     return undefined;
   }
  };
  private serializeKey(key: KvKey): string { return ""; }
  async set(
    key: KvKey,
    value: unknown,
    options?: KvStoreSetOptions
  ): Promise<void> { }
  async delete(key: KvKey): Promise<void> { }
  async *list(): AsyncIterable<{ key: KvKey; value: unknown }> { }
// ---cut-before---
async get<T = unknown>(key: KvKey): Promise<T | undefined> {
  const serializedKey = this.serializeKey(key);
  // Retrieve value from your storage backend
  const value = await this.storage.retrieve(serializedKey);
  return value as T | undefined;
}
// ---cut-after---
}
```

### Implement `~KvStore.set()` method

Store the value with the given key. Handle the optional TTL if your backend
supports it:

```typescript twoslash
import type { KvStore, KvKey, KvStoreSetOptions } from "@fedify/fedify";
/**
 * A hypothetical storage interface.
 */
interface HypotheticalStorage {
  /**
   * A hypothetical method to set a value by key.
   * @param key The key to set.
   * @param value The value to set.
   */
  set(key: string, value: unknown): Promise<unknown>;
  /**
   * A hypothetical method to set a value by key with a time-to-live.
   * @param key The key to set.
   * @param value The value to set.
   * @param ttl The time-to-live in milliseconds.
   */
  setWithTtl(key: string, value: unknown, ttl: number): Promise<unknown>;
}
class MyCustomKvStore implements KvStore {
  /**
   * A hypothetical storage backend.
   */
  storage: HypotheticalStorage = {
   async set(key: string, value: unknown): Promise<void> { },
   async setWithTtl(key: string, value: unknown, ttl: number): Promise<void> { }
  };
  private serializeKey(key: KvKey): string { return ""; }
  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
    return undefined;
  }
  async delete(key: KvKey): Promise<void> { }
  async *list(): AsyncIterable<{ key: KvKey; value: unknown }> { }
// ---cut-before---
async set(
  key: KvKey,
  value: unknown,
  options?: KvStoreSetOptions,
): Promise<void> {
  const serializedKey = this.serializeKey(key);
  if (options?.ttl == null) {
    await this.storage.set(serializedKey, value);
  } else {
    // Set with TTL if supported
    await this.storage.setWithTtl(
      serializedKey,
      value,
      options.ttl.total('millisecond'),
    );
  }
}
// ---cut-after---
}
```

\*\[TTL]: time-to-live

### Implement `~KvStore.delete()` method

Remove the value associated with the key:

```typescript twoslash
import type { KvStore, KvKey, KvStoreSetOptions } from "@fedify/fedify";
/**
 * A hypothetical storage interface.
 */
interface HypotheticalStorage {
  /**
   * A hypothetical method to remove a value by key.
   * @param key The key to remove.
   */
  remove(key: string): Promise<void>;
}
class MyCustomKvStore implements KvStore {
  /**
   * A hypothetical storage backend.
   */
  storage: HypotheticalStorage = {
   async remove(key: string): Promise<void> { }
  };
  private serializeKey(key: KvKey): string { return ""; }
  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
    return undefined;
  }
  async set(
    key: KvKey,
    value: unknown,
    options?: KvStoreSetOptions
  ): Promise<void> { }
  async *list(): AsyncIterable<{ key: KvKey; value: unknown }> { }
// ---cut-before---
async delete(key: KvKey): Promise<void> {
  const serializedKey = this.serializeKey(key);
  await this.storage.remove(serializedKey);
}
// ---cut-after---
}
```

### Implement `~KvStore.cas()` method (optional)

If your storage backend supports compare-and-swap (CAS) operations, you can
implement the `~KvStore.cas()` method. This method allows you to atomically
update a value only if it matches the expected value. This is useful for
implementing optimistic concurrency control.

```typescript twoslash
import type { KvStore, KvKey, KvStoreSetOptions } from "@fedify/fedify";
/**
 * A hypothetical storage interface.
 */
interface HypotheticalStorage {
  /**
   * A hypothetical method to compare and swap a value by key.
   * @param key The key to compare and swap.
   * @param expectedValue The expected value to match.
   * @param newValue The new value to set if the expected value matches.
   * @returns True if the operation was successful, false otherwise.
   */
  compareAndSwap(
    key: string,
    expectedValue: unknown,
    newValue: unknown
  ): Promise<boolean>;
}
class MyCustomKvStore implements KvStore {
  /**
   * A hypothetical storage backend.
   */
  storage: HypotheticalStorage = {
   async compareAndSwap(
     key: string,
     expectedValue: unknown,
     newValue: unknown
   ): Promise<boolean> { return false; }
  };
  private serializeKey(key: KvKey): string { return ""; }
  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
    return undefined;
  }
  async set(
    key: KvKey,
    value: unknown,
    options?: KvStoreSetOptions
  ): Promise<void> { }
  async delete(key: KvKey): Promise<void> { }
  async *list(): AsyncIterable<{ key: KvKey; value: unknown }> { }
// ---cut-before---
async cas(
  key: KvKey,
  expectedValue: unknown,
  newValue: unknown
): Promise<boolean> {
  const serializedKey = this.serializeKey(key);
  return await this.storage.compareAndSwap(
    serializedKey,
    expectedValue,
    newValue
  );
}
// ---cut-after---
}
```

### Implement `~KvStore.list()` method

*This API is available since Fedify 1.10.0.*

*Since Fedify 2.0.0, this method is required instead of optional.*

The `~KvStore.list()` method allows you to enumerate all entries whose keys
start with a given prefix.  This is useful for implementing batch operations
or iterating over related entries.  If your storage backend supports prefix
scanning, you can use it to implement this method efficiently.

```typescript twoslash
import type {
  KvKey,
  KvStore,
  KvStoreListEntry,
  KvStoreSetOptions,
} from "@fedify/fedify";

/**
 * A hypothetical storage interface.
 */
interface HypotheticalStorage {
  /**
   * A hypothetical method to list entries by prefix.
   * @param prefix The prefix to filter by.
   * @returns An async iterable of key-value pairs.
   */
  scan(prefix: string): AsyncIterable<{ key: string; value: unknown }>;
}
class MyCustomKvStore implements KvStore {
  /**
   * A hypothetical storage backend.
   */
  storage: HypotheticalStorage = {
   async *scan(prefix: string): AsyncIterable<{ key: string; value: unknown }> {
   }
  };
  private serializeKey(key: KvKey): string { return ""; }
  private deserializeKey(key: string): KvKey {
    return key.split(":") as unknown as KvKey;
  }
  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
    return undefined;
  }
  async set(
    key: KvKey,
    value: unknown,
    options?: KvStoreSetOptions
  ): Promise<void> { }
  async delete(key: KvKey): Promise<void> { }
// ---cut-before---
async *list(prefix?: KvKey): AsyncIterable<KvStoreListEntry> {
  const serializedPrefix = prefix ? this.serializeKey(prefix) : "";
  for await (const { key, value } of this.storage.scan(serializedPrefix)) {
    yield {
      key: this.deserializeKey(key),
      value,
    };
  }
}
// ---cut-after---
}
```

The `~KvStore.list()` method takes an optional `prefix` parameter specifying
the key prefix to filter by.  If omitted or empty, it returns all entries.
It returns an `AsyncIterable` of `KvStoreListEntry` objects, each containing
a `~KvStoreListEntry.key` and a `~KvStoreListEntry.value`.

> \[!TIP]
> When implementing `~KvStore.list()`, make sure to:
>
> * Include the exact prefix key itself if it exists (not just keys that
>   have additional components after the prefix)
> * Filter out expired entries if your storage backend supports TTL
> * Handle pagination efficiently for large datasets

### Use your custom `KvStore`

That's it! You can now use your custom `KvStore` implementation with Fedify:

```typescript twoslash
import { KvStore, KvKey, KvStoreSetOptions } from "@fedify/fedify";
class MyCustomKvStore implements KvStore {
  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
    return undefined;
  }
  async set(
    key: KvKey,
    value: unknown,
    options?: KvStoreSetOptions
  ): Promise<void> {
  }
  async delete(key: KvKey): Promise<void> {
  }
  async *list(): AsyncIterable<{ key: KvKey; value: unknown }> {
  }
}
// ---cut-before---
import { createFederation } from "@fedify/fedify";

const customKvStore = new MyCustomKvStore();
const federation = createFederation<void>({
  kv: customKvStore,
  // ... other options
});
```

---

---
url: /tutorial/basics.md
description: >-
  This tutorial provides a step-by-step guide to building a small federated
  server with the Fedify framework.  It is intended for developers who want to
  build a federated server with the Fedify framework.
---

# Learning the basics of Fedify

> \[!TIP]
>
> This tutorial is also available in the following languages: [한국어] (Korean).

In this tutorial, we will build a small federated server that can only accept
follow requests to understand the basic concepts of the Fedify framework.
Despite its simplicity, it will cover the key features of the
ActivityPub protocol and the Fedify framework, such as actors, sending and
receiving activities, and the inbox.

This tutorial will not use the quick start project template created by the
[`fedify init`](../cli.md#fedify-init-initializing-a-fedify-project) command.
Instead, we will start from scratch to understand how the Fedify framework
works without any boilerplate code.

As prerequisite knowledge, you should have a basic understanding of
JavaScript, command-line interfaces, and minimum experience with building
web server apps.  However, it's perfectly fine if you're not familiar with
the ActivityPub protocol or TypeScript; we will explain them as we go.

[한국어]: https://hackmd.io/@OKSUchun/fedify-tutorial-ko

## What we will build

We will build a small federated server which can accept follow requests from
other servers.  The server will have a single actor (i.e., account) and an inbox
to receive follow requests.  When the server receives a follow request, it will
send an accept activity back to the sender.  The home page of the server will
list the actor's followers.

## Creating a new project

> \[!TIP]
> We recommend using [Deno] or [Bun] (which are TypeScript-first) for the best
> experience, but you can use [Node.js] if you prefer.

Let's create a new project directory and initialize a new project:

::: code-group

```sh [Deno]
mkdir follow-server
cd follow-server/
echo '{ "unstable": ["kv"] }' > deno.json
deno add jsr:@fedify/fedify
```

```sh [Bun]
mkdir follow-server
cd follow-server/
echo '{ "type": "module" }' > package.json
bun add @fedify/fedify @deno/kv
```

```sh [Node.js]
mkdir follow-server
cd follow-server/
echo '{ "type": "module" }' > package.json
npm add -D typescript tsx @types/node
npm add @fedify/fedify @deno/kv @hono/node-server
```

:::

The above commands will create a *deno.json* (in case of Deno) or *package.json*
(in case of Node.js or Bun) in the project directory with the following content
(formatted for readability):\[^2]

::: code-group

```json [Deno]
{
  "unstable": ["kv"],
  "imports": {
    "@fedify/fedify": "jsr:@fedify/fedify@^1.1.0"
  }
}
```

```json [Bun]
{
  "type": "module",
  "dependencies": {
    "@deno/kv": "^0.8.1",
    "@fedify/fedify": "^1.1.0"
  }
}
```

```json [Node.js]
{
  "type": "module",
  "devDependencies": {
    "@types/node": "^20.12.7",
    "tsx": "^4.8.2",
    "typescript": "^5.4.5"
  },
  "dependencies": {
    "@deno/kv": "^0.8.1",
    "@fedify/fedify": "^1.1.0",
    "@hono/node-server": "^1.11.1"
  }
}
```

:::

> \[!NOTE]
> If you use Deno 2.7.0 or later, you do not need any extra setting for
> [`Temporal`].  If you use Deno earlier than 2.7.0, add `"temporal"` to the
> [`"unstable"`] field in *deno.json*.

> \[!NOTE]
> In Bun and Node.js, we recommend adding [`"type": "module"`] to the
> *package.json* file to use [ESM] imports. While Fedify also supports
> [CommonJS] for legacy compatibility, ESM is the preferred and recommended
> approach.

> \[!TIP]
> Do you wonder why we need to add *[tsx]* and *@types/node* in the case of
> Node.js?  It's because Fedify is written in TypeScript, and
> Node.js doesn't support TypeScript out of the box.  By adding *tsx* and
> *@types/node*, you can write TypeScript code in Node.js without any hassle.

\[^2]: The actual version number may vary depending on the latest version of the
Fedify framework as of reading this tutorial.

[Deno]: https://deno.com/

[Bun]: https://bun.sh/

[Node.js]: https://nodejs.org/

[`Temporal`]: https://tc39.es/proposal-temporal/docs/

[`"unstable"`]: https://docs.deno.com/runtime/manual/tools/unstable_flags/#configuring-flags-in-deno.json

[`"type": "module"`]: https://nodejs.org/api/packages.html#type

[ESM]: https://nodejs.org/api/esm.html

[CommonJS]: https://nodejs.org/docs/latest/api/modules.html

[tsx]: https://tsx.is/

## Creating the server

Now, let's create the server script.  Create a new file named *server.ts* in the
project directory and write the following code:

::: code-group

```typescript twoslash [Deno]
Deno.serve(request =>
  new Response("Hello, world", {
    headers: { "Content-Type": "text/plain" }
  })
);
```

```typescript twoslash [Bun]
import "@types/bun";
// ---cut-before---
Bun.serve({
  port: 8000,
  fetch(request) {
    return new Response("Hello, world", {
      headers: { "Content-Type": "text/plain" }
    });
  }
});
```

```typescript twoslash [Node.js]
import { serve } from "@hono/node-server";

serve({
  port: 8000,
  fetch(request) {
    return new Response("Hello, world", {
      headers: { "Content-Type": "text/plain" }
    });
  }
});
```

:::

It's a simple HTTP server that responds with Hello, world to any incoming
request.  You can run the server by executing the following command:

::: code-group

```sh [Deno]
deno run -A server.ts
```

```sh [Bun]
bun server.ts
```

```sh [Node.js]
node --import tsx server.ts
```

::::

Now, open your web browser and navigate to <http://localhost:8000/>.  You should
see the Hello, world message.

As you can guess, [`Deno.serve()`] (in case of Deno), [`Bun.serve()`] (in case
of Bun), and [`serve()`] (in case of Node.js) are functions to create an HTTP
server.  They take a callback function that receives a [`Request`] object and
returns a [`Response`] object. The `Response` object is sent back to the client.

This server is not federated yet, but it's a good starting point to build a
federated server.

[`Deno.serve()`]: https://docs.deno.com/api/deno/~/Deno.serve

[`Bun.serve()`]: https://bun.sh/docs/api/http#bun-serve

[`serve()`]: https://github.com/honojs/node-server?tab=readme-ov-file#usage

[`Request`]: https://developer.mozilla.org/en-US/docs/Web/API/Request

[`Response`]: https://developer.mozilla.org/en-US/docs/Web/API/Response

## `Federation` object

To make the server federated, we need to use the `Federation` object from the
Fedify framework.  The `Federation` object is the main object that handles
ActivityPub activities and actors.  Let's modify the server script to use the
`Federation` object:

```typescript twoslash [server.ts]
import { createFederation, MemoryKvStore } from "@fedify/fedify";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
});
```

In the above code, we import the `createFederation()` function from the Fedify
framework to create a new `Federation` object.  We pass an object to the
`createFederation()` function, which is the configuration object.
The `kv` property is a key–value store that is used to store several internal
data of the `Federation` object.  We use the `MemoryKvStore` to open
a key–value store.

> \[!IMPORTANT]
> Since `MemoryKvStore` is for testing and development purposes, you should
> use a persistent key–value store like `DenoKvStore` (in Deno) or
> [`RedisKvStore`] (from [`@fedify/redis`] package) or [`PostgresKvStore`]
> (from [`@fedify/postgres`] package) or [`MysqlKvStore`]
> (from [`@fedify/mysql`] package) for production use.
>
> For further details, see the [*Key–value store* section](../manual/kv.md).

Then, we pass the incoming `Request` to the `Federation.fetch()` method:

::: code-group

```typescript{2} twoslash [Deno]
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
Deno.serve(
  request => federation.fetch(request, { contextData: undefined })
);
```

```typescript{4} twoslash [Bun]
import "@types/bun";
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
Bun.serve({
  port: 8000,
  fetch(request) {
    return federation.fetch(request, { contextData: undefined });
  }
});
```

```typescript{6} twoslash [Node.js]
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { serve } from "@hono/node-server";

serve({
  port: 8000,
  fetch(request) {
    return federation.fetch(request, { contextData: undefined });
  }
});
```

:::

The `Federation.fetch()` method takes the incoming `Request` and a few options.
In this case, we pass `undefined` as the `contextData` because we don't
need to share any context data here.

> \[!TIP]
> The `Federation` object is a generic class that takes a type parameter named
> `TContextData`.  The `TContextData` type is the type of the context data,
> which is shared among the actor dispatcher, inbox listener, and other
> callback functions.  The `TContextData` type can be `void` if you don't
> need to share any context data, but it can be any type if you need to share
> context data.
>
> See [*`TContextData`* section](../manual/federation.md#tcontextdata) for more
> details.

The `Federation` object is now ready to handle incoming requests.  Let's move on
to the next step.

> \[!TIP]
> Although it's not mandatory, we highly recommend to set up loggers to see
> what's going on in the server.  To set up loggers, you need to install
> [LogTape] first:
>
> ::: code-group
>
> ```sh [Deno]
> deno add jsr:@logtape/logtape
> ```
>
> ```sh [Bun]
> bun add @logtape/logtape
> ```
>
> ```sh [Node.js]
> npm add @logtape/logtape
> ```
>
> :::
>
> Then, you can set up loggers by calling [`configure()`] function at the
> top of the *server.ts* file:
>
> ```typescript twoslash [server.ts]
> import { configure, getConsoleSink } from "@logtape/logtape";
>
> await configure({
>   sinks: { console: getConsoleSink() },
>   filters: {},
>   loggers: [
>     { category: "fedify",  sinks: ["console"], lowestLevel: "info" },
>   ],
> });
> ```

[`RedisKvStore`]: https://jsr.io/@fedify/redis/doc/kv/~/RedisKvStore

[`@fedify/redis`]: https://github.com/fedify-dev/fedify/tree/main/packages/redis

[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore

[`@fedify/postgres`]: https://github.com/fedify-dev/fedify/tree/main/packages/postgres

[`MysqlKvStore`]: https://jsr.io/@fedify/mysql/doc/kv/~/MysqlKvStore

[`@fedify/mysql`]: https://github.com/fedify-dev/fedify/tree/main/packages/mysql

[LogTape]: https://logtape.org/

[`configure()`]: https://jsr.io/@logtape/logtape/doc/~/configure

## Actor dispatcher

The `Federation` object needs an actor dispatcher to handle incoming activities
from other servers.  The actor dispatcher is a function that is called when
an incoming activity is addressed to an actor on the server.

As mentioned earlier, there will be only one actor (i.e., account) on
the server.  We will name its identifier as *me* (you can choose any identifier
you like).

Let's create an actor dispatcher for our server:

::: code-group

```typescript{7-16} twoslash [Deno]
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { Person } from "@fedify/vocab";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
});

federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  if (identifier !== "me") return null;  // Other than "me" is not found.
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "Me",  // Display name
    summary: "This is me!",  // Bio
    preferredUsername: identifier,  // Bare handle
    url: new URL("/", ctx.url),
  });
});

Deno.serve(
  request => federation.fetch(request, { contextData: undefined })
);
```

```typescript{7-16} twoslash [Bun]
import "@types/bun";
// ---cut-before---
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { Person } from "@fedify/vocab";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
});

federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  if (identifier !== "me") return null;  // Other than "me" is not found.
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "Me",  // Display name
    summary: "This is me!",  // Bio
    preferredUsername: identifier,  // Bare handle
    url: new URL("/", ctx.url),
  });
});

Bun.serve({
  port: 8000,
  fetch(request) {
    return federation.fetch(request, { contextData: undefined });
  }
});
```

```typescript{8-17} twoslash [Node.js]
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
import { serve } from "@hono/node-server";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
});

federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  if (identifier !== "me") return null;  // Other than "me" is not found.
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "Me",  // Display name
    summary: "This is me!",  // Bio
    preferredUsername: identifier,  // Bare handle
    url: new URL("/", ctx.url),
  });
});

serve({
  port: 8000,
  fetch(request) {
    return federation.fetch(request, { contextData: undefined });
  }
});
```

:::

In the above code, we use the `~Federatable.setActorDispatcher()` method to set
an actor dispatcher for the server.  The first argument is the path pattern
for the actor, and the second argument is a callback function that takes
a `Context` object and the actor's identifier.  The callback function should
return an `Actor` object or `null` if the actor is not found.  In this case,
we return a `Person` object for the actor *me*.

Alright, we have an actor on the server.  Let's see if it works by querying
WebFinger for the actor.  Run the server by executing the following command:

::: code-group

```sh [Deno]
deno run -A server.ts
```

```sh [Bun]
bun run server.ts
```

```sh [Node.js]
node --import tsx server.ts
```

:::

Now, open a new terminal session and run the following command to query the
actor:\[^3]

```sh
curl "http://localhost:8000/.well-known/webfinger?resource=acct:me@localhost:8000"
```

The response should look like this (formatted for readability):

```json
{
  "subject": "acct:me@localhost:8000",
  "aliases": [
    "http://localhost:8000/users/me"
  ],
  "links": [
    {
      "rel": "self",
      "href": "http://localhost:8000/users/me",
      "type": "application/activity+json"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "href": "http://localhost:8000/"
    }
  ]
}
```

The above response shows that the actor *me* is found on the server, and its
canonical URI is `http://localhost:8000/users/me`.  Let's see what happens when
we query the actor's canonical URI (note that the request contains
the `Accept: application/activity+json` header):\[^3]

```sh
curl -H"Accept: application/activity+json" http://localhost:8000/users/me
```

The response should look like this (formatted for readability):

```json
{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {
      "toot": "http://joinmastodon.org/ns#",
      "discoverable": "toot:discoverable",
      "suspended": "toot:suspended",
      "memorial": "toot:memorial",
      "indexable": "toot:indexable"
    }
  ],
  "id": "http://localhost:8000/users/me",
  "type": "Person",
  "name": "Me",
  "preferredUsername": "me",
  "summary": "This is me!",
  "url": "http://localhost:8000/"
}
```

The response shows the actor *me* with its basic information.

Requests we've made so far are what ordinary ActivityPub implementations
do behind the scenes when they try to look up an actor (i.e., account).
For example, when you search with a full handle of an actor on Mastodon,
a Mastodon instance queries the WebFinger endpoint to find the actor's
canonical URI and then queries the canonical URI to get the actor's profile.

However, you still can't follow the actor *me* from other ActivityPub servers,
because our server is not exposed to the public internet yet.  We will cover
this in the next section.

> \[!TIP]
> If you are curious about the actor dispatcher further, see the
> [*Actor dispatcher* section](../manual/actor.md) in the manual.

\[^3]: It assumes that you have [curl] installed on your system. If you don't
have curl, you need to install it first.

[curl]: https://curl.se/

## Exposing the server to the public internet

To expose the server to the public internet, generally, you need a proper domain
name configured with a DNS record pointing to your server's IP address.
However, for local development, you can use the
[`fedify tunnel`](../cli.md#fedify-tunnel-exposing-a-local-http-server-to-the-public-internet)
command to temporarily expose your server to the public internet.

To use `fedify tunnel`, first make sure you have the `fedify` command installed.
If you haven't installed it yet, please follow the installation instructions in
the [*`fedify`: CLI toolchain* section](../cli.md#installation).

After installing the `fedify` command, you can expose your server to the public
internet by running the following command (note that you need to run this
command in a new terminal session so that the server is still running):

```sh
fedify tunnel 8000
```

The above command will expose your server to the public internet.  You will see
a public URL that you can use to access your server from the internet, e.g.:

```console
✔ Your local server at 8000 is now publicly accessible:

https://e875a03fc2a35b.lhr.life/

Press ^C to close the tunnel.
```

> \[!NOTE]
> Do not rely on `fedify tunnel` for production use.  It is only for local
> development.  The domain name it provides is temporary and will change every
> time you restart the command.

However, since `fedify tunnel` is a reverse proxy between the public internet
and your server, the server is still not aware of the fact that it is exposed to
the public internet through HTTPS.  In order to make the server aware of it,
you need to place a [x-forwarded-fetch] middleware in front of the `Federation`.

To do this, you need to install the package:

::: code-group

```sh [Deno]
deno add jsr:@hongminhee/x-forwarded-fetch
```

```sh [Bun]
bun add x-forwarded-fetch
```

```sh [Node.js]
npm add x-forwarded-fetch
```

:::

Then, import the package and place the `behindProxy()` middleware in front of
the `Federation.fetch()` method:

::: code-group

```typescript{1,4} twoslash [Deno]
// @noErrors: 2300 2307
import { behindProxy } from "x-forwarded-fetch";
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { behindProxy } from "@hongminhee/x-forwarded-fetch";

Deno.serve(
  behindProxy(request => federation.fetch(request, { contextData: undefined }))
);
```

```typescript{1,5} twoslash [Bun]
import "@types/bun";
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { behindProxy } from "x-forwarded-fetch";

Bun.serve({
  port: 8000,
  fetch: behindProxy((request) => federation.fetch(request, { contextData: undefined })),
});
```

```typescript{2,6} twoslash [Node.js]
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { serve } from "@hono/node-server";
import { behindProxy } from "x-forwarded-fetch";

serve({
  port: 8000,
  fetch: behindProxy((request) => federation.fetch(request, { contextData: undefined })),
});
```

:::

To restart the server, you need to stop the server by pressing ^C and
then run the server again:

::: code-group

```sh [Deno]
deno run -A server.ts
```

```sh [Bun]
bun run server.ts
```

```sh [Node.js]
node --import tsx server.ts
```

:::

Let's query the actor *me* again, but this time with the public URL (change
the domain name to the one `fedify tunnel` provides you):\[^3]

```sh
curl "https://e875a03fc2a35b.lhr.life/.well-known/webfinger?resource=acct:me@e875a03fc2a35b.lhr.life"
curl -H"Accept: application/activity+json" https://e875a03fc2a35b.lhr.life/users/me
```

Does it work?  If so, congratulations!  Your server is now exposed to the
public internet.  However, you still can't follow the actor *me* from other
ActivityPub servers because our server doesn't accept follow requests yet.

> \[!TIP]
> There are alternatives to `fedify tunnel`.  See also the [*Exposing a local
> server to the public*
> section](../manual/test.md#exposing-a-local-server-to-the-public) in the
> manual for more details.

[x-forwarded-fetch]: https://github.com/dahlia/x-forwarded-fetch

## Inbox listener

In ActivityPub, an [inbox] is where an actor receives incoming activities from
other actors.  To accept follow requests from other servers, we need to register
an inbox listener for the actor *me*.

Let's register an inbox listener for the actor *me*.  First, every
activity is represented as a class in the Fedify framework.  The `Follow` class
represents the `Follow` activity.  We will use the `Follow` class to handle
incoming follow requests:

```typescript twoslash [server.ts]
import { createFederation, MemoryKvStore } from "@fedify/fedify";
import { Follow, Person } from "@fedify/vocab";  // [!code highlight]
```

Then, we register an inbox listener for the `Follow` activity:

```typescript{3-11} twoslash [server.ts]
import { type Federation } from "@fedify/fedify";
import { Follow } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    if (follow.id == null || follow.actorId == null || follow.objectId == null) {
      return;
    }
    const parsed = ctx.parseUri(follow.objectId);
    if (parsed?.type !== "actor" || parsed.identifier !== "me") return;
    const follower = await follow.getActor(ctx);
    console.debug(follower);
  });
```

Yet, the above code doesn't do anything other than printing the follower's
information to the console.  We will send an accept activity back to the sender
when we receive a follow request in the next section, but here we just see
who the follower is.

In order to test the inbox listener, the actor *me* needs to point out its inbox
URI in the actor object.  Let's modify the actor dispatcher to include the inbox
URI:

```typescript twoslash [server.ts]
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
  if (identifier !== "me") return null;
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "Me",
    summary: "This is me!",
    preferredUsername: identifier,
    url: new URL("/", ctx.url),
    inbox: ctx.getInboxUri(identifier),  // Inbox URI // [!code highlight]
  });
});
```

Now, let's restart the server and look up the actor *me* again, but this time
on your Mastodon instance (or any other ActivityPub server you have account on).
To look up the actor *me*, you need to search with the full handle of the actor
(i.e., *@me@your-server-domain*):

![Search results on Mastodon; the actor @me shows up.](/assets/search-result.B_h66_4S.png)

When you find the actor *me*, click on the actor's profile and then click on
the *Follow* button.  You should see your Mastodon account sending a follow
request to the actor *me* on the console where the server is running:

```
Person {
  id: URL "...",
  name: "...",
  ... omitted for brevity ...
}
```

However, the server doesn't send an accept activity back to the sender yet.
We will cover this in the next section.

> \[!TIP]
> If you are curious about the inbox listener further, see the
> [*Inbox listeners* section](../manual/inbox.md) in the manual.

[inbox]: https://www.w3.org/TR/activitypub/#inbox

## Generating a key pair

To send an activity, first, we need to generate a key pair for the actor *me*
so that the server can sign the activity with the private key.  Fortunately,
Fedify provides helper functions to generate and export/import keys:

```typescript{3-5} twoslash [server.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
  MemoryKvStore,
} from "@fedify/fedify";
import { Follow, Person } from "@fedify/vocab";
```

By the way, when should we generate a key pair?  In general, you should generate
a key pair when the actor is created.  In our case, we generate a key pair when
the actor *me* is dispatched for the first time.  Then, we store the key pair
in the key–value store so that the server can use the key pair later.

The `~ActorCallbackSetters.setKeyPairsDispatcher()` method is used to set a key
pairs dispatcher for the actor.  The key pairs dispatcher is a function that is
called when the key pairs of an actor is needed.  Let's set a key pairs
dispatcher for the actor *me*.  `~ActorCallbackSetters.setKeyPairsDispatcher()`
method should be chained after the `~Federatable.setActorDispatcher()` method:

::: code-group

```typescript{13-14,17-37} twoslash [Deno]
import {
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
  type Federation,
} from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
const kv = await Deno.openKv();  // Open the key–value store

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier !== "me") return null;
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "Me",
      summary: "This is me!",
      preferredUsername: identifier,
      url: new URL("/", ctx.url),
      inbox: ctx.getInboxUri(identifier),
      // The public keys of the actor; they are provided by the key pairs
      // dispatcher we define below:
      publicKeys: (await ctx.getActorKeyPairs(identifier))
        .map(keyPair => keyPair.cryptographicKey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    if (identifier != "me") return [];  // Other than "me" is not found.
    const entry = await kv.get<{
      privateKey: JsonWebKey;
      publicKey: JsonWebKey;
    }>(["key"]);
    if (entry == null || entry.value == null) {
      // Generate a new key pair at the first time:
      const { privateKey, publicKey } =
        await generateCryptoKeyPair("RSASSA-PKCS1-v1_5");
      // Store the generated key pair to the Deno KV database in JWK format:
      await kv.set(
        ["key"],
        {
          privateKey: await exportJwk(privateKey),
          publicKey: await exportJwk(publicKey),
        }
      );
      return [{ privateKey, publicKey }];
    }
    // Load the key pair from the Deno KV database:
    const privateKey = await importJwk(entry.value.privateKey, "private");
    const publicKey =  await importJwk(entry.value.publicKey, "public");
    return [{ privateKey, publicKey }];
  });
```

```typescript{15-16,19-39} twoslash [Bun]
// @noErrors: 2307
import {
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
  type Federation,
} from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { serialize as encodeV8, deserialize as decodeV8 } from "node:v8";
import { openKv } from "@deno/kv";

// Open the key–value store:
const kv = await openKv("kv.db", { encodeV8, decodeV8 });

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier !== "me") return null;
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "Me",
      summary: "This is me!",
      preferredUsername: identifier,
      url: new URL("/", ctx.url),
      inbox: ctx.getInboxUri(identifier),
      // The public keys of the actor; they are provided by the key pairs
      // dispatcher we define below:
      publicKeys: (await ctx.getActorKeyPairs(identifier))
        .map(keyPair => keyPair.cryptographicKey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    if (identifier != "me") return [];  // Other than "me" is not found.
    const entry = await kv.get<{
      privateKey: JsonWebKey;
      publicKey: JsonWebKey;
    }>(["key"]);
    if (entry == null || entry.value == null) {
      // Generate a new key pair at the first time:
      const { privateKey, publicKey } =
        await generateCryptoKeyPair("RSASSA-PKCS1-v1_5");
      // Store the generated key pair to the Deno KV database in JWK format:
      await kv.set(
        ["key"],
        {
          privateKey: await exportJwk(privateKey),
          publicKey: await exportJwk(publicKey),
        }
      );
      return [{ privateKey, publicKey }];
    }
    // Load the key pair from the Deno KV database:
    const privateKey = await importJwk(entry.value.privateKey, "private");
    const publicKey =  await importJwk(entry.value.publicKey, "public");
    return [{ privateKey, publicKey }];
  });
```

```typescript{15-16,19-39} twoslash [Node.js]
import {
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
  type Federation,
} from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
import { openKv } from "@deno/kv";

const kv = await openKv("kv.db");  // Open the key–value store

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier !== "me") return null;
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "Me",
      summary: "This is me!",
      preferredUsername: identifier,
      url: new URL("/", ctx.url),
      inbox: ctx.getInboxUri(identifier),
      // The public keys of the actor; they are provided by the key pairs
      // dispatcher we define below:
      publicKeys: (await ctx.getActorKeyPairs(identifier))
        .map(keyPair => keyPair.cryptographicKey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    if (identifier != "me") return [];  // Other than "me" is not found.
    const entry = await kv.get<{
      privateKey: JsonWebKey;
      publicKey: JsonWebKey;
    }>(["key"]);
    if (entry == null || entry.value == null) {
      // Generate a new key pair at the first time:
      const { privateKey, publicKey } =
        await generateCryptoKeyPair("RSASSA-PKCS1-v1_5");
      // Store the generated key pair to the Deno KV database in JWK format:
      await kv.set(
        ["key"],
        {
          privateKey: await exportJwk(privateKey),
          publicKey: await exportJwk(publicKey),
        }
      );
      return [{ privateKey, publicKey }];
    }
    // Load the key pair from the Deno KV database:
    const privateKey = await importJwk(entry.value.privateKey, "private");
    const publicKey =  await importJwk(entry.value.publicKey, "public");
    return [{ privateKey, publicKey }];
  });
```

:::

In the above code, we use the `~ActorCallbackSetters.setKeyPairsDispatcher()`
method to set a key pairs dispatcher for the actor *me*.  The key pairs
dispatcher is called when the key pairs of an actor is needed. The key pairs
dispatcher should return an array of objects that contain the private key
and the public key of the actor.  In this case, we generate a new key pair
at the first time and store it in the key–value store.  When the actor *me* is
dispatched again, the key pairs dispatcher loads the key pair from the key–value
store.

> \[!NOTE]
> Although we use the Deno KV database in this tutorial, you can use any
> other your favorite database to store the key pair.  The key–value store
> is just an example.

Restart the server and make an HTTP request to the actor *me* using `curl`.
Now you should see the actor *me* with the public key in the response:

```json {16-21}
{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {
      "toot": "http://joinmastodon.org/ns#",
      "discoverable": "toot:discoverable",
      "suspended": "toot:suspended",
      "memorial": "toot:memorial",
      "indexable": "toot:indexable"
    }
  ],
  "id": "https://e875a03fc2a35b.lhr.life/users/me",
  "type": "Person",
  "inbox": "https://e875a03fc2a35b.lhr.life/users/me/inbox",
  "publicKey": {
    "id": "https://e875a03fc2a35b.lhr.life/users/me#main-key",
    "type": "CryptographicKey",
    "owner": "https://e875a03fc2a35b.lhr.life/users/me",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0kptPO/arJVTv1qBzISP\nhJC8MZSut20FHZuJFON/kTscQT19eP2zGC9qDnQVl1vOXrvFybPWMjQP4p2x1/VM\np0wnY2EzKsdU4+lKfHsjd0VU2+TJvPtZ/AqJAG3PLMXeN7E5RpeUTwdTr9fkyrHE\n0M8n8yWG1AMtXp5pzhR/Le8uHmuSjbgJxIZPZOj8T6ZdMXKxudF0H/i0IB60lN9D\nt5tOzajmE5jvZD0mapdIDhghidGBu77fgopKmBtNn3IDjLJLXIh3dp7NICl1czHB\ntVtU1c2kmNPXq1WSndQgokN4CXNoy/BqTKo4VhIOWWb/oGaTZOWflFM5EXWTJUxK\n8JFyCD/1KVJXYEd662y+r400oDJqHKHhG78yud83PD4bpbJm/t7BD7RgO95g/rpN\nwi8mjLQVp7Y9ttXGf3lEgbBPZfPr0pm3X4ppoDAwtzVO7RmfboSb9ECa9uwQc1VG\nse3yNi7bDrHIu+HjBzk+glELcW2Hj4t4s/PPX9g0fH3UHgME1Pysz3Y8OZZeJlTu\n1yYcCg9X/dMV1qxxon6b8XhIEttW+RZjJunmtzOt1sKf2NM2jPXv+ZmFRao1eOzo\nvcVI/eeXV+1LDhHtTQJGnLObqnHnVdg3Qiaao176KOxrKh4/l6kJmaq/pw8+ZSkE\nzxUovxHGCJ0UqqgcaPsBsJMCAwEAAQ==\n-----END PUBLIC KEY-----"
  },
  "name": "Me",
  "preferredUsername": "me",
  "summary": "This is me!",
  "url": "https://e875a03fc2a35b.lhr.life/"
}
```

Alright, we have the public key of the actor *me*.  Let's move on to the next
section to send an accept activity back to the sender when we receive a follow
request.

> \[!TIP]
> If you are curious about the key pairs dispatcher further, see the
> [*Public keys of an `Actor`*
> section](../manual/actor.md#public-keys-of-an-actor) in the manual.

## Sending an `Accept` activity

When the server receives a follow request, it should send an `Accept` or
`Reject` activity back to the sender.  The `Accept` activity is a response to
the follow request and indicates that the follow request is accepted.

Let's import the `Accept` class from the Fedify framework:

```typescript twoslash [server.ts]
import {
  createFederation,
  exportJwk,
  generateCryptoKeyPair,
  importJwk,
} from "@fedify/fedify";
import {
  Accept,  // [!code highlight]
  Follow,
  Person,
} from "@fedify/vocab";
```

Then, we modify the inbox listener to send an `Accept` activity back to the
follower when we receive a follow request:

```typescript{10-17} twoslash [server.ts]
import { type Federation } from "@fedify/fedify";
import { Accept, Follow } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    if (follow.id == null || follow.actorId == null || follow.objectId == null) {
      return;
    }
    const parsed = ctx.parseUri(follow.objectId);
    if (parsed?.type !== "actor" || parsed.identifier !== "me") return;
    const follower = await follow.getActor(ctx);
    if (follower == null) return;
    // Note that if a server receives a `Follow` activity, it should reply
    // with either an `Accept` or a `Reject` activity.  In this case, the
    // server automatically accepts the follow request:
    await ctx.sendActivity(
      { identifier: parsed.identifier },
      follower,
      new Accept({ actor: follow.objectId, object: follow }),
    );
  });
```

Restart the server, and make a follow request from your Mastodon account to
the actor *me*.  You should see the server immediately accept the follow
request.

> \[!TIP]
> If you are curious about sending activities further, see the [*Sending
> activities* section](../manual/send.md) in the manual.

## Listing followers

The server should list the actor's followers on the home page.  To do this,
we need to store the followers in the key–value store.  We will store each
`Follow` activity's ID as the key and the follower's actor ID as the value:

```typescript{16-17} twoslash [server.ts]
import { type Federation } from "@fedify/fedify";
import { Accept, Follow } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
const kv = await Deno.openKv();
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Follow, async (ctx, follow) => {
    if (follow.id == null || follow.actorId == null || follow.objectId == null) {
      return;
    }
    const parsed = ctx.parseUri(follow.objectId);
    if (parsed?.type !== "actor" || parsed.identifier !== "me") return;
    const follower = await follow.getActor(ctx);
    if (follower == null) return;
    await ctx.sendActivity(
      { identifier: parsed.identifier },
      follower,
      new Accept({ actor: follow.objectId, object: follow }),
    );
    // Store the follower in the key–value store:
    await kv.set(["followers", follow.id.href], follow.actorId.href);
  });
```

Now, we need to make the home page to show the actor's followers.  Let's modify
the script inside the fetch function:

::: code-group

```typescript{2-16} twoslash [Deno]
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
const kv = await Deno.openKv();
// ---cut-before---
Deno.serve(async (request) => {
  const url = new URL(request.url);
  // The home page:
  if (url.pathname === "/") {
    const followers: string[] = [];
    for await (const entry of kv.list<string>({ prefix: ["followers"] })) {
      if (followers.includes(entry.value)) continue;
      followers.push(entry.value);
    }
    return new Response(
      `<ul>${followers.map((f) => `<li>${f}</li>`)}</ul>`,
      {
        headers: { "Content-Type": "text/html; charset=utf-8" },
      },
    );
  }

  // The federation-related requests are handled by the Federation object:
  return await federation.fetch(request, { contextData: undefined });
});
```

```typescript{4-18} twoslash [Bun]
import "@types/bun";
import type { Federation } from "@fedify/fedify";
import { openKv } from "@deno/kv";
const federation = null as unknown as Federation<void>;
const kv = await openKv();
// ---cut-before---
Bun.serve({
  port: 8000,
  async fetch(request) {
    const url = new URL(request.url);
    // The home page:
    if (url.pathname === "/") {
      const followers: string[] = [];
      for await (const entry of kv.list<string>({ prefix: ["followers"] })) {
        if (followers.includes(entry.value)) continue;
        followers.push(entry.value);
      }
      return new Response(
        `<ul>${followers.map((f) => `<li>${f}</li>`)}</ul>`,
        {
          headers: { "Content-Type": "text/html; charset=utf-8" },
        },
      );
    }

    // The federation-related requests are handled by the Federation object:
    return await federation.fetch(request, { contextData: undefined });
  }
});
```

```typescript{4-18} twoslash [Node.js]
import { serve } from "@hono/node-server";
import type { Federation } from "@fedify/fedify";
import { openKv } from "@deno/kv";
const federation = null as unknown as Federation<void>;
const kv = await openKv();
// ---cut-before---
serve({
  port: 8000,
  async fetch(request) {
    const url = new URL(request.url);
    // The home page:
    if (url.pathname === "/") {
      const followers: string[] = [];
      for await (const entry of kv.list<string>({ prefix: ["followers"] })) {
        if (followers.includes(entry.value)) continue;
        followers.push(entry.value);
      }
      return new Response(
        `<ul>${followers.map((f) => `<li>${f}</li>`)}</ul>`,
        {
          headers: { "Content-Type": "text/html; charset=utf-8" },
        },
      );
    }

    // The federation-related requests are handled by the Federation object:
    return await federation.fetch(request, { contextData: undefined });
  }
});
```

:::

The above code lists the actor's followers on the home page.  The followers are
stored in the key–value store, and we retrieve the followers from the key–value
store and display them on the home page.

Restart the server and navigate to the home page in your web browser.  You
should see the actor's followers in the bulleted list.

> \[!NOTE]
> Although the above code handles the home page *before* the federation-related
> requests, it is just an example.  In a real-world application, you should
> integrate Fedify with a web framework like [Hono], where the order of
> handling requests is reversed: the federation-related requests are handled
> *before* other web-related requests.
>
> For more details, see the [*Integration* section](../manual/integration.md).

[Hono]: https://hono.dev/

## Linting your federation code

As your federated server grows, it's important to maintain code quality and
catch common mistakes early.  Fedify provides the [`@fedify/lint`] package
with linting plugins for both Deno Lint and ESLint, which include specialized
linting rules for federation code.

The `@fedify/lint` package helps you avoid common pitfalls such as:

* Using incorrect actor IDs (e.g., relative URLs instead of
  `Context.getActorUri()`)
* Missing required actor properties (inbox, outbox, followers, etc.)
* Incorrect URL patterns for actor collections
* Missing public keys or assertion methods

For example, if you had written the actor dispatcher like this:

```typescript
// ❌ Wrong: Using relative URL
federation.setActorDispatcher(
  "/{identifier}",
  (_ctx, identifier) => {
    return new Person({
      id: new URL(`/${identifier}`),  // ❌ Linter will catch this
      name: "Example User",
    });
  },
);
```

The linter would warn you:

```
error[fedify-lint/actor-id-mismatch]: Actor's `id` property must match
`_ctx.getActorUri(identifier)`. Ensure you're using the correct context method.
```

This helps you catch mistakes before they cause issues in production.

> \[!TIP]
> For detailed setup instructions, available rules, and configuration options,
> see the [*Linting* section](../manual/lint.md) in the manual.

[`@fedify/lint`]: https://jsr.io/@fedify/lint

## Wrapping up

Congratulations!  You have built a small federated server that can accept
follow requests and list the actor's followers.  You have learned the key
features of the ActivityPub protocol and the Fedify framework, such as actors,
sending and receiving activities, and the inbox.

In this tutorial, we have covered the following topics:

* Creating a new project
* Creating the server
* `Federation` object
* Actor dispatcher
* Exposing the server to the public internet
* Inbox listener
* Generating a key pair
* Sending an `Accept` activity
* Listing followers

You can extend the server by adding more features, such as sending other
activities, handling other types of activities, and implementing other callback
functions.  The Fedify framework provides a wide range of features to build
a federated server, and you can explore them by reading
the [manual](../manual/federation.md) and the [API reference].

If you have any questions or feedback, feel free to ask in
the [Fedify community] on Matrix or the [Discord server] or
the [GitHub Discussions].

[API reference]: https://jsr.io/@fedify/fedify

[Fedify community]: https://matrix.to/#/#fedify:matrix.org

[Discord server]: https://discord.gg/bhtwpzURwd

[GitHub Discussions]: https://github.com/fedify-dev/fedify/discussions

## Exercises

* Implement unfollowing feature: Listen to the `Undo` activity and remove
  the follower from the key–value store when the server receives an `Undo`
  activity.

* Integration with a web framework: In the above example, we hard-coded
  the home page inside the callback function passed to `Deno.serve()`
  (in case of Deno), `Bun.serve()` (in case of Bun), and `serve()` (in case
  of Node.js).  This is not enough for a real-world application as you would
  need to rendering HTML templates, handling media files, and so on.
  Instead, you can use a web framework like [Hono] or [Fresh] to utilize
  the proper routing system and [JSX] templates to produce HTML.

  See also the [*Integration* section](../manual/integration.md) in
  the manual for more details.

[Fresh]: https://fresh.deno.dev/

[JSX]: https://facebook.github.io/jsx/

---

---
url: /manual/lint.md
description: >-
  Fedify provides linting plugins for Deno Lint and ESLint to help you catch
  common mistakes and enforce best practices when building federated server
  apps.
---

# Linting

*This package is available since Fedify 2.0.0.*

> \[!TIP]
> We highly recommend using the `@fedify/lint` package in your federated server
> app to catch common mistakes early and enforce best practices.

Fedify provides the [`@fedify/lint`] package, which includes lint rules
specifically designed for Fedify applications. It supports both [Deno Lint] and
[ESLint], so you can use it regardless of your JavaScript/TypeScript runtime.

The plugin includes rules that check for:

* Proper actor ID configuration
* Required actor properties (inbox, outbox, followers, etc.)
* Correct URL patterns for actor collections
* Public key and assertion method requirements
* Collection filtering implementation

[`@fedify/lint`]: https://jsr.io/@fedify/lint

[Deno Lint]: https://docs.deno.com/runtime/reference/lint_plugins/

[ESLint]: https://eslint.org/

## Installation

::: code-group

```sh [Deno]
deno add jsr:@fedify/lint
```

```sh [npm]
npm add -D @fedify/lint
```

```sh [pnpm]
pnpm add -D @fedify/lint
```

```sh [Yarn]
yarn add -D @fedify/lint
```

```sh [Bun]
bun add -D @fedify/lint
```

:::

## Deno Lint

### Basic setup

Add the plugin to your *deno.json* configuration file:

```json
{
  "lint": {
    "plugins": ["jsr:@fedify/lint"]
  }
}
```

By default, this enables all recommended rules.

### Custom configuration

You can customize which rules to enable and their severity levels:

```json
{
  "lint": {
    "plugins": ["jsr:@fedify/lint"],
    "rules": {
      "tags": ["recommended"],
      "include": [
        "@fedify/lint/actor-id-required",
        "@fedify/lint/actor-id-mismatch"
      ],
      "exclude": [
        "@fedify/lint/actor-featured-property-required"
      ]
    }
  }
}
```

### Running Deno Lint

After setting up the configuration, run Deno's linter:

```sh
deno lint
```

You can also specify which files to lint:

```sh
deno lint federation.ts
deno lint src/federation/
```

## ESLint

### Basic setup

Add the plugin to your ESLint configuration file (e.g., *eslint.config.ts* or
*eslint.config.js*):

```typescript twoslash
import fedifyLint from "@fedify/lint";

// If your `createFederation` code is in `federation.ts` or `federation/**.ts`
export default fedifyLint;
```

Or specify your own federation files:

```typescript twoslash
// @errors: 2304
import fedifyLint from "@fedify/lint";
// ---cut-before---
export default {
  ...fedifyLint,
  files: ["my-own-federation.ts"],
};
```

If you use other ESLint configurations:

```typescript twoslash
// @errors: 2304
import fedifyLint from "@fedify/lint";
// ---cut-before---
export default [
  // otherConfig,
  fedifyLint,
];
```

The default configuration applies recommended rules to files that match common
federation-related patterns (e.g., *federation.ts*, *federation/\*.ts*).

### Custom configuration

You can customize which files to lint and which rules to enable:

```typescript twoslash
import { plugin } from "@fedify/lint";

export default [{
  files: ["src/federation/**/*.ts"], // Your federation code location
  plugins: {
    "@fedify/lint": plugin,
  },
  rules: {
    "@fedify/lint/actor-id-required": "error",
    "@fedify/lint/actor-id-mismatch": "error",
    "@fedify/lint/actor-inbox-property-required": "warn",
    // ... other rules
  },
}];
```

### Using configurations

The plugin provides two preset configurations:

#### Recommended (default)

Enables critical rules as errors and optional rules as warnings:

```typescript twoslash
import fedifyLint from "@fedify/lint";

export default fedifyLint;
```

#### Strict

Enables all rules as errors:

```typescript twoslash
import { plugin } from "@fedify/lint";

export default [{
  files: ["**/*.ts"],
  ...plugin.configs.strict,
}];
```

### Running ESLint

Set up your ESLint configuration as shown above and add a script to
*package.json*:

```jsonc
{
  "scripts": {
    "lint": "eslint ."
  }
}
```

After setting up the configuration, run ESLint on your codebase:

::: code-group

```sh [npm]
npm run lint
```

```sh [pnpm]
pnpm lint
```

```sh [Yarn]
yarn lint
```

```sh [Bun]
bun lint
```

:::

Or run the linter directly via command line:

::: code-group

```sh [npm]
npx eslint .
```

```sh [pnpm]
pnpx eslint .
```

```sh [Yarn]
yarn eslint .
```

```sh [Bun]
bunx eslint .
```

:::

## Rules

### `actor-id-required`

Ensures all actors have an `id` property in the actor dispatcher.

**When this rule applies:**
The actor dispatcher returns a `Person`, `Organization`, `Group`, `Application`,
or `Service` object without an `id` property.

**Why it matters:**
Every ActivityPub actor must have a unique identifier (ID) to be discoverable
and to receive activities from other servers.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing id property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    name: "John Doe",  // No id!
  });
});

// ✅ Good: Include id property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "John Doe",
  });
});
```

### `actor-id-mismatch`

Validates that actor IDs match the expected URI from `Context.getActorUri()`.

**When this rule applies:**
The `id` property is set to a value other than `ctx.getActorUri(identifier)`,
such as a hardcoded URL string, `new URL(...)`, or a different context method.

**Why it matters:**
Using the wrong URI for the actor ID can cause federation issues.  Other servers
won't be able to properly verify the actor's identity or send activities to it.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using hardcoded URL
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: new URL(`https://example.com/users/${identifier}`),
    name: "John Doe",
  });
});

// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getFollowersUri(identifier),  // Wrong method!
    name: "John Doe",
  });
});

// ✅ Good: Use ctx.getActorUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "John Doe",
  });
});
```

### `actor-public-key-required`

Ensures actors have public keys for [HTTP Signatures].

**When this rule applies:**
The actor dispatcher is chained with `setKeyPairsDispatcher()`, but the actor
object doesn't include a `publicKey` or `publicKeys` property.

**Why it matters:**
HTTP Signatures are used to verify the authenticity of activities.  Without
a public key, other servers cannot verify that activities sent by your actor
are legitimate.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing publicKey when setKeyPairsDispatcher is configured
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "John Doe",
      // Missing publicKey!
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // Returns key pairs...
    return [];
  });

// ✅ Good: Include publicKey from key pairs dispatcher
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    const keyPairs = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "John Doe",
      publicKey: keyPairs[0].cryptographicKey,
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // Returns key pairs...
    return [];
  });
```

[HTTP Signatures]: ./send.md#http-signatures

### `actor-assertion-method-required`

Validates that actors have assertion methods for [Object Integrity Proofs].

**When this rule applies:**
The actor dispatcher is chained with `setKeyPairsDispatcher()`, but the actor
object doesn't include an `assertionMethod` property.

**Why it matters:**
Object Integrity Proofs use assertion methods to cryptographically sign
activities.  This provides an additional layer of security beyond HTTP
Signatures.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing assertionMethod when setKeyPairsDispatcher is configured
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    const keyPairs = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "John Doe",
      publicKey: keyPairs[0].cryptographicKey,
      // Missing assertionMethod!
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // Returns key pairs...
    return [];
  });

// ✅ Good: Include assertionMethod from key pairs dispatcher
federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    const keyPairs = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      name: "John Doe",
      publicKey: keyPairs[0].cryptographicKey,
      assertionMethod: keyPairs[0].multikey,
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // Returns key pairs...
    return [];
  });
```

[Object Integrity Proofs]: ./send.md#object-integrity-proofs

### `actor-inbox-property-required`

Ensures `inbox` is defined when `setInboxListeners()` is configured.

**When this rule applies:**
You've called `federation.setInboxListeners()` to handle incoming activities,
but the actor object doesn't include an `inbox` property.

**Why it matters:**
The inbox URL tells other servers where to send activities to your actor.
Without it, your actor cannot receive follow requests, mentions, or any other
activities.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing inbox when setInboxListeners is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "John Doe",
    // Missing inbox!
  });
});

federation.setInboxListeners("/users/{identifier}/inbox", "/inbox");

// ✅ Good: Include inbox property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    name: "John Doe",
    inbox: ctx.getInboxUri(identifier),
  });
});

federation.setInboxListeners("/users/{identifier}/inbox", "/inbox");
```

### `actor-inbox-property-mismatch`

Validates that the `inbox` URI is set using `ctx.getInboxUri(identifier)`.

**When this rule applies:**
The `inbox` property is set to a value other than `ctx.getInboxUri(identifier)`.

**Why it matters:**
The inbox URI must match the path configured in `setInboxListeners()`.  Using
a different URI will cause incoming activities to fail.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using hardcoded URL
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    inbox: new URL(`https://example.com/inbox/${identifier}`),  // Wrong!
  });
});

// ✅ Good: Use ctx.getInboxUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    inbox: ctx.getInboxUri(identifier),
  });
});
```

### `actor-outbox-property-required`

Ensures `outbox` is defined when `setOutboxDispatcher()` is configured.

**When this rule applies:**
You've called `federation.setOutboxDispatcher()` to serve the actor's outbox,
but the actor object doesn't include an `outbox` property.

**Why it matters:**
The outbox URL allows other servers and users to view the actor's published
activities.  It's part of the standard ActivityPub actor profile.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing outbox when setOutboxDispatcher is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    // Missing outbox!
  });
});

federation.setOutboxDispatcher(
  "/users/{identifier}/outbox",
  (ctx, identifier) => ({ items: [] })
);

// ✅ Good: Include outbox property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    outbox: ctx.getOutboxUri(identifier),
  });
});
```

### `actor-outbox-property-mismatch`

Validates that the `outbox` URI is set using `ctx.getOutboxUri(identifier)`.

**When this rule applies:**
The `outbox` property is set to a value other than
`ctx.getOutboxUri(identifier)`.

**Why it matters:**
The outbox URI must match the path configured in `setOutboxDispatcher()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    outbox: ctx.getInboxUri(identifier),  // Wrong method!
  });
});

// ✅ Good: Use ctx.getOutboxUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    outbox: ctx.getOutboxUri(identifier),
  });
});
```

### `actor-followers-property-required`

Ensures `followers` is defined when `setFollowersDispatcher()` is configured.

**When this rule applies:**
You've called `federation.setFollowersDispatcher()` to serve the actor's
followers collection, but the actor object doesn't include a `followers`
property.

**Why it matters:**
The followers URL allows other servers to discover who follows this actor,
which is important for activity delivery and social graph discovery.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing followers when setFollowersDispatcher is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    // Missing followers!
  });
});

federation.setFollowersDispatcher(
  "/users/{identifier}/followers",
  (ctx, identifier) => ({ items: [] })
);

// ✅ Good: Include followers property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    followers: ctx.getFollowersUri(identifier),
  });
});
```

### `actor-followers-property-mismatch`

Validates that the `followers` URI is set using
`ctx.getFollowersUri(identifier)`.

**When this rule applies:**
The `followers` property is set to a value other than
`ctx.getFollowersUri(identifier)`.

**Why it matters:**
The followers URI must match the path configured in `setFollowersDispatcher()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    followers: ctx.getFollowingUri(identifier),  // Wrong method!
  });
});

// ✅ Good: Use ctx.getFollowersUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    followers: ctx.getFollowersUri(identifier),
  });
});
```

### `actor-following-property-required`

Ensures `following` is defined when `setFollowingDispatcher()` is configured.

**When this rule applies:**
You've called `federation.setFollowingDispatcher()` to serve the actor's
following collection, but the actor object doesn't include a `following`
property.

**Why it matters:**
The following URL allows other servers to discover who this actor follows.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing following when setFollowingDispatcher is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    // Missing following!
  });
});

federation.setFollowingDispatcher(
  "/users/{identifier}/following",
  (ctx, identifier) => ({ items: [] })
);

// ✅ Good: Include following property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    following: ctx.getFollowingUri(identifier),
  });
});
```

### `actor-following-property-mismatch`

Validates that the `following` URI is set using
`ctx.getFollowingUri(identifier)`.

**When this rule applies:**
The `following` property is set to a value other than
`ctx.getFollowingUri(identifier)`.

**Why it matters:**
The following URI must match the path configured in `setFollowingDispatcher()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    following: ctx.getFollowersUri(identifier),  // Wrong method!
  });
});

// ✅ Good: Use ctx.getFollowingUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    following: ctx.getFollowingUri(identifier),
  });
});
```

### `actor-liked-property-required`

Ensures `liked` is defined when `setLikedDispatcher()` is configured.

**When this rule applies:**
You've called `federation.setLikedDispatcher()` to serve the actor's liked
collection, but the actor object doesn't include a `liked` property.

**Why it matters:**
The liked URL allows other servers to discover what content this actor has
liked.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing liked when setLikedDispatcher is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    // Missing liked!
  });
});

federation.setLikedDispatcher(
  "/users/{identifier}/liked",
  (ctx, identifier) => ({ items: [] })
);

// ✅ Good: Include liked property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    liked: ctx.getLikedUri(identifier),
  });
});
```

### `actor-liked-property-mismatch`

Validates that the `liked` URI is set using `ctx.getLikedUri(identifier)`.

**When this rule applies:**
The `liked` property is set to a value other than `ctx.getLikedUri(identifier)`.

**Why it matters:**
The liked URI must match the path configured in `setLikedDispatcher()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    liked: ctx.getFollowersUri(identifier),  // Wrong method!
  });
});

// ✅ Good: Use ctx.getLikedUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    liked: ctx.getLikedUri(identifier),
  });
});
```

### `actor-featured-property-required`

Ensures `featured` is defined when `setFeaturedDispatcher()` is configured.

**When this rule applies:**
You've called `federation.setFeaturedDispatcher()` to serve the actor's
featured/pinned posts collection, but the actor object doesn't include a
`featured` property.

**Why it matters:**
The featured URL allows other servers to discover the actor's pinned or
highlighted content (commonly shown at the top of a profile).

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing featured when setFeaturedDispatcher is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    // Missing featured!
  });
});

federation.setFeaturedDispatcher(
  "/users/{identifier}/featured",
  (ctx, identifier) => ({ items: [] })
);

// ✅ Good: Include featured property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    featured: ctx.getFeaturedUri(identifier),
  });
});
```

### `actor-featured-property-mismatch`

Validates that the `featured` URI is set using
`ctx.getFeaturedUri(identifier)`.

**When this rule applies:**
The `featured` property is set to a value other than
`ctx.getFeaturedUri(identifier)`.

**Why it matters:**
The featured URI must match the path configured in `setFeaturedDispatcher()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    featured: ctx.getFollowersUri(identifier),  // Wrong method!
  });
});

// ✅ Good: Use ctx.getFeaturedUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    featured: ctx.getFeaturedUri(identifier),
  });
});
```

### `actor-featured-tags-property-required`

Ensures `featuredTags` is defined when `setFeaturedTagsDispatcher()` is
configured.

**When this rule applies:**
You've called `federation.setFeaturedTagsDispatcher()` to serve the actor's
featured hashtags collection, but the actor object doesn't include a
`featuredTags` property.

**Why it matters:**
The featuredTags URL allows other servers to discover the actor's featured
hashtags (commonly used for profile discovery).

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing featuredTags when setFeaturedTagsDispatcher is configured
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    // Missing featuredTags!
  });
});

federation.setFeaturedTagsDispatcher(
  "/users/{identifier}/tags",
  (ctx, identifier) => ({ items: [] })
);

// ✅ Good: Include featuredTags property
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    featuredTags: ctx.getFeaturedTagsUri(identifier),
  });
});
```

### `actor-featured-tags-property-mismatch`

Validates that the `featuredTags` URI is set using
`ctx.getFeaturedTagsUri(identifier)`.

**When this rule applies:**
The `featuredTags` property is set to a value other than
`ctx.getFeaturedTagsUri(identifier)`.

**Why it matters:**
The featuredTags URI must match the path configured in
`setFeaturedTagsDispatcher()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using wrong context method
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    featuredTags: ctx.getFollowersUri(identifier),  // Wrong method!
  });
});

// ✅ Good: Use ctx.getFeaturedTagsUri()
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    featuredTags: ctx.getFeaturedTagsUri(identifier),
  });
});
```

### `actor-shared-inbox-property-required`

Ensures `endpoints.sharedInbox` is defined when `setInboxListeners()` is
configured with a shared inbox path.

**When this rule applies:**
You've called `federation.setInboxListeners()` with a second parameter (shared
inbox path), but the actor object doesn't include an
`endpoints: new Endpoints({ sharedInbox: ... })` property.

**Why it matters:**
The shared inbox allows other servers to send activities to multiple actors
on your server with a single request, improving federation efficiency.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing sharedInbox when setInboxListeners has shared inbox path
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    inbox: ctx.getInboxUri(identifier),
    // Missing endpoints.sharedInbox!
  });
});

federation.setInboxListeners("/users/{identifier}/inbox", "/inbox");

// ✅ Good: Include endpoints.sharedInbox
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    inbox: ctx.getInboxUri(identifier),
    endpoints: new Endpoints({
      sharedInbox: ctx.getInboxUri(),
    }),
  });
});
```

### `actor-shared-inbox-property-mismatch`

Validates that `endpoints.sharedInbox` is set using `ctx.getInboxUri()` (without
identifier).

**When this rule applies:**
The `endpoints.sharedInbox` property is set to a value other than
`ctx.getInboxUri()` (called without arguments for the shared inbox).

**Why it matters:**
The shared inbox URI must match the shared inbox path configured in
`setInboxListeners()`.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Using getInboxUri with identifier for shared inbox
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    inbox: ctx.getInboxUri(identifier),
    endpoints: new Endpoints({
      sharedInbox: ctx.getInboxUri(identifier),  // Wrong! Should be no args
    }),
  });
});

// ✅ Good: Use ctx.getInboxUri() without arguments
federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) => {
  return new Person({
    id: ctx.getActorUri(identifier),
    inbox: ctx.getInboxUri(identifier),
    endpoints: new Endpoints({
      sharedInbox: ctx.getInboxUri(),  // No identifier for shared inbox
    }),
  });
});
```

### `collection-filtering-not-implemented`

Warns when collection dispatchers don't implement filtering.

**When this rule applies:**
The `setFollowersDispatcher()` callback function has fewer than 4 parameters
(missing the `filter` parameter).

> \[!NOTE]
> Currently, this rule only checks `setFollowersDispatcher()`.  Other collection
> dispatchers may be added in the future.

**Why it matters:**
Collection filtering allows clients to request specific subsets of a collection,
reducing response payload sizes and improving performance.  Without filtering,
large collections could cause performance issues.

For more information, see the [*Filtering by server*] section in the
collections manual.

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Bad: Missing filter parameter
federation.setFollowersDispatcher(
  "/users/{identifier}/followers",
  async (ctx, identifier, cursor) => {  // Only 3 parameters!
    return { items: [] };
  }
);

// ✅ Good: Include filter parameter (4th parameter)
federation.setFollowersDispatcher(
  "/users/{identifier}/followers",
  async (ctx, identifier, cursor, filter) => {
    // Use filter to handle filtering requests
    return { items: [] };
  }
);
```

[*Filtering by server*]: ./collections.md#filtering-by-server

## Example

Here's an example of code that would trigger lint errors:

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ❌ Wrong: Using relative URL for actor ID
federation.setActorDispatcher(
  "/{identifier}",
  (_ctx, identifier) => {
    return new Person({
      id: new URL(`/${identifier}`), // ❌ Should use ctx.getActorUri()
      name: "Example User",
    });
  },
);
```

Corrected version:

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = createFederation<void>({ kv: null as any });
// ---cut-before---
// ✅ Correct: Using Context.getActorUri() for actor ID
federation.setActorDispatcher(
  "/{identifier}",
  (ctx, identifier) => {
    return new Person({
      id: ctx.getActorUri(identifier), // ✅ Correct
      name: "Example User",
      inbox: ctx.getInboxUri(identifier),
      outbox: ctx.getOutboxUri(identifier),
      followers: ctx.getFollowersUri(identifier),
      // ... other required properties
    });
  },
);
```

When you run the linter on the incorrect code, you'll see an error like:

```
error[fedify-lint/actor-id-mismatch]: Actor's `id` property must match
`ctx.getActorUri(identifier)`. Ensure you're using the correct context method.
```

## See also

* [`@fedify/lint` on JSR]
* [`@fedify/lint` on npm]
* [Deno Lint plugins documentation]
* [ESLint documentation]
* [Example project]

[`@fedify/lint` on JSR]: https://jsr.io/@fedify/lint

[`@fedify/lint` on npm]: https://www.npmjs.com/package/@fedify/lint

[Deno Lint plugins documentation]: https://docs.deno.com/runtime/reference/lint_plugins/

[ESLint documentation]: https://eslint.org/

[Example project]: https://github.com/fedify-dev/fedify/tree/main/examples/lint

---

---
url: /manual/log.md
description: >-
  Logging is a useful tool for debugging your federated server app.  This
  section explains how to enable logging in your federated server app.
---

# Logging

*This API is available since Fedify 0.7.0.*

> \[!TIP]
> We highly recommend enabling logging in your federated server app to debug
> your app easily.

Fedify uses the [LogTape] package to log messages.  You can enable logging in
your federated server app by installing the `@logtape/logtape` package and
configuring it in the entry point of your app.

[LogTape]: https://logtape.org/

## Setting up LogTape

To enable logging in your federated server app, you need to install the
`@logtape/logtape` package (available on both [JSR] and [npm]):

::: code-group

```sh [Deno]
deno add jsr:@logtape/logtape
```

```sh [npm]
npm add @logtape/logtape
```

```sh [pnpm]
pnpm add @logtape/logtape
```

```sh [Yarn]
yarn add @logtape/logtape
```

```sh [Bun]
bun add @logtape/logtape
```

:::

Then, you can [`configure()`] the logger in the entry point of your app:

```typescript twoslash
import { AsyncLocalStorage } from "node:async_hooks";
import { configure, getConsoleSink } from "@logtape/logtape";

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: "your-app", sinks: ["console"], lowestLevel: "debug" },
    { category: "fedify",   sinks: ["console"], lowestLevel: "error" },
  ],
  contextLocalStorage: new AsyncLocalStorage(),
});
```

The `configure()` function takes an object with three properties:

`sinks` (mandatory)
:   An object that maps sink names to sink instances.  In this example, we use
the `getConsoleSink()` function to get a console sink instance.

`filters` (mandatory)
:   An object that maps logger categories to filter functions.  In this example,
we use an empty object to disable filtering.

`loggers` (mandatory)
:   An array of logger configurations.  Each configuration is an object with
four properties:

`loggers.category` (mandatory)
:   The `category` property is an array of string or a string that specifies
the logger category.  If a string is given, it is treated as an array
with a single element.

`loggers.sinks` (optional)
:   The `sinks` property is an array of string that specifies the sink names
that the logger should use.

`loggers.filters` (optional)
:   The `filters` property is an array of string that specifies the filter
names that the logger should use.

`loggers.lowestLevel` (optional)
:   The `lowestLevel` property is a string that specifies the log level.
The log level can be one of the following: `"debug"`, `"info"`, `"warning"`,
`"error"`, or `"fatal"`.

```
> [!NOTE]
> The `lowestLevel` property was introduced in LogTape 0.8.0.  Prior to
> LogTape 0.8.0, please use the `level` property instead of `lowestLevel`.
```

`contextLocalStorage` (recommended)
:   *This property is available since LogTape 0.7.0.*

```
An instance of [`AsyncLocalStorage`] that is used to store
[implicit contexts] of the log messages.  This is useful when you want to
trace the log messages in a specific context.
```

[JSR]: https://jsr.io/@logtape/logtape

[npm]: https://www.npmjs.com/package/@logtape/logtape

[`configure()`]: https://jsr.io/@logtape/logtape/doc/~/configure

[`AsyncLocalStorage`]: https://nodejs.org/api/async_context.html#class-asynclocalstorage

[implicit contexts]: https://logtape.org/manual/contexts#implicit-contexts

## Categories

> \[!TIP]
> A logger category is an array of strings that specifies the logger category.
> The logger category is used to filter log messages, or to configure
> the specific sink for the logger.  Since it's hierarchical, you can filter
> out log messages by specifying a prefix of the logger category while
> seeing log messages of a specific subcategory.
>
> Note that the logger category is case-sensitive.  A bare string is treated
> as an array with a single element.

Fedify uses the following logger categories:

### `"fedify"`

The `"fedify"` category is used for everything related to the Fedify library.

### `["fedify", "compat", "transformers"]`

*This category is available since Fedify 1.4.0.*

The `["fedify", "compat", "transformers"]` category is used for logging
`ActivityTransformer`-related messages.

### `["fedify", "federation"]`

The `["fedify", "federation"]` category is used for logging federation-related
messages.

### `["fedify", "federation", "actor"]`

*This category is available since Fedify 0.9.0.*

The `["fedify", "federation", "actor"]` category is used for logging messages
related to actor dispatcher.

### `["fedify", "federation", "collection"]`

*This category is available since Fedify 0.8.0.*

The `["fedify", "federation", "collection"]` category is used for logging
messages related to collections (e.g., outbox, followers, following).

### `["fedify", "federation", "fanout"]`

*This category is available since Fedify 1.5.0.*

The `["fedify", "federation", "fanout"]` category is used for logging
messages related to fanning out outgoing activities.

### `["fedify", "federation", "http"]`

*This category is available since Fedify 0.9.0.*

The `["fedify", "federation", "http"]` category is used for logging messages
related to HTTP requests and responses.  When you are curious about the
HTTP requests and responses, you can check the log messages in this category
with the `"info"` level.

### `["fedify", "federation", "inbox"]`

The `["fedify", "federation", "inbox"]` category is used for logging messages
related to incoming activities.  When you cannot receive an activity, you can
check the log messages in this category with the `"debug"` level.

### `["fedify", "federation", "object"]`

The `["fedify", "federation", "object"]` category is used for logging messages
related to object dispatchers.

### `["fedify", "federation", "outbox"]`

The `["fedify", "federation", "outbox"]` category is used for logging messages
related to outgoing activities.  When you cannot send an activity, you can
check the log messages in this category with the `"debug"` level.

### `["fedify", "federation", "queue"]`

*This category is available since Fedify 0.12.0.*

The `["fedify", "federation", "queue"]` category is used for logging messages
related to the task queue.  When you are curious about the task queue, you can
check the log messages in this category with the `"debug"` level.

### `["fedify", "nodeinfo", "client"]`

*This category is available since Fedify 1.2.0.*

The `["fedify", "nodeinfo", "client"]` category is used for logging messages
related to the NodeInfo client.  When you are curious about the NodeInfo client,
you can check the log messages in this category with the `"error"` level.

### `["fedify", "otel", "exporter"]`

*This category is available since Fedify 1.10.0.*

The `["fedify", "otel", "exporter"]` category is used for logging messages
related to the `FedifySpanExporter`.  When span export to the `KvStore` fails,
you can check the log messages in this category with the `"error"` level.

### `["fedify", "runtime", "docloader"]`

*This category is available since Fedify 0.8.0.*

The `["fedify", "runtime", "docloader"]` category is used for logging messages
related to the document loader.  When you are curious about what specific
requests are made by the document loader, you can check the log messages in
this category with the `"debug"` level.

### `["fedify", "sig", "http"]`

*This category is available since Fedify 0.9.0.*

The `["fedify", "sig", "ld"]` category is used for logging messages related
to [HTTP Signatures](./send.md#http-signatures).  When you are curious about
the signature verification process, you can check the log messages in this
category with the `"debug"` level.

### `["fedify", "sig", "ld"]`

*This category is available since Fedify 1.0.0.*

The `["fedify", "sig", "ld"]` category is used for logging messages related to
[Linked Data Signatures](./send.md#linked-data-signatures).  When you are
curious about the signature verification process, you can check the log
messages in this category with the `"debug"` level.

### `["fedify", "sig", "proof"]`

*This category is available since Fedify 0.10.0.*

The `["fedify", "sig", "proof"]` category is used for logging messages related
to [Object Integrity Proofs](./send.md#object-integrity-proofs).  When you are
curious about the proof verification process, you can check the log messages in
this category with the `"debug"` level.

### `["fedify", "sig", "key"]`

*This category is available since Fedify 0.10.0.*

The `["fedify", "sig", "key"]` category is used for logging messages related
to key generation and key retrieval.  When you are curious about these
processes, you can check the log messages in this category with the `"debug"`
level.

### `["fedify", "vocab", "lookup"]`

*This category is available since Fedify 0.10.0.*

The `["fedify", "vocab", "lookup"]` category is used for logging messages
related to looking up ActivityPub objects.  When you are curious about the
lookup process, you can check the log messages in this category with the
`"debug"` level.

### `["fedify", "webfinger", "server"]`

*This category is available since Fedify 0.13.0.*

The `["fedify", "webfinger", "server"]` category is used for logging messages
related to the WebFinger server.  When you are curious about the WebFinger
server, you can check the log messages in this category with the `"debug"`
level.

### `["fedify", "webfinger", "lookup"]`

*This category is available since Fedify 0.10.0.*

The `["fedify", "webfinger", "lookup"]` category is used for logging messages
related to looking up WebFinger resources.  When you are curious about the
lookup process, you can check the log messages in this category with the
`"debug"` level.

## Sinks

A sink is a destination where log messages are sent.  LogTape provides few
built-in sinks:

* [console sink]
* [stream sink]
* [file sink]
* [rotating file sink]
* [OpenTelemetry sink]

However, you can create your own sink by implementing the [`Sink`] interface,
e.g., to send log messages to a database or a cloud service.

For more information about sinks, see the [*Sinks* section] in the LogTape docs.

[console sink]: https://logtape.org/manual/sinks#console-sink

[stream sink]: https://logtape.org/manual/sinks#stream-sink

[file sink]: https://logtape.org/manual/sinks#file-sink

[rotating file sink]: https://logtape.org/manual/sinks#rotating-file-sink

[OpenTelemetry sink]: https://logtape.org/manual/sinks#opentelemetry-sink

[`Sink`]: https://jsr.io/@logtape/logtape/doc/~/Sink

[*Sinks* section]: https://logtape.org/manual/sinks

## Deprecation warnings

When you are using deprecated APIs, you can see deprecation warnings in the
log messages.  The deprecation warnings are logged with the `"warning"` level
in each category where the deprecated API is used.  If you want to see all
deprecation warnings, you can set the log level to `"warning"` for the
[`"fedify"` category](#fedify).

## Tracing

*This feature is available since Fedify 1.2.0.*

> \[!CAUTION]
> Traceable log messages rely on [implicit contexts] which was introduced in
> LogTape 0.7.0.  If you don't configure `contextLocalStorage` in
> [`configure()`], you cannot trace log messages.

The most of log messages made by Fedify can be traced by either below two
properties:

`requestId`
:   If the log message is made in the context of an HTTP request,
the `requestId` property is included in it.  The `requestId` is a unique
identifier for the HTTP request, which is derived from one of the following
headers:

```
 -  [`X-Request-Id`]
 -  `X-Correlation-Id`
 -  [`Traceparent`]
 -  Otherwise, the `requestId` is a unique string derived from
    the current timestamp and the random number.
```

`messageId`
:   If the log message is made in the context of a background task,
the `messageId` property is included in it.  The `messageId` is a unique
identifier for the background task, which is a UUID.

When you want to trace log messages, first you need to use a sink that
writes log messages as structured data.  For example, you can use
a [file sink] with a [JSON Lines] formatter.  Oh, and don't forget to set
`contextLocalStorage` in [`configure()`]!  To sum up, you can configure
loggers like this:

```typescript twoslash
import { AsyncLocalStorage } from "node:async_hooks";
import { getFileSink } from "@logtape/file";
import { type LogRecord, configure } from "@logtape/logtape";

await configure({
  sinks: {
    file: getFileSink("fedify-logs.jsonld", {
      formatter(record: LogRecord): string {
        return JSON.stringify(record) + "\n";
      }
    })
  },
  loggers: [
    { category: "fedify", sinks: ["file"], lowestLevel: "info" },
  ],
  contextLocalStorage: new AsyncLocalStorage(),
});
```

If your loggers are configured like this, you can filter log messages by
`requestId` or `messageId` in the log file.  For example, you can filter log
messages by `requestId` using [`jq`]:

```sh
jq -r 'select(.properties.requestId == "your-request-id")' fedify-logs.jsonl
```

[`X-Request-Id`]: https://http.dev/x-request-id

[`Traceparent`]: https://www.w3.org/TR/trace-context/#traceparent-header

[JSON Lines]: https://jsonlines.org/

[`jq`]: https://jqlang.github.io/jq/

---

---
url: /manual/mq.md
---
# Message queue

*This API is available since Fedify 0.5.0.*

The `MessageQueue` interface in Fedify provides an abstraction for handling
asynchronous message processing. This document will help you understand
how to choose a `MessageQueue` implementation and how to create your own custom
implementation if needed.

## Choosing a `MessageQueue` implementation

When choosing an implementation, consider the following factors:

1. *Runtime environment*: Are you using [Deno], [Node.js], [Bun],
   or another JavaScript runtime?
2. *Scalability need*: Do you need to support multiple workers or servers?
3. *Persistence requirements*: Do messages need to survive server restarts?
4. *Development vs. production*: Are you in a development/testing phase or
   deploying to production?

Fedify provides several built-in `MessageQueue` implementations,
each suited for different use cases:

[Deno]: https://deno.com/

[Node.js]: https://nodejs.org/

[Bun]: https://bun.sh/

### `InProcessMessageQueue`

`InProcessMessageQueue` is a simple in-memory message queue that doesn't persist
messages between restarts. It's best suited for development and testing
environments.

Best for
:   Development and testing.

Pros
:   Simple, no external dependencies.

Cons
:   Not suitable for production, doesn't persist messages between restarts,
no native retry mechanism.

```typescript twoslash
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: new InProcessMessageQueue(),  // [!code highlight]
  // ... other options
});
```

### `DenoKvMessageQueue` (Deno only)

To use the [`DenoKvMessageQueue`], you need to install the *@fedify/denokv*
package first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/denokv
```

:::

[`DenoKvMessageQueue`] is a message queue implementation for [Deno] runtime that
uses Deno's built-in [`Deno.openKv()`] API. It provides persistent storage and
good performance for Deno environments.  It's suitable for production use in
Deno applications.

Best for
:   Production use in Deno environments.

Pros
:   Persistent, scalable, easy to set up, native retry with exponential backoff.

Cons
:   Only available in Deno runtime.

```typescript
import { createFederation } from "@fedify/fedify";
import { DenoKvMessageQueue } from "@fedify/denokv";

const kv = await Deno.openKv();
const federation = createFederation<void>({
  queue: new DenoKvMessageQueue(kv),  // [!code highlight]
  // ... other options
});
```

[`DenoKvMessageQueue`]: https://jsr.io/@fedify/denokv/doc/mq/~/DenoKvMessageQueue

[`Deno.openKv()`]: https://docs.deno.com/api/deno/~/Deno.openKv

### [`RedisMessageQueue`]

To use [`RedisMessageQueue`], you need to install the *@fedify/redis* package:

::: code-group

```bash [Deno]
deno add jsr:@fedify/redis
```

```bash [npm]
npm add @fedify/redis
```

```bash [pnpm]
pnpm add @fedify/redis
```

```bash [Yarn]
yarn add @fedify/redis
```

```bash [Bun]
bun add @fedify/redis
```

:::

[`RedisMessageQueue`] is a message queue implementation that uses Redis as
the backend. It provides scalability and high performance, making it
suitable for production use across various runtimes.  It requires a Redis
server setup and management.

Best for
:   Production use across various runtimes.

Pros
:   Persistent, scalable, supports multiple workers.

Cons
:   Requires Redis setup and management.

```typescript twoslash
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import Redis from "ioredis";

const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: new RedisMessageQueue(() => new Redis()),  // [!code highlight]
  // ... other options
});
```

[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

### [`PostgresMessageQueue`]

To use [`PostgresMessageQueue`], you need to install the *@fedify/postgres*
package first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/postgres
```

```bash [npm]
npm add @fedify/postgres
```

```bash [pnpm]
pnpm add @fedify/postgres
```

```bash [Yarn]
yarn add @fedify/postgres
```

```bash [Bun]
bun add @fedify/postgres
```

:::

[`PostgresMessageQueue`] is a message queue implementation that uses
a PostgreSQL database as the message queue backend.  Under the hood,
it uses a table for maintaining the queue, and [`LISTEN`]/[`NOTIFY`] for
real-time message delivery.  It's suitable for production use if you
already rely on PostgreSQL in your application.

Best for
:   Production use, a system that already uses PostgreSQL.

Pros
:   Persistent, scalable, supports multiple workers.

Cons
:   Requires PostgreSQL setup.

```typescript{6-8} twoslash
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { PostgresMessageQueue } from "@fedify/postgres";
import postgres from "postgres";

const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: new PostgresMessageQueue(
    postgres("postgresql://user:pass@localhost/db"),
  ),
  // ... other options
});
```

> \[!WARNING]
> When using `PostgresMessageQueue` together with
> [`ParallelMessageQueue`](#parallel-message-processing)`(queue, N)`,
> make sure the PostgreSQL connection pool is sized to at least `N` plus a few
> extra connections.  This is because each parallel worker may hold a database
> connection, and poll operations also require additional connections for
> advisory lock management.  If the pool is shared with other parts of your
> application (e.g., a KV store, HTTP request handlers), increase the pool size
> accordingly—or use a dedicated pool for the queue.  Using the default pool
> size of 10 with `ParallelMessageQueue(queue, 10)` can cause connection
> starvation that makes the application appear hung.  \[[#603]]

[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/mq/~/PostgresMessageQueue

[`LISTEN`]: https://www.postgresql.org/docs/current/sql-listen.html

[`NOTIFY`]: https://www.postgresql.org/docs/current/sql-notify.html

[#603]: https://github.com/fedify-dev/fedify/issues/603

### `AmqpMessageQueue`

To use \[`AmqpMessageQueue`], you need to install the *@fedify/amqp* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/amqp
```

```bash [npm]
npm add @fedify/amqp
```

```bash [pnpm]
pnpm add @fedify/amqp
```

```bash [Yarn]
yarn add @fedify/amqp
```

```bash [Bun]
bun add @fedify/amqp
```

:::

> \[!NOTE]
>
> Although it's theoretically possible to be used with any AMQP 0-9-1 broker,
> \[`AmqpMessageQueue`] is primarily designed for and tested with \[RabbitMQ].

\[`AmqpMessageQueue`] is a message queue implementation that uses AMQP 0-9-1
for message delivery.  The best-known AMQP broker is \[RabbitMQ].  It provides
scalability and high performance, making it suitable for production use across
various runtimes.  It requires an AMQP broker setup and management.

Best for
:   Production use across various runtimes.

Pros
:   Persistent, reliable, scalable, supports multiple workers.

Cons
:   Requires AMQP broker setup and management.

```typescript twoslash
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { AmqpMessageQueue } from "@fedify/amqp";
import { connect } from "amqplib";

const federation = createFederation({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: new AmqpMessageQueue(await connect("amqp://localhost")),  // [!code highlight]
  // ... other options
});
```

\*\[AMQP]: Advanced Message Queuing Protocol
\[`AmqpMessageQueue`]: https://jsr.io/@fedify/amqp/doc/mq/~/AmqpMessageQueue
\[RabbitMQ]: https://www.rabbitmq.com/

### [`MysqlMessageQueue`]

*This API is available since Fedify 2.1.0.*

To use [`MysqlMessageQueue`], you need to install the *@fedify/mysql* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/mysql
```

```bash [npm]
npm add @fedify/mysql mysql2
```

```bash [pnpm]
pnpm add @fedify/mysql mysql2
```

```bash [Yarn]
yarn add @fedify/mysql mysql2
```

```bash [Bun]
bun add @fedify/mysql mysql2
```

:::

[`MysqlMessageQueue`] is a message queue implementation that uses a MySQL or
MariaDB database as the backend.  Since MySQL and MariaDB do not provide a
`LISTEN`/`NOTIFY` mechanism, it uses **polling** to discover new messages.
The polling interval is configurable and defaults to 1 second to minimize
latency; this is shorter than the default for PostgreSQL-backed queues.

Concurrent workers are safely supported via `SELECT … FOR UPDATE SKIP LOCKED`
and MySQL advisory locks (`GET_LOCK`/`RELEASE_LOCK`).

> \[!NOTE]
> `MysqlMessageQueue` requires MySQL 8.0+ or MariaDB 10.6+ for
> `SELECT … FOR UPDATE SKIP LOCKED` support.

> \[!NOTE]
> Because `MysqlMessageQueue` uses polling rather than a push-based
> notification system, there is an inherent latency between when a message
> is enqueued and when it is delivered.  With the default 1-second poll
> interval, messages may take up to 1 second to be picked up.  You can
> lower the `pollInterval` option to reduce this latency at the cost of
> additional database load.

Best for
:   Production use in systems that already use MySQL or MariaDB.

Pros
:   Persistent, supports multiple workers, minimal additional infrastructure
for MySQL/MariaDB users.

Cons
:   Polling-based delivery (up to `pollInterval` latency); requires
MySQL 8.0+ or MariaDB 10.6+.

```typescript twoslash
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { MysqlMessageQueue } from "@fedify/mysql";
import mysql from "mysql2/promise";

const pool = mysql.createPool("mysql://user:pass@localhost/db");
const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: new MysqlMessageQueue(pool),  // [!code highlight]
  // ... other options
});
```

[`MysqlMessageQueue`]: https://jsr.io/@fedify/mysql/doc/mq/~/MysqlMessageQueue

### `SqliteMessageQueue`

*This API is available since Fedify 2.0.0.*

To use [`SqliteMessageQueue`], you need to install the *@fedify/sqlite* package
first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/sqlite
```

```bash [npm]
npm add @fedify/sqlite
```

```bash [pnpm]
pnpm add @fedify/sqlite
```

```bash [Yarn]
yarn add @fedify/sqlite
```

```bash [Bun]
bun add @fedify/sqlite
```

:::

[`SqliteMessageQueue`] is a message queue implementation that uses SQLite as
the backend.  It uses polling to check for new messages and is designed for
single-node deployments.  It's suitable for development, testing, and
small-scale production use where simplicity is preferred over high throughput.
It uses native sqlite modules, \[`node:sqlite`] for Node.js and Deno,
\[`bun:sqlite`] for Bun.

Best for
:   Development and testing.

Pros
:   Simple, persistent with minimal configuration.

Cons
:   Limited scalability, not suitable for high-traffic production.

> \[!NOTE]
> `SqliteMessageQueue` uses `DELETE ... RETURNING` to atomically fetch and
> delete the oldest message that is ready to be processed.  This requires
> SQLite 3.35.0 or later.

::: code-group

```typescript twoslash [Deno]
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { DatabaseSync } from "node:sqlite";
import { createFederation } from "@fedify/fedify";
import { SqliteMessageQueue } from "@fedify/sqlite";

const db = new DatabaseSync(":memory:");
const federation = createFederation<void>({
  // ...
  // ---cut-start---
    kv: null as unknown as KvStore,
  // ---cut-end---
  queue: new SqliteMessageQueue(db),  // [!code highlight]
});
```

```typescript twoslash [Node.js]
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { DatabaseSync } from "node:sqlite";
import { createFederation } from "@fedify/fedify";
import { SqliteMessageQueue } from "@fedify/sqlite";

const db = new DatabaseSync(":memory:");
const federation = createFederation<void>({
  // ...
  // ---cut-start---
    kv: null as unknown as KvStore,
  // ---cut-end---
  queue: new SqliteMessageQueue(db),  // [!code highlight]
});
```

```typescript [Bun]
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { Database } from "bun:sqlite";
import { createFederation } from "@fedify/fedify";
import { SqliteMessageQueue } from "@fedify/sqlite";

const db = new Database(":memory:");
const federation = createFederation<void>({
  // ...
  // ---cut-start---
    kv: null as unknown as KvStore,
  // ---cut-end---
  queue: new SqliteMessageQueue(db),  // [!code highlight]
});
```

:::

[`SqliteMessageQueue`]: https://jsr.io/@fedify/sqlite/doc/mq/~/SqliteMessageQueue

### `WorkersMessageQueue` (Cloudflare Workers only)

*This API is available since Fedify 1.6.0.*

To use the \[`WorkersMessageQueue`], you need to install the *@fedify/cfworkers*
package first:

::: code-group

```bash [Deno]
deno add jsr:@fedify/cfworkers
```

```bash [npm]
npm add @fedify/cfworkers
```

```bash [pnpm]
pnpm add @fedify/cfworkers
```

```bash [Yarn]
yarn add @fedify/cfworkers
```

```bash [Bun]
bun add @fedify/cfworkers
```

:::

`WorkersMessageQueue` is a message queue implementation for [Cloudflare Workers]
that uses Cloudflare's built-in [Cloudflare Queues] API.  It provides
scalability and high performance, making it suitable for production use in
Cloudflare Workers environments.  It requires a Cloudflare Queues setup and
management.

Best for
:   Production use in Cloudflare Workers environments.

Pros
:   Persistent, reliable, scalable, easy to set up, native retry with exponential
backoff and dead-letter queues.

Cons
:   Only available in Cloudflare Workers runtime.

```typescript twoslash
// @noErrors: 2322 2345
import type { FederationBuilder, KvStore } from "@fedify/fedify";
const builder = undefined as unknown as FederationBuilder<void>;
// ---cut-before---
import type { Federation, Message } from "@fedify/fedify";
import { WorkersMessageQueue } from "@fedify/cfworkers";

export default {
  async fetch(request, env, ctx) {
    const federation: Federation<void> = await builder.build({
// ---cut-start---
      kv: undefined as unknown as KvStore,
// ---cut-end---
      queue: new WorkersMessageQueue(env.QUEUE_BINDING),
    });
    // Omit the rest of the code for brevity
  },

  // Since defining a `queue()` method is the only way to consume messages
  // from the queue in Cloudflare Workers, we need to define it so that
  // the messages can be manually processed by `Federation.processQueuedTask()`
  // method:
  async queue(batch, env, ctx) {
    const federation: Federation<void> = await builder.build({
// ---cut-start---
      kv: undefined as unknown as KvStore,
// ---cut-end---
      queue: new WorkersMessageQueue(env.QUEUE_BINDING),
    });
    for (const msg of batch.messages) {
      await federation.processQueuedTask(
        undefined,  // You need to pass your context data here
        msg.body as Message,  // You need to cast the message body to `Message`
      );
    }
  }
} satisfies ExportedHandler<{ QUEUE_BINDING: Queue }>;
```

> \[!NOTE]
> Since your `Queue` is not bound to a global variable, but rather passed as
> an argument to the `fetch()` and `queue()` methods, you need to instantiate
> your `Federation` object inside these methods, rather than at the top level.
>
> For better organization, you probably want to use a builder pattern to
> register your dispatchers and listeners before instantiating the `Federation`
> object.  See the [*Builder pattern for structuring*
> section](./federation.md#builder-pattern-for-structuring) for details.

> \[!NOTE]
> The [Cloudflare Queues] API does not provide a way to poll messages from
> the queue, so `WorkersMessageQueue.listen()` method always throws
> a `TypeError` when invoked.  Instead, you should define a `queue()` method
> in your Cloudflare worker, which will be called by the Cloudflare Queues
> API when new messages are available in the queue.  Inside the `queue()`
> method, you need to call `Federation.processQueuedTask()` method to manually
> process the messages.  The `queue()` method is the only way to consume
> messages from the queue in Cloudflare Workers.

[Cloudflare Workers]: https://workers.cloudflare.com/

[Cloudflare Queues]: https://developers.cloudflare.com/queues/

## Implementing a custom `MessageQueue`

If the built-in implementations don't meet your needs, you can create a custom
`MessageQueue`.  Here's a guide to implementing your own:

### Implement the `MessageQueue` interface

Create a class that implements the `MessageQueue` interface, which includes
the `~MessageQueue.enqueue()` and `~MessageQueue.listen()` methods:

```typescript twoslash
import type {
  MessageQueue,
  MessageQueueEnqueueOptions,
  MessageQueueListenOptions,
} from "@fedify/fedify";

class CustomMessageQueue implements MessageQueue {
  // Set to true if your backend provides native retry mechanisms
  readonly nativeRetrial = false;

  async enqueue(
    message: any,
    options?: MessageQueueEnqueueOptions,
  ): Promise<void> {
    // Implementation here
  }

  async listen(
    handler: (message: any) => Promise<void> | void,
    options: MessageQueueListenOptions = {},
  ): Promise<void> {
    // Implementation here
  }
}
```

### Implement `~MessageQueue.enqueue()` method

This method should add the message to your queue system.
Handle the `~MessageQueueEnqueueOptions.delay` option if provided in
`MessageQueueEnqueueOptions`.  If provided, handle the
`~MessageQueueEnqueueOptions.orderingKey` option to ensure messages with the
same ordering key are processed sequentially.  Ensure the method is non-blocking
(use async operations where necessary).

### Implement `~MessageQueue.enqueueMany` method (optional)

*This API is available since Fedify 1.5.0.*

This method should add multiple messages to your queue system at once.
Handle the `~MessageQueueEnqueueOptions.delay` option if provided in
`MessageQueueEnqueueOptions`.  Ensure the method is non-blocking
(use async operations where necessary).

Although this method is optional, it's recommended to implement it
for better performance when enqueuing multiple messages at once.
Otherwise, Fedify will call `~MessageQueue.enqueue()` for each message
individually, which may be less efficient.

### Implement `~MessageQueue.listen()` method

This method should start a process that listens for new messages.
When a message is received, it should call the provided `handler` function.
Ensure proper error handling to prevent the listener from crashing.

> \[!NOTE]
> A `Promise` object it returns should never resolve unless the given
> `~MessageQueueListenOptions.signal` is triggered.

### Consider additional features

Here's a list of additional features you might want to implement in your
custom `MessageQueue`:

* *Message persistence*: Store messages in a database or file system
  if your backend doesn't provide persistence.
* *Multiple workers*: Guarantee a queue can be consumed by multiple workers.
* *Message acknowledgment*: Implement message acknowledgment to ensure
  messages are processed only once.

However, you don't need to implement retry logic yourself, as Fedify handles
retrying failed messages automatically.  If your message queue backend provides
native retry mechanisms (like exponential backoff, dead-letter queues, etc.),
you can set the `nativeRetrial` property to `true` to indicate this.
When this property is `true`, Fedify will skip its own retry logic and rely
on your backend to handle retries, avoiding duplicate retry mechanisms.

## Parallel message processing

*This API is available since Fedify 1.0.0.*

Fedify supports parallel message processing by running multiple workers
concurrently.  To enable parallel processing, wrap your `MessageQueue` with
`ParallelMessageQueue`, a special implementation of the `MessageQueue` interface
designed to process messages in parallel.  It acts as a decorator for another
`MessageQueue` implementation, allowing for concurrent processing of messages
up to a specified number of workers.  The `ParallelMessageQueue` inherits
the `nativeRetrial` property from the wrapped queue:

```typescript twoslash
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation, ParallelMessageQueue } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import Redis from "ioredis";

const baseQueue = new RedisMessageQueue(() => new Redis());

// Use parallelQueue in your Federation configuration
const federation = createFederation<void>({
  queue: new ParallelMessageQueue(baseQueue, 5),  // [!code highlight]
  // ... other options
  // ---cut-start---
  kv: null as unknown as KvStore,
  // ---cut-end---
});
```

> \[!NOTE]
> 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.
>
> If your [inbox listeners](./inbox.md) are CPU-bound, you should consider
> running multiple nodes of your application so that each node can process
> messages in parallel with the shared message queue.

> \[!WARNING]
> When using `ParallelMessageQueue(queue, N)` with [`PostgresMessageQueue`],
> make sure the PostgreSQL connection pool is sized to at least `N` plus a few
> extra connections.  If the pool is shared with other parts of your application
> (e.g., a KV store, HTTP request handlers), increase the pool size
> accordingly—or use a dedicated pool for the queue.  See the
> [*`PostgresMessageQueue`* section](#postgresmessagequeue) for details.

## Separating message processing from the main process

*This API is available since Fedify 1.0.0.*

On high-traffic servers, it's common to separate message processing from
the main server process to avoid blocking the main event loop.  To achieve this,
you can use the `~FederationOptions.manuallyStartQueue` option and
`Federation.startQueue()` method:

::: code-group

```typescript{11-17} twoslash [Deno]
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import Redis from "ioredis";

const federation = createFederation<void>({
  queue: new RedisMessageQueue(() => new Redis()),
  manuallyStartQueue: true,  // [!code highlight]
  // ... other options
  // ---cut-start---
  kv: null as unknown as KvStore,
  // ---cut-end---
});

// Start the message queue manually only in worker nodes.
// On non-worker nodes, the queue won't be started.
if (Deno.env.get("NODE_TYPE") === "worker") {
  const controller = new AbortController();
  Deno.addSignalListener("SIGINT", () => controller.abort());
  await federation.startQueue(undefined, { signal: controller.signal });
}
```

```typescript{12-18} twoslash [Node.js/Bun]
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import Redis from "ioredis";
import process from "node:process";

const federation = createFederation<void>({
  queue: new RedisMessageQueue(() => new Redis()),
  manuallyStartQueue: true,  // [!code highlight]
  // ... other options
  // ---cut-start---
  kv: null as unknown as KvStore,
  // ---cut-end---
});

// Start the message queue manually only in worker nodes.
// On non-worker nodes, the queue won't be started.
if (process.env.NODE_TYPE === "worker") {
  const controller = new AbortController();
  process.on("SIGINT", () => controller.abort());
  await federation.startQueue(undefined, { signal: controller.signal });
}
```

:::

The key point is to ensure that messages are enqueued only from
the `NODE_TYPE=web` nodes, and messages are processed only from
the `NODE_TYPE=worker` nodes:

| `NODE_TYPE` | Process messages? | Enqueue messages? |
| ----------- | ----------------- | ----------------- |
| `web`       | Do not process    | Enqueue           |
| `worker`    | Process           | Do not enqueue    |

This separation allows you to scale your application by running multiple worker
nodes that process messages concurrently.  It also helps to keep the main
server process responsive by offloading message processing to worker nodes.

> \[!NOTE]
> To ensure that messages are enqueued only from the `NODE_TYPE=web` nodes,
> you should not place the `NODE_TYPE=worker` nodes behind a load balancer.

## Native retry mechanisms

*This API is available since Fedify 1.7.0.*

Some message queue backends provide their own retry mechanisms with features
like exponential backoff, dead-letter queues, and automatic failure handling.
To avoid duplicate retry logic and improve efficiency, Fedify supports
the `~MessageQueue.nativeRetrial` property on `MessageQueue` implementations.

When `MessageQueue.nativeRetrial` is `true`, Fedify will skip its own retry
logic and rely entirely on the backend's native retry mechanisms.
When `false` or omitted, Fedify handles retries using its own retry policies.

### Current implementations

The following implementations currently support native retry:

`DenoKvMessageQueue`
:   Deno KV provides automatic retry with exponential backoff
(`~MessageQueue.nativeRetrial` is `true`).

`WorkersMessageQueue`
:   Cloudflare Queues provide automatic retry with exponential backoff and
dead-letter queues (`~MessageQueue.nativeRetrial` is `true`).

The following implementations do not yet support native retry:

`InProcessMessageQueue`
:   No native retry support (`~MessageQueue.nativeRetrial` is `false`).

[`RedisMessageQueue`]
:   Native retry support planned for future release.

[`PostgresMessageQueue`]
:   Native retry support planned for future release.

[`MysqlMessageQueue`]
:   No native retry support (`~MessageQueue.nativeRetrial` is `false`).

\[`AmqpMessageQueue`]
:   Native retry support planned for future release.

[`SqliteMessageQueue`]
:   No native retry support (`~MessageQueue.nativeRetrial` is `false`).

`ParallelMessageQueue` inherits the `~MessageQueue.nativeRetrial` value from
the wrapped queue.

### Benefits of native retry

Using native retry mechanisms provides several advantages:

Reduced overhead
:   Eliminates duplicate retry logic between Fedify and the message queue
backend.

Better reliability
:   Leverages proven retry mechanisms from established queue backends.

Improved observability
:   Backend-native retry mechanisms often provide better monitoring and
debugging capabilities.

Optimized performance
:   Backend-specific optimizations for retry logic.

## Ordering guarantees

*This API is available since Fedify 2.0.0.*

By default, message queues do not guarantee the order in which messages are
processed.  This can cause issues when related messages need to be processed
in a specific order.  For example, when a post is created and quickly deleted,
the `Delete` activity might arrive before the `Create` activity, resulting in
“zombie posts” that should have been deleted.

To address this, you can use the `~MessageQueueEnqueueOptions.orderingKey`
option when enqueuing messages.  Messages with the same ordering key are
guaranteed to be processed in the order they were enqueued.  Messages without
an ordering key or with different ordering keys can be processed in parallel.

```typescript twoslash
import type { KvStore, MessageQueue } from "@fedify/fedify";
declare const queue: MessageQueue;
// ---cut-before---
// These messages will be processed in order (1, 2, 3)
await queue.enqueue({ action: "create", noteId: "123" }, { orderingKey: "note:123" });
await queue.enqueue({ action: "update", noteId: "123" }, { orderingKey: "note:123" });
await queue.enqueue({ action: "delete", noteId: "123" }, { orderingKey: "note:123" });

// These messages can be processed in parallel with the above
await queue.enqueue({ action: "create", noteId: "456" }, { orderingKey: "note:456" });
await queue.enqueue({ action: "delete", noteId: "456" }, { orderingKey: "note:456" });
```

### Implementation support

The following implementations support ordering keys:

| Implementation           | Ordering Key Support |
| ------------------------ | -------------------- |
| `InProcessMessageQueue`  | Yes                  |
| [`DenoKvMessageQueue`]   | Yes                  |
| [`RedisMessageQueue`]    | Yes                  |
| [`PostgresMessageQueue`] | Yes                  |
| [`MysqlMessageQueue`]    | Yes                  |
| \[`AmqpMessageQueue`]     | Yes\[^1]              |
| [`SqliteMessageQueue`]   | Yes                  |
| `WorkersMessageQueue`    | Yes\[^2]              |

> \[!NOTE]
> When using `ParallelMessageQueue`, the ordering guarantee is preserved
> only if the underlying queue delivers messages in wrapper format with the
> ordering key embedded (currently `DenoKvMessageQueue` and
> `WorkersMessageQueue`).  For other implementations, ordering is handled
> internally by the queue itself, not by `ParallelMessageQueue`.
> Messages with the same ordering key will never be processed concurrently,
> ensuring sequential processing within each key.

\[^1]: `AmqpMessageQueue` requires the [`rabbitmq_consistent_hash_exchange`]
plugin to be enabled on the RabbitMQ server.  This is a Tier 1 plugin that
ships with RabbitMQ but is not enabled by default.  Enable it with:

```
  ~~~~ bash
  rabbitmq-plugins enable rabbitmq_consistent_hash_exchange
  ~~~~
```

\[^2]: `WorkersMessageQueue` requires a Workers KV namespace to be provided for
ordering key locks. Due to Workers KV's eventual consistency, the ordering
guarantee is best-effort. For strict ordering requirements, consider using
Durable Objects.

[`rabbitmq_consistent_hash_exchange`]: https://www.rabbitmq.com/docs/consistent-hash-exchange

## Using different message queues for different tasks

*This API is available since Fedify 1.3.0.*

In some cases, you may want to use different message queues for different tasks,
such as using a faster-but-less-persistent queue for outgoing activities and
a slower-but-more-persistent queue for incoming activities.  To achieve this,
you can pass `FederationQueueOptions` to the `FederationOptions.queue`
option.

For example, the following code shows how to use a [`PostgresMessageQueue`] for
the inbox and a [`RedisMessageQueue`] for the outbox:

```typescript twoslash
import {
  createFederation,
  type KvStore,
  MemoryKvStore,
  type MessageQueue,
} from "@fedify/fedify";
import { PostgresMessageQueue } from "@fedify/postgres";
import { RedisMessageQueue } from "@fedify/redis";
import postgres from "postgres";
import Redis from "ioredis";

// ---cut-before---
const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: {
    inbox: new PostgresMessageQueue(
      postgres("postgresql://user:pass@localhost/db")
    ),
    outbox: new RedisMessageQueue(() => new Redis()),
  },
  // ... other options
});
```

Or, you can provide a message queue for only the `inbox` or `outbox` by omitting
the other:

```typescript twoslash
import {
  createFederation,
  type KvStore,
  MemoryKvStore,
  type MessageQueue,
} from "@fedify/fedify";
import { PostgresMessageQueue } from "@fedify/postgres";
import postgres from "postgres";

// ---cut-before---
const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  queue: {
    inbox: new PostgresMessageQueue(
      postgres("postgresql://user:pass@localhost/db")
    ),
    // outbox is not provided; outgoing activities will not be queued
  },
  // ... other options
});
```

When you [manually start a task
worker](#separating-message-processing-from-the-main-process), you can specify
which queue to start (if `queue` is not provided in the options, it will start
all queues).  The following example shows how to start only the `inbox` queue:

::: code-group

```typescript twoslash [Deno]
import type { KvStore } from "@fedify/fedify";
import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import Redis from "ioredis";

const federation = createFederation<void>({
  queue: new RedisMessageQueue(() => new Redis()),
  manuallyStartQueue: true,  // [!code highlight]
  // ... other options
  // ---cut-start---
  kv: null as unknown as KvStore,
  // ---cut-end---
});

// ---cut-before---
if (Deno.env.get("NODE_TYPE") === "worker") {
  const controller = new AbortController();
  Deno.addSignalListener("SIGINT", () => controller.abort());
  await federation.startQueue(undefined, {
    signal: controller.signal,
    queue: "inbox",  // [!code highlight]
  });
}
```

```typescript twoslash [Node.js/Bun]
import type { KvStore } from "@fedify/fedify";
import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import Redis from "ioredis";
import process from "node:process";

const federation = createFederation<void>({
  queue: new RedisMessageQueue(() => new Redis()),
  manuallyStartQueue: true,  // [!code highlight]
  // ... other options
  // ---cut-start---
  kv: null as unknown as KvStore,
  // ---cut-end---
});

// ---cut-before---
if (process.env.NODE_TYPE === "worker") {
  const controller = new AbortController();
  process.on("SIGINT", () => controller.abort());
  await federation.startQueue(undefined, {
    signal: controller.signal,
    queue: "inbox",  // [!code highlight]
  });
}
```

:::

---

---
url: /manual/nodeinfo.md
description: >-
  According to the official NodeInfo website, NodeInfo is an effort to create a
  standardized way of exposing metadata about a server running one of the
  distributed social networks.  This section explains how to expose a NodeInfo
  endpoint and the key properties of a NodeInfo object.
---

# NodeInfo

*This API is available since Fedify 0.2.0.*

According to the official [NodeInfo] website:

> NodeInfo is an effort to create a standardized way of exposing metadata
> about a server running one of the distributed social networks.
> The two key goals are being able to get better insights into the user base of
> distributed social networking and the ability to build tools that allow
> users to choose the best-fitting software and server for their needs.

In fact, many ActivityPub servers, including Mastodon and Misskey, provide
NodeInfo endpoints.  Fedify provides a way to expose NodeInfo endpoints for
your server.

> \[!NOTE]
> The version of NodeInfo that Fedify supports is 2.1.

[NodeInfo]: https://nodeinfo.diaspora.software/

## Exposing NodeInfo endpoint

To expose a NodeInfo endpoint, you need to register a NodeInfo dispatcher with
`~Federatable.setNodeInfoDispatcher()` method.  The following shows how to
expose a NodeInfo endpoint:

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
});

federation.setNodeInfoDispatcher("/nodeinfo/2.1", async (ctx) => {
  return {
    software: {
      name: "your-software-name",  // Lowercase, digits, and hyphens only.
      version: { major: 1, minor: 0, patch: 0 },
      homepage: new URL("https://your-software.com/"),
    },
    protocols: ["activitypub"],
    usage: {
      // Usage statistics is hard-coded here for demonstration purposes.
      // You should replace these with real statistics:
      users: { total: 100, activeHalfyear: 50, activeMonth: 20 },
      localPosts: 1000,
      localComments: 2000,
    }
  }
});
```

For details about the `NodeInfo` interface,
see the [next section](#nodeinfo-schema).

> \[!TIP]
> You don't have to use */nodeinfo/2.1* as the path, but it is quite common
> among ActivityPub servers.

> \[!NOTE]
> Whether or not you expose a NodeInfo endpoint, */.well-known/nodeinfo* is
> automatically handled by `Federation.fetch()` method.  In case you don't
> register a NodeInfo dispatcher, Fedify will respond with an empty `links`
> array, e.g.:
>
> ```json
> {
>   "links": []
> }
> ```

## NodeInfo schema

The `NodeInfo` interface is defined as follows:

`software.name`
:   *Required.*  The canonical name of the server software.  This must comply
with pattern `/^[a-z0-9-]+$/`.

`software.version`
:   *Required.*  The version of the server software.

`software.repository`
:   The [`URL`] of the source code repository of the server software.

`software.homepage`
:   The [`URL`] of the homepage of the server software.

`protocols`
:   *Required and non-empty.*  The protocols supported on the server.  At least
one protocol must be supported.   You usually put `["activitypub"]` here.

`services.inbound`
:   The third party sites the server can retrieve messages from for combined
display with regular traffic.

`services.outbound`
:   The third party sites the server can publish messages to on the behalf of
a user.

`openRegistrations`
:   Whether the server allows open self-registration.  Defaults to `false`.

`usage.users.total`
:   The total amount of on the server registered users.  This `number` has to
be an integer greater than or equal to zero.

`usage.users.activeHalfyear`
:   The amount of users that signed in at least once in the last 180 days.
This `number` has to be an integer greater than or equal to zero.

`usage.users.activeMonth`
:   The amount of users that signed in at least once in the last 30 days.
This `number` has to be an integer greater than or equal to zero.

`usage.localPosts`
:   The amount of posts that were made by users that are registered on
the server.  This `number` has to be an integer greater than or equal to
zero.

`usage.localComments`
:   The amount of comments that were made by users that are registered on
the server.  This `number` has to be an integer greater than or equal to
zero.

[`URL`]: https://developer.mozilla.org/en-US/docs/Web/API/URL

## NodeInfo client

*This API is available since Fedify 1.4.0.*

You may want to fetch NodeInfo objects from other servers.  Fedify provides
a way to fetch NodeInfo objects with the `Context.lookupNodeInfo()` method:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const nodeInfo = await ctx.lookupNodeInfo("https://example.com/");
if (nodeInfo != null) console.log(nodeInfo);
```

The `Context.lookupNodeInfo()` method returns a `NodeInfo` object if the server
provides a NodeInfo endpoint and the response is valid.  Otherwise, it returns
`undefined`.

> \[!TIP]
> Sometimes, a server may provide a slightly invalid NodeInfo object.  In such
> case, you can enforce parsing the object by passing `{ parse: "best-effort" }`
> option as the second argument to `Context.lookupNodeInfo()` method:
>
> ```typescript twoslash
> import { type Context } from "@fedify/fedify";
> const ctx = null as unknown as Context<void>;
> // ---cut-before---
> const nodeInfo = await ctx.lookupNodeInfo("https://example.com/", {
>   parse: "best-effort",
> });
>
> if (nodeInfo != null) console.log(nodeInfo);
> ```
>
> However, it does not guarantee that parsing will always succeed.  It just
> tries to parse the object as much as possible.

---

---
url: /manual/object.md
description: >-
  You can register an object dispatcher so that Fedify can dispatch an
  appropriate object by its class and URL arguments.  This section explains how
  to register an object dispatcher.
---

# Object dispatcher

*This API is available since Fedify 0.7.0.*

In ActivityPub, [objects] are entities that can be attached to activities or
other objects.  Objects sometimes need to be resolved by their dereferenceable
URIs.  To let objects be resolved, you can register object dispatchers so that
Fedify can dispatch an appropriate object by its class and URL arguments.

An object dispatcher is a callback function that takes a `Context` object and
URL arguments, and returns an object.  Every object dispatcher has one or more
URL parameters that are used to dispatch the object.  The URL parameters are
specified in the path pattern of the object dispatcher, e.g., `/notes/{id}`,
`/users/{userId}/articles/{articleId}`.

The below example shows how to register an object dispatcher:

```typescript{7-19} twoslash
// @noErrors: 2345
const note: { id: string; content: string } = { id: "", content: "" };
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
});

federation.setObjectDispatcher(
  Note,
  "/users/{userId}/notes/{noteId}",
  async (ctx, { userId, noteId }) => {
    // Work with the database to find the note by the author ID and the note ID.
    if (note == null) return null;  // Return null if the note is not found.
    return new Note({
      id: ctx.getObjectUri(Note, { userId, noteId }),
      content: note.content,
      // Many more properties...
    });
  }
);
```

In the above example, the `~Federatable.setObjectDispatcher()` method registers
an object dispatcher for the `Note` class and
the `/users/{userId}/notes/{noteId}` path.  This pattern syntax follows
the [URI Template] specification.

> \[!NOTE]
> The URI Template syntax supports different expansion types like `{userId}`
> (simple expansion) and `{+userId}` (reserved expansion).  If your
> identifiers contain URIs or special characters, you may need to use
> `{+userId}` to avoid double-encoding issues.  See the
> [*URI Template* guide](./uri-template.md) for details.

[objects]: https://www.w3.org/TR/activitystreams-core/#object

[URI Template]: https://datatracker.ietf.org/doc/html/rfc6570

## Constructing object URIs

To construct an object URI, you can use the `Context.getObjectUri()` method.
This method takes a class and URL arguments, and returns a dereferenceable URI
of the object.

The below example shows how to construct an object URI:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
// ---cut-before---
ctx.getObjectUri(Note, {
  userId: "2bd304f9-36b3-44f0-bf0b-29124aafcbb4",
  noteId: "9f60274d-f6c2-4e3f-8eae-447f4416c0fb",
})
```

> \[!NOTE]
>
> The `Context.getObjectUri()` method does not guarantee that the object
> actually exists.  It only constructs a URI based on the given class and URL
> arguments, which may respond with `404 Not Found`.  Make sure to check
> if the arguments are valid before calling the method.

---

---
url: /manual/opentelemetry.md
description: >-
  OpenTelemetry is a set of APIs, libraries, agents, and instrumentation to
  provide observability to your applications.  Fedify supports OpenTelemetry for
  tracing.  This document explains how to use OpenTelemetry with Fedify.
---

# OpenTelemetry

*This API is available since Fedify 1.3.0.*

[OpenTelemetry] is a standardized set of APIs, libraries, agents, and
instrumentation to provide observability to your applications.  Fedify supports
OpenTelemetry for tracing.  This document explains how to use OpenTelemetry with
Fedify.

[OpenTelemetry]: https://opentelemetry.io/

## Setting up OpenTelemetry

> \[!TIP]
> If you are using Deno 2.2 or later, you can use Deno's built-in OpenTelemetry
> support.  See the [*Using Deno's built-in OpenTelemetry support*
> section](#using-deno-s-built-in-opentelemetry-support) for more details.

To trace your Fedify application with OpenTelemetry, you need to set up the
OpenTelemetry SDK.  First of all, you need to install the OpenTelemetry SDK and
the tracer exporter you want to use.  For example, if you want to use the trace
exporter for OTLP (http/protobuf), you should install the following packages:

::: code-group

```sh [Deno]
deno add npm:@opentelemetry/sdk-node npm:@opentelemetry/exporter-trace-otlp-proto
```

```sh [Node.js]
npm add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto
```

```sh [Bun]
bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto
```

:::

Then you can set up the OpenTelemetry SDK in your Fedify application.  Here is
an example code snippet to set up the OpenTelemetry SDK with the OTLP trace
exporter:

```typescript twoslash
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

const sdk = new NodeSDK({
  serviceName: "my-fedify-app",
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4317",
    headers: { "x-some-header": "some-value" }
  }),
});

sdk.start();
```

> \[!CAUTION]
> The above code which sets up the OpenTelemetry SDK needs to be executed before
> the Fedify server starts.  Otherwise, the tracing may not work as expected.

## Using Deno's built-in OpenTelemetry support

Since Deno 2.2, Deno has [built-in support for OpenTelemetry][deno-otel].
This means you can use OpenTelemetry with your Fedify application on Deno
without manually setting up the OpenTelemetry SDK.

To enable the OpenTelemetry integration in Deno, you need to:

1. Run your Deno script with the `--unstable-otel` flag
2. Set the environment variable `OTEL_DENO=true`

For example:

```sh
OTEL_DENO=true deno run --unstable-otel your_fedify_app.ts
```

This will automatically collect and export runtime observability data to
an OpenTelemetry endpoint at `localhost:4318` using Protobuf over HTTP
(http/protobuf).

You can customize the endpoint and protocol using environment variables like
`OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_PROTOCOL`.
For authentication, you can use the `OTEL_EXPORTER_OTLP_HEADERS` environment
variable.

[deno-otel]: https://docs.deno.com/runtime/fundamentals/open_telemetry/

## Explicit [`TracerProvider`] configuration

The `createFederation()` function accepts the
[`tracerProvider`](./federation.md#tracerprovider) option to explicitly
configure the [`TracerProvider`] for the OpenTelemetry SDK.  Note that if it's
omitted, Fedify will use the global default [`TracerProvider`] provided by
the OpenTelemetry SDK.

For example, if you want to use [Sentry] as the trace exporter, you can set up
the Sentry SDK and pass the [`TracerProvider`] provided by the Sentry SDK to the
`createFederation()` function:

```typescript twoslash
// @noErrors: 2339
import type { KvStore } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { getClient } from "@sentry/node";

const federation = createFederation<void>({
// ---cut-start---
  kv: null as unknown as KvStore,
// ---cut-end---
  // Omitted for brevity; see the related section for details.
  tracerProvider: getClient()?.traceProvider,
});
```

> \[!CAUTION]
> The Sentry SDK's OpenTelemetry integration is available since [@sentry/node]
> 8.0.0, and it's not available yet in [@sentry/deno] or [@sentry/bun] as of
> November 2024.
>
> For more information about the Sentry SDK's OpenTelemetry integration, please
> refer to the [*OpenTelemetry Support* section] in the Sentry SDK docs.

[`TracerProvider`]: https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.TracerProvider.html

[Sentry]: https://sentry.io/

[@sentry/node]: https://npmjs.com/package/@sentry/node

[@sentry/deno]: https://npmjs.com/package/@sentry/deno

[@sentry/bun]: https://npmjs.com/package/@sentry/bun

[*OpenTelemetry Support* section]: https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/

## Instrumented spans

Fedify automatically instruments the following operations with OpenTelemetry
spans:

| Span name                                           | [Span kind] | Description                                   |
| --------------------------------------------------- | ----------- | --------------------------------------------- |
| `{method} {template}`                               | Server      | Serves the incoming HTTP request.             |
| `activitypub.dispatch_actor`                        | Server      | Dispatches the ActivityPub actor.             |
| `activitypub.dispatch_actor_key_pairs`              | Server      | Dispatches the ActivityPub actor key pairs.   |
| `activitypub.dispatch_collection {collection}`      | Server      | Dispatches the ActivityPub collection.        |
| `activitypub.dispatch_collection_page {collection}` | Server      | Dispatches the ActivityPub collection page.   |
| `activitypub.dispatch_inbox_listener {type}`        | Internal    | Dispatches the ActivityPub inbox listener.    |
| `activitypub.dispatch_object`                       | Server      | Dispatches the Activity Streams object.       |
| `activitypub.fanout`                                | Consumer    | Dequeues the ActivityPub activity to fan out. |
| `activitypub.fanout`                                | Producer    | Enqueues the ActivityPub activity to fan out. |
| `activitypub.fetch_key`                             | Client      | Fetches the public keys for the actor.        |
| `activitypub.get_actor_handle`                      | Client      | Resolves the actor handle.                    |
| `activitypub.inbox`                                 | Consumer    | Dequeues the ActivityPub activity to receive. |
| `activitypub.inbox`                                 | Internal    | Manually routes the ActivityPub activity.     |
| `activitypub.inbox`                                 | Producer    | Enqueues the ActivityPub activity to receive. |
| `activitypub.inbox`                                 | Server      | Receives the ActivityPub activity.            |
| `activitypub.lookup_object`                         | Client      | Looks up the Activity Streams object.         |
| `activitypub.outbox`                                | Client      | Sends the ActivityPub activity.               |
| `activitypub.outbox`                                | Consumer    | Dequeues the ActivityPub activity to send.    |
| `activitypub.outbox`                                | Producer    | Enqueues the ActivityPub activity to send.    |
| `activitypub.parse_object`                          | Internal    | Parses the Activity Streams object.           |
| `activitypub.fetch_document`                        | Client      | Fetches a remote JSON-LD document.            |
| `activitypub.send_activity`                         | Client      | Sends the ActivityPub activity.               |
| `activitypub.verify_key_ownership`                  | Internal    | Verifies actor ownership of a key.            |
| `http_signatures.sign`                              | Internal    | Signs the HTTP request.                       |
| `http_signatures.verify`                            | Internal    | Verifies the HTTP request signature.          |
| `ld_signatures.sign`                                | Internal    | Makes the Linked Data signature.              |
| `ld_signatures.verify`                              | Internal    | Verifies the Linked Data signature.           |
| `object_integrity_proofs.sign`                      | Internal    | Makes the object integrity proof.             |
| `object_integrity_proofs.verify`                    | Internal    | Verifies the object integrity proof.          |
| `webfinger.handle`                                  | Server      | Handles the WebFinger request.                |
| `webfinger.lookup`                                  | Client      | Looks up the WebFinger resource.              |

More operations will be instrumented in the future releases.

[Span kind]: https://opentelemetry.io/docs/specs/otel/trace/api/#spankind

## Span events

In addition to spans, Fedify also records [span events] to capture rich,
structured data about key operations.  Span events allow recording complex data
that wouldn't fit in span attributes (which are limited to primitive values).

The following span events are recorded:

| Event name                      | Recorded on span            | Description                                                                      |
| ------------------------------- | --------------------------- | -------------------------------------------------------------------------------- |
| `activitypub.activity.received` | `activitypub.inbox`         | Records full activity JSON and verification status when an activity is received. |
| `activitypub.activity.sent`     | `activitypub.send_activity` | Records full activity JSON and delivery details when an activity is sent.        |
| `activitypub.object.fetched`    | `activitypub.lookup_object` | Records full object JSON when successfully fetched.                              |

[span events]: https://opentelemetry.io/docs/concepts/signals/traces/#span-events

### Event attributes

Each span event includes attributes with detailed information:

**`activitypub.activity.received` event attributes:**

* `activitypub.activity.json`: The complete activity JSON
* `activitypub.activity.verified`: Whether the activity was verified
  (`true`/`false`)
* `ld_signatures.verified`: Whether Linked Data Signatures were verified
  (`true`/`false`)
* `http_signatures.verified`: Whether HTTP Signatures were verified
  (`true`/`false`)
* `http_signatures.key_id`: The key ID used for HTTP signature verification
* `http_signatures.failure_reason` (optional): Why HTTP signature
  verification failed (`noSignature`, `invalidSignature`, or
  `keyFetchError`)
* `http_signatures.key_fetch_status` (optional): The HTTP status code when
  fetching the signing key failed with an HTTP response
* `http_signatures.key_fetch_error` (optional): The error type when fetching
  the signing key failed without an HTTP response

**`activitypub.activity.sent` event attributes:**

* `activitypub.activity.json`: The complete activity JSON being sent
* `activitypub.inbox.url`: The inbox URL where the activity was delivered
* `activitypub.activity.id`: The activity ID

**`activitypub.object.fetched` event attributes:**

* `activitypub.object.type`: The type URI of the fetched object
* `activitypub.object.json`: The complete object JSON

## Semantic [attributes] for ActivityPub

The [OpenTelemetry Semantic Conventions] currently do not have a specification
for ActivityPub as of November 2024.  However, Fedify provides a set of semantic
[attributes] for ActivityPub.  The following table shows the semantic attributes
for ActivityPub:

| Attribute                             | Type     | Description                                                                                                              | Example                                                              |
| ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `activitypub.activity.id`             | string   | The URI of the activity object.                                                                                          | `"https://example.com/activity/1"`                                   |
| `activitypub.activity.type`           | string\[] | The qualified URI(s) of the activity type(s).                                                                            | `["https://www.w3.org/ns/activitystreams#Create"]`                   |
| `activitypub.activity.to`             | string\[] | The URI(s) of the recipient collections/actors of the activity.                                                          | `["https://example.com/1/followers/2"]`                              |
| `activitypub.activity.cc`             | string\[] | The URI(s) of the carbon-copied recipient collections/actors of the activity.                                            | `["https://www.w3.org/ns/activitystreams#Public"]`                   |
| `activitypub.activity.bto`            | string\[] | The URI(s) of the blind recipient collections/actors of the activity.                                                    | `["https://example.com/1/followers/2"]`                              |
| `activitypub.activity.bcc`            | string\[] | The URI(s) of the blind carbon-copied recipient collections/actors of the activity.                                      | `["https://www.w3.org/ns/activitystreams#Public"]`                   |
| `activitypub.activity.retries`        | int      | The ordinal number of activity resending attempt (if and only if it's retried).                                          | `3`                                                                  |
| `activitypub.actor.id`                | string   | The URI of the actor object.                                                                                             | `"https://example.com/actor/1"`                                      |
| `activitypub.actor.key.cached`        | boolean  | Whether the actor's public keys are cached.                                                                              | `true`                                                               |
| `activitypub.actor.type`              | string\[] | The qualified URI(s) of the actor type(s).                                                                               | `["https://www.w3.org/ns/activitystreams#Person"]`                   |
| `activitypub.key.id`                  | string   | The URI of the cryptographic key being verified.                                                                         | `"https://example.com/actor/1#main-key"`                             |
| `activitypub.key_ownership.method`    | string   | The method used to verify key ownership (`owner_id` or `actor_fetch`).                                                   | `"actor_fetch"`                                                      |
| `activitypub.key_ownership.verified`  | boolean  | Whether the key ownership was successfully verified.                                                                     | `true`                                                               |
| `activitypub.collection.id`           | string   | The URI of the collection object.                                                                                        | `"https://example.com/collection/1"`                                 |
| `activitypub.collection.type`         | string\[] | The qualified URI(s) of the collection type(s).                                                                          | `["https://www.w3.org/ns/activitystreams#OrderedCollection"]`        |
| `activitypub.collection.total_items`  | int      | The total number of items in the collection.                                                                             | `42`                                                                 |
| `activitypub.object.id`               | string   | The URI of the object or the object enclosed by the activity.                                                            | `"https://example.com/object/1"`                                     |
| `activitypub.object.type`             | string\[] | The qualified URI(s) of the object type(s).                                                                              | `["https://www.w3.org/ns/activitystreams#Note"]`                     |
| `activitypub.object.in_reply_to`      | string\[] | The URI(s) of the original object to which the object reply.                                                             | `["https://example.com/object/1"]`                                   |
| `activitypub.inboxes`                 | int      | The number of inboxes the activity is sent to.                                                                           | `12`                                                                 |
| `activitypub.shared_inbox`            | boolean  | Whether the activity is sent to the shared inbox.                                                                        | `true`                                                               |
| `docloader.context_url`               | string   | The URL of the JSON-LD context document (if provided via Link header).                                                   | `"https://www.w3.org/ns/activitystreams"`                            |
| `docloader.document_url`              | string   | The final URL of the fetched document (after following redirects).                                                       | `"https://example.com/object/1"`                                     |
| `fedify.actor.identifier`             | string   | The identifier of the actor.                                                                                             | `"1"`                                                                |
| `fedify.inbox.recipient`              | string   | The identifier of the inbox recipient.                                                                                   | `"1"`                                                                |
| `fedify.object.type`                  | string   | The URI of the object type.                                                                                              | `"https://www.w3.org/ns/activitystreams#Note"`                       |
| `fedify.object.values.{parameter}`    | string\[] | The argument values of the object dispatcher.                                                                            | `["1", "2"]`                                                         |
| `fedify.collection.cursor`            | string   | The cursor of the collection.                                                                                            | `"eyJpZCI6IjEiLCJ0eXBlIjoiT3JkZXJlZENvbGxlY3Rpb24ifQ=="`             |
| `fedify.collection.items`             | number   | The number of items in the collection page.  It can be less than the total items.                                        | `10`                                                                 |
| `http.redirect.url`                   | string   | The redirect URL when a document fetch results in a redirect.                                                            | `"https://example.com/new-location"`                                 |
| `http.response.status_code`           | int      | The HTTP response status code.                                                                                           | `200`                                                                |
| `http_signatures.signature`           | string   | The signature of the HTTP request in hexadecimal.                                                                        | `"73a74c990beabe6e59cc68f9c6db7811b59cbb22fd12dcffb3565b651540efe9"` |
| `http_signatures.algorithm`           | string   | The algorithm of the HTTP request signature.                                                                             | `"rsa-sha256"`                                                       |
| `http_signatures.key_id`              | string   | The public key ID of the HTTP request signature.                                                                         | `"https://example.com/actor/1#main-key"`                             |
| `http_signatures.verified`            | boolean  | Whether the HTTP request signature was verified successfully.                                                            | `false`                                                              |
| `http_signatures.failure_reason`      | string   | Why HTTP signature verification failed (`noSignature`, `invalidSignature`, or `keyFetchError`).                          | `"keyFetchError"`                                                    |
| `http_signatures.key_fetch_status`    | int      | The HTTP status code from a failed signing-key fetch, when available.                                                    | `410`                                                                |
| `http_signatures.key_fetch_error`     | string   | The error type from a non-HTTP signing-key fetch failure, when available.                                                | `"TypeError"`                                                        |
| `http_signatures.digest.{algorithm}`  | string   | The digest of the HTTP request body in hexadecimal.  The `{algorithm}` is the digest algorithm (e.g., `sha`, `sha-256`). | `"d41d8cd98f00b204e9800998ecf8427e"`                                 |
| `ld_signatures.key_id`                | string   | The public key ID of the Linked Data signature.                                                                          | `"https://example.com/actor/1#main-key"`                             |
| `ld_signatures.signature`             | string   | The signature of the Linked Data in hexadecimal.                                                                         | `"73a74c990beabe6e59cc68f9c6db7811b59cbb22fd12dcffb3565b651540efe9"` |
| `ld_signatures.type`                  | string   | The algorithm of the Linked Data signature.                                                                              | `"RsaSignature2017"`                                                 |
| `object_integrity_proofs.cryptosuite` | string   | The cryptographic suite of the object integrity proof.                                                                   | `"eddsa-jcs-2022"`                                                   |
| `object_integrity_proofs.key_id`      | string   | The public key ID of the object integrity proof.                                                                         | `"https://example.com/actor/1#main-key"`                             |
| `object_integrity_proofs.signature`   | string   | The integrity proof of the object in hexadecimal.                                                                        | `"73a74c990beabe6e59cc68f9c6db7811b59cbb22fd12dcffb3565b651540efe9"` |
| `url.full`                            | string   | The full URL being fetched by the document loader.                                                                       | `"https://example.com/actor/1"`                                      |
| `webfinger.resource`                  | string   | The queried resource URI.                                                                                                | `"acct:fedify@hollo.social"`                                         |
| `webfinger.resource.scheme`           | string   | The scheme of the queried resource URI.                                                                                  | `"acct"`                                                             |

[attributes]: https://opentelemetry.io/docs/specs/otel/common/#attribute

[OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/specs/semconv/

## Building observability tools with OpenTelemetry

The OpenTelemetry instrumentation in Fedify provides a powerful foundation for
building custom observability tools.  By implementing a custom [SpanExporter],
you can capture and process all the telemetry data generated by Fedify to build
tools like debug dashboards, activity monitors, or analytics systems.

[SpanExporter]: https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk_trace_base.SpanExporter.html

### Example: ActivityPub debug dashboard

Here's an example of how you might implement a custom `SpanExporter` to capture
ActivityPub activities for a debug dashboard:

```typescript
import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { ExportResultCode } from "@opentelemetry/core";

interface ActivityRecord {
  direction: "inbound" | "outbound";
  activity: unknown;
  timestamp: Date;
  verified?: boolean;
}

export class FedifyDebugExporter implements SpanExporter {
  private activities: ActivityRecord[] = [];

  export(spans: ReadableSpan[], resultCallback: (result: { code: ExportResultCode }) => void): void {
    for (const span of spans) {
      // Capture inbound activities
      if (span.name === "activitypub.inbox") {
        const event = span.events.find(
          (e) => e.name === "activitypub.activity.received"
        );
        if (event && event.attributes) {
          this.activities.push({
            direction: "inbound",
            activity: JSON.parse(
              event.attributes["activitypub.activity.json"] as string
            ),
            timestamp: new Date(span.startTime[0] * 1000),
            verified: event.attributes["activitypub.activity.verified"] as boolean,
          });
        }
      }

      // Capture outbound activities
      if (span.name === "activitypub.send_activity") {
        const event = span.events.find(
          (e) => e.name === "activitypub.activity.sent"
        );
        if (event && event.attributes) {
          this.activities.push({
            direction: "outbound",
            activity: JSON.parse(
              event.attributes["activitypub.activity.json"] as string
            ),
            timestamp: new Date(span.startTime[0] * 1000),
          });
        }
      }
    }
    resultCallback({ code: ExportResultCode.SUCCESS });
  }

  async forceFlush(): Promise<void> {
    // Flush any pending data
  }

  async shutdown(): Promise<void> {
    // Clean up resources
  }

  getActivities(): ActivityRecord[] {
    return this.activities;
  }
}
```

### Integrating the custom exporter

To use the custom exporter, add it to your OpenTelemetry SDK configuration:

```typescript
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { createFederation } from "@fedify/fedify";

const debugExporter = new FedifyDebugExporter();
const tracerProvider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(debugExporter)],
});

const federation = createFederation({
  kv: /* your KV store */,
  tracerProvider,
});
```

Now the `debugExporter` will receive all telemetry data from Fedify, and you
can use `debugExporter.getActivities()` to access the captured activities for
your debug dashboard or other observability tools.

## Distributed trace storage with `FedifySpanExporter`

*This API is available since Fedify 1.10.0.*

The example `FedifyDebugExporter` shown above stores activities in memory,
which works well for single-process applications.  However, Fedify applications
often run in distributed environments where:

* The web server handling HTTP requests runs on different nodes than
  the background workers processing the message queue.
* Multiple worker nodes may process queued messages in parallel.
* The debug dashboard itself may run on yet another node.

In such environments, an in-memory exporter cannot aggregate traces across
nodes.  Each node would only see its own spans, making it impossible to view
the complete picture of a distributed trace.

Fedify provides [`FedifySpanExporter`] which persists trace data to a
[`KvStore`](./kv.md), enabling distributed tracing across multiple nodes.
All nodes can write to the same storage, and your debug dashboard can query
this shared storage to display complete traces.

[`FedifySpanExporter`]: https://jsr.io/@fedify/fedify/doc/otel/~/FedifySpanExporter

### Setting up `FedifySpanExporter`

To use `FedifySpanExporter`, import it from the `@fedify/fedify/otel` module
and configure it with a [`KvStore`](./kv.md):

::: code-group

```typescript twoslash [Deno]
import type { KvStore, MessageQueue } from "@fedify/fedify";
// ---cut-before---
import { createFederation } from "@fedify/fedify";
import { RedisKvStore } from "@fedify/redis";
import { FedifySpanExporter } from "@fedify/fedify/otel";
import {
  BasicTracerProvider,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
import Redis from "ioredis";

const redis = new Redis();
const kv = new RedisKvStore(redis);

// Create the exporter that writes to KvStore
const fedifyExporter = new FedifySpanExporter(kv, {
  ttl: Temporal.Duration.from({ hours: 1 }),
});

const tracerProvider = new BasicTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(fedifyExporter)],
});

const federation = createFederation<void>({
  kv,
  tracerProvider,
// ---cut-start---
  queue: null as unknown as MessageQueue,
// ---cut-end---
  // Omitted for brevity; see the related section for details.
});
```

```typescript [Node.js]
import { createFederation } from "@fedify/fedify";
import { RedisKvStore } from "@fedify/redis";
import { FedifySpanExporter } from "@fedify/fedify/otel";
import { NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node";
import Redis from "ioredis";

const redis = new Redis();
const kv = new RedisKvStore(redis);

// Create the exporter that writes to KvStore
const fedifyExporter = new FedifySpanExporter(kv, {
  ttl: Temporal.Duration.from({ hours: 1 }),
});

const tracerProvider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(fedifyExporter)],
});

const federation = createFederation({
  kv,
  tracerProvider,
  // Omitted for brevity; see the related section for details.
});
```

:::

### Querying stored traces

The `FedifySpanExporter` provides methods to query stored trace data:

```typescript twoslash
import { MemoryKvStore } from "@fedify/fedify";
import { FedifySpanExporter } from "@fedify/fedify/otel";
const kv = new MemoryKvStore();
const fedifyExporter = new FedifySpanExporter(kv);
const traceId = "";
// ---cut-before---
// Get all activities for a specific trace
const activities = await fedifyExporter.getActivitiesByTraceId(traceId);

// Get recent traces (with optional limit)
const recentTraces = await fedifyExporter.getRecentTraces({ limit: 100 });
```

> \[!NOTE]
> The `~FedifySpanExporter.getRecentTraces()` method requires a `KvStore`
> implementation that supports the `list()` method.  When using a store
> that only provides `cas()` without `list()` support, this method will
> return an empty array.

Each `TraceActivityRecord` contains:

* `traceId`: The OpenTelemetry trace ID
* `spanId`: The OpenTelemetry span ID
* `parentSpanId`: The parent span ID (if any)
* `direction`: `"inbound"` or `"outbound"`
* `activityType`: The ActivityPub activity type (e.g., `"Create"`, `"Follow"`)
* `activityId`: The activity's ID URL
* `actorId`: The actor ID URL (sender of the activity)
* `activityJson`: The complete activity JSON
* `verified`: Whether the activity was verified (for inbound activities)
* `signatureDetails`: Detailed signature verification information
  (for inbound activities), containing:
  * `httpSignaturesVerified`: Whether HTTP Signatures were verified
  * `httpSignaturesKeyId` (optional): The key ID used for HTTP signature
    verification, if available
  * `httpSignaturesFailureReason` (optional): Why HTTP signature
    verification failed, if available
  * `httpSignaturesKeyFetchStatus` (optional): The HTTP status code from a
    failed key fetch, if available
  * `httpSignaturesKeyFetchError` (optional): The error type from a
    non-HTTP key fetch failure, if available
  * `ldSignaturesVerified`: Whether Linked Data Signatures were verified
* `timestamp`: ISO 8601 timestamp
* `inboxUrl`: The target inbox URL (for outbound activities)

### Configuration options

The `FedifySpanExporter` constructor accepts the following options:

`ttl`
:   The time-to-live for stored trace data.  If not specified, data will be
stored indefinitely (or until manually deleted).  This is useful for
automatically cleaning up old trace data:

```
~~~~ typescript twoslash
import { MemoryKvStore } from "@fedify/fedify";
import { FedifySpanExporter } from "@fedify/fedify/otel";
const kv = new MemoryKvStore();
// ---cut-before---
const exporter = new FedifySpanExporter(kv, {
  ttl: Temporal.Duration.from({ hours: 24 }),
});
~~~~
```

`keyPrefix`
:   The key prefix for storing trace data in the `KvStore`.  Defaults to
`["fedify", "traces"]`.  You can customize this to avoid conflicts with
other data in the same `KvStore`:

```
~~~~ typescript twoslash
import { MemoryKvStore } from "@fedify/fedify";
import { FedifySpanExporter } from "@fedify/fedify/otel";
const kv = new MemoryKvStore();
// ---cut-before---
const exporter = new FedifySpanExporter(kv, {
  keyPrefix: ["myapp", "otel", "traces"],
});
~~~~
```

### `KvStore` requirements

The `FedifySpanExporter` requires a [`KvStore`](./kv.md) that supports either
the `list()` method (preferred) or the `cas()` method:

* When `list()` is available, the exporter stores each activity record under
  its own unique key, enabling efficient prefix scans without concurrency
  issues.
* When only `cas()` is available, the exporter uses compare-and-swap
  operations to append records to a list, which works but may experience
  contention under high load.
* If neither method is available, the constructor throws an error.

The following `KvStore` implementations support the required operations:

* `MemoryKvStore` (supports both `list()` and `cas()`)
* `RedisKvStore` from *@fedify/redis* (supports both `list()` and `cas()`)
* `PostgresKvStore` from *@fedify/postgres* (supports `list()`)
* `SqliteKvStore` from *@fedify/sqlite* (supports `list()`)
* `DenoKvStore` from *@fedify/denokv* (supports both `list()` and `cas()`)
* `WorkersKvStore` from *@fedify/cfworkers* (supports `list()`)

---

---
url: /manual/pragmatics.md
description: >-
  This section explains the pragmatic aspects of using Fedify, such as how to
  utilize the vocabulary API and the de facto norms of ActivityPub
  implementations.
---

# Pragmatics

> \[!NOTE]
> This section is a work in progress.  Contributions are welcome.

While Fedify provides [vocabulary API](./vocab.md), it does not inherently
define how to utilize those vocabularies.  ActivityPub implementations like
[Mastodon] and [Misskey] already have de facto norms for how to use them,
which you should follow to get the desired results.

For example, you need to know which properties on a `Person` object should be
populated with which values to display an avatar or header image, which property
represents a date joined, and so on.

In this section, we will explain the pragmatic aspects of using Fedify, such as
how to utilize the vocabulary API and the de facto norms of ActivityPub
implementations.

[Mastodon]: https://joinmastodon.org/

[Misskey]: https://misskey-hub.net/

## Actors

The following five types of actors represent entities that can perform
activities in ActivityPub:

* `Application` describes a software application.
* `Group` represents a formal or informal collective of actors.
* `Organization` represents an organization.
* `Person` represents an individual person.
* `Service` represents a service of any kind.

The most common type of actor is `Person`, which represents an individual user.
When you register an [actor dispatcher], you should return an actor object of
an appropriate type of the account.

Those five types of actors have the same set of properties, e.g., `name`,
`preferredUsername`, `summary`, and `published`.

[actor dispatcher]: ./actor.md

### `Application`/`Service`: Automated/bot actors

If an actor is represented as an `Application` or `Service` object, it is
considered an automated actor by Mastodon and a bot actor by Misskey.

```typescript twoslash
import { Application } from "@fedify/vocab";
// ---cut-before---
new Application({  // [!code highlight]
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  // Other properties...
})
```

For example, the above actor object is displayed as an automated actor in
Mastodon like the following:

![Screenshot: An automated actor in Mastodon](/assets/mastodon-automated.BsaNJl0-.png)

### `Group`

If an actor is represented as a `Group` object, it is considered a group actor
by Mastodon.

```typescript twoslash
import { Group } from "@fedify/vocab";
// ---cut-before---
new Group({  // [!code highlight]
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  // Other properties...
})
```

For example, the above actor object is displayed as a group actor in Mastodon
like the following:

![Screenshot: A group actor in Mastodon](/assets/mastodon-group.Dfj-8V_i.png)

> \[!TIP]
> [Lemmy] communities and [Guppe] groups are also represented as `Group`
> objects.

[Lemmy]: https://join-lemmy.org/

[Guppe]: https://a.gup.pe/

### `name`: Display name

The `name` property is used as a display name in Mastodon and the most
ActivityPub implementations.  The display name is usually a full name or
a nickname of a person, or a title of a group or an organization.
It is displayed in the profile page of an actor and the timeline.

```typescript twoslash
import { Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",  // [!code highlight]
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with display name Fedify Demo in
Mastodon](/assets/mastodon-person.CguqStwl.png)

### `summary`: Bio

The `summary` property is used as a bio in Mastodon and the most ActivityPub
implementations.  The bio is displayed in the profile page of the actor.

> \[!NOTE]
> The `summary` property expects an HTML string, so you should escape HTML
> entities if it contains characters like `<`, `>`, and `&`.

```typescript twoslash
import { Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",  // [!code highlight]
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a bio in
Mastodon](/assets/mastodon-person.CguqStwl.png)

### `published`: Date joined

The `published` property is used as a date joined in Mastodon and Misskey.
The date joined is displayed in the profile page of the actor.

> \[!NOTE]
> Although the `published` property contains a date and time, it is displayed
> as a date only in Mastodon and Misskey.  However, there may be ActivityPub
> implementations that display the date and time.

```typescript twoslash
import { Person } from "@fedify/vocab";
import { Temporal } from "@js-temporal/polyfill";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  published: Temporal.Instant.from("2024-03-31T00:00:00Z"), // [!code highlight]
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a date joined in
Mastodon](/assets/mastodon-person.CguqStwl.png)

### `icon`: Avatar image

The `icon` property is used as an avatar image in Mastodon and the most
ActivityPub implementations.  The avatar image is displayed next to the name
of the actor in the profile page and the timeline.

```typescript{5-8} twoslash
import { Image, Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  icon: new Image({
    url: new URL("https://i.imgur.com/CUBXuVX.jpeg"),
    mediaType: "image/jpeg",
  }),
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a cat avatar image in
Mastodon](/assets/mastodon-avatar.LhnwTjgW.png)

### `image`: Header image

The `image` property is used as a header image in Mastodon and Misskey.
The header image is displayed on the top of the profile page.

```typescript{5-8} twoslash
import { Image, Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  image: new Image({
    url: new URL("https://i.imgur.com/yEZ0EEw.jpeg"),
    mediaType: "image/jpeg",
  }),
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a cat header image in
Mastodon](/assets/mastodon-header.Tx1ryfwX.png)

### `attachments`: Custom fields

The `attachments` property is used as custom fields in Mastodon and Misskey.
The custom fields are displayed as a table in the profile page.

```typescript{5-18} twoslash
import { Person, PropertyValue } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  attachments: [
    new PropertyValue({
      name: "Location",
      value: "Seoul, South Korea",
    }),
    new PropertyValue({
      name: "Pronoun",
      value: "they/them",
    }),
    new PropertyValue({
      name: "Website",
      value: '<a href="https://fedify.dev/">fedify.dev</a>'
    }),
  ],
  // Other properties...
})
```

> \[!NOTE]
> The `PropertyValue.value` property expects an HTML string, so you should
> escape HTML entities if it contains characters like `<`, `>`, and `&`.

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with custom fields in
Mastodon](/assets/mastodon-custom-fields.C3PtMsqk.png)

### `manuallyApprovesFollowers`: Lock account

The `manuallyApprovesFollowers` property is used to *indicate* that the actor
manually approves followers.  In Mastodon and Misskey, the actor is displayed as
a locked account if the `manuallyApprovesFollowers` property is `true`.

> \[!WARNING]
> The `manuallyApprovesFollowers` property only *indicates* that the actor
> manually approves followers.  The actual behavior of the actor is determined
> by the [inbox listener](./inbox.md) for `Follow` activities.
> If it automatically sends `Accept` activities right after receiving `Follow`,
> the actor behaves as an unlocked account.  If it sends `Accept` when the
> owner explicitly clicks the *Accept* button, the actor behaves as a locked
> account.

```typescript twoslash
import { Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  manuallyApprovesFollowers: true,  // [!code highlight]
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a lock icon next to the handle in
Mastodon](/assets/mastodon-lock.CQLe7TL5.png)

### `suspended`

The `suspended` property is used to suspend an actor in Mastodon.
If the `suspended` property is `true`, the profile page of the actor is
displayed as suspended.

```typescript twoslash
import { Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  suspended: true,  // [!code highlight]
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a suspended status in
Mastodon](/assets/mastodon-suspended.B9tSG2Ro.png)

### `memorial`

The `memorial` property is used to memorialize an actor in Mastodon.
If the `memorial` property is `true`, the profile page of the actor is
displayed as memorialized.

```typescript twoslash
import { Person } from "@fedify/vocab";
// ---cut-before---
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  memorial: true,  // [!code highlight]
  // Other properties...
})
```

For example, the above actor object is displayed like the following in Mastodon:

![Screenshot: An actor profile with a memorialized status in
Mastodon](/assets/mastodon-memorial.BeXxVg6w.png)

### `~Federatable.setFollowingDispatcher()`: Following collection

The `~Federatable.setFollowingDispatcher()` method registers a dispatcher for
the collection of actors that the actor follows.  The number of the collection
is displayed in the profile page of the actor.  Each item in the collection is
a URI of the actor that the actor follows, or an actor object itself.

```typescript twoslash
import type { Federation } from "@fedify/fedify";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setFollowingDispatcher(
    "/users/{identifier}/following", async (ctx, identifier, cursor) => {
      // Loads the list of actors that the actor follows...
      return {
        items: [
          new URL("..."),
          new URL("..."),
          // ...
        ]
      };
    }
  )
  .setCounter((ctx, identifier) => 123);
```

For example, the above following collection is displayed like the below
in Mastodon:

![Screenshot: An actor profile with 123 following in
Mastodon](/assets/mastodon-following.32UfxP7X.png)

> \[!NOTE]
> Mastodon does not display the following collection of a remote actor,
> but other ActivityPub implementations may display it.

### `~Federatable.setFollowersDispatcher()`: Followers collection

The `~Federatable.setFollowersDispatcher()` method registers a dispatcher for
the collection of actors that follow the actor.  The number of the collection
is displayed in the profile page of the actor.  Each item in the collection is
a `Recipient` or an `Actor` that follows the actor.

```typescript twoslash
import type { Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setFollowersDispatcher(
    "/users/{identifier}/followers", async (ctx, identifier, cursor) => {
      // Loads the list of actors that follow the actor...
      return {
        items: [
          {
            id: new URL("..."),
            inboxId: new URL("..."),
          } satisfies Recipient,
          // ...
        ]
      };
    }
  )
  .setCounter((ctx, identifier) => 456);
```

For example, the above followers collection is displayed like the below
in Mastodon:

![Screenshot: An actor profile with 456 followers in
Mastodon](/assets/mastodon-followers.DspHQzVp.png)

> \[!NOTE]
> Mastodon does not display the followers collection of a remote actor,
> but other ActivityPub implementations may display it.

---

---
url: /manual/relay.md
description: >-
  Fedify provides a ready-to-use relay server implementation for building
  ActivityPub relay infrastructure.
---

# Relay

*This API is available since Fedify 2.0.0.*

Fedify provides the *@fedify/relay* package for building
[ActivityPub relay servers]—services that forward activities between instances
without requiring individual actor-following relationships.

[ActivityPub relay servers]: https://fediverse.party/en/miscellaneous/#relays

## Setting up a relay server

First, install the *@fedify/relay* package.

::: code-group

```sh [Deno]
deno add @fedify/relay
```

```sh [npm]
npm add @fedify/relay @hono/node-server
```

```sh [pnpm]
pnpm add @fedify/relay @hono/node-server
```

```sh [Yarn]
yarn add @fedify/relay @hono/node-server
```

```sh [Bun]
bun add @fedify/relay
```

:::

Then create a relay using the `createRelay()` function.

::: code-group

```typescript twoslash [Deno]
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";

const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  name: "My ActivityPub Relay",
  subscriptionHandler: async (ctx, actor) => {
    // Approve all subscriptions
    return true;
  },
});

Deno.serve((request) => relay.fetch(request));
```

```typescript twoslash [Bun]
import "@types/bun";
// ---cut-before---
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";

const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  name: "My ActivityPub Relay",
  subscriptionHandler: async (ctx, actor) => {
    // Approve all subscriptions
    return true;
  },
});

Bun.serve({
  port: 8000,
  fetch(request) {
    return relay.fetch(request);
  },
});
```

```typescript twoslash [Node.js]
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
import { serve } from "@hono/node-server";

const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  name: "My ActivityPub Relay",
  subscriptionHandler: async (ctx, actor) => {
    // Approve all subscriptions
    return true;
  },
});

serve({
  port: 8000,
  fetch(request) {
    return relay.fetch(request);
  },
});
```

:::

> \[!WARNING]
> `MemoryKvStore` is for development only. For production, use a persistent
> store like `RedisKvStore` from *@fedify/redis*, `PostgresKvStore` from
> *@fedify/postgres*, `MysqlKvStore` from *@fedify/mysql*, or `DenoKvStore`
> from *@fedify/denokv*.
>
> See the [*Key–value store* section](./kv.md) for details.

## Configuration options

`kv` (required)
:   A [`KvStore`](./kv.md) for storing subscriber information and cryptographic
keys.

`origin` (required)
:   The origin URL where the relay is hosted (e.g., `"https://relay.example.com"`).

`name`
:   Display name for the relay actor. Defaults to `"ActivityPub Relay"`.

`queue`
:   A [`MessageQueue`](./mq.md) for background activity processing.  Recommended
for production:

```
~~~~ typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore, InProcessMessageQueue } from "@fedify/fedify";
// ---cut-before---
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  queue: new InProcessMessageQueue(),
  subscriptionHandler: async (ctx, actor) => true,
});
~~~~

> [!NOTE]
> For production, use [`RedisMessageQueue`], [`PostgresMessageQueue`],
> or [`MysqlMessageQueue`].
```

`subscriptionHandler` (required)
:   Callback to approve or reject subscription requests. See
[*Handling subscriptions*](#handling-subscriptions). To create an open relay
that accepts all subscriptions:

```
~~~~ typescript
subscriptionHandler: async (ctx, actor) => true
~~~~
```

`documentLoaderFactory`
:   A factory function for creating a document loader to fetch remote
ActivityPub objects. See [*Getting a `Federation`
object*](./federation.md#documentloaderfactory).

`authenticatedDocumentLoaderFactory`
:   A factory function for creating an authenticated document loader.
See
[`authenticatedDocumentLoaderFactory`](./federation.md#authenticateddocumentloaderfactory).

[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/mq/~/PostgresMessageQueue

[`MysqlMessageQueue`]: https://jsr.io/@fedify/mysql/doc/mq/~/MysqlMessageQueue

## Relay types

The first parameter to `createRelay()` specifies the relay protocol.
For detailed protocol specifications, see [FEP-ae0c].

| Feature                | `"mastodon"`                 | `"litepub"`                |
| ---------------------- | ---------------------------- | -------------------------- |
| Activity forwarding    | Direct                       | Wrapped in `Announce`      |
| Following relationship | One-way                      | Bidirectional              |
| Subscription state     | Immediate `"accepted"`       | `"pending"` → `"accepted"` |
| Compatibility          | Broad (most implementations) | LitePub-aware servers      |

> \[!TIP]
> Use `"mastodon"` for broader compatibility. Switch to `"litepub"` only if
> you need its specific features.

[FEP-ae0c]: https://w3id.org/fep/ae0c

### Mastodon-style relay

Activities are forwarded directly to subscribers. Instances follow the relay,
but the relay doesn't follow back.

```typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
// ---cut-before---
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,
});
```

Forwards `Create`, `Update`, `Delete`, `Move`, and `Announce` activities.

### LitePub-style relay

The relay server follows back instances that subscribe to it. Forwarded
activities are wrapped in `Announce` objects.

```typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
// ---cut-before---
const relay = createRelay("litepub", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,
});
```

## Subscribing to a relay

Instance administrators can subscribe to your relay by adding the relay URL
in their server settings.  The URL format differs depending on the relay type.

### Subscription URL

The subscription URL differs between Mastodon-style and LitePub-style relays:

| Relay type   | Subscription URL            | Example                           |
| ------------ | --------------------------- | --------------------------------- |
| `"mastodon"` | Inbox URL: `{origin}/inbox` | `https://relay.example.com/inbox` |
| `"litepub"`  | Actor URL: `{origin}/actor` | `https://relay.example.com/actor` |

For more details on the protocol differences, see [FEP-ae0c].

### Subscribing from Mastodon

To subscribe from a Mastodon instance:

1. Go to **Preferences** → **Administration** → **Relays**
2. Click **Add new relay**
3. Enter the relay inbox URL (e.g., `https://relay.example.com/inbox`)
4. Click **Save and enable**

The relay will receive a `Follow` activity from the instance.  If the
`subscriptionHandler` approves the request, the relay sends back an `Accept`
activity, and the instance becomes a subscriber.

> \[!NOTE]
> Mastodon only supports Mastodon-style relays.  Use the inbox URL
> (`https://{domain}/inbox`) when subscribing from Mastodon.

### Subscribing from Pleroma/Akkoma

Pleroma and Akkoma use LitePub-style relays by default.  To subscribe:

1. Use the admin CLI or MIX task to add the relay
2. Enter the relay actor URL (e.g., `https://relay.example.com/actor`)

### Subscribing from other software

Consult your server software's documentation for specific instructions.
The general process is:

1. Find the relay settings in your server's administration panel
2. Add the appropriate relay URL (inbox URL for Mastodon-style, actor URL
   for LitePub-style)
3. Wait for the subscription to be approved

## Handling subscriptions

The `subscriptionHandler` is required and determines whether to approve or
reject subscription requests. For an open relay that accepts all subscriptions:

```typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
// ---cut-before---
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,  // Accept all
});
```

To implement approval logic with blocklists:

```typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
// ---cut-before---
const blockedDomains = ["spam.example", "blocked.example"];

const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => {
    const domain = new URL(actor.id!).hostname;
    if (blockedDomains.includes(domain)) {
      return false;  // Reject
    }
    return true;  // Approve
  },
});
```

The handler receives:

* `ctx`: The `Context<RelayOptions>` object
* `actor`: The `Actor` requesting subscription

Return `true` to approve or `false` to reject.  Rejected requests receive a
`Reject` activity.

## Managing followers

The relay provides methods to query and manage followers through the `Relay`
interface.

### Listing all followers

Use `listFollowers()` to iterate over all followers:

```typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,
});
// ---cut-before---
for await (const follower of relay.listFollowers()) {
  console.log(`Follower: ${follower.actorId}`);
  console.log(`State: ${follower.state}`);
  console.log(`Actor name: ${follower.actor.name}`);
}
```

### Getting a specific follower

Use `getFollower()` to retrieve a specific follower by actor ID:

```typescript twoslash
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,
});
// ---cut-before---
const follower = await relay.getFollower(
  "https://mastodon.example.com/users/alice"
);
if (follower != null) {
  console.log(`State: ${follower.state}`);
  console.log(`Actor: ${follower.actor.preferredUsername}`);
}
```

### `RelayFollower` type

Each follower entry contains:

* `actorId`: The actor's ID (URL) as a string
* `actor`: The validated `Actor` object
* `state`: Either `"pending"` or `"accepted"`

> \[!NOTE]
> The `listFollowers()` method requires a `KvStore` implementation that
> supports listing by prefix (Redis, PostgreSQL, SQLite, Deno KV all support
> this).

## Storage requirements

### Follower data

Stored with keys `["follower", actorId]`.  Actor objects typically range from
1–10 KB.  For 1,000 subscribers, expect 1–10 MB of storage.

### Cryptographic keys

Two key pairs are generated and stored:

| Key                               | Purpose                                         |
| --------------------------------- | ----------------------------------------------- |
| `["keypair", "rsa", "relay"]`     | HTTP Signatures                                 |
| `["keypair", "ed25519", "relay"]` | Linked Data Signatures, Object Integrity Proofs |

> \[!NOTE]
> These keys are critical for the relay's identity.  Back up your `KvStore`
> regularly.

## Security considerations

### Signature verification

The relay automatically verifies incoming activities using:

* [HTTP Signatures]
* [Linked Data Signatures]
* [Object Integrity Proofs]

Invalid signatures are silently ignored.  Enable [logging](./log.md) for the
`["fedify", "sig"]` category to debug verification failures.

[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

[Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/

[Object Integrity Proofs]: https://w3id.org/fep/8b32

### Subscription abuse

Protect against abuse by:

1. Implementing a `subscriptionHandler` to validate requests
2. Maintaining a blocklist
3. Rate limiting at the infrastructure level
4. Monitoring activity volumes

### Content moderation

> \[!WARNING]
> Running a relay makes you responsible for forwarded content. Establish clear
> policies and vet subscribing instances.

### Privacy

The relay has access to all activities that pass through it. Do not store or
log activity content beyond operational needs.

> \[!CAUTION]
> Never forward non-public activities. The relay is designed only for public
> content distribution.

## Monitoring

### Logging

Enable relay-specific logging:

```typescript twoslash
import { configure, getConsoleSink } from "@logtape/logtape";

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: ["fedify"], lowestLevel: "info", sinks: ["console"] },
  ],
});
```

Key log categories:

| Category                             | Description            |
| ------------------------------------ | ---------------------- |
| `["fedify", "federation", "inbox"]`  | Incoming activities    |
| `["fedify", "federation", "outbox"]` | Outgoing activities    |
| `["fedify", "sig"]`                  | Signature verification |

### OpenTelemetry

The relay supports [OpenTelemetry](./opentelemetry.md) tracing. Key spans:

| Span                                  | Description             |
| ------------------------------------- | ----------------------- |
| `activitypub.inbox`                   | Receiving activities    |
| `activitypub.send_activity`           | Forwarding activities   |
| `activitypub.dispatch_inbox_listener` | Processing inbox events |

---

---
url: /manual/send.md
description: >-
  Fedify provides a way to send activities to other actors' inboxes. This
  section explains how to send activities to others.
---

# Sending activities

In ActivityPub, an actor can deliver an activity to another actor by
[sending an HTTP `POST` request to the recipient's inbox][1].  Fedify provides
an abstracted way to send activities to other actors' inboxes.

[1]: https://www.w3.org/TR/activitypub/#delivery

## Prerequisite: actor key pairs

Before sending an activity to another actor, you need to have the sender's
key pairs.  The key pairs are used to sign the activity so that the recipient
can verify the sender's identity.  The key pairs can be registered by calling
`~ActorCallbackSetters.setKeyPairsDispatcher()` method.

For more information about this topic, see [*Public keys of an `Actor`*
section](./actor.md#public-keys-of-an-actor) in the *Actor dispatcher* section.

## Sending an activity

To send an activity to another actor, you can use the `Context.sendActivity()`
method.  The following shows how to send a `Follow` activity to another actor:

```typescript{8-15} twoslash
import { type Context } from "@fedify/fedify";
import { Follow, type Recipient } from "@fedify/vocab";

async function sendFollow(
  ctx: Context<void>,
  senderId: string,
  recipient: Recipient,
) {
  await ctx.sendActivity(
    { identifier: senderId },
    recipient,
    new Follow({
      id: new URL(`https://example.com/${senderId}/follows/${recipient.id}`),
      actor: ctx.getActorUri(senderId),
      object: recipient.id,
    }),
  );
}
```

> \[!TIP]
> Wonder where you can acquire a `Context` object?  See the [*Where to get a
> `Context` object* section](./context.md#where-to-get-a-context-object) in
> the *Context* section.

## Specifying a sender

The first argument of the `Context.sendActivity()` method is the sender
of the activity.  It can be three types of values:

### `{ identifier: string }`

If you specify an object with the `identifier` property, the sender is
the actor with the given identifier.  The identifier is used to find the
actor's key pairs to sign the activity:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
// ---cut-before---
await ctx.sendActivity(
  { identifier: "2bd304f9-36b3-44f0-bf0b-29124aafcbb4" },  // [!code highlight]
  "followers",
  activity,
);
```

### `{ username: string }`

If you specify an object with the `username` property, the sender is
the actor with the given WebFinger username.  The username is used to find
the actor's key pairs to sign the activity:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
// ---cut-before---
await ctx.sendActivity(
  { username: "john" },  // [!code highlight]
  "followers",
  activity,
);
```

If you don't [decouple the username from the
identifier](./actor.md#decoupling-actor-uris-from-webfinger-usernames),
this is the same as the `{ identifier: string }` case.

### `SenderKeyPair | SenderKeyPair[]`

If you specify a `SenderKeyPair` object or an array of `SenderKeyPair` objects,
the sender is the set of the given key pairs:

```typescript twoslash
import { type Context, SenderKeyPair } from "@fedify/fedify";
import { Activity, type Actor } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
const recipients: Actor[] = [];
// ---cut-before---
await ctx.sendActivity(
  await ctx.getActorKeyPairs("2bd304f9-36b3-44f0-bf0b-29124aafcbb4"),  // [!code highlight]
  recipients,  // You need to specify the recipients manually
  activity,
);
```

However, you probably don't want to use this option directly; instead,
you should use above two options to specify the sender.

## Specifying recipients

The second argument of the `Context.sendActivity()` method is the recipients
of the activity.  It can be multiple, and you can set them to `Recipient`
objects, or `Actor` objects (which satisfy the `Recipient` interface), or
simply `"followers"` string which is a special value that represents the
followers of the sender.

### `Actor | Actor[]`

If you specify `Actor` objects, the activity is delivered to the actors'
inboxes (or shared inboxes if some actors support it and you turn on
the `preferSharedInbox` option):

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity, type Actor } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
const actor = {} as Actor;
// ---cut-before---
await ctx.sendActivity(
  { identifier: "2bd304f9-36b3-44f0-bf0b-29124aafcbb4" },
  actor,  // [!code highlight]
  activity,
);
```

Or you can specify multiple actors:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity, type Actor } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
const actor = {} as Actor;
const actor2 = {} as Actor;
const actor3 = {} as Actor;
// ---cut-before---
await ctx.sendActivity(
  { username: "john" },
  [actor, actor2, actor3],  // [!code highlight]
  activity,
);
```

### `Recipient | Recipient[]`

If you specify any objects that satisfy the `Recipient` interface, the activity
is delivered to the recipients' inboxes (or shared inboxes if some recipients
support it and you turn on the `preferSharedInbox` option).

The `Recipient` interface is defined as follows:

```typescript twoslash
export interface Recipient {
  readonly id: URL | null;
  readonly inboxId: URL | null;
  readonly endpoints?: {
    sharedInbox: URL | null;
  } | null;
}
```

Here's an example of specifying a `Recipient` object:

```typescript{3-6} twoslash
import { type Context } from "@fedify/fedify";
import { Activity, Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
// ---cut-before---
await ctx.sendActivity(
  { identifier: "2bd304f9-36b3-44f0-bf0b-29124aafcbb4" },
  {
    id: new URL("https://example.com/actors/1"),
    inboxId: new URL("https://example.com/actors/1/inbox"),
  } satisfies Recipient,
  activity,
);
```

Or you can provide its shared inbox endpoint as well:

```typescript{6-8} twoslash
import { type Context } from "@fedify/fedify";
import { Activity, Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
// ---cut-before---
await ctx.sendActivity(
  { username: "john" },
  {
    id: new URL("https://example.com/actors/1"),
    inboxId: new URL("https://example.com/actors/1/inbox"),
    endpoints: {
      sharedInbox: new URL("https://example.com/inbox"),
    }
  } satisfies Recipient,
  activity,
  { preferSharedInbox: true },  // [!code highlight]
);
```

### `"followers"`

> \[!NOTE]
> You need to implement the [followers collection
> dispatcher](./collections.md#followers) to use this feature.

It's the most convenient way to deliver an activity to the followers of the
sender.

If you specify the `"followers"` string, the activity is delivered to the
followers of the sender.  It is a special value that represents the followers
of the sender:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = new Activity({});
// ---cut-before---
await ctx.sendActivity(
  { identifier: "2bd304f9-36b3-44f0-bf0b-29124aafcbb4" },
  "followers",  // [!code highlight]
  activity,
);
```

> \[!NOTE]
> You cannot use the `"followers"` string if the sender is a `SenderKeyPair` or
> an array of `SenderKeyPair` objects.  You need to specify the recipients
> manually in this case.

> \[!TIP]
> Does the `Context.sendActivity()` method take quite a long time to complete
> even if you configured the [`queue`](./federation.md#queue)?  It might be
> because the followers collection is large and the method under the hood
> invokes your [followers collection dispatcher](./collections.md#followers)
> multiple times to paginate the collection.  To improve the performance,
> you should implement the [one-short followers collection for gathering
> recipients](./collections.md#one-shot-followers-collection-for-gathering-recipients).

## Specifying an activity

The third argument of the `Context.sendActivity()` method is the activity
to send.  It can be an instance of any subclass of the `Activity` class, such
as `Follow`, `Create`, `Like`, and so on.

Every activity must have the `actor` property, which corresponds to the sender
of the activity.  [You can get the actor's URI by calling
the `Context.getActorUri()` method.](./actor.md#constructing-actor-uris)

Every activity should have the `id` property, which is a unique IRI for the
activity.  If you don't specify the `id` property, [Fedify automatically
generates a unique IRI for the activity by default](#autoidassigner)—but it is
recommended to specify the `id` property explicitly.

> \[!TIP]
> The activity's `id` does not have to be necessarily dereferenceable—it's
> totally fine to use a URL with a fragment identifier, such as
> `https://example.com/123#follow/751d477f-2167-4473-ace5-4404f4760c0d`.

> \[!CAUTION]
> Sometimes you may tempted to derive the activity's `id` from the actor and
> the object's `id` properties, but keep in mind that the same kind of
> activities can be made by the same actor to the same object multiple times.
>
> For example, if Alice sends a `Follow` activity to Bob, Bob accepts it,
> Alice sends an `Undo(Follow)` activity to Bob, and Alice sends a `Follow`
> activity to Bob again, the `id` of the `Follow` activity should be different
> from the previous one, even if the `actor` and the `object` are the same.
>
> If they have the same `id`, the recipient may mistakenly think that the
> activity is a duplicate of the previous one and ignore it, which is not
> what you want.
>
> To ensure the uniqueness of the activity's `id`, it is recommended to contain
> a UUID or a similar unique identifier in the `id` property.

The most of cases, an activity should have the `to` property, which corresponds
to the recipient of the activity.  If it's a public activity, you can set
the `to` property to the `PUBLIC_COLLECTION` constant, which represents
the public addressing.  There's also the `cc` property, which corresponds to
the secondary recipients of the activity.  Those two properties can be multiple,
and you can set them to `Actor` objects, `Collection` objects, or `URL` objects.

> \[!TIP]
> If you want to mimic the behavior of Mastodon's post privacy settings,
> here's a table that shows how to set the `to` and `cc` properties:
>
> | Privacy setting  | `to` property               | `cc` property               |
> | ---------------- | --------------------------- | --------------------------- |
> | Public           | `PUBLIC_COLLECTION`         | `Context.getFollowersUri()` |
> | Quiet public\[^1] | `Context.getFollowersUri()` | `PUBLIC_COLLECTION`         |
> | Followers-only   | `Context.getFollowersUri()` | Mentioned actors            |
> | Direct message   | Mentioned actors            |                             |

To wrap up, the following is an example of sending a `Create` activity:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { type Actor, Create, Note, PUBLIC_COLLECTION } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const senderId: string = "";
const noteId: string = "";
const content: string = "";
const recipients: Actor[] = [];
// ---cut-before---
await ctx.sendActivity(
  { identifier: senderId },
  recipients,
  new Create({
    id: new URL(`#create`, ctx.getObjectUri(Note, { id: noteId })),
    actor: ctx.getActorUri(senderId),
    object: new Note({
      id: ctx.getObjectUri(Note, { id: noteId }),
      attribution: ctx.getActorUri(senderId),
      to: PUBLIC_COLLECTION,
      cc: ctx.getFollowersUri(senderId),
      content,
    }),
  }),
);
```

\[^1]: Previously known as Unlisted in Mastodon—renamed to Quiet
public in Mastodon 4.3.0. It's a public post that doesn't appear in
the public timeline and the hashtag pages.

## Enqueuing an outgoing activity

The delivery failure can happen for various reasons, such as network failure,
recipient server failure, and so on.  For reliable delivery, Fedify enqueues
an outgoing activity to the queue instead of immediately sending it to
the recipient's inbox if possible; the system retries the delivery on failure.

This queueing mechanism is enabled only if a [`queue`](./federation.md#queue)
option is set to the `createFederation()` function:

```typescript twoslash
// @noErrors: 2345
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
  queue: new InProcessMessageQueue(),  // [!code highlight]
});
```

> \[!NOTE]
> The `InProcessMessageQueue` is a simple in-memory message queue that is
> suitable for development and testing.  For production use, you should
> consider using a more robust message queue, such as [`DenoKvMessageQueue`]
> from [`@fedify/denokv`] package, [`RedisMessageQueue`] from
> [`@fedify/redis`] package, or [`MysqlMessageQueue`] from
> [`@fedify/mysql`] package.
>
> For further information, see the [*Message queue* section](./mq.md).

The failed activities are automatically retried after a certain period of time.
By default, Fedify handles retries using exponential backoff with a maximum of
10 retries, but you can customize it by providing
an [`outboxRetryPolicy`](./federation.md#outboxretrypolicy) option to
the `createFederation()` function.

However, if your message queue backend provides native retry mechanisms
(indicated by `MessageQueue.nativeRetrial` being `true`), Fedify will skip
its own retry logic and rely on the backend to handle retries.  This avoids
duplicate retry mechanisms and leverages the backend's optimized retry features.

If the `queue` is not set, the `~Context.sendActivity()` method immediately
sends the activity to the recipient's inbox.  If the delivery fails, it throws
an error and does not retry the delivery.

[`DenoKvMessageQueue`]: https://jsr.io/@fedify/denokv/doc/mq/~/DenoKvMessageQueue

[`@fedify/denokv`]: https://github.com/fedify-dev/fedify/tree/main/packages/denokv

[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

[`@fedify/redis`]: https://github.com/fedify-dev/fedify/tree/main/packages/redis

[`MysqlMessageQueue`]: https://jsr.io/@fedify/mysql/doc/mq/~/MysqlMessageQueue

[`@fedify/mysql`]: https://github.com/fedify-dev/fedify/tree/main/packages/mysql

## Optimizing activity delivery for large audiences

*This API is available since Fedify 1.5.0.*

When sending activities to many recipients (such as when a user with thousands
of followers creates a post), the delivery process can become
performance-intensive.  Fedify optimizes this scenario by using a fan-out
mechanism that improves response times and resource utilization.

### How fan-out works

By default, when the number of recipients exceeds a threshold, Fedify uses
a two-stage delivery process:

1. First, it creates a single consolidated message containing the activity
   payload and all recipient inboxes
2. Then, a background worker processes this message and re-enqueues individual
   delivery tasks

This approach has several benefits:

* The `Context.sendActivity()` method returns more quickly
* Memory consumption is reduced by avoiding payload duplication
* The user interface remains responsive during large-scale deliveries
* Each delivery still maintains independent retry logic

### Customizing fan-out behavior

You can control this behavior using the `fanout` option in
the `~Context.sendActivity()` method:

```typescript twoslash
import type { Context } from "@fedify/fedify";
import type { Activity, Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = {} as Activity;
const recipients: Recipient[] = [];
// ---cut-before---
await ctx.sendActivity(
  { identifier: "alice" },  // sender
  recipients,               // recipients
  activity,                 // activity to send
  { fanout: "auto" }        // fan-out strategy  // [!code highlight]
);
```

The `fanout` option accepts the following values:

`"auto"` (default)
:   Automatically chooses the optimal strategy based on recipient count

`"skip"`
:   Always enqueues individual messages, bypassing the fan-out queue
(use when payload needs to vary per recipient)

`"force"`
:   Always uses the fan-out queue regardless of recipient count

> \[!NOTE]
> The `fanout` option is ignored when `immediate: true` is specified,
> as immediate delivery bypasses all queuing mechanisms.

### When to use each option

Use the default `"auto"` for most cases:

```typescript twoslash
import type { Context } from "@fedify/fedify";
import type { Activity, Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = {} as Activity;
const recipients: Recipient[] = [];
// ---cut-before---
await ctx.sendActivity({ identifier: "alice" }, recipients, activity);
```

Use `"skip"` when you need different content for each recipient:

```typescript twoslash
import type { Context } from "@fedify/fedify";
import type { Activity, Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = {} as Activity;
const recipients: Recipient[] = [];
// ---cut-before---
await ctx.sendActivity(
  { identifier: "alice" },
  recipients,
  activity,
  { fanout: "skip" }  // [!code highlight]
);
```

Use `"force"` to ensure fan-out behavior even with few recipients (rarely
needed):

```typescript twoslash
import type { Context } from "@fedify/fedify";
import type { Activity, Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const activity = {} as Activity;
const recipients: Recipient[] = [];
// ---cut-before---
await ctx.sendActivity(
  { identifier: "alice" },
  recipients,
  activity,
  { fanout: "force" }  // [!code highlight]
);
```

## Ensuring ordered delivery

*This API is available since Fedify 2.0.0.*

When sending multiple related activities for the same object
(e.g., `Create(Note)` followed by `Delete(Note)` for the same `Note`),
it's important that they arrive at recipient servers in the correct order.
Without ordering guarantees, a `Delete(Note)` activity might arrive before
the `Create(Note)` activity, causing the recipient to ignore the deletion and
leaving a “zombie post” that should have been deleted.

To ensure ordered delivery, you can use the `~SendActivityOptions.orderingKey`
option in the `~Context.sendActivity()` method:

```typescript twoslash
import type { Context } from "@fedify/fedify";
import { Create, Delete, Note, type Recipient } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const recipients: Recipient[] = [];
const noteId = new URL("https://example.com/notes/123");
// ---cut-before---
// Create activity
await ctx.sendActivity(
  { identifier: "alice" },
  recipients,
  new Create({
    id: new URL("#create", noteId),
    actor: ctx.getActorUri("alice"),
    object: new Note({ id: noteId }),
  }),
  { orderingKey: noteId.href },  // [!code highlight]
);

// Delete activity - guaranteed to arrive after Create
await ctx.sendActivity(
  { identifier: "alice" },
  recipients,
  new Delete({
    id: new URL("#delete", noteId),
    actor: ctx.getActorUri("alice"),
    object: noteId,
  }),
  { orderingKey: noteId.href },  // [!code highlight]
);
```

Activities with the same `~SendActivityOptions.orderingKey` are guaranteed to be
delivered in the order they were enqueued, per recipient server.  Activities
with different `~SendActivityOptions.orderingKey` values (or no
`~SendActivityOptions.orderingKey`) can be delivered in parallel for maximum
throughput.

### When to use `~SendActivityOptions.orderingKey`

Use `~SendActivityOptions.orderingKey` when you have activities that must be
processed in a specific order:

* `Create(Note)` → `Update(Note)` → `Delete(Note)` for the same object
* `Follow(Person)` → `Undo(Follow(Person))` for the same target
* Any sequence where later activities depend on earlier ones

Don't use `~SendActivityOptions.orderingKey` for unrelated activities,
as it unnecessarily reduces parallelism.

### How it works

When you specify an `~SendActivityOptions.orderingKey`:

1. During fan-out, the key is passed as-is to the fanout queue
2. When individual delivery tasks are created, the key is transformed to
   `${orderingKey}\n${recipientServerOrigin}` to ensure ordering is maintained
   per-recipient-server while allowing parallel delivery to different servers

This means Server A can receive a `Delete(Note)` immediately after its
`Create(Note)` completes, without waiting for Server Z's `Create(Note)` to
finish.

## Immediately sending an activity

Sometimes you may want to send an activity immediately without queueing it.
You can do this by calling the `~Context.sendActivity()` method with the
`immediate` option:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Follow, type Recipient } from "@fedify/vocab";

async function sendFollow(
  ctx: Context<void>,
  senderId: string,
  recipient: Recipient,
) {
  await ctx.sendActivity(
    { identifier: senderId },
    recipient,
    new Follow({
      actor: ctx.getActorUri(senderId),
      object: recipient.id,
    }),
    { immediate: true },  // [!code highlight]
  );
}
```

## Shared inbox delivery

The [shared inbox delivery] is an efficient way to deliver an activity to
multiple recipients belonging to the same server at once.  It is useful
for broadcasting activities, such as a public post.

By default, `~Context.sendActivity()` method delivers an activity to the
recipient's personal inbox.  To deliver an activity to the shared inbox,
you can pass the `preferSharedInbox` option:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Create, Note, type Recipient, PUBLIC_COLLECTION } from "@fedify/vocab";

async function sendNote(
  ctx: Context<void>,
  senderId: string,
  recipient: Recipient,
) {
  await ctx.sendActivity(
    { identifier: senderId },
    recipient,
    new Create({
      actor: ctx.getActorUri(senderId),
      to: PUBLIC_COLLECTION,
      object: new Note({
        attribution: ctx.getActorUri(senderId),
        to: PUBLIC_COLLECTION,
      }),
    }),
    { preferSharedInbox: true },  // [!code highlight]
  );
}
```

> \[!TIP]
> `PUBLIC_COLLECTION` constant contains a `URL` object of
> <https://www.w3.org/ns/activitystreams#Public>, a special IRI that
> represents the public audience.  By setting the `to` property to this IRI,
> the activity is visible to everyone.  See also the
> [*Public Addressing* section] in the ActivityPub specification.

> \[!NOTE]
> To deliver an activity to the shared inbox, the recipient server must support
> the shared inbox delivery.  Otherwise, Fedify silently falls back to
> the personal inbox delivery.

[shared inbox delivery]: https://www.w3.org/TR/activitypub/#shared-inbox-delivery

[*Public Addressing* section]: https://www.w3.org/TR/activitypub/#public-addressing

## Followers collection synchronization

*This API is available since Fedify 0.8.0, and it is optional since
Fedify 1.5.0.*

> \[!NOTE]
> For efficiency, you should implement
> [filtering-by-server](./collections.md#filtering-by-server) of
> the followers collection, otherwise the synchronization may be slow.

If an activity needs to be delivered to only followers of the sender through
the shared inbox, the server of the recipients has to be aware of the list of
followers residing on the server.  However, synchronizing the followers
collection every time an activity is sent is inefficient. To solve this problem,
Mastodon, etc., use a mechanism called
[followers collection synchronization][FEP-8fcf].

The idea is to send a digest of the followers collection with the activity
so that the recipient server can check if it needs to resynchronize
the followers collection.  Fedify provides a way to include the digest
of the followers collection in the activity delivery request by specifying
the recipients parameter of the `~Context.sendActivity()` method as
the `"followers"` string and turning on
the `~SendActivityOptionsForCollection.syncCollection` option:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Create, Note } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const senderId : string = "";
// ---cut-before---
await ctx.sendActivity(
  { identifier: senderId },
  "followers",  // [!code highlight]
  new Create({
    actor: ctx.getActorUri(senderId),
    to: ctx.getFollowersUri(senderId),
    object: new Note({
      attribution: ctx.getActorUri(senderId),
      to: ctx.getFollowersUri(senderId),
    }),
  }),
  {
    preferSharedInbox: true,  // [!code highlight]
    syncCollection: true,  // [!code highlight]
  },
);
```

The `~SendActivityOptionsForCollection.syncCollection` option is only available
when you specify the `"followers"` string as the recipients parameter.  With
turning on this option, it automatically sends the activity to the sender's
followers and includes the digest of the followers collection in the payload.

> \[!NOTE]
> The `to` and `cc` properties of an `Activity` and its `object` should be set
> to the followers collection IRI to ensure that the activity is visible to
> the followers.  If you set the `to` and `cc` properties to
> the `PUBLIC_COLLECTION`, the activity is visible to everyone regardless of
> the recipients parameter.

> \[!NOTE]
> Some history of this feature: The followers collection synchronization was
> first introduced in Fedify 0.8.0, but it was automatically turned on when
> the recipients parameter was set to the `"followers"` string then.
> Since Fedify 1.5.0, it is optional, and you need to explicitly turn on
> the `~SendActivityOptionsForCollection.syncCollection` option to use it.

[FEP-8fcf]: https://w3id.org/fep/8fcf

## Excluding same-server recipients

*This API is available since Fedify 0.9.0.*

Usually, you don't want to send messages through ActivityPub to followers on
the same server because they share the same database, so there's no need to.

For example, if *@foo@example.com* creates a post, it's already stored in
the database at *example.com*, so there's no need to send a `Create(Note)`
activity to *@bar@example.com*, because *@bar@example.com* already has access
to the post in the database.

To exclude same-server recipients, you can pass the `excludeBaseUris` option
to the `~Context.sendActivity()` method:

```typescript twoslash
import { type Context } from "@fedify/fedify";
import { Activity } from "@fedify/vocab";
const ctx = null as unknown as Context<void>;
const senderId: string = "";
const activity = new Activity({});
// ---cut-before---
await ctx.sendActivity(
  { identifier: senderId },
  "followers",
  activity,
  { excludeBaseUris: [ctx.getInboxUri()] },  // [!code highlight]
);
```

Excluded recipients do not receive the activity, even if they are included in
the recipients parameter.

> \[!NOTE]
> Only the `origin` parts of the specified URIs are compared with the
> inbox URLs of the recipients.  Even if they have `pathname` or `search` parts,
> they are ignored when comparing the URIs.

## Error handling

*This API is available since Fedify 0.6.0.*

Since an outgoing activity is not immediately processed, but enqueued to the
queue, the `~Context.sendActivity()` method does not throw an error even if
the delivery fails.  Instead, the delivery failure is reported to the queue
and retried later.

If you want to handle the delivery failure, you can register an error handler
to the queue:

```typescript{6-9} twoslash
// @noErrors: 2345
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
  queue: new InProcessMessageQueue(),
  onOutboxError: (error, activity) => {
    console.error("Failed to deliver an activity:", error);
    console.error("Activity:", activity);
  },
});
```

> \[!NOTE]
> The `onOutboxError` callback can be called multiple times for the same
> activity, because the delivery is retried according to the backoff schedule
> until it succeeds or reaches the maximum retry count.

### Permanent delivery failure handling

*This API is available since Fedify 2.0.0.*

When a remote inbox returns an HTTP status code that indicates a permanent
failure (such as `410 Gone` or `404 Not Found`), there is no point in retrying
the delivery.  Fedify automatically skips retries for permanent failures and
allows you to handle them by registering a permanent failure handler:

```typescript twoslash
// @noErrors: 2304 2345
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
  queue: new InProcessMessageQueue(),
});

federation.setOutboxPermanentFailureHandler(async (ctx, values) => {
  console.warn(
    `Inbox ${values.inbox.href} permanently failed ` +
    `with status ${values.statusCode}`
  );
  // Remove followers associated with this inbox:
  for (const actorId of values.actorIds) {
    await removeFollower(actorId);
  }
});
```

The handler receives the following information:

`values.inbox`
:   The inbox URL that returned the permanent failure.

`values.activity`
:   The `Activity` object that failed to deliver.

`values.error`
:   The `SendActivityError` that was thrown.

`values.statusCode`
:   The HTTP status code returned by the inbox (e.g., `404` or `410`).

`values.actorIds`
:   The actor IDs that were supposed to receive the activity at this inbox.
When `preferSharedInbox: true` is used, a single inbox URL may represent
multiple followers.

By default, the following HTTP status codes are treated as permanent failures:

* `404 Not Found` — the inbox no longer exists
* `410 Gone` — the inbox is explicitly marked as gone

You can customize which status codes are treated as permanent failures using
the `permanentFailureStatusCodes` option in `FederationOptions`:

```typescript twoslash
// @noErrors: 2345
import { createFederation, InProcessMessageQueue } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
  queue: new InProcessMessageQueue(),
  permanentFailureStatusCodes: [404, 410, 451],
});
```

See also the
[`permanentFailureStatusCodes`](./federation.md#permanentfailurestatuscodes)
option in the *Federation* section for more details.

> \[!NOTE]
> The permanent failure handler is called only once for each permanent
> failure, and delivery is not retried afterwards.  This is different from
> `onOutboxError`, which can be called multiple times due to retries.
>
> Even if no handler is registered, permanent failures will still skip retries.

> \[!TIP]
> If any errors are thrown in the permanent failure handler, they are caught,
> logged, and ignored, similar to `onOutboxError`.

## HTTP Signatures

Draft cavage [HTTP Signatures] is a de facto standard for signing ActivityPub
activities.  Although it is not a finalized specification, it is still widely
used in the fediverse to verify the sender's identity and the integrity of
the activity.

Fedify automatically signs activities with the sender's private key if
the [actor keys dispatcher is set](./actor.md#public-keys-of-an-actor) and
the actor has any RSA-PKCS#1-v1.5 key pair.  If there are multiple key pairs,
Fedify selects the first RSA-PKCS#1-v1.5 key pair among them.

[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

## HTTP Message Signatures

*This API is available since Fedify 1.6.0.*

[RFC 9421], also known as *HTTP Message Signatures*, is the final revision of
the HTTP Signatures specification.  Although it is the official standard,
it is not widely used in the fediverse yet.  As of May 2025, major ActivityPub
implementations, such as Mastodon, et al., still rely on the draft cavage
version of HTTP Signatures for signing portable activities.

Fedify automatically signs activities with the sender's private key if
the [actor keys dispatcher is set](./actor.md#public-keys-of-an-actor) and
the actor has any RSA-PKCS#1-v1.5 key pair.  If there are multiple key pairs,
Fedify selects the first RSA-PKCS#1-v1.5 key pair among them.

> \[!NOTE]
> Although HTTP Message Signatures support other than RSA-PKCS#1-v1.5,
> Fedify currently supports only RSA-PKCS#1-v1.5 key pairs for generating
> HTTP Message Signatures.  This limitation will be lifted in the future
> releases.

[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421

## Double-knocking HTTP Signatures

*This API is available since Fedify 1.6.0.*

As you read above, there are two revisions of HTTP Signatures:
the [draft cavage][HTTP Signatures] version and the [RFC 9421] version.
The draft cavage version is declared as obsolete, but it is still widely used
in the fediverse, and many ActivityPub implementations still rely on it.
On the other hand, the RFC 9421 version is the official standard, but
it is not widely used yet.

To support both versions of HTTP Signatures, Fedify uses the [double-knocking]
mechanism: trying one version, then falling back to another if rejected.
If it's the first encounter with the recipient server, Fedify tries
the RFC 9421 version first, and if it fails, it falls back to the draft
cavage version.  If the recipient server accepts the RFC 9421 version,
Fedify remembers it and uses the RFC 9421 version for the next time.
If the recipient server rejects the RFC 9421 version, Fedify falls back
to the draft cavage version and remembers it for the next time.

[double-knocking]: https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions

### `Accept-Signature` negotiation

*This API is available since Fedify 2.1.0.*

In addition to double-knocking, Fedify supports the [`Accept-Signature`]
challenge-response negotiation defined in [RFC 9421 §5].  When a recipient
server responds with a `401` status and includes an `Accept-Signature` header,
Fedify automatically parses the challenge, validates it, and retries the
request with the requested signature parameters (e.g., specific covered
components, a nonce, or a tag).

Safety constraints prevent abuse:

* The requested algorithm (`alg`) must match the local private key's
  algorithm; otherwise the challenge entry is skipped.
* The requested key identifier (`keyid`) must match the local key; otherwise
  the challenge entry is skipped.
* Fedify's minimum covered component set (`@method`, `@target-uri`,
  `@authority`) is always included, even if the challenge does not request
  them.

If the challenge cannot be fulfilled (e.g., incompatible algorithm),
Fedify falls through to the existing double-knocking spec-swap fallback.
At most three signed request attempts are made to the final URL per delivery
attempt (redirects may add extra HTTP requests):

1. Initial signed request
2. Challenge-driven retry (if `Accept-Signature` is present)
3. Legacy spec-swap retry (if the challenge retry also fails)

[`Accept-Signature`]: https://www.rfc-editor.org/rfc/rfc9421#section-5.1

[RFC 9421 §5]: https://www.rfc-editor.org/rfc/rfc9421#section-5

## Linked Data Signatures

*This API is available since Fedify 1.0.0.*

[Linked Data Signatures] is a more advanced and widely used, but *obsolete*,
mechanism for signing portable ActivityPub activities.  As of November 2024,
major ActivityPub implementations, such as Mastodon, et al., still rely on
Linked Data Signatures for signing portable activities, despite they declare
that Linked Data Signatures is outdated.

It shares the similar concept with [HTTP Signatures](#http-signatures),
but unlike HTTP Signatures, it can be used for signing portable activities.
For example, it can be used for [forwarding from inbox] and several other
cases that HTTP Signatures cannot handle.

Fedify automatically includes the Linked Data Signature of activities by
signing them with the sender's private key if the [actor keys dispatcher is
set](./actor.md#public-keys-of-an-actor) and the actor has any RSA-PKCS#1-v1.5
key pair.  If there are multiple key pairs, Fedify uses the first
RSA-PKCS#1-v1.5 key pair among them.

> \[!TIP]
> The combination of HTTP Signatures and Linked Data Signatures is the most
> widely supported way to sign activities in the fediverse, as of September
> 2024\.  Despite Linked Data Signatures is outdated and not recommended for
> new implementations, it is still widely used in the fediverse due to Mastodon
> and other major implementations' reliance on it.
>
> However, for new implementations, you should consider using *both* [Object
> Integrity Proofs](#object-integrity-proofs) and Linked Data Signatures
> for maximum compatibility and future-proofing.  Fortunately, Fedify supports
> both Object Integrity Proofs and Linked Data Signatures simultaneously,
> in addition to HTTP Signatures.

> \[!NOTE]
> If an activity is signed with both HTTP Signatures and Linked Data Signatures,
> the recipient verifies the Linked Data Signatures first when it is supported,
> and ignores the HTTP Signatures if the Linked Data Signatures are valid.
> If the recipient does not support Linked Data Signatures, it falls back to
> verifying the HTTP Signatures.

[Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/

[forwarding from inbox]: https://www.w3.org/TR/activitypub/#inbox-forwarding

## Object Integrity Proofs

*This API is available since Fedify 0.10.0.*

[Object Integrity Proofs][FEP-8b32] is a mechanism to ensure the integrity
of ActivityPub objects (not only activities!) in the fediverse.  It shares
the similar concept with [Linked Data Signatures](#linked-data-signatures),
but it has more functionalities and is more flexible.  However, as it is
relatively new, it is not widely supported yet.

Fedify automatically includes the integrity proof of activities by signing
them with the sender's private key if the [actor keys dispatcher is
set](./actor.md#public-keys-of-an-actor) and the actor has any Ed25519 key pair.
If there are multiple key pairs, Fedify creates the number of integrity proofs
equal to the number of Ed25519 key pairs.

> \[!TIP]
> HTTPS Signatures, Linked Data Signatures, and Object Integrity Proofs can
> coexist in an application and be used together for maximum compatibility.
>
> If an activity is signed with HTTP Signatures, Linked Data Signatures,
> and Object Integrity Proofs, the recipient verifies the Object Integrity
> Proofs first when it is supported, and ignores the HTTP Signatures and
> Linked Data Signatures if the Object Integrity Proofs are valid.
> If the recipient does not support Object Integrity Proofs, it falls back to
> verifying the HTTP Signatures and Linked Data Signatures.
>
> To support HTTP Signatures, Linked Data Signatures, and Object Integrity
> Proofs simultaneously, you need to generate both RSA-PKCS#1-v1.5 and Ed25519
> key pairs for each actor, and store them in the database.

[FEP-8b32]: https://w3id.org/fep/8b32

## Activity transformers

*This API is available since Fedify 1.4.0.*

Activity transformers are a way to adjust activities before sending them to
the recipients.  It is useful for modifying the activity to fit the recipient's
ActivityPub implementation (which may have some quirks) or for adding some
additional information to the activity.

The activity transformers are applied before they are signed with the sender's
private key and sent to the recipients.

It can be configured by setting
the [`activityTransformers`](./federation.md#activitytransformers) option.
By default, the following activity transformers are enabled:

### `autoIdAssigner()`

This activity transformer automatically assigns a unique IRI to the activity
if the `id` property is not set.  It is useful for ensuring that
the activity has a unique IRI, which is required by the ActivityPub
specification.

The generated IRI is a URN UUID like:

```
urn:uuid:12345678-1234-5678-1234-567812345678
```

### `actorDehydrator()`

This activity transformer dehydrates the `actor` property of the activity
so that it only contains the actor's URI (rather than the full actor object
inlined).  It is useful for satisfying some ActivityPub implementations like
[Threads] that have quirks, which fail to parse the activity if the `actor`
property contains the full actor object inlined.

For example, the following activity:

```typescript{3-7} twoslash
import { Follow, Person } from "@fedify/vocab";
// ---cut-before---
new Follow({
  id: new URL("http://example.com/activities/1"),
  actor: new Person({
    id: new URL("http://example.com/actors/1"),
    name: "Alice",
    preferredUsername: "alice",
  }),
  object: new Person({
    id: new URL("http://example.com/actors/2"),
    name: "Bob",
    preferredUsername: "bob",
  }),
});
```

is transformed into:

```typescript twoslash
import { Follow, Person } from "@fedify/vocab";
// ---cut-before---
new Follow({
  id: new URL("http://example.com/activities/1"),
  actor: new URL("http://example.com/actors/1"),  // [!code highlight]
  object: new Person({
    id: new URL("http://example.com/actors/2"),
    name: "Bob",
    preferredUsername: "bob",
  }),
});
```

[Threads]: https://www.threads.net/

---

---
url: /manual/test.md
description: >-
  Testing a federated server app is a bit tricky because it requires a federated
  environment.  This document explains how to easily test your federated server
  app with the help of several tools.
---

# Testing

Testing a federated server app is a bit tricky because it requires a federated
environment.  This document explains how to easily test your federated server
app with the help of several tools.

## Exposing a local server to the public

To test your federated server app, you need to expose your local server to the
public internet with a domain name and TLS certificate.  There are several tools
that help you do that:

* [`fedify tunnel`](../cli.md#fedify-tunnel-exposing-a-local-http-server-to-the-public-internet)
* [ngrok]
* [serveo]
* [localhost.run]
* [Tailscale Funnel]

> \[!NOTE]
> These tools are not for production use; they are for testing only.
> In production, you should expose your server with a proper domain and TLS
> certificate.

> \[!TIP]
> These tools behave like a reverse proxy, so basically the federation server
> cannot recognize if it is behind a reverse proxy, and if the reverse proxy
> is in HTTPS.  So the federation server will generate HTTP URLs in the
> ActivityPub messages, which cause interoperability issues.\[^1]  In this case,
> you can use the [x-forwarded-fetch] middleware in front of
> the `Federation.fetch()` method so that the `Federation` object recognizes
> the proper domain name and protocol of the incoming HTTP requests.
>
> For more information, see [*How the Federation object recognizes
> the domain name*
> section](./federation.md#how-the-federation-object-recognizes-the-domain-name)
> in the *Federation* document.

\[^1]: According to the [*Object Identifiers* section][1] in the ActivityPub
specification, the public dereferenceable URIs should use HTTPS URIs.

[ngrok]: https://ngrok.com/

[serveo]: https://serveo.net/

[localhost.run]: https://localhost.run/

[Tailscale Funnel]: https://tailscale.com/kb/1223/funnel

[x-forwarded-fetch]: https://github.com/dahlia/x-forwarded-fetch

[1]: https://www.w3.org/TR/activitypub/#obj-id

## Inspecting ActivityPub objects

### BrowserPub

[BrowserPub] is a browser for debugging ActivityPub and the fediverse.  You can
punch in any ActivityPub discoverable web URL or fediverse handle, and it will
discover and display the underlying ActivityPub.

For example:

* [hollo.social/@fedify]
* [@hongminhee@fosstodon.org]

If you want to know further details about BrowserPub,
read the [creator's Mastodon thread].

[BrowserPub]: https://browser.pub/

[hollo.social/@fedify]: https://browser.pub/https://hollo.social/@fedify

[@hongminhee@fosstodon.org]: https://browser.pub/@hongminhee@fosstodon.org

[creator's Mastodon thread]: https://podcastindex.social/@js/113011966366461060

### `fedify lookup` command

Fedify provides a [CLI toolchain](../cli.md) for testing and debugging.
The
[`fedify lookup` command](../cli.md#fedify-lookup-looking-up-an-activitypub-object)
is a simple tool for looking up an ActivityPub object by its URL or fediverse
handle.

## Inspecting ActivityPub activities

### ActivityPub.Academy

[ActivityPub.Academy] is a special Mastodon instance that is designed for
debugging and testing ActivityPub peers.  You can create an account on it and
use it for testing your federated server app.  Its best feature is that it
provides a web interface for debugging ActivityPub messages.  Any sent and
received activities are displayed on the web interface in real-time.

> \[!NOTE]
> Any accounts on ActivityPub.Academy are volatile; they are deleted after a
> certain period of inactivity.

[ActivityPub.Academy]: https://activitypub.academy/

### `fedify inbox` command

Fedify provides a [CLI toolchain](../cli.md) for testing and debugging.
The [`fedify inbox` command](../cli.md#fedify-inbox-ephemeral-inbox-server) is
a simple tool for spinning up an ephemeral inbox server that receives and
displays incoming ActivityPub messages.

## Allowing fetching private network addresses

*This API is available since Fedify 0.15.0.*

By default, Fedify disallows fetching private network addresses
(e.g., localhost) in order to prevent [SSRF] attacks.  However, in some cases,
you may want to allow fetching private network addresses for testing purposes
(e.g., end-to-end testing).  In this case, you can set
the [`allowPrivateAddress`](./federation.md#allowprivateaddress) option to
`true` in the `createFederation()` function:

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";
// ---cut-before---
const federation = createFederation({
  // ... other options
  allowPrivateAddress: true,
});
```

> \[!NOTE]
> By turning on the `allowPrivateAddress` option, you cannot configure other
> options related to document loaders including
> [`documentLoader`](./federation.md#documentloader),
> [`contextLoader`](./federation.md#contextloader), and
> [`authenticatedDocumentLoaderFactory`](./federation.md#authenticateddocumentloaderfactory)

> \[!WARNING]
> Be careful when you allow fetching private network addresses.  It may cause
> security vulnerabilities such as [SSRF].  Make sure to turn off the option
> when you finish testing, or conditionally turn it on only in the testing
> environment.

[SSRF]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery

## Mocking

*This API is available since Fedify 1.8.0.*

When writing unit tests for your federated server application, you often need
to mock the federation layer to avoid making actual network requests and to
have predictable test behavior.  Fedify provides the `@fedify/testing` package
that includes mock implementations of the `Federation` and `Context` interfaces
specifically designed for testing purposes.

### Installation

You can install the `@fedify/testing` package using your preferred package
manager:

::: code-group

```bash [Deno]
deno add @fedify/testing
```

```bash [npm]
npm install @fedify/testing
```

```bash [pnpm]
pnpm add @fedify/testing
```

```bash [Yarn]
yarn add @fedify/testing
```

```bash [Bun]
bun add @fedify/testing
```

:::

### `createFederation()`

*This API is available since Fedify 1.9.1.*

The `createFederation()` function creates a mock implementation of the
`Federation` interface that allows you to:

* Track sent activities without making network requests
* Simulate receiving activities and test inbox listeners
* Configure custom URI templates for testing
* Test queue-based activity processing

Here's a basic example of using `createFederation()`:

```typescript twoslash
import { createFederation } from "@fedify/testing";
import { Create, Note } from "@fedify/vocab";

// Create a mock federation with context data
const federation = createFederation<{ userId: string }>({
  contextData: { userId: "test-user" }
});

// Set up inbox listeners
federation
  .setInboxListeners("/users/{identifier}/inbox")
  .on(Create, async (ctx: any, activity: any) => {
    console.log("Received activity:", activity.id);
    // Your inbox logic here
  });

// Simulate receiving an activity
const activity = new Create({
  id: new URL("https://example.com/activities/1"),
  actor: new URL("https://example.com/users/alice"),
  object: new Note({
    id: new URL("https://example.com/notes/1"),
    content: "Hello, world!"
  })
});

await federation.receiveActivity(activity);

// Check sent activities
console.log("Sent activities:", federation.sentActivities);
```

### Creating mock contexts

You can create mock contexts using the `createContext()` method,
which provides a mock implementation of the `Context` interface that tracks
sent activities and provides mock implementations of URI generation methods:

```typescript twoslash
import { createFederation } from "@fedify/testing";
import { Create, Note, Person } from "@fedify/vocab";

// Create a mock federation and context
const federation = createFederation<{ userId: string }>();
const context = federation.createContext(
  new URL("https://example.com"),
  { userId: "test-user" }
);

// Send an activity
const activity = new Create({
  id: new URL("https://example.com/activities/1"),
  actor: new URL("https://example.com/users/alice"),
  object: new Note({
    id: new URL("https://example.com/notes/1"),
    content: "Hello from MockContext!"
  })
});

await context.sendActivity(
  { identifier: "alice" },
  new Person({ id: new URL("https://example.com/users/bob") }),
  activity
);

// Check sent activities
const sentActivities = context.getSentActivities();
console.log("Context sent activities:", sentActivities);

// Also available in federation
console.log("Federation sent activities:", federation.sentActivities);
```

### Testing URI generation

Mock contexts created with the `createContext()` method provide mock
implementations of all URI generation methods that work with the paths
configured in your test federation:

```typescript twoslash
import { createFederation } from "@fedify/testing";
import { Note } from "@fedify/vocab";

const federation = createFederation();

// Configure paths (similar to real federation setup)
federation.setActorDispatcher("/users/{identifier}", () => null);
federation.setInboxListeners("/users/{identifier}/inbox", "/shared-inbox");
federation.setOutboxDispatcher("/users/{identifier}/outbox", () => null);
federation.setObjectDispatcher(Note, "/notes/{id}", () => null);

const context = federation.createContext(
  new URL("https://example.com"),
  undefined
);

// Test URI generation
console.log(context.getActorUri("alice"));     // https://example.com/users/alice
console.log(context.getInboxUri("alice"));     // https://example.com/users/alice/inbox
console.log(context.getOutboxUri("alice"));    // https://example.com/users/alice/outbox
console.log(context.getObjectUri(Note, { id: "123" })); // https://example.com/notes/123
```

### Tracking sent activities

Both the test federation and mock contexts track sent activities with detailed
metadata:

```typescript twoslash
// @noErrors: 2554
import { createFederation } from "@fedify/testing";

const federation = createFederation();
const context = federation.createContext(
  new URL("https://example.com/"),
  undefined
);

// Send some activities...
await context.sendActivity(/* ... */);

// Check federation-level tracking
for (const sent of federation.sentActivities) {
  console.log("Activity:", sent.activity.id);
  console.log("Queued:", sent.queued);
  console.log("Queue type:", sent.queue);
  console.log("Send order:", sent.sentOrder);
}

// Check context-level tracking
for (const sent of context.getSentActivities()) {
  console.log("Sender:", sent.sender);
  console.log("Recipients:", sent.recipients);
  console.log("Activity:", sent.activity);
}
```

### Simulating queue processing

You can test queue-based activity processing by starting the mock queue:

```typescript twoslash
// @noErrors: 2554
import { createFederation } from "@fedify/testing";

const federation = createFederation();

// Start the queue to simulate background processing
await federation.startQueue({ contextData: { userId: "test" } });

// Now sent activities will be marked as queued
const context = federation.createContext(
  new URL("https://example.com/"),
  { userId: "test" }
);
await context.sendActivity(/* ... */);

// Check if activities were queued
const queued = federation.sentActivities.filter(a => a.queued);
console.log("Queued activities:", queued.length);
```

### Resetting mock state

Both the test federation and mock contexts provide `reset()` methods to clear
tracked activities:

```typescript twoslash
import { createFederation } from "@fedify/testing";
const federation = createFederation();
const context = federation.createContext(
  new URL("https://example.com/"),
  undefined
);
// ---cut-before---
// Clear all sent activities
federation.reset();
context.reset();

console.log(federation.sentActivities.length); // 0
console.log(context.getSentActivities().length); // 0
```

The mocking utilities make it easy to write comprehensive unit tests for your
federated server application without requiring a full federation setup or
making actual network requests.

---

---
url: /manual/uri-template.md
description: >-
  Fedify uses RFC 6570 URI Templates for routing.  This guide explains the
  different URI Template expansion types and when to use each one.
---

# URI Template

Fedify uses URI Templates ([RFC 6570]) for defining URL patterns throughout
the framework.  This includes actor dispatchers, collection dispatchers, inbox
listeners, object dispatchers, and more.  Understanding the different expansion
types is crucial for handling identifiers correctly, especially when they
contain special characters or URIs.

[RFC 6570]: https://datatracker.ietf.org/doc/html/rfc6570

## What are URI Templates?

URI Templates are a compact way to describe a range of URIs through variable
expansion.  They use curly braces `{}` to mark variable parts that get replaced
with actual values.  The way these variables are expanded depends on the
*operator* used inside the braces.

## Expansion types

### Simple string expansion: `{var}`

Simple expansion is the default behavior when no operator is specified.
It percent-encodes reserved characters, making it suitable for basic string
identifiers like usernames or UUIDs.

Use this for basic identifiers that don't contain URIs or paths, such as
simple usernames (`alice`), numeric IDs, or UUIDs.  Notice how special
characters like `:` and spaces are percent-encoded:

| Template              | Value         | Result                 |
| --------------------- | ------------- | ---------------------- |
| `/users/{identifier}` | `alice`       | `/users/alice`         |
| `/users/{identifier}` | `alice:bob`   | `/users/alice%3Abob`   |
| `/users/{identifier}` | `hello world` | `/users/hello%20world` |

Here's how to use it in an actor dispatcher:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher(
  "/users/{identifier}",  // Simple expansion
  async (ctx, identifier) => {
    // identifier could be: "alice", "user123", "uuid-4567", etc.
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      // ...
    });
  }
);
```

> \[!WARNING]
> Do not use simple expansion for identifiers that contain URIs or paths,
> as it will double-encode reserved characters like `:`, `/`, `?`, etc.

### Reserved string expansion: `{+var}`

Reserved expansion (using the `+` operator) preserves reserved characters that
are allowed in URIs, such as `:`, `/`, `?`, `#`, etc.  This is essential when
your identifier contains a URI or path.

Use this for identifiers that contain URIs, URLs, or paths.  Unlike simple
expansion, reserved characters are kept as-is instead of being percent-encoded.
This prevents double-encoding issues when your identifier is itself a URI:

| Template               | Value                       | Result                             |
| ---------------------- | --------------------------- | ---------------------------------- |
| `/users/{+identifier}` | `https://example.com/actor` | `/users/https://example.com/actor` |
| `/users/{+identifier}` | `alice:bob`                 | `/users/alice:bob`                 |
| `/users/{+identifier}` | `path/to/resource`          | `/users/path/to/resource`          |

Here's how to use it when your identifiers might contain URIs:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher(
  "/users/{+identifier}",  // Reserved expansion
  async (ctx, identifier) => {
    // identifier could be: "https://example.com/actor", "urn:uuid:123", etc.
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      // ...
    });
  }
);
```

> \[!TIP]
> If you're getting double-encoding issues (e.g., `%253A` instead of `%3A`),
> switch from `{identifier}` to `{+identifier}`.

### Path segment expansion: `{/var}`

Path expansion automatically prefixes the value with a `/` character.
It's useful for optional path segments.  When the variable is empty or
undefined, nothing is added to the path:

| Template         | Value     | Result    |
| ---------------- | --------- | --------- |
| `/api{/version}` | `v1`      | `/api/v1` |
| `/api{/version}` | *(empty)* | `/api`    |

### Query parameter expansion: `{?var}`

Query expansion creates URL query parameters with `?` prefix.  You can specify
multiple variables separated by commas, and each will become a separate query
parameter:

| Template           | Value              | Result                    |
| ------------------ | ------------------ | ------------------------- |
| `/search{?q}`      | `hello`            | `/search?q=hello`         |
| `/search{?q,lang}` | `q=hello, lang=en` | `/search?q=hello&lang=en` |

### Query continuation: `{&var}`

Query continuation adds additional query parameters using `&` instead of `?`.
This is useful when you already have query parameters in the template and want
to add more:

| Template               | Value   | Result                     |
| ---------------------- | ------- | -------------------------- |
| `/search?type=all{&q}` | `hello` | `/search?type=all&q=hello` |

## Common use cases in Fedify

### Actor identifiers

If you're using simple usernames or UUIDs as actor identifiers, use simple
expansion.  This will properly encode any special characters:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher(
  "/users/{identifier}",
  async (ctx, identifier) => {
    // identifier: "alice", "bob", "550e8400-e29b-41d4-a716-446655440000"
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      // ...
    });
  }
);
```

However, if you're using URIs as identifiers (for example, when building
a proxy layer on top of existing ActivityPub servers), use reserved expansion
to avoid double-encoding:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher(
  "/users/{+identifier}",
  async (ctx, identifier) => {
    // identifier: "https://solid.example/activitypub/actor"
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      // ...
    });
  }
);
```

### Collections

The same principle applies to collections.  Use simple expansion when your
identifiers are basic strings:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setFollowersDispatcher(
  "/users/{identifier}/followers",
  async (ctx, identifier, cursor) => {
    // identifier: "alice", "bob"
    const items: Recipient[] = [];  // Your implementation here
    return { items };
  }
);
```

And use reserved expansion when identifiers might contain URIs:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import type { Recipient } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setFollowersDispatcher(
  "/users/{+identifier}/followers",
  async (ctx, identifier, cursor) => {
    // identifier: "https://example.com/users/alice"
    const items: Recipient[] = [];  // Your implementation here
    return { items };
  }
);
```

### Other dispatchers and listeners

URI Templates work the same way across all Fedify routing configurations.
Here are some additional examples:

Inbox listeners use the same pattern as other dispatchers:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Create } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Create, async (ctx, create) => {
    // Handle incoming Create activity
  });
```

Object dispatchers allow you to serve ActivityPub objects at custom URIs:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Note } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setObjectDispatcher(
  Note,
  "/users/{identifier}/posts/{id}",
  async (ctx, values) => {
    // values.identifier and values.id are both available
    return new Note({
      id: ctx.getObjectUri(Note, values),
      content: "Hello, world!",
    });
  }
);
```

The same expansion rules apply: use `{identifier}` for simple strings and
`{+identifier}` for URI-containing values.

## Common pitfalls

### Double-encoding with `{identifier}` for URIs

Using `{identifier}` when the identifier contains a URI causes double-encoding.
For example, if your identifier is `"https://example.com/actor"`, the collection
ID becomes
`https://fedify.example/users/https%253A%252F%252Fexample.com%252Factor/followers`
(notice `%253A` instead of `%3A`—the percent sign itself gets encoded).

This is wrong:

```typescript
// ❌ WRONG: Using {identifier} for URI-containing identifiers
federation.setFollowersDispatcher(
  "/users/{identifier}/followers",
  async (ctx, identifier, cursor) => {
    // Double-encoding will occur!
  }
);
```

Instead, use `{+identifier}` for URI-containing identifiers:

```typescript
// ✅ CORRECT: Using {+identifier} for URI-containing identifiers
federation.setFollowersDispatcher(
  "/users/{+identifier}/followers",
  async (ctx, identifier, cursor) => {
    // Now it expands to: /users/https://example.com/actor/followers
  }
);
```

### Matching issues with `{+identifier}`

Reserved expansion `{+identifier}` can match too broadly, including additional
path segments.  For example, `/users/{+identifier}` might match
`/users/alice/inbox`, giving `identifier` the value `"alice/inbox"`.

To prevent this, add validation in your dispatcher to reject identifiers
containing unexpected characters:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher(
  "/users/{+identifier}",
  async (ctx, identifier) => {
    // Reject identifiers with path separators if not expected
    if (identifier.includes('/')) return null;
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
    });
  }
);
```

## Decision guide

Use this guide to choose the right expansion type:

```mermaid
flowchart TD
    Start[What kind of identifier?]
    Start --> Simple{Simple string?<br/>e.g., username, UUID}
    Start --> URI{Contains URI?<br/>e.g., https://...}
    Start --> Path{Path segment?}
    Start --> Query{Query parameter?}

    Simple --> UseBraces["Use {identifier}"]
    URI --> UsePlus["Use {+identifier}"]
    Path --> UseSlash["Use {/var}"]
    Query --> UseQuestion["Use {?var} or {&var}"]

    UseBraces --> Example1["Example: /users/{identifier}"]
    UsePlus --> Example2["Example: /users/{+identifier}"]
    UseSlash --> Example3["Example: /api{/version}"]
    UseQuestion --> Example4["Example: /search{?q}"]
```

Quick reference:

| If your identifier contains…   | Use                         |
| ------------------------------ | --------------------------- |
| Just letters, numbers, hyphens | `{identifier}`              |
| UUIDs                          | `{identifier}`              |
| URIs or URLs                   | `{+identifier}`             |
| Special chars like `:`, `/`    | `{+identifier}`             |
| Path segments                  | `{+identifier}` or `{/var}` |

## Troubleshooting

### How do I know if I'm using the wrong expansion type?

Symptoms of using `{identifier}` when you should use `{+identifier}`:

* Double-encoded characters (e.g., `%253A` instead of `%3A`)
* Collection IDs that don't match the expected format
* Errors when trying to access generated URIs

Symptoms of using `{+identifier}` when you should use `{identifier}`:

* Routes matching too broadly (catching extra path segments)
* Security issues with path traversal
* Unexpected values in your identifier parameter

### Testing your URI Template

You can test your URI Template patterns by examining the generated URIs in your
dispatcher callbacks.  The `Context.getActorUri()` and similar methods will
expand the templates according to the pattern you specified.

For example, to verify the expansion:

```typescript twoslash
import { type Federation } from "@fedify/fedify";
import { Person } from "@fedify/vocab";
const federation = null as unknown as Federation<void>;
// ---cut-before---
federation.setActorDispatcher(
  "/users/{+identifier}",
  async (ctx, identifier) => {
    // Log the generated URI to verify expansion
    const uri = ctx.getActorUri(identifier);
    console.log(`Identifier: ${identifier}`);
    console.log(`Generated URI: ${uri.href}`);

    return new Person({
      id: uri,
      preferredUsername: identifier,
    });
  }
);
```

## Further reading

[RFC 6570]: URI Template
:   The official specification

[Actor dispatcher](./actor.md)
:   Learn about actor routing in Fedify

[Collections](./collections.md)
:   Learn about collection routing in Fedify

[Inbox listeners](./inbox.md)
:   Learn about handling incoming activities

[Object dispatcher](./object.md)
:   Learn about serving custom objects

---

---
url: /manual/vocab.md
description: >-
  The Activity Vocabulary is a collection of type-safe objects that represent
  the Activity Vocabulary and the vendor-specific extensions.  This section
  explains the key features of the objects.
---

# Vocabulary

One of the key features of Fedify library is that it provides a collection of
type-safe objects that represent the Activity Vocabulary and the vendor-specific
extensions.

There are tons of objects in the Activity Vocabulary, and it's not practical to
list all of them here.  Instead, we'll show a few examples of the objects that
are available in the library: `Create`, `Note`, and `Person`.  For the full
list of the objects, please refer to the [API reference].

> \[!CAUTION]
>
> Some classes in the Activity Vocabulary have the same name as the built-in
> JavaScript classes.  For example, the `Object` class in the Activity
> Vocabulary is different from the built-in [`Object`] class.  Therefore, you
> should be careful when importing the classes in the Activity Vocabulary so
> that you don't unintentionally shadow the built-in JavaScript classes.
>
> Here's a list of the classes in the Activity Vocabulary that have the same
> name as the built-in JavaScript classes:
>
> * `Image`
> * `Object`
>
> In order to avoid the conflict, you can alias the classes in the Activity
> Vocabulary when importing them.  For example, you can alias the `Object`
> class as `ASObject` as follows:
>
> ```typescript twoslash
> import { Object as ASObject } from "@fedify/vocab";
> ```
>
> Or, you can import the classes from the Activity Vocabulary with a prefix as
> follows:
>
> ```typescript
> import * as vocab from "@fedify/vocab";
> ```

[API reference]: https://jsr.io/@fedify/vocab/doc/~

[`Object`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object

## Installation

The `@fedify/vocab` package is available on [JSR] and [npm].  You can install
it using the following command:

::: code-group

```bash [Deno]
deno add jsr:@fedify/vocab
```

```bash [npm]
npm add @fedify/vocab
```

```bash [pnpm]
pnpm add @fedify/vocab
```

```bash [Yarn]
yarn add @fedify/vocab
```

```bash [Bun]
bun add @fedify/vocab
```

:::

[JSR]: https://jsr.io/@fedify/vocab

[npm]: https://www.npmjs.com/package/@fedify/vocab

## Instantiation

You can instantiate an object by calling the constructor function with an object
that contains the properties of the object.  The following shows an example of
instantiating a `Create` object:

```typescript twoslash
import { Temporal } from "@js-temporal/polyfill";
// ---cut-before---
import { Create, Note } from "@fedify/vocab";

const create = new Create({
  id: new URL("https://example.com/activities/123"),
  actor: new URL("https://example.com/users/alice"),
  object: new Note({
    id: new URL("https://example.com/notes/456"),
    content: "Hello, world!",
    published: Temporal.Instant.from("2024-01-01T00:00:00Z"),
  }),
});
```

Note that every URI is represented as a [`URL`] object.  This is for
distinguishing the URIs from the other strings.

> \[!TIP]
> You can instantiate an object from a JSON-LD document by calling the
> `fromJsonLd()` method of the object.  See the [*JSON-LD* section](#json-ld)
> for details.

[`URL`]: https://developer.mozilla.org/en-US/docs/Web/API/URL

## Properties

Every object in the Activity Vocabulary has a set of properties.  The properties
are categorized into the following types:

* Functional or non-functional
* Scalar or non-scalar

Functional properties are the properties that contain zero or
a single value, while non-functional properties are the properties
that contain zero or multiple values.

Scalar properties can contain only [scalar values](#scalar-types)
(e.g., string, number, boolean, URI), while non-scalar properties
can contain both scalar and non-scalar values. Objects like `Create`, `Note`,
and `Person` are non-scalar values.  Non-scalar properties can contain either
objects or URIs (object ID) of the objects.

Depending on the category of the property, the accessors of the property are
different.  The following table shows examples of the accessors:

|            | Functional                            | Non-functional                                                                         |
| ---------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
| Scalar     | `Object.published`                    | `Object.name`/`~Object.names`                                                          |
| Non-scalar | `Person.inboxId`/`~Person.getInbox()` | `Activity.actorId`/`~Activity.actorIds`/`~Activity.getActor()`/`~Activity.getActors()` |

Some non-functional properties have both singular and plural accessors for
the sake of convenience.  In such cases, the singular accessors return the first
value of the property, while the plural accessors return all values of the
property.

> \[!NOTE]
> Some of the properties in Activity Vocabulary have been renamed in Fedify:
>
> | Original name                | Accessor in Fedify                                                                                                                      |
> | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
> | [`alsoKnownAs`]              | `Application.getAliases()`/`Group.getAliases()`/`Organization.getAliases()`/`Person.getAliases()`/`Service.getAliases()`                |
> | [`anyOf`]                    | `Question.getInclusiveOptions()`                                                                                                        |
> | [`attributedTo`]             | `Object.getAttributions()`                                                                                                              |
> | [`hreflang`]                 | `Link.language`                                                                                                                         |
> | [`inReplyTo`]                | `Object.getReplyTargets()`                                                                                                              |
> | [`isCat`]                    | `Application.cat`/`Group.cat`/`Organization.cat`/`Person.cat`/`Service.cat`                                                             |
> | [`movedTo`]                  | `Application.getSuccessor()`/`Group.getSuccessor()`/`Organization.getSuccessor()`/`Person.getSuccessor()`/`Service.getSuccessor()`      |
> | [`oneOf`]                    | `Question.getExclusiveOptions()`                                                                                                        |
> | [`orderedItems`]             | `OrderedCollection.getItems()`                                                                                                          |
> | [`publicKeyMultibase`]       | `Multikey.publicKey`                                                                                                                    |
> | [`publicKeyPem`]             | `CryptographicKey.publicKey`                                                                                                            |
> | [`quoteUri`]                 | `Article.quoteUrl`/`ChatMessage.quoteUrl`/`Note.quoteUrl`/`Question.quoteUrl`                                                           |
> | [`votersCount`]              | `Question.voters`                                                                                                                       |
> | [`_misskey_followedMessage`] | `Application.followedMessage`/`Group.followedMessage`/`Organization.followedMessage`/`Person.followedMessage`/`Service.followedMessage` |
> | [`_misskey_quote`]           | `Article.quoteUrl`/`ChatMessage.quoteUrl`/`Note.quoteUrl`/`Question.quoteUrl`                                                           |

[`alsoKnownAs`]: https://www.w3.org/TR/did-core/#dfn-alsoknownas

[`anyOf`]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-anyof

[`attributedTo`]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attributedto

[`hreflang`]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-hreflang

[`inReplyTo`]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-inreplyto

[`isCat`]: https://misskey-hub.net/ns#iscat

[`movedTo`]: https://swicg.github.io/miscellany/#movedTo

[`oneOf`]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-oneof

[`orderedItems`]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-items

[`publicKeyMultibase`]: https://www.w3.org/TR/controller-document/#dfn-publickeymultibase

[`publicKeyPem`]: https://web.archive.org/web/20221218063101/https://web-payments.org/vocabs/security#publicKey

[`quoteUri`]: https://github.com/fedibird/mastodon?tab=readme-ov-file#quotes

[`votersCount`]: https://docs.joinmastodon.org/spec/activitypub/#poll-specific-properties

[`_misskey_followedMessage`]: https://misskey-hub.net/ns#_misskey_followedmessage

[`_misskey_quote`]: https://misskey-hub.net/ns#_misskey_quote

## Object IDs and remote objects

Every object in the Activity Vocabulary has an `id` property, which is the URI
of the object.  It is used to identify and dereference the object.

For example, the following two objects are equivalent (where dereferencing URI
*https://example.com/notes/456* returns the `Note` object):

```typescript twoslash
import { Create, Note } from "@fedify/vocab";
import { Temporal } from "@js-temporal/polyfill";
// ---cut-before---
const a = new Create({
  id: new URL("https://example.com/activities/123"),
  actor: new URL("https://example.com/users/alice"),
  object: new Note({
    id: new URL("https://example.com/notes/456"),
    content: "Hello, world!",
    published: Temporal.Instant.from("2024-01-01T00:00:00Z"),
  }),
});
const b = new Create({
  actor: new URL("https://example.com/users/alice"),
  object: new URL("https://example.com/notes/456"),
});
```

How are the two objects equivalent?  Because for the both objects,
`~Activity.getObject()` returns the equivalent `Note` object.  Such `get*()`
methods for non-scalar properties are called dereferencing accessors.
Under the hood, the `get*()` methods fetch the remote object from the URI
and return the object if no cache hit.  In the above example, the
`await a.getObject()` immediately returns the `Note` object because it's already
instantiated, while the `await b.getObject()` fetches the remote object from
the URI and returns the `Note` object.

If you only need the object ID without fetching the remote object, you can use
the `*Id`/`*Ids` accessors instead of dereferencing accessors.  In the same
manner, both `a.objectId` and `b.objectId` return the equivalent URI.

> \[!TIP]
> Dereferencing accessors take option `documentLoader` to specify the method
> to fetch the remote object.  By default, it uses the default document loader
> which utilizes the [`fetch()`] API.
>
> If you want to implement your own document loader, see the `DocumentLoader`
> interface in the API reference.
>
> See the
> [*Getting a `DocumentLoader`* section](./context.md#getting-a-documentloader)
> for details.

[`fetch()`]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

## Property hydration

The `get*()` accessor methods for non-scalar properties automatically populate
the property with the remote object when the methods are called even if
the property internally contains only the URI of the object.  This is called
property hydration.

For example, the following code hydrates the `object` property of the `Create`
object:

```typescript twoslash
import { Create } from "@fedify/vocab";
// ---cut-before---
const create = new Create({
  object: new URL(
    "https://hollo.social/@fedify/0191e4f3-6b08-7003-9d33-f07d1e33d7b4",
  ),
});

// Hydrates the `object` property:
const note = await create.getObject();

// Returns the hydrated `object` property; therefore, the following code does
// not make any HTTP request:
const note2 = await create.getObject();
```

Hydrating the property also affects the JSON-LD representation of the object.

For example, since the following code does not hydrate the `object` property,
the JSON-LD representation of the `Create` object has the `object` property
with the URI of the object:

```typescript twoslash
import { Create } from "@fedify/vocab";
// ---cut-before---
const create = new Create({
  object: new URL(
    "https://hollo.social/@fedify/0191e4f3-6b08-7003-9d33-f07d1e33d7b4",
  ),
});

const jsonLd = await create.toJsonLd();
console.log(JSON.stringify(jsonLd));
```

The above code outputs the following JSON-LD document (`"@context"` is
simplified for readability):

```json
{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Create",
  "object": "https://hollo.social/@fedify/0191e4f3-6b08-7003-9d33-f07d1e33d7b4"
}
```

However, if the property is once hydrated, the JSON-LD representation of the
object has the `object` property with the full object:

```typescript twoslash
import { Create } from "@fedify/vocab";
const create = new Create({ });
// ---cut-before---
// Hydrates the `object` property:
await create.getObject();

const jsonLd = await create.toJsonLd();
console.log(JSON.stringify(jsonLd));
```

The above code outputs the following JSON-LD document (`"@context"` and some
attributes are simplified or omitted for readability):

```json
{
  "type": "Create",
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "object": {
    "id": "https://hollo.social/@fedify/0191e4f3-6b08-7003-9d33-f07d1e33d7b4",
    "type": "Note",
    "attributedTo": "https://hollo.social/@fedify",
    "content": "<p>...</p>\n",
    "published": "2024-09-12T06:37:23.593Z",
    "sensitive": false,
    "tag": [],
    "to": "as:Public",
    "url": "https://hollo.social/@fedify/0191e4f3-6b08-7003-9d33-f07d1e33d7b4"
  }
}
```

## Immutability

Every object in the Activity Vocabulary is represented as an immutable object.
This means that you cannot change the properties of the object after the object
is instantiated.  This is for ensuring the consistency of the objects and the
safety of the objects in the concurrent environment.

In order to change the properties of the object, you need to clone the object
with the new properties.  Fortunately, the objects have a `clone()` method that
takes an object with the new properties and returns a new object with the new
properties.  The following shows an example of changing the `~Object.content`
property of a `Note` object:

```typescript{8-10} twoslash
import { Temporal } from "@js-temporal/polyfill";
// ---cut-before---
import { Note } from "@fedify/vocab";
import { LanguageString } from "@fedify/vocab-runtime";

const noteInEnglish = new Note({
  id: new URL("https://example.com/notes/123"),
  content: new LanguageString("Hello, world!", "en"),
  published: Temporal.Now.instant(),
});
const noteInChinese = noteInEnglish.clone({
  content: new LanguageString("你好，世界！", "zh"),
});
```

Parameters of the `clone()` method share the same type with parameters of
the constructor.

## Looking up remote objects

See the [*Looking up remote objects*
section](./context.md#looking-up-remote-objects) in the *Context* docs.

## Traversing remote collections

See the [*Traversing remote collections*
section](./context.md#traversing-remote-collections) in the *Context* docs.

## JSON-LD

Under the hood, every object in the Activity Vocabulary is represented as a
[JSON-LD] document.  The JSON-LD document is a JSON object that contains the
properties of the object.  The following shows an example of the JSON-LD
representation of the `Create` object:

```json
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://example.com/activities/123",
  "actor": "https://example.com/users/alice",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/456",
    "content": "Hello, world!",
    "published": "2024-01-01T00:00:00Z"
  }
}
```

If you want to instantiate an object from a JSON-LD document, you can use the
`fromJsonLd()` method of the object.  The following shows an example of
instantiating a `Create` object from the JSON-LD document:

```typescript twoslash
import { Create } from "@fedify/vocab";

const create = await Create.fromJsonLd({
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://example.com/activities/123",
  "actor": "https://example.com/users/alice",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/456",
    "content": "Hello, world!",
    "published": "2024-01-01T00:00:00Z"
  }
});
```

Note that the `fromJsonLd()` method can parse a subtype as well.  For example,
since `Create` is a subtype of `Activity`, the `Activity.fromJsonLd()` method
can parse a `Create` object as well:

```typescript twoslash
import { Activity } from "@fedify/vocab";

const create = await Activity.fromJsonLd({
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://example.com/activities/123",
  "actor": "https://example.com/users/alice",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/456",
    "content": "Hello, world!",
    "published": "2024-01-01T00:00:00Z"
  }
});
```

On the other way around, you can use the `toJsonLd()` method to get the JSON-LD
representation of the object:

```typescript twoslash
import { Create } from "@fedify/vocab";
const create = new Create({});
// ---cut-before---
const jsonLd = await create.toJsonLd();
```

By default, the `toJsonLd()` method returns the JSON-LD document which is
neither compacted nor expanded.  Instead, it processes the JSON-LD document
without the proper JSON-LD processor for efficiency.

The `toJsonLd()` method takes some options to customize the JSON-LD document.
For example, you can compact the JSON-LD document with a custom context.
In this case, the `toJsonLd()` method returns the compacted JSON-LD document
which is processed by the proper JSON-LD processor:

```typescript twoslash
import { Create } from "@fedify/vocab";
const create = new Create({});
// ---cut-before---
const jsonLd = await create.toJsonLd({
  format: "compact",
  context: "https://example.com/context",
});
```

> \[!TIP]
> Why are the `fromJsonLd()` and `toJsonLd()` methods asynchronous?  Because
> both methods may fetch remote documents under the hood in order to
> [compact/expand a JSON-LD document].  In fact, like the dereferencing
> accessors, both `fromJsonLd()` and `toJsonLd()` methods take option
> `documentLoader` to specify the method to fetch the remote document.
>
> See the
> [*Getting a `DocumentLoader`* section](./context.md#getting-a-documentloader)
> for details.

[JSON-LD]: https://json-ld.org/

[compact/expand a JSON-LD document]: https://www.youtube.com/watch?v=Tm3fD89dqRE

## Scalar types

The Activity Vocabulary has a few scalar types that are used as the values of
the properties.  The following table shows the scalar types and their
corresponding TypeScript types:

| Scalar type              | TypeScript type                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `xsd:boolean`            | `boolean`                                                                                                     |
| `xsd:integer`            | `number`                                                                                                      |
| `xsd:nonNegativeInteger` | `number`                                                                                                      |
| `xsd:float`              | `number`                                                                                                      |
| `xsd:decimal`            | `Decimal`                                                                                                     |
| `xsd:string`             | `string`                                                                                                      |
| `xsd:anyURI`             | [`URL`]                                                                                                       |
| `xsd:dateTime`           | [`Temporal.Instant`]                                                                                          |
| `xsd:duration`           | [`Temporal.Duration`]                                                                                         |
| `rdf:langString`         | `LanguageString`                                                                                              |
| `w3id:cryptosuiteString` | `"eddsa-jcs-2022"`                                                                                            |
| `w3id:multibase`         | [`Uint8Array`]                                                                                                |
| Language tag ([BCP 47])  | [`Intl.Locale`]                                                                                               |
| Public key PEM           | [`CryptoKey`]                                                                                                 |
| Public key Multibase     | [`CryptoKey`]                                                                                                 |
| Proof purpose            | `"assertionMethod" \| "authentication" \| "capabilityInvocation" \| "capabilityDelegation" \| "keyAgreement"` |
| Units                    | `"cm" \| "feet" \| "inches" \| "km" \| "m" \| "miles" \| URL`                                                 |

`Decimal` values come from `@fedify/vocab-runtime` as a branded string type.
Use `isDecimal()` when you need to check whether a string is already in the
normalized `xsd:decimal` lexical form, and use `canParseDecimal()` or
`parseDecimal()` when you need XML Schema whitespace normalization before
validation:

```typescript twoslash
import type { Decimal } from "@fedify/vocab-runtime";
import {
  canParseDecimal,
  isDecimal,
  parseDecimal,
} from "@fedify/vocab-runtime";

const raw = " 12.50 ";

isDecimal(raw); // false
canParseDecimal(raw); // true

const price: Decimal = parseDecimal(raw);
price; // "12.50"
```

`Decimal` keeps the original string at runtime instead of converting it to
JavaScript `number`, which avoids floating-point precision loss for exact
decimal values such as prices and measurements.  `parseDecimal()` normalizes
XML Schema whitespace before returning the branded value, so the runtime
representation always uses the normalized lexical form.

A property range must not combine `xsd:string` and `xsd:decimal`.  Both map to
runtime strings, so the generated encoder cannot distinguish them reliably
during JSON-LD serialization and Fedify rejects such schema definitions at code
generation time.

[`Temporal.Instant`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant

[`Temporal.Duration`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration

[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array

[BCP 47]: https://www.rfc-editor.org/info/bcp47

[`Intl.Locale`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale

[`CryptoKey`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey

## Origin-based security model

*This section is applicable since Fedify 1.9.0.*

Fedify implements an origin-based security model following [FEP-fe34] to protect
against content spoofing attacks and maintain secure federation practices.
This security model ensures that objects and their properties respect origin
boundaries, preventing malicious actors from impersonating content from other
servers.

[FEP-fe34]: https://w3id.org/fep/fe34

### Same-origin policy for properties

When accessing properties of ActivityPub objects, Fedify enforces same-origin
policy rules.  Even if an object appears to be embedded in the JSON-LD
representation, property accessors will automatically perform hydration (remote
fetching) if the embedded object's `@id` has a different origin than its parent
object.

For example, consider this JSON-LD representation:

```json
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://example.com/activities/123",
  "actor": "https://example.com/users/alice",
  "object": {
    "type": "Note",
    "id": "https://different-origin.com/notes/456",
    "content": "This is from a different origin"
  }
}
```

In this case, when you access the `object` property of the `Create` activity,
Fedify will not trust the embedded `Note` object because its `@id` has a
different origin (`different-origin.com`) than the parent activity's origin
(`example.com`).  Instead, it will fetch the `Note` object directly from
`https://different-origin.com/notes/456` to verify its authenticity.

### Controlling origin checks

You can control this behavior using the `crossOrigin` option when calling
property accessors:

```typescript twoslash
import { Create } from "@fedify/vocab";
const create = {} as unknown as Create;
// ---cut-before---
// Default behavior: ignore untrusted embedded objects (recommended)
const objectDefault = await create.getObject();

// Throw an error when encountering cross-origin objects
const objectStrict = await create.getObject({ crossOrigin: "throw" });

// Bypass origin checks (not recommended, potential security risk)
const objectBypass = await create.getObject({ crossOrigin: "trust" });
```

The `crossOrigin` option accepts the following values:

`"ignore"` (default)
:   Ignore untrusted embedded objects and fetch from origin

`"throw"`
:   Throw an error when encountering cross-origin embedded objects

`"trust"`
:   Trust embedded objects regardless of origin (⚠️ security risk)

> \[!WARNING]
> Using `crossOrigin: "trust"` can expose your application to security
> vulnerabilities, including content spoofing attacks.  Only use this option
> if you fully understand the security implications and have implemented
> additional validation measures.

### Trust tracking

Internally, Fedify maintains trust information for each property value.  Objects
that are constructed locally, fetched directly from their authoritative source,
or explicitly validated are marked as trusted.  This trust information is used
to determine whether property accessors need to perform additional validation
or fetching.

## Extending the vocabulary

While Fedify's vocabulary API offers many advantages, it has a limitation due to
its implementation through code generation: it is difficult to extend with
custom types or custom properties that are not included in the Activity
Vocabulary and major vendor extensions provided by Fedify.  This means that
adding custom types or properties at runtime is challenging, and if you want to
add new types or properties, you need to contribute to the Fedify upstream
repository.

Fortunately, Fedify's vocabulary API is very open to external contributions,
and technically, adding new types or properties to the vocabulary API is not
difficult.

The Fedify project accepts contributions to the vocabulary API almost
unconditionally if any of the following conditions are met:

* The type or property is specified in some form as a [FEP] (Fediverse
  Enhancement Proposal) or equivalent specification document
* The type or property is already adopted and used by widely-used
  implementations in the fediverse such as Mastodon, Pleroma, etc.
* The type or property has been sufficiently discussed in the Fedify
  community ([Discord], [Matrix], [GitHub Discussions], etc.)

If you want to contribute to Fedify's vocabulary API, the process is
straightforward.  The *\*.yaml* files located in the *packages/vocab/src/*
directory of the Fedify repository serve as the source data for code generation.
To add a new type, you simply need to add a new *.yaml* file, and to add a new
property, you need to define the new property in the `properties` section of an
existing *.yaml* file.

For detailed information on how to contribute to the vocabulary API, please
refer to the [*Contributing guide*](../contribute.md) and the existing YAML
files in the *packages/vocab/src/* directory for examples.

[FEP]: https://w3id.org/fep/

[Discord]: https://discord.gg/bhtwpzURwd

[Matrix]: https://matrix.to/#/#fedify:matrix.org

[GitHub Discussions]: https://github.com/fedify-dev/fedify/discussions

---

---
url: /manual/webfinger.md
description: >-
  WebFinger is a protocol that allows for the discovery of information about
  people and other entities on the Internet using just their identifier. This
  section explains how to implement WebFinger endpoints and use the WebFinger
  client in Fedify.
---

# WebFinger

According to the [WebFinger website]:

> WebFinger is used to discover information about people or other entities
> on the Internet that are identified by a URI using standard
> Hypertext Transfer Protocol (HTTP) methods over a secure transport.
> A WebFinger resource returns a JavaScript Object Notation (JSON) object
> describing the entity that is queried. The JSON object is referred to as
> the JSON Resource Descriptor (JRD).

WebFinger is essential for ActivityPub federation. It lets servers discover
actor profiles using familiar identifiers like `@user@example.com`.
Most ActivityPub implementations, including Mastodon and Misskey, depend on
WebFinger for account discovery.

> \[!NOTE]
> Fedify implements WebFinger according to [RFC 7033] specification.

[WebFinger website]: https://webfinger.net/

[RFC 7033]: https://datatracker.ietf.org/doc/html/rfc7033

## WebFinger schema

The WebFinger response follows the JSON Resource Descriptor (JRD) format
as defined in [RFC 7033]. The main interfaces are:

### `ResourceDescriptor`

The main WebFinger response object:

`subject`
:   A URI that identifies the entity that this descriptor describes.
This is typically set automatically by Fedify.

`aliases`
:   URIs that identify the same entity as the `subject`.

`properties`
:   Additional key-value properties about the `subject`.

`links`
:   An array of [`Link`] objects pointing to related resources.

[`Link`]: https://jsr.io/@fedify/fedify/doc/webfinger/~/Link

### `Link`

Represents a link to a related resource:

`rel`
:   *Required.* The link's relation type, which is either a URI or a
registered relation type (see [RFC 5988]).

`type`
:   The media type of the target resource (see [RFC 6838]).

`href`
:   A URI pointing to the target resource.

`titles`
:   Human-readable titles describing the link relation. If the language is
unknown or unspecified, the key is `"und"`.

`properties`
:   Additional key-value properties about the link relation.

`template`
:   *Since Fedify 1.9.0.* A URI Template ([RFC 6570]) with placeholders
for variable substitution. Commonly used for remote follow endpoints
where `{uri}` is replaced with the account to follow.

[RFC 5988]: https://datatracker.ietf.org/doc/html/rfc5988

[RFC 6838]: https://datatracker.ietf.org/doc/html/rfc6838

[RFC 6570]: https://datatracker.ietf.org/doc/html/rfc6570

### Common link relations

Fedify automatically generates these link relations from actor properties:

`"self"`
:   The actor's ActivityPub profile URI. Uses `application/activity+json`
as the media type.

`"http://webfinger.net/rel/profile-page"`
:   The actor's profile page from the `url` property. Uses `text/html` as
the media type.

`"http://webfinger.net/rel/avatar"`
:   The actor's avatar from the `icon` property.

Additional custom links can be added via WebFinger links dispatcher:

`"http://ostatus.org/schema/1.0/subscribe"`
:   Remote follow endpoint (common in Mastodon). Uses a URI template
with `{uri}` placeholder for the account being followed.

Example WebFinger response (including both automatic and custom links):

```json
{
  "subject": "acct:alice@your-domain.com",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://your-domain.com/users/alice"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://your-domain.com/@alice"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://your-domain.com/authorize_interaction?uri={uri}"
    }
  ]
}
```

## Customizing WebFinger endpoint

*This API is available since Fedify 1.9.0.*

While Fedify automatically handles WebFinger responses for actors registered
via `~Federatable.setActorDispatcher()`, you can add custom links using
`~Federatable.setWebFingerLinksDispatcher()`. This is useful for adding
non-standard links like Mastodon's remote follow endpoint:

```typescript twoslash
// @noErrors: 2345
import { createFederation } from "@fedify/fedify";

const federation = createFederation({
  // Omitted for brevity; see the related section for details.
});

federation.setWebFingerLinksDispatcher(async (ctx, resource) => {
    return [
      {
        rel: "http://ostatus.org/schema/1.0/subscribe",
        template: `https://your-domain.com/@${resource.pathname}/authorize_interaction?uri={uri}`
      }
    ];
  }
);
```

This gives results like below:

```json
{
  "subject": "acct:alice@your-domain.com",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://your-domain.com/users/alice"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://your-domain.com/@alice"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://your-domain.com/@alice@your-domain.com/authorize_interaction?uri={uri}"
    }
  ]
}
```

The WebFinger links dispatcher receives two parameters:

`ctx`
:   The federation context

`resource`
:   The URL queried via WebFinger

> \[!TIP]
> The WebFinger endpoint is automatically exposed at `/.well-known/webfinger`
> by the `Federation.fetch()` method. You don't need to manually handle this
> route.

> \[!NOTE]
> Before the introduction of `~Federatable.setWebFingerLinksDispatcher()` in
> Fedify 1.9.0, WebFinger responses could only be customized through
> `~Federatable.setActorDispatcher()` by setting the actor's `url` property.
> This method still works and is sufficient for many use cases, though it
> doesn't support the `template` field needed for features like Mastodon's
> remote follow functionality.
>
> See the [WebFinger links section](./actor.md#webfinger-links) in the Actor
> documentation for details on customizing WebFinger through actor properties.

## Looking up WebFinger

*This API is available since Fedify 1.6.0.*

Use `~Context.lookupWebFinger()` to query remote WebFinger endpoints:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const webfingerData = await ctx.lookupWebFinger("acct:fedify@hollo.social");
```

If the lookup fails or the account doesn't exist, the method returns `null`.
The returned WebFinger document contains links to various resources associated
with the account, such as profile pages, ActivityPub actor URIs, and more:

```typescript twoslash
import { type Context } from "@fedify/fedify";
const ctx = null as unknown as Context<void>;
// ---cut-before---
const webfingerData = await ctx.lookupWebFinger("acct:fedify@hollo.social");

// Find the ActivityPub actor URI
const activityPubActorLink = webfingerData?.links?.find(link =>
  link.rel === "self" && link.type === "application/activity+json"
);

if (activityPubActorLink?.href) {
  const actor = await ctx.lookupObject(activityPubActorLink.href);
  // Work with the actor...
}
```

> \[!NOTE]
> In most cases, you can use the higher-level `~Context.lookupObject()` method
> which automatically performs WebFinger lookups when given a handle.
> Use `~Context.lookupWebFinger()` when you need the raw WebFinger data or
> want more direct control over the lookup process.

## Using WebFinger client

The `@fedify/webfinger` package provides a standalone WebFinger client that can
be used independently of the main Fedify framework.  This is useful when you
only need WebFinger lookup functionality without the full ActivityPub
federation capabilities.

### Installation

The `@fedify/webfinger` package is available on [JSR] and [npm].  You can
install it using the following command:

::: code-group

```bash [Deno]
deno add jsr:@fedify/webfinger
```

```bash [npm]
npm add @fedify/webfinger
```

```bash [pnpm]
pnpm add @fedify/webfinger
```

```bash [Yarn]
yarn add @fedify/webfinger
```

```bash [Bun]
bun add @fedify/webfinger
```

:::

[JSR]: https://jsr.io/@fedify/webfinger

[npm]: https://www.npmjs.com/package/@fedify/webfinger

### Looking up a WebFinger resource

You can look up a WebFinger resource using the `lookupWebFinger()` function:

```typescript twoslash
import { lookupWebFinger } from "@fedify/webfinger";

// Look up by acct: URI
const result = await lookupWebFinger("acct:alice@example.com");

// Look up by URL
const result2 = await lookupWebFinger("https://example.com/users/alice");
```

### Working with the result

The result is a `ResourceDescriptor` object containing the subject, aliases,
properties, and links:

```typescript twoslash
import { lookupWebFinger } from "@fedify/webfinger";

const result = await lookupWebFinger("acct:alice@example.com");
if (result != null) {
  console.log("Subject:", result.subject);
  console.log("Aliases:", result.aliases);

  // Find the ActivityPub actor URL
  const actorLink = result.links?.find(
    (link) => link.rel === "self" && link.type === "application/activity+json",
  );
  if (actorLink?.href != null) {
    console.log("Actor URL:", actorLink.href);
  }
}
```

### Configuration options

The `lookupWebFinger()` function accepts various options:

```typescript twoslash
import { lookupWebFinger } from "@fedify/webfinger";

const result = await lookupWebFinger("acct:alice@example.com", {
  // Custom User-Agent header
  userAgent: "MyApp/1.0",

  // Maximum redirects to follow (default: 5)
  maxRedirection: 3,

  // AbortSignal for cancellation
  signal: AbortSignal.timeout(5000),
});
```

The available options are:

`userAgent`
:   The `User-Agent` header value to use when making requests.  Can be a string
or an object with options for generating the header.

`allowPrivateAddress`
:   Whether to allow private IP addresses in the URL.  Mostly useful for
testing purposes.  *Do not use this in production.*  Turned off by default.

`maxRedirection`
:   The maximum number of redirections to follow.  Defaults to `5`.

`tracerProvider`
:   The OpenTelemetry tracer provider.  If omitted, the global tracer provider
is used.

`signal`
:   An `AbortSignal` for cancelling the request.

> \[!TIP]
> Use `@fedify/webfinger` when you need a lightweight WebFinger client without
> the full Fedify framework.  If you're already using Fedify, prefer
> `~Context.lookupWebFinger()` instead as it integrates with the federation
> context.

---

---
url: /intro.md
---
# What is Fedify?

Fedify is a TypeScript library for building federated server apps
powered by [ActivityPub] and other standards, so-called [fediverse].\[^1]
It aims to eliminate the complexity and boilerplate code when
building a federated server app, so that you can focus on your business logic
and user experience.

Currently, Fedify provides the following features out of the box:

* Type-safe objects for [Activity Vocabulary] (including some vendor-specific
  extensions)
* [WebFinger] client and server
* [HTTP Signatures] & [HTTP Message Signatures]
* [Object Integrity Proofs][FEP-8b32] & [Linked Data Signatures]
* Middlewares for handling webhooks
* [NodeInfo] protocol
* Enhanced interoperability with Mastodon and other popular fediverse
  software
* [Integration with various web frameworks](./manual/integration.md)
* [CLI toolchain for testing and debugging](./cli.md)

If you want to know more about the project, please take a look at the following
resources:

* [GitHub]
* Tutorials: [Learning the basics](./tutorial/basics.md) &
  [Creating a microblog](./tutorial/microblog.md)
* [API reference]
* [Examples]

If you have any questions, suggestions, or feedback, please feel free to
join our [Matrix chat space] or [Discord server] or [GitHub Discussions].

\[^1]: You may already know some of the networks in the fediverse, such as
[Mastodon], [Lemmy], [Pixelfed], [PeerTube], and so on.

[ActivityPub]: https://www.w3.org/TR/activitypub/

[fediverse]: https://en.wikipedia.org/wiki/Fediverse

[Activity Vocabulary]: https://www.w3.org/TR/activitystreams-vocabulary/

[WebFinger]: https://datatracker.ietf.org/doc/html/rfc7033

[HTTP Signatures]: https://tools.ietf.org/html/draft-cavage-http-signatures-12

[HTTP Message Signatures]: https://www.rfc-editor.org/rfc/rfc9421

[FEP-8b32]: https://w3id.org/fep/8b32

[Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/

[NodeInfo]: https://nodeinfo.diaspora.software/

[GitHub]: https://github.com/fedify-dev/fedify

[API reference]: https://jsr.io/@fedify/fedify

[Examples]: https://github.com/fedify-dev/fedify/tree/main/examples

[Matrix chat space]: https://matrix.to/#/#fedify:matrix.org

[Discord server]: https://discord.gg/bhtwpzURwd

[GitHub Discussions]: https://github.com/fedify-dev/fedify/discussions

[Mastodon]: https://joinmastodon.org/

[Lemmy]: https://join-lemmy.org/

[Pixelfed]: https://pixelfed.org/

[PeerTube]: https://joinpeertube.org/

---

---
url: /why.md
description: >-
  This document explains why you should consider using Fedify for your
  ActivityPub server development.
---

# Why Fedify?

Developing a federated application using ActivityPub can be complex and
time-consuming.  While the ActivityPub specification provides a solid foundation
for decentralized social networking, implementing it from scratch presents
significant challenges.  Fedify alleviates these pain points,
allowing developers to focus on their application's unique features rather
than protocol intricacies.

## Common pain points when implementing ActivityPub from scratch

Without a framework like Fedify, developers face numerous challenges:

### Technical complexity

Steep learning curve
:   The ActivityPub family of specifications is extensive, covering hundreds of
pages of technical documentation

JSON-LD complexities
:   Dealing with context resolution, expansion, and compaction manually is
error-prone

Cryptographic hurdles
:   Implementing HTTP Signatures, key management, and signature verification
correctly requires specialized knowledge

### Infrastructure requirements

Message delivery reliability
:   Building retry logic, exponential backoff, and failure handling from scratch

Performance bottlenecks
:   Naive message delivery implementations can cause timeouts,
high memory usage, and server crashes

Scalability issues
:   Direct delivery to thousands of followers can overload your application
servers

### Federation challenges

Incompatible implementations
:   Different ActivityPub servers interpret the specifications differently,
requiring implementation-specific adaptations

Evolving ecosystem
:   Federation standards continue to evolve with community extensions and
conventions

Security vulnerabilities
:   Potential for SSRF attacks, signature forgery, and other security issues
without careful implementation

### Development overhead

No standardized tools
:   Developers must build their own debugging and testing utilities for
federation

Reinventing the wheel
:   Common patterns like WebFinger resolution or follower management must be
reimplemented

Maintenance burden
:   Keeping up with security patches and protocol changes across the fediverse

## Protocol complexity and data handling

The ActivityPub family of W3C recommendations—including ActivityStreams 2.0,
Activity Vocabulary, and ActivityPub—is extensive and challenging to implement
correctly.  Messages encoded in JSON-LD using the ActivityStreams vocabulary
require careful attention to contexts, IRI resolution, and object serialization.

Fedify provides:

* A higher-level abstraction over these protocols
* Type-safe TypeScript classes for all standard ActivityStreams types
* Utilities for creation, manipulation, and validation of ActivityPub objects

## Federation infrastructure

Building an ActivityPub server requires implementing several interconnected
systems:

### Message processing and delivery

Fedify offers a comprehensive solution for managing ActivityPub's inbox/outbox
model:

* Robust inbox handlers with activity de-duplication
* Configurable message queues with reliable retry mechanisms

### Scalability with fan-out architecture

One of the most challenging aspects of ActivityPub implementation is efficiently
delivering activities to potentially thousands of recipients.  Fedify's
[two-stage delivery process](./manual/send.md#optimizing-activity-delivery-for-large-audiences)
addresses this:

1. For activities with many recipients, a single consolidated message
   containing the activity and all recipient information is created
2. A background worker processes this message and re-enqueues individual
   delivery tasks
3. Each delivery has independent retry logic and error handling

```mermaid
flowchart TB
    A[Client] -->|Create post| B[Application]
    B -->|Create activity| C[Fedify]

    subgraph "Two-stage delivery process"
        C -->|1\. Single consolidated message| D[(Message Queue)]
        D -->|2\. Process message| E[Fan-out Worker]
        E -->|3\. Create individual delivery tasks| F[(Delivery Queue)]
    end

    F -->|Deliver to recipient 1| G[Remote server 1]
    F -->|Deliver to recipient 2| H[Remote server 2]
    F -->|Deliver to recipient N| I[Remote server N]

    G -.-|Failed? Retry with backoff| F
    H -.-|Failed? Retry with backoff| F
    I -.-|Failed? Retry with backoff| F
```

Benefits include:

* Faster API response times for improved UX
* Reduced memory consumption through payload deduplication
* Configurable fan-out strategies with `"auto"`, `"skip"`, or `"force"` options

## Security and interoperability

Security is paramount in federation, while interoperability across diverse
implementations presents ongoing challenges.

Fedify provides:

* Comprehensive cryptographic support (RSA-PKCS#1-v1.5 and Ed25519 keys)
* Multiple authentication methods
  ([HTTP Signatures](./manual/send.md#http-signatures),
  [HTTP Message Signatures](./manual/send.md#http-message-signatures),
  [Object Integrity Proofs](./manual/send.md#object-integrity-proofs),
  [Linked Data Signatures](./manual/send.md#linked-data-signatures))
* SSRF protection and other security best practices
* [Activity transformers](./manual/send.md#activity-transformers) that adjust
  outgoing activities for maximum compatibility
* Multi-origin support with canonical URL handling for consistent identity

## Technology agnosticism

Fedify doesn't force you to use specific technologies, giving you the freedom to
build with your preferred tools.

### Framework flexibility

Works with virtually any JavaScript/TypeScript web framework:

* [Express](./manual/integration.md#express)
* [Hono](./manual/integration.md#hono)
* [Fresh](./manual/integration.md#fresh)
* [SvelteKit](./manual/integration.md#sveltekit)
* [Next.js](./manual/integration.md#next.js)
* [h3](./manual/integration.md#h3)/Nitro

… and many more!

### Database independence

* Use any SQL or NoSQL database (PostgreSQL, MySQL, MongoDB, etc.)
* Use any ORM (Prisma, TypeORM, Drizzle ORM, etc.)
* Fedify only requires a [key–value interface](./manual/kv.md)
  for its internal caching

## Developer experience

Fedify significantly improves the developer experience through:

TypeScript-native design
:   Comprehensive type definitions with intelligent auto-completion

Observability
:   [Built-in OpenTelemetry support](./manual/opentelemetry.md) for tracing and
monitoring

[CLI toolchain](./cli.md)
:   Tools for testing and debugging federation, including:

```
 -  [Object lookup utility](./cli.md#fedify-lookup-looking-up-an-activitypub-object)
 -  [Ephemeral inbox server](./cli.md#fedify-inbox-ephemeral-inbox-server)
    for testing outgoing activities
 -  [Local tunnel](./cli.md#fedify-tunnel-exposing-a-local-http-server-to-the-public-internet)
    for exposing development servers to the internet
```

## Success stories

Several notable projects have chosen Fedify to implement ActivityPub federation,
demonstrating its effectiveness in real-world applications:

### Ghost: Federation for a major publishing platform

[Ghost], a leading open-source publishing platform used by thousands of
journalists, creators, and companies worldwide, chose Fedify for their
ActivityPub implementation:

* Built a separate ActivityPub service with Fedify rather than integrating
  directly into Ghost core
* Leveraged Fedify to quickly implement federation while focusing on
  delivering value to their large user base
* Contributes back features and bug fixes to the Fedify ecosystem

> ActivityPub sits on top of a lot more standards than you might think, so it's
> sometimes necessary to juggle a lot of complex standards to get the full
> picture… This is the main reason I created Fedify.
>
> …
>
> We can definitely attest to the problems that Fedify is working hard to
> solve, because even in just a few weeks of early prototyping we were running
> into the issues described above right away.
>
> —From *[Alright, let's Fedify]*

[Ghost]: https://ghost.org

[Alright, let's Fedify]: https://activitypub.ghost.org/day-4/

### Hollo: Single-user microblogging

[Hollo] is a federated microblogging platform specifically designed for single
users, created by the original developer of Fedify:

* Initially faced challenges implementing ActivityPub from scratch,
  which inspired the creation of Fedify
* Now powered by Fedify, offering features like Mastodon-compatible API,
  CommonMark support, and Misskey-style quotes
* Serves as both a showcase and test case for Fedify's capabilities

> Implementing ActivityPub from the ground up was quite painful for me…
> I realized that I was already building a sloppy quasi-framework for
> ActivityPub. I thought, “No way, I'm going to build a proper ActivityPub
> framework,” and Fedify is the result.
>
> —Hong Minhee, creator of Fedify and Hollo, in *[Alright, let's Fedify]*

[Hollo]: https://docs.hollo.social

### Hackers' Pub: Community-driven federation

[Hackers' Pub] is an open-source community project building federation
capabilities with Fedify:

* Demonstrates how community-driven projects can leverage Fedify to implement
  ActivityPub
* Showcases the accessibility of federation technology to developers beyond
  large organizations
* Part of the growing ecosystem of developers adopting Fedify to join
  the fediverse

[Hackers' Pub]: https://hackers.pub/

### Encyclia: Bridging academic research to the fediverse

[Encyclia] is an innovative service that makes [ORCID] (Open Researcher and
Contributor ID) records available on the fediverse:

* Bridges academic research into federated social networks by making
  researcher profiles and publications discoverable through ActivityPub
* Allows users to follow researchers and see their new publications in
  their federated social feeds
* Built using Fedify for ActivityPub implementation with tested
  interoperability across Mastodon and other fediverse platforms
* Demonstrates Fedify's versatility in specialized domains beyond traditional
  social networking applications

> Encyclia is built using Fedify, an ActivityPub-based federated server
> framework that helps developers easily integrate their applications with
> the fediverse… It simplifies the complex implementation of the ActivityPub
> protocol, significantly reducing development time.
>
> —From the [Encyclia roadmap]

[Encyclia]: https://encyclia.pub/

[ORCID]: https://orcid.org/

[Encyclia roadmap]: https://encyclia.pub/roadmap

### Typo Blue: Text-only blogging meets the fediverse

[Typo Blue] is a Korean text-only blogging platform that embraces minimalist
writing, allowing users to focus purely on text without images or attachments:

* Originally featured email subscription for readers to follow blogs
* Recently added opt-in ActivityPub integration using Fedify, enabling blogs
  to be discoverable across the fediverse
* Allows readers on Mastodon, Misskey, and other ActivityPub-compatible
  platforms to follow and interact with blogs
* Demonstrates how specialized platforms can maintain their unique identity
  while participating in the open social web

[Typo Blue]: https://typo.blue/

## Conclusion

While building an ActivityPub server from scratch can be educational,
it's a complex undertaking that can slow development and lead to
interoperability or security issues.

Fedify abstracts away these complexities, providing a robust, secure,
and developer-friendly framework.  By handling the low-level details of
ActivityPub, WebFinger, authentication, and more, Fedify empowers you to:

Develop faster
:   Focus on your application's core functionality and user experience

Reduce errors
:   Leverage type safety and battle-tested components

Ensure interoperability
:   Work seamlessly with the diverse fediverse ecosystem

Improve security
:   Rely on built-in security mechanisms and best practices

Stay flexible
:   Integrate with your technology stack of choice

If you're looking to build a federated application on the ActivityPub protocol,
Fedify offers a powerful and efficient path to success.