Rust网络文档解析库tor-netdoc的使用，高效解析Tor网络协议与目录文档

tor-netdoc概述

tor-netdoc是一个用于解析和表示Tor网络中使用的目录对象的Rust库。Tor网络使用多种"目录对象"来传递关于网络中继节点的信息，这些对象在dir-spec.txt中有详细说明。

该库包含解析和验证这些文档的通用代码。目前它能够处理元格式以及路由器描述符类型的某些部分。未来需要支持更多类型的文档解析。

设计架构

该库主要分为三个部分：

1. parse模块（私有）：包含用于解析不同类型网络文档的通用代码
2. types模块：实现解析目录文档中使用的特定数据结构
3. doc模块：定义文档本身的解析器

功能特性

• build_docs：启用构建表示不同网络文档对象的代码
• routerdesc：支持"路由器描述符"文档类型，桥接客户端和中继节点需要此功能
• ns-consensus：支持"ns共识"文档类型，某些中继节点会缓存并提供此类文档

使用示例

以下是使用tor-netdoc解析Tor网络文档的基本示例：

use tor_netdoc::doc::netstatus::{Consensus, ConsensusBuilder};
use tor_netdoc::types::misc::NetParams;

fn parse_consensus_document(consensus_text: &str) -> Result<(), tor_netdoc::Error> {
    // 解析共识文档
    let consensus = Consensus::parse(consensus_text)?;
    
    // 获取网络参数
    let params: NetParams = consensus.params();
    println!("Network parameters: {:?}", params);
    
    // 遍历路由器状态
    for rs in consensus.rs() {
        println!("Found relay: {}", rs.nickname());
    }
    
    Ok(())
}

fn build_consensus_document() -> Result<(), tor_netdoc::Error> {
    // 构建新的共识文档
    let mut builder = ConsensusBuilder::new();
    
    // 添加网络参数
    builder.set_param("circuitwindow", "1000")?;
    builder.set_param("mincircuitpath", "3")?;
    
    // 添加路由器状态
    builder.add_rs(
        /* nickname */ "TorNode1",
        /* identity */ [0u8; 20],
        /* digest */ [0u8; 32],
        /* publication */ std::time::SystemTime::now(),
        /* ip */ "192.0.2.1".parse().unwrap(),
        /* or_port */ 443,
        /* dir_port */ Some(80),
        /* flags */ vec!["Fast", "Running", "Valid"],
    )?;
    
    // 生成文档
    let consensus = builder.testing_consensus()?;
    println!("Built consensus:\n{}", consensus);
    
    Ok(())
}

当前限制

1. 要求所有输入必须是有效的UTF-8编码（假设Tor主线上已实现提案285）
2. 某些应该公开的部分目前尚未公开
3. 需要更多的测试用例
4. 某些功能可能应该拆分为更小的模块（如版本号处理、退出策略等）

许可证

该库采用MIT或Apache-2.0双许可证。

安装方法

在项目目录中运行以下Cargo命令：

cargo add tor-netdoc

或在Cargo.toml中添加：

tor-netdoc = "0.32.0"

tor-netdoc是Arti项目的一部分，Arti是一个用Rust实现Tor的项目。

完整示例代码

use tor_netdoc::doc::netstatus::{Consensus, ConsensusBuilder, RelayFlags};
use tor_netdoc::types::misc::NetParams;
use std::time::SystemTime;

fn main() -> Result<(), tor_netdoc::Error> {
    // 示例1: 解析共识文档
    let consensus_text = r"
    network-status-version 3
    vote-status consensus
    valid-after 2023-01-01 00:00:00
    fresh-until 2023-01-01 03:00:00
    valid-until 2023-01-01 06:00:00
    voting-delay 300 300
    consensus-method 34
    known-flags Authority Fast Guard Running Valid
    params CircuitWindow=1000,MinCircuitPath=3
    r TorNode1 A1B2C3D4E5F6G7H8I9J0 2023-01-01 00:00:00 192.0.2.1 443 80
    s Fast Running Valid
    r TorNode2 K1L2M3N4O5P6Q7R8S9T0 2023-01-01 00:00:00 192.0.2.2 443 80
    s Fast Running Valid
    ";
    
    parse_consensus_document(consensus_text)?;
    
    // 示例2: 构建共识文档
    build_consensus_document()?;
    
    Ok(())
}

fn parse_consensus_document(consensus_text: &str) -> Result<(), tor_netdoc::Error> {
    // 解析共识文档
    let consensus = Consensus::parse(consensus_text)?;
    
    // 获取网络参数
    let params: NetParams = consensus.params();
    println!("网络参数:");
    for (key, value) in params.iter() {
        println!("  {} = {}", key, value);
    }
    
    // 遍历路由器状态
    println!("\n中继节点列表:");
    for rs in consensus.rs() {
        println!("\n节点昵称: {}", rs.nickname());
        println!("身份标识: {:?}", rs.identity());
        println!("IPv4地址: {}", rs.ipv4_addr());
        println!("OR端口: {}", rs.or_port());
        if let Some(dir_port) = rs.dir_port() {
            println!("目录端口: {}", dir_port);
        }
        
        // 检查节点标志
        let flags = rs.flags();
        println!("节点标志:");
        if flags.contains(RelayFlags::FAST) {
            println!("  - Fast");
        }
        if flags.contains(RelayFlags::RUNNING) {
            println!("  - Running");
        }
        if flags.contains(RelayFlags::VALID) {
            println!("  - Valid");
        }
        if flags.contains(RelayFlags::GUARD) {
            println!("  - Guard");
        }
    }
    
    Ok(())
}

fn build_consensus_document() -> Result<(), tor_netdoc::Error> {
    // 创建共识文档构建器
    let mut builder = ConsensusBuilder::new();
    
    // 设置基本元数据
    builder.set_network_status_version(3);
    builder.set_vote_status("consensus");
    builder.set_valid_after(SystemTime::now());
    builder.set_fresh_until(SystemTime::now() + std::time::Duration::from_secs(10800));
    builder.set_valid_until(SystemTime::now() + std::time::Duration::from_secs(21600));
    
    // 添加已知标志
    builder.add_known_flags(vec![
        "Authority".to_string(),
        "Fast".to_string(),
        "Guard".to_string(),
        "Running".to_string(),
        "Valid".to_string(),
    ]);
    
    // 添加网络参数
    builder.set_param("CircuitWindow", "1000")?;
    builder.set_param("MinCircuitPath", "3")?;
    
    // 添加第一个中继节点
    builder.add_rs(
        "TorNode1",  // 昵称
        [1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0],  // 身份标识
        [0u8; 32],  // 摘要
        SystemTime::now(),  // 发布时间
        "192.0.2.1".parse().unwrap(),  // IP地址
        443,  // OR端口
        Some(80),  // 目录端口
        vec!["Fast", "Running", "Valid"],  // 标志
    )?;
    
    // 添加第二个中继节点
    builder.add_rs(
        "TorNode2",
        [0, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 9, 8, 7, 6, 5, 4, 3, 2, 1],
        [0u8; 32],
        SystemTime::now(),
        "192.0.2.2".parse().unwrap(),
        443,
        Some(80),
        vec!["Fast", "Running", "Valid"],
    )?;
    
    // 生成并打印共识文档
    let consensus = builder.testing_consensus()?;
    println!("\n构建的共识文档:\n{}", consensus);
    
    Ok(())
}

这个完整示例展示了如何:

1. 解析Tor网络共识文档
2. 提取网络参数和中继节点信息
3. 构建一个新的共识文档
4. 添加多个中继节点和网络参数

代码中包含了详细的注释，说明了每个步骤的功能和用法。