Skip to content

Engine API zh CN

Jump to bottom
github-actions[bot] edited this page Aug 27, 2026 · 1 revision

Engine API 参考

typebit::Engine<H: Host> 就是你要驱动的全部表面。std feature 自带 StdHost； 其他平台实现 Host （见 实现 Host）。

构造

签名 说明
Engine::new(host, cfg) -> Engine<H> cfg.proxy.is_some() 会硬化引擎（无入站/DHT/UDP/端口映射，端口 0）。
EngineConfig::default() 监听 6881、DHT 开、缓存 256 MiB、512 连接上限、每 IP 8 个、30 s 连接超时。

EngineConfig 字段：listen_port、cache_bytes、dht_enabled、 global_upload_limit_bps、global_download_limit_bps、 global_max_connections、max_connections_per_ip、port_mapping、 verify_workers（0 = std 下自动、no_std 下内联）、proxy、 connect_timeout_ms、session（SessionConfig 单任务默认）。

添加内容

签名 说明
add_torrent(data: &[u8], save_dir: &str) -> Result<InfoHash> 解析并添加 .torrent 字节
add_torrent_obj(torrent: Torrent, save_dir: &str) -> Result<InfoHash> 添加已解析的 Torrent
add_magnet(uri: &str, save_dir: &str) -> Result<InfoHash> 磁力；元数据从 peer 抓取
add_torrents_batch(&[(&[u8], &str)]) -> Vec<Result<InfoHash>> 单个失败不中断整批
add_magnets_batch(&[(&str, &str)]) -> Vec<Result<InfoHash>> 同上，磁力版
restore_torrent(hash, &TorrentState) -> Result<()> 重新加种后回放持久化状态
install_metadata(hash, info_raw: &[u8]) -> Result<()> 持久化预取 info dict（磁力不再重抓）
remove_torrent(hash) -> Result<()> 停止并丢弃会话

生命周期

签名 说明
start(hash) -> Result<()> 开始公告 / 连接
pause(hash) 暂停会话
resume(hash) 恢复
tick() -> Result<()> 驱动一切；用 ~100–500 ms 定时器调用
stop_port_mapping() 尽力移除 NAT 映射

观测

签名 说明
progress(hash) -> f64 0.0 – 1.0，按已选片计算
downloaded(hash) -> u64 / uploaded(hash) -> u64 载荷字节
is_complete(hash) -> bool 所有已选片校验完毕
peer_snapshot(hash) -> Vec<PeerSnapshot> 每 peer 的 phase/速率/标志
metainfo(hash) -> Option<&Torrent> 已知后的解析元信息
stats() -> EngineStats 缓存 + 连接计数器
active_trackers() -> usize 各会话活跃 tracker 数
torrent_count() -> usize 已加载会话数
peer_id() -> &[u8; 20] 我们的 peer id
dht() -> Option<&Dht> DHT 句柄（表统计等）
dht_external() -> Option<([u8; 16], u16)> BEP-42 确认的外部地址
take_events() -> Vec<EngineEvent> 排空事件（见下）
flush_cache() 强制刷盘

控制

签名 说明
add_tracker(hash, url) -> Result<bool> / remove_tracker(hash, url) -> Result<bool> 运行时 tracker 管理
trackers(hash) -> Option<Vec<String>> 当前 tracker 列表
set_file_priority(hash, file, FilePriority) -> Result<()> 单文件
set_file_priorities(hash, &[FilePriority]) -> Result<()> 批量
file_priority(hash, file) -> Option<FilePriority> 当前值
file_priorities(hash) -> Option<Vec<FilePriority>> 全部文件
set_hold_data(hash, hold) -> Result<()> 仅排队模式（不请求任何东西）
holding_data(hash) -> Option<bool> 挂起状态
set_global_limits(down_bps, up_bps) 引擎级令牌桶
set_session_limits(hash, down_bps, up_bps) -> Result<()> 单任务

FilePriority 是 Skip | Normal | High（typebit::session::FilePriority）。

持久化

签名 说明
save_state() -> SessionState 已验证片、部分块、优先级、限速、声誉、DHT 节点
load_state(&SessionState, now: u64) 恢复之前的会话

恢复模式：

let state = engine.save_state();
// 之后，重新添加相同 torrent：
engine.load_state(&state, 0);
for t in &state.torrents {
    if let Some(hash) = /* 你的查询 */ {
        engine.restore_torrent(&hash, t)?;
    }
}

入站连接

宿主把完成的入站 TCP 连接交给引擎：

engine.on_inbound_connection(conn, addr); // conn: Host::tcp_connect 返回的 ConnId

从此 socket 归引擎管。代理模式立即拒绝入站。

EngineEvent

#[non_exhaustive]——匹配时务必带通配分支：

  • PeerConnected { info_hash, addr, peer_id }
  • PieceVerified { info_hash, piece }
  • HashFailure { info_hash, piece }
  • TorrentComplete { info_hash }
  • MetadataComplete { info_hash } / MetadataFailed { info_hash }
  • TrackerAnnounced { info_hash, peers }
  • PeerBanned { info_hash, addr, reason }
  • PortMapping { phase, external_port }
  • DhtNodeCount(usize)
  • Error { code, detail } —— 非致命降级（0 = UDP 打开失败，1 = 无 DHT 路由可解析）

InfoHash

typebit::InfoHash（从 metainfo 再导出）：

  • InfoHash::v1([u8; 20]) / InfoHash::v2([u8; 32])
  • to_hex() -> String / from_hex(&str) -> Result<InfoHash>
  • as_bytes()、len()、is_v1()、is_v2()、full() -> [u8; 32]
  • Ord/Eq/Hash —— 可直接做 map 键

Clone this wiki locally