zerolaunch_plugin_api/services/icon/
icon_extractor.rs

1use crate::common::image_utils::ImageUtils;
2use crate::host::cache_level::CacheLevel;
3use crate::host::error::HostApiError;
4use crate::services::icon::icon_cache::IconCacheService;
5use crate::services::icon_request::IconRequest;
6use async_trait::async_trait;
7
8/// 图标提取器 trait，定义平台原语与跨平台业务默认实现。
9/// 平台实现者只需实现 6 个原语方法，业务逻辑由默认实现提供。
10/// 默认实现可按需覆盖。
11#[async_trait]
12pub trait IconExtractor: Send + Sync {
13    // ===== 平台原语（各平台必须实现）=====
14
15    /// 从本地文件路径提取图标，返回 PNG 格式字节数据。
16    /// 参数：path - 文件路径（exe, lnk, url, ico, png 等）。
17    /// 返回：PNG 格式图标字节数据，失败返回 HostApiError。
18    async fn extract_from_path(&self, path: &str) -> Result<Vec<u8>, HostApiError>;
19
20    /// 从网址提取图标（favicon），返回 PNG 格式字节数据。
21    /// 参数：url - 网址。
22    /// 返回：PNG 格式图标字节数据，失败返回 HostApiError。
23    async fn extract_from_url(&self, url: &str) -> Result<Vec<u8>, HostApiError>;
24
25    /// 从文件扩展名提取系统关联图标，返回 PNG 格式字节数据。
26    /// 参数：ext - 文件扩展名（如 ".txt", ".doc"）。
27    /// 返回：PNG 格式图标字节数据，失败返回 HostApiError。
28    async fn extract_from_extension(&self, ext: &str) -> Result<Vec<u8>, HostApiError>;
29
30    /// 获取默认应用图标的文件路径。
31    /// 参数：无。
32    /// 返回：默认应用图标路径字符串。
33    fn default_app_icon_path(&self) -> &str;
34
35    /// 获取默认网址图标的文件路径。
36    /// 参数：无。
37    /// 返回：默认网址图标路径字符串。
38    fn default_web_icon_path(&self) -> &str;
39
40    /// 检测当前平台网络是否可用。
41    /// 参数：无。
42    /// 返回：网络可用返回 true。
43    fn is_network_available(&self) -> bool;
44
45    // ===== 跨平台业务逻辑（默认实现）=====
46
47    /// 根据 IconRequest 提取原始图标数据。
48    /// 默认实现根据请求类型分发到对应的平台原语方法。
49    /// 参数：request - 图标请求。
50    /// 返回：PNG 格式图标字节数据，失败返回 HostApiError。
51    async fn extract(&self, request: &IconRequest) -> Result<Vec<u8>, HostApiError> {
52        match request {
53            IconRequest::Path(p) => self.extract_from_path(p).await,
54            IconRequest::Url(u) => self.extract_from_url(u).await,
55            IconRequest::Extension(e) => self.extract_from_extension(e).await,
56            IconRequest::Data(data) => decode_data_url(data),
57        }
58    }
59
60    /// 提取图标并应用后处理：非位图先光栅化 → 裁剪白边 → 等比缩放到 128×128 上限 → WebP 无损编码（VP8L）。
61    /// 参数：request - 图标请求。
62    /// 返回：处理后的 WebP 格式图标字节数据（失败回退位图原始字节，消费方按字节头嗅探），提取失败返回 HostApiError。
63    async fn extract_and_process(&self, request: &IconRequest) -> Result<Vec<u8>, HostApiError> {
64        const MAX_ICON_SIZE: u32 = 128;
65        let data = self.extract(request).await?;
66        // 0. 非位图输入（插件图标常以 SVG 矢量提供）先光栅化为 PNG
67        //    后续裁剪/缩放/编码都是位图链路，矢量字节会在每一步失败并原样透出，
68        //    最终按位图 MIME 编码的 data URL 消费方无法解码（图标显示为破图）。
69        let data = if is_raster_icon(&data) {
70            data
71        } else {
72            ImageUtils::convert_image_to_png(data.clone())
73                .await
74                .unwrap_or(data)
75        };
76        // 1. 裁剪透明/白边（失败回退原数据）
77        let trimmed = ImageUtils::trim_transparent_white_border(data.clone()).unwrap_or(data);
78        // 2. 超过 128×128 时等比缩放到 128（失败回退裁剪产物）
79        let resized = ImageUtils::resize_image(trimmed.clone(), MAX_ICON_SIZE, MAX_ICON_SIZE)
80            .await
81            .unwrap_or(trimmed);
82        // 3. WebP 无损编码（失败回退原始字节，MIME 侧按字节头嗅探兜底）
83        Ok(ImageUtils::to_webp(resized.clone()).unwrap_or(resized))
84    }
85
86    /// 加载默认图标。
87    /// 默认实现：URL 类型加载默认网址图标，其他类型加载默认应用图标。
88    /// 参数：request - 图标请求（用于判断类型）。
89    /// 返回：默认图标的 WebP 字节数据，读取失败返回空 Vec。
90    async fn load_default_icon(&self, request: &IconRequest) -> Vec<u8> {
91        let default_path = match request {
92            IconRequest::Url(_) => self.default_web_icon_path(),
93            _ => self.default_app_icon_path(),
94        };
95        let png = tokio::fs::read(default_path).await.unwrap_or_default();
96        if png.is_empty() {
97            return png;
98        }
99        // 与提取路径一致编码为 WebP，统一返回字节格式
100        ImageUtils::to_webp(png.clone()).unwrap_or(png)
101    }
102
103    /// 完整的图标获取流程，包含缓存策略。
104    /// 默认实现：根据 CacheLevel 执行 L1 → L2 → 提取 → 写回缓存，提取失败返回默认图标。
105    /// 缓存命中还会校验内容为可识别位图，历史版本写入的非位图条目按未命中处理并重新提取。
106    /// 参数：cache - 图标缓存服务；request - 图标请求；level - 缓存等级。
107    /// 返回：WebP 格式图标字节数据（回退路径为原始字节，消费方按字节头嗅探 MIME），失败返回 HostApiError。
108    async fn get_icon(
109        &self,
110        cache: &IconCacheService,
111        request: &IconRequest,
112        level: CacheLevel,
113    ) -> Result<Vec<u8>, HostApiError> {
114        let hash_key = request.get_hash_string() + ".webp";
115
116        // 1. 根据缓存等级查缓存
117        if level != CacheLevel::SkipAll {
118            // L1 查询
119            if level == CacheLevel::Full {
120                if let Some(data) = cache.get_l1(&hash_key) {
121                    if is_raster_icon(&data) {
122                        return Ok(data);
123                    }
124                }
125            }
126
127            // L2 查询
128            if cache.contains_l2(&hash_key) {
129                if let Some(data) = cache.get_l2(&hash_key).await {
130                    if !is_raster_icon(&data) {
131                        // 非位图内容视为未命中，走提取链路覆盖写回
132                        return extract_and_cache(self, cache, request, level, &hash_key).await;
133                    }
134                    // L2 命中时回填 L1
135                    if level == CacheLevel::Full {
136                        cache.set_l1(&hash_key, data.clone());
137                    }
138                    return Ok(data);
139                }
140            }
141        }
142
143        extract_and_cache(self, cache, request, level, &hash_key).await
144    }
145
146    /// 强制从磁盘提取图标并更新缓存（跳过缓存读取）。
147    /// 默认实现：直接提取 → 写回缓存。
148    /// 参数：cache - 图标缓存服务；request - 图标请求；level - 缓存等级。
149    /// 返回：WebP 格式图标字节数据，提取失败返回 HostApiError。
150    async fn get_icon_and_update_cache(
151        &self,
152        cache: &IconCacheService,
153        request: &IconRequest,
154        level: CacheLevel,
155    ) -> Result<Vec<u8>, HostApiError> {
156        let hash_key = request.get_hash_string() + ".webp";
157        let data = self.extract_and_process(request).await?;
158        write_back_cache(cache, &hash_key, &data, level).await;
159        Ok(data)
160    }
161}
162
163/// 根据缓存等级将图标数据写回缓存。
164/// Full: 写入 L1 + L2；SkipMemory: 只写 L2；SkipAll: 不写。
165async fn write_back_cache(
166    cache: &IconCacheService,
167    hash_key: &str,
168    icon_data: &[u8],
169    level: CacheLevel,
170) {
171    if level == CacheLevel::Full {
172        cache.set_l1(hash_key, icon_data.to_vec());
173    }
174
175    if level == CacheLevel::Full || level == CacheLevel::SkipMemory {
176        cache.set_l2(hash_key, icon_data.to_vec()).await;
177    }
178}
179
180/// 提取并后处理图标，成功后按缓存等级写回；失败或结果为空时回退默认图标。
181/// 参数：extractor - 图标提取器；cache - 图标缓存服务；request - 图标请求；level - 缓存等级；hash_key - 缓存键。
182/// 返回：图标字节数据（WebP，回退路径为位图原始字节）。
183async fn extract_and_cache<E: IconExtractor + ?Sized>(
184    extractor: &E,
185    cache: &IconCacheService,
186    request: &IconRequest,
187    level: CacheLevel,
188    hash_key: &str,
189) -> Result<Vec<u8>, HostApiError> {
190    let data = match extractor.extract_and_process(request).await {
191        Ok(d) if !d.is_empty() => d,
192        _ => return Ok(extractor.load_default_icon(request).await),
193    };
194
195    write_back_cache(cache, hash_key, &data, level).await;
196
197    Ok(data)
198}
199
200/// 判断图标字节是否为可识别位图（image crate 的字节头嗅探）。
201/// 缓存键固定以 .webp 结尾，但历史版本可能写入未光栅化的 SVG 等非位图字节，
202/// 命中此类条目必须按未命中处理并重新提取。
203/// 参数：data - 图标字节数据。
204/// 返回：true 表示是可识别位图。
205fn is_raster_icon(data: &[u8]) -> bool {
206    image::guess_format(data).is_ok()
207}
208
209/// 解码 data URL 或纯 base64 为原始字节（IconRequest::Data 直通路径）。
210/// 参数：data - "data:<mime>;base64,<payload>" 形式或纯 base64 字符串。
211/// 返回：解码后的字节；格式不合法返回 HostApiError。
212fn decode_data_url(data: &str) -> Result<Vec<u8>, HostApiError> {
213    let payload = data.rsplit_once(";base64,").map(|(_, p)| p).unwrap_or(data);
214    base64::Engine::decode(&base64::engine::general_purpose::STANDARD, payload).map_err(|e| {
215        HostApiError::IconExtractionFailed {
216            request: "data".to_string(),
217            reason: format!("data URL 解码失败: {}", e),
218        }
219    })
220}
221
222#[cfg(test)]
223mod tests {
224    use super::*;
225
226    /// 最小可渲染 SVG（第三方插件图标常见形态）。
227    const SVG_SOURCE: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"><rect width="64" height="64" fill="#2f7fd8"/></svg>"##;
228
229    /// 以 data URL 形式提供 SVG，与插件候选图标下发形态一致。
230    fn svg_data_url() -> String {
231        use base64::Engine;
232        format!(
233            "data:image/svg+xml;base64,{}",
234            base64::engine::general_purpose::STANDARD.encode(SVG_SOURCE)
235        )
236    }
237
238    /// 最小提取器：平台原语不可用，图标只经 IconRequest::Data 直通。
239    struct StubExtractor;
240
241    #[async_trait]
242    impl IconExtractor for StubExtractor {
243        async fn extract_from_path(&self, _path: &str) -> Result<Vec<u8>, HostApiError> {
244            Err(HostApiError::IconExtractionFailed {
245                request: "path".to_string(),
246                reason: "stub".to_string(),
247            })
248        }
249
250        async fn extract_from_url(&self, _url: &str) -> Result<Vec<u8>, HostApiError> {
251            Err(HostApiError::IconExtractionFailed {
252                request: "url".to_string(),
253                reason: "stub".to_string(),
254            })
255        }
256
257        async fn extract_from_extension(&self, _ext: &str) -> Result<Vec<u8>, HostApiError> {
258            Err(HostApiError::IconExtractionFailed {
259                request: "extension".to_string(),
260                reason: "stub".to_string(),
261            })
262        }
263
264        fn default_app_icon_path(&self) -> &str {
265            ""
266        }
267
268        fn default_web_icon_path(&self) -> &str {
269            ""
270        }
271
272        fn is_network_available(&self) -> bool {
273            false
274        }
275    }
276
277    /// SVG 图标必须光栅化为位图，否则 data URL 只能按位图 MIME 标注 → 消费方解码失败（破图）。
278    #[tokio::test]
279    async fn svg_icon_is_rasterized_to_bitmap() {
280        let processed = StubExtractor
281            .extract_and_process(&IconRequest::Data(svg_data_url()))
282            .await
283            .expect("SVG 图标应能完成提取与后处理");
284
285        let format = image::guess_format(&processed).expect("处理结果必须是可识别位图");
286        assert!(
287            matches!(format, image::ImageFormat::WebP | image::ImageFormat::Png),
288            "SVG 应被光栅化，实际格式: {format:?}"
289        );
290    }
291
292    /// 历史版本可能把非位图字节写进 .webp 缓存条目，命中后必须重新提取而非直接返回。
293    #[tokio::test]
294    async fn non_raster_cache_entry_is_re_extracted() {
295        let dir = tempfile::tempdir().expect("创建临时缓存目录");
296        let cache = IconCacheService::new(dir.path().to_string_lossy().into_owned());
297        cache.init();
298
299        let request = IconRequest::Data(svg_data_url());
300        cache
301            .set_l2(
302                &(request.get_hash_string() + ".webp"),
303                SVG_SOURCE.as_bytes().to_vec(),
304            )
305            .await;
306
307        let data = StubExtractor
308            .get_icon(&cache, &request, CacheLevel::Full)
309            .await
310            .expect("应忽略陈旧条目并重新提取");
311
312        assert!(
313            image::guess_format(&data).is_ok(),
314            "返回内容必须是可识别位图，而不是缓存中的 SVG 文本"
315        );
316    }
317}
zerolaunch_plugin_api/services/icon/icon_extractor.rs

zerolaunch_plugin_api/services/icon/
icon_extractor.rs
