Crate qrpc_sdk

Source
Expand description

A toolkit for writing clients on the qrpc message bus. This bus is the backbone of the qaul.net service ecosystem. With it you can create applications (called “services”) that interact with a libqaul instance, and other services on the same message broker.

These crate docs describe the API and basic usage. For an overview of the core concepts of this ecosystem, consult the contributors manual.

Additionally, you can access documentation of the internal utilities by passing “--features internals” to your cargo invocation. These components are exposed via the API either way, but only documented on demand to not clutter the main documentation.

§Using this sdk

In order to interact with a running qrpc-broker instance your service needs to register itself and it’s capabilities.

First your service needs a place to save some state, composing different parts of this sdk together to create an app.

You create a Service and RpcSocket and connect to the rpc-broker socket. The first thing you do with this connection is call register(...) on the Service. This establishes the connection, the broker saves your service in it’s address lookup table, and you get assigned a hash-id to identify you in future interactions.

use qrpc_sdk::{Service, RpcSocket, default_socket_path};

let mut serv = Service::new("com.example.myapp", 1, "A simple app");
let (addr, port) = default_socket_path();
let sock = RpcSocket::connect(addr, port).await?;

serv.register(sock).await?;
println!("Service registered! ID: {}", serv.hash_id().unwrap());

Next you need to include the client-lib of the component you want to use, and call connect(...) on your service with the component initialiser.


// serv.connect(libqaul_rpc::Init).await?;

This will establish a connection with the libqaul component and verifies it’s capability set. This mechanism is provided by the ServiceConnector. Your service will also have to implement this mechanism to be usable by other services on the qrpc bus.

After that you can call functions on the public API type of the component. You can get a copy of it via your service handle.


// net.qaul.libqaul is exposed as libqaul_rpc.COMP_ID
// let users = serv.component("net.qaul.libqaul").list_users().await?;
// println!("Available users: {:?}", users);

If you want to see a minimal example of the smallest functional service, see the ping crate.

Modules§

  • builders
    A set of message builder utilities
  • error
    RPC related error handling
  • io
    I/O utility module
  • parser
    An I/O abstraction module for the qrpc system
  • rpc
    qrpc message types
  • types
    qrpc message types

Structs§

  • Identity
    A generic object identifier
  • RpcSocket
    Bi-directional socket connection to a qrpc bus system
  • Service
    A service representation on the qrpc system

Constants§

Traits§

Functions§