Macro unfurl crate 深度解析:六边形架构下的链接预览与 SSRF 防护实现
Macro unfurl crate 深度解析:六边形架构下的链接预览与 SSRF 防护实现
crates/unfurl 是 Macro 中所有“链接预览”(link preview)能力的共享基础设施:它把任意 URL 抓取为标题、描述、预览图与 favicon,并以严格的 SSRF 防护约束所有出站请求。本文以该 crate 的维护者文档 crates/unfurl/AGENTS.md 为主线,逐层拆解它的架构分层、端口契约、抓取实现与安全边界,并结合 services/unfurl_service 与 crates/crm/src/outbound/unfurl_resolver.rs 说明它在真实调用链中的装配方式,帮助你既能读懂现有实现,也能安全地在其上扩展。
一、这个 crate 到底是什么
AGENTS.md 的开篇给出了最精确的定位:“Shared infrastructure for link previews, used by email and CRM — a hex crate for URL unfurling: fetches a URL's meta tags (title, description, image, favicon) with SSRF protections.”
拆开来看有三层含义:
- 共享基础设施:它不是某个服务私有的工具函数,而是被多个上层消费者复用的库。文档明确标注的消费者是
services/unfurl_service、services/email_service与crates/crm(见 crates/unfurl/Cargo.toml 中的依赖方向)。 - hex crate(六边形架构):领域逻辑不依赖任何 I/O 框架,HTTP 抓取、HTTP 路由都作为可替换的适配器挂在端口上,见 crates/unfurl/src/lib.rs。
- 带 SSRF 防护的抓取:因为输入 URL 完全来自用户(粘贴的链接、邮件正文、CRM 域名),抓取这一动作天然是攻击面,防护是本 crate 的一等公民而非附属功能。
职责边界(Scope)
文档把“Owns”和“Not here”划得很硬:
| 分类 | 内容 |
|---|---|
| 拥有 | 抓取并解析一个 URL 的 unfurl 元数据 |
| 不负责 | 在 UI 中渲染 unfurl 卡片 |
| 不负责 | 长期缓存 unfurl 结果 |
| 依赖 | scraper、reqwest(仅 outbound feature) |
| 被使用 | services/unfurl_service、services/email_service、crates/crm |
这条边界很关键:缓存与渲染被刻意排除,所以你在本 crate 里找不到 TTL、Redis、数据库表;CRUD 与持久化属于调用方。这也解释了为什么 unfurl_service 里还保留了一套 bulk / proxy 路由——那是服务层的职责,而不是 crate 的职责。
从哪读起
AGENTS.md 给出了四个入口,顺序本身就是一条阅读路径:
src/domain/service.rs— unfurl 工作流;src/outbound/http_safety.rs— URL 校验与私有 IP 拦截,改动任何出站抓取路径前必读;src/outbound/reqwest_fetcher.rs— 真实 HTTP 抓取器;src/inbound/axum_router.rs(axumfeature)— HTTP 路由。
二、六边形分层与 feature 组合
lib.rs 的文档注释把三层职责写得很清楚:
#![deny(missing_docs)]
//! - `domain` — pure models, ports, and service logic (no I/O deps).
//! - `inbound` — HTTP / tool adapters that drive the domain.
//! - `outbound` — concrete adapters the domain drives (e.g. the reqwest-backed
//! meta-tag fetcher).
pub mod domain;
#[cfg(feature = "inbound")]
pub mod inbound;
#[cfg(feature = "outbound")]
pub mod outbound;
注意 #![deny(missing_docs)]:这是一个强制文档化的 crate,任何新增的公开项都必须写文档,否则编译失败。这既是质量约束,也解释了源码中密集的 doc comment 风格。
feature 拓扑
Cargo.toml 中的 feature 并不是随意开关,而是有依赖关系:
| feature | 含义 | 传递依赖 |
|---|---|---|
ports |
只启用端口与服务层(domain::ports、domain::service) |
无 |
inbound |
启用入站适配器层 | ports |
outbound |
启用真实 HTTP 抓取器 | ports + bytes、futures、reqwest、scraper、tokio |
axum |
启用 HTTP 路由适配器 | inbound + axum、utoipa |
all |
全开 | axum、inbound、outbound、ports |
这套设计的实际收益体现在下游依赖上:crates/crm/Cargo.toml 只引入 features = ["ports"],因此 CRM 可以只依赖端口 trait 与领域模型,而不把 reqwest / scraper / axum 拉进自己的编译图;services/email_service 引入 features = ["outbound"],因为它需要自己构造抓取器;只有 services/unfurl_service 同时开 axum + outbound,因为它既暴露 HTTP 又执行真实抓取。
domain.rs 的模块门控印证了这一点:
pub mod favicon;
pub mod models;
pub mod url_parsers;
#[cfg(feature = "ports")]
pub mod ports;
#[cfg(feature = "ports")]
pub mod service;
也就是说 favicon、models、url_parsers 是永远可用的纯逻辑(无 I/O、无网络依赖),这也是 CRM 只开 ports 就能复用标题解析与模型的原因。
三、核心工作流:三步组成一条 unfurl
domain/service.rs 是整个 crate 的心脏,实现短到可以一眼看完,但每一步都对应一个明确职责:
#[tracing::instrument(err(level = Level::DEBUG), skip(self))]
async fn unfurl(&self, url: &str) -> Result<GetUnfurlResponse, UnfurlErr> {
let tags = self
.fetcher
.fetch_meta_tags(url)
.await
.map_err(|e| UnfurlErr::Fetch(e.into()))?;
let tags = append_optimistic_favico(tags, url);
Ok(GetUnfurlResponse::new(url, &tags))
}
三步分别是:
- 抓取:委托给
UnfurlFetcher端口,得到扁平的HashMap<String, String>元标签表; - 补全 favicon:页面若未声明图标,用
scheme://host[:port]/favicon.ico兜底; - 建模:把元标签表装配成结构化的
GetUnfurlResponse。
UnfurlServiceImpl<F> 是泛型参数化的,F: UnfurlFetcher,构造器 new(fetcher) 只保存一个字段。这种写法的好处是:领域服务不持有具体 HTTP 客户端,测试中直接注入 MockUnfurlFetcher 即可,无需网络。仓库里的两个单测就是最好的证明:
unfurl_returns_response_built_from_fetcher_tags:mock 返回property:og:title/property:og:description,断言最终favicon_url被乐观补全为https://example.com/favicon.ico;unfurl_surfaces_fetcher_errors:mock 返回错误,断言错误被包装成UnfurlErr::Fetch。
还有一个容易被忽略的类型约束:
impl<F> UnfurlService for UnfurlServiceImpl<F>
where
F: UnfurlFetcher,
anyhow::Error: From<F::Err>,
即适配器的错误类型必须能转成 anyhow::Error。这使得错误传播统一收口,调用方只需处理一种错误枚举。日志侧使用 #[tracing::instrument(err(level = Level::DEBUG))]——抓取失败是预期内的业务事件(链接失效、站点拒绝爬虫),因此只记 DEBUG,避免生产日志被无效链接淹没。
四、端口契约:UnfurlFetcher 与 UnfurlService
domain/ports.rs 只定义了两个 trait,一进一出:
#[cfg_attr(test, mockall::automock(type Err = anyhow::Error;))]
pub trait UnfurlFetcher: Send + Sync + 'static {
type Err: Send;
fn fetch_meta_tags(
&self,
url: &str,
) -> impl Future<Output = Result<HashMap<String, String>, Self::Err>> + Send;
}
pub trait UnfurlService: Send + Sync + 'static {
fn unfurl(
&self,
url: &str,
) -> impl Future<Output = Result<GetUnfurlResponse, UnfurlErr>> + Send;
}
几个设计要点:
- 使用
impl Future而非async fnin trait:trait 中返回impl Future + Send,既保留 RPITIT 的零分配优势,又显式约束Send,让实现可以安全放进tokio::spawn。 Send + Sync + 'static:因为服务会被Arc包进 axum 的 router state(见后文UnfurlRouterState),必须能在多线程执行器间共享。#[cfg_attr(test, mockall::automock(...))]:仅在测试构建下生成MockUnfurlFetcher,生产二进制不引入 mockall(它只是dev-dependencies)。
键名约定是隐性契约——fetch_meta_tags 的文档明确要求键格式为 property:og:title、property:og:description、property:og:image、title、favicon。任何自定义 fetcher 实现都必须遵守这套命名,否则 get_title 会静默降级到 URL 兜底值。
五、响应模型与标题优先级
GetUnfurlResponse 是跨服务的事实标准数据结构:
| 字段 | 类型 | 来源 | 序列化行为 |
|---|---|---|---|
url |
String |
入参原样 | 总是输出 |
title |
String |
自定义解析器 → og:title → og:site_name → <title> → URL 本身 |
总是输出 |
description |
Option<String> |
property:og:description |
None 时省略 |
image_url |
Option<String> |
property:og:image |
None 时省略 |
favicon_url |
Option<String> |
favicon 键,并相对页面 URL 解析为绝对地址 |
None 时省略 |
embed_type |
UnfurlEmbedType |
由 parse_embed_info 判定 |
None 变体时省略 |
embed_url |
Option<String> |
Loom / Supercut 的 iframe 地址 | None 时省略 |
skip_serializing_if 的组合效果是:一个只有标题的页面返回极简 JSON,不会出现一串 null;而 embed_type 有专门谓词 is_embed_type_none,保证 None 变体也不参与序列化。
标题解析的顺序在 get_title 中写死,且自定义解析器优先:
if let Some(custom_title) = parse_custom_title(url) {
return custom_title;
}
let properties = ["property:og:title", "property:og:site_name", "title"];
let title = properties.iter().find_map(|p| metatags.get(*p));
match title {
Some(s) => s.to_string(),
None => url.to_string(),
}
文档给出的理由是:某些服务把标题编码进 URL,却渲染通用 HTML 标题(典型如 Notion、Figma、Linear),走元标签会得到无用结果。最后的 None => url.to_string() 兜底意味着**GetUnfurlResponse.title 永远非空**——这一点直接影响下游行为,CRM 适配器专门处理了“标题等于 URL”的情形(见第十一节)。
GetUnfurlResponseList = Vec<Option<GetUnfurlResponse>> 则是批量场景的类型别名:下标对齐请求列表,None 表示该条失败,而不是整批失败。
六、自定义 URL 解析器:把标题从路径里“挖”出来
domain/url_parsers.rs 承担了两件事:从 URL 结构推断标题、为视频服务生成 iframe 地址。
子域名安全校验
所有解析器共用同一个前置判断:
fn is_valid_provider_host(host: &str, provider_domain: &str) -> bool {
host == provider_domain || host.ends_with(&format!(".{}", provider_domain))
}
它拒绝 loom.com.evil.example、fake-loom.com 这类仿冒域名(测试 test_hostname_validation_rejects_lookalikes 覆盖了这四种攻击形态),但允许 app.loom.com 这类合法子域。这是字符串后缀匹配而非子串匹配,前缀的 . 是关键。
各服务支持矩阵
| 服务 | 识别模式 | 提取规则 | 解析失败兜底 |
|---|---|---|---|
| Notion | notion.so/[workspace]/Title-With-Dashes-uuid |
取最后一个长度 > 32 且末尾 32 位为十六进制的路径段,截掉 - + 32 位 UUID,将 - 转空格并逐词首字母大写 |
"Notion" |
| Figma | figma.com/design/[file-id]/[title] |
segments.len() >= 3 && segments[0] == "design" 时取 segments[2] |
"Figma" |
| Linear | linear.app/[team]/issue/[ticket-id]/[title] |
segments.len() >= 4 && segments[1] == "issue" 时取 segments[3] |
"Linear" |
| Supercut | supercut.ai/share/[workspace]/[video-id] |
生成 https://supercut.ai/embed/{workspace}/{video_id} |
"Supercut" |
| Loom | loom.com/share/[video-id] |
生成 https://www.loom.com/embed/{video_id} |
"Loom" |
Notion 的截断逻辑值得单独看,因为它解释了 -33 这个魔法数字:
if title_segment.len() > 33 {
let title_part = &title_segment[..title_segment.len() - 33];
let title = title_part.replace('-', " ");
32 位 UUID + 1 个连字符 = 33。少于等于 33 字符说明这段只有 UUID 没有标题,直接放弃并回落到服务名。capitalize_first 只处理每个词的首字符大写,其余字符保持原样——所以 AI-side-panel 变成 AI Side Panel,而不会破坏已有的缩写大小写(测试 test_figma_title_parsing 与 test_linear_title_parsing 都断言了这一点)。
embed 的两级派发
pub fn parse_embed_info(url: &str) -> Option<EmbedInfo> {
if let Some(info) = parse_supercut_embed(url) {
return Some(info);
}
if let Some(info) = parse_loom_embed(url) {
return Some(info);
}
None
}
EmbedType 目前只有 Video 一个变体,UnfurlEmbedType 通过 From<EmbedType> 转换并额外拥有 None 变体(#[default])。这种“领域枚举 + 可序列化枚举”的分离让 url_parsers 保持 serde 无依赖,而 API 层仍能稳定输出 "Video" 字符串。
文档 services/unfurl_service/CUSTOM_PARSERS.md 给出了完整示例与函数层级树,其中也指出前端收到 embed_type: "Video" 时会在 LinkHoverCard 中渲染 iframe 播放器——渲染不在本 crate 内,符合 AGENTS.md 的职责边界。
七、SSRF 防护:本 crate 的安全地基
AGENTS.md 中带强烈措辞的那一条值得原文引用:
src/outbound/http_safety.rs: URL validation and private-IP blocking — read before touching any outbound fetch path, it's what keeps this crate from being an SSRF vector against the internal network.
http_safety.rs 的模块注释也明确:“These keep the unfurl service from being abused as a server-side request forgery vector against the internal network.” 这里的防护是分层叠加的,而不是单点校验。
7.1 错误类型即攻击面清单
FetchError 的每个变体都对应一类可被利用或可利用性需被观测的异常:
| 变体 | 触发条件 | 安全含义 |
|---|---|---|
InvalidUrl(String) |
Url::parse 失败 |
畸形输入 |
InvalidScheme |
scheme 不是 http/https |
阻断 file://、gopher:// 等 |
MissingHost |
无 host | 相对形式/非法形式 |
DnsLookupFailed |
DNS 解析失败 | 不可控域名 |
PrivateIp |
解析到私有/内部地址 | 核心 SSRF 拦截点 |
UpstreamTimeout |
请求超时 | 慢速攻击防护 |
UpstreamConnect |
连接失败 | 端口探测迹象 |
UpstreamRedirect |
重定向异常或超限 | 重定向绕过 |
UpstreamNetwork |
其他网络错误 | 兜底归类 |
UpstreamStatus(StatusCode) |
非 2xx | 上游拒绝 |
UnexpectedContentType |
非 HTML | 阻断拉取二进制/大文件 |
ResponseTooLarge { content_length, max } |
超过体积上限 | 内存耗尽防护 |
ResponseRead(String) |
body 流读取失败/非 UTF-8 | 传输层异常 |
这些枚举不是简单字符串,ResponseTooLarge 同时携带实际 content_length 与配置上限 max,便于日志与告警精确定位;send_request 还会用 build_error_chain 把 reqwest::Error 的 source() 链逐层拼成 \nCaused by: ...,避免只看到最外层“error sending request”而无从排查。
7.2 校验三步:scheme、host、IP
第一步,validate_url:解析成功后只允许 http / https,并剥离 fragment:
pub(super) fn validate_url(raw_url: &str) -> Result<Url, FetchError> {
let mut url = Url::parse(raw_url).map_err(|e| FetchError::InvalidUrl(e.to_string()))?;
if url.scheme() != "http" && url.scheme() != "https" {
return Err(FetchError::InvalidScheme);
}
url.set_fragment(None);
Ok(url)
}
剥离 fragment 有两个作用:同一 URL 的 #anchor 变体不会产生不同的抓取结果,也让后续的 URL 比较(如 CRM 里 title == url 的判等)更稳定。
第二步,assert_not_internal:这是 preflight 拦截。它用 url.port_or_known_default().unwrap_or(80) 得到端口,然后对 format!("{host}:{port}") 做 tokio::net::lookup_host:
for addr in addrs {
if is_private_ip(&addr.ip()) {
tracing::warn!(host, ip = %addr.ip(), "blocked request to private/internal IP");
return Err(FetchError::PrivateIp);
}
}
注意语义是任一地址私有即拒绝(fail-closed),而不是“只要有一个公网地址就放行”。对于返回多个 A 记录的域名,这堵死了“混入一个内网 IP”的绕过手法。
第三步,is_private_ip:判定矩阵覆盖了 IPv4 与 IPv6 两套私有空间,并处理了 IPv4-mapped IPv6:
IpAddr::V6(v6) => {
if let Some(mapped_v4) = v6.to_ipv4_mapped() {
return is_private_ip(&IpAddr::V4(mapped_v4));
}
v6.is_loopback()
|| v6.is_unspecified()
|| v6.is_unique_local() // fc00::/7
|| v6.is_unicast_link_local() // fe80::/10
}
| 地址族 | 拦截范围 | 说明 |
|---|---|---|
| IPv4 | loopback / private / link-local / unspecified / broadcast | 127/8、10/8、172.16/12、192.168/16、169.254/16、0.0.0.0、255.255.255.255 |
| IPv6 | loopback / unspecified / unique-local / unicast link-local | ::1、::、fc00::/7(RFC1918 等价物)、fe80::/10 |
| IPv4-mapped IPv6 | 递归委托给 IPv4 判定 | ::ffff:10.0.0.1 等价于 10.0.0.1 |
这一点被测试逐条钉死:ipv6_mapped_v4_loopback_is_blocked、ipv6_unique_local_is_blocked、ipv6_link_local_is_blocked,同时 ipv6_public_is_allowed / ipv4_public_is_allowed 保证不过度拦截(Google DNS 2001:4860:4860::8888 与 8.8.8.8 必须放行)。
7.3 重定向:为什么必须关掉 reqwest 的自动跟随
redirect_target 的文档注释是整份代码里最重要的安全说明之一:
Does not check the target's IPs — the caller must run [
assert_not_internal] on the returned URL before issuing the next request, so a 302 → internal-IP cannot bypass the preflight.
如果让 reqwest 自动跟随重定向,preflight 只作用于原始 URL,攻击者可以构造“公网 URL → 302 到 http://169.254.169.254/(云元数据地址)”完成绕过。因此:
send_request刻意不检查响应状态,把 3xx 交给调用方处理:
/// Issue a GET against `url`. The response is returned without inspecting its
/// status — the caller decides how to handle 3xx (redirect-follow) vs 4xx /
/// 5xx (error). This is intentional: the redirect loop in
/// `reqwest_fetcher::extract_meta_tags` needs to see 3xx responses so it can
/// run [`assert_not_internal`] against each hop before following.
redirect_target只负责把Location相对解析成绝对地址,并重复 scheme 校验与 fragment 剥离——与validate_url同样的卫生标准,防止重定向目标降级为file://。
reqwest_fetcher 的客户端构造因此显式禁用自动重定向,并接上自定义 DNS 解析器:
let client = reqwest::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.dns_resolver(Arc::new(PrivateIpFilteringResolver))
.timeout(REQUEST_TIMEOUT)
.connect_timeout(CONNECT_TIMEOUT)
.build()?;
ReqwestUnfurlFetcher::new() 的文档把这一设计意图写得很明白:让客户端构造与 fetcher 类型不可分割,“callers can't accidentally hand in a redirect-following or unfiltered client”。这是一个利用类型系统封堵误用的典型例子——没有暴露“传入你自己的 client”的构造器。
7.4 DNS rebinding:TOCTOU 窗口的关闭
outbound/resolver.rs 解决的是 preflight 与实际连接之间的时间差问题。模块注释描述得很精确:preflight 时解析一次,reqwest 建连时又解析一次;控制权威 DNS 的攻击者可以让第一次返回公网 IP、第二次返回内网 IP。PrivateIpFilteringResolver 把同一套 is_private_ip 过滤器插进 ClientBuilder::dns_resolver,在 reqwest 即将连接的瞬间再过滤一次:
let filtered: Vec<SocketAddr> = lookup
.filter(|sa| !is_private_ip(&sa.ip()))
.collect();
if filtered.is_empty() {
return Err(Box::new(std::io::Error::new(
std::io::ErrorKind::PermissionDenied,
format!("all resolved IPs for {hostname} are private/internal; refusing to connect"),
)) /* ... */);
}
两个细节值得注意:
- 解析时用
format!("{hostname}:0"),端口占位为0——注释解释了端口对解析无意义,reqwest 会在连接前用 URL 的端口覆盖; - 过滤后为空时返回
PermissionDenied,而不是静默返回空集,避免上层把“无可用地址”误判为瞬时故障无限重试。
于是防护形成双保险:preflight 的 assert_not_internal(逐跳)+ 连接期的 resolver 过滤(防 rebinding)。文档中“Any change to URL validation or redirect handling must keep private/loopback IPs blocked”这条 Gotcha,保护的正是这两处。
7.5 内容类型与体积
抓 HTML 时还有两道闸:
fn is_html_content_type(content_type: &str) -> bool {
let primary = content_type
.split(';')
.next()
.unwrap_or(content_type)
.trim()
.to_ascii_lowercase();
primary == "text/html" || primary == "application/xhtml+xml"
}
先按 ; 切掉 charset 参数再比较,因此 text/html; charset=utf-8 能通过;image/png、application/json 被拒绝,对应 UnexpectedContentType。content_type_of 在缺失头时默认 application/octet-stream,同样会被拒——缺失即不可信。
体积控制有两道:check_content_length 依据声明的 Content-Length 提前拒绝;read_body_capped 在流式读取中逐 chunk 累加,超过 MAX_HTML_SIZE 立即中断。后者是必需的,因为 Content-Length 可以缺失或撒谎(chunked 编码),仅靠头部检查会被绕过:
if (buf.len() as u64) + (chunk.len() as u64) > max {
return Err(UnfurlFetchError::Fetch(FetchError::ResponseTooLarge {
content_length: (buf.len() as u64) + (chunk.len() as u64),
max,
}));
}
读取完成后还要求 String::from_utf8 成功,否则报 ResponseRead — 这一步同时把“非 UTF-8 页面”变成显式错误,而不是产出乱码标题。
7.6 关键常量一览
| 常量 | 值 | 位置 | 作用 |
|---|---|---|---|
MAX_HTML_SIZE |
1024 * 1024(1 MB) |
crates/unfurl/src/outbound/reqwest_fetcher.rs | HTML 体积硬上限 |
MAX_REDIRECTS |
5 |
同上 | 手动重定向跳数上限,注释说明与原 Policy::limited(5) 行为对齐 |
REQUEST_TIMEOUT |
8s |
同上 | 整请求超时 |
CONNECT_TIMEOUT |
3s |
同上 | 建连超时 |
BULK_CONCURRENCY |
16 |
services/unfurl_service/src/unfurl.rs | 批量抓取的并发上限 |
MAX_RESPONSE_SIZE |
2 * 1024 * 1024(2 MB) |
services/unfurl_service/src/api/proxy.rs | 图片代理体积上限 |
MAX_REDIRECTS 也解释了循环的写法:redirects_remaining 从 5 递减,归零时返回带明确数字的错误信息 "exceeded maximum of {MAX_REDIRECTS} redirects"。
八、fetcher 实现:抓取循环的完整形态
extract_meta_tags 是 crate 内唯一发起真实网络请求的函数,结构上是一个 loop:
let mut url = validate_url(raw_url)?;
let mut redirects_remaining = MAX_REDIRECTS;
let response = loop {
assert_not_internal(&url).await?; // 每跳都做 preflight
let response = send_request(client, &url).await?;
let status = response.status();
if status.is_redirection() {
if redirects_remaining == 0 { /* UpstreamRedirect */ }
let next = redirect_target(&url, &response)?;
tracing::debug!(from = %url, to = %next, "following redirect");
redirects_remaining -= 1;
url = next;
continue;
}
if !status.is_success() {
return Err(FetchError::UpstreamStatus(status).into());
}
break response;
};
关键顺序:先 assert_not_internal,再发请求。在 continue 之后的新一轮迭代里,新 URL 会重新经过 preflight,因此“302 到内网”在发出第二个请求之前就被拦下。
拿到 2xx 响应后依次做:content-type 白名单 → Content-Length 上限 → 流式读取带截断 → UTF-8 校验 → HTML 解析。
解析产出的键值表
parse_document 用 scraper 的选择器抽取三类信息:
for element in document.select(&meta_selector) {
if let Some(name) = element.value().attr("name")
&& let Some(content) = element.value().attr("content")
{
meta_tags.insert(format!("name:{name}"), content.to_string());
}
if let Some(property) = element.value().attr("property")
&& let Some(content) = element.value().attr("content")
{
meta_tags.insert(format!("property:{property}"), content.to_string());
}
}
name="description"→ 键name:descriptionproperty="og:title"→ 键property:og:title<title>的inner_html()→ 键title(用inner_html而非text(),保留内部实体的原始形态)<link rel="icon">→ 键favicon
find_favicon 的 rel 判定用了 contains("icon") 的子串匹配,因此 rel="shortcut icon"、rel="apple-touch-icon" 也能命中;拿到 href 后尝试 base_url.join(href) 转绝对地址,join 失败则原样返回(视为已是绝对地址)。注意它返回第一个匹配项即停止,不做优先级排序。
必须强调:正文里的 og:* 与 <title> 都是不可信输入,可能超长、可能含控制字符。crate 只做结构化抽取,不做清洗——这是有意的职责切分,展示层负责转义。
九、favicon 兜底:一个 10 行的策略函数
domain/favicon.rs 提供两个函数:
pub fn favico_url(url: &str) -> Result<String, anyhow::Error> {
let url = Url::parse(url).map_err(|e| anyhow::anyhow!("failed to parse url: {e}"))?;
let host = url.host().ok_or_else(|| anyhow::anyhow!("no host"))?;
let scheme = url.scheme();
let port = url.port().map(|port| format!(":{port}")).unwrap_or_default();
Ok(format!("{scheme}://{host}{port}/favicon.ico"))
}
注意 url.port() 只返回显式书写的端口,默认端口不会出现,所以 https://example.com/a/b?c=d 得到的是 https://example.com/favicon.ico,不会带 :443。
append_optimistic_favico 的语义是只补不覆盖:
if !meta_tags.contains_key("favicon")
&& let Ok(url) = optimistic_url
{
meta_tags.insert("favicon".to_string(), url);
}
“optimistic”这个词很准确:这个 URL 可能 404,但多数站点确实把图标放在根路径。解析失败时通过 inspect_err 记一条 DEBUG,不影响主流程——favicon 属于锦上添花,绝不能让它导致整个 unfurl 失败。
GetUnfurlResponse::new 还会再做一次绝对化,因为解析器给出的可能是站点根相对路径:
if let Ok(base_url) = Url::parse(url)
&& let Some(furl) = favicon_url.as_deref()
&& let Ok(joined) = base_url.join(furl)
{
favicon_url = Some(joined.to_string());
}
十、axum 入站适配器:一个 200 与一个 500
inbound/axum_router.rs 把领域服务暴露为 HTTP。state 用 Arc<T> 包装以获得廉价 Clone:
pub struct UnfurlRouterState<T> {
inner: Arc<T>,
}
路由只挂一个 /,由消费方决定挂载前缀:
pub fn unfurl_router<S, T>(state: UnfurlRouterState<T>) -> Router<S>
where
S: Send + Sync + 'static,
T: UnfurlService,
{
Router::new()
.route("/", get(get_unfurl_handler::<T>))
.with_state(state)
}
handler 的错误契约用返回类型本身表达:
) -> (StatusCode, Json<Option<GetUnfurlResponse>>)
where
T: UnfurlService,
{
match state.inner.unfurl(¶ms.url).await {
Ok(response) => (StatusCode::OK, Json(Some(response))),
Err(e) => {
tracing::warn!(error = %e, url = %params.url, "unfurl failed");
(StatusCode::INTERNAL_SERVER_ERROR, Json(None))
}
}
}
文档注释解释了为什么是 Option 而不是 Result:让 OpenAPI 契约与函数签名一致。#[utoipa::path] 中显式声明了两个响应:200 返回 GetUnfurlResponse,500 返回 Option<GetUnfurlResponse> 且 body 为 JSON null。
这里有一个值得注意的设计权衡:所有错误都被折叠成 500,FetchError 的细分状态码(403、504、422 等)在 crate 的 router 中不体现。原因在于本 crate 的 FetchError 是 pub(super) 的私有类型,领域层只暴露 UnfurlErr::Fetch。如果需要细粒度状态码,那是服务层自有实现的职责——services/unfurl_service/src/http_safety.rs 就为 FetchError 实现了 IntoResponse 映射(PrivateIp → 403、UpstreamTimeout → 504、UnexpectedContentType → 415、ResponseTooLarge → 422)。
十一、真实装配:unfurl_service 如何组合这个 crate
services/unfurl_service/src/main.rs 展示了标准装配流程:
let unfurl_fetcher =
ReqwestUnfurlFetcher::new().context("failed to build unfurl http client")?;
let unfurl_state = UnfurlRouterState::new(UnfurlServiceImpl::new(unfurl_fetcher));
api::setup_and_serve(state, unfurl_state, config.port).await?;
注释说明了为什么 fetcher 自己持有 client:“a 302 → internal IP must not be followed past the assert_not_internal preflight on the original URL.” 同一服务里另外还有一个 SsrfSafeHttpClient 供旧的 bulk / proxy 路由使用——两套客户端的差异只有在“谁负责重定向循环”上,防护要素(禁自动重定向 + 私有 IP 过滤 resolver + 超时)完全一致。
路由树与挂载点
api_router 把两个子路由 nest 进去:
Router::new()
.nest("/unfurl", unfurl::router(unfurl_state))
.nest("/proxy", proxy::router())
而 app_router 做了双挂载:
Router::new().merge(inner.clone()).nest("/unfurl", inner)
效果是同一批路由在根路径与 /unfurl 前缀下都可达,测试 test_gateway_prefixed_unfurl_path_is_reachable 与 test_health_is_served_at_root_and_gateway_prefix 专门验证了 /unfurl/unfurl、/health、/unfurl/health 三种形态。这类双挂载通常是为了兼容网关前缀重写,属于部署细节,但对调试很有用:本地既能 curl /unfurl?url=...,也能 curl /unfurl/unfurl?url=...。
| 端点 | 方法 | 说明 |
|---|---|---|
/unfurl(及 /unfurl/unfurl) |
GET | crate 提供的单条 unfurl,query 参数 url |
/unfurl/bulk |
POST | 服务自有批量接口,body 为 {"url_list": [...]} |
/proxy |
GET | 图片代理,query 参数 url,2 MB 上限 |
/health、/unfurl/health |
GET | 返回纯文本 healthy |
/docs、/unfurl/docs |
GET | Swagger UI,OpenAPI 在 /api-doc/openapi.json |
批量接口用 buffered(BULK_CONCURRENCY) 保持并发但有界、结果保序,失败项填 None 而不整体失败:
futures::stream::iter(links.iter().cloned())
.map(|url| async move { /* ... */ Some(resp) / None })
.buffered(BULK_CONCURRENCY)
.collect()
buffered 与 buffer_unordered 的差别正在于前者保序——这与 GetUnfurlResponseList “下标对齐请求”的约定必须一致。
图片代理的头部处理是另一处安全细节:请求方向只转发 accept、accept-language、user-agent 三个头(避免把 Cookie / Authorization 泄露给第三方),响应方向只回传 cache-control、content-encoding、content-language、content-type、etag、expires、last-modified,并强制加上 Cross-Origin-Resource-Policy: cross-origin 与 X-Content-Type-Options: nosniff。
运行与验证命令
来自 services/unfurl_service/README.md 与 services/unfurl_service/justfile:
# 启动服务(默认端口 8080)
just run
# 单条 unfurl
just unfurl https://macro.com
# 批量(读取 data/lots_of_links.json)
just bulk-link-test
# 跑测试(启用 mock feature,不触网)
just test
# 容器
just docker-build
just docker-run
justfile 首行是 export SQLX_OFFLINE := "true",因为服务层带数据库相关依赖;而 crate 自身的检查则按 AGENTS.md 的要求在不设置 SQLX_OFFLINE 的前提下执行:
cargo test -p unfurl
mock feature 提供了离线行为:extract_meta_tags 在 cfg!(feature = "mock") 时走 extract_meta_tags_mock,对 https://hello.com 与 https://example.com 返回固定元标签,其他 URL 返回 "not found" 错误。这让批量与 404 场景都能在无网络环境下被断言。
十二、下游消费者:CRM 与邮件服务
crates/crm/src/outbound/unfurl_resolver.rs 是理解“为什么 crate 只开 ports”的最佳样本。它实现了 CompanyMetadataResolver,把 https://{domain} 交给 UnfurlService:
| unfurl 字段 | DomainMetadata 字段 |
|---|---|
title |
name |
description |
description |
favicon_url |
icon_url |
关键逻辑是对“URL 兜底标题”的处理:
let title = response.title.trim();
let name = if title.is_empty() || title == url {
None
} else {
Some(title.to_string())
};
因为 get_title 在无可用元标签时会返回 URL 本身,若直接持久化就会把公司名写成 https://example.com——这比留空更糟。同时 trim() 把纯空白标题也折叠成 None。
错误处理同样遵循“不要把瞬时错误缓存成空值”的原则:任何失败(网络、SSRF 拦截、解析、非 HTML)都返回 DomainResolution::Unavailable,让调用方在有限次数内重试,而不是把空元数据永久写入。
services/email_service 走的是另一条路径:它在 services/email_service/src/bin/pubsub_workers/pubsub_workers.rs 中用 USE_APOLLO_CRM_ENRICHMENT 在 Apollo.io 与 unfurl 之间选择,并在 Apollo key 缺失时回落到 unfurl。这说明 unfurl 在本项目中还承担了第三方富化不可用时的降级通道角色——这也是它必须自带 SSRF 防护的原因:域名来自外部邮件,完全由攻击者可控。
十三、扩展与修改时的检查清单
基于 AGENTS.md 的 Gotchas 与源码结构,修改本 crate 时应遵循以下约束:
- 任何新增出站抓取路径都必须复用
http_safety的四个原语:validate_url→assert_not_internal(每跳)→redirect_target→check_content_length+ 流式截断。绕过其中任一环都可能打开 SSRF 或内存耗尽缺口。 - 不要给
ReqwestUnfurlFetcher增加“传入自定义 client”的构造器。文档明确指出客户端构造与类型绑定是刻意的误用防护;如需不同策略,应新增独立适配器并同样内置 resolver 与禁用重定向。 - 重定向处理必须保持“逐跳 preflight”。
send_request不检查状态码是设计而非疏漏,改为自动跟随会立刻破坏防护。 - 新增自定义 URL 解析器时复用
is_valid_provider_host,不要用contains或裸ends_with判断域名,否则会重新引入仿冒域名漏洞(参考test_hostname_validation_rejects_lookalikes)。 - 保持
title非空语义与None序列化省略语义。下游(CRM、邮件、前端卡片)都依赖这两条隐含契约;改字段类型或skip_serializing_if属于破坏性变更。 - 新公开项必须写 doc comment(
#![deny(missing_docs)]),新逻辑必须配单测;安全相关分支至少覆盖 IP 判定矩阵、仿冒域名、重定向超限、体积超限四类。 - 职责不越界:不要在这个 crate 里加缓存、数据库或 UI 渲染。若需要缓存,应在服务层或调用方实现,并为“失败不缓存”留出语义(参考 CRM 的
Unavailable)。
结语
crates/unfurl 的代码量不大,但它把三件事做得相当克制且完整:用六边形架构把领域逻辑与 I/O 隔离(domain / inbound / outbound 加 feature 门控,让 CRM 可以零网络依赖地复用模型与解析器)、用端口抽象让抓取可 mock 可替换(UnfurlFetcher + mockall,服务层 20 行代码就完成装配)、用分层防护把 SSRF 风险压到最低(scheme 白名单、逐跳 preflight、连接期 DNS 过滤、体积与类型上限)。读懂这四个文件——service.rs、http_safety.rs、reqwest_fetcher.rs、axum_router.rs——基本就掌握了 Macro 中所有链接预览行为的全部事实依据。