🥮 mooncakes.io

    moonair

    MoonAir —— aria2 协议核的 MoonBit 验证实现(下载生命周期状态机 + 分段续传纯核,Bring Your Own Transport)

    Download zip
    Author
    Version
    0.0.4
    License
    Apache-2.0
    Repository
    Last updated
    2 hours ago
    Downloads
    17

    #MoonAir

    MoonAir 是使用 MoonBit 实现的下载协议与传输组件库，覆盖 HTTP(S) 分段下载、断点续传、Metalink、aria2 兼容 JSON-RPC，以及 BitTorrent/DHT 协议子集。

    状态：实验性（0.x）。公开 API、持久化格式与兼容范围可能随版本演进而调整。

    MoonAir 是独立实现，不是 aria2 的官方项目、衍生版本或直接替代品。项目使用 aria2 的公开 RPC 名称与协议行为作为互操作依据，不代表 aria2 项目提供认可或支持。

    #主要能力

    • 下载核心：下载生命周期状态机、段账、多源调度、分片校验与断点续传。
    • 传输执行：HTTP(S) 多连接分段下载、源故障切换、边写边校验、整文件校验和控制文件持久化。
    • Metalink：解析 Metalink v4，并按来源优先级、地域偏好、摘要强度与分片信息生成下载计划。
    • RPC 控制面：提供 JSON-RPC 2.0 接口、任务状态查询、暂停与移除、会话保存与恢复、WebSocket 下载通知。
    • wget 风格命令行：支持续传、指定输出文件、静默模式、输入会话和失败任务导出。
    • BitTorrent：实现 bencode、元信息、Peer Wire、HTTP/UDP Tracker、DHT 基础协议、磁力链接、BEP 9/10 元数据交换与 MSE/PE 入站接待。
    • 可替换边界：存储、摘要和 XML 解析通过端口注入；纯决策层不直接依赖网络、文件系统或异步运行时。

    #环境要求

    • MoonBit 工具链
    • 模块默认目标后端为 native
    • 纯协议包支持 wasm-gc、wasm、js 和 native
    • 异步传输包支持 native 与 wasm
    • aria2 互操作测试需要 aria2c 1.36.0、Python 3 及常见 Unix 命令

    #快速开始

    在仓库根目录执行：

    moon check --deny-warn

    使用 moonair 下载：

    moon run engine/cmd --target native -- \
  https://example.com/file.bin ./file.bin 4 1048576

    参数依次为下载地址、输出路径、并发连接数和段长上限。后两项可省略，默认值分别为 4 和 1048576 字节。

    使用 wget 风格接口：

    moon run style/cmd --target native -- \
  -c -O ./file.bin https://example.com/file.bin

    moonair 也提供相同入口：

    moon run engine/cmd --target native -- \
  --w -c -O ./file.bin https://example.com/file.bin

    可用选项：

    -c                续传
-O file           指定输出路径
-q                静默模式
-i file           从文件读取下载地址
--save-session=f  将失败任务写入重试文件
-h, --help        显示帮助
-V, --version     显示版本

    #RPC 兼容范围

    HTTP JSON-RPC 服务监听 /jsonrpc，支持以下方法：

    • aria2.addUri
    • aria2.addMetalink
    • aria2.tellStatus
    • aria2.pause
    • aria2.remove
    • aria2.saveSession

    /jsonrpc 同时支持 WebSocket 升级，并发送 onDownloadStart、onDownloadComplete 与 onDownloadError 通知。

    服务默认绑定回环地址。绑定非回环地址时必须配置访问令牌；文件操作限制在配置的下载根目录内。RPC 服务作为库使用，通过 rpc/server.ServiceConfig::new 配置并由 rpc/server.serve 启动。

    兼容范围为 aria2 公共接口子集，并非完整实现。当前有意差异包括：

    • 严格要求 JSON-RPC 版本为 2.0
    • 仅接受 Metalink v4，明确拒绝 v3
    • 严格拒绝非规范 bencode 与非法 Torrent 元信息
    • 相同优先级的来源按文档顺序调度，以保证结果可复现

    完整契约与差异清单见 spec.md。

    #包结构

    包职责
    core生命周期状态机、段账、分片账、摘要与存储端口、多源调度
    core/digest_mooncry基于 mooncry 的摘要实现
    protocolRange、Metalink、bencode、Peer Wire、Tracker、DHT 等协议编解码
    protocol/xml_milkyXML 事件适配与 Metalink 文档解析
    sim故障源、存储与控制文件恢复的仿真测试环境
    io文件存储与控制文件持久化
    engine多源多连接下载执行与 Metalink 计划
    rpcJSON-RPC 请求、响应与 aria2 词表
    rpc/serverHTTP/WebSocket 服务、任务管理与会话恢复
    style、style/runwget 风格参数解析、输出与执行装配
    btBitTorrent 客户端、做种端、Tracker、DHT 与元数据交换
    examples本地 HTTP 服务与 wget 风格示例

    #构建与测试

    执行静态检查：

    moon check --deny-warn

    运行不依赖外部程序的常规测试：

    moon test core sim protocol protocol/xml_milky rpc style --target native

    验证纯协议包的跨后端兼容性：

    moon test core sim protocol protocol/xml_milky rpc style --target wasm-gc

    运行 wget 风格端到端示例：

    moon run examples/wget_demo --target native

    BitTorrent 互操作测试包含五个需要外部 aria2 会话的用例。完整验证前应先运行对应驱动：

    sh driver/oracle_k9.sh

    aria2 控制文件续传兼容性由独立驱动验证：

    sh driver/oracle_ac.sh

    成功后分别输出 ORACLE-K9: PASS 与 ORACLE-AC: PASS。

    #当前限制

    • 项目尚处于 0.x 实验阶段，API 稳定性不作保证。
    • 未实现 aria2 CLI、RPC 与 BitTorrent 协议的完整功能集。
    • 不支持 uTP、SFTP 和文件预分配。
    • Metalink 仅支持 v4，尚不验证 PGP 签名。
    • BitTorrent 实现聚焦选定 BEP 与可验证下载链路，不包含完整的 Peer Exchange、Swarm 调优与全部扩展协议。
    • 异步传输面不提供 js 与 wasm-gc 实现。

    #许可证与独立性

    本项目采用 Apache License 2.0。第三方依赖分别遵循其自身许可证；分发或修改时应同时遵守相应条款。

    MoonAir 的实现与发行独立于 aria2。协议名称、RPC 方法名及兼容行为仅用于描述互操作目标，不构成对任何上游项目的归属、授权延伸或官方背书。

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io