Flare IM — 业务扩展（Hook / Extension）

本目录描述 如何在不开 fork flare-im-core 的前提下 接入风控、审计、运营等业务能力。

Social（好友、群、通讯录）已独立文档，见 /docs/social。
开源通讯核心快速接入见 /docs/core。

这一层完全开源

Hook 与 Extension 的契约、宿主实现、配置与部署方式全部在开源仓里， 你可以自由实现自己的插件，不需要任何授权，也不必 fork 核心：

插件跑在你自己的进程里，通过 gRPC 与核心通信——所以用什么语言写、怎么部署、 怎么升级，都由你决定；核心不会因为你加了插件而需要重新编译。

要动手写一个，直接看 12 — 自己开发一个插件： 那篇从零走完注册、声明边界、计费单位、健康检查与优雅停机，并列出每个常见坑 对应的确切症状。

暂未开放的部分：客户端插件的打包清单与分发目录（plugin manifest / catalog） 目前不在开源仓内。也就是说，你现在可以自由实现并部署插件，但还没有一个 公共的插件市场来分发它们。这一层的形态还在打磨，不想先给出一个日后要改的契约。

从一个能跑的插件开始

仓里有一个完整可运行的样例：发送频率限制。它是独立进程、用 gRPC 接核心， 演示了 PreSend 最关键的语义——拒绝。

cd flare-im-core
cargo run --example hook_rate_limit          # 默认监听 127.0.0.1:7801

然后把它挂到核心（config/hooks.toml）：

[[pre_send]]
name = "rate-limit"
priority = 10
timeout_ms = 200
require_success = true      # 插件不可用时拒发；改 false 则放行

[pre_send.transport]
type = "grpc"
endpoint = "http://127.0.0.1:7801"

窗口与阈值走环境变量（HOOK_RATE_LIMIT_MAX / HOOK_RATE_LIMIT_WINDOW_SECS）， 不用改代码就能试。

写自己的插件时，这几处直接照抄：operation 的命名是 flare.hook.v1.<hook 名>； 请求响应都装在 Any 里按 type_url 解包；放行时必须原样回传 draft （不回传等于把消息内容清空）；不认识的 operation 要放行——否则核心将来新增 hook 点时，你的插件会在升级当天把所有消息挡下来。

读者

• 平台架构师：扩展点边界、部署模式
• 业务后端：HookPlugin / ExtensionPlugin 实现
• 客户端：见 flare-proto 与 /docs/sdk

文档索引

配置样例

• flare-im-core/config/hooks.example.toml — 通用 Hook（仓库根 flare-im-core/config/）
• flare-im-core/config/hooks.social.example.toml — Social PreSend
• 本目录 hooks.social.example.toml — 与上者相同，便于官网单目录分发

核心原则（摘要）

1. flare-im-core 不依赖任何业务 crate（含 flare-social）。
2. 业务通过 HookPlugin（生命周期）与 ExtensionPlugin（命令/查询型扩展）接入。
3. Social 为独立微服务集群，可用 Rust / Java / Go 实现，只要实现 gRPC 契约。
4. flare-api-gateway 只做 HTTP/gRPC 边界适配，认证、错误与返回格式规范见 flare-im-core/flare-api-gateway/GATEWAY_SPEC.md。