@fedify/relay 2.0.0-dev.12 → 2.0.0-dev.150

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2024–2025 Hong Minhee
+Copyright 2024–2026 Hong Minhee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -13,6 +13,9 @@ This package provides ActivityPub relay functionality for the [Fedify]
 ecosystem, enabling the creation and management of relay servers that can
 forward activities between federated instances.
 
+For comprehensive documentation on building and operating relay servers,
+see the [*Relay server* section in the Fedify manual][manual].
+
 
 What is an ActivityPub relay?
 ------------------------------
@@ -33,7 +36,7 @@ This package supports two popular relay protocols used in the fediverse:
 ### Mastodon-style relay
 
 The Mastodon-style relay protocol uses LD signatures for activity
-verification and follows the Public collection.  This protocol is widely
+verification and follows the Public collection. This protocol is widely
 supported by Mastodon and many other ActivityPub implementations.
 
 Key features:
@@ -46,11 +49,16 @@ Key features:
 
 ### LitePub-style relay
 
-*LitePub relay support is planned for a future release.*
-
 The LitePub-style relay protocol uses bidirectional following relationships
 and wraps activities in `Announce` activities for distribution.
 
+Key features:
+
+ -  Reciprocal following between relay and subscribers
+ -  Activities wrapped in `Announce` for distribution
+ -  Two-phase subscription (pending → accepted)
+ -  Enhanced federation capabilities
+
 
 Installation
 ------------
@@ -83,46 +91,101 @@ bun add @fedify/relay
 Usage
 -----
 
-### Creating a Mastodon-style relay
+### Creating a relay
 
-Here's a simple example of creating a Mastodon-compatible relay server:
+Here's a simple example of creating a relay server using the factory function:
 
 ~~~~ typescript
-import { MastodonRelay } from "@fedify/relay";
+import { createRelay } from "@fedify/relay";
 import { MemoryKvStore } from "@fedify/fedify";
 
