Holochain Conductor API: Rust分布式应用开发库指南

介绍

Holochain Conductor API是一个用于构建去中心化P2P应用的Rust插件库，它提供了与Holochain Conductor交互的接口。Holochain是一个用于构建完全分布式应用程序的框架，而Conductor是运行Holochain应用程序(DNA)的运行时环境。

这个库允许开发者:

• 以编程方式管理Holochain Conductor实例
• 安装、激活和管理DNA(分布式应用程序)
• 与运行的DNA实例进行交互
• 构建去中心化的P2P应用程序

安装方法

在Cargo.toml中添加依赖:

[dependencies]
holochain_conductor_api = "0.0.17"
tokio = { version = "1.0", features = ["full"] }

基本使用方法

1. 创建Conductor配置

use holochain_conductor_api::conductor::ConductorConfig;

async fn create_conductor_config() -> ConductorConfig {
    ConductorConfig::default()
}

2. 启动Conductor

use holochain_conductor_api::ConductorHandle;

async fn start_conductor(config: ConductorConfig) -> anyhow::Result<ConductorHandle> {
    let conductor = ConductorHandle::new(config).await?;
    Ok(conductor)
}

3. 安装DNA

use holochain_conductor_api::InstallAppDnaPayload;

async fn install_dna(
    conductor: &ConductorHandle,
    dna_path: &str,
    app_id: &str,
) -> anyhow::Result<()> {
    let payload = InstallAppDnaPayload {
        path: dna_path.into(),
        installed_app_id: Some(app_id.into()),
        ..Default::default()
    };
    
    conductor.install_app_dna(payload).await?;
    Ok(())
}

4. 激活DNA实例

use holochain_conductor_api::EnableAppPayload;

async fn activate_app(
    conductor: &ConductorHandle,
    app_id: &str,
) -> anyhow::Result<()> {
    let payload = EnableAppPayload {
        installed_app_id: app_id.into(),
    };
    
    conductor.enable_app(payload).await?;
    Ok(())
}

高级用法示例

调用DNA的Zome函数

use holochain_conductor_api::{
    call_zome::CallZomePayload,
    AppRequest, AppResponse,
};

async fn call_zome_function(
    conductor: &ConductorHandle,
    app_id: &str,
    zome_name: &str,
    fn_name: &str,
    payload: serde_json::Value,
) -> anyhow::Result<AppResponse> {
    let call = CallZomePayload {
        cell_id: None,
        zome_name: zome_name.into(),
        fn_name: fn_name.into(),
        payload,
        provenance: None,
        cap_secret: None,
    };
    
    let request = AppRequest::CallZome(Box::new(call));
    let response = conductor.app_interface(app_id, request).await?;
    
    Ok(response)
}

完整示例: 创建并运行一个简单的Holochain应用

use holochain_conductor_api::{
    conductor::ConductorConfig,
    ConductorHandle,
    InstallAppDnaPayload,
    EnableAppPayload,
    AppRequest, AppResponse,
    call_zome::CallZomePayload,
};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. 创建配置
    let config = ConductorConfig::default();
    
    // 2. 启动Conductor
    let conductor = ConductorHandle::new(config).await?;
    
    // 3. 安装DNA (假设有一个本地DNA文件)
    let dna_path = "./path/to/your/dna.happ";
    let app_id = "my_app";
    
    let install_payload = InstallAppDnaPayload {
        path: dna_path.into(),
        installed_app_id: Some(app_id.into()),
        ..Default::default()
    };
    
    conductor.install_app_dna(install_payload).await?;
    
    // 4. 激活应用
    let enable_payload = EnableAppPayload {
        installed_app_id: app_id.into(),
    };
    
    conductor.enable_app(enable_payload).await?;
    
    // 5. 调用Zome函数
    let call_payload = CallZomePayload {
        cell_id: None,
        zome_name: "some_zome".into(),
        fn_name: "some_function".into(),
        payload: json!({"key": "value"}),
        provenance: None,
        cap_secret: None,
    };
    
    let request = AppRequest::CallZome(Box::new(call_payload));
    let response = conductor.app_interface(app_id, request).await?;
    
    println!("Zome function response: {:?}", response);
    
    Ok(())
}

完整示例demo

下面是一个更完整的示例，展示了如何创建一个简单的社交应用:

use holochain_conductor_api::{
    conductor::ConductorConfig,
    ConductorHandle,
    InstallAppDnaPayload,
    EnableAppPayload,
    AppRequest, AppResponse,
    call_zome::CallZomePayload,
};
use serde_json::json;
use std::path::PathBuf;
use tokio::fs;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. 初始化配置
    let mut config = ConductorConfig::default();
    config.environment_path = Some(PathBuf::from("./holochain_environment"));
    
    // 2. 启动Conductor
    println!("启动Holochain Conductor...");
    let conductor = ConductorHandle::new(config).await?;
    
    // 3. 安装DNA
    println!("安装DNA...");
    let dna_path = "./social_app.happ"; // 假设有这个文件
    let app_id = "social_network";
    
    // 检查DNA文件是否存在
    if !PathBuf::from(dna_path).exists() {
        return Err(anyhow::anyhow!("DNA文件不存在: {}", dna_path));
    }
    
    let install_payload = InstallAppDnaPayload {
        path: dna_path.into(),
        installed_app_id: Some(app_id.into()),
        ..Default::default()
    };
    
    conductor.install_app_dna(install_payload).await?;
    
    // 4. 激活应用
    println!("激活应用...");
    let enable_payload = EnableAppPayload {
        installed_app_id: app_id.into(),
    };
    
    conductor.enable_app(enable_payload).await?;
    
    // 5. 创建用户档案
    println!("创建用户档案...");
    let profile_data = json!({
        "username": "rust_dev",
        "name": "Rust开发者",
        "bio": "专注于去中心化应用开发"
    });
    
    let call_payload = CallZomePayload {
        cell_id: None,
        zome_name: "profiles".into(),
        fn_name: "create_profile".into(),
        payload: profile_data,
        provenance: None,
        cap_secret: None,
    };
    
    let request = AppRequest::CallZome(Box::new(call_payload));
    let response = conductor.app_interface(app_id, request).await?;
    
    println!("创建档案响应: {:?}", response);
    
    // 6. 获取用户档案
    println!("获取用户档案...");
    let get_payload = CallZomePayload {
        cell_id: None,
        zome_name: "profiles".into(),
        fn_name: "get_my_profile".into(),
        payload: json!(null),
        provenance: None,
        cap_secret: None,
    };
    
    let request = AppRequest::CallZome(Box::new(get_payload));
    let response = conductor.app_interface(app_id, request).await?;
    
    println!("我的档案: {:?}", response);
    
    Ok(())
}

注意事项

1. Holochain生态系统仍在快速发展中，API可能会有较大变化
2. 需要先安装Holochain运行时环境
3. 分布式应用开发需要考虑网络拓扑和同步策略
4. 错误处理非常重要，因为P2P环境中的失败是常态而非例外

通过holochain_conductor_api，Rust开发者可以构建完全去中心化的应用程序，这些应用程序不依赖于中心服务器，而是直接在用户设备之间运行和同步数据。