pagesift_api/
engine.rs

1//! 抓取引擎接口。API 层只做协议、校验和任务管理，真正的抓取由实现这个 trait 的引擎完成。
2
3use std::future::Future;
4use std::pin::Pin;
5use std::sync::Arc;
6
7use crate::error::ApiError;
8use crate::types::{
9    CrawlRequest, CrawlSummary, Document, ExtractRequest, MapLink, MapRequest, ScrapeOptions,
10    SearchRequest,
11};
12use serde_json::Value;
13
14pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
15
16pub trait Engine: Send + Sync + 'static {
17    fn scrape<'a>(
18        &'a self,
19        url: &'a str,
20        opts: &'a ScrapeOptions,
21    ) -> BoxFuture<'a, Result<Document, ApiError>>;
22
23    fn map<'a>(&'a self, _req: &'a MapRequest) -> BoxFuture<'a, Result<Vec<MapLink>, ApiError>> {
24        Box::pin(async { Err(ApiError::unsupported("map is not available in this build")) })
25    }
26
27    /// 整站爬取：抓到一页、出错一页、发现新 URL 时都通过 `sink` 回报，直到爬完或被取消。
28    fn crawl<'a>(
29        &'a self,
30        _req: &'a CrawlRequest,
31        _sink: Arc<dyn CrawlSink>,
32    ) -> BoxFuture<'a, Result<(), ApiError>> {
33        Box::pin(async {
34            Err(ApiError::unsupported(
35                "crawl is not available in this build",
36            ))
37        })
38    }
39
40    /// `/v2/search`：返回 Firecrawl 的 `data`（`{ "web": [...] }`）。
41    fn search<'a>(&'a self, _req: &'a SearchRequest) -> BoxFuture<'a, Result<Value, ApiError>> {
42        Box::pin(async {
43            Err(ApiError::unsupported(
44                "search is not configured: set [search] in pagesift.toml",
45            ))
46        })
47    }
48
49    /// `/v2/extract`：返回提取出的 JSON。
50    fn extract<'a>(&'a self, _req: &'a ExtractRequest) -> BoxFuture<'a, Result<Value, ApiError>> {
51        Box::pin(async {
52            Err(ApiError::unsupported(
53                "extract needs an LLM: set [llm] in pagesift.toml",
54            ))
55        })
56    }
57
58    /// 引擎支持的 `formats`；请求了不支持的格式时返回 UNSUPPORTED_OPTION，不悄悄忽略。
59    fn supported_formats(&self) -> &'static [&'static str] {
60        &["markdown", "html", "rawHtml", "links", "images"]
61    }
62
63    /// 是否支持 `actions`（需要浏览器渲染）。
64    fn supports_actions(&self) -> bool {
65        false
66    }
67}
68
69/// 整站爬取的进度回报，由 API 层的任务管理实现。
70pub trait CrawlSink: Send + Sync {
71    fn page(&self, doc: Document) -> BoxFuture<'_, ()>;
72    fn error<'a>(&'a self, url: &'a str, err: ApiError) -> BoxFuture<'a, ()>;
73    /// 已经确定要抓的页面总数（随着发现新链接增长）。
74    fn total(&self, total: usize) -> BoxFuture<'_, ()>;
75    fn cancelled(&self) -> BoxFuture<'_, bool>;
76
77    /// 断点续爬：任务是从中断处恢复的时候返回上次的进度，引擎据此重建队列和去重表，
78    /// 不再抓已经完成的页面。新任务返回 `None`。
79    fn resume(&self) -> Option<CrawlResume> {
80        None
81    }
82
83    /// 是否需要 [`CrawlSink::enqueued`] 回报（持久化的任务需要）。不需要时引擎不必收集。
84    fn tracks_frontier(&self) -> bool {
85        false
86    }
87
88    /// 新进入队列的 URL 和发现深度，按入队顺序。只在 [`CrawlSink::tracks_frontier`] 为真时调用。
89    fn enqueued(&self, _urls: Vec<(String, usize)>) -> BoxFuture<'_, ()> {
90        Box::pin(async {})
91    }
92
93    /// 爬取结束时的说明（停止原因等）；只有带查询的爬取会调用。
94    fn summary(&self, _summary: CrawlSummary) -> BoxFuture<'_, ()> {
95        Box::pin(async {})
96    }
97}
98
99/// 中断的爬取任务恢复时的进度。完成的页面以文档的 `metadata.sourceURL`（失败的以出错的 URL）为准。
100#[derive(Debug, Clone, Default, PartialEq)]
101pub struct CrawlResume {
102    /// 入过队的全部 URL，按入队顺序（去重表）。
103    pub enqueued: Vec<String>,
104    /// 入了队但还没完成的 URL 和发现深度，按入队顺序。中断时正在抓的页面也在这里。
105    pub pending: Vec<(String, usize)>,
106    /// 已经完成的页数（成功和失败都算），计入 `limit`。
107    pub done: usize,
108}
pagesift_api/engine.rs

pagesift_api/
engine.rs
