Struct Connection 

pub struct Connection { /* private fields */ }

A connection to the HyveOS runtime.

This struct provides access to the various services provided by HyveOS.

By default, the connection to the HyveOS runtime will be made through the scripting bridge, i.e., the Unix domain socket specified by the HYVEOS_BRIDGE_SOCKET environment variable (hyveos_core::BRIDGE_SOCKET_ENV_VAR) will be used to communicate with the runtime. If another connection type is desired, use the Self::builder function to get a ConnectionBuilder and use the ConnectionBuilder::custom or ConnectionBuilder::uri methods.

Example

use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut discovery_service = connection.discovery();
let peer_id = discovery_service.get_own_id().await.unwrap();

println!("My peer id: {peer_id}");

Implementations

impl Connection

pub async fn new() -> Result<Self>

Establishes a connection to the HyveOS runtime through the scripting bridge.

The Unix domain socket specified by the HYVEOS_BRIDGE_SOCKET environment variable (hyveos_core::BRIDGE_SOCKET_ENV_VAR) will be used to communicate with the runtime. If another connection type is desired, use the Self::builder function to get a ConnectionBuilder and use the ConnectionBuilder::custom or ConnectionBuilder::uri methods.

Errors

Returns an error if the connection could not be established.

Example

use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut discovery_service = connection.discovery();
let peer_id = discovery_service.get_own_id().await.unwrap();

println!("My peer id: {peer_id}");

pub fn builder() -> ConnectionBuilder<BridgeConnection>

Creates a new builder for configuring a connection to the HyveOS runtime.

By default, the connection to the HyveOS runtime will be made through the scripting bridge, i.e., the Unix domain socket specified by the HYVEOS_BRIDGE_SOCKET environment variable (hyveos_core::BRIDGE_SOCKET_ENV_VAR) will be used to communicate with the runtime. If another connection type is desired, use the ConnectionBuilder::custom or ConnectionBuilder::uri methods.

Example

use hyveos_sdk::Connection;

let connection = Connection::builder()
    .custom("/path/to/hyveos.sock", "/path/to/shared/dir")
    .connect()
    .await
    .unwrap();
let mut discovery_service = connection.discovery();
let peer_id = discovery_service.get_own_id().await.unwrap();

println!("My peer id: {peer_id}");

pub fn db(&self) -> DbService

Returns a handle to the database service.

Example

use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut db_service = connection.db();
assert!(db_service.put("key", b"value").await.unwrap().is_none());

let value = db_service.get("key").await.unwrap().unwrap();
assert_eq!(value, b"value");

pub fn debug(&self) -> DebugService

Returns a handle to the debug service.

Example

use futures::TryStreamExt as _;
use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut debug_service = connection.debug();
let mut events = debug_service.subscribe_mesh_topology().await.unwrap();

while let Some(event) = events.try_next().await.unwrap() {
    println!("{event:?}");
}

pub fn dht(&self) -> DhtService

Returns a handle to the DHT service.

Example

use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut dht_service = connection.dht();
let value = dht_service.get_record("topic", "key").await.unwrap();

if let Some(value) = value.and_then(|value| String::from_utf8(value).ok()) {
    println!("Record has value: {value}");
} else {
   println!("Record not found");
}

pub fn discovery(&self) -> DiscoveryService

Returns a handle to the discovery service.

Example

use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut discovery_service = connection.discovery();
let peer_id = discovery_service.get_own_id().await.unwrap();

println!("My peer id: {peer_id}");

pub fn file_transfer(&self) -> FileTransferService

Returns a handle to the file transfer service.

Example

use std::path::Path;

use hyveos_sdk::Connection;

let shared_dir = std::env::var(hyveos_core::BRIDGE_SHARED_DIR_ENV_VAR).unwrap();
let file_path = Path::new(&shared_dir).join("example.txt");
tokio::fs::write(&file_path, "Hello, world!").await.unwrap();

let connection = Connection::new().await.unwrap();
let mut file_transfer_service = connection.file_transfer();
let cid = file_transfer_service.publish_file(&file_path).await.unwrap();

println!("Content ID: {cid:?}");

pub fn gossipsub(&self) -> GossipSubService

Returns a handle to the gossipsub service.

Example

use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut gossipsub_service = connection.gossipsub();
let id = gossipsub_service.publish("topic", "Hello, world!").await.unwrap();

println!("Published message with id: {id}");

pub fn req_resp(&self) -> ReqRespService

Returns a handle to the request-response service.

Example

use futures::StreamExt as _;
use hyveos_sdk::Connection;

let connection = Connection::new().await.unwrap();
let mut dht_service = connection.dht();
let peer_id = dht_service
    .get_providers("identification", "example")
    .await
    .unwrap()
    .next()
    .await
    .unwrap()
    .unwrap();

let mut req_resp_service = connection.req_resp();
let response = req_resp_service
    .send_request(peer_id, "Hello, world!", None)
    .await
    .unwrap();

let data = Vec::try_from(response).unwrap();
println!("Received response: {}", String::from_utf8(data).unwrap());

pub fn req_resp_json<Req, Resp>(&self) -> JsonReqRespService<Req, Resp>

where Req: Serialize + DeserializeOwned, Resp: Serialize + DeserializeOwned,

Available on crate feature json only.

Returns a handle to the request-response service with JSON-encoded requests and responses.

Example

use futures::StreamExt as _;
use hyveos_sdk::Connection;
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
struct ExampleRequest {
   message: String,
}

#[derive(Debug, Serialize, Deserialize)]
struct ExampleResponse {
   message: String,
}

let connection = Connection::new().await.unwrap();
let mut dht_service = connection.dht();
let peer_id = dht_service
    .get_providers("identification", "example")
    .await
    .unwrap()
    .next()
    .await
    .unwrap()
    .unwrap();

let mut req_resp_service = connection.req_resp_json();
let request = ExampleRequest { message: "Hello, world!".to_string() };
let response = req_resp_service
    .send_request(peer_id, &request, None)
    .await
    .unwrap();

let data: ExampleResponse = Result::from(response).unwrap();
println!("Received response: {data:?}");

pub fn req_resp_cbor<Req, Resp>(&self) -> CborReqRespService<Req, Resp>

where Req: Serialize + DeserializeOwned, Resp: Serialize + DeserializeOwned,

Available on crate feature cbor only.

Returns a handle to the request-response service with JSON-encoded requests and responses.

Example

use futures::StreamExt as _;
use hyveos_sdk::Connection;
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
struct ExampleRequest {
   message: String,
}

#[derive(Debug, Serialize, Deserialize)]
struct ExampleResponse {
   message: String,
}

let connection = Connection::new().await.unwrap();
let mut dht_service = connection.dht();
let peer_id = dht_service
    .get_providers("identification", "example")
    .await
    .unwrap()
    .next()
    .await
    .unwrap()
    .unwrap();

let mut req_resp_service = connection.req_resp_cbor();
let request = ExampleRequest { message: "Hello, world!".to_string() };
let response = req_resp_service
    .send_request(peer_id, &request, None)
    .await
    .unwrap();

let data: ExampleResponse = Result::from(response).unwrap();
println!("Received response: {data:?}");