Macro unfurl crate 深度解析:六边形架构下的链接预览与 SSRF 防护实现

原创2026-10-30 13:47:271,875 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

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.”

拆开来看有三层含义:

  1. 共享基础设施:它不是某个服务私有的工具函数,而是被多个上层消费者复用的库。文档明确标注的消费者是 services/unfurl_service、services/email_service 与 crates/crm(见 crates/unfurl/Cargo.toml 中的依赖方向)。
  2. hex crate(六边形架构):领域逻辑不依赖任何 I/O 框架,HTTP 抓取、HTTP 路由都作为可替换的适配器挂在端口上,见 crates/unfurl/src/lib.rs。
  3. 带 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(axum feature)— 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))
}

三步分别是:

  1. 抓取:委托给 UnfurlFetcher 端口,得到扁平的 HashMap<String, String> 元标签表;
  2. 补全 favicon:页面若未声明图标,用 scheme://host[:port]/favicon.ico 兜底;
  3. 建模:把元标签表装配成结构化的 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 fn in 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:description
  • property="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(&params.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 时应遵循以下约束:

  1. 任何新增出站抓取路径都必须复用 http_safety 的四个原语:validate_url → assert_not_internal(每跳)→ redirect_target → check_content_length + 流式截断。绕过其中任一环都可能打开 SSRF 或内存耗尽缺口。
  2. 不要给 ReqwestUnfurlFetcher 增加“传入自定义 client”的构造器。文档明确指出客户端构造与类型绑定是刻意的误用防护;如需不同策略,应新增独立适配器并同样内置 resolver 与禁用重定向。
  3. 重定向处理必须保持“逐跳 preflight”。send_request 不检查状态码是设计而非疏漏,改为自动跟随会立刻破坏防护。
  4. 新增自定义 URL 解析器时复用 is_valid_provider_host,不要用 contains 或裸 ends_with 判断域名,否则会重新引入仿冒域名漏洞(参考 test_hostname_validation_rejects_lookalikes)。
  5. 保持 title 非空语义与 None 序列化省略语义。下游(CRM、邮件、前端卡片)都依赖这两条隐含契约;改字段类型或 skip_serializing_if 属于破坏性变更。
  6. 新公开项必须写 doc comment(#![deny(missing_docs)]),新逻辑必须配单测;安全相关分支至少覆盖 IP 判定矩阵、仿冒域名、重定向超限、体积超限四类。
  7. 职责不越界:不要在这个 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 中所有链接预览行为的全部事实依据。

登录后查看全文
macro