@fedify/中继:活动Pub中继器用于联邦化
此包自Fedify 2.0.
此软件包提供了活动Pub中继功能 联邦 生态系统,能够创建和管理能够 在联邦机构之间开展前瞻性活动.
关于建立和运作中继服务器的全面文件, 见 中继服务器 《联邦手册》中的章节。 。 。 .
什么是活动接力?
活动Pub中继器是有助于小实例的基础设施组件 参与联邦社会网络 发布公共内容而不需要的中介服务器 个人演员跟踪关系。 当一个实例订阅 中继器,所有来自该案例的公职都转交给所有其他 订阅实例,创建一个共享的联邦内容库.
中继协议
这个软件包支持两个在fediverse中使用的流行接力协议:
马斯通式接力
Mastodon 风格的中继协议使用 LD 签名进行活动 核查并跟踪公共收藏。 这个协议很广泛 由Mastodon和许多其他活动Pub的实施提供支持.
关键特性:
- 带有适当内容类型的直接活动中继(
Create, (中文(简体) ),Update, (中文(简体) ),Delete, (中文(简体) ),Move(中文(简体) ) - LD 签名验证和生成
- 遵循活动Pub 公开收藏
- 通过简单的订阅机制
Follow活动
LitePub 式继电器
LitePub 式接力协议使用双向关系
并覆盖活动 Announce 分发活动.
关键特性:
- 接力和订阅者之间的对接
- 包含的活动
Announce分发 - 分两阶段订阅(待) 已接受)
- 加强联邦能力
安装
* :密码组
deno add jsr:@fedify/relay
npm add @fedify/relay
pnpm add @fedify/relay
yarn add @fedify/relay
bun add @fedify/relay
* :
使用量
创建中继器
以下是使用工厂功能创建中继服务器的简单例子:
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
// Create a Mastodon-style relay
const relay = createRelay("mastodon", {
kv: new MemoryKvStore(),
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));
您也可以通过更改类型来创建 LitePub 式接力 :
const relay = createRelay("litepub", {
kv: new MemoryKvStore(),
origin: "https://relay.example.com",
subscriptionHandler: async (ctx, actor) => true,
});
订阅处理
这个 subscriptionHandler 需要并决定是否批准或
拒绝订阅请求 。 对于接受所有订阅的开放式中继器:
const relay = createRelay("mastodon", {
kv: new MemoryKvStore(),
origin: "https://relay.example.com",
subscriptionHandler: async (ctx, actor) => true, // Accept all
});
也可以执行自定义批准逻辑 :
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);
},
});
管理追随者
中继器提供了查询和管理追随者的方法而不曝光 内部存储细节.
列出所有追随者
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}`);
}
获取特定跟踪器
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");
}
与网络框架的整合
中继器 fetch() 方法返回标准 Response 对象, 制作
兼容任何支持获取 API 的网络框架。 这个
与 Hono 相关的示例 :
import { Hono } from "hono";
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";
const app = new Hono();
const relay = createRelay("mastodon", {
kv: new MemoryKvStore(),
origin: "https://relay.example.com",
subscriptionHandler: async (ctx, actor) => true,
});
app.use("*", async (c) => {
return await relay.fetch(c.req.raw);
});
export default app;
如何运作
中继器由:
- 演员注册:中继器以服务演员的身份呈现于
/users/relay - 订阅:通过发送一个
Follow活动 - 核准:中继器的订阅处理器决定是否
核准订阅
Accept或者说Reject(中文(简体) ) - 转发: 当一个订阅实例发送活动时(
Create, (中文(简体) ),Update, (中文(简体) ),Delete, (中文(简体) ),Move)到继电器的收件箱,继电器转发它们 所有其它订阅实例 - 取消订阅: 实例可以通过发送
Undo活动 包装他们的正本Follow活动
储存要求
中继需要密钥- 值存储持续 :
- 订阅者列表及其后续活动ID
- 订阅者演员信息
- 中继密码密钥对 (RSA和Ed25519)
任意 KvStore 可使用来自联邦的实施工作,包括:
MemoryKvStore(供开发/试验)DenoKvStore(德诺克V)RedisKvStore(雷迪斯语)PostgresKvStore(PostgreSQL) (英语)MysqlKvStore(MySQL/马里亚DB)SqliteKvStore(SQLite) (英语)
对于生产用途,选择像Redis一样的持久存储后端, PostgreSQL,即MySQL/马里亚DB. 见 补充关于关键价值库存的文件 更多细节.
API 参考
createRelay()
工厂功能创建中继实例 .
function createRelay(
type: "mastodon" | "litepub",
options: RelayOptions
): Relay
参数:
type: 要创建的继电器类型 ("mastodon"或者说"litepub"(中文(简体) )options: 中继的配置选项
回返情况: A 类 Relay 实例
Relay
活动Pub中继执行的公共接口.
方法
fetch(request: Request): Promise<Response>: 处理收到的 HTTP 请求listFollowers(): AsyncIterableIterator<RelayFollower>: 列出全部 中继的后继者getFollower(actorId: string): Promise<RelayFollower | null>: 获取 由演员 ID 指定跟踪者getActorUri(): Promise<URL>: 获得接力演员的URIgetSharedInboxUri(): Promise<URL>: 获取中继器共享的收件箱 URI
中继类型
呼叫时指定中继类型 createRelay()数字 :
"mastodon": Mastodon兼容中继器,使用直接活性转发, 立即批准订阅和LD签名"litepub": LitePub 相容继电器,采用双向跟踪, 包含的活动Announce,以及两阶段订阅
RelayOptions
中继的配置选项 :
kv: KvStore(需要):持续中继数据的关键值存储origin: string(要求):Relay的出处URL(例如,,"https://relay.example.com"(中文(简体) )name?: string: 中继显示名( 默认为"ActivityPub Relay"(中文(简体) )subscriptionHandler: SubscriptionRequestHandler(需要): 负责 订阅核准/拒绝documentLoaderFactory?: DocumentLoaderFactory: 自定义文档加载器 工厂authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory数字 : 自定义认证的文件加载厂queue?: MessageQueue: 用于背景活动处理的信件队列
SubscriptionRequestHandler
决定是否批准订阅请求的函数:
type SubscriptionRequestHandler = (
ctx: Context<RelayOptions>,
clientActor: Actor,
) => Promise<boolean>
参数:
ctx: 带有中继选项的上下文对象clientActor: 请求订阅的演员
回返情况:
true核准订阅false拒绝订阅
RelayFollower
中继器的追随者, 具有有效的代理实例 :
interface RelayFollower {
readonly actorId: string;
readonly actor: Actor;
readonly state: "pending" | "accepted";
}
属性 :
actorId:追随者的演员ID(URL)actor: 经验证的演员对象state:后人所领之州"pending"或者说"accepted"(中文(简体) )