-const relay = new MastodonRelay({
+// Create a Mastodon-style relay
+const relay = createRelay("mastodon", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
-});
-
-// Optional: Set a custom subscription handler to approve/reject subscriptions
-relay.setSubscriptionHandler(async (ctx, actor) => {
-  // Implement your approval logic here
-  // Return true to approve, false to reject
-  const domain = new URL(actor.id!).hostname;
-  const blockedDomains = ["spam.example", "blocked.example"];
-  return !blockedDomains.includes(domain);
+  origin: "https://relay.example.com",
+  // Required: Set a subscription handler to approve/reject subscriptions
+  subscriptionHandler: async (ctx, actor) => {
+    // For an open relay, simply return true
+    // return true;
+
+    // Or implement custom approval logic:
+    const domain = new URL(actor.id!).hostname;
+    const blockedDomains = ["spam.example", "blocked.example"];
+    return !blockedDomains.includes(domain);
+  },
 });
 
 // Serve the relay
 Deno.serve((request) => relay.fetch(request));
 ~~~~
 
+You can also create a LitePub-style relay by changing the type:
+
+~~~~ typescript
+const relay = createRelay("litepub", {
+  kv: new MemoryKvStore(),
+  origin: "https://relay.example.com",
+  subscriptionHandler: async (ctx, actor) => true,
+});
+~~~~
+
 ### Subscription handling
 
-By default, the relay automatically rejects all subscription requests.
-You can customize this behavior by setting a subscription handler:
+The `subscriptionHandler` is required and determines whether to approve or reject
+subscription requests.  For an open relay that accepts all subscriptions:
 
 ~~~~ typescript
-relay.setSubscriptionHandler(async (ctx, actor) => {
-  // Example: Only allow subscriptions from specific domains
-  const domain = new URL(actor.id!).hostname;
-  const allowedDomains = ["mastodon.social", "fosstodon.org"];
-  return allowedDomains.includes(domain);
+const relay = createRelay("mastodon", {
+  kv: new MemoryKvStore(),
+  origin: "https://relay.example.com",
+  subscriptionHandler: async (ctx, actor) => true,  // Accept all
 });
 ~~~~
 
+You can also implement custom approval logic:
+
+~~~~ typescript
+const relay = createRelay("mastodon", {
+  kv: new MemoryKvStore(),
+  origin: "https://relay.example.com",
+  subscriptionHandler: async (ctx, actor) => {
+    // Example: Only allow subscriptions from specific domains
+    const domain = new URL(actor.id!).hostname;
+    const allowedDomains = ["mastodon.social", "fosstodon.org"];
+    return allowedDomains.includes(domain);
+  },
+});
+~~~~
+
+### Managing followers
+
+The relay provides methods to query and manage followers without exposing
+internal storage details.
+
+#### Listing all followers
+
+~~~~ typescript
+for await (const follower of relay.listFollowers()) {
+  console.log(`Follower: ${follower.actorId}`);
+  console.log(`State: ${follower.state}`);
+  console.log(`Actor name: ${follower.actor.name}`);
+  console.log(`Actor type: ${follower.actor.constructor.name}`);
+}
+~~~~
+
+#### Getting a specific follower
+
+~~~~ typescript
+const follower = await relay.getFollower("https://mastodon.example.com/users/alice");
+if (follower) {
+  console.log(`Found follower in state: ${follower.state}`);
+  console.log(`Actor username: ${follower.actor.preferredUsername}`);
+  console.log(`Inbox: ${follower.actor.inboxId?.href}`);
+} else {
+  console.log("Follower not found");
+}
+~~~~
+
 ### Integration with web frameworks
 
 The relay's `fetch()` method returns a standard `Response` object, making it
@@ -131,13 +194,14 @@ example with Hono:
 
 ~~~~ typescript
 import { Hono } from "hono";
-import { MastodonRelay } from "@fedify/relay";
+import { createRelay } from "@fedify/relay";
 import { MemoryKvStore } from "@fedify/fedify";
 
 const app = new Hono();
-const relay = new MastodonRelay({
+const relay = createRelay("mastodon", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
+  origin: "https://relay.example.com",
+  subscriptionHandler: async (ctx, actor) => true,
 });
 
 app.use("*", async (c) => {
@@ -191,38 +255,61 @@ details.
 API reference
 -------------
 
-### `MastodonRelay`
-
-A Mastodon-compatible ActivityPub relay implementation.
+### `createRelay()`
 
-#### Constructor
+Factory function to create a relay instance.
 
 ~~~~ typescript
-new MastodonRelay(options: RelayOptions)
+function createRelay(
+  type: "mastodon" | "litepub",
+  options: RelayOptions
+): Relay
 ~~~~
 
-#### Properties
+**Parameters:**
+
+ -  `type`: The type of relay to create (`"mastodon"` or `"litepub"`)
+ -  `options`: Configuration options for the relay
+
+**Returns:** A `Relay` instance
 
- -  `domain`: The relay's domain name (read-only)
+### `Relay`
+
+Public interface for ActivityPub relay implementations.
 
 #### Methods
 
  -  `fetch(request: Request): Promise<Response>`: Handle incoming HTTP requests
- -  `setSubscriptionHandler(handler: SubscriptionRequestHandler): this`:
-    Set a custom handler for subscription approval/rejection
+ -  `listFollowers(): AsyncIterableIterator<RelayFollower>`: Lists all
+    followers of the relay
+ -  `getFollower(actorId: string): Promise<RelayFollower | null>`: Gets
+    a specific follower by actor ID
+ -  `getActorUri(): Promise<URL>`: Gets the URI of the relay actor
+ -  `getSharedInboxUri(): Promise<URL>`: Gets the shared inbox URI of the relay
+
+#### Relay types
+
+The relay type is specified when calling `createRelay()`:
+
+ -  `"mastodon"`: Mastodon-compatible relay using direct activity forwarding,
+    immediate subscription approval, and LD signatures
+ -  `"litepub"`: LitePub-compatible relay using bidirectional following,
+    activities wrapped in `Announce`, and two-phase subscription
 
 ### `RelayOptions`
 
 Configuration options for the relay:
 
  -  `kv: KvStore` (required): Key–value store for persisting relay data
- -  `domain?: string`: Relay's domain name (defaults to `"localhost"`)
+ -  `origin: string` (required): Relay's origin URL (e.g.,
+    `"https://relay.example.com"`)
+ -  `name?: string`: Relay's display name (defaults to `"ActivityPub Relay"`)
+ -  `subscriptionHandler: SubscriptionRequestHandler` (required): Handler for
+    subscription approval/rejection
  -  `documentLoaderFactory?: DocumentLoaderFactory`: Custom document loader
     factory
  -  `authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory`:
     Custom authenticated document loader factory
- -  `federation?: Federation<void>`: Custom Federation instance (for advanced
-    use cases)
  -  `queue?: MessageQueue`: Message queue for background activity processing
 
 ### `SubscriptionRequestHandler`
@@ -231,21 +318,39 @@ A function that determines whether to approve a subscription request:
 
 ~~~~ typescript
 type SubscriptionRequestHandler = (
-  ctx: Context<void>,
+  ctx: Context<RelayOptions>,
   clientActor: Actor,
 ) => Promise<boolean>
 ~~~~
 
-Parameters:
+**Parameters:**
 
- -  `ctx`: The Fedify context object
+ -  `ctx`: The Fedify context object with relay options
  -  `clientActor`: The actor requesting to subscribe
 
-Returns:
+**Returns:**
 
  -  `true` to approve the subscription
  -  `false` to reject the subscription
 
+### `RelayFollower`
+
+A follower of the relay with validated Actor instance:
+
+~~~~ typescript
+interface RelayFollower {
+  readonly actorId: string;
+  readonly actor: Actor;
+  readonly state: "pending" | "accepted";
+}
+~~~~
+
+**Properties:**
+
+ -  `actorId`: The actor ID (URL) of the follower
+ -  `actor`: The validated Actor object
+ -  `state`: The follower's state (`"pending"` or `"accepted"`)
+
 
 [JSR]: https://jsr.io/@fedify/relay
 [JSR badge]: https://jsr.io/badges/@fedify/relay
@@ -255,3 +360,4 @@ Returns:
 [@fedify@hollo.social]: https://hollo.social/@fedify
 [Fedify]: https://fedify.dev/
 [Fedify documentation on key–value stores]: https://fedify.dev/manual/kv
+[manual]: https://fedify.dev/manual/relay