Rust的Holochain CLI沙盒库holochain_cli_sandbox使用指南

介绍

holochain_cli_sandbox是一个用于Holochain开发的Rust库，它提供了一个命令行界面(CLI)沙盒环境，用于简化分布式应用的开发和测试流程。Holochain是一个用于构建去中心化应用的框架，而这个沙盒库让开发者能够快速设置本地测试环境，无需配置完整的Holochain网络。

主要特性

• 快速启动本地Holochain测试环境
• 简化的API用于测试Holochain应用(称为"hApps")
• 支持多个并发代理(agent)模拟
• 内置网络仿真功能
• 与现有Holochain工具链无缝集成

安装方法

首先，确保你已经安装了Rust和Cargo。然后添加以下依赖到你的Cargo.toml文件中：

[dependencies]
holochain_cli_sandbox = "0.1.0"  # 请检查最新版本
tokio = { version = "1.0", features = ["full"] }  # 需要异步运行时

基本使用方法

1. 创建沙盒环境

use holochain_cli_sandbox as sandbox;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 创建默认配置的沙盒
    let sandbox = sandbox::Sandbox::new().await?;
    
    // 或者使用自定义配置
    let config = sandbox::SandboxConfig {
        network: Some(sandbox::NetworkConfig::default()),
        ..Default::default()
    };
    let sandbox = sandbox::Sandbox::with_config(config).await?;
    
    Ok(())
}

2. 安装和运行hApp

let dna_path = "/path/to/your/happ.dna";
let installed_app = sandbox.install_app("my_app", &dna_path).await?;
sandbox.start_apps().await?;

3. 创建代理(Agent)和调用Zome函数

// 创建新代理
let agent = sandbox.create_agent("alice").await?;

// 调用zome函数
let result: serde_json::Value = sandbox
    .call_zome(
        &agent,
        "my_app",
        "my_zome",
        "my_function",
        serde_json::json!({"arg": "value"}),
    )
    .await?;

println!("Zome call result: {:?}", result);

4. 模拟多个代理交互

let alice = sandbox.create_agent("alice").await?;
let bob = sandbox.create_agent("bob").await?;

// Alice创建一条记录
let create_result: serde_json::Value = sandbox
    .call_zome(
        &alice,
        "my_app",
        "posts",
        "create_post",
        serde_json::json!({"content": "Hello from Alice"}),
    )
    .await?;

// Bob获取这条记录
let get_result: serde_json::Value = sandbox
    .call_zome(
        &bob,
        "my_app",
        "posts",
        "get_post",
        serde_json::json!({"hash": create_result["hash"]}),
    )
    .await?;

println!("Bob retrieved: {:?}", get_result);

高级功能

网络仿真

let config = sandbox::SandboxConfig {
    network: Some(sandbox::NetworkConfig {
        latency: std::time::Duration::from_millis(100),
        bandwidth: 1024, // KB/s
        ..Default::default()
    }),
    ..Default::default()
};
let sandbox = sandbox::Sandbox::with_config(config).await?;

测试并发场景

use futures::future::join_all;

let agents = vec![
    sandbox.create_agent("agent1").await?,
    sandbox.create_agent("agent2").await?,
    sandbox.create_agent("agent3").await?,
];

let calls = agents.iter().map(|agent| {
    sandbox.call_zome(
        agent,
        "my_app",
        "my_zome",
        "concurrent_function",
        serde_json::json!({"id": agent.id()}),
    )
});

let results = join_all(calls).await;

清理资源

// 关闭沙盒环境
sandbox.shutdown().await?;

实际应用示例

以下是一个完整的测试示例，模拟一个简单的博客应用：

