#MoonCrawl 🕷️🥮

moon add guangting0905/mooncrawl@0.1.2

#为什么做这个

• 什么是同一个资源 —— 大小写、默认端口、点段、fragment 折叠； 查询参数顺序不折叠（见下）。
• 什么是礼貌 —— robots.txt 的解析与匹配、Crawl-delay、按 origin 记账的 请求间隔。这些做错不会报错，只会悄悄变成滥用。
• 怎么并发不失控 —— 跨站点并行提速，同站点必须串行。
• 提取规则放哪 —— 写死在代码里换站点就得改代码；做成数据换选择器就行。

#快速开始

moon add guangting0905/mooncrawl@0.1.2

moon test --target js     # 82 个离线测试
moon run cmd/main --target js -- https://books.toscrape.com/ --max-pages 12 --depth 1

#能力范围

#URL 处理（url.mbt）

• 解析绝对 http/https URL：scheme/host 小写化、userinfo 剥离、IPv6 字面量、 端口校验、fragment 丢弃；
• 规范化：折叠 RFC 3986 §6.2.2 意义上的语法等价（大小写、默认端口、点段、 fragment），默认保留查询参数原始顺序；
• 相对地址展开：同目录、根相对、scheme 相对、查询相对，javascript:/mailto: 等外部 scheme 拒绝解析；
• 显式的 normalize_url_sorted_query：仅当调用方确认站点把 query 当无序 多重集时启用参数排序折叠。

#robots.txt（robots.mbt）

• §2.2.1 组选择：大小写不敏感前缀匹配、多组匹配时合并、* 组回退；
• §2.2.2 匹配：从首字节匹配、最长模式优先、等长 Allow 优先、/robots.txt 隐式允许；
• §2.2.3 特殊字符：# 注释、* 通配、$ 锚定；
• §2.2.2 百分号解码：比较前解码 unreserved 字符的 %XX（%7E 与 ~ 视为同一 路径），%2F 等保留字符不解码；
• §2.5 解析上限：1 MiB 截断，截断点之前的规则照常生效；
• §2.3.1 状态码：2xx 执行、4xx 放行、5xx 与网络错误默认完全禁止 （RobotsUnreachable::Disallow，可按需改为 Allow）；
• 扩展：Crawl-delay 解析并在合并组时取最大值，只抬高不降低请求间隔。

#去重与队列（bloom.mbt / frontier.mbt）

• 布隆过滤器：每元素 16 bit、7 哈希、理论误报率约 0.07%；位用 Array[UInt64] 手工打包，十万 URL 约 200 KiB；
• 游标式 FIFO（无大数组 shift 退化）、已见去重、按 host 的间隔推算；
• pop_batch(n)：批量出队且每个 host 最多一个，为并发调度提供同站串行保证。

#异步抓取引擎（crawl.mbt）

• async fn crawl(...)：深度/页数上限、robots 准入、按 origin 礼貌限速；
• 三阶段调度：串行做准入判定 → 并行抓取（跨 origin）→ 串行做提取入队， 共享状态只在串行段修改；
• max_concurrency 控制跨 origin 并行度，同一 origin 始终串行；
• 传输层是可注入闭包（FetchFn），引擎能在无网络、无时钟依赖的离线环境下 对假站点确定性测试；默认实现 http_fetch 基于 moonbitlang/async/http （30 秒超时、User-Agent 透传、错误统一折叠）；
• 统计计数：抓取页数、成功/失败、robots 拒绝、robots 不可达拒绝、 发现链接数、不可达 origin 数。

#提取（extract.mbt / selector.mbt）

• 基础提取：<a href> 按文档顺序收集、<title> 提取、正文文本 （跳过 script/style/noscript 并折叠空白）；
• CSS 选择器子集：类型/类/ID/属性（= ~= ^= $= *= |=）、 后代与子代组合子、逗号并集、:first-child；
• 字段映射：FieldSpec（名称 + 选择器 + 可选取属性）→ extract_fields（整页一条记录）与 extract_records（逐容器成表， 字段选择器不越过容器边界）；
• 明确不支持：伪元素、:not()/:has()、兄弟组合子 +/~、 nth-child 表达式、XPath。遇到无法识别的语法返回空选择器，不猜。

#导出（export.mbt）

• CSV（RFC 4180 转义，CRLF 行尾）与 JSONL（控制字符转义）；
• 通用 json_record / csv_record 接受任意字段对，配合字段提取使用；
• 核心零文件 IO 依赖，输出走 stdout，便于重定向与管道。

#CLI（cmd/main）

# 页面模式：每页一条元数据
moon run cmd/main --target js -- https://books.toscrape.com/ --max-pages 12 --depth 1

# 采集模式：按 CSS 选择器逐条提取记录
moon run cmd/main --target js -- \
  "https://books.toscrape.com/catalogue/category/books/travel_2/index.html" \
  --max-pages 1 --depth 0 \
  --container "article.product_pod" \
  --fields "title=h3 a@title;price=.price_color;link=h3 a@href"

{"title":"It's Only the Himalayas","price":"£45.17","link":"https://books.toscrape.com/catalogue/its-only-the-himalayas_981/index.html"}
{"title":"Vagabonding: An Uncommon Guide to the Art of Long-Term World Travel","price":"£36.94","link":"https://books.toscrape.com/catalogue/vagabonding-an-uncommon-guide-to-the-art-of-long-term-world-travel_552/index.html"}
# pages_fetched=1 ok=1 failed=0 robots_skipped=0 robots_unreachable=0 links=76

