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

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

> **Social**（好友、群、通讯录）已独立文档，见 [`/docs/social`](../social/README.md)。  
> **开源通讯核心**快速接入见 [`/docs/core`](../core/README.md)。

## 这一层完全开源

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

| 你要写的东西 | 契约在哪 | 仓库 |
| --- | --- | --- |
| 消息链路上的拦截与改写 | `flare-im-hooks` 的 8 个 Hook trait | flare-im-core（开源） |
| 显式调用的业务扩展 | `ExtensionPlugin.Call` gRPC 服务 | flare-grpc-proto（开源） |
| 插件的注册与授权声明 | `PluginDeclaration` / `PluginHost` | flare-plugin-host（开源） |
| 客户端侧扩展与拦截器 | `SdkExtension` / `MessageInterceptor` | flare-im-core-sdk（开源） |

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

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

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

## 从一个能跑的插件开始

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

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

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

```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](../sdk/README.md)

## 文档索引

| 文档 | 内容 |
|------|------|
| [01-architecture.md](./01-architecture.md) | Core / Capability 分层与集成原则 |
| [02-hook-plugin.md](./02-hook-plugin.md) | HookPlugin 契约、PreSend 流程 |
| [03-extension-plugin.md](./03-extension-plugin.md) | ExtensionPlugin、operation 命名 |
| [04-social-integration.md](./04-social-integration.md) | **已迁移** → [/docs/social](../social/README.md) |
| [05-deployment-modes.md](./05-deployment-modes.md) | Hook 远程 / 进程内等部署模式 |
| [06-quickstart.md](./06-quickstart.md) | Hook 本地验证清单 |
| [07-core-extension-points-api.md](./07-core-extension-points-api.md) | Core 全部业务扩展点 |
| [10-business-instrumentation.md](./10-business-instrumentation.md) | 埋点、事件模型与非侵入扩展 |

## 配置样例

- `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`](./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`。