use holochain_cli_sandbox as sandbox;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. 初始化沙盒
    let sandbox = sandbox::Sandbox::new().await?;
    
    // 2. 安装博客应用
    let installed_app = sandbox
        .install_app("blog_app", "./path/to/blog_app.dna")
        .await?;
    sandbox.start_apps().await?;
    
    // 3. 创建两个用户
    let alice = sandbox.create_agent("alice").await?;
    let bob = sandbox.create_agent("bob").await?;
    
    // 4. Alice创建一篇博客
    let post_content = "My first blog post about Rust and Holochain!";
    let create_result: serde_json::Value = sandbox
        .call_zome(
            &alice,
            "blog_app",
            "blog",
            "create_post",
            serde_json::json!({"content": post_content}),
        )
        .await?;
    
    let post_hash = &create_result["hash"];
    println!("Alice created post with hash: {}", post_hash);
    
    // 极客时间
    // 5. Bob获取并评论这篇博客
    let comment_content = "Great post about Holochain!";
    let _comment_result = sandbox
        .call_zome(
            &bob,
            "blog_app",
            "blog",
            "create_comment",
            serde_json::json!({
                "post_hash": post_hash,
                "content": comment_content
            }),
        )
        .await?;
    
    // 6. 验证博客和评论
    let get_result: serde_json::Value = sandbox
        .call_zome(
            &alice,
            "blog_app",
            "blog",
           极客时间
            "get_post_with_comments",
            serde_json::json!({"post_hash": post_hash}),
        )
        .await?;
    
    println!("Full post with comments: {:#?}", get_result);
    
    // 7. 清理
    sandbox.shutdown().await?;
    
    Ok(())
}

完整示例demo

下面是一个完整的社交网络应用测试示例，展示如何使用holochain_cli_sandbox测试用户之间的社交互动：

use holochain_cli_sandbox as sandbox;
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. 初始化沙盒环境
    let config = sandbox::SandboxConfig {
        network: Some(sandbox::NetworkConfig {
            latency: std::time::Duration::from_millis(50),
            bandwidth: 2048,
            ..Default::default()
        }),
        ..Default::default()
    };
    
    let sandbox = sandbox::Sandbox::with_config(config).await?;
    
    // 2. 安装社交应用
    let installed_app = sandbox
        .install_app("social_app", "./path/to/social_app.dna")
        .await?;
    sandbox.start_apps().await?;
    
    // 3. 创建三个用户
    let alice = sandbox.create_agent("alice").await?;
    let bob = sandbox.create_agent("bob").await?;
    let charlie = sandbox.create_agent("charlie").await?;
    
    // 4. Alice发布帖子
    let post_content = "Check out my new Holochain project!";
    let post_result: serde_json::Value = sandbox
        .call_zome(
            &alice,
            "social_app",
            "posts",
            "create_post",
            json!({"content": post_content}),
        )
        .await?;
    
    let post_hash = &post_result["hash"];
    println!("Alice created post with hash: {}", post_hash);
    
    // 5. Bob和Charlie关注Alice
    let _follow_result1 = sandbox
        .call_zome(
            &bob,
            "social_app",
            "profiles",
            "follow",
            json!({"agent": alice.id()}),
        )
        .await?;
    
    let _follow_result2 = sandbox
        .call_zome(
            &charlie,
            "social_app",
            "profiles",
            "follow",
            json!({"agent": alice.id()}),
        )
        .await?;
    
    // 6. Bob评论Alice的帖子
    let comment_result: serde_json::Value = sandbox
        .call_zome(
            &bob,
            "social_app",
            "posts",
            "create_comment",
            json!({
                "post_hash": post_hash,
                "content": "Looking great Alice!"
            }),
        )
        .await?;
    
    let comment_hash = &comment_result["hash"];
    
    // 7. Charlie点赞评论
    let _like_result = sandbox
        .call_zome(
            &charlie,
            "social_app",
            "posts",
            "like_comment",
            json!({"comment_hash": comment_hash}),
        )
        .await?;
    
    // 8. 验证社交互动
    let interactions: serde_json::Value = sandbox
        .call_zome(
            &alice,
            "social_app",
            "posts",
            "get_post_interactions",
            json!({"post_hash": post_hash}),
        )
        .await?;
    
    println!("Post interactions: {:#?}", interactions);
    
    // 9. 清理资源
    sandbox.shutdown().await?;
    
    Ok(())
}

总结

holochain_cli_sandbox为Holochain应用开发提供了强大的测试工具，使得开发者能够：

• 快速搭建本地测试环境
• 模拟多个用户交互
• 测试分布式应用逻辑
• 验证数据一致性
• 模拟网络条件

通过这个库，你可以更高效地开发和测试你的Holochain应用，而无需担心复杂的网络配置和基础设施设置。