{"url":"https://books.toscrape.com/","status":200,"depth":0,"links_found":94,"title":"All products | Books to Scrape - Sandbox"}
{"url":"https://books.toscrape.com/catalogue/category/books/travel_2/index.html","status":200,"depth":1,"links_found":76,"title":"Travel | Books to Scrape - Sandbox"}
# pages_fetched=12 ok=12 failed=0 robots_skipped=0 robots_unreachable=0 links=1089

#库用法

// URL 规范化：折叠语法等价，保留参数顺序
let u = @mooncrawl.parse_url("HTTP://Example.COM:80/a/./b?b=2&a=1#top").unwrap()
println(@mooncrawl.normalize_url(u))              // http://example.com/a/b?b=2&a=1
println(@mooncrawl.normalize_url_sorted_query(u)) // http://example.com/a/b?a=1&b=2

// 相对地址展开
let base = @mooncrawl.parse_url("https://example.com/a/b/index.html").unwrap()
let next = @mooncrawl.resolve_url(base, "page2.html").unwrap()

// 布隆去重
let seen = @mooncrawl.Bloom::new(100_000)
seen.add("https://example.com/page/1")

// robots 判定与 Crawl-delay
let rules = @mooncrawl.parse_robots(robots_txt)
if rules.allowed_url("MoonCrawl/0.1", u) { /* 可以抓 */ }
let delay = rules.crawl_delay_ms("MoonCrawl/0.1")

// CSS 选择器提取
let rows = @mooncrawl.extract_records(html, "article.product_pod", [
  @mooncrawl.FieldSpec::text("title", "h3 a"),
  @mooncrawl.FieldSpec::attr("link", "h3 a", "href"),
  @mooncrawl.FieldSpec::text("price", ".price_color"),
])

// 引擎：传输层可替换（需在 async fn 中调用）
let stats = @mooncrawl.crawl(seed, options, @mooncrawl.http_fetch, on_page)

#架构

Seeds ──▶ Frontier（FIFO + 布隆去重 + pop_batch 按 host 分流）
              │
              ▼
      Politeness（origin 间隔 + Crawl-delay）──▶ robots.txt（RFC 9309）
              │
              ▼
      Fetcher（可注入闭包 / moonbitlang/async/http）
              │  跨 origin 并行，同 origin 串行
              ▼
      Extract（链接 / 标题 / 正文 / CSS 选择器字段）
              │
              ▼
      Export（JSONL / CSV）

while 未达页数上限 {
  batch = frontier.pop_batch(max_concurrency)   // 每个 host 最多一个
  阶段 1（串行）：robots 加载与准入判定
  阶段 2（并行）：@async.all 跨 origin 抓取，各自 polite.gate
  阶段 3（串行）：结果处理、链接提取、入队、统计、回调
}

#已知限制

1. 查询参数顺序不折叠。?a=1&b=2 与 ?b=2&a=1 被视为不同 URL， 同一资源可能被抓两次。这是有意的保守取舍：参数顺序在部分服务端是语义 （签名、重复键、按位置读参）。确认目标站点无序时用 normalize_url_sorted_query。
2. 不处理重定向链。robots.txt 的重定向跟随交给传输层，本模块不解析 重定向链，也不校验 RFC 9309 §2.3.1.2 的「5 次」上限。
3. robots 缓存不持久化。只在单次 crawl 调用内有效，不跨进程。
4. 不做 JS 渲染。只解析服务端返回的 HTML，SPA 站点需要在渲染层另行解决。
5. 不做 XPath。选择器只覆盖 CSS 子集。
6. 单机内存队列。URL 全量驻留内存（布隆过滤器只做去重），不支持分布式调度。
7. 同 origin 串行。跨 origin 才并行；单站点抓取的吞吐受 delay_ms 限制。

#工程实践

• 持续提交：提交历史按模块推进，功能提交标注测试数并关联 Issue。
• 双目标 CI：GitHub Actions 在 js 与 native 后端跑全量测试 + moon fmt 门禁。
• Issue 驱动：立项时建 10 个 Issue 作为看板，随里程碑关闭并附交付说明。
• 接口稳定：moon info 生成 .mbti 接口文件入库，重构可见性有据可查。
• 零告警：moon check 无警告无错误，moon fmt 无 diff。

#查重声明

#路线图

• URL 解析 / 规范化 / 相对展开（D1）
• 布隆去重（D1）
• robots.txt 解析匹配、状态码语义与 Crawl-delay（D2）
• frontier 与礼貌调度（D2）
• 异步抓取引擎（D3）
• HTML 链接/标题/正文提取（D4）
• CSS 选择器与声明式字段提取（D5）
• JSONL/CSV 导出（D5）
• 真实站点演示 + CLI 双模式（D5）
• CI 双目标门禁（D6）
• mooncakes.io 上架（guangting0905/mooncrawl v0.1.2，moon publish 已通过）

• robots 百分号解码与 500 KiB 解析上限
• 重定向链显式处理（5 跳上限）
• Sitemap 发现与优先级队列
• 提取规则持久化（配置文件驱动的采集任务）
• native 单文件二进制发布 + skills.mooncakes.io 技能上架

#开源合规

• NOTICE：第三方组件归属与所引用的规范清单见 NOTICE。 项目为原创实现，未复制或内联任何第三方源码；moonbitlang/async、 moonbit-community/html 均为 Apache-2.0，以 moon.mod 声明的方式作为依赖使用。
• 规范引用：RFC 3986（URL 规范化）、RFC 9309（robots.txt）、 RFC 4180（CSV）为文档而非代码，引用处以 docs/ 与源码注释标注。
• 打包范围：.moonignore 控制发布内容，参赛材料（含联系方式与审核沟通记录） 不随包分发。

